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

annotate xml/en/docs/dev/development_guide.xml @ 2009:9b7302e3b21f

DevGuide: fixed variables example.

author	Vladimir Homutov <vl@nginx.com>
date	Wed, 05 Jul 2017 15:30:48 +0300
parents	1f2f9fa97065
children	ec34516cbd1b

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>
1999 1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	378 <literal>ngx_tolower()</literal>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	379 </listitem>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	380
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	381 <listitem>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	382 <literal>ngx_toupper()</literal>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	383 </listitem>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	384
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	385 <listitem>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	386 <literal>ngx_strlow()</literal>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	387 </listitem>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	388
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	389 <listitem>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	390 <literal>ngx_strcasecmp()</literal>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	391 </listitem>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	392
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	393 <listitem>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	394 <literal>ngx_strncasecmp()</literal>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	395 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	396
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	397 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	398 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	399
1998 18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	400 <para>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	401 The following macros simplify string initialization:
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	402 </para>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	403
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	404 <list type="bullet">
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	405
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	406 <listitem>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	407 <literal>ngx_string(text)</literal> — static initializer for the
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	408 <literal>ngx_str_t</literal> type from the C string literal
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	409 <literal>text</literal>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	410 </listitem>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	411
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	412 <listitem>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	413 <literal>ngx_null_string</literal> — static empty string initializer for the
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	414 <literal>ngx_str_t</literal> type
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	415 </listitem>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	416
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	417 <listitem>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	418 <literal>ngx_str_set(str, text)</literal> — initializes string
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	419 <literal>str</literal> of <literal>ngx_str_t *</literal> type with the C string
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	420 literal <literal>text</literal>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	421 </listitem>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	422
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	423 <listitem>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	424 <literal>ngx_str_null(str)</literal> — initializes string <literal>str</literal>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	425 of <literal>ngx_str_t *</literal> type with the empty string
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	426 </listitem>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	427
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	428 </list>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	429
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	430 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	431
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	432
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	433 <section name="Formatting" id="formatting">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	434
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	435 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	436 The following formatting functions support nginx-specific types:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	437 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	438
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	439
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	440 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	441 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	442
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	443 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	444 <literal>ngx_sprintf(buf, fmt, ...)</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	445 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	446
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	447 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	448 <literal>ngx_snprintf(buf, max, fmt, ...)</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	449 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	450
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	451 <listitem>
1975 459a6f194fcf Fixed a typo. Vladimir Homutov <vl@nginx.com> parents: 1971 diff changeset	452 <literal>ngx_slprintf(buf, last, fmt, ...)</literal>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	453 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	454
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	455 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	456 <literal>ngx_vslprint(buf, last, fmt, args)</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	457 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	458
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	459 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	460 <literal>ngx_vsnprint(buf, max, fmt, args)</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	461 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	462
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	463 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	464 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	465
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	466 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	467 The full list of formatting options, supported by these functions is
1915 8b7c3b0ef1a4 Semantically marked paths. Vladimir Homutov <vl@nginx.com> parents: 1914 diff changeset	468 in <path>src/core/ngx_string.c</path>. Some of them are:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	469 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	470
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	471
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	472 <list type="bullet">
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	473
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	474 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	475 <literal>%O</literal> — <literal>off_t</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	476 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	477
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	478 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	479 <literal>%T</literal> — <literal>time_t</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	480 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	481
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	482 <listitem>
1997 eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	483 <literal>%z</literal> — <literal>ssize_t</literal>
eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	484 </listitem>
eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	485
eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	486 <listitem>
eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	487 <literal>%i</literal> — <literal>ngx_int_t</literal>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	488 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	489
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	490 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	491 <literal>%p</literal> — <literal>void *</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	492 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	493
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	494 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	495 <literal>%V</literal> — <literal>ngx_str_t *</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	496 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	497
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	498 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	499 <literal>%s</literal> — <literal>u_char *</literal> (null-terminated)
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	500 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	501
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	502 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	503 <literal>%s</literal> — <literal>size_t + u_char </literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	504 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	505
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	506 </list>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	507
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	508
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	509 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	510 You can prepend <literal>u</literal> on most types to make them unsigned.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	511 To convert output to hex, use <literal>X</literal> or <literal>x</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	512 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	513
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	514 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	515 For example:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	516
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	517 <programlisting>
1997 eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	518 u_char buf[NGX_INT_T_LEN];
eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	519 size_t len;
eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	520 ngx_uint_t n;
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	521
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	522 /* set n here */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	523
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	524 len = ngx_sprintf(buf, "%ui", n) — buf;
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	525 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	526
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	527 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	528
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	529 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	530
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	531
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	532 <section name="Numeric conversion" id="numeric_conversion">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	533
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	534 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	535 Several functions for numeric conversion are implemented in nginx.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	536 The first four each convert a string of given length to a positive integer of
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	537 the indicated type.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	538 They return <literal>NGX_ERROR</literal> on error.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	539
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	540 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	541
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	542 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	543 <literal>ngx_atoi(line, n)</literal> — <literal>ngx_int_t</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	544 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	545
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	546 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	547 <literal>ngx_atosz(line, n)</literal> — <literal>ssize_t</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	548 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	549
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	550 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	551 <literal>ngx_atoof(line, n)</literal> — <literal>off_t</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	552 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	553
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	554 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	555 <literal>ngx_atotm(line, n)</literal> — <literal>time_t</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	556 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	557
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	558 </list>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	559 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	560
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	561 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	562 There are two additional numeric conversion functions.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	563 Like the first four, they return <literal>NGX_ERROR</literal> on error.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	564
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	565 <list type="bullet">
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	566
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	567 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	568 <literal>ngx_atofp(line, n, point)</literal> — Converts a fixed point floating
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	569 number of given length to a positive integer of type
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	570 <literal>ngx_int_t</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	571 The result is shifted left by <literal>point</literal> decimal
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	572 positions.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	573 The string representation of the number is expected to have no more
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	574 than <literal>points</literal> fractional digits.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	575 For example, <literal>ngx_atofp("10.5", 4, 2)</literal> returns
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	576 <literal>1050</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	577 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	578
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	579 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	580 <literal>ngx_hextoi(line, n)</literal> — Converts a hexadecimal representation
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	581 of a positive integer to <literal>ngx_int_t</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	582 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	583
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	584 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	585 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	586
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	587 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	588
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	589 <section name="Regular expressions" id="regex">
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	590
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	591 <para>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	592 The regular expressions interface in nginx is a wrapper around
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	593 the <link url="http://www.pcre.org">PCRE</link>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	594 library.
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	595 The corresponding header file is <path>src/core/ngx_regex.h</path>.
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	596 </para>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	597
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	598 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	599 To use a regular expression for string matching, it first needs to be
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	600 compiled, which is usually done at the configuration phase.
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	601 Note that since PCRE support is optional, all code using the interface must
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	602 be protected by the surrounding <literal>NGX_PCRE</literal> macro:
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	603
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	604 <programlisting>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	605 #if (NGX_PCRE)
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	606 ngx_regex_t *re;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	607 ngx_regex_compile_t rc;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	608
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	609 u_char errstr[NGX_MAX_CONF_ERRSTR];
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	610
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	611 ngx_str_t value = ngx_string("message (\\d\\d\\d).*Codeword is '(?<cw>\\w+)'");
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	612
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	613 ngx_memzero(&rc, sizeof(ngx_regex_compile_t));
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	614
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	615 rc.pattern = value;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	616 rc.pool = cf->pool;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	617 rc.err.len = NGX_MAX_CONF_ERRSTR;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	618 rc.err.data = errstr;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	619 /* rc.options are passed as is to pcre_compile() */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	620
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	621 if (ngx_regex_compile(&rc) != NGX_OK) {
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	622 ngx_conf_log_error(NGX_LOG_EMERG, cf, 0, "%V", &rc.err);
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	623 return NGX_CONF_ERROR;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	624 }
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	625
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	626 re = rc.regex;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	627 #endif
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	628 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	629 After successful compilation, the <literal>captures</literal> and
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	630 <literal>named_captures</literal> fields in the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	631 <literal>ngx_regex_compile_t</literal> structure contain the count of all
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	632 captures and named captures, respectively, found in the regular expression.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	633 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	634
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	635 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	636 The compiled regular expression can then be used for matching against strings:
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	637 <programlisting>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	638 ngx_int_t n;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	639 int captures[(1 + rc.captures) * 3];
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	640
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	641 ngx_str_t input = ngx_string("This is message 123. Codeword is 'foobar'.");
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	642
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	643 n = ngx_regex_exec(re, &input, captures, (1 + rc.captures) * 3);
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	644 if (n >= 0) {
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	645 /* string matches expression */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	646
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	647 } else if (n == NGX_REGEX_NO_MATCHED) {
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	648 /* no match was found */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	649
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	650 } else {
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	651 /* some error */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	652 ngx_log_error(NGX_LOG_ALERT, log, 0, ngx_regex_exec_n " failed: %i", n);
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	653 }
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	654 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	655 The arguments to <literal>ngx_regex_exec()</literal> are the compiled regular
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	656 expression <literal>re</literal>, the string to match <literal>s</literal>,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	657 an optional array of integers to hold any <literal>captures</literal> that are
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	658 found, and the array's <literal>size</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	659 The size of the <literal>captures</literal> array must be a multiple of three,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	660 as required by the
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	661 <link url="http://www.pcre.org/original/doc/html/pcreapi.html">PCRE API</link>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	662 In the example, the size is calculated from the total number of captures plus
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	663 <literal>1</literal>one for the matched string itself.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	664 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	665
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	666 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	667 If there are matches, captures can be accessed as follows:
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	668 <programlisting>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	669 u_char *p;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	670 size_t size;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	671 ngx_str_t name, value;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	672
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	673 /* all captures */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	674 for (i = 0; i < n * 2; i += 2) {
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	675 value.data = input.data + captures[i];
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	676 value.len = captures[i + 1] — captures[i];
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	677 }
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	678
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	679 /* accessing named captures */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	680
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	681 size = rc.name_size;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	682 p = rc.names;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	683
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	684 for (i = 0; i < rc.named_captures; i++, p += size) {
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	685
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	686 /* capture name */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	687 name.data = &p[2];
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	688 name.len = ngx_strlen(name.data);
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	689
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	690 n = 2 * ((p[0] << 8) + p[1]);
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	691
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	692 /* captured value */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	693 value.data = &input.data[captures[n]];
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	694 value.len = captures[n + 1] — captures[n];
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	695 }
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	696 </programlisting>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	697 </para>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	698
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	699 <para>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	700 The <literal>ngx_regex_exec_array()</literal> function accepts the array of
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	701 <literal>ngx_regex_elt_t</literal> elements (which are just compiled regular
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	702 expressions with associated names), a string to match, and a log.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	703 The function applies expressions from the array to the string until
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	704 either a match is found or no more expressions are left.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	705 The return value is <literal>NGX_OK</literal> when there is a match and
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	706 <literal>NGX_DECLINED</literal> otherwise, or <literal>NGX_ERROR</literal>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	707 in case of error.
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	708 </para>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	709
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	710 </section>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	711
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	712 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	713
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	714
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	715 <section name="Time" id="time">
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	716
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	717 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	718 The <literal>ngx_time_t</literal> structure represents time with three separate
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	719 types for seconds, milliseconds, and the GMT offset:
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	720 <programlisting>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	721 typedef struct {
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	722 time_t sec;
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	723 ngx_uint_t msec;
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	724 ngx_int_t gmtoff;
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	725 } ngx_time_t;
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	726 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	727 The <literal>ngx_tm_t</literal> structure is an alias for
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	728 <literal>struct tm</literal> on UNIX platforms and <literal>SYSTEMTIME</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	729 on Windows.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	730 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	731
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	732 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	733 To obtain the current time, it is usually sufficient to access one of the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	734 available global variables, representing the cached time value in the desired
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	735 format.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	736 For example, the <literal>ngx_current_msec</literal> variable holds the number
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	737 of milliseconds elapsed since Epoch and truncated to
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	738 <literal>ngx_msec_t</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	739 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	740
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	741 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	742 The available string representations are:
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	743
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	744 <list type="bullet">
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	745
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	746 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	747 <literal>ngx_cached_err_log_time</literal> — Used in error log entries:
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	748 <literal>"1970/09/28 12:00:00"</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	749 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	750
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	751 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	752 <literal>ngx_cached_http_log_time</literal> — Used in HTTP access log entries:
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	753 <literal>"28/Sep/1970:12:00:00 +0600"</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	754 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	755
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	756 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	757 <literal>ngx_cached_syslog_time</literal> — Used in syslog entries:
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	758 <literal>"Sep 28 12:00:00"</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	759 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	760
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	761 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	762 <literal>ngx_cached_http_time</literal> — Used in HTTP headers:
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	763 <literal>"Mon, 28 Sep 1970 06:00:00 GMT"</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	764 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	765
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	766 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	767 <literal>ngx_cached_http_log_iso8601</literal> — The ISO 8601
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	768 standard format:
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	769 <literal>"1970-09-28T12:00:00+06:00"</literal>
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	770 </listitem>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	771
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	772 </list>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	773 </para>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	774
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	775 <para>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	776 The <literal>ngx_time()</literal> and <literal>ngx_timeofday()</literal> macros
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	777 return the current time value in seconds and are the preferred way to access
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	778 the cached time value.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	779 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	780
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	781 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	782 To obtain the time explicitly, use <literal>ngx_gettimeofday()</literal>,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	783 which updates its argument (pointer to
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	784 <literal>struct timeval</literal>).
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	785 The time is always updated when nginx returns to the event loop from system
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	786 calls.
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	787 To update the time immediately, call <literal>ngx_time_update()</literal>,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	788 or <literal>ngx_time_sigsafe_update()</literal> if updating the time in the
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	789 signal handler context.
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	790 </para>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	791
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	792 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	793 The following functions convert <literal>time_t</literal> into the indicated
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	794 broken-down time representation.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	795 The first function in each pair converts <literal>time_t</literal> to
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	796 <literal>ngx_tm_t</literal> and the second (with the <literal>_libc_</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	797 infix) to <literal>struct tm</literal>:
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	798
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	799 <list type="bullet">
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	800
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	801 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	802 <literal>ngx_gmtime(), ngx_libc_gmtime()</literal> — Time expressed as UTC
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	803 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	804
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	805 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	806 <literal>ngx_localtime(), ngx_libc_localtime()</literal> — Time expressed
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	807 relative to the local time zone
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	808 </listitem>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	809
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	810 </list>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	811
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	812 The <literal>ngx_http_time(buf, time)</literal> function returns a string
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	813 representation suitable for use in HTTP headers (for example,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	814 <literal>"Mon, 28 Sep 1970 06:00:00 GMT"</literal>).
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	815 The <literal>ngx_http_cookie_time(buf, time)</literal> returns a string
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	816 representation function returns a string representation suitable
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	817 for HTTP cookies (<literal>"Thu, 31-Dec-37 23:55:55 GMT"</literal>).
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	818 </para>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	819
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	820 </section>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	821
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	822
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	823 <section name="Containers" id="containers">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	824
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	825
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	826 <section name="Array" id="array">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	827
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	828 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	829 The nginx array type <literal>ngx_array_t</literal> is defined as follows
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	830 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	831
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	832
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	833 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	834 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	835 void *elts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	836 ngx_uint_t nelts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	837 size_t size;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	838 ngx_uint_t nalloc;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	839 ngx_pool_t *pool;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	840 } ngx_array_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	841 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	842
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	843 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	844 The elements of the array are available in the <literal>elts</literal> field.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	845 The <literal>nelts</literal> field holds the number of elements.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	846 The <literal>size</literal> field holds the size of a single element and is set
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	847 when the array is initialized.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	848 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	849
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	850 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	851 Use the <literal>ngx_array_create(pool, n, size)</literal> call to create an
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	852 array in a pool, and the <literal>ngx_array_init(array, pool, n, size)</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	853 call to initialize an array object that has already been allocated.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	854 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	855
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	856
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	857 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	858 ngx_array_t *a, b;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	859
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	860 /* create an array of strings with preallocated memory for 10 elements */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	861 a = ngx_array_create(pool, 10, sizeof(ngx_str_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	862
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	863 /* initialize string array for 10 elements */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	864 ngx_array_init(&b, pool, 10, sizeof(ngx_str_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	865 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	866
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	867 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	868 Use the following functions to add elements to an array:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	869 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	870
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	871 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	872 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	873
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	874 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	875 <literal>ngx_array_push(a)</literal> adds one tail element and returns pointer
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	876 to it
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	877 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	878
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	879 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	880 <literal>ngx_array_push_n(a, n)</literal> adds <literal>n</literal> tail elements
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	881 and returns pointer to the first one
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	882 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	883
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	884 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	885 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	886
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	887 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	888 If the currently allocated amount of memory is not large enough to accommodate
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	889 the new elements, a new block of memory is allocated and the existing elements
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	890 are copied to it.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	891 The new memory block is normally twice as large as the existing one.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	892 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	893
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	894
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	895 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	896 s = ngx_array_push(a);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	897 ss = ngx_array_push_n(&b, 3);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	898 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	899
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	900 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	901
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	902
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	903 <section name="List" id="list">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	904
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	905 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	906 In nginx a list is a sequence of arrays, optimized for inserting a potentially
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	907 large number of items.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	908 The <literal>ngx_list_t</literal> list type is defined as follows:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	909 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	910
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	911
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	912 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	913 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	914 ngx_list_part_t *last;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	915 ngx_list_part_t part;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	916 size_t size;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	917 ngx_uint_t nalloc;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	918 ngx_pool_t *pool;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	919 } ngx_list_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	920 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	921
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	922 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	923 The actual items are stored in list parts, which are defined as follows:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	924 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	925
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	926
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	927 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	928 typedef struct ngx_list_part_s ngx_list_part_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	929
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	930 struct ngx_list_part_s {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	931 void *elts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	932 ngx_uint_t nelts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	933 ngx_list_part_t *next;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	934 };
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	935 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	936
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	937 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	938 Before use, a list must be initialized by calling
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	939 <literal>ngx_list_init(list, pool, n, size)</literal> or created by calling
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	940 <literal>ngx_list_create(pool, n, size)</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	941 Both functions take as arguments the size of a single item and a number of
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	942 items per list part.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	943 To add an item to a list, use the <literal>ngx_list_push(list)</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	944 function.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	945 To iterate over the items, directly access the list fields as shown in the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	946 example:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	947 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	948
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	949
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	950 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	951 ngx_str_t *v;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	952 ngx_uint_t i;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	953 ngx_list_t *list;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	954 ngx_list_part_t *part;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	955
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	956 list = ngx_list_create(pool, 100, sizeof(ngx_str_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	957 if (list == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	958
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	959 /* add items to the list */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	960
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	961 v = ngx_list_push(list);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	962 if (v == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	963 ngx_str_set(v, "foo");
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	964
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	965 v = ngx_list_push(list);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	966 if (v == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	967 ngx_str_set(v, "bar");
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	968
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	969 /* iterate over the list */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	970
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	971 part = &list->part;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	972 v = part->elts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	973
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	974 for (i = 0; /* void */; i++) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	975
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	976 if (i >= part->nelts) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	977 if (part->next == NULL) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	978 break;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	979 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	980
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	981 part = part->next;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	982 v = part->elts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	983 i = 0;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	984 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	985
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	986 ngx_do_smth(&v[i]);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	987 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	988 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	989
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	990 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	991 Lists are primarily used for HTTP input and output headers.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	992 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	993
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	994 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	995 Lists do not support item removal.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	996 However, when needed, items can internally be marked as missing without actually
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	997 being removed from the list.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	998 For example, to mark HTTP output headers (which are stored as
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	999 <literal>ngx_table_elt_t</literal> objects) as missing, set the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1000 <literal>hash</literal> field in <literal>ngx_table_elt_t</literal> to
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1001 zero.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1002 Items marked in this way are explicitly skipped when the headers are iterated
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1003 over.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1004 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1005
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1006 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1007
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1008
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1009 <section name="Queue" id="queue">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1010
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1011 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1012 In nginx a queue is an intrusive doubly linked list, with each node defined as
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1013 follows:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1014 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1015
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1016
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1017 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1018 typedef struct ngx_queue_s ngx_queue_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1019
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1020 struct ngx_queue_s {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1021 ngx_queue_t *prev;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1022 ngx_queue_t *next;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1023 };
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1024 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1025
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1026 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1027 The head queue node is not linked with any data.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1028 Use the <literal>ngx_queue_init(q)</literal> call to initialize the list head
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1029 before use.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1030 Queues support the following operations:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1031 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1032
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1033 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1034 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1035
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1036 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1037 <literal>ngx_queue_insert_head(h, x)</literal>,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1038 <literal>ngx_queue_insert_tail(h, x)</literal> — Insert a new node
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1039 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1040
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1041 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1042 <literal>ngx_queue_remove(x)</literal> — Remove a queue node
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1043 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1044
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1045 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1046 <literal>ngx_queue_split(h, q, n)</literal> — Split a queue at a node,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1047 returning the queue tail in a separate queue
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1048 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1049
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1050 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1051 <literal>ngx_queue_add(h, n)</literal> — Add a second queue to the first queue
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1052 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1053
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1054 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1055 <literal>ngx_queue_head(h)</literal>,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1056 <literal>ngx_queue_last(h)</literal> — Get first or last queue node
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1057 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1058
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1059 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1060 <literal>ngx_queue_sentinel(h)</literal> - Get a queue sentinel object to end
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1061 iteration at
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1062 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1063
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1064 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1065 <literal>ngx_queue_data(q, type, link)</literal> — Get a reference to the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1066 beginning of a queue node data structure, considering the queue field offset in
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1067 it
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1068 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1069
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1070 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1071 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1072
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1073 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1074 An example:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1075 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1076
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1077
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1078 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1079 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1080 ngx_str_t value;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1081 ngx_queue_t queue;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1082 } ngx_foo_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1083
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1084 ngx_foo_t *f;
2008 1f2f9fa97065 DevGuide: fixed queue example. Vladimir Homutov <vl@nginx.com> parents: 2007 diff changeset	1085 ngx_queue_t values, *q;
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1086
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1087 ngx_queue_init(&values);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1088
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1089 f = ngx_palloc(pool, sizeof(ngx_foo_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1090 if (f == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	1091 ngx_str_set(&f->value, "foo");
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1092
2008 1f2f9fa97065 DevGuide: fixed queue example. Vladimir Homutov <vl@nginx.com> parents: 2007 diff changeset	1093 ngx_queue_insert_tail(&values, &f->queue);
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1094
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1095 /* insert more nodes here */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1096
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1097 for (q = ngx_queue_head(&values);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1098 q != ngx_queue_sentinel(&values);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1099 q = ngx_queue_next(q))
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1100 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1101 f = ngx_queue_data(q, ngx_foo_t, queue);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1102
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1103 ngx_do_smth(&f->value);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1104 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1105 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1106
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1107 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1108
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1109
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1110 <section name="Red-Black tree" id="red_black_tree">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1111
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1112 <para>
1915 8b7c3b0ef1a4 Semantically marked paths. Vladimir Homutov <vl@nginx.com> parents: 1914 diff changeset	1113 The <path>src/core/ngx_rbtree.h</path> header file provides access to the
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1114 effective implementation of red-black trees.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1115 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1116
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1117
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1118 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1119 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1120 ngx_rbtree_t rbtree;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1121 ngx_rbtree_node_t sentinel;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1122
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1123 /* custom per-tree data here */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1124 } my_tree_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1125
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1126 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1127 ngx_rbtree_node_t rbnode;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1128
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1129 /* custom per-node data */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1130 foo_t val;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1131 } my_node_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1132 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1133
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1134 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1135 To deal with a tree as a whole, you need two nodes: root and sentinel.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1136 Typically, they are added to a custom structure, allowing you to
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1137 organize your data into a tree in which the leaves contain a link to or embed
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1138 your data.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1139 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1140
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1141 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1142 To initialize a tree:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1143 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1144
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1145
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1146 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1147 my_tree_t root;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1148
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1149 ngx_rbtree_init(&root.rbtree, &root.sentinel, insert_value_function);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1150 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1151
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1152 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1153 To traverse a tree and insert new values, use the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1154 "<literal>insert_value</literal>" functions.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1155 For example, the <literal>ngx_str_rbtree_insert_value</literal> function deals
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1156 with the <literal>ngx_str_t</literal> type.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1157 Its arguments are pointers to a root node of an insertion, the newly created
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1158 node to be added, and a tree sentinel.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1159 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1160
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1161
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1162 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1163 void ngx_str_rbtree_insert_value(ngx_rbtree_node_t *temp,
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1164 ngx_rbtree_node_t *node,
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1165 ngx_rbtree_node_t *sentinel)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1166 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1167
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1168
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1169 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1170 The traversal is pretty straightforward and can be demonstrated with the
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1171 following lookup function pattern:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1172 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1173
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1174
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1175 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1176 my_node_t *
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1177 my_rbtree_lookup(ngx_rbtree_t rbtree, foo_t val, uint32_t hash)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1178 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1179 ngx_int_t rc;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1180 my_node_t *n;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1181 ngx_rbtree_node_t node, sentinel;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1182
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1183 node = rbtree->root;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1184 sentinel = rbtree->sentinel;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1185
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1186 while (node != sentinel) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1187
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1188 n = (my_node_t *) node;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1189
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1190 if (hash != node->key) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1191 node = (hash < node->key) ? node->left : node->right;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1192 continue;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1193 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1194
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1195 rc = compare(val, node->val);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1196
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1197 if (rc < 0) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1198 node = node->left;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1199 continue;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1200 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1201
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1202 if (rc > 0) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1203 node = node->right;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1204 continue;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1205 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1206
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1207 return n;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1208 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1209
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1210 return NULL;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1211 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1212 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1213
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1214 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1215 The <literal>compare()</literal> function is a classic comparator function that
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1216 returns a value less than, equal to, or greater than zero.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1217 To speed up lookups and avoid comparing user objects that can be big, an integer
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1218 hash field is used.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1219 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1220
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1221 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1222 To add a node to a tree, allocate a new node, initialize it and call
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1223 <literal>ngx_rbtree_insert()</literal>:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1224 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1225
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1226
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1227 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1228 my_node_t *my_node;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1229 ngx_rbtree_node_t *node;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1230
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1231 my_node = ngx_palloc(...);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1232 init_custom_data(&my_node->val);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1233
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1234 node = &my_node->rbnode;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1235 node->key = create_key(my_node->val);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1236
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1237 ngx_rbtree_insert(&root->rbtree, node);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1238 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1239
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1240 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1241 To remove a node, call the <literal>ngx_rbtree_delete()</literal> function:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1242 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1243
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1244
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1245 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1246 ngx_rbtree_delete(&root->rbtree, node);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1247 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1248
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1249 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1250
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1251 <section name="Hash" id="hash">
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1252
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1253 <para>
1920 de5251816480 Fixed a typo. Vladimir Homutov <vl@nginx.com> parents: 1919 diff changeset	1254 Hash table functions are declared in <path>src/core/ngx_hash.h</path>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1255 Both exact and wildcard matching are supported.
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1256 The latter requires extra setup and is described in a separate section below.
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1257 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1258
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1259 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1260 Before initializing a hash, you need to know the number of elements it will
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1261 hold so that nginx can build it optimally.
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1262 Two parameters that need to be configured are <literal>max_size</literal>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1263 and <literal>bucket_size</literal>, as detailed in a separate
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1264 <link doc="../hash.xml">document</link>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1265 They are usually configurable by the user.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1266 Hash initialization settings are stored with the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1267 <literal>ngx_hash_init_t</literal> type, and the hash itself is
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1268 <literal>ngx_hash_t</literal>:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1269 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1270 ngx_hash_t foo_hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1271 ngx_hash_init_t hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1272
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1273 hash.hash = &foo_hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1274 hash.key = ngx_hash_key;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1275 hash.max_size = 512;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1276 hash.bucket_size = ngx_align(64, ngx_cacheline_size);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1277 hash.name = "foo_hash";
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1278 hash.pool = cf->pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1279 hash.temp_pool = cf->temp_pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1280 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1281 The <literal>key</literal> is a pointer to a function that creates the hash
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1282 integer key from a string.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1283 There are two generic key-creation functions:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1284 <literal>ngx_hash_key(data, len)</literal> and
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1285 <literal>ngx_hash_key_lc(data, len)</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1286 The latter converts a string to all lowercase characters, so the passed string
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1287 must be writeable.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1288 If that is not true, pass the <literal>NGX_HASH_READONLY_KEY</literal> flag
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1289 to the function, initializing the key array (see below).
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1290 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1291
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1292 <para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1293 The hash keys are stored in <literal>ngx_hash_keys_arrays_t</literal> and
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1294 are initialized with <literal>ngx_hash_keys_array_init(arr, type)</literal>:
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1295 The second parameter (<literal>type</literal>) controls the amount of resources
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1296 preallocated for the hash and can be either <literal>NGX_HASH_SMALL</literal> or
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1297 <literal>NGX_HASH_LARGE</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1298 The latter is appropriate if you expect the hash to contain thousands of
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1299 elements.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1300
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1301 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1302 ngx_hash_keys_arrays_t foo_keys;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1303
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1304 foo_keys.pool = cf->pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1305 foo_keys.temp_pool = cf->temp_pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1306
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1307 ngx_hash_keys_array_init(&foo_keys, NGX_HASH_SMALL);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1308 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1309 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1310
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1311 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1312 To insert keys into a hash keys array, use the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1313 <literal>ngx_hash_add_key(keys_array, key, value, flags)</literal> function:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1314 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1315 ngx_str_t k1 = ngx_string("key1");
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1316 ngx_str_t k2 = ngx_string("key2");
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1317
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1318 ngx_hash_add_key(&foo_keys, &k1, &my_data_ptr_1, NGX_HASH_READONLY_KEY);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1319 ngx_hash_add_key(&foo_keys, &k2, &my_data_ptr_2, NGX_HASH_READONLY_KEY);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1320 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1321 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1322
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1323 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1324 To build the hash table, call the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1325 <literal>ngx_hash_init(hinit, key_names, nelts)</literal> function:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1326
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1327 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1328 ngx_hash_init(&hash, foo_keys.keys.elts, foo_keys.keys.nelts);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1329 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1330
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1331 The function fails if <literal>max_size</literal> or
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1332 <literal>bucket_size</literal> parameters are not big enough.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1333 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1334
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1335 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1336 When the hash is built, use the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1337 <literal>ngx_hash_find(hash, key, name, len)</literal> function to look up
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1338 elements:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1339 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1340 my_data_t *data;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1341 ngx_uint_t key;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1342
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1343 key = ngx_hash_key(k1.data, k1.len);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1344
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1345 data = ngx_hash_find(&foo_hash, key, k1.data, k1.len);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1346 if (data == NULL) {
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1347 /* key not found */
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1348 }
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1349 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1350
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1351 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1352
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1353 <section name="Wildcard matching" id="wildcard_matching">
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1354
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1355 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1356 To create a hash that works with wildcards, use the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1357 <literal>ngx_hash_combined_t</literal> type.
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1358 It includes the hash type described above and has two additional keys arrays:
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1359 <literal>dns_wc_head</literal> and <literal>dns_wc_tail</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1360 The initialization of basic properties is similar to a regular hash:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1361 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1362 ngx_hash_init_t hash
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1363 ngx_hash_combined_t foo_hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1364
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1365 hash.hash = &foo_hash.hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1366 hash.key = ...;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1367 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1368 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1369
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1370 <para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1371 It is possible to add wildcard keys using the
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1372 <literal>NGX_HASH_WILDCARD_KEY</literal> flag:
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1373 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1374 /* k1 = ".example.org"; */
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1375 /* k2 = "foo."; /
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1376 ngx_hash_add_key(&foo_keys, &k1, &data1, NGX_HASH_WILDCARD_KEY);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1377 ngx_hash_add_key(&foo_keys, &k2, &data2, NGX_HASH_WILDCARD_KEY);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1378 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1379 The function recognizes wildcards and adds keys into the corresponding arrays.
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1380 Please refer to the
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1381 <link doc="../http/ngx_http_map_module.xml" id="map"/> module
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1382 documentation for the description of the wildcard syntax and the
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1383 matching algorithm.
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1384 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1385
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1386 <para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1387 Depending on the contents of added keys, you may need to initialize up to three
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1388 key arrays: one for exact matching (described above), and two more to enable
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1389 matching starting from the head or tail of a string:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1390 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1391 if (foo_keys.dns_wc_head.nelts) {
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1392
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1393 ngx_qsort(foo_keys.dns_wc_head.elts,
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1394 (size_t) foo_keys.dns_wc_head.nelts,
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1395 sizeof(ngx_hash_key_t),
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1396 cmp_dns_wildcards);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1397
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1398 hash.hash = NULL;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1399 hash.temp_pool = pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1400
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1401 if (ngx_hash_wildcard_init(&hash, foo_keys.dns_wc_head.elts,
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1402 foo_keys.dns_wc_head.nelts)
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1403 != NGX_OK)
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1404 {
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1405 return NGX_ERROR;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1406 }
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1407
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1408 foo_hash.wc_head = (ngx_hash_wildcard_t *) hash.hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1409 }
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1410 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1411 The keys array needs to be sorted, and initialization results must be added
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1412 to the combined hash.
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1413 The initialization of <literal>dns_wc_tail</literal> array is done similarly.
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1414 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1415
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1416 <para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1417 The lookup in a combined hash is handled by the
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1418 <literal>ngx_hash_find_combined(chash, key, name, len)</literal>:
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1419 <programlisting>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	1420 /* key = "bar.example.org"; — will match ".example.org" */
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	1421 /* key = "foo.example.com"; — will match "foo." /
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1422
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1423 hkey = ngx_hash_key(key.data, key.len);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1424 res = ngx_hash_find_combined(&foo_hash, hkey, key.data, key.len);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1425 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1426 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1427
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1428 </section>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1429
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1430 </section>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1431
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1432 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1433
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1434
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1435 <section name="Memory management" id="memory_management">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1436
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1437
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1438 <section name="Heap" id="heap">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1439
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1440 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1441 To allocate memory from system heap, use the following functions:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1442 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1443
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1444 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1445 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1446
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1447 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1448 <literal>ngx_alloc(size, log)</literal> — Allocate memory from system heap.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1449 This is a wrapper around <literal>malloc()</literal> with logging support.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1450 Allocation error and debugging information is logged to <literal>log</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1451 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1452
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1453 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1454 <literal>ngx_calloc(size, log)</literal> — Allocate memory from system heap
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1455 like <literal>ngx_alloc()</literal>, but fill memory with zeros after
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1456 allocation.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1457 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1458
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1459 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1460 <literal>ngx_memalign(alignment, size, log)</literal> — Allocate aligned memory
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1461 from system heap.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1462 This is a wrapper around <literal>posix_memalign()</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1463 on those platforms that provide that function.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1464 Otherwise implementation falls back to <literal>ngx_alloc()</literal> which
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1465 provides maximum alignment.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1466 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1467
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1468 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1469 <literal>ngx_free(p)</literal> — Free allocated memory.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1470 This is a wrapper around <literal>free()</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1471 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1472
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1473 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1474 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1475
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1476 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1477
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1478
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1479 <section name="Pool" id="pool">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1480
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1481 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1482 Most nginx allocations are done in pools.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1483 Memory allocated in an nginx pool is freed automatically when the pool is
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1484 destroyed.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1485 This provides good allocation performance and makes memory control easy.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1486 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1487
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1488 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1489 A pool internally allocates objects in continuous blocks of memory.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1490 Once a block is full, a new one is allocated and added to the pool memory
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1491 block list.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1492 When the requested allocation is too large to fit into a block, the request
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1493 is forwarded to the system allocator and the
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1494 returned pointer is stored in the pool for further deallocation.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1495 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1496
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1497 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1498 The type for nginx pools is <literal>ngx_pool_t</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1499 The following operations are supported:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1500 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1501
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1502 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1503 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1504
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1505 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1506 <literal>ngx_create_pool(size, log)</literal> — Create a pool with specified
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1507 block size.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1508 The pool object returned is allocated in the pool as well.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1509 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1510
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1511 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1512 <literal>ngx_destroy_pool(pool)</literal> — Free all pool memory, including
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1513 the pool object itself.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1514 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1515
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1516 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1517 <literal>ngx_palloc(pool, size)</literal> — Allocate aligned memory from the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1518 specified pool.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1519 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1520
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1521 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1522 <literal>ngx_pcalloc(pool, size)</literal> — Allocate aligned memory
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1523 from the specified pool and fill it with zeroes.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1524 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1525
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1526 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1527 <literal>ngx_pnalloc(pool, size)</literal> — Allocate unaligned memory from the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1528 specified pool.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1529 Mostly used for allocating strings.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1530 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1531
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1532 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1533 <literal>ngx_pfree(pool, p)</literal> — Free memory that was previously
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1534 allocated in the specified pool.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1535 Only allocations that result from requests forwarded to the system allocator
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1536 can be freed.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1537 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1538
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1539 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1540 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1541
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1542 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1543 u_char *p;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1544 ngx_str_t *s;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1545 ngx_pool_t *pool;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1546
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1547 pool = ngx_create_pool(1024, log);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1548 if (pool == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1549
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1550 s = ngx_palloc(pool, sizeof(ngx_str_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1551 if (s == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	1552 ngx_str_set(s, "foo");
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1553
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1554 p = ngx_pnalloc(pool, 3);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1555 if (p == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	1556 ngx_memcpy(p, "foo", 3);
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1557 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1558
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1559 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1560 Chain links (<literal>ngx_chain_t</literal>) are actively used in nginx,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1561 so the nginx pool implementation provides a way to reuse them.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1562 The <literal>chain</literal> field of <literal>ngx_pool_t</literal> keeps a
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1563 list of previously allocated links ready for reuse.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1564 For efficient allocation of a chain link in a pool, use the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1565 <literal>ngx_alloc_chain_link(pool)</literal> function.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1566 This function looks up a free chain link in the pool list and allocates a new
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1567 chain link if the pool list is empty.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1568 To free a link, call the <literal>ngx_free_chain(pool, cl)</literal> function.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1569 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1570
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1571 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1572 Cleanup handlers can be registered in a pool.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1573 A cleanup handler is a callback with an argument which is called when pool is
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1574 destroyed.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1575 A pool is usually tied to a specific nginx object (like an HTTP request) and is
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1576 destroyed when the object reaches the end of its lifetime.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1577 Registering a pool cleanup is a convenient way to release resources, close
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1578 file descriptors or make final adjustments to the shared data associated with
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1579 the main object.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1580 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1581
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1582 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1583 To register a pool cleanup, call
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1584 <literal>ngx_pool_cleanup_add(pool, size)</literal>, which returns a
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1585 <literal>ngx_pool_cleanup_t</literal> pointer to
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1586 be filled in by the caller.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1587 Use the <literal>size</literal> argument to allocate context for the cleanup
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1588 handler.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1589 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1590
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1591
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1592 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1593 ngx_pool_cleanup_t *cln;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1594
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1595 cln = ngx_pool_cleanup_add(pool, 0);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1596 if (cln == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1597
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1598 cln->handler = ngx_my_cleanup;
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	1599 cln->data = "foo";
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1600
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1601 ...
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1602
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1603 static void
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1604 ngx_my_cleanup(void *data)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1605 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1606 u_char *msg = data;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1607
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1608 ngx_do_smth(msg);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1609 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1610 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1611
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1612 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1613
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1614
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1615 <section name="Shared memory" id="shared_memory">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1616
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1617 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1618 Shared memory is used by nginx to share common data between processes.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1619 The <literal>ngx_shared_memory_add(cf, name, size, tag)</literal> function adds
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1620 a new shared memory entry <literal>ngx_shm_zone_t</literal> to a cycle.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1621 The function receives the <literal>name</literal> and <literal>size</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1622 of the zone.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1623 Each shared zone must have a unique name.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1624 If a shared zone entry with the provided <literal>name</literal> and
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1625 <literal>tag</literal> already exists, the existing zone entry is reused.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1626 The function fails with an error if an existing entry with the same name has a
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1627 different tag.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1628 Usually, the address of the module structure is passed as
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1629 <literal>tag</literal>, making it possible to reuse shared zones by name within
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1630 one nginx module.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1631 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1632
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1633 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1634 The shared memory entry structure <literal>ngx_shm_zone_t</literal> has the
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1635 following fields:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1636 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1637
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1638 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1639 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1640
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1641 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1642 <literal>init</literal> — Initialization callback, called after the shared zone
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1643 is mapped to actual memory
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1644 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1645
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1646 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1647 <literal>data</literal> — Data context, used to pass arbitrary data to the
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1648 <literal>init</literal> callback
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1649 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1650
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1651 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1652 <literal>noreuse</literal> — Flag that disables reuse of a shared zone from the
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1653 old cycle
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1654 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1655
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1656 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1657 <literal>tag</literal> — Shared zone tag
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1658 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1659
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1660 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1661 <literal>shm</literal> — Platform-specific object of type
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1662 <literal>ngx_shm_t</literal>, having at least the following fields:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1663 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1664
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1665 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1666 <literal>addr</literal> — Mapped shared memory address, initially NULL
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1667 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1668
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1669 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1670 <literal>size</literal> — Shared memory size
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1671 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1672
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1673 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1674 <literal>name</literal> — Shared memory name
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1675 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1676
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1677 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1678 <literal>log</literal> — Shared memory log
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1679 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1680
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1681 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1682 <literal>exists</literal> — Flag that indicates shared memory was inherited
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1683 from the master process (Windows-specific)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1684 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1685
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1686 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1687 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1688
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1689 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1690 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1691
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1692 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1693 Shared zone entries are mapped to actual memory in
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1694 <literal>ngx_init_cycle()</literal> after the configuration is parsed.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1695 On POSIX systems, the <literal>mmap()</literal> syscall is used to create the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1696 shared anonymous mapping.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1697 On Windows, the <literal>CreateFileMapping()</literal>/
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1698 <literal>MapViewOfFileEx()</literal> pair is used.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1699 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1700
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1701 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1702 For allocating in shared memory, nginx provides the slab pool
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1703 <literal>ngx_slab_pool_t</literal> type.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1704 A slab pool for allocating memory is automatically created in each nginx shared
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1705 zone.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1706 The pool is located in the beginning of the shared zone and can be accessed by
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1707 the expression <literal>(ngx_slab_pool_t *) shm_zone->shm.addr</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1708 To allocate memory in a shared zone, call either
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1709 <literal>ngx_slab_alloc(pool, size)</literal> or
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1710 <literal>ngx_slab_calloc(pool, size)</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1711 To free memory, call <literal>ngx_slab_free(pool, p)</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1712 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1713
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1714 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1715 Slab pool divides all shared zone into pages.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1716 Each page is used for allocating objects of the same size.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1717 The specified size must be a power of 2, and greater than the minimum size of
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1718 8 bytes.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1719 Nonconforming values are rounded up.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1720 A bitmask for each page tracks which blocks are in use and which are free for
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1721 allocation.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1722 For sizes greater than a half page (which is usually 2048 bytes), allocation is
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1723 done an entire page at a time
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1724 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1725
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1726 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1727 To protect data in shared memory from concurrent access, use the mutex
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1728 available in the <literal>mutex</literal> field of
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1729 <literal>ngx_slab_pool_t</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1730 A mutex is most commonly used by the slab pool while allocating and freeing
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1731 memory, but it can be used to protect any other user data structures allocated
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1732 in the shared zone.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1733 To lock or unlock a mutex, call
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1734 <literal>ngx_shmtx_lock(&shpool->mutex)</literal> or
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1735 <literal>ngx_shmtx_unlock(&shpool->mutex)</literal> respectively.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1736 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1737
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1738
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1739 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1740 ngx_str_t name;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1741 ngx_foo_ctx_t *ctx;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1742 ngx_shm_zone_t *shm_zone;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1743
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1744 ngx_str_set(&name, "foo");
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1745
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1746 /* allocate shared zone context */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1747 ctx = ngx_pcalloc(cf->pool, sizeof(ngx_foo_ctx_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1748 if (ctx == NULL) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1749 /* error */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1750 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1751
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1752 /* add an entry for 64k shared zone */
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1753 shm_zone = ngx_shared_memory_add(cf, &name, 65536, &ngx_foo_module);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1754 if (shm_zone == NULL) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1755 /* error */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1756 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1757
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1758 /* register init callback and context */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1759 shm_zone->init = ngx_foo_init_zone;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1760 shm_zone->data = ctx;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1761
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1762
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1763 ...
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1764
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1765
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1766 static ngx_int_t
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1767 ngx_foo_init_zone(ngx_shm_zone_t shm_zone, void data)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1768 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1769 ngx_foo_ctx_t *octx = data;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1770
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1771 size_t len;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1772 ngx_foo_ctx_t *ctx;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1773 ngx_slab_pool_t *shpool;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1774
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1775 value = shm_zone->data;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1776
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1777 if (octx) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1778 /* reusing a shared zone from old cycle */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1779 ctx->value = octx->value;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1780 return NGX_OK;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1781 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1782
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1783 shpool = (ngx_slab_pool_t *) shm_zone->shm.addr;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1784
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1785 if (shm_zone->shm.exists) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1786 /* initialize shared zone context in Windows nginx worker */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1787 ctx->value = shpool->data;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1788 return NGX_OK;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1789 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1790
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1791 /* initialize shared zone */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1792
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1793 ctx->value = ngx_slab_alloc(shpool, sizeof(ngx_uint_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1794 if (ctx->value == NULL) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1795 return NGX_ERROR;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1796 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1797
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1798 shpool->data = ctx->value;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1799
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1800 return NGX_OK;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1801 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1802 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1803
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1804 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1805
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1806
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1807 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1808
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1809
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1810 <section name="Logging" id="logging">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1811
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1812 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1813 For logging nginx uses <literal>ngx_log_t</literal> objects.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1814 The nginx logger supports several types of output:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1815
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1816 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1817
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1818 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1819 stderr — Logging to standard error (stderr)
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1820 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1821
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1822 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1823 file — Logging to a file
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1824 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1825
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1826 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1827 syslog — Logging to syslog
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1828 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1829
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1830 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1831 memory — Logging to internal memory storage for development purposes; the memory
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1832 can be accessed later with a debugger
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1833 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1834
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1835 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1836 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1837
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1838 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1839 A logger instance can be a chain of loggers, linked to each other with
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1840 the <literal>next</literal> field.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1841 In this case, each message is written to all loggers in the chain.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1842 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1843
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1844 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1845 For each logger, a severity level controls which messages are written to the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1846 log (only events assigned that level or higher are logged).
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1847 The following severity levels are supported:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1848 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1849
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1850 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1851 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1852
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1853 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1854 <literal>NGX_LOG_EMERG</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1855 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1856
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1857 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1858 <literal>NGX_LOG_ALERT</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1859 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1860
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1861 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1862 <literal>NGX_LOG_CRIT</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1863 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1864
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1865 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1866 <literal>NGX_LOG_ERR</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1867 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1868
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1869 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1870 <literal>NGX_LOG_WARN</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1871 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1872
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1873 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1874 <literal>NGX_LOG_NOTICE</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1875 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1876
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1877 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1878 <literal>NGX_LOG_INFO</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1879 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1880
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1881 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1882 <literal>NGX_LOG_DEBUG</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1883 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1884
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1885 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1886 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1887
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1888 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1889 For debug logging, the debug mask is checked as well.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1890 The debug masks are:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1891 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1892
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1893 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1894 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1895
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1896 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1897 <literal>NGX_LOG_DEBUG_CORE</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1898 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1899
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1900 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1901 <literal>NGX_LOG_DEBUG_ALLOC</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1902 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1903
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1904 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1905 <literal>NGX_LOG_DEBUG_MUTEX</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1906 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1907
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1908 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1909 <literal>NGX_LOG_DEBUG_EVENT</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1910 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1911
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1912 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1913 <literal>NGX_LOG_DEBUG_HTTP</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1914 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1915
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1916 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1917 <literal>NGX_LOG_DEBUG_MAIL</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1918 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1919
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1920 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1921 <literal>NGX_LOG_DEBUG_STREAM</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1922 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1923
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1924 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1925 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1926
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1927 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1928 Normally, loggers are created by existing nginx code from
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1929 <literal>error_log</literal> directives and are available at nearly every stage
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1930 of processing in cycle, configuration, client connection and other objects.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1931 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1932
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1933 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1934 Nginx provides the following logging macros:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1935 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1936
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1937 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1938 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1939
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1940 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1941 <literal>ngx_log_error(level, log, err, fmt, ...)</literal> — Error logging
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1942 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1943
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1944 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1945 <literal>ngx_log_debug0(level, log, err, fmt)</literal>,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1946 <literal>ngx_log_debug1(level, log, err, fmt, arg1)</literal> etc — Debug
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1947 logging with up to eight supported formatting arguments
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1948 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1949
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1950 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1951 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1952
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1953 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1954 A log message is formatted in a buffer of size
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1955 <literal>NGX_MAX_ERROR_STR</literal> (currently, 2048 bytes) on stack.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1956 The message is prepended with the severity level, process ID (PID), connection
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1957 ID (stored in <literal>log->connection</literal>), and the system error text.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1958 For non-debug messages <literal>log->handler</literal> is called as well to
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1959 prepend more specific information to the log message.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1960 HTTP module sets <literal>ngx_http_log_error()</literal> function as log
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1961 handler to log client and server addresses, current action (stored in
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1962 <literal>log->action</literal>), client request line, server name etc.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1963 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1964
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1965 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1966 /* specify what is currently done */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1967 log->action = "sending mp4 to client”;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1968
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1969 /* error and debug log */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1970 ngx_log_error(NGX_LOG_INFO, c->log, 0, "client prematurely
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1971 closed connection”);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1972
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1973 ngx_log_debug2(NGX_LOG_DEBUG_HTTP, mp4->file.log, 0,
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1974 "mp4 start:%ui, length:%ui”, mp4->start, mp4->length);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1975 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1976
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1977 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1978 The example above results in log entries like these:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1979 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1980
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1981
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1982 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1983 2016/09/16 22:08:52 [info] 17445#0: *1 client prematurely closed connection while
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1984 sending mp4 to client, client: 127.0.0.1, server: , request: "GET /file.mp4 HTTP/1.1”
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1985 2016/09/16 23:28:33 [debug] 22140#0: *1 mp4 start:0, length:10000
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1986 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1987
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1988 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1989
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1990
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1991 <section name="Cycle" id="cycle">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1992
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1993 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1994 A cycle object stores the nginx runtime context created from a specific
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1995 configuration.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1996 Its type is <literal>ngx_cycle_t</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1997 The current cycle is referenced by the <literal>ngx_cycle</literal> global
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1998 variable and inherited by nginx workers as they start.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1999 Each time the nginx configuration is reloaded, a new cycle is created from the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2000 new nginx configuration; the old cycle is usually deleted after the new one is
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2001 successfully created.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2002 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2003
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2004 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2005 A cycle is created by the <literal>ngx_init_cycle()</literal> function, which
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2006 takes the previous cycle as its argument.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2007 The function locates the previous cycle's configuration file and inherits as
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2008 many resources as possible from the previous cycle.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2009 A placeholder cycle called "init cycle" is created as nginx start, then is
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2010 replaced by an actual cycle built from configuration.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2011 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2012
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2013 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2014 Members of the cycle include:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2015 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2016
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2017 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2018 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2019
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2020 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2021 <literal>pool</literal> — Cycle pool.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2022 Created for each new cycle.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2023 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2024
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2025 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2026 <literal>log</literal> — Cycle log.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2027 Initially inherited from the old cycle, it is set to point to
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2028 <literal>new_log</literal> after the configuration is read.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2029 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2030
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2031 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2032 <literal>new_log</literal> — Cycle log, created by the configuration.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2033 It's affected by the root-scope <literal>error_log</literal> directive.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2034 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2035
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2036 <listitem>
1981 082724c57c38 Fixes in cycle section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1980 diff changeset	2037 <literal>connections</literal>, <literal>connection_n</literal> —
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2038 Array of connections of type <literal>ngx_connection_t</literal>, created by
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2039 the event module while initializing each nginx worker.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2040 The <literal>worker_connections</literal> directive in the nginx configuration
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2041 sets the number of connections <literal>connection_n</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2042 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2043
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2044 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2045 <literal>free_connections</literal>,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2046 <literal>free_connection_n</literal> — List and number of currently available
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2047 connections.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2048 If no connections are available, an nginx worker refuses to accept new clients
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2049 or connect to upstream servers.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2050 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2051
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2052 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2053 <literal>files</literal>, <literal>files_n</literal> — Array for mapping file
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2054 descriptors to nginx connections.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2055 This mapping is used by the event modules, having the
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2056 <literal>NGX_USE_FD_EVENT</literal> flag (currently, it's
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2057 <literal>poll</literal> and <literal>devpoll</literal>).
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2058 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2059
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2060 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2061 <literal>conf_ctx</literal> — Array of core module configurations.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2062 The configurations are created and filled during reading of nginx configuration
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2063 files.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2064 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2065
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2066 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2067 <literal>modules</literal>, <literal>modules_n</literal> — Array of modules
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2068 of type <literal>ngx_module_t</literal>, both static and dynamic, loaded by
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2069 the current configuration.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2070 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2071
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2072 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2073 <literal>listening</literal> — Array of listening objects of type
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2074 <literal>ngx_listening_t</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2075 Listening objects are normally added by the <literal>listen</literal>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2076 directive of different modules which call the
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2077 <literal>ngx_create_listening()</literal> function.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2078 Listen sockets are created based on the listening objects.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2079 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2080
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2081 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2082 <literal>paths</literal> — Array of paths of type <literal>ngx_path_t</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2083 Paths are added by calling the function <literal>ngx_add_path()</literal> from
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2084 modules which are going to operate on certain directories.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2085 These directories are created by nginx after reading configuration, if missing.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2086 Moreover, two handlers can be added for each path:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2087
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2088 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2089
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2090 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2091 path loader — Executes only once in 60 seconds after starting or reloading
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2092 nginx.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2093 Normally, the loader reads the directory and stores data in nginx shared
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2094 memory.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2095 The handler is called from the dedicated nginx process “nginx cache loader”.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2096 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2097
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2098 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2099 path manager — Executes periodically.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2100 Normally, the manager removes old files from the directory and updates nginx
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2101 memory to reflect the changes.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2102 The handler is called from the dedicated “nginx cache manager” process.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2103 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2104
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2105 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2106 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2107
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2108 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2109 <literal>open_files</literal> — List of open file objects of type
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2110 <literal>ngx_open_file_t</literal>, which are created by calling the function
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2111 <literal>ngx_conf_open_file()</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2112 Currently, nginx uses this kind of open files for logging.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2113 After reading the configuration, nginx opens all files in the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2114 <literal>open_files</literal> list and stores each file descriptor in the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2115 object's <literal>fd</literal> field.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2116 The files are opened in append mode and are created if missing.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2117 The files in the list are reopened by nginx workers upon receiving the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2118 reopen signal (most often <literal>USR1</literal>).
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2119 In this case the descriptor in the <literal>fd</literal> field is changed to a
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2120 new value.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2121 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2122
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2123 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2124 <literal>shared_memory</literal> — List of shared memory zones, each added by
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2125 calling the <literal>ngx_shared_memory_add()</literal> function.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2126 Shared zones are mapped to the same address range in all nginx processes and
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2127 are used to share common data, for example the HTTP cache in-memory tree.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2128 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2129
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2130 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2131 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2132
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2133 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2134
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2135 <section name="Buffer" id="buffer">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2136
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2137 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2138 For input/output operations, nginx provides the buffer type
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2139 <literal>ngx_buf_t</literal>.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2140 Normally, it's used to hold data to be written to a destination or read from a
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2141 source.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2142 A buffer can reference data in memory or in a file and it's technically
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2143 possible for a buffer to reference both at the same time.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2144 Memory for the buffer is allocated separately and is not related to the buffer
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2145 structure <literal>ngx_buf_t</literal>.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2146 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2147
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2148 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2149 The <literal>ngx_buf_t</literal> structure has the following fields:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2150 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2151
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2152 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2153 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2154
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2155 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2156 <literal>start</literal>, <literal>end</literal> — The boundaries of the memory
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2157 block allocated for the buffer.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2158 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2159
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2160 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2161 <literal>pos</literal>, <literal>last</literal> — The boundaries of the memory
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2162 buffer; normally a subrange of <literal>start</literal> ..
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2163 <literal>end</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2164 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2165
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2166 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2167 <literal>file_pos</literal>, <literal>file_last</literal> — The boundaries of a
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2168 file buffer, expressed as offsets from the beginning of the file.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2169 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2170
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2171 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2172 <literal>tag</literal> — Unique value used to distinguish buffers; created by
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2173 different nginx modules, usually for the purpose of buffer reuse.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2174 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2175
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2176 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2177 <literal>file</literal> — File object.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2178 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2179
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2180 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2181 <literal>temporary</literal> — Flag indicating that the buffer references
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2182 writable memory.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2183 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2184
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2185 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2186 <literal>memory</literal> — Flag indicating that the buffer references read-only
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2187 memory.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2188 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2189
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2190 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2191 <literal>in_file</literal> — Flag indicating that the buffer references data
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2192 in a file.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2193 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2194
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2195 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2196 <literal>flush</literal> — Flag indicating that all data prior to the buffer
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2197 need to be flushed.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2198 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2199
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2200 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2201 <literal>recycled</literal> — Flag indicating that the buffer can be reused and
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2202 needs to be consumed as soon as possible.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2203 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2204
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2205 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2206 <literal>sync</literal> — Flag indicating that the buffer carries no data or
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2207 special signal like <literal>flush</literal> or <literal>last_buf</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2208 By default nginx considers such buffers an error condition, but this flag tells
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2209 nginx to skip the error check.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2210 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2211
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2212 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2213 <literal>last_buf</literal> — Flag indicating that the buffer is the last in
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2214 output.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2215 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2216
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2217 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2218 <literal>last_in_chain</literal> — Flag indicating that there are no more data
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2219 buffers in a request or subrequest.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2220 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2221
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2222 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2223 <literal>shadow</literal> — Reference to another ("shadow") buffer related to
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2224 the current buffer, usually in the sense that the buffer uses data from the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2225 shadow.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2226 When the buffer is consumed, the shadow buffer is normally also marked as
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2227 consumed.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2228 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2229
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2230 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2231 <literal>last_shadow</literal> — Flag indicating that the buffer is the last
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2232 one that references a particular shadow buffer.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2233 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2234
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2235 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2236 <literal>temp_file</literal> — Flag indicating that the buffer is in a temporary
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2237 file.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2238 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2239
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2240 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2241 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2242
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2243 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2244 For input and output operations buffers are linked in chains.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2245 A chain is a sequence of chain links of type <literal>ngx_chain_t</literal>,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2246 defined as follows:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2247 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2248
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2249
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2250 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2251 typedef struct ngx_chain_s ngx_chain_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2252
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2253 struct ngx_chain_s {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2254 ngx_buf_t *buf;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2255 ngx_chain_t *next;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2256 };
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2257 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2258
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2259 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2260 Each chain link keeps a reference to its buffer and a reference to the next
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2261 chain link.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2262 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2263
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2264 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2265 An example of using buffers and chains:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2266 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2267
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2268
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2269 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2270 ngx_chain_t *
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2271 ngx_get_my_chain(ngx_pool_t *pool)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2272 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2273 ngx_buf_t *b;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2274 ngx_chain_t out, cl, **ll;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2275
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2276 /* first buf */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2277 cl = ngx_alloc_chain_link(pool);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2278 if (cl == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2279
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2280 b = ngx_calloc_buf(pool);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2281 if (b == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2282
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2283 b->start = (u_char *) "foo";
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2284 b->pos = b->start;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2285 b->end = b->start + 3;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2286 b->last = b->end;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2287 b->memory = 1; /* read-only memory */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2288
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2289 cl->buf = b;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2290 out = cl;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2291 ll = &cl->next;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2292
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2293 /* second buf */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2294 cl = ngx_alloc_chain_link(pool);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2295 if (cl == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2296
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2297 b = ngx_create_temp_buf(pool, 3);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2298 if (b == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2299
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2300 b->last = ngx_cpymem(b->last, "foo", 3);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2301
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2302 cl->buf = b;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2303 cl->next = NULL;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2304 *ll = cl;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2305
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2306 return out;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2307 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2308 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2309
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2310 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2311
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2312
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2313 <section name="Networking" id="networking">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2314
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2315
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2316 <!--
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2317 <section name="Network data types" id="network_data_types">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2318
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2319 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2320 TBD: ngx_addr_t, ngx_url_t, ngx_socket_t, ngx_sockaddr_t, parse url, parse
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2321 address...
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2322 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2323
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2324 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2325 -->
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2326
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2327 <section name="Connection" id="connection">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2328
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2329 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2330 The connection type <literal>ngx_connection_t</literal> is a wrapper around a
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2331 socket descriptor.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2332 It includes the following fields:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2333 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2334
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2335 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2336 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2337
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2338 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2339 <literal>fd</literal> — Socket descriptor
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2340 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2341
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2342 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2343 <literal>data</literal> — Arbitrary connection context.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2344 Normally, it is a pointer to a higher-level object built on top of the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2345 connection, such as an HTTP request or a Stream session.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2346 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2347
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2348 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2349 <literal>read</literal>, <literal>write</literal> — Read and write events for
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2350 the connection.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2351 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2352
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2353 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2354 <literal>recv</literal>, <literal>send</literal>,
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	2355 <literal>recv_chain</literal>, <literal>send_chain</literal> — I/O operations
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2356 for the connection.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2357 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2358
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2359 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2360 <literal>pool</literal> — Connection pool.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2361 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2362
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2363 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2364 <literal>log</literal> — Connection log.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2365 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2366
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2367 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2368 <literal>sockaddr</literal>, <literal>socklen</literal>,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2369 <literal>addr_text</literal> — Remote socket address in binary and text forms.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2370 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2371
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2372 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2373 <literal>local_sockaddr</literal>, <literal>local_socklen</literal> — Local
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2374 socket address in binary form.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2375 Initially, these fields are empty.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2376 Use the <literal>ngx_connection_local_sockaddr()</literal> function to get the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2377 local socket address.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2378 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2379
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2380 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2381 <literal>proxy_protocol_addr</literal>, <literal>proxy_protocol_port</literal>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2382 - PROXY protocol client address and port, if the PROXY protocol is enabled for
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2383 the connection.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2384 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2385
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2386 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2387 <literal>ssl</literal> — SSL context for the connection.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2388 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2389
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2390 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2391 <literal>reusable</literal> — Flag indicating the connection is in a state that
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2392 makes it eligible for reuse.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2393 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2394
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2395 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2396 <literal>close</literal> — Flag indicating that the connection is being reused
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2397 and needs to be closed.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2398 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2399
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2400 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2401 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2402
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2403 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2404 An nginx connection can transparently encapsulate the SSL layer.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2405 In this case the connection's <literal>ssl</literal> field holds a pointer to an
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2406 <literal>ngx_ssl_connection_t</literal> structure, keeping all SSL-related data
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2407 for the connection, including <literal>SSL_CTX</literal> and
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2408 <literal>SSL</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2409 The <literal>recv</literal>, <literal>send</literal>,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2410 <literal>recv_chain</literal>, and <literal>send_chain</literal> handlers are
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2411 set to SSL-enabled functions as well.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2412 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2413
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2414 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2415 The <literal>worker_connections</literal> directive in the nginx configuration
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2416 limits the number of connections per nginx worker.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2417 All connection structures are precreated when a worker starts and stored in
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2418 the <literal>connections</literal> field of the cycle object.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2419 To retrieve a connection structure, use the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2420 <literal>ngx_get_connection(s, log)</literal> function.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2421 It takes as its <literal>s</literal> argument a socket descriptor, which needs
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2422 to be wrapped in a connection structure.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2423 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2424
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2425 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2426 Because the number of connections per worker is limited, nginx provides a
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2427 way to grab connections that are currently in use.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2428 To enable or disable reuse of a connection, call the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2429 <literal>ngx_reusable_connection(c, reusable)</literal> function.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2430 Calling <literal>ngx_reusable_connection(c, 1)</literal> sets the
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2431 <literal>reuse</literal> flag in the connection structure and inserts the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2432 connection into the <literal>reusable_connections_queue</literal> of the cycle.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2433 Whenever <literal>ngx_get_connection()</literal> finds out there are no
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2434 available connections in the cycle's <literal>free_connections</literal> list,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2435 it calls <literal>ngx_drain_connections()</literal> to release a
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2436 specific number of reusable connections.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2437 For each such connection, the <literal>close</literal> flag is set and its read
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2438 handler is called which is supposed to free the connection by calling
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2439 <literal>ngx_close_connection(c)</literal> and make it available for reuse.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2440 To exit the state when a connection can be reused
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2441 <literal>ngx_reusable_connection(c, 0)</literal> is called.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2442 HTTP client connections are an example of reusable connections in nginx; they
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2443 are marked as reusable until the first request byte is received from the client.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2444 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2445
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2446 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2447
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2448
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2449 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2450
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2451
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2452 <section name="Events" id="events">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2453
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2454
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2455 <section name="Event" id="event">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2456
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2457 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2458 Event object <literal>ngx_event_t</literal> in nginx provides a mechanism
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2459 for notification that a specific event has occurred.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2460 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2461
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2462 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2463 Fields in <literal>ngx_event_t</literal> include:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2464 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2465
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2466 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2467 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2468
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2469 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2470 <literal>data</literal> — Arbitrary event context used in event handlers,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2471 usually as pointer to a connection related to the event.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2472 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2473
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2474 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2475 <literal>handler</literal> — Callback function to be invoked when the event
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2476 happens.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2477 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2478
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2479 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2480 <literal>write</literal> — Flag indicating a write event.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2481 Absence of the flag indicates a read event.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2482 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2483
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2484 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2485 <literal>active</literal> — Flag indicating that the event is registered for
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2486 receiving I/O notifications, normally from notification mechanisms like
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2487 <literal>epoll</literal>, <literal>kqueue</literal>, <literal>poll</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2488 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2489
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2490 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2491 <literal>ready</literal> — Flag indicating that the event has received an
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2492 I/O notification.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2493 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2494
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2495 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2496 <literal>delayed</literal> — Flag indicating that I/O is delayed due to rate
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2497 limiting.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2498 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2499
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2500 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2501 <literal>timer</literal> — Red-black tree node for inserting the event into
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2502 the timer tree.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2503 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2504
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2505 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2506 <literal>timer_set</literal> — Flag indicating that the event timer is set and
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2507 not yet expired.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2508 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2509
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2510 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2511 <literal>timedout</literal> — Flag indicating that the event timer has expired.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2512 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2513
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2514 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2515 <literal>eof</literal> — Flag indicating that EOF occurred while reading data.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2516 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2517
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2518 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2519 <literal>pending_eof</literal> — Flag indicating that EOF is pending on the
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2520 socket, even though there may be some data available before it.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2521 The flag is delivered via the <literal>EPOLLRDHUP</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2522 <literal>epoll</literal> event or
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2523 <literal>EV_EOF</literal> <literal>kqueue</literal> flag.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2524 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2525
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2526 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2527 <literal>error</literal> — Flag indicating that an error occurred during
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2528 reading (for a read event) or writing (for a write event).
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2529 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2530
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2531 <listitem>
1995 80f53da7280c Updated cancelable event description in the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1994 diff changeset	2532 <literal>cancelable</literal> — Timer event flag indicating that the event
80f53da7280c Updated cancelable event description in the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1994 diff changeset	2533 should be ignored while shutting down the worker.
80f53da7280c Updated cancelable event description in the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1994 diff changeset	2534 Graceful worker shutdown is delayed until there are no non-cancelable timer
80f53da7280c Updated cancelable event description in the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1994 diff changeset	2535 events scheduled.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2536 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2537
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2538 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2539 <literal>posted</literal> — Flag indicating that the event is posted to a queue.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2540 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2541
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2542 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2543 <literal>queue</literal> — Queue node for posting the event to a queue.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2544 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2545
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2546 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2547 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2548
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2549 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2550
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2551
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2552 <section name="I/O events" id="i_o_events">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2553
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2554 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2555 Each connection obtained by calling the <literal>ngx_get_connection()</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2556 function has two attached events, <literal>c->read</literal> and
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2557 <literal>c->write</literal>, which are used for receiving notification that the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2558 socket is ready for reading or writing.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2559 All such events operate in Edge-Triggered mode, meaning that they only trigger
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2560 notifications when the state of the socket changes.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2561 For example, doing a partial read on a socket does not make nginx deliver a
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2562 repeated read notification until more data arrives on the socket.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2563 Even when the underlying I/O notification mechanism is essentially
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2564 Level-Triggered (<literal>poll</literal>, <literal>select</literal> etc), nginx
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2565 converts the notifications to Edge-Triggered.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2566 To make nginx event notifications consistent across all notifications systems
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2567 on different platforms, the functions
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2568 <literal>ngx_handle_read_event(rev, flags)</literal> and
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2569 <literal>ngx_handle_write_event(wev, lowat)</literal> must be called after
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2570 handling an I/O socket notification or calling any I/O functions on that socket.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2571 Normally, the functions are called once at the end of each read or write
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2572 event handler.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2573 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2574
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2575 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2576
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2577
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2578 <section name="Timer events" id="timer_events">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2579
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2580 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2581 An event can be set to send a notification when a timeout expires.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2582 The function <literal>ngx_add_timer(ev, timer)</literal> sets a timeout for an
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2583 event, <literal>ngx_del_timer(ev)</literal> deletes a previously set timeout.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2584 The global timeout red-black tree <literal>ngx_event_timer_rbtree</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2585 stores all timeouts currently set.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2586 The key in the tree is of type <literal>ngx_msec_t</literal> and is the time
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2587 when the event expires, expressed in milliseconds since the midnight on of
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2588 January 1, 1970 modulus <literal>ngx_msec_t</literal> max value.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2589 The tree structure enables fast insertion and deletion operations, as well as
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2590 access to the nearest timeouts, which nginx uses to find out how long to wait
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2591 for I/O events and for expiring timeout events.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2592 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2593
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2594 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2595
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2596
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2597 <section name="Posted events" id="posted_events">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2598
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2599 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2600 An event can be posted which means that its handler will be called at some
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2601 point later within the current event loop iteration.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2602 Posting events is a good practice for simplifying code and escaping stack
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2603 overflows.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2604 Posted events are held in a post queue.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2605 The <literal>ngx_post_event(ev, q)</literal> mscro posts the event
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2606 <literal>ev</literal> to the post queue <literal>q</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2607 The <literal>ngx_delete_posted_event(ev)</literal> macro deletes the event
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2608 <literal>ev</literal> from the queue it's currently posted in.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2609 Normally, events are posted to the <literal>ngx_posted_events</literal> queue,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2610 which is processed late in the event loop — after all I/O and timer
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2611 events are already handled.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2612 The function <literal>ngx_event_process_posted()</literal> is called to process
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2613 an event queue.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2614 It calls event handlers until the queue is not empty.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2615 This means that a posted event handler can post more events to be processed
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2616 within the current event loop iteration.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2617 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2618
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2619 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2620 An example:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2621 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2622
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2623
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2624 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2625 void
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2626 ngx_my_connection_read(ngx_connection_t *c)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2627 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2628 ngx_event_t *rev;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2629
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2630 rev = c->read;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2631
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2632 ngx_add_timer(rev, 1000);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2633
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2634 rev->handler = ngx_my_read_handler;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2635
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2636 ngx_my_read(rev);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2637 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2638
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2639
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2640 void
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2641 ngx_my_read_handler(ngx_event_t *rev)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2642 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2643 ssize_t n;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2644 ngx_connection_t *c;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2645 u_char buf[256];
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2646
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2647 if (rev->timedout) { /* timeout expired */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2648
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2649 c = rev->data;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2650
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2651 while (rev->ready) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2652 n = c->recv(c, buf, sizeof(buf));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2653
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2654 if (n == NGX_AGAIN) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2655 break;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2656 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2657
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2658 if (n == NGX_ERROR) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2659
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2660 /* process buf */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2661 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2662
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2663 if (ngx_handle_read_event(rev, 0) != NGX_OK) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2664 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2665 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2666
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2667 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2668
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2669
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2670 <section name="Event loop" id="event_loop">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2671
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2672 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2673 Except for the nginx master process, all nginx processes do I/O and so have an
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2674 event loop.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2675 (The nginx master process instead spends most of its time in the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2676 <literal>sigsuspend()</literal> call waiting for signals to arrive.)
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2677 The nginx event loop is implemented in the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2678 <literal>ngx_process_events_and_timers()</literal> function, which is called
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2679 repeatedly until the process exits.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2680 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2681
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2682 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2683 The event loop has the following stages:
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2684
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2685 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2686
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2687 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2688 Find the timeout that is closest to expiring, by calling
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2689 <literal>ngx_event_find_timer()</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2690 This function finds the leftmost node in the timer tree and returns the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2691 number of milliseconds until the node expires.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2692 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2693
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2694 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2695 Process I/O events by calling a handler, specific to the event notification
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2696 mechanism, chosen by nginx configuration.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2697 This handler waits for at least one I/O event to happen, but only until the next
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2698 timeout expires.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2699 When a read or write event occurs, the <literal>ready</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2700 flag is set and the event's handler is called.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2701 For Linux, the <literal>ngx_epoll_process_events()</literal> handler
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2702 is normally used, which calls <literal>epoll_wait()</literal> to wait for I/O
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2703 events.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2704 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2705
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2706 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2707 Expire timers by calling <literal>ngx_event_expire_timers()</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2708 The timer tree is iterated from the leftmost element to the right until an
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2709 unexpired timeout is found.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2710 For each expired node the <literal>timedout</literal> event flag is set,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2711 the <literal>timer_set</literal> flag is reset, and the event handler is called
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2712 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2713
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2714 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2715 Process posted events by calling <literal>ngx_event_process_posted()</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2716 The function repeatedly removes the first element from the posted events
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2717 queue and calls the element's handler, until the queue is empty.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2718 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2719
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2720 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2721 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2722
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2723 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2724 All nginx processes handle signals as well.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2725 Signal handlers only set global variables which are checked after the
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2726 <literal>ngx_process_events_and_timers()</literal> call.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2727 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2728
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2729 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2730
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2731
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2732 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2733
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2734
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2735 <section name="Processes" id="processes">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2736
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2737 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2738 There are several types of processes in nginx.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2739 The type of a process is kept in the <literal>ngx_process</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2740 global variable, and is one of the following:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2741 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2742
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2743 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2744
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2745 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2746
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2747 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2748 <literal>NGX_PROCESS_MASTER</literal> — The master process, which reads the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2749 NGINX configuration, creates cycles, and starts and controls child processes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2750 It does not perform any I/O and responds only to signals.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2751 Its cycle function is <literal>ngx_master_process_cycle()</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2752 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2753
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2754
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2755 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2756
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2757 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2758
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2759 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2760 <literal>NGX_PROCESS_WORKER</literal> — The worker process, which handles client
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2761 connections.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2762 It is started by the master process and responds to its signals and channel
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2763 commands as well.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2764 Its cycle function is <literal>ngx_worker_process_cycle()</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2765 There can be multiple worker processes, as configured by the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2766 <literal>worker_processes</literal> directive.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2767 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2768
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2769 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2770
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2771 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2772
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2773 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2774 <literal>NGX_PROCESS_SINGLE</literal> — The single process, which exists only in
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2775 <literal>master_process off</literal> mode, and is the only process running in
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2776 that mode.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2777 It creates cycles (like the master process does) and handles client connections
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2778 (like the worker process does).
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2779 Its cycle function is <literal>ngx_single_process_cycle()</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2780 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2781
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2782 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2783
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2784 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2785
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2786 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2787 <literal>NGX_PROCESS_HELPER</literal> — The helper process, of which currently
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2788 there are two types: cache manager and cache loader.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2789 The cycle function for both is
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2790 <literal>ngx_cache_manager_process_cycle()</literal>.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2791 </para>
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 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2796
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2797 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2798 The nginx processes handle the following signals:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2799 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2800
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2801 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2802
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2803 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2804
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2805 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2806 <literal>NGX_SHUTDOWN_SIGNAL</literal> (<literal>SIGQUIT</literal> on most
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2807 systems) — Gracefully shutdown.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2808 Upon receiving this signal, the master process sends a shutdown signal to all
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2809 child processes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2810 When no child processes are left, the master destroys the cycle pool and exits.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2811 When a worker process receives this signal, it closes all listening sockets and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2812 waits until there are no non-cancelable events scheduled, then destroys the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2813 cycle pool and exits.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2814 When the cache manager or the cache loader process receives this signal, it
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2815 exits immediately.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2816 The <literal>ngx_quit</literal> variable is set to <literal>1</literal> when a
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2817 process receives this signal, and is immediately reset after being processed.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2818 The <literal>ngx_exiting</literal> variable is set to <literal>1</literal> while
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2819 a worker process is in the shutdown state.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2820 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2821
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2822 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2823
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2824 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2825
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2826 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2827 <literal>NGX_TERMINATE_SIGNAL</literal> (<literal>SIGTERM</literal> on most
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2828 systems) — Terminate.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2829 Upon receiving this signal, the master process sends a terminate signal to all
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2830 child processes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2831 If a child process does not exit within 1 second, the master process sends the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2832 <literal>SIGKILL</literal> signal to kill it.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2833 When no child processes are left, the master process destroys the cycle pool and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2834 exits.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2835 When a worker process, the cache manager process or the cache loader process
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2836 receives this signal, it destroys the cycle pool and exits.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2837 The variable <literal>ngx_terminate</literal> is set to <literal>1</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2838 when this signal is received.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2839 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2840
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2841 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2842
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2843 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2844
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2845 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2846 <literal>NGX_NOACCEPT_SIGNAL</literal> (<literal>SIGWINCH</literal> on most
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2847 systems) - Shut down all worker and helper processes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2848 Upon receiving this signal, the master process shuts down its child processes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2849 If a previously started new nginx binary exits, the child processes of the old
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2850 master are started again.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2851 When a worker process receives this signal, it shuts down in debug mode
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2852 set by the <literal>debug_points</literal> directive.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2853 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2854
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2855
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2856 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2857
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2858 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2859
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2860 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2861 <literal>NGX_RECONFIGURE_SIGNAL</literal> (<literal>SIGHUP</literal> on most
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2862 systems) - Reconfigure.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2863 Upon receiving this signal, the master process re-reads the configuration and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2864 creates a new cycle based on it.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2865 If the new cycle is created successfully, the old cycle is deleted and new
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2866 child processes are started.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2867 Meanwhile, the old child processes receive the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2868 <literal>NGX_SHUTDOWN_SIGNAL</literal> signal.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2869 In single-process mode, nginx creates a new cycle, but keeps the old one until
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2870 there are no longer clients with active connections tied to it.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2871 The worker and helper processes ignore this signal.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2872 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2873
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2874 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2875
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2876 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2877
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2878 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2879 <literal>NGX_REOPEN_SIGNAL</literal> (<literal>SIGUSR1</literal> on most
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2880 systems) — Reopen files.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2881 The master process sends this signal to workers, which reopen all
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2882 <literal>open_files</literal> related to the cycle.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2883 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2884
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2885 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2886
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2887 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2888
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2889 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2890 <literal>NGX_CHANGEBIN_SIGNAL</literal> (<literal>SIGUSR2</literal> on most
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2891 systems) — Change the nginx binary.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2892 The master process starts a new nginx binary and passes in a list of all listen
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2893 sockets.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2894 The text-format list, passed in the <literal>“NGINX”</literal> environment
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2895 variable, consists of descriptor numbers separated with semicolons.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2896 The new nginx binary reads the <literal>“NGINX”</literal> variable and adds the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2897 sockets to its init cycle.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2898 Other processes ignore this signal.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2899 </para>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2900
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2901 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2902
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2903 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2904
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2905 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2906 While all nginx worker processes are able to receive and properly handle POSIX
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2907 signals, the master process does not use the standard <literal>kill()</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2908 syscall to pass signals to workers and helpers.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2909 Instead, nginx uses inter-process socket pairs which allow sending messages
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2910 between all nginx processes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2911 Currently, however, messages are only sent from the master to its children.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2912 The messages carry the standard signals.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2913 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2914
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2915 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2916
1983 7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2917 <section name="Threads" id="threads">
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 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2920 It is possible to offload into a separate thread tasks that would otherwise
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2921 block the nginx worker process.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2922 For example, nginx can be configured to use threads to perform
1983 7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2923 <link doc="../http/ngx_http_core_module.xml" id="aio">file I/O</link>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2924 Another use case is a library that doesn't have asynchronous interface
1983 7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2925 and thus cannot be normally used with nginx.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2926 Keep in mind that the threads interface is a helper for the existing
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2927 asynchronous approach to processing client connections, and by no means
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2928 intended as a replacement.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2929 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2930
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2931 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2932 To deal with synchronization, the following wrappers over
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2933 <literal>pthreads</literal> primitives are available:
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2934
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2935 <list type="bullet">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2936
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2937 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2938 <literal>typedef pthread_mutex_t ngx_thread_mutex_t;</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2939
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2940 <list type="bullet">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2941
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2942 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2943 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2944 ngx_thread_mutex_create(ngx_thread_mutex_t mtx, ngx_log_t log);</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2945 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2946
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2947 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2948 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2949 ngx_thread_mutex_destroy(ngx_thread_mutex_t mtx, ngx_log_t log);</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2950 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2951
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2952 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2953 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2954 ngx_thread_mutex_lock(ngx_thread_mutex_t mtx, ngx_log_t log);</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2955 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2956
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2957 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2958 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2959 ngx_thread_mutex_unlock(ngx_thread_mutex_t mtx, ngx_log_t log);</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2960 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2961
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2962 </list>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2963
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2964 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2965
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2966 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2967 <literal>typedef pthread_cond_t ngx_thread_cond_t;</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2968
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2969 <list type="bullet">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2970
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2971 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2972 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2973 ngx_thread_cond_create(ngx_thread_cond_t cond, ngx_log_t log);</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2974 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2975
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2976 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2977 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2978 ngx_thread_cond_destroy(ngx_thread_cond_t cond, ngx_log_t log);</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2979 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2980
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2981 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2982 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2983 ngx_thread_cond_signal(ngx_thread_cond_t cond, ngx_log_t log);</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2984 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2985
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2986 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2987 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2988 ngx_thread_cond_wait(ngx_thread_cond_t cond, ngx_thread_mutex_t mtx,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2989 ngx_log_t *log);</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2990 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2991
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2992 </list>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2993
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2994 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2995
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2996 </list>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2997
1983 7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2998 </para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2999
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3000 <para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3001 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	3002 a <link doc="../ngx_core_module.xml" id="thread_pool"/> strategy.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3003 Multiple thread pools may be configured for different purposes
1983 7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3004 (for example, performing I/O on different sets of disks).
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3005 Each thread pool is created at startup and contains a limited number of threads
1983 7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3006 that process a queue of tasks.
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3007 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	3008 </para>
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 <para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3011 The <literal>src/core/ngx_thread_pool.h</literal> header file contains
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3012 relevant definitions:
1983 7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3013 <programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3014 struct ngx_thread_task_s {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3015 ngx_thread_task_t *next;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3016 ngx_uint_t id;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3017 void *ctx;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3018 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	3019 ngx_event_t event;
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 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	3023
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3024 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	3025 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	3026
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3027 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	3028 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	3029
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3030 </programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3031 At configuration time, a module willing to use threads has to obtain a
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3032 reference to a thread pool by calling
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3033 <literal>ngx_thread_pool_add(cf, name)</literal>, which either creates a
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3034 new thread pool with the given <literal>name</literal> or returns a reference
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3035 to the pool with that name if it already exists.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3036 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3037
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3038 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3039 To add a <literal>task</literal> into a queue of a specified thread pool
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3040 <literal>tp</literal> at runtime, use the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3041 <literal>ngx_thread_task_post(tp, task)</literal> function.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3042
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3043 To execute a function in a thread, pass parameters and setup a completion
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3044 handler using the <literal>ngx_thread_task_t</literal> structure:
1983 7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3045 <programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3046 typedef struct {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3047 int foo;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3048 } my_thread_ctx_t;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3049
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3050
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3051 static void
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3052 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	3053 {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3054 my_thread_ctx_t *ctx = data;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3055
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3056 /* 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	3057 }
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3058
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3059
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3060 static void
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3061 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	3062 {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3063 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	3064
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3065 /* executed in nginx event loop */
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3066 }
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3067
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3068
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3069 ngx_int_t
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3070 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	3071 {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3072 my_thread_ctx_t *ctx;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3073 ngx_thread_task_t *task;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3074
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3075 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	3076 if (task == NULL) {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3077 return NGX_ERROR;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3078 }
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3079
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3080 ctx = task->ctx;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3081
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3082 ctx->foo = 42;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3083
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3084 task->handler = my_thread_func;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3085 task->event.handler = my_thread_completion;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3086 task->event.data = ctx;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3087
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3088 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	3089 return NGX_ERROR;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3090 }
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3091
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3092 return NGX_OK;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3093 }
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3094 </programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3095
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3096 </para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3097
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3098 </section>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3099
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3100
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3101 <section name="Modules" id="Modules">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3102
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3103 <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	3104 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3105 Each standalone nginx module resides in a separate directory that contains
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3106 at least two files:
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3107 <literal>config</literal> and a file with the module source code.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3108 The <literal>config</literal> file contains all information needed for nginx to
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3109 integrate the module, for example:
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3110 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3111 ngx_module_type=CORE
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3112 ngx_module_name=ngx_foo_module
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3113 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	3114
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3115 . auto/module
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3116
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3117 ngx_addon_name=$ngx_module_name
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3118 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3119 The <literal>config</literal> file is a POSIX shell script that can set
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3120 and access the following variables:
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3121 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3122
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3123 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3124 <literal>ngx_module_type</literal> — Type of module to build.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3125 Possible values are <literal>CORE</literal>, <literal>HTTP</literal>,
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3126 <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	3127 <literal>HTTP_AUX_FILTER</literal>, <literal>MAIL</literal>,
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3128 <literal>STREAM</literal>, or <literal>MISC</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3129 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3130
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3131 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3132 <literal>ngx_module_name</literal> — Module names.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3133 To build multiple modules from a set of source files, specify a
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3134 whitespace-separated list of names.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3135 The first name indicates the name of the output binary for the dynamic module.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3136 The names in the list must match the names used in the source code.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3137 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3138
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3139 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3140 <literal>ngx_addon_name</literal> — Name of the module as it appears in output
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3141 on the console from the configure script.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3142 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3143
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3144 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3145 <literal>ngx_module_srcs</literal> — Whitespace-separated list of source
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3146 files used to compile the module.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3147 The <literal>$ngx_addon_dir</literal> variable can be used to represent the path
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3148 to the module directory.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3149 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3150
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3151 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3152 <literal>ngx_module_incs</literal> — Include paths required to build the module
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3153 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3154
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3155 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3156 <literal>ngx_module_deps</literal> — Whitespace-separated list of the module's
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3157 dependencies.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3158 Usually, it is the list of header files.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3159 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3160
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3161 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3162 <literal>ngx_module_libs</literal> — Whitespace-separated list of libraries to
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3163 link with the module.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3164 For example, use <literal>ngx_module_libs=-lpthread</literal> to link
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3165 <literal>libpthread</literal> library.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3166 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	3167 nginx:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3168 <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	3169 <literal>PCRE</literal>, <literal>OPENSSL</literal>, <literal>MD5</literal>,
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3170 <literal>SHA1</literal>, <literal>ZLIB</literal>, and <literal>PERL</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3171 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3172
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3173 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3174 <literal>ngx_module_link</literal> — Variable set by the build system to
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3175 <literal>DYNAMIC</literal> for a dynamic module or <literal>ADDON</literal>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3176 for a static module and used to determine different actions to perform
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3177 depending on linking type.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3178 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3179
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3180 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3181 <literal>ngx_module_order</literal> — Load order for the module;
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3182 useful for the <literal>HTTP_FILTER</literal> and
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3183 <literal>HTTP_AUX_FILTER</literal> module types.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3184 The format for this option is a whitespace-separated list of modules.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3185 All modules in the list following the current module's name end up after it in
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3186 the global list of modules, which sets up the order for modules initialization.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3187 For filter modules later initialization means earlier execution.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3188
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3189 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3190 The following modules are typically used as references.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3191 The <literal>ngx_http_copy_filter_module</literal> reads the data for other
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3192 filter modules and is placed near the bottom of the list so that it is one of
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3193 the first to be executed.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3194 The <literal>ngx_http_write_filter_module</literal> writes the data to the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3195 client socket and is placed near the top of the list, and is the last to be
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3196 executed.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3197 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3198
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3199 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3200 By default, filter modules are placed before the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3201 <literal>ngx_http_copy_filter</literal> in the module list so that the filter
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3202 handler is executed after the copy filter handler.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3203 For other module types the default is the empty string.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3204 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3205
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3206 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3207
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3208 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3209
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3210 To compile a module into nginx statically, use the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3211 <literal>--add-module=/path/to/module</literal> argument to the configure
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3212 script.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3213 To compile a module for later dynamic loading into nginx, use the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3214 <literal>--add-dynamic-module=/path/to/module</literal> argument.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3215 </para>
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 </section>
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
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3220 <section name="Core Modules" id="core_modules">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3221
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3222 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3223 Modules are the building blocks of nginx, and most of its functionality is
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3224 implemented as modules.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3225 The module source file must contain a global variable of type
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3226 <literal>ngx_module_t</literal>, which is defined as follows:
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3227 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3228 struct ngx_module_s {
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 /* private part is omitted */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3231
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3232 void *ctx;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3233 ngx_command_t *commands;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3234 ngx_uint_t type;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3235
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3236 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	3237
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3238 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	3239
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3240 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	3241 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	3242 void (exit_thread)(ngx_cycle_t cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3243 void (exit_process)(ngx_cycle_t cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3244
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3245 void (exit_master)(ngx_cycle_t cycle);
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 /* stubs for future extensions are omitted */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3248 };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3249 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3250 The omitted private part includes the module version and a signature and is
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3251 filled using the predefined macro <literal>NGX_MODULE_V1</literal>.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3252 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3253
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3254 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3255 Each module keeps its private data in the <literal>ctx</literal> field,
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3256 recognizes the configuration directives, specified in the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3257 <literal>commands</literal> array, and can be invoked at certain stages of
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3258 nginx lifecycle.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3259 The module lifecycle consists of the following events:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3260
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3261 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3262
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3263 <listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3264 Configuration directive handlers are called as they appear
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3265 in configuration files in the context of the master process.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3266 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3267
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3268 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3269 After the configuration is parsed successfully, <literal>init_module</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3270 handler is called in the context of the master process.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3271 The <literal>init_module</literal> handler is called in the master process each
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3272 time a configuration is loaded.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3273 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3274
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3275 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3276 The master process creates one or more worker processes and the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3277 <literal>init_process</literal> handler is called in each of them.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3278 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3279
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3280 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3281 When a worker process receives the shutdown or terminate command from the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3282 master, it invokes the <literal>exit_process</literal> handler.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3283 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3284
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3285 <listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3286 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	3287 exiting.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3288 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3289
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3290 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3291
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3292 Because threads are used in nginx only as a supplementary I/O facility with its
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3293 own API, <literal>init_thread</literal> and <literal>exit_thread</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3294 handlers are not currently called.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3295 There is also no <literal>init_master</literal> handler, because it would be
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3296 unnecessary overhead.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3297 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3298
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3299 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3300 The module <literal>type</literal> defines exactly what is stored in the
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3301 <literal>ctx</literal> field.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3302 Its value is one of the following types:
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3303 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3304 <listitem><literal>NGX_CORE_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3305 <listitem><literal>NGX_EVENT_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3306 <listitem><literal>NGX_HTTP_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3307 <listitem><literal>NGX_MAIL_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3308 <listitem><literal>NGX_STREAM_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3309 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3310 The <literal>NGX_CORE_MODULE</literal> is the most basic and thus the most
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3311 generic and most low-level type of module.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3312 The other module types are implemented on top of it and provide a more
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3313 convenient way to deal with corresponding domains, like handling events or HTTP
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3314 requests.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3315 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3316
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3317 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3318 The set of core modules includes <literal>ngx_core_module</literal>,
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3319 <literal>ngx_errlog_module</literal>, <literal>ngx_regex_module</literal>,
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3320 <literal>ngx_thread_pool_module</literal> and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3321 <literal>ngx_openssl_module</literal> modules.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3322 The HTTP module, the stream module, the mail module and event modules are core
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3323 modules too.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3324 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	3325 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3326 typedef struct {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3327 ngx_str_t name;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3328 void (create_conf)(ngx_cycle_t *cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3329 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	3330 } ngx_core_module_t;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3331 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3332 where the <literal>name</literal> is a module name string,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3333 <literal>create_conf</literal> and <literal>init_conf</literal>
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3334 are pointers to functions that create and initialize module configuration
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3335 respectively.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3336 For core modules, nginx calls <literal>create_conf</literal> before parsing
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3337 a new configuration and <literal>init_conf</literal> after all configuration
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3338 is parsed successfully.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3339 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	3340 configuration and sets default values.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3341 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3342
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3343 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3344 For example, a simplistic module called <literal>ngx_foo_module</literal> might
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3345 look like this:
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3346 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3347 /*
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3348 * Copyright (C) Author.
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
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3352 #include <ngx_config.h>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3353 #include <ngx_core.h>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3354
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3355
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3356 typedef struct {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3357 ngx_flag_t enable;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3358 } ngx_foo_conf_t;
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 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	3362 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	3363
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3364 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	3365 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	3366
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3367
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3368 static ngx_command_t ngx_foo_commands[] = {
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 { ngx_string("foo_enabled"),
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3371 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	3372 ngx_conf_set_flag_slot,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3373 0,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3374 offsetof(ngx_foo_conf_t, enable),
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3375 &ngx_foo_enable_post },
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3376
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3377 ngx_null_command
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3378 };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3379
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3380
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3381 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	3382 ngx_string("foo"),
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3383 ngx_foo_create_conf,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3384 ngx_foo_init_conf
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3385 };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3386
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3387
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3388 ngx_module_t ngx_foo_module = {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3389 NGX_MODULE_V1,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3390 &ngx_foo_module_ctx, /* module context */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3391 ngx_foo_commands, /* module directives */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3392 NGX_CORE_MODULE, /* module type */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3393 NULL, /* init master */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3394 NULL, /* init module */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3395 NULL, /* init process */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3396 NULL, /* init thread */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3397 NULL, /* exit thread */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3398 NULL, /* exit process */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3399 NULL, /* exit master */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3400 NGX_MODULE_V1_PADDING
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3401 };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3402
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3403
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3404 static void *
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3405 ngx_foo_create_conf(ngx_cycle_t *cycle)
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3406 {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3407 ngx_foo_conf_t *fcf;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3408
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3409 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	3410 if (fcf == NULL) {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3411 return NULL;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3412 }
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3413
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3414 fcf->enable = NGX_CONF_UNSET;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3415
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3416 return fcf;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3417 }
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3418
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3419
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3420 static char *
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3421 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	3422 {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3423 ngx_foo_conf_t *fcf = conf;
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 ngx_conf_init_value(fcf->enable, 0);
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 return NGX_CONF_OK;
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
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 static char *
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3432 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	3433 {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3434 ngx_flag_t *fp = data;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3435
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3436 if (*fp == 0) {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3437 return NGX_CONF_OK;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3438 }
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3439
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3440 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	3441
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3442 return NGX_CONF_OK;
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 </programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3445 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3446
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3447 </section>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3448
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3449
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3450 <section name="Configuration Directives" id="config_directives">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3451
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3452 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3453 The <literal>ngx_command_t</literal> type defines a single configuration
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3454 directive.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3455 Each module that supports configuration provides an array of such structures
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3456 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	3457 <programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3458 typedef struct ngx_command_s ngx_command_t;
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3459
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3460 struct ngx_command_s {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3461 ngx_str_t name;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3462 ngx_uint_t type;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3463 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	3464 ngx_uint_t conf;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3465 ngx_uint_t offset;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3466 void *post;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3467 };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3468 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3469 Terminate the array with the special value <literal>ngx_null_command</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3470 The <literal>name</literal> is the name of a directive as it appears
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3471 in the configuration file, for example "worker_processes" or "listen".
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3472 The <literal>type</literal> is a bit-field of flags that specify the number of
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3473 arguments the directive takes, its type, and the context in which it appears.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3474 The flags are:
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3475
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3476 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3477
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3478 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3479 <literal>NGX_CONF_NOARGS</literal> — Directive takes no arguments.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3480 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3481
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3482 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3483 <literal>NGX_CONF_1MORE</literal> — Directive takes one or more arguments.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3484 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3485
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3486 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3487 <literal>NGX_CONF_2MORE</literal> — Directive takes two or more arguments.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3488 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3489
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3490 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3491 <literal>NGX_CONF_TAKE1</literal>..<literal>NGX_CONF_TAKE7</literal> —
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3492 Directive takes exactly the indicated number of arguments.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3493 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3494
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3495 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3496 <literal>NGX_CONF_TAKE12</literal>, <literal>NGX_CONF_TAKE13</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3497 <literal>NGX_CONF_TAKE23</literal>, <literal>NGX_CONF_TAKE123</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3498 <literal>NGX_CONF_TAKE1234</literal> — Directive may take different number of
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3499 arguments.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3500 Options are limited to the given numbers.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3501 For example, <literal>NGX_CONF_TAKE12</literal> means it takes one or two
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3502 arguments.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3503 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3504
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3505 </list>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3506
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3507 The flags for directive types are:
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3508
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3509 <list type="bullet">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3510
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3511 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3512 <literal>NGX_CONF_BLOCK</literal> — Directive is a block, that is, it can
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3513 contain other directives within its opening and closing curly braces, or even
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3514 implement its own parser to handle contents inside.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3515 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3516
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3517 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3518 <literal>NGX_CONF_FLAG</literal> — Directive takes a boolean value, either
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3519 <literal>on</literal> or <literal>off</literal>.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3520 </listitem>
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 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3523
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3524 A directive's context defines where it may appear in the configuration:
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3525
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3526 <list type="bullet">
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>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3529 <literal>NGX_MAIN_CONF</literal> — In the top level context.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3530 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3531
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3532 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3533 <literal>NGX_HTTP_MAIN_CONF</literal> — In the <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3534 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3535
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3536 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3537 <literal>NGX_HTTP_SRV_CONF</literal> — In a <literal>server</literal> block
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3538 within the <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3539 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3540
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3541 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3542 <literal>NGX_HTTP_LOC_CONF</literal> — In a <literal>location</literal> block
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3543 within the <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3544 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3545
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3546 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3547 <literal>NGX_HTTP_UPS_CONF</literal> — In an <literal>upstream</literal> block
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3548 within the <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3549 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3550
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3551 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3552 <literal>NGX_HTTP_SIF_CONF</literal> — In an <literal>if</literal> block within
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3553 a <literal>server</literal> block in the <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3554 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3555
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3556 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3557 <literal>NGX_HTTP_LIF_CONF</literal> — In an <literal>if</literal> block within
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3558 a <literal>location</literal> block in the <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3559 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3560
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3561 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3562 <literal>NGX_HTTP_LMT_CONF</literal> — In a <literal>limit_except</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3563 block within the <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3564 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3565
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3566 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3567 <literal>NGX_STREAM_MAIN_CONF</literal> — In the <literal>stream</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3568 block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3569 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3570
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3571 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3572 <literal>NGX_STREAM_SRV_CONF</literal> — In a <literal>server</literal> block
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3573 within the <literal>stream</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3574 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3575
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3576 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3577 <literal>NGX_STREAM_UPS_CONF</literal> — In an <literal>upstream</literal> block
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3578 within the <literal>stream</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3579 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3580
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3581 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3582 <literal>NGX_MAIL_MAIN_CONF</literal> — In the <literal>mail</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3583 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3584
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3585 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3586 <literal>NGX_MAIL_SRV_CONF</literal> — In a <literal>server</literal> block
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3587 within the <literal>mail</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3588 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3589
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3590 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3591 <literal>NGX_EVENT_CONF</literal> — In the <literal>event</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3592 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3593
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3594 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3595 <literal>NGX_DIRECT_CONF</literal> — Used by modules that don't
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3596 create a hierarchy of contexts and only have one global configuration.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3597 This configuration is passed to the handler as the <literal>conf</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3598 argument.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3599 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3600 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3601
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3602 The configuration parser uses these flags to throw an error in case of
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3603 a misplaced directive and calls directive handlers supplied with a proper
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3604 configuration pointer, so that the same directives in different locations can
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3605 store their values in distinct places.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3606 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3607
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3608 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3609 The <literal>set</literal> field defines a handler that processes a directive
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3610 and stores parsed values into the corresponding configuration.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3611 There's a number of functions that perform common conversions:
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3612
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3613 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3614
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3615 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3616 <literal>ngx_conf_set_flag_slot</literal> — Converts the literal strings
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3617 <literal>on</literal> and <literal>off</literal> into an
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3618 <literal>ngx_flag_t</literal> value with values 1 or 0, respectively.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3619 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3620
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3621 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3622 <literal>ngx_conf_set_str_slot</literal> — Stores a string as a value of the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3623 <literal>ngx_str_t</literal> type.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3624 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3625
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3626 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3627 <literal>ngx_conf_set_str_array_slot</literal> — Appends a value to an array
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3628 <literal>ngx_array_t</literal> of strings <literal>ngx_str_t</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3629 The array is created if does not already exist.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3630 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3631
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3632 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3633 <literal>ngx_conf_set_keyval_slot</literal> — Appends a key-value pair to an
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3634 array <literal>ngx_array_t</literal> of key-value pairs
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3635 <literal>ngx_keyval_t</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3636 The first string becomes the key and the second the value.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3637 The array is created if it does not already exist.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3638 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3639
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3640 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3641 <literal>ngx_conf_set_num_slot</literal> — Converts a directive's argument
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3642 to an <literal>ngx_int_t</literal> value.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3643 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3644
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3645 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3646 <literal>ngx_conf_set_size_slot</literal> — Converts a
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3647 <link doc="../syntax.xml">size</link> to a <literal>size_t</literal> value
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3648 expressed in bytes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3649 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3650
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3651 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3652 <literal>ngx_conf_set_off_slot</literal> — Converts an
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3653 <link doc="../syntax.xml">offset</link> to an <literal>off_t</literal> value
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3654 expressed in bytes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3655 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3656
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3657 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3658 <literal>ngx_conf_set_msec_slot</literal> — Converts a
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3659 <link doc="../syntax.xml">time</link> to an <literal>ngx_msec_t</literal> value
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3660 expressed in milliseconds.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3661 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3662
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3663 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3664 <literal>ngx_conf_set_sec_slot</literal> — Converts a
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3665 <link doc="../syntax.xml">time</link> to a <literal>time_t</literal> value
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3666 expressed in in seconds.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3667 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3668
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3669 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3670 <literal>ngx_conf_set_bufs_slot</literal> — Converts the two supplied arguments
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3671 into an <literal>ngx_bufs_t</literal> object that holds the number and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3672 <link doc="../syntax.xml">size</link> of buffers.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3673 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3674
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3675 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3676 <literal>ngx_conf_set_enum_slot</literal> — Converts the supplied argument
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3677 into an <literal>ngx_uint_t</literal> value.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3678 The null-terminated array of <literal>ngx_conf_enum_t</literal> passed in the
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3679 <literal>post</literal> field defines the acceptable strings and corresponding
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3680 integer values.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3681 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3682
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3683 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3684 <literal>ngx_conf_set_bitmask_slot</literal> — Converts the supplied arguments
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3685 into an <literal>ngx_uint_t</literal> value.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3686 The mask values for each argument are ORed producing the result.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3687 The null-terminated array of <literal>ngx_conf_bitmask_t</literal> passed in the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3688 <literal>post</literal> field defines the acceptable strings and corresponding
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3689 mask values.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3690 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3691
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3692 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3693 <literal>set_path_slot</literal> — Converts the supplied arguments to an
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3694 <literal>ngx_path_t</literal> value and performs all required initializations.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3695 For details, see the documentation for the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3696 <link doc="../http/ngx_http_proxy_module.xml" id="proxy_temp_path">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3697 proxy_temp_path</link> directive.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3698 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3699
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3700 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3701 <literal>set_access_slot</literal> — Converts the supplied arguments to a file
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3702 permissions mask.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3703 For details, see the documentation for the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3704 <link doc="../http/ngx_http_proxy_module.xml" id="proxy_store_access">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3705 proxy_store_access</link> directive.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3706 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3707
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3708 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3709
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3710 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3711
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3712 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3713 The <literal>conf</literal> field defines which configuration structure is
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3714 passed to the directory handler.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3715 Core modules only have the global configuration and set
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3716 <literal>NGX_DIRECT_CONF</literal> flag to access it.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3717 Modules like HTTP, Stream or Mail create hierarchies of configurations.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3718 For example, a module's configuration is created for <literal>server</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3719 <literal>location</literal> and <literal>if</literal> scopes.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3720
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3721 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3722 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3723 <literal>NGX_HTTP_MAIN_CONF_OFFSET</literal> — Configuration for the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3724 <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3725 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3726
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3727 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3728 <literal>NGX_HTTP_SRV_CONF_OFFSET</literal> — Configuration for a
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3729 <literal>server</literal> block within the <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3730 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3731
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3732 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3733 <literal>NGX_HTTP_LOC_CONF_OFFSET</literal> — Configuration for a
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3734 <literal>location</literal> block within the <literal>http</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3735 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3736
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3737 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3738 <literal>NGX_STREAM_MAIN_CONF_OFFSET</literal> — Configuration for the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3739 <literal>stream</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3740 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3741
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3742 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3743 <literal>NGX_STREAM_SRV_CONF_OFFSET</literal> — Configuration for a
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3744 <literal>server</literal> block within the <literal>stream</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3745 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3746
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3747 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3748 <literal>NGX_MAIL_MAIN_CONF_OFFSET</literal> — Configuration for the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3749 <literal>mail</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3750 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3751
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3752 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3753 <literal>NGX_MAIL_SRV_CONF_OFFSET</literal> — Configuration for a
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3754 <literal>server</literal> block within the <literal>mail</literal> block.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3755 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3756
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3757 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3758
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3759 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3760
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3761 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3762 The <literal>offset</literal> defines the offset of a field in a module
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3763 configuration structure that holds values for this particular directive.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3764 The typical use is to employ the <literal>offsetof()</literal> macro.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3765 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3766
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3767 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3768 The <literal>post</literal> field has two purposes: it may be used to define
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3769 a handler to be called after the main handler has completed, or to pass
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3770 additional data to the main handler.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3771 In the first case, the <literal>ngx_conf_post_t</literal> structure needs to
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3772 be initialized with a pointer to the handler, for example:
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3773 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3774 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	3775 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	3776 </programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3777 The <literal>post</literal> argument is the <literal>ngx_conf_post_t</literal>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3778 object itself, and the <literal>data</literal> is a pointer to the value,
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3779 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	3780 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3781
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3782 </section>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3783
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3784 </section>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3785
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3786
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3787 <section name="HTTP" id="http">
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
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3790 <section name="Connection" id="http_connection">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3791
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3792 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3793 Each HTTP client connection runs through the following stages:
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3794 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3795
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3796 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3797
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3798 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3799 <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	3800 This handler is called in response to a read notification on a listen socket.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3801 A new <literal>ngx_connecton_t</literal> object is created at this stage
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3802 to wrap the newly accepted client socket.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3803 Each nginx listener provides a handler to pass the new connection object to.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3804 For HTTP connections it's <literal>ngx_http_init_connection(c)</literal>.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3805 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3806
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3807 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3808 <literal>ngx_http_init_connection()</literal> performs early initialization of
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3809 the HTTP connection.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3810 At this stage an <literal>ngx_http_connection_t</literal> object is created for
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3811 the connection and its reference is stored in the connection's
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3812 <literal>data</literal> field.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3813 Later it will be replaced by an HTTP request object.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3814 A PROXY protocol parser and the SSL handshake are started at
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3815 this stage as well.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3816 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3817
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3818 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3819 <literal>ngx_http_wait_request_handler()</literal> read event handler
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3820 is called when data is available on the client socket.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3821 At this stage an HTTP request object <literal>ngx_http_request_t</literal> is
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3822 created and set to the connection's <literal>data</literal> field.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3823 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3824
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3825 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3826 <literal>ngx_http_process_request_line()</literal> read event handler
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3827 reads client request line.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3828 The handler is set by <literal>ngx_http_wait_request_handler()</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3829 The data is read into connection's <literal>buffer</literal>.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3830 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	3831 <link doc="../http/ngx_http_core_module.xml" id="client_header_buffer_size"/>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3832 The entire client header is supposed to fit in the buffer.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3833 If the initial size is not sufficient, a bigger buffer is allocated,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3834 with the capacity set by the <literal>large_client_header_buffers</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3835 directive.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3836 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3837
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3838 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3839 <literal>ngx_http_process_request_headers()</literal> read event handler,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3840 is set after <literal>ngx_http_process_request_line()</literal> to read
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3841 the client request header.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3842 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3843
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3844 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3845 <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	3846 is completely read and parsed.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3847 This function runs request phases from
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3848 <literal>NGX_HTTP_POST_READ_PHASE</literal> to
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3849 <literal>NGX_HTTP_CONTENT_PHASE</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3850 The last phase is intended to generate a response and pass it along the filter
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3851 chain.
1979 ff28ca78bef3 Fixed a typo. Vladimir Homutov <vl@nginx.com> parents: 1976 diff changeset	3852 The response is not necessarily sent to the client at this phase.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3853 It might remain buffered and be sent at the finalization stage.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	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>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3857 <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	3858 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	3859 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	3860 response.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3861 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	3862 HTTP writer <literal>ngx_http_writer()</literal> is activated to finish
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3863 sending outstanding data.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3864 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3865
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3866 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3867 <literal>ngx_http_finalize_connection()</literal> is called when the complete
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3868 response has been sent to the client and the request can be destroyed.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3869 If the client connection keepalive feature is enabled,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3870 <literal>ngx_http_set_keepalive()</literal> is called, which destroys the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3871 current request and waits for the next request on the connection.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3872 Otherwise, <literal>ngx_http_close_request()</literal> destroys both the
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3873 request and the connection.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3874 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3875
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3876 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3877
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3878 </section>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3879
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3880
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3881 <section name="Request" id="http_request">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3882
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3883 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3884 For each client HTTP request the <literal>ngx_http_request_t</literal> object is
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3885 created. Some of the fields of this object are:
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3886 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3887
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3888 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3889
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3890 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3891
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3892 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3893 <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	3894 client connection object.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3895 Several requests can reference the same connection object at the same time -
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3896 one main request and its subrequests.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3897 After a request is deleted, a new request can be created on the same connection.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3898 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3899
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3900 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3901 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	3902 <literal>data</literal> field points back to the request.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3903 Such requests are called active, as opposed to the other requests tied to the
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3904 connection.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3905 An active request is used to handle client connection events and is allowed to
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3906 output its response to the client.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3907 Normally, each request becomes active at some point so that it can send its
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3908 output.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3909 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3910
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3911 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3912
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3913 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3914
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3915 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3916 <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	3917 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	3918 (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	3919 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	3920 <literal>ctx_index</literal> position.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3921 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	3922 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3923
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3924 <list type="bullet">
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>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3927 <literal>ngx_http_get_module_ctx(r, module)</literal> — Returns
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3928 the <literal>module</literal>'s context
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3929 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3930
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3931 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3932 <literal>ngx_http_set_ctx(r, c, module)</literal> — Sets <literal>c</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3933 as the <literal>module</literal>'s context
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3934 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3935
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3936 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3937
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3938 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3939
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3940 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3941 <literal>main_conf</literal>, <literal>srv_conf</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3942 <literal>loc_conf</literal> — Arrays of current request
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3943 configurations.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3944 Configurations are stored at the module's <literal>ctx_index</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3945 positions.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3946 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3947
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3948 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3949 <literal>read_event_handler</literal>, <literal>write_event_handler</literal> -
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3950 Read and write event handlers for the request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3951 Normally, both the read and write event handlers for an HTTP connection
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3952 are set to <literal>ngx_http_request_handler()</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3953 This function calls the <literal>read_event_handler</literal> and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3954 <literal>write_event_handler</literal> handlers for the currently
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3955 active request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3956 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3957
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3958 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3959 <literal>cache</literal> — Request cache object for caching the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3960 upstream response.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3961 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3962
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3963 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3964 <literal>upstream</literal> — Request upstream object for proxying.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3965 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3966
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3967 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3968 <literal>pool</literal> — Request pool.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3969 The request object itself is allocated in this pool, which is destroyed when
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3970 the request is deleted.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3971 For allocations that need to be available throughout the client connection's
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3972 lifetime, use <literal>ngx_connection_t</literal>'s pool instead.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3973 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3974
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3975 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3976 <literal>header_in</literal> — Buffer into which the client HTTP request
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3977 header is read.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3978 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3979
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3980 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3981 <literal>headers_in</literal>, <literal>headers_out</literal> — Input and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3982 output HTTP headers objects.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3983 Both objects contain the <literal>headers</literal> field of type
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3984 <literal>ngx_list_t</literal> for keeping the raw list of headers.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3985 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	3986 separate fields, for example <literal>content_length_n</literal>,
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3987 <literal>status</literal> etc.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3988 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3989
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3990 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3991 <literal>request_body</literal> — Client request body object.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3992 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3993
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3994 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3995 <literal>start_sec</literal>, <literal>start_msec</literal> — Time point when
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3996 the request was created, used for tracking request duration.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3997 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3998
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3999 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4000 <literal>method</literal>, <literal>method_name</literal> — Numeric and text
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4001 representation of the client HTTP request method.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4002 Numeric values for methods are defined in
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4003 <literal>src/http/ngx_http_request.h</literal> with the macros
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4004 <literal>NGX_HTTP_GET</literal>, <literal>NGX_HTTP_HEAD</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4005 <literal>NGX_HTTP_POST</literal>, etc.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4006 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4007
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4008 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4009 <literal>http_protocol</literal> — Client HTTP protocol version in its
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4010 original text form (“HTTP/1.0”, “HTTP/1.1” etc).
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4011 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4012
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4013 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4014 <literal>http_version</literal> — Client HTTP protocol version in
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4015 numeric form (<literal>NGX_HTTP_VERSION_10</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4016 <literal>NGX_HTTP_VERSION_11</literal>, etc.).
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4017 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4018
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4019 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4020 <literal>http_major</literal>, <literal>http_minor</literal> — Client HTTP
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4021 protocol version in numeric form split into major and minor parts.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4022 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4023
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4024 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4025 <literal>request_line</literal>, <literal>unparsed_uri</literal> — Request line
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4026 and URI in the original client request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4027 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4028
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4029 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4030 <literal>uri</literal>, <literal>args</literal>, <literal>exten</literal> —
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4031 URI, arguments and file extension for the current request.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4032 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	4033 normalization.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4034 Throughout request processing, these values can change as internal redirects
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4035 are performed.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4036 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4037
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4038 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4039 <literal>main</literal> — Pointer to a main request object.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4040 This object is created to process a client HTTP request, as opposed to
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4041 subrequests, which are created to perform a specific subtask within the main
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4042 request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4043 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4044
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4045 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4046 <literal>parent</literal> — Pointer to the parent request of a subrequest.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4047 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4048
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4049 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4050 <literal>postponed</literal> — List of output buffers and subrequests, in the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4051 order in which they are sent and created.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4052 The list is used by the postpone filter to provide consistent request output
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4053 when parts of it are created by subrequests.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4054 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4055
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4056 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4057 <literal>post_subrequest</literal> — Pointer to a handler with the context
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4058 to be called when a subrequest gets finalized.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4059 Unused for main requests.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4060 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4061
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4062 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4063
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4064 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4065 <literal>posted_requests</literal> — List of requests to be started or
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4066 resumed, which is done by calling the request's
1932 937e03180281 Fixed trailing spaces. Vladimir Homutov <vl@nginx.com> parents: 1929 diff changeset	4067 <literal>write_event_handler</literal>.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4068 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	4069 request phases and then produces the output.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4070 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4071
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4072 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4073 A request is usually posted by the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4074 <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	4075 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	4076 The function <literal>ngx_http_run_posted_requests(c)</literal> runs all
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4077 requests that are posted in the main request of the passed
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4078 connection's active request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4079 All event handlers call <literal>ngx_http_run_posted_requests</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4080 which can lead to new posted requests.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4081 Normally, it is called after invoking a request's read or write handler.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4082 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4083
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4084 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4085
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4086 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4087 <literal>phase_handler</literal> — Index of current request phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4088 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4089
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4090 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4091 <literal>ncaptures</literal>, <literal>captures</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4092 <literal>captures_data</literal> — Regex captures produced
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4093 by the last regex match of the request.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4094 A regex match can occur at a number of places during request processing:
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4095 map lookup, server lookup by SNI or HTTP Host, rewrite, proxy_redirect, etc.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4096 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	4097 The field <literal>ncaptures</literal> holds the number of captures,
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4098 <literal>captures</literal> holds captures boundaries and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4099 <literal>captures_data</literal> holds the string against which the regex was
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4100 matched and which is used to extract captures.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4101 After each new regex match, request captures are reset to hold new values.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4102 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4103
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4104 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4105 <literal>count</literal> — Request reference counter.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4106 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	4107 Increasing the counter is done by simple <literal>r->main->count++</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4108 To decrease the counter, call
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4109 <literal>ngx_http_finalize_request(r, rc)</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4110 Creating of a subrequest and running the request body read process both
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4111 increment the counter.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4112 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4113
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4114 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4115 <literal>subrequests</literal> — Current subrequest nesting level.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4116 Each subrequest inherits its parent's nesting level, decreased by one.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4117 An error is generated if the value reaches zero.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4118 The value for the main request is defined by the
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4119 <literal>NGX_HTTP_MAX_SUBREQUESTS</literal> constant.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4120 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4121
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4122 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4123 <literal>uri_changes</literal> — Number of URI changes remaining for
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4124 the request.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4125 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	4126 <literal>NGX_HTTP_MAX_URI_CHANGES</literal> constant.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4127 With each change the value is decremented until it reaches zero, at which time
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4128 an error is generated.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4129 Rewrites and internal redirects to normal or named locations are considered URI
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4130 changes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4131 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4132
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4133 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4134 <literal>blocked</literal> — Counter of blocks held on the request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4135 While this value is non-zero, the request cannot be terminated.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4136 Currently, this value is increased by pending AIO operations (POSIX AIO and
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4137 thread operations) and active cache lock.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4138 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4139
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4140 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4141 <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	4142 output produced by the request.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4143 A number of filters can buffer output; for example, sub_filter can buffer data
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4144 because of a partial string match, copy filter can buffer data because of the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4145 lack of free output buffers etc.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4146 As long as this value is non-zero, the request is not finalized
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4147 pending the flush.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4148 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4149
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4150 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4151 <literal>header_only</literal> — Flag indicating that the output does not
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4152 require a body.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4153 For example, this flag is used by HTTP HEAD requests.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4154 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4155
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4156 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4157 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4158 <literal>keepalive</literal> — Flag indicating whether client connection
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4159 keepalive is supported.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4160 The value is inferred from the HTTP version and the value of the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4161 <header>Connection</header> header.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4162 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4163 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4164
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4165 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4166 <literal>header_sent</literal> — Flag indicating that the output header
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4167 has already been sent by the request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4168 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4169
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4170 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4171 <literal>internal</literal> — Flag indicating that the current request
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4172 is internal.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4173 To enter the internal state, a request must pass through an internal
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4174 redirect or be a subrequest.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4175 Internal requests are allowed to enter internal locations.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4176 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4177
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4178 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4179 <literal>allow_ranges</literal> — Flag indicating that a partial response
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4180 can be sent to the client, as requested by the HTTP Range header.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4181 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4182
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4183 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4184 <literal>subrequest_ranges</literal> — Flag indicating that a partial response
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4185 can be sent while a subrequest is being processed.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4186 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4187
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4188 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4189 <literal>single_range</literal> — Flag indicating that only a single continuous
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4190 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	4191 This flag is usually set when sending a stream of data, for example from a
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4192 proxied server, and the entire response is not available in one buffer.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4193 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4194
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4195 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4196 <literal>main_filter_need_in_memory</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4197 <literal>filter_need_in_memory</literal> — Flags
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4198 requesting that the output produced in memory buffers rather than files.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4199 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	4200 sendfile is enabled.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4201 The difference between the two flags is the location of the filter modules that
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4202 set them.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4203 Filters called before the postpone filter in the filter chain set
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4204 <literal>filter_need_in_memory</literal>, requesting that only the current
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4205 request output come in memory buffers.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4206 Filters called later in the filter chain set
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4207 <literal>main_filter_need_in_memory</literal>, requesting that
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4208 both the main request and all subrequests read files in memory
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4209 while sending output.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4210 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4211
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4212 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4213 <literal>filter_need_temporary</literal> — Flag requesting that the request
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4214 output be produced in temporary buffers, but not in readonly memory buffers or
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4215 file buffers.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4216 This is used by filters which may change output directly in the buffers where
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4217 it's sent.</listitem>
1929 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>
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 </section>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4222
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4223
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4224 <section name="Configuration" id="http_conf">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4225
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4226 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4227 Each HTTP module can have three types of configuration:
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4228 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4229
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4230 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4231
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4232 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4233 Main configuration — Applies to the entire <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4234 Functions as global settings for a module.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4235 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4236
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4237 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4238 Server configuration — Applies to a single <literal>server</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4239 Functions as server-specific settings for a module.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4240 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4241
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4242 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4243 Location configuration — Applies to a single <literal>location</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4244 <literal>if</literal> or <literal>limit_except</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4245 Functions as location-specific settings for a module.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4246 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4247
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4248 </list>
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 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4251 Configuration structures are created at the nginx configuration stage by
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4252 calling functions, which allocate the structures, initialize them
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4253 and merge them.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4254 The following example shows how to create a simple location
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4255 configuration for a module.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4256 The configuration has one setting, <literal>foo</literal>, of type
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4257 unsigned integer.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4258 </para>
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 <programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4261 typedef struct {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4262 ngx_uint_t foo;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4263 } ngx_http_foo_loc_conf_t;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4264
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 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	4267 NULL, /* preconfiguration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4268 NULL, /* postconfiguration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4269
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4270 NULL, /* create main configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4271 NULL, /* init main configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4272
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4273 NULL, /* create server configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4274 NULL, /* merge server configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4275
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4276 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	4277 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	4278 };
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
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4281 static void *
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4282 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	4283 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4284 ngx_http_foo_loc_conf_t *conf;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4285
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4286 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	4287 if (conf == NULL) {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4288 return NULL;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4289 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4290
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4291 conf->foo = NGX_CONF_UNSET_UINT;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4292
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4293 return conf;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4294 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4295
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4296
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4297 static char *
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4298 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	4299 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4300 ngx_http_foo_loc_conf_t *prev = parent;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4301 ngx_http_foo_loc_conf_t *conf = child;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4302
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4303 ngx_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	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
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4307 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4308 As seen in the example, the <literal>ngx_http_foo_create_loc_conf()</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4309 function creates a new configuration structure, and
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4310 <literal>ngx_http_foo_merge_loc_conf()</literal> merges a configuration with
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4311 configuration from a higher level.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4312 In fact, server and location configuration do not exist only at the server and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4313 location levels, but are also created for all levels above them.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4314 Specifically, a server configuration is also created at the main level and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4315 location configurations are created at the main, server, and location levels.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4316 These configurations make it possible to specify server- and location-specific
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4317 settings at any level of an nginx configuration file.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4318 Eventually configurations are merged down.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4319 A number of macros like <literal>NGX_CONF_UNSET</literal> and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4320 <literal>NGX_CONF_UNSET_UINT</literal> are provided
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4321 for indicating a missing setting and ignoring it while merging.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4322 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	4323 <literal>ngx_conf_merge_uint_value()</literal> provide a convenient way to
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4324 merge a setting and set the default value if none of the configurations
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4325 provided an explicit value.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4326 For complete list of macros for different types, see
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4327 <literal>src/core/ngx_conf_file.h</literal>.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4328 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4329
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4330 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4331 The following macros are available.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4332 for accessing configuration for HTTP modules at configuration time.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4333 They all take <literal>ngx_conf_t</literal> reference as the first argument.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4334 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4335
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4336 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4337
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4338 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4339 <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	4340 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4341
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4342 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4343 <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	4344 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4345
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4346 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4347 <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	4348 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4349
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4350 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4351
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4352 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4353 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	4354 standard nginx core module
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4355 <link doc="../http/ngx_http_core_module.xml">ngx_http_core_module</link>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4356 and replaces the location content handler kept
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4357 in the <literal>handler</literal> field of the structure.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4358 </para>
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 <programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4361 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	4362
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4363
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4364 static ngx_command_t ngx_http_foo_commands[] = {
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 { ngx_string("foo"),
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4367 NGX_HTTP_LOC_CONF\|NGX_CONF_NOARGS,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4368 ngx_http_foo,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4369 0,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4370 0,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4371 NULL },
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4372
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4373 ngx_null_command
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4374 };
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4375
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4376
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4377 static char *
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4378 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	4379 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4380 ngx_http_core_loc_conf_t *clcf;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4381
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4382 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	4383 clcf->handler = ngx_http_bar_handler;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4384
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4385 return NGX_CONF_OK;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4386 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4387 </programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4388
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4389 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4390 The following macros are available for accessing configuration for HTTP
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4391 modules at runtime.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4392 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4393
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4394 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4395
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4396 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4397 <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	4398 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4399
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4400 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4401 <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	4402 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4403
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 <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	4406 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4407
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4408 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4409
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4410 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4411 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	4412 <literal>ngx_http_request_t</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4413 The main configuration of a request never changes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4414 Server configuration can change from the default after
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4415 the virtual server for the request is chosen.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4416 Location configuration selected for processing a request can change multiple
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4417 times as a result of a rewrite operation or internal redirect.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4418 The following example shows how to access a module's HTTP configuration at
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4419 runtime.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4420 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4421
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4422 <programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4423 static ngx_int_t
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4424 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	4425 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4426 ngx_http_foo_loc_conf_t *flcf;
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 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	4429
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4430 ...
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4431 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4432 </programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4433
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4434 </section>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4435
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4436
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4437 <section name="Phases" id="http_phases">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4438
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4439 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4440 Each HTTP request passes through a sequence of phases.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4441 In each phase a distinct type of processing is performed on the request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4442 Module-specific handlers can be registered in most phases,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4443 and many standard nginx modules register their phase handlers as a way
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4444 to get called at a specific stage of request processing.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4445 Phases are processed successively and the phase handlers are called
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4446 once the request reaches the phase.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4447 Following is the list of nginx HTTP phases.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4448 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4449
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4450 <list type="bullet">
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 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4453 <literal>NGX_HTTP_POST_READ_PHASE</literal> — First phase.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4454 The <link doc="../http/ngx_http_realip_module.xml">ngx_http_realip_module</link>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4455 registers its handler at this phase to enable
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4456 substitution of client addresses before any other module is invoked.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4457 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4458
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4459 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4460 <literal>NGX_HTTP_SERVER_REWRITE_PHASE</literal> — Phase where
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4461 rewrite directives defined in a <literal>server</literal> block
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4462 (but outside a <literal>location</literal> block) are processed.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4463 The
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4464 <link doc="../http/ngx_http_rewrite_module.xml">ngx_http_rewrite_module</link>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4465 installs its handler at this phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4466 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4467
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4468 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4469 <literal>NGX_HTTP_FIND_CONFIG_PHASE</literal> — Special phase
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4470 where a location is chosen based on the request URI.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4471 Before this phase, the default location for the relevant virtual server
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4472 is assigned to the request, and any module requesting a location configuration
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4473 receives the configuration for the default server location.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4474 This phase a assigns a new location to the request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4475 No additional handlers can be registered at this phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4476 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4477
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4478 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4479 <literal>NGX_HTTP_REWRITE_PHASE</literal> — Same as
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4480 <literal>NGX_HTTP_SERVER_REWRITE_PHASE</literal>, but for
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4481 rewrite rules defined in the location, chosen in the previous phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4482 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4483
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4484 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4485 <literal>NGX_HTTP_POST_REWRITE_PHASE</literal> — Special phase
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4486 where the request is redirected to a new location if its URI changed
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4487 during a rewrite.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4488 This is implemented by the request going through
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4489 the <literal>NGX_HTTP_FIND_CONFIG_PHASE</literal> again.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4490 No additional handlers can be registered at this phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4491 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4492
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4493 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4494 <literal>NGX_HTTP_PREACCESS_PHASE</literal> — A common phase for different
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4495 types of handlers, not associated with access control.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4496 The standard nginx modules
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4497 <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	4498 </link> and
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4499 <link doc="../http/ngx_http_limit_req_module.xml">
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4500 ngx_http_limit_req_module</link> register their handlers at this phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4501 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4502
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4503 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4504 <literal>NGX_HTTP_ACCESS_PHASE</literal> — Phase where it is verified
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4505 that the client is authorized to make the request.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4506 Standard nginx modules such as
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4507 <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	4508 <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	4509 </link> register their handlers at this phase.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4510 By default the client must pass the authorization check of all handlers
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4511 registered at this phase for the request to continue to the next phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4512 The <link doc="../http/ngx_http_core_module.xml" id="satisfy"/> directive,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4513 can be used to permit processing to continue if any of the phase handlers
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4514 authorizes the client.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4515 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4516
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4517 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4518 <literal>NGX_HTTP_POST_ACCESS_PHASE</literal> — Special phase where the
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4519 <link doc="../http/ngx_http_core_module.xml" id="satisfy">satisfy any</link>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4520 directive is processed.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4521 If some access phase handlers denied access and none explictly allowed it, the
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4522 request is finalized.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4523 No additional handlers can be registered at this phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4524 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4525
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4526 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4527 <literal>NGX_HTTP_TRY_FILES_PHASE</literal> — Special phase where
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4528 the <link doc="../http/ngx_http_core_module.xml" id="try_files"/> directive
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4529 is processed.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4530 No additional handlers can be registered at this phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4531 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4532
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4533 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4534 <literal>NGX_HTTP_CONTENT_PHASE</literal> — Phase where the response
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4535 is normally generated.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4536 Multiple nginx standard modules register their handlers at this phase,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4537 including
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4538 <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	4539 <literal>ngx_http_static_module</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4540 They are called sequentially until one of them produces
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4541 the output.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4542 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	4543 If the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4544 <link doc="../http/ngx_http_core_module.xml">ngx_http_core_module</link>'s
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4545 location configuration has <literal>handler</literal> set, it is
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4546 called as the content handler and the handlers installed at this phase
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4547 are ignored.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4548 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4549
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4550 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4551 <literal>NGX_HTTP_LOG_PHASE</literal> — Phase where request logging
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4552 is performed.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4553 Currently, only the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4554 <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	4555 registers its handler
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4556 at this stage for access logging.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4557 Log phase handlers are called at the very end of request processing, right
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4558 before freeing the request.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4559 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4560
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4561 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4562
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4563 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4564 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	4565 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4566
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4567 <programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4568 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	4569 NULL, /* preconfiguration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4570 ngx_http_foo_init, /* postconfiguration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4571
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4572 NULL, /* create main configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4573 NULL, /* init main configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4574
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4575 NULL, /* create server configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4576 NULL, /* merge server configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4577
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4578 NULL, /* create location configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4579 NULL /* merge location configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4580 };
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4581
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4582
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4583 static ngx_int_t
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4584 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	4585 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4586 ngx_str_t *ua;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4587
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4588 ua = r->headers_in->user_agent;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4589
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4590 if (ua == NULL) {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4591 return NGX_DECLINED;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4592 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4593
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4594 /* reject requests with "User-Agent: foo" */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4595 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	4596 return NGX_HTTP_FORBIDDEN;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4597 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4598
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4599 return NGX_DECLINED;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4600 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4601
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4602
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4603 static ngx_int_t
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4604 ngx_http_foo_init(ngx_conf_t *cf)
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4605 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4606 ngx_http_handler_pt *h;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4607 ngx_http_core_main_conf_t *cmcf;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4608
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4609 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	4610
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4611 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	4612 if (h == NULL) {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4613 return NGX_ERROR;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4614 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4615
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4616 *h = ngx_http_foo_handler;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4617
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4618 return NGX_OK;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4619 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4620 </programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4621
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4622 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4623 Phase handlers are expected to return specific codes:
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4624 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4625
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4626 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4627
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4628 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4629 <literal>NGX_OK</literal> — Proceed to the next phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4630 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4631
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4632 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4633 <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	4634 phase.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4635 If the current handler is the last in the current phase,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4636 move to the next phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4637 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4638
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4639 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4640 <literal>NGX_AGAIN</literal>, <literal>NGX_DONE</literal> — Suspend
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4641 phase handling until some future event which can be
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4642 an asynchronous I/O operation or just a delay, for example.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4643 It is assumed, that phase handling will be resumed later by calling
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4644 <literal>ngx_http_core_run_phases()</literal>.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4645 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4646
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4647 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4648 Any other value returned by the phase handler is treated as a request
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4649 finalization code, in particular, an HTTP response code.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4650 The request is finalized with the code provided.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4651 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4652
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4653 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4654
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4655 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4656 For some phases, return codes are treated in a slightly different way.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4657 At the content phase, any return code other that
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4658 <literal>NGX_DECLINED</literal> is considered a finalization code.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4659 Any return code from the location content handlers is considered a
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4660 finalization code.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4661 At the access phase, in
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4662 <link doc="../http/ngx_http_core_module.xml" id="satisfy">satisfy any</link>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4663 mode,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4664 any return code other than <literal>NGX_OK</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4665 <literal>NGX_DECLINED</literal>, <literal>NGX_AGAIN</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4666 <literal>NGX_DONE</literal> is considered a denial.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4667 If no subsequent access handlers allow or deny access with a different
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4668 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	4669 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4670
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4671 </section>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4672
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	4673
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4674 <section name="Variables" id="http_variables">
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4675
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4676 <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	4677
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4678 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4679 Variables can be referenced by index (this is the most common method)
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4680 or name (see <link id="http_creating_variables">below</link>).
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4681 The index is created at configuration stage, when a variable is added
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4682 to the configuration.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4683 To obtain the variable index, use
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4684 <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	4685 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4686 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	4687 ngx_int_t index;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4688
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4689 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	4690 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4691 Here, <literal>cf</literal> is a pointer to nginx configuration and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4692 <literal>name</literal> points to a string containing the variable name.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4693 The function returns <literal>NGX_ERROR</literal> on error or a valid index
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4694 otherwise, which is typically stored somewhere in the module's
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4695 configuration for future use.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4696 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4697
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4698 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4699 All HTTP variables are evaluated in the context of a given HTTP request,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4700 and results are specific to and cached in that HTTP request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4701 All functions that evaluate variables return the
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4702 <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	4703 the variable value:
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4704 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4705 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	4706
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4707 typedef struct {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4708 unsigned len:28;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4709
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4710 unsigned valid:1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4711 unsigned no_cacheable:1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4712 unsigned not_found:1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4713 unsigned escape:1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4714
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4715 u_char *data;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4716 } ngx_variable_value_t;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4717 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4718 where:
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4719 <list type="bullet">
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4720
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4721 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4722 <literal>len</literal> — The length of the value
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4723 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4724
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4725 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4726 <literal>data</literal> — The value itself
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4727 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4728
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4729 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4730 <literal>valid</literal> — The value is valid
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4731 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4732
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4733 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4734 <literal>not_found</literal> — The variable was not found and thus
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4735 the <literal>data</literal> and <literal>len</literal> fields are irrelevant;
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4736 this can happen, for example, with variables like <var>$arg_foo</var>
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4737 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	4738 </listitem>
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 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4741 <literal>no_cacheable</literal> — Do not cache result
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4742 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4743
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4744 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4745 <literal>escape</literal> — Used internally by the logging module to mark
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4746 values that require escaping on output.
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4747 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4748
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4749 </list>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4750 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4751
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4752 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4753 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	4754 and <literal>ngx_http_get_indexed_variable()</literal> functions
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4755 are used to obtain the value of a variable.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4756 They have the same interface - accepting an HTTP request <literal>r</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4757 as a context for evaluating the variable and an <literal>index</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4758 that identifies it.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4759 An example of typical usage:
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4760 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4761 ngx_http_variable_value_t *v;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4762
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4763 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	4764
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4765 if (v == NULL \|\| v->not_found) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4766 /* 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	4767 return NGX_ERROR;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4768 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4769
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4770 /* some meaningful value is found */
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4771 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4772 The difference between functions is that the
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4773 <literal>ngx_http_get_indexed_variable()</literal> returns a cached value
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4774 and <literal>ngx_http_get_flushed_variable()</literal> flushes the cache for
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4775 non-cacheable variables.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4776 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4777
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4778 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4779 Some modules, such as SSI and Perl, need to deal with variables for which the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4780 name is not known at configuration time.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4781 An index therefore cannot be used to access them, but the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4782 <literal>ngx_http_get_variable(r, name, key)</literal> function
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4783 is available.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4784 It searches for a variable with a given
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4785 <literal>name</literal> and its hash <literal>key</literal> derived
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4786 from the name.
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4787 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4788
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4789 </section>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4790
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4791
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4792 <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	4793
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4794 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4795 To create a variable, use the <literal>ngx_http_add_variable()</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4796 function.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4797 It takes as arguments a configuration (where the variable is registered),
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4798 the variable name and flags that control the function's behaviour:
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4799
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4800 <list type="bullet">
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4801 <listitem><literal>NGX_HTTP_VAR_CHANGEABLE</literal> — Enables redefinition of
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4802 the variable: there is no conflict if another module defines a variable with
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4803 the same name.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4804 This allows the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4805 <link doc="../http/ngx_http_rewrite_module.xml" id="set"/> directive
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4806 to override variables.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4807 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4808
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4809 <listitem><literal>NGX_HTTP_VAR_NOCACHEABLE</literal> — Disables caching,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4810 which is useful for variables such as <literal>$time_local</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4811 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4812
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4813 <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	4814 this variable is only accessible by index, not by name.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4815 This is a small optimization for use when it is known that the
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4816 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	4817 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4818
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4819 <listitem><literal>NGX_HTTP_VAR_PREFIX</literal> — The name of the
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4820 variable is a prefix.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4821 In this case, a handler must implement additional logic to obtain the value
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4822 of a specific variable.
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4823 For example, all “<literal>arg_</literal>” variables are processed by the
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4824 same handler, which performs lookup in request arguments and returns the value
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4825 of a specific argument.
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4826 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4827
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4828 </list>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4829
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4830 The function returns NULL in case of error or a pointer to
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4831 <literal>ngx_http_variable_t</literal> otherwise:
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4832 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4833 struct ngx_http_variable_s {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4834 ngx_str_t name;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4835 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	4836 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	4837 uintptr_t data;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4838 ngx_uint_t flags;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4839 ngx_uint_t index;
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 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4842
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4843 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	4844 are called to obtain or set the variable value,
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4845 <literal>data</literal> is passed to variable handlers, and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4846 <literal>index</literal> holds assigned variable index used to reference
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4847 the variable.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4848 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4849
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4850 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4851 Usually, a null-terminated static array of
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4852 <literal>ngx_http_variable_t</literal> structures is created
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4853 by a module and processed at the preconfiguration stage to add variables
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4854 into the configuration, for example:
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4855 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4856 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	4857
2009 9b7302e3b21f DevGuide: fixed variables example. Vladimir Homutov <vl@nginx.com> parents: 2008 diff changeset	4858 { ngx_string("foo_v1"), NULL, ngx_http_foo_v1_variable, 0, 0, 0 },
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4859
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4860 { 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	4861 };
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4862
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4863 static ngx_int_t
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4864 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	4865 {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4866 ngx_http_variable_t var, v;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4867
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4868 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	4869 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	4870 if (var == NULL) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4871 return NGX_ERROR;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4872 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4873
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4874 var->get_handler = v->get_handler;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4875 var->data = v->data;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4876 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4877
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4878 return NGX_OK;
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 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4881 This function in the example is used to initialize
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4882 the <literal>preconfiguration</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4883 field of the HTTP module context and is called before the parsing of HTTP
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4884 configuration, so that the parser can refer to these variables.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4885 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4886
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4887 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4888 The <literal>get</literal> handler is responsible for evaluating a variable
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4889 in the context of a specific request, for example:
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4890 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4891 static ngx_int_t
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4892 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	4893 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	4894 {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4895 u_char *p;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4896
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4897 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	4898 if (p == NULL) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4899 return NGX_ERROR;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4900 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4901
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4902 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	4903 v->valid = 1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4904 v->no_cacheable = 0;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4905 v->not_found = 0;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4906 v->data = p;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4907
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4908 return NGX_OK;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4909 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4910 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4911 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	4912 (for example, failed memory allocation) or <literal>NGX_OK</literal> otherwise.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4913 To learn the status of variable evaluation, inspect the flags
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4914 in <literal>ngx_http_variable_value_t</literal> (see the description
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4915 <link id="http_existing_variables">above</link>).
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4916 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4917
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4918 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4919 The <literal>set</literal> handler allows setting the property
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4920 referenced by the variable.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4921 For example, the set handler of the <literal>$limit_rate</literal> variable
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4922 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	4923 <programlisting>
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 { 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	4926 ngx_http_variable_request_get_size,
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4927 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	4928 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	4929 ...
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4930
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4931 static void
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4932 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	4933 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	4934 {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4935 ssize_t s, *sp;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4936 ngx_str_t val;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4937
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4938 val.len = v->len;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4939 val.data = v->data;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4940
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4941 s = ngx_parse_size(&val);
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4942
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4943 if (s == NGX_ERROR) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4944 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	4945 "invalid size \"%V\"", &val);
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4946 return;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4947 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4948
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4949 sp = (ssize_t ) ((char ) r + data);
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4950
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4951 *sp = s;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4952
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4953 return;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4954 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4955 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4956
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4957 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4958
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4959 </section>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4960
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4961 </section>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4962
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4963
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4964 <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	4965
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4966 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4967 A complex value, despite its name, provides an easy way to evaluate
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4968 expressions which can contain text, variables, and their combination.
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4969 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4970
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4971 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4972 The complex value description in
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4973 <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	4974 configuration stage into <literal>ngx_http_complex_value_t</literal>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4975 which is used at runtime to obtain results of expression evaluation.
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4976
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4977 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4978 ngx_str_t *value;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4979 ngx_http_complex_value_t cv;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4980 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	4981
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4982 value = cf->args->elts; /* directive arguments */
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4983
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4984 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	4985
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4986 ccv.cf = cf;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4987 ccv.value = &value[1];
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4988 ccv.complex_value = &cv;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4989 ccv.zero = 1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4990 ccv.conf_prefix = 1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4991
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4992 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	4993 return NGX_CONF_ERROR;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4994 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4995 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4996
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4997 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	4998 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	4999
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5000 <list type="bullet">
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5001
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5002 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5003 <literal>cf</literal> — Configuration pointer
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5004 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5005
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5006 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5007 <literal>value</literal> — String to be parsed (input)
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5008 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5009
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5010 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5011 <literal>complex_value</literal> — Compiled value (output)
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5012 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5013
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5014 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5015 <literal>zero</literal> — Flag that enables zero-terminating value
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5016 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5017
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5018 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5019 <literal>conf_prefix</literal> — Prefixes the result with the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5020 configuration prefix (the directory where nginx is currently looking for
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5021 configuration)
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5022 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5023
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5024 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5025 <literal>root_prefix</literal> — Prefixes the result with the root prefix
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5026 (the normal nginx installation prefix)
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5027 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5028
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5029 </list>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5030 The <literal>zero</literal> flag is useful when results are to be passed to
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5031 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	5032 dealing with filenames.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5033 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5034
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5035 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5036 Upon successful compilation, <literal>cv.lengths</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5037 contains information about the presence of variables
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5038 in the expression.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5039 The NULL value means that the expression contained static text only,
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5040 and so can be stored in a simple string rather than as a complex value.
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5041 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5042
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5043 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5044 The <literal>ngx_http_set_complex_value_slot()</literal> is a convenient
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5045 function used to initialize a complex value completely in the directive
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5046 declaration itself.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5047 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5048
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5049 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5050 At runtime, a complex value can be calculated using the
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5051 <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	5052 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5053 ngx_str_t res;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5054
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5055 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	5056 return NGX_ERROR;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5057 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5058 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5059 Given the request <literal>r</literal> and previously compiled
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5060 value <literal>cv</literal>, the function evaluates the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5061 expression and writes the result to <literal>res</literal>.
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5062 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5063
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5064 </section>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5065
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5066
1967 ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5067 <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	5068
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5069 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5070 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	5071 <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	5072 structure.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5073 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	5074 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	5075 <literal>ngx_http_get_module_loc_conf(r, module)</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5076 Request location can change several times during the request's lifetime.
1967 ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5077 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	5078 request.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5079 If the request switches to a different server (chosen by the HTTP
1967 ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5080 <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	5081 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	5082 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	5083 <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	5084 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	5085 configured for the server.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5086 The
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5087 <link doc="../http/ngx_http_rewrite_module.xml">ngx_http_rewrite_module</link>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5088 can change the request URI at the
1967 ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5089 <literal>NGX_HTTP_REWRITE_PHASE</literal> request phase as a result of
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5090 the <link doc="../http/ngx_http_rewrite_module.xml" id="rewrite">rewrite</link>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5091 directive and send the request back
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5092 to the <literal>NGX_HTTP_FIND_CONFIG_PHASE</literal> phase for selection of a
1967 ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5093 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	5094 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5095
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5096 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5097 It is also possible to redirect a request to a new location at any point by
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5098 calling one of
1967 ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5099 <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	5100 <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	5101 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5102
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5103 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5104 The <literal>ngx_http_internal_redirect(r, uri, args)</literal> function changes
1967 ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5105 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	5106 <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	5107 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	5108 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	5109 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	5110 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5111
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5112 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5113 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	5114 arguments.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5115 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5116
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5117 <programlisting>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5118 ngx_int_t
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5119 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	5120 {
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5121 ngx_str_t uri, args;
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5122
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5123 ngx_str_set(&uri, "/foo");
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5124 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	5125
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5126 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	5127 }
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5128 </programlisting>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5129
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5130 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5131 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	5132 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	5133 argument.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	5134 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	5135 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	5136 <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	5137 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5138
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5139 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5140 The 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	5141 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5142
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5143 <programlisting>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5144 ngx_int_t
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5145 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	5146 {
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5147 ngx_str_t name;
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5148
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5149 ngx_str_set(&name, "foo");
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5150
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5151 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	5152 }
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5153 </programlisting>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5154
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5155 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5156 Both functions - <literal>ngx_http_internal_redirect(r, uri, args)</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5157 and <literal>ngx_http_named_location(r, name)</literal> can be called when
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5158 nginx modules have already stored some contexts in a request's
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5159 <literal>ctx</literal> field.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5160 It's possible for these contexts to become inconsistent with the new
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	5161 location configuration.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	5162 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	5163 erased by both redirect functions.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5164 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5165
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5166 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5167 Calling <literal>ngx_http_internal_redirect(r, uri, args)</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5168 or <literal>ngx_http_named_location(r, name)</literal> increases the request
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5169 <literal>count</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5170 For consistent request reference counting, call
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5171 <literal>ngx_http_finalize_request(r, NGX_DONE)</literal> after redirecting the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5172 request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5173 This will finalize current request code path and decrease the counter.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5174 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5175
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5176 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5177 Redirected and rewritten requests become internal and can access the
1967 ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5178 <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	5179 locations.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	5180 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	5181 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5182
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5183 </section>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5184
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5185
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5186 <section name="Subrequests" id="http_subrequests">
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 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5189 Subrequests are primarily used to insert output of one request into another,
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5190 possibly mixed with other data.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5191 A subrequest looks like a normal request, but shares some data with its parent.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5192 In particular, all fields related to client input are shared
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5193 because a subrequest does not receive any other input from the client.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5194 The request field <literal>parent</literal> for a subrequest contains a link
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5195 to its parent request and is NULL for the main request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5196 The field <literal>main</literal> contains a link to the main request in
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5197 a group of requests.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5198 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5199
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5200 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5201 A subrequest starts in the <literal>NGX_HTTP_SERVER_REWRITE_PHASE</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5202 phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5203 It passes through the same subsequent phases as a normal request and is
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5204 assigned a location based on its own URI.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5205 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5206
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5207 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5208 The output header in a subrequest is always ignored.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5209 The <literal>ngx_http_postpone_filter</literal> places the subrequest's
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5210 output body in the right position relative to other data produced
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5211 by the parent request.
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5212 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5213
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5214 <para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5215 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	5216 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	5217 <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	5218 connection object.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5219 At any given point, only the active request in a request group is allowed
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5220 to output its buffers to the client.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5221 An inactive request can still send its output to the filter chain, but it
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5222 does not pass beyond the <literal>ngx_http_postpone_filter</literal> and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5223 remains buffered by that filter until the request becomes active.
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5224 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	5225 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5226
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5227 <list type="bullet">
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 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5230 Initially, the main request is active.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5231 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5232
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5233 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5234 The first subrequest of an active request becomes active right after creation.
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5235 </listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5236
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5237 <listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5238 The <literal>ngx_http_postpone_filter</literal> activates the next request
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5239 in the active request's subrequest list, once all data prior to that request
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5240 are sent.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5241 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5242
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5243 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5244 When a request is finalized, its parent is activated.
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5245 </listitem>
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 </list>
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 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5250 Create a subrequest by calling the function
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5251 <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	5252 <literal>r</literal> is the parent request, <literal>uri</literal> and
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5253 <literal>args</literal> are the URI and arguments of the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5254 subrequest, <literal>psr</literal> is the output parameter, which receives the
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5255 newly created subrequest reference, <literal>ps</literal> is a callback object
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5256 for notifying the parent request that the subrequest is being finalized, and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5257 <literal>flags</literal> is bitmask of flags.
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5258 The following flags are available:
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5259 </para>
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 <list type="bullet">
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 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5264 <literal>NGX_HTTP_SUBREQUEST_IN_MEMORY</literal> - Output is not
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5265 sent to the client, but rather stored in memory.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5266 The flag only affects subrequests which are processed by one of the proxying
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5267 modules.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5268 After a subrequest is finalized its output is available in
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5269 a <literal>r->upstream->buffer</literal> of type <literal>ngx_buf_t</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5270 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5271
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5272 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5273 <literal>NGX_HTTP_SUBREQUEST_WAITED</literal> - The subrequest's
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5274 <literal>done</literal> flag is set even if the subrequest is not active when
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5275 it is finalized.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5276 This subrequest flag is used by the SSI filter.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5277 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5278
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5279 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5280 <literal>NGX_HTTP_SUBREQUEST_CLONE</literal> - The subrequest is created as a
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5281 clone of its parent.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5282 It is started at the same location and proceeds from the same phase as the
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5283 parent request.
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5284 </listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5285
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5286 </list>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5287
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5288 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5289 The following example creates a subrequest with the URI
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5290 of <literal>/foo</literal>.
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5291 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5292
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5293 <programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5294 ngx_int_t rc;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5295 ngx_str_t uri;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5296 ngx_http_request_t *sr;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5297
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5298 ...
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5299
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5300 ngx_str_set(&uri, "/foo");
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5301
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5302 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	5303 if (rc == NGX_ERROR) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5304 /* error */
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5305 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5306 </programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5307
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5308 <para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5309 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	5310 subrequest.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5311 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5312
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5313 <programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5314 ngx_int_t
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5315 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	5316 {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5317 ngx_http_request_t *sr;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5318 ngx_http_post_subrequest_t *ps;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5319
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5320 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	5321 if (ps == NULL) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5322 return NGX_ERROR;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5323 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5324
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5325 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	5326 ps->data = "foo";
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5327
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5328 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	5329 NGX_HTTP_SUBREQUEST_CLONE);
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5330 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5331
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5332
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5333 ngx_int_t
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5334 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	5335 {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5336 char msg = (char ) data;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5337
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5338 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	5339 "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	5340
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5341 return rc;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5342 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5343 </programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5344
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5345 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5346 Subrequests are normally created in a body filter, in which case their output
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5347 can be treated like the output from any explicit request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5348 This means that eventually the output of a subrequest is sent to the client,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5349 after all explicit buffers that are passed before subrequest creation and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5350 before any buffers that are passed after creation.
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5351 This ordering is preserved even for large hierarchies of subrequests.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5352 The following example inserts output from a subrequest after all request data
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5353 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	5354 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5355
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5356 <programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5357 ngx_int_t
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5358 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	5359 {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5360 ngx_int_t rc;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5361 ngx_buf_t *b;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5362 ngx_uint_t last;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5363 ngx_chain_t *cl, out;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5364 ngx_http_request_t *sr;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5365 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	5366
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5367 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	5368 if (ctx == NULL) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5369 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	5370 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5371
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5372 last = 0;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5373
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5374 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	5375 if (cl->buf->last_buf) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5376 cl->buf->last_buf = 0;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5377 cl->buf->last_in_chain = 1;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5378 cl->buf->sync = 1;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5379 last = 1;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5380 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5381 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5382
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5383 /* Output explicit output buffers */
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5384
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5385 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	5386
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5387 if (rc == NGX_ERROR \|\| !last) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5388 return rc;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5389 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5390
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5391 /*
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5392 * 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	5393 * 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	5394 * 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	5395 */
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5396
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5397 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	5398 return NGX_ERROR;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5399 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5400
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5401 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	5402
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5403 /* 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	5404
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5405 b = ngx_calloc_buf(r->pool);
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5406 if (b == NULL) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5407 return NGX_ERROR;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5408 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5409
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5410 b->last_buf = 1;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5411
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5412 out.buf = b;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5413 out.next = NULL;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5414
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5415 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	5416 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5417 </programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5418
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5419 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5420 A subrequest can also be created for other purposes than data output.
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5421 For example, the <link doc="../http/ngx_http_auth_request_module.xml">
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5422 ngx_http_auth_request_module</link> module
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5423 creates a subrequest at the <literal>NGX_HTTP_ACCESS_PHASE</literal> phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5424 To disable output at this point, the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5425 <literal>header_only</literal> flag is set on the subrequest.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5426 This prevents the subrequest body from being sent to the client.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5427 Note that the subrequest's header is never sent to the client.
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5428 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	5429 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5430
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5431 </section>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5432
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5433
1969 275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5434 <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	5435
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5436 <para>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5437 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	5438 <literal>ngx_http_finalize_request(r, rc)</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5439 It is usually finalized by the content handler after all output buffers
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5440 are sent to the filter chain.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5441 At this point all of the output might not be sent to the client,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5442 with some of it remaining buffered somewhere along the filter chain.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5443 If it is, the <literal>ngx_http_finalize_request(r, rc)</literal> function
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5444 automatically installs a special handler <literal>ngx_http_writer(r)</literal>
1969 275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5445 to finish sending the output.
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5446 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	5447 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	5448 </para>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5449
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5450 <para>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5451 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	5452 following <literal>rc</literal> values:
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5453 </para>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5454
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5455 <list type="bullet">
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5456
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5457 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5458 <literal>NGX_DONE</literal> - Fast finalization.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5459 Decrement the request <literal>count</literal> and destroy the request if it
1969 275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5460 reaches zero.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5461 The client connection can be used for more requests after the current request
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5462 is destroyed.
1969 275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5463 </listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5464
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5465 <listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5466 <literal>NGX_ERROR</literal>, <literal>NGX_HTTP_REQUEST_TIME_OUT</literal>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5467 (<literal>408</literal>), <literal>NGX_HTTP_CLIENT_CLOSED_REQUEST</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5468 (<literal>499</literal>) - Error finalization.
1969 275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5469 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	5470 </listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5471
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5472 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5473 <literal>NGX_HTTP_CREATED</literal> (<literal>201</literal>),
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5474 <literal>NGX_HTTP_NO_CONTENT</literal> (<literal>204</literal>), codes greater
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5475 than or equal to <literal>NGX_HTTP_SPECIAL_RESPONSE</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5476 (<literal>300</literal>) - Special response finalization.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5477 For these values nginx either sends to the client a default response page for
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5478 the code or performs the internal redirect to an
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5479 <link doc="../http/ngx_http_core_module.xml" id="error_page"/> location if that
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5480 is configured for the code.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5481 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5482
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5483 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5484 Other codes are considered successful finalization codes and might activate the
1969 275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5485 request writer to finish sending the response body.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5486 Once the body is completely sent, the request <literal>count</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5487 is decremented.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5488 If it reaches zero, the request is destroyed, but the client connection can
1969 275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5489 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	5490 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	5491 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	5492 </listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5493
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5494 </list>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5495
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5496 </section>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5497
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5498
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5499 <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	5500
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5501 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5502 For dealing with the body of a client request, nginx provides the
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5503 <literal>ngx_http_read_client_request_body(r, post_handler)</literal> and
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5504 <literal>ngx_http_discard_request_body(r)</literal> functions.
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5505 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	5506 <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	5507 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	5508 body.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5509 One of these functions must be called for every request.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5510 Normally, the content handler makes the call.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5511 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5512
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5513 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5514 Reading or discarding the client request body from a subrequest is not allowed.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5515 It must always be done in the main request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5516 When a subrequest is created, it inherits the parent's
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5517 <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	5518 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	5519 </para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5520
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5521 <para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5522 The function
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5523 <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	5524 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	5525 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	5526 is called to continue processing the request.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5527 If the request body is missing or has already been read, the callback is called
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5528 immediately.
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5529 The function
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5530 <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	5531 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	5532 <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	5533 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	5534 chain.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5535 The body can be saved in memory buffers or file buffers, if the capacity
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5536 specified by the
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5537 <link doc="../http/ngx_http_core_module.xml" id="client_body_buffer_size"/>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5538 directive is not enough to fit the entire body in memory.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5539 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5540
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5541 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5542 The following example reads a client request body and returns its size.
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5543 </para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5544
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5545 <programlisting>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5546 ngx_int_t
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5547 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	5548 {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5549 ngx_int_t rc;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5550
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5551 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	5552
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5553 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	5554 /* error */
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5555 return rc;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5556 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5557
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5558 return NGX_DONE;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5559 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5560
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5561
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5562 void
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5563 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	5564 {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5565 off_t len;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5566 ngx_buf_t *b;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5567 ngx_int_t rc;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5568 ngx_chain_t *in, out;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5569
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5570 if (r->request_body == NULL) {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5571 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	5572 return;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5573 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5574
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5575 len = 0;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5576
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5577 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	5578 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	5579 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5580
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5581 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	5582 if (b == NULL) {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5583 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	5584 return;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5585 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5586
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5587 b->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	5588 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	5589 b->last_in_chain = 1;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5590
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5591 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	5592 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	5593
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5594 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	5595
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5596 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	5597 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	5598 return;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5599 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5600
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5601 out.buf = b;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5602 out.next = NULL;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5603
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5604 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	5605
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5606 ngx_http_finalize_request(r, rc);
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5607 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5608 </programlisting>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5609
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5610 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5611 The following fields of the request determine how the request body is read:
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5612 </para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5613
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5614 <list type="bullet">
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5615
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5616 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5617 <literal>request_body_in_single_buf</literal> - Read the body to a single memory
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5618 buffer.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5619 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5620
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5621 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5622 <literal>request_body_in_file_only</literal> - Always read the body to a file,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5623 even if fits in the memory buffer.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5624 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5625
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5626 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5627 <literal>request_body_in_persistent_file</literal> - Do not unlink the file
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5628 immediately after creation.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5629 A file with this flag can be moved to another directory.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5630 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5631
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5632 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5633 <literal>request_body_in_clean_file</literal> - Unlink the file when the
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5634 request is finalized.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5635 This can be useful when a file was supposed to be moved to another directory
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5636 but was not moved for some reason.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5637 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5638
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5639 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5640 <literal>request_body_file_group_access</literal> - Enable group access to the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5641 file by replacing the default 0600 access mask with 0660.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5642 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5643
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5644 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5645 <literal>request_body_file_log_level</literal> - Severity level at which to
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5646 log file errors.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5647 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5648
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5649 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5650 <literal>request_body_no_buffering</literal> - Read the request body without
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5651 buffering.
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5652 </listitem>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5653
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5654 </list>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5655
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5656 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5657 The <literal>request_body_no_buffering</literal> flag enables the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5658 unbuffered mode of reading a request body.
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5659 In this mode, after calling
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5660 <literal>ngx_http_read_client_request_body()</literal>, the
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5661 <literal>bufs</literal> chain might keep only a part of the body.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5662 To read the next part, call the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5663 <literal>ngx_http_read_unbuffered_request_body(r)</literal> function.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5664 The return value <literal>NGX_AGAIN</literal> and the request flag
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5665 <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	5666 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	5667 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	5668 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	5669 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	5670 </para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5671
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5672 </section>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5673
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5674
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5675 <section name="Response" id="http_response">
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5676
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5677 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5678 In nginx an HTTP response is produced by sending the response header followed by
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5679 the optional response body.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5680 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	5681 written to the client socket.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5682 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	5683 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	5684 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5685
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5686
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5687 <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	5688
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5689 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5690 The <literal>ngx_http_send_header(r)</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5691 function sends the output header.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5692 Do not call this function until <literal>r->headers_out</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5693 contains all of the data required to produce the HTTP response header.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5694 The <literal>status</literal> field in <literal>r->headers_out</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5695 must always be set.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5696 If the response status indicates that a response body follows the header,
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5697 <literal>content_length_n</literal> can be set as well.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5698 The default value for this field is <literal>-1</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5699 which means that the body size is unknown.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5700 In this case, chunked transfer encoding is used.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5701 To output an arbitrary header, append the <literal>headers</literal> list.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5702 </para>
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 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5706 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	5707 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5708 ngx_int_t rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5709 ngx_table_elt_t *h;
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 /* send header */
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 r->headers_out.status = NGX_HTTP_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5714 r->headers_out.content_length_n = 3;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5715
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5716 /* X-Foo: foo */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5717
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5718 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	5719 if (h == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5720 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5721 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5722
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5723 h->hash = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5724 ngx_str_set(&h->key, "X-Foo");
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5725 ngx_str_set(&h->value, "foo");
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5726
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5727 rc = ngx_http_send_header(r);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5728
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5729 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	5730 return rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5731 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5732
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5733 /* send body */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5734
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5735 ...
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5736 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5737 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5738
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5739 </section>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5740
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5741
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5742 <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	5743
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5744 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5745 The <literal>ngx_http_send_header(r)</literal> function invokes the header
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5746 filter chain by calling the first header filter handler stored in
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5747 the <literal>ngx_http_top_header_filter</literal> variable.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5748 It's assumed that every header handler calls the next handler in the chain
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5749 until the final handler <literal>ngx_http_header_filter(r)</literal> is called.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5750 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	5751 <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	5752 <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	5753 </para>
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 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5756 To add a handler to the header filter chain, store its address in
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5757 the global variable <literal>ngx_http_top_header_filter</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5758 at configuration time.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5759 The previous handler address is normally stored in a static variable in a module
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5760 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	5761 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5762
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5763 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5764 The following example of a header filter module adds the HTTP header
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5765 "<literal>X-Foo: foo</literal>" to every response with status
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5766 <literal>200</literal>.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5767 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5768
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5769 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5770 #include <ngx_config.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5771 #include <ngx_core.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5772 #include <ngx_http.h>
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5775 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	5776 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	5777
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5778
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5779 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	5780 NULL, /* preconfiguration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5781 ngx_http_foo_header_filter_init, /* postconfiguration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5782
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5783 NULL, /* create main configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5784 NULL, /* init main configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5785
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5786 NULL, /* create server configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5787 NULL, /* merge server configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5788
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5789 NULL, /* create location configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5790 NULL /* merge location configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5791 };
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5792
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5793
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5794 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	5795 NGX_MODULE_V1,
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5796 &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	5797 NULL, /* module directives */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5798 NGX_HTTP_MODULE, /* module type */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5799 NULL, /* init master */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5800 NULL, /* init module */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5801 NULL, /* init process */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5802 NULL, /* init thread */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5803 NULL, /* exit thread */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5804 NULL, /* exit process */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5805 NULL, /* exit master */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5806 NGX_MODULE_V1_PADDING
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5807 };
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 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	5811
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5812
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5813 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5814 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	5815 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5816 ngx_table_elt_t *h;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5817
1971 5fb870087b76 Fixed typo and removed trailing spaces. Vladimir Homutov <vl@nginx.com> parents: 1970 diff changeset	5818 /*
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5819 * 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	5820 * to every HTTP 200 response
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 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	5824 return ngx_http_next_header_filter(r);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5825 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5826
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5827 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	5828 if (h == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5829 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5830 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5831
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5832 h->hash = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5833 ngx_str_set(&h->key, "X-Foo");
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5834 ngx_str_set(&h->value, "foo");
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 return ngx_http_next_header_filter(r);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5837 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5838
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5839
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5840 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5841 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	5842 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5843 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	5844 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	5845
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5846 return NGX_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5847 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5848 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5849
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5850 </section>
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 </section>
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5855 <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	5856
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5857 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5858 To send the response body, call the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5859 <literal>ngx_http_output_filter(r, cl)</literal> function.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5860 The function can be called multiple times.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5861 Each time, it sends a part of the response body in the form of a buffer chain.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5862 Set the <literal>last_buf</literal> flag in the last body buffer.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5863 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5864
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5865 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5866 The following example produces a complete HTTP response with "foo" as its body.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5867 For the example to work as subrequest as well as a main request,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5868 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	5869 of the output.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5870 The <literal>last_buf</literal> flag is set only for the main request because
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5871 the last buffer for a subrequest does not end the entire output.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5872 </para>
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 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5875 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5876 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	5877 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5878 ngx_int_t rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5879 ngx_buf_t *b;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5880 ngx_chain_t out;
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 /* send header */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5883
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5884 r->headers_out.status = NGX_HTTP_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5885 r->headers_out.content_length_n = 3;
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 rc = ngx_http_send_header(r);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5888
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5889 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	5890 return rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5891 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5892
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5893 /* send body */
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 b = ngx_calloc_buf(r->pool);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5896 if (b == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5897 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5898 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5899
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5900 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	5901 b->last_in_chain = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5902
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5903 b->memory = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5904
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5905 b->pos = (u_char *) "foo";
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5906 b->last = b->pos + 3;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5907
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5908 out.buf = b;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5909 out.next = NULL;
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 return ngx_http_output_filter(r, &out);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5912 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5913 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5914
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5915 </section>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5916
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5917
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5918 <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	5919
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5920 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5921 The function <literal>ngx_http_output_filter(r, cl)</literal> invokes the
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5922 body filter chain by calling the first body filter handler stored in
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5923 the <literal>ngx_http_top_body_filter</literal> variable.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5924 It's assumed that every body handler calls the next handler in the chain until
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5925 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	5926 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5927
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5928 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5929 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	5930 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	5931 the next handler.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5932 It's worth noting that the chain links <literal>ngx_chain_t</literal> of the
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5933 incoming chain belong to the caller, and must not be reused or changed.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5934 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	5935 to keep track of the buffers it has sent.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5936 To save the buffer chain or to substitute some buffers before passing to the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5937 next filter, a handler needs to allocate its own chain links.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5938 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5939
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5940 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5941 Following is an example of a simple body filter that counts the number of
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5942 bytes in the body.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5943 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	5944 used in the access log.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5945 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5946
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5947 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5948 #include <ngx_config.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5949 #include <ngx_core.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5950 #include <ngx_http.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5951
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5952
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5953 typedef struct {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5954 off_t count;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5955 } ngx_http_counter_filter_ctx_t;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5956
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5957
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5958 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	5959 ngx_chain_t *in);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5960 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	5961 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	5962 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	5963 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	5964
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5965
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5966 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	5967 ngx_http_counter_add_variables, /* preconfiguration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5968 ngx_http_counter_filter_init, /* postconfiguration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5969
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5970 NULL, /* create main configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5971 NULL, /* init main configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5972
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5973 NULL, /* create server configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5974 NULL, /* merge server configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5975
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5976 NULL, /* create location configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5977 NULL /* merge location configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5978 };
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5979
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5980
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5981 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	5982 NGX_MODULE_V1,
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5983 &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	5984 NULL, /* module directives */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5985 NGX_HTTP_MODULE, /* module type */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5986 NULL, /* init master */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5987 NULL, /* init module */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5988 NULL, /* init process */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5989 NULL, /* init thread */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5990 NULL, /* exit thread */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5991 NULL, /* exit process */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5992 NULL, /* exit master */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5993 NGX_MODULE_V1_PADDING
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5994 };
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5995
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5996
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5997 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	5998
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5999 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	6000
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6001
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6002 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6003 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	6004 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6005 ngx_chain_t *cl;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6006 ngx_http_counter_filter_ctx_t *ctx;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6007
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6008 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	6009 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6010 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	6011 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6012 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6013 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6014
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6015 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	6016 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6017
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6018 for (cl = in; cl; cl = cl->next) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6019 ctx->count += ngx_buf_size(cl->buf);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6020 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6021
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6022 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	6023 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6024
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 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6027 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	6028 uintptr_t data)
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6029 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6030 u_char *p;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6031 ngx_http_counter_filter_ctx_t *ctx;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6032
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6033 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	6034 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6035 v->not_found = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6036 return NGX_OK;
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6039 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	6040 if (p == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6041 return NGX_ERROR;
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6044 v->data = p;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6045 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	6046 v->valid = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6047 v->no_cacheable = 0;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6048 v->not_found = 0;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6049
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6050 return NGX_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6051 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6052
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6053
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6054 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6055 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	6056 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6057 ngx_http_variable_t *var;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6058
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6059 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	6060 if (var == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6061 return NGX_ERROR;
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6064 var->get_handler = ngx_http_counter_variable;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6065
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6066 return NGX_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6067 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6068
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 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6071 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	6072 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6073 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	6074 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	6075
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6076 return NGX_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6077 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6078 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6079
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6080 </section>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6081
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6082
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6083 <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	6084
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6085 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6086 When writing a body or header filter, pay special attention to the filter's
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6087 position in the filter order.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6088 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	6089 modules.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6090 The nginx standard modules register a number of head and body filters and it's
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6091 important to register a new filter module in the right place with respect to
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6092 them.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6093 Normally, modules register filters in their postconfiguration handlers.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6094 The order in which filters are called during processing is obviously the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6095 reverse of the order in which they are registered.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6096 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6097
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6098 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6099 For third-party filter modules nginx provides a special slot
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6100 <literal>HTTP_AUX_FILTER_MODULES</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6101 To register a filter module in this slot, set
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6102 the <literal>ngx_module_type</literal> variable to
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6103 <literal>HTTP_AUX_FILTER</literal> in the module's configuration.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6104 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6105
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6106 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6107 The following example shows a filter module config file assuming
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6108 for a module with just
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6109 one source file, <literal>ngx_http_foo_filter_module.c</literal>.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6110 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6111
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6112 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6113 ngx_module_type=HTTP_AUX_FILTER
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6114 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	6115 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	6116
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6117 . auto/module
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6118 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6119
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6120 </section>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6121
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6122
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6123 <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	6124
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6125 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6126 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	6127 allocated buffers.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6128 A standard and widely adopted approach in nginx code is to keep
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6129 two buffer chains for this purpose:
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6130 <literal>free</literal> and <literal>busy</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6131 The <literal>free</literal> chain keeps all free buffers,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6132 which can be reused.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6133 The <literal>busy</literal> chain keeps all buffers sent by the current
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6134 module that are still in use by some other filter handler.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6135 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	6136 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	6137 (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	6138 <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	6139 Once a buffer is completely consumed, it's ready to be reused.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6140 To add newly freed buffers to the <literal>free</literal> chain
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6141 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	6142 size buffers at the head of it to <literal>free</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6143 This operation is so common that there is a special function for it,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6144 <literal>ngx_chain_update_chains(free, busy, out, tag)</literal>.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6145 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	6146 <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	6147 <literal>busy</literal> to <literal>free</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6148 Only the buffers with the specified <literal>tag</literal> are reused.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6149 This lets a module reuse only the buffers that it allocated itself.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6150 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6151
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6152 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6153 The following example is a body filter that inserts the string “foo” before each
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6154 incoming buffer.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6155 The new buffers allocated by the module are reused if possible.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6156 Note that for this example to work properly, setting up a
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6157 <link id="http_header_filters">header filter</link>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6158 and resetting <literal>content_length_n</literal> to <literal>-1</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6159 is also required, but the relevant code is not provided here.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6160 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6161
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6162 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6163 typedef struct {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6164 ngx_chain_t *free;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6165 ngx_chain_t *busy;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6166 } ngx_http_foo_filter_ctx_t;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6167
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6168
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6169 ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6170 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	6171 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6172 ngx_int_t rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6173 ngx_buf_t *b;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6174 ngx_chain_t cl, tl, out, *ll;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6175 ngx_http_foo_filter_ctx_t *ctx;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6176
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6177 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	6178 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6179 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	6180 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6181 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6182 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6183
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6184 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	6185 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6186
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6187 /* 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	6188
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6189 ll = &out;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6190
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6191 for (cl = in; cl; cl = cl->next) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6192
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6193 /* 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	6194
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6195 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	6196 if (tl == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6197 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6198 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6199
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6200 b = tl->buf;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6201 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	6202 b->memory = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6203 b->pos = (u_char *) "foo";
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6204 b->last = b->pos + 3;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6205
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6206 *ll = tl;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6207 ll = &tl->next;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6208
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6209 /* append the next incoming buffer */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6210
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6211 tl = ngx_alloc_chain_link(r->pool);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6212 if (tl == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6213 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6214 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6215
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6216 tl->buf = cl->buf;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6217 *ll = tl;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6218 ll = &tl->next;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6219 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6220
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6221 *ll = NULL;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6222
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6223 /* send the new chain */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6224
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6225 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	6226
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6227 /* update "busy" and "free" chains for reuse */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6228
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6229 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	6230 (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	6231
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6232 return rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6233 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6234 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6235
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6236 </section>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6237
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6238
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6239 <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	6240
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6241 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6242 The
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6243 <link doc="../http/ngx_http_upstream_module.xml">ngx_http_upstream_module</link>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6244 provides the basic functionality needed to pass requests to remote servers.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6245 Modules that implement specific protocols, such as HTTP or FastCGI, use
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6246 this functionality.
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6247 The module also provides an interface for creating custom
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6248 load-balancing modules and implements a default round-robin method.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6249 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6250
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6251 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6252 The <link doc="../http/ngx_http_upstream_module.xml" id="least_conn"/>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6253 and <link doc="../http/ngx_http_upstream_module.xml" id="hash"/>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6254 modules implement alternative load-balancing methods, but
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6255 are actually implemented as extensions of the upstream round-robin
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6256 module and share a lot of code with it, such as the representation
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6257 of a server group.
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6258 The <link doc="../http/ngx_http_upstream_module.xml" id="keepalive"/> module
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6259 is an independent module that extends upstream functionality.
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6260 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6261
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6262 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6263 The
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6264 <link doc="../http/ngx_http_upstream_module.xml">ngx_http_upstream_module</link>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6265 can be configured explicitly by placing the corresponding
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6266 <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	6267 the configuration file, or implicitly by using directives
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6268 such as <link doc="../http/ngx_http_proxy_module.xml" id="proxy_pass"/>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6269 that accept a URL that gets evaluated at some point into a list of servers.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6270 The alternative load-balancing methods are available only with an explicit
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6271 upstream configuration.
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6272 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	6273 <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	6274 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	6275 <programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6276 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	6277 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	6278 void **srv_conf;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6279
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6280 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	6281
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6282 ngx_uint_t flags;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6283 ngx_str_t host;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6284 u_char *file_name;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6285 ngx_uint_t line;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6286 in_port_t port;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6287 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	6288
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6289 #if (NGX_HTTP_UPSTREAM_ZONE)
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6290 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	6291 #endif
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6292 };
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6293 </programlisting>
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 <list type="bullet">
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 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6298 <literal>srv_conf</literal> — Configuration context of upstream modules.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6299 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6300
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6301 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6302 <literal>servers</literal> — Array of
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6303 <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	6304 <link doc="../http/ngx_http_upstream_module.xml" id="server"/> directives
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6305 in the <literal>upstream</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6306 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6307
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6308 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6309 <literal>flags</literal> — Flags that mostly mark which features
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6310 are supported by the load-balancing method.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6311 The features are configured as parameters of
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6312 the <link doc="../http/ngx_http_upstream_module.xml" id="server"/> directive:
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6313
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6314
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6315 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6316
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6317 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6318 <literal>NGX_HTTP_UPSTREAM_CREATE</literal> — Distinguishes explicitly
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6319 defined upstreams from those that are automatically created by the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6320 <link doc="../http/ngx_http_proxy_module.xml" id="proxy_pass"/> directive
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6321 and “friends”
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6322 (FastCGI, SCGI, etc.)
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6323 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6324
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6325 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6326 <literal>NGX_HTTP_UPSTREAM_WEIGHT</literal> — The “<literal>weight</literal>”
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6327 parameter is supported
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6328 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6329
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6330 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6331 <literal>NGX_HTTP_UPSTREAM_MAX_FAILS</literal> — The
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6332 “<literal>max_fails</literal>” parameter is supported
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6333 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6334
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6335 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6336 <literal>NGX_HTTP_UPSTREAM_FAIL_TIMEOUT</literal> —
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6337 The “<literal>fail_timeout</literal>” parameter is supported
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6338 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6339
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6340 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6341 <literal>NGX_HTTP_UPSTREAM_DOWN</literal> — The “<literal>down</literal>”
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6342 parameter is supported
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6343 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6344
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6345 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6346 <literal>NGX_HTTP_UPSTREAM_BACKUP</literal> — The “<literal>backup</literal>”
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6347 parameter is supported
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6348 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6349
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6350 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6351 <literal>NGX_HTTP_UPSTREAM_MAX_CONNS</literal> — The
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6352 “<literal>max_conns</literal>” parameter is supported
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6353 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6354
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6355 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6356
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6357 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6358
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6359 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6360 <literal>host</literal> — Name of the upstream.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6361 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6362
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6363 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6364 <literal>file_name, line</literal> — Name of the configuration file
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6365 and the line where the <literal>upstream</literal> block is located.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6366 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6367
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6368 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6369 <literal>port</literal> and <literal>no_port</literal> — Not used for
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6370 explicitly defined upstream groups.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6371 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6372
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6373 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6374 <literal>shm_zone</literal> — Shared memory zone used by this upstream group,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6375 if any.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6376 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6377
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6378 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6379 <literal>peer</literal> — object that holds generic methods for
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6380 initializing upstream configuration:
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6381
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6382 <programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6383 typedef struct {
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6384 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	6385 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	6386 void *data;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6387 } ngx_http_upstream_peer_t;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6388 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6389 A module that implements a load-balancing algorithm must set these
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6390 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	6391 If <literal>init_upstream</literal> was not initialized during configuration
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6392 parsing, <literal>ngx_http_upstream_module</literal> sets it to the default
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6393 <literal>ngx_http_upstream_init_round_robin</literal> algorithm.
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6394
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6395 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6396 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6397 <literal>init_upstream(cf, us)</literal> — Configuration-time
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6398 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	6399 initializing the <literal>init()</literal> method in case of success.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6400 A typical load-balancing module uses a list of servers in the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6401 <literal>upstream</literal> block
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6402 to create an efficient data structure that it uses and saves its own
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6403 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	6404 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6405
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6406 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6407 <literal>init(r, us)</literal> — Initializes a per-request
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6408 <literal>ngx_http_upstream_peer_t.peer</literal> structure that is used for
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6409 load balancing (not to be confused with the
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6410 <literal>ngx_http_upstream_srv_conf_t.peer</literal> described above which
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6411 is per-upstream).
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6412 It is passed as the <literal>data</literal> argument to all callbacks that
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6413 deal with server selection.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6414 </listitem>
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 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6418 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6419 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6420
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6421 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6422 When nginx has to pass a request to another host for processing, it uses
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6423 the configured load-balancing method to obtain an address to connect to.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6424 The method is obtained from the
1994 effdf0747a05 Development guide: fixed a typo. Vladimir Homutov <vl@nginx.com> parents: 1993 diff changeset	6425 <literal>ngx_http_upstream_t.peer</literal> object
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6426 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	6427 <programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6428 struct ngx_peer_connection_s {
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6429 ...
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6430
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6431 struct sockaddr *sockaddr;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6432 socklen_t socklen;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6433 ngx_str_t *name;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6434
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6435 ngx_uint_t tries;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6436
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6437 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	6438 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	6439 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	6440 void *data;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6441
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6442 #if (NGX_SSL \|\| NGX_COMPAT)
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6443 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	6444 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	6445 #endif
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6446
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6447 ...
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6448 };
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6449 </programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6450
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6451 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	6452
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6453 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6454 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6455 <literal>sockaddr</literal>, <literal>socklen</literal>,
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6456 <literal>name</literal> — Address of the upstream server to connect to;
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6457 this is the output parameter of a load-balancing method.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6458 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6459
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6460 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6461 <literal>data</literal> — The per-request data of a load-balancing method;
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6462 keeps the state of the selection algorithm and usually includes the link
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6463 to the upstream configuration.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6464 It is passed as an argument to all methods that deal with server selection
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6465 (see <link id="lb_method_get">below</link>).
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6466 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6467
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6468 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6469 <literal>tries</literal> — Allowed
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6470 <link doc="../http/ngx_http_proxy_module.xml" id="proxy_next_upstream_tries">number</link>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6471 of attempts to connect to an upstream server.
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6472 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6473
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6474 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6475 <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	6476 <literal>set_session</literal>, and <literal>save_session</literal>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6477 - Methods of the load-balancing module, described below.
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6478 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6479
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6480 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6481
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6482 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6483
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6484 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6485 All methods accept at least two arguments: a peer connection object
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6486 <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	6487 <literal>ngx_http_upstream_srv_conf_t.peer.init()</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6488 Note that it might differ from <literal>pc.data</literal> due
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6489 to “chaining” of load-balancing modules.
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6490 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6491
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6492 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6493
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6494 <list type="bullet">
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6495 <listitem id="lb_method_get">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6496 <literal>get(pc, data)</literal> — The method called when the upstream
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6497 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	6498 its address.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6499 The method has to fill the <literal>sockaddr</literal>,
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6500 <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	6501 <literal>ngx_peer_connection_t</literal> structure.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6502 The return is one of:
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6503
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6504 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6505
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6506 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6507 <literal>NGX_OK</literal> — Server was selected.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6508 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6509
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6510 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6511 <literal>NGX_ERROR</literal> — Internal error occurred.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6512 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6513
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6514 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6515 <literal>NGX_BUSY</literal> — no servers are currently available.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6516 This can happen due to many reasons, including: the dynamic server group is
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6517 empty, all servers in the group are in the failed state, or
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6518 all servers in the group are already
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6519 handling the maximum number of connections.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6520 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6521
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6522 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6523 <literal>NGX_DONE</literal> — the underlying connection was reused and there
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6524 is no need to create a new connection to the upstream server.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6525 This value is set by the <literal>keepalive</literal> module.
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6526 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6527
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6528 <!--
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6529 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6530 <literal>NGX_ABORT</literal> — the request was queued and the further
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6531 processing of this request should be postponed.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6532 This value is set by the <literal>queue</literal> module.
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6533 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6534 -->
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6535
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6536 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6537
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6538 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6539
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6540 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6541 <literal>free(pc, data, state)</literal> — The method called when an
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6542 upstream module has finished work with a particular server.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6543 The <literal>state</literal> argument is the completion status of the upstream
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6544 connection, a bitmask with the following possible values:
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6545
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6546 <list type="bullet">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6547
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6548 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6549 <literal>NGX_PEER_FAILED</literal> — Attempt was
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6550 <link doc="../http/ngx_http_upstream_module.xml" id="max_fails">unsuccessful</link>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6551 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6552
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6553 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6554 <literal>NGX_PEER_NEXT</literal> — A special case when upstream server
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6555 returns codes <literal>403</literal> or <literal>404</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6556 which are not considered a
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6557 <link doc="../http/ngx_http_upstream_module.xml" id="max_fails">failure</link>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6558 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6559
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6560 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6561 <literal>NGX_PEER_KEEPALIVE</literal> — Currently unused
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6562 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6563
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6564 </list>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6565
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6566 This method also decrements the <literal>tries</literal> counter.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6567
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6568 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6569
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6570 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6571 <literal>notify(pc, data, type)</literal> — Currently unused
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6572 in the OSS version.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6573 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6574
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6575 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6576 <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	6577 <literal>save_session(pc, data)</literal>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6578 — SSL-specific methods that enable caching sessions to upstream
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6579 servers.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6580 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	6581 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6582
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6583 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6584
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6585 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6586
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	6587 </section>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	6588
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6589 </section>
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	6590
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	6591 </article>

Mercurial > hg > nginx-site

annotate xml/en/docs/dev/development_guide.xml @ 2009:9b7302e3b21f