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

annotate xml/en/docs/dev/development_guide.xml @ 2994:537b98ec3c83

Development guide: fixed example code. The code produced compiler errors.

author	Roman Arutyunyan <arut@nginx.com>
date	Thu, 17 Aug 2023 20:31:29 +0400
parents	b7ff3d1915a1
children	89ab7fc9fea5

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"
2819 b7ff3d1915a1 Development guide: fixed misleading comment about rc.options. Maxim Dounin <mdounin@mdounin.ru> parents: 2765 diff changeset	12 rev="11">
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>
2406 e79e32d19ae4 Development guide: fixed function type in code example. Vladimir Homutov <vl@nginx.com> parents: 2366 diff changeset	231 ngx_int_t
1899 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
2410 392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	261 <section name="Overview" id="string_overview">
1899 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>
2294 58df9b14b8ec Development guide: documented ngx_explicit_memzero(). Roman Arutyunyan <arut@nginx.com> parents: 2258 diff changeset	353 <literal>ngx_explicit_memzero()</literal> — Does the same as
58df9b14b8ec Development guide: documented ngx_explicit_memzero(). Roman Arutyunyan <arut@nginx.com> parents: 2258 diff changeset	354 <literal>ngx_memzero()</literal>, but this call is never removed by the
58df9b14b8ec Development guide: documented ngx_explicit_memzero(). Roman Arutyunyan <arut@nginx.com> parents: 2258 diff changeset	355 compiler's dead store elimination optimization.
58df9b14b8ec Development guide: documented ngx_explicit_memzero(). Roman Arutyunyan <arut@nginx.com> parents: 2258 diff changeset	356 This function can be used to clear sensitive data such as passwords and keys.
58df9b14b8ec Development guide: documented ngx_explicit_memzero(). Roman Arutyunyan <arut@nginx.com> parents: 2258 diff changeset	357 </listitem>
58df9b14b8ec Development guide: documented ngx_explicit_memzero(). Roman Arutyunyan <arut@nginx.com> parents: 2258 diff changeset	358
58df9b14b8ec Development guide: documented ngx_explicit_memzero(). Roman Arutyunyan <arut@nginx.com> parents: 2258 diff changeset	359 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	360 <literal>ngx_cpymem()</literal> — Does the same as
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	361 <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	362 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	363 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	364
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	365 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	366 <literal>ngx_movemem()</literal> — Does the same as
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	367 <literal>ngx_memmove()</literal>, but returns the final destination address.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	368 </listitem>
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 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	371 <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	372 delimited by two pointers.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	373 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	374 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	375 </para>
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	378 The following functions perform case conversion and comparison:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	379 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	380
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	381 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	382 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	383
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	384 <listitem>
1999 1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	385 <literal>ngx_tolower()</literal>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	386 </listitem>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	387
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	388 <listitem>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	389 <literal>ngx_toupper()</literal>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	390 </listitem>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	391
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	392 <listitem>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	393 <literal>ngx_strlow()</literal>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	394 </listitem>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	395
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	396 <listitem>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	397 <literal>ngx_strcasecmp()</literal>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	398 </listitem>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	399
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	400 <listitem>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	401 <literal>ngx_strncasecmp()</literal>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	402 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	403
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	404 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	405 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	406
1998 18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	407 <para>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	408 The following macros simplify string initialization:
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	409 </para>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	410
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	411 <list type="bullet">
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	412
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	413 <listitem>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	414 <literal>ngx_string(text)</literal> — static initializer for the
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	415 <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	416 <literal>text</literal>
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
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	419 <listitem>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	420 <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	421 <literal>ngx_str_t</literal> type
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	422 </listitem>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	423
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	424 <listitem>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	425 <literal>ngx_str_set(str, text)</literal> — initializes string
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	426 <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	427 literal <literal>text</literal>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	428 </listitem>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	429
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	430 <listitem>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	431 <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	432 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	433 </listitem>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	434
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	435 </list>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	436
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	437 </section>
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 <section name="Formatting" id="formatting">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	441
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	442 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	443 The following formatting functions support nginx-specific types:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	444 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	445
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 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	448 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	449
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	450 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	451 <literal>ngx_sprintf(buf, fmt, ...)</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	452 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	453
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	454 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	455 <literal>ngx_snprintf(buf, max, fmt, ...)</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	456 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	457
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	458 <listitem>
1975 459a6f194fcf Fixed a typo. Vladimir Homutov <vl@nginx.com> parents: 1971 diff changeset	459 <literal>ngx_slprintf(buf, last, fmt, ...)</literal>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	460 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	461
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	462 <listitem>
2079 05f5bfdaffa3 Development guide: fixed formatting function names. Maxim Dounin <mdounin@mdounin.ru> parents: 2078 diff changeset	463 <literal>ngx_vslprintf(buf, last, fmt, args)</literal>
05f5bfdaffa3 Development guide: fixed formatting function names. Maxim Dounin <mdounin@mdounin.ru> parents: 2078 diff changeset	464 </listitem>
05f5bfdaffa3 Development guide: fixed formatting function names. Maxim Dounin <mdounin@mdounin.ru> parents: 2078 diff changeset	465
05f5bfdaffa3 Development guide: fixed formatting function names. Maxim Dounin <mdounin@mdounin.ru> parents: 2078 diff changeset	466 <listitem>
05f5bfdaffa3 Development guide: fixed formatting function names. Maxim Dounin <mdounin@mdounin.ru> parents: 2078 diff changeset	467 <literal>ngx_vsnprintf(buf, max, fmt, args)</literal>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	468 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	469
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	470 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	471 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	472
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	473 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	474 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	475 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	476 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	477
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	478
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	479 <list type="bullet">
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	480
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	481 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	482 <literal>%O</literal> — <literal>off_t</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	483 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	484
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	485 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	486 <literal>%T</literal> — <literal>time_t</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	487 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	488
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	489 <listitem>
1997 eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	490 <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	491 </listitem>
eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	492
eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	493 <listitem>
eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	494 <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	495 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	496
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	497 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	498 <literal>%p</literal> — <literal>void *</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	499 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	500
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	501 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	502 <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	503 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	504
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	505 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	506 <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	507 </listitem>
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 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	510 <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	511 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	512
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	513 </list>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	514
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	515
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	516 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	517 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	518 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	519 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	520
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	521 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	522 For example:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	523
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	524 <programlisting>
1997 eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	525 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	526 size_t len;
eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	527 ngx_uint_t n;
1899 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 /* set n here */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	530
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	531 len = ngx_sprintf(buf, "%ui", n) — buf;
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	532 </programlisting>
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>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	535
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	536 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	537
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	538
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	539 <section name="Numeric conversion" id="numeric_conversion">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	540
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	541 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	542 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	543 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	544 the indicated type.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	545 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	546
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	547 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	548
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	549 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	550 <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	551 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	552
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	553 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	554 <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	555 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	556
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	557 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	558 <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	559 </listitem>
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 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	562 <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	563 </listitem>
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>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	566 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	567
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	568 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	569 There are two additional numeric conversion functions.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	570 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	571
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	572 <list type="bullet">
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	573
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	574 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	575 <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	576 number of given length to a positive integer of type
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	577 <literal>ngx_int_t</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	578 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	579 positions.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	580 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	581 than <literal>points</literal> fractional digits.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	582 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	583 <literal>1050</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	584 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	585
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	586 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	587 <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	588 of a positive integer to <literal>ngx_int_t</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	589 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	590
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	591 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	592 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	593
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	594 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	595
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	596 <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	597
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	598 <para>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	599 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	600 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	601 library.
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	602 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	603 </para>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	604
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	605 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	606 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	607 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	608 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	609 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	610
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	611 <programlisting>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	612 #if (NGX_PCRE)
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	613 ngx_regex_t *re;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	614 ngx_regex_compile_t rc;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	615
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	616 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	617
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	618 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	619
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	620 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	621
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	622 rc.pattern = value;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	623 rc.pool = cf->pool;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	624 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	625 rc.err.data = errstr;
2819 b7ff3d1915a1 Development guide: fixed misleading comment about rc.options. Maxim Dounin <mdounin@mdounin.ru> parents: 2765 diff changeset	626 /* rc.options can be set to NGX_REGEX_CASELESS */
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	627
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	628 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	629 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	630 return NGX_CONF_ERROR;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	631 }
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	632
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	633 re = rc.regex;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	634 #endif
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	635 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	636 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	637 <literal>named_captures</literal> fields in the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	638 <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	639 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	640 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	641
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	642 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	643 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	644 <programlisting>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	645 ngx_int_t n;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	646 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	647
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	648 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	649
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	650 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	651 if (n >= 0) {
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	652 /* string matches expression */
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 } 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	655 /* no match was found */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	656
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	657 } else {
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	658 /* some error */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	659 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	660 }
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	661 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	662 The arguments to <literal>ngx_regex_exec()</literal> are the compiled regular
2422 eca8e37a34ef Fixed typos. Vladimir Homutov <vl@nginx.com> parents: 2412 diff changeset	663 expression <literal>re</literal>, the string to match <literal>input</literal>,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	664 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	665 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	666 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	667 as required by the
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	668 <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	669 In the example, the size is calculated from the total number of captures plus
2422 eca8e37a34ef Fixed typos. Vladimir Homutov <vl@nginx.com> parents: 2412 diff changeset	670 one for the matched string itself.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	671 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	672
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	673 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	674 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	675 <programlisting>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	676 u_char *p;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	677 size_t size;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	678 ngx_str_t name, value;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	679
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	680 /* all captures */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	681 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	682 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	683 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	684 }
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 /* accessing named captures */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	687
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	688 size = rc.name_size;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	689 p = rc.names;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	690
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	691 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	692
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	693 /* capture name */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	694 name.data = &p[2];
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	695 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	696
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	697 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	698
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	699 /* captured value */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	700 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	701 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	702 }
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	703 </programlisting>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	704 </para>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	705
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	706 <para>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	707 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	708 <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	709 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	710 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	711 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	712 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	713 <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	714 in case of error.
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	715 </para>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	716
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	717 </section>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	718
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	719 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	720
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	721
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	722 <section name="Time" id="time">
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	723
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	724 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	725 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	726 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	727 <programlisting>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	728 typedef struct {
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	729 time_t sec;
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	730 ngx_uint_t msec;
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	731 ngx_int_t gmtoff;
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	732 } ngx_time_t;
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	733 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	734 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	735 <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	736 on Windows.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	737 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	738
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 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	741 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	742 format.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	743 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	744
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	745 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	746 The available string representations are:
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	747
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	748 <list type="bullet">
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	749
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	750 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	751 <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	752 <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	753 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	754
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	755 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	756 <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	757 <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	758 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	759
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	760 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	761 <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	762 <literal>"Sep 28 12:00:00"</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	763 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	764
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	765 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	766 <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	767 <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	768 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	769
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	770 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	771 <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	772 standard format:
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	773 <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	774 </listitem>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	775
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	776 </list>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	777 </para>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	778
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	779 <para>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	780 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	781 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	782 the cached time value.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	783 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	784
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	785 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	786 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	787 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	788 <literal>struct timeval</literal>).
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	789 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	790 calls.
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	791 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	792 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	793 signal handler context.
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	794 </para>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	795
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	796 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	797 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	798 broken-down time representation.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	799 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	800 <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	801 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	802
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	803 <list type="bullet">
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	804
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	805 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	806 <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	807 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	808
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	809 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	810 <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	811 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	812 </listitem>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	813
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	814 </list>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	815
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	816 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	817 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	818 <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	819 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	820 representation function returns a string representation suitable
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	821 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	822 </para>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	823
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	824 </section>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	825
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	826
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	827 <section name="Containers" id="containers">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	828
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	829
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	830 <section name="Array" id="array">
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 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	833 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	834 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	835
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	836
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	837 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	838 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	839 void *elts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	840 ngx_uint_t nelts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	841 size_t size;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	842 ngx_uint_t nalloc;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	843 ngx_pool_t *pool;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	844 } ngx_array_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	845 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	846
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	847 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	848 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	849 The <literal>nelts</literal> field holds the number of elements.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	850 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	851 when the array is initialized.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	852 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	853
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	854 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	855 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	856 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	857 call to initialize an array object that has already been allocated.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	858 </para>
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	861 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	862 ngx_array_t *a, b;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	863
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	864 /* create an array of strings with preallocated memory for 10 elements */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	865 a = ngx_array_create(pool, 10, sizeof(ngx_str_t));
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 /* initialize string array for 10 elements */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	868 ngx_array_init(&b, pool, 10, sizeof(ngx_str_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	869 </programlisting>
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>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	872 Use the following functions to add elements to an array:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	873 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	874
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	875 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	876 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	877
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	878 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	879 <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	880 to it
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	881 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	882
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	883 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	884 <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	885 and returns pointer to the first one
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	886 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	887
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	888 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	889 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	890
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	891 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	892 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	893 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	894 are copied to it.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	895 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	896 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	897
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	898
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	899 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	900 s = ngx_array_push(a);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	901 ss = ngx_array_push_n(&b, 3);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	902 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	903
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	904 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	905
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	906
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	907 <section name="List" id="list">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	908
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	909 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	910 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	911 large number of items.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	912 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	913 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	914
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	915
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	916 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	917 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	918 ngx_list_part_t *last;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	919 ngx_list_part_t part;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	920 size_t size;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	921 ngx_uint_t nalloc;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	922 ngx_pool_t *pool;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	923 } ngx_list_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	924 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	925
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	926 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	927 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	928 </para>
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	931 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	932 typedef struct ngx_list_part_s ngx_list_part_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	933
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	934 struct ngx_list_part_s {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	935 void *elts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	936 ngx_uint_t nelts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	937 ngx_list_part_t *next;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	938 };
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	939 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	940
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	941 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	942 Before use, a list must be initialized by calling
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	943 <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	944 <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	945 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	946 items per list part.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	947 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	948 function.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	949 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	950 example:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	951 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	952
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	953
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	954 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	955 ngx_str_t *v;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	956 ngx_uint_t i;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	957 ngx_list_t *list;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	958 ngx_list_part_t *part;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	959
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	960 list = ngx_list_create(pool, 100, sizeof(ngx_str_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	961 if (list == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	962
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	963 /* add items to the list */
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, "foo");
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 v = ngx_list_push(list);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	970 if (v == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	971 ngx_str_set(v, "bar");
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	972
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	973 /* iterate over the list */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	974
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	975 part = &list->part;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	976 v = part->elts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	977
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	978 for (i = 0; /* void */; i++) {
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 if (i >= part->nelts) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	981 if (part->next == NULL) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	982 break;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	983 }
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 part = part->next;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	986 v = part->elts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	987 i = 0;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	988 }
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 ngx_do_smth(&v[i]);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	991 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	992 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	993
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	994 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	995 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	996 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	997
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	998 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	999 Lists do not support item removal.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1000 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	1001 being removed from the list.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1002 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	1003 <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	1004 <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	1005 zero.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1006 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	1007 over.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1008 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1009
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1010 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1011
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1012
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1013 <section name="Queue" id="queue">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1014
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1015 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1016 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	1017 follows:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1018 </para>
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1021 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1022 typedef struct ngx_queue_s ngx_queue_t;
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 struct ngx_queue_s {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1025 ngx_queue_t *prev;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1026 ngx_queue_t *next;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1027 };
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1028 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1029
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1030 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1031 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	1032 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	1033 before use.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1034 Queues support the following operations:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1035 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1036
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1037 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1038 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1039
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1040 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1041 <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	1042 <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	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_remove(x)</literal> — Remove a queue node
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1047 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1048
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1049 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1050 <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	1051 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	1052 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1053
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1054 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1055 <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	1056 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1057
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1058 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1059 <literal>ngx_queue_head(h)</literal>,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1060 <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	1061 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1062
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1063 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1064 <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	1065 iteration at
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1066 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1067
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1068 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1069 <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	1070 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	1071 it
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1072 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1073
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1074 </list>
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1078 An example:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1079 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1080
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1081
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1082 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1083 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1084 ngx_str_t value;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1085 ngx_queue_t queue;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1086 } ngx_foo_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1087
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1088 ngx_foo_t *f;
2008 1f2f9fa97065 DevGuide: fixed queue example. Vladimir Homutov <vl@nginx.com> parents: 2007 diff changeset	1089 ngx_queue_t values, *q;
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1090
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1091 ngx_queue_init(&values);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1092
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1093 f = ngx_palloc(pool, sizeof(ngx_foo_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1094 if (f == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	1095 ngx_str_set(&f->value, "foo");
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1096
2008 1f2f9fa97065 DevGuide: fixed queue example. Vladimir Homutov <vl@nginx.com> parents: 2007 diff changeset	1097 ngx_queue_insert_tail(&values, &f->queue);
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1098
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1099 /* insert more nodes here */
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 for (q = ngx_queue_head(&values);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1102 q != ngx_queue_sentinel(&values);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1103 q = ngx_queue_next(q))
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 f = ngx_queue_data(q, ngx_foo_t, queue);
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 ngx_do_smth(&f->value);
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 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1110
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1111 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1112
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1113
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1114 <section name="Red-Black tree" id="red_black_tree">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1115
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1116 <para>
1915 8b7c3b0ef1a4 Semantically marked paths. Vladimir Homutov <vl@nginx.com> parents: 1914 diff changeset	1117 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	1118 effective implementation of red-black trees.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1119 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1120
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1121
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1122 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1123 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1124 ngx_rbtree_t rbtree;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1125 ngx_rbtree_node_t sentinel;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1126
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1127 /* custom per-tree data here */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1128 } my_tree_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1129
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1130 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1131 ngx_rbtree_node_t rbnode;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1132
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1133 /* custom per-node data */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1134 foo_t val;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1135 } my_node_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1136 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1137
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1138 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1139 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	1140 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	1141 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	1142 your data.
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 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1146 To initialize a tree:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1147 </para>
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
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 my_tree_t root;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1152
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1153 ngx_rbtree_init(&root.rbtree, &root.sentinel, insert_value_function);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1154 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1155
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1156 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1157 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	1158 "<literal>insert_value</literal>" functions.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1159 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	1160 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	1161 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	1162 node to be added, and a tree sentinel.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1163 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1164
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1165
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1166 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1167 void ngx_str_rbtree_insert_value(ngx_rbtree_node_t *temp,
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1168 ngx_rbtree_node_t *node,
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1169 ngx_rbtree_node_t *sentinel)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1170 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1171
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1172
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1173 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1174 The traversal is pretty straightforward and can be demonstrated with the
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1175 following lookup function pattern:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1176 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1177
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 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1180 my_node_t *
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1181 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	1182 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1183 ngx_int_t rc;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1184 my_node_t *n;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1185 ngx_rbtree_node_t node, sentinel;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1186
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1187 node = rbtree->root;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1188 sentinel = rbtree->sentinel;
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 while (node != sentinel) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1191
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1192 n = (my_node_t *) node;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1193
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1194 if (hash != node->key) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1195 node = (hash < node->key) ? node->left : node->right;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1196 continue;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1197 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1198
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1199 rc = compare(val, node->val);
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 if (rc < 0) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1202 node = node->left;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1203 continue;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1204 }
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 if (rc > 0) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1207 node = node->right;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1208 continue;
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1211 return n;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1212 }
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 return NULL;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1215 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1216 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1217
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1218 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1219 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	1220 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	1221 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	1222 hash field is used.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1223 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1224
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1225 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1226 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	1227 <literal>ngx_rbtree_insert()</literal>:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1228 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1229
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 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1232 my_node_t *my_node;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1233 ngx_rbtree_node_t *node;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1234
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1235 my_node = ngx_palloc(...);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1236 init_custom_data(&my_node->val);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1237
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1238 node = &my_node->rbnode;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1239 node->key = create_key(my_node->val);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1240
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1241 ngx_rbtree_insert(&root->rbtree, node);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1242 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1243
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1244 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1245 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	1246 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1247
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 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1250 ngx_rbtree_delete(&root->rbtree, node);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1251 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1252
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1253 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1254
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1255 <section name="Hash" id="hash">
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1256
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1257 <para>
1920 de5251816480 Fixed a typo. Vladimir Homutov <vl@nginx.com> parents: 1919 diff changeset	1258 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	1259 Both exact and wildcard matching are supported.
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1260 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	1261 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1262
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1263 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1264 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	1265 hold so that nginx can build it optimally.
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1266 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	1267 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	1268 <link doc="../hash.xml">document</link>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1269 They are usually configurable by the user.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1270 Hash initialization settings are stored with the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1271 <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	1272 <literal>ngx_hash_t</literal>:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1273 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1274 ngx_hash_t foo_hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1275 ngx_hash_init_t hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1276
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1277 hash.hash = &foo_hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1278 hash.key = ngx_hash_key;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1279 hash.max_size = 512;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1280 hash.bucket_size = ngx_align(64, ngx_cacheline_size);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1281 hash.name = "foo_hash";
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1282 hash.pool = cf->pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1283 hash.temp_pool = cf->temp_pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1284 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1285 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	1286 integer key from a string.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1287 There are two generic key-creation functions:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1288 <literal>ngx_hash_key(data, len)</literal> and
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1289 <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	1290 The latter converts a string to all lowercase characters, so the passed string
2422 eca8e37a34ef Fixed typos. Vladimir Homutov <vl@nginx.com> parents: 2412 diff changeset	1291 must be writable.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1292 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	1293 to the function, initializing the key array (see below).
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1294 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1295
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1296 <para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1297 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	1298 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	1299 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	1300 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	1301 <literal>NGX_HASH_LARGE</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1302 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	1303 elements.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1304
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1305 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1306 ngx_hash_keys_arrays_t foo_keys;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1307
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1308 foo_keys.pool = cf->pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1309 foo_keys.temp_pool = cf->temp_pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1310
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1311 ngx_hash_keys_array_init(&foo_keys, NGX_HASH_SMALL);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1312 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1313 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1314
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1315 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1316 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	1317 <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	1318 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1319 ngx_str_t k1 = ngx_string("key1");
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1320 ngx_str_t k2 = ngx_string("key2");
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1321
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1322 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	1323 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	1324 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1325 </para>
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1328 To build the hash table, call the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1329 <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	1330
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1331 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1332 ngx_hash_init(&hash, foo_keys.keys.elts, foo_keys.keys.nelts);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1333 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1334
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1335 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	1336 <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	1337 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1338
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1339 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1340 When the hash is built, use the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1341 <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	1342 elements:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1343 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1344 my_data_t *data;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1345 ngx_uint_t key;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1346
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1347 key = ngx_hash_key(k1.data, k1.len);
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 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	1350 if (data == NULL) {
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1351 /* key not found */
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 </programlisting>
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>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1356
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1357 <section name="Wildcard matching" id="wildcard_matching">
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1358
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1359 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1360 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	1361 <literal>ngx_hash_combined_t</literal> type.
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1362 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	1363 <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	1364 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	1365 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1366 ngx_hash_init_t hash
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1367 ngx_hash_combined_t foo_hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1368
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1369 hash.hash = &foo_hash.hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1370 hash.key = ...;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1371 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1372 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1373
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1374 <para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1375 It is possible to add wildcard keys using the
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1376 <literal>NGX_HASH_WILDCARD_KEY</literal> flag:
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1377 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1378 /* k1 = ".example.org"; */
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1379 /* k2 = "foo."; /
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1380 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	1381 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	1382 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1383 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	1384 Please refer to the
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1385 <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	1386 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	1387 matching algorithm.
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1388 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1389
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1390 <para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1391 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	1392 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	1393 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	1394 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1395 if (foo_keys.dns_wc_head.nelts) {
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1396
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1397 ngx_qsort(foo_keys.dns_wc_head.elts,
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1398 (size_t) foo_keys.dns_wc_head.nelts,
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1399 sizeof(ngx_hash_key_t),
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1400 cmp_dns_wildcards);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1401
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1402 hash.hash = NULL;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1403 hash.temp_pool = pool;
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 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	1406 foo_keys.dns_wc_head.nelts)
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1407 != NGX_OK)
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1408 {
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1409 return NGX_ERROR;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1410 }
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1411
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1412 foo_hash.wc_head = (ngx_hash_wildcard_t *) hash.hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1413 }
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1414 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1415 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	1416 to the combined hash.
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1417 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	1418 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1419
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1420 <para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1421 The lookup in a combined hash is handled by the
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1422 <literal>ngx_hash_find_combined(chash, key, name, len)</literal>:
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1423 <programlisting>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	1424 /* 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	1425 /* key = "foo.example.com"; — will match "foo." /
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1426
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1427 hkey = ngx_hash_key(key.data, key.len);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1428 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	1429 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1430 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1431
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1432 </section>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1433
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1434 </section>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1435
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1436 </section>
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1439 <section name="Memory management" id="memory_management">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1440
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1441
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1442 <section name="Heap" id="heap">
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>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1445 To allocate memory from system heap, use the following functions:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1446 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1447
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1448 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1449 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1450
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1451 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1452 <literal>ngx_alloc(size, log)</literal> — Allocate memory from system heap.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1453 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	1454 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	1455 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1456
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 <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	1459 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	1460 allocation.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1461 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1462
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1463 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1464 <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	1465 from system heap.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1466 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	1467 on those platforms that provide that function.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1468 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	1469 provides maximum alignment.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1470 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1471
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1472 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1473 <literal>ngx_free(p)</literal> — Free allocated memory.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1474 This is a wrapper around <literal>free()</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1475 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1476
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1477 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1478 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1479
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1480 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1481
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1482
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1483 <section name="Pool" id="pool">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1484
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1485 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1486 Most nginx allocations are done in pools.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1487 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	1488 destroyed.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1489 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	1490 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1491
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1492 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1493 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	1494 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	1495 block list.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1496 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	1497 is forwarded to the system allocator and the
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1498 returned pointer is stored in the pool for further deallocation.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1499 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1500
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1501 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1502 The type for nginx pools is <literal>ngx_pool_t</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1503 The following operations are supported:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1504 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1505
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1506 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1507 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1508
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1509 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1510 <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	1511 block size.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1512 The pool object returned is allocated in the pool as well.
2081 f29bd40e9a62 Development guide: documented ngx_create_pool() size requirements. Ruslan Ermilov <ru@nginx.com> parents: 2079 diff changeset	1513 The <literal>size</literal>
f29bd40e9a62 Development guide: documented ngx_create_pool() size requirements. Ruslan Ermilov <ru@nginx.com> parents: 2079 diff changeset	1514 should be at least <literal>NGX_MIN_POOL_SIZE</literal>
f29bd40e9a62 Development guide: documented ngx_create_pool() size requirements. Ruslan Ermilov <ru@nginx.com> parents: 2079 diff changeset	1515 and a multiple of <literal>NGX_POOL_ALIGNMENT</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1516 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1517
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1518 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1519 <literal>ngx_destroy_pool(pool)</literal> — Free all pool memory, including
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1520 the pool object itself.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1521 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1522
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1523 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1524 <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	1525 specified pool.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1528 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1529 <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	1530 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	1531 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1532
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1533 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1534 <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	1535 specified pool.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1536 Mostly used for allocating strings.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1537 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1538
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1539 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1540 <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	1541 allocated in the specified pool.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1542 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	1543 can be freed.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1544 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1545
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1546 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1547 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1548
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1549 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1550 u_char *p;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1551 ngx_str_t *s;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1552 ngx_pool_t *pool;
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 pool = ngx_create_pool(1024, log);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1555 if (pool == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1556
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1557 s = ngx_palloc(pool, sizeof(ngx_str_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1558 if (s == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	1559 ngx_str_set(s, "foo");
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1560
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1561 p = ngx_pnalloc(pool, 3);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1562 if (p == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	1563 ngx_memcpy(p, "foo", 3);
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1564 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1565
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1566 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1567 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	1568 so the nginx pool implementation provides a way to reuse them.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1569 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	1570 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	1571 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	1572 <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	1573 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	1574 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	1575 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	1576 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1577
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1578 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1579 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	1580 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	1581 destroyed.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1582 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	1583 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	1584 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	1585 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	1586 the main object.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1587 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1588
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1589 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1590 To register a pool cleanup, call
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1591 <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	1592 <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	1593 be filled in by the caller.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1594 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	1595 handler.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1596 </para>
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1599 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1600 ngx_pool_cleanup_t *cln;
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 cln = ngx_pool_cleanup_add(pool, 0);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1603 if (cln == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1604
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1605 cln->handler = ngx_my_cleanup;
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	1606 cln->data = "foo";
1899 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 ...
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 static void
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1611 ngx_my_cleanup(void *data)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1612 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1613 u_char *msg = data;
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 ngx_do_smth(msg);
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 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1618
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1619 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1620
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1621
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1622 <section name="Shared memory" id="shared_memory">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1623
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1624 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1625 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	1626 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	1627 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	1628 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	1629 of the zone.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1630 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	1631 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	1632 <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	1633 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	1634 different tag.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1635 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	1636 <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	1637 one nginx module.
1899 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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1640 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1641 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	1642 following fields:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1643 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1644
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1645 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1646 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1647
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1648 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1649 <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	1650 is mapped to actual memory
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1651 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1652
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1653 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1654 <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	1655 <literal>init</literal> callback
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1656 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1657
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1658 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1659 <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	1660 old cycle
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1661 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1662
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1663 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1664 <literal>tag</literal> — Shared zone tag
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1665 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1666
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 <literal>shm</literal> — Platform-specific object of type
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1669 <literal>ngx_shm_t</literal>, having at least the following fields:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1670 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1671
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1672 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1673 <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	1674 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1675
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1676 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1677 <literal>size</literal> — Shared memory size
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1678 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1679
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1680 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1681 <literal>name</literal> — Shared memory name
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1682 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1683
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1684 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1685 <literal>log</literal> — Shared memory log
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1686 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1687
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1688 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1689 <literal>exists</literal> — Flag that indicates shared memory was inherited
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1690 from the master process (Windows-specific)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1691 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1692
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1693 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1694 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1695
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1696 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1697 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1698
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1699 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1700 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	1701 <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	1702 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	1703 shared anonymous mapping.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1704 On Windows, the <literal>CreateFileMapping()</literal>/
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1705 <literal>MapViewOfFileEx()</literal> pair is used.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1706 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1707
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1708 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1709 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	1710 <literal>ngx_slab_pool_t</literal> type.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1711 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	1712 zone.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1713 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	1714 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	1715 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	1716 <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	1717 <literal>ngx_slab_calloc(pool, size)</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1718 To free memory, call <literal>ngx_slab_free(pool, p)</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1719 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1720
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1721 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1722 Slab pool divides all shared zone into pages.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1723 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	1724 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	1725 8 bytes.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1726 Nonconforming values are rounded up.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1727 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	1728 allocation.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1729 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	1730 done an entire page at a time
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1731 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1732
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1733 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1734 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	1735 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	1736 <literal>ngx_slab_pool_t</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1737 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	1738 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	1739 in the shared zone.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1740 To lock or unlock a mutex, call
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1741 <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	1742 <literal>ngx_shmtx_unlock(&shpool->mutex)</literal> respectively.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1743 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1744
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1745
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1746 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1747 ngx_str_t name;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1748 ngx_foo_ctx_t *ctx;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1749 ngx_shm_zone_t *shm_zone;
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 ngx_str_set(&name, "foo");
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1752
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1753 /* allocate shared zone context */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1754 ctx = ngx_pcalloc(cf->pool, sizeof(ngx_foo_ctx_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1755 if (ctx == NULL) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1756 /* error */
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
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1759 /* add an entry for 64k shared zone */
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1760 shm_zone = ngx_shared_memory_add(cf, &name, 65536, &ngx_foo_module);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1761 if (shm_zone == NULL) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1762 /* error */
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 /* register init callback and context */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1766 shm_zone->init = ngx_foo_init_zone;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1767 shm_zone->data = ctx;
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
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1772
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1773 static ngx_int_t
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1774 ngx_foo_init_zone(ngx_shm_zone_t shm_zone, void data)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1775 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1776 ngx_foo_ctx_t *octx = data;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1777
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1778 size_t len;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1779 ngx_foo_ctx_t *ctx;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1780 ngx_slab_pool_t *shpool;
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 value = shm_zone->data;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1783
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1784 if (octx) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1785 /* reusing a shared zone from old cycle */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1786 ctx->value = octx->value;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1787 return NGX_OK;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1788 }
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 shpool = (ngx_slab_pool_t *) shm_zone->shm.addr;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1791
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1792 if (shm_zone->shm.exists) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1793 /* initialize shared zone context in Windows nginx worker */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1794 ctx->value = shpool->data;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1795 return NGX_OK;
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 /* initialize shared zone */
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 ctx->value = ngx_slab_alloc(shpool, sizeof(ngx_uint_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1801 if (ctx->value == NULL) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1802 return NGX_ERROR;
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1805 shpool->data = ctx->value;
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 return NGX_OK;
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 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1810
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1811 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1812
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1813
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1814 </section>
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1817 <section name="Logging" id="logging">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1818
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1819 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1820 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	1821 The nginx logger supports several types of output:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1822
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1823 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1824
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1825 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1826 stderr — Logging to standard error (stderr)
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1827 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1828
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1829 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1830 file — Logging to a file
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1831 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1832
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1833 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1834 syslog — Logging to syslog
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1835 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1836
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1837 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1838 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	1839 can be accessed later with a debugger
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1840 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1841
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1842 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1843 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1844
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1845 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1846 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	1847 the <literal>next</literal> field.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1848 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	1849 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1850
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1851 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1852 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	1853 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	1854 The following severity levels are supported:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1855 </para>
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 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1858 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1859
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1860 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1861 <literal>NGX_LOG_EMERG</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1862 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1863
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1864 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1865 <literal>NGX_LOG_ALERT</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1866 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1867
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1868 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1869 <literal>NGX_LOG_CRIT</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1870 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1871
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1872 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1873 <literal>NGX_LOG_ERR</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1874 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1875
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1876 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1877 <literal>NGX_LOG_WARN</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1878 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1879
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1880 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1881 <literal>NGX_LOG_NOTICE</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1882 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1883
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1884 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1885 <literal>NGX_LOG_INFO</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1886 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1887
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1888 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1889 <literal>NGX_LOG_DEBUG</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1890 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1891
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1892 </list>
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1895 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1896 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	1897 The debug masks are:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1898 </para>
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 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1901 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1902
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1903 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1904 <literal>NGX_LOG_DEBUG_CORE</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1905 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1906
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1907 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1908 <literal>NGX_LOG_DEBUG_ALLOC</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1909 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1910
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1911 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1912 <literal>NGX_LOG_DEBUG_MUTEX</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1913 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1914
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1915 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1916 <literal>NGX_LOG_DEBUG_EVENT</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1917 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1918
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1919 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1920 <literal>NGX_LOG_DEBUG_HTTP</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1921 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1922
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1923 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1924 <literal>NGX_LOG_DEBUG_MAIL</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1925 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1926
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1927 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1928 <literal>NGX_LOG_DEBUG_STREAM</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1929 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1930
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1931 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1932 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1933
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1934 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1935 Normally, loggers are created by existing nginx code from
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1936 <literal>error_log</literal> directives and are available at nearly every stage
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1937 of processing in cycle, configuration, client connection and other objects.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1938 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1939
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1940 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1941 Nginx provides the following logging macros:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1942 </para>
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 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1945 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1946
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1947 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1948 <literal>ngx_log_error(level, log, err, fmt, ...)</literal> — Error logging
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1949 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1950
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1951 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1952 <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	1953 <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	1954 logging with up to eight supported formatting arguments
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1955 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1956
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1957 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1958 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1959
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1960 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1961 A log message is formatted in a buffer of size
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1962 <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	1963 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	1964 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	1965 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	1966 prepend more specific information to the log message.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1967 HTTP module sets <literal>ngx_http_log_error()</literal> function as log
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1968 handler to log client and server addresses, current action (stored in
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1969 <literal>log->action</literal>), client request line, server name etc.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1970 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1971
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1972 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1973 /* specify what is currently done */
2258 2c8c10f00518 Development guide: fixed quotes encoding in <programlisting>. Sergey Kandaurov <pluknet@nginx.com> parents: 2170 diff changeset	1974 log->action = "sending mp4 to client";
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1975
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1976 /* error and debug log */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1977 ngx_log_error(NGX_LOG_INFO, c->log, 0, "client prematurely
2258 2c8c10f00518 Development guide: fixed quotes encoding in <programlisting>. Sergey Kandaurov <pluknet@nginx.com> parents: 2170 diff changeset	1978 closed connection");
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1979
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1980 ngx_log_debug2(NGX_LOG_DEBUG_HTTP, mp4->file.log, 0,
2258 2c8c10f00518 Development guide: fixed quotes encoding in <programlisting>. Sergey Kandaurov <pluknet@nginx.com> parents: 2170 diff changeset	1981 "mp4 start:%ui, length:%ui", mp4->start, mp4->length);
1899 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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1984 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1985 The example above results in log entries like these:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1986 </para>
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1989 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1990 2016/09/16 22:08:52 [info] 17445#0: *1 client prematurely closed connection while
2258 2c8c10f00518 Development guide: fixed quotes encoding in <programlisting>. Sergey Kandaurov <pluknet@nginx.com> parents: 2170 diff changeset	1991 sending mp4 to client, client: 127.0.0.1, server: , request: "GET /file.mp4 HTTP/1.1"
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1992 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	1993 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1994
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1995 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1996
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1997
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1998 <section name="Cycle" id="cycle">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1999
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2000 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2001 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	2002 configuration.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2003 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	2004 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	2005 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	2006 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	2007 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	2008 successfully created.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2009 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2010
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 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	2013 takes the previous cycle as its argument.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2014 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	2015 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	2016 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	2017 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	2018 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2019
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2020 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2021 Members of the cycle include:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2022 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2023
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2024 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2025 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2026
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2027 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2028 <literal>pool</literal> — Cycle pool.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2029 Created for each new cycle.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2030 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2031
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2032 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2033 <literal>log</literal> — Cycle log.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2034 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	2035 <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	2036 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2037
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2038 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2039 <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	2040 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	2041 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2042
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2043 <listitem>
1981 082724c57c38 Fixes in cycle section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1980 diff changeset	2044 <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	2045 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	2046 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	2047 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	2048 sets the number of connections <literal>connection_n</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2049 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2050
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2051 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2052 <literal>free_connections</literal>,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2053 <literal>free_connection_n</literal> — List and number of currently available
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2054 connections.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2055 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	2056 or connect to upstream servers.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2057 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2058
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2059 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2060 <literal>files</literal>, <literal>files_n</literal> — Array for mapping file
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2061 descriptors to nginx connections.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2062 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	2063 <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	2064 <literal>poll</literal> and <literal>devpoll</literal>).
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2065 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2066
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2067 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2068 <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	2069 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	2070 files.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2071 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2072
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2073 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2074 <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	2075 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	2076 the current configuration.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2077 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2078
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 <literal>listening</literal> — Array of listening objects of type
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2081 <literal>ngx_listening_t</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2082 Listening objects are normally added by the <literal>listen</literal>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2083 directive of different modules which call the
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2084 <literal>ngx_create_listening()</literal> function.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2085 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	2086 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2087
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2088 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2089 <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	2090 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	2091 modules which are going to operate on certain directories.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2092 These directories are created by nginx after reading configuration, if missing.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2093 Moreover, two handlers can be added for each path:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2094
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2095 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2096
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2097 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2098 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	2099 nginx.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2100 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	2101 memory.
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 process “nginx cache loader”.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2103 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2104
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2105 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2106 path manager — Executes periodically.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2107 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	2108 memory to reflect the changes.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2109 The handler is called from the dedicated “nginx cache manager” process.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2110 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2111
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2112 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2113 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2114
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2115 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2116 <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	2117 <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	2118 <literal>ngx_conf_open_file()</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2119 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	2120 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	2121 <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	2122 object's <literal>fd</literal> field.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2123 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	2124 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	2125 reopen signal (most often <literal>USR1</literal>).
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2126 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	2127 new value.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2128 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2129
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2130 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2131 <literal>shared_memory</literal> — List of shared memory zones, each added by
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2132 calling the <literal>ngx_shared_memory_add()</literal> function.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2133 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	2134 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	2135 </listitem>
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 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2138 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2139
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2140 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2141
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2142 <section name="Buffer" id="buffer">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2143
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2144 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2145 For input/output operations, nginx provides the buffer type
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2146 <literal>ngx_buf_t</literal>.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2147 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	2148 source.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2149 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	2150 possible for a buffer to reference both at the same time.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2151 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	2152 structure <literal>ngx_buf_t</literal>.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2153 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2154
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2155 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2156 The <literal>ngx_buf_t</literal> structure has the following fields:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2157 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2158
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2159 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2160 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2161
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2162 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2163 <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	2164 block allocated for the buffer.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2165 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2166
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2167 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2168 <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	2169 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	2170 <literal>end</literal>.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2173 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2174 <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	2175 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	2176 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2177
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 <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	2180 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	2181 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2182
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2183 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2184 <literal>file</literal> — File object.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2185 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2186
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2187 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2188 <literal>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	2189 writable memory.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2190 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2191
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2192 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2193 <literal>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	2194 memory.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2197 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2198 <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	2199 in a file.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2202 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2203 <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	2204 need to be flushed.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2207 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2208 <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	2209 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	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>sync</literal> — Flag indicating that the buffer carries no data or
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2214 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	2215 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	2216 nginx to skip the error check.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2219 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2220 <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	2221 output.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2224 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2225 <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	2226 buffers in a request or subrequest.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2227 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2228
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2229 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2230 <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	2231 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	2232 shadow.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2233 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	2234 consumed.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2237 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2238 <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	2239 one that references a particular shadow buffer.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2240 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2241
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2242 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2243 <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	2244 file.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2245 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2246
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2247 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2248 </para>
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2251 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	2252 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	2253 defined as follows:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2254 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2255
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2256
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 typedef struct ngx_chain_s ngx_chain_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2259
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2260 struct ngx_chain_s {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2261 ngx_buf_t *buf;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2262 ngx_chain_t *next;
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 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2265
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 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	2268 chain link.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2269 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2270
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2271 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2272 An example of using buffers and chains:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2273 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2274
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 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2277 ngx_chain_t *
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2278 ngx_get_my_chain(ngx_pool_t *pool)
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 ngx_buf_t *b;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2281 ngx_chain_t out, cl, **ll;
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 /* first buf */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2284 cl = ngx_alloc_chain_link(pool);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2285 if (cl == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2286
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2287 b = ngx_calloc_buf(pool);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2288 if (b == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2289
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2290 b->start = (u_char *) "foo";
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2291 b->pos = b->start;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2292 b->end = b->start + 3;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2293 b->last = b->end;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2294 b->memory = 1; /* read-only memory */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2295
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2296 cl->buf = b;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2297 out = cl;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2298 ll = &cl->next;
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 /* second buf */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2301 cl = ngx_alloc_chain_link(pool);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2302 if (cl == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2303
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2304 b = ngx_create_temp_buf(pool, 3);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2305 if (b == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2306
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2307 b->last = ngx_cpymem(b->last, "foo", 3);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2308
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2309 cl->buf = b;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2310 cl->next = NULL;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2311 *ll = cl;
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 return out;
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 </programlisting>
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>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2318
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2319
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2320 <section name="Networking" id="networking">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2321
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2322
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 name="Network data types" id="network_data_types">
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 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2327 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	2328 address...
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2329 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2330
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2331 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2332 -->
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2333
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2334 <section name="Connection" id="connection">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2335
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2336 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2337 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	2338 socket descriptor.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2339 It includes the following fields:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2340 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2341
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2342 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2343 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2344
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2345 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2346 <literal>fd</literal> — Socket descriptor
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2347 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2348
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2349 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2350 <literal>data</literal> — Arbitrary connection context.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2351 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	2352 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	2353 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2354
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2355 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2356 <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	2357 the connection.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2358 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2359
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2360 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2361 <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	2362 <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	2363 for the connection.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2364 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2365
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2366 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2367 <literal>pool</literal> — Connection pool.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2368 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2369
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 <literal>log</literal> — Connection log.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2372 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2373
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2374 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2375 <literal>sockaddr</literal>, <literal>socklen</literal>,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2376 <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	2377 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2378
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2379 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2380 <literal>local_sockaddr</literal>, <literal>local_socklen</literal> — Local
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2381 socket address in binary form.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2382 Initially, these fields are empty.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2383 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	2384 local socket address.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2385 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2386
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2387 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2388 <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	2389 - 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	2390 the connection.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2391 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2392
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2393 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2394 <literal>ssl</literal> — SSL context for the connection.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2397 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2398 <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	2399 makes it eligible for reuse.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2400 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2401
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2402 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2403 <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	2404 and needs to be closed.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2405 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2406
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2407 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2408 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2409
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2410 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2411 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	2412 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	2413 <literal>ngx_ssl_connection_t</literal> structure, keeping all SSL-related data
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2414 for the connection, including <literal>SSL_CTX</literal> and
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2415 <literal>SSL</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2416 The <literal>recv</literal>, <literal>send</literal>,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2417 <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	2418 set to SSL-enabled functions as well.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2419 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2420
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2421 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2422 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	2423 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	2424 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	2425 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	2426 To retrieve a connection structure, use the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2427 <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	2428 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	2429 to be wrapped in a connection structure.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2430 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2431
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2432 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2433 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	2434 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	2435 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	2436 <literal>ngx_reusable_connection(c, reusable)</literal> function.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2437 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	2438 <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	2439 connection into the <literal>reusable_connections_queue</literal> of the cycle.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2440 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	2441 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	2442 it calls <literal>ngx_drain_connections()</literal> to release a
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2443 specific number of reusable connections.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2444 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	2445 handler is called which is supposed to free the connection by calling
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2446 <literal>ngx_close_connection(c)</literal> and make it available for reuse.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2447 To exit the state when a connection can be reused
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2448 <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	2449 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	2450 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	2451 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2452
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2453 </section>
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2456 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2457
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2458
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2459 <section name="Events" id="events">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2460
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2461
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2462 <section name="Event" id="event">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2463
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2464 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2465 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	2466 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	2467 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2468
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2469 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2470 Fields in <literal>ngx_event_t</literal> include:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2471 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2472
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2473 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2474 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2475
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2476 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2477 <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	2478 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	2479 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2480
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2481 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2482 <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	2483 happens.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2486 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2487 <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	2488 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	2489 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2490
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2491 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2492 <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	2493 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	2494 <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	2495 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2496
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2497 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2498 <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	2499 I/O notification.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2502 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2503 <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	2504 limiting.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2507 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2508 <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	2509 the timer tree.
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
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 <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	2514 not yet expired.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2515 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2516
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2517 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2518 <literal>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	2519 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2520
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2521 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2522 <literal>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	2523 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2524
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2525 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2526 <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	2527 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	2528 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	2529 <literal>epoll</literal> event or
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2530 <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	2531 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2532
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2533 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2534 <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	2535 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	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>
1995 80f53da7280c Updated cancelable event description in the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1994 diff changeset	2539 <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	2540 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	2541 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	2542 events scheduled.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2543 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2544
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2545 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2546 <literal>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	2547 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2548
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2549 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2550 <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	2551 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2552
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2553 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2554 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2555
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2556 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2557
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2558
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2559 <section name="I/O events" id="i_o_events">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2560
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2561 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2562 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	2563 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	2564 <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	2565 socket is ready for reading or writing.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2566 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	2567 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	2568 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	2569 repeated read notification until more data arrives on the socket.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2570 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	2571 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	2572 converts the notifications to Edge-Triggered.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2573 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	2574 on different platforms, the functions
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2575 <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	2576 <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	2577 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	2578 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	2579 event handler.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2580 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2581
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2582 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2583
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2584
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2585 <section name="Timer events" id="timer_events">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2586
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2587 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2588 An event can be set to send a notification when a timeout expires.
2170 2bc348966475 Development guide: updated Time and Events chapters. Vladimir Homutov <vl@nginx.com> parents: 2153 diff changeset	2589 The timer used by events counts milliseconds since some unspecified point
2bc348966475 Development guide: updated Time and Events chapters. Vladimir Homutov <vl@nginx.com> parents: 2153 diff changeset	2590 in the past truncated to <literal>ngx_msec_t</literal> type.
2bc348966475 Development guide: updated Time and Events chapters. Vladimir Homutov <vl@nginx.com> parents: 2153 diff changeset	2591 Its current value can be obtained from the <literal>ngx_current_msec</literal>
2bc348966475 Development guide: updated Time and Events chapters. Vladimir Homutov <vl@nginx.com> parents: 2153 diff changeset	2592 variable.
2bc348966475 Development guide: updated Time and Events chapters. Vladimir Homutov <vl@nginx.com> parents: 2153 diff changeset	2593 </para>
2bc348966475 Development guide: updated Time and Events chapters. Vladimir Homutov <vl@nginx.com> parents: 2153 diff changeset	2594
2bc348966475 Development guide: updated Time and Events chapters. Vladimir Homutov <vl@nginx.com> parents: 2153 diff changeset	2595 <para>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2596 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	2597 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	2598 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	2599 stores all timeouts currently set.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2600 The key in the tree is of type <literal>ngx_msec_t</literal> and is the time
2170 2bc348966475 Development guide: updated Time and Events chapters. Vladimir Homutov <vl@nginx.com> parents: 2153 diff changeset	2601 when the event occurs.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2602 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	2603 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	2604 for I/O events and for expiring timeout events.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2605 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2606
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2607 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2608
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2609
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2610 <section name="Posted events" id="posted_events">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2611
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2612 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2613 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	2614 point later within the current event loop iteration.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2615 Posting events is a good practice for simplifying code and escaping stack
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2616 overflows.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2617 Posted events are held in a post queue.
2422 eca8e37a34ef Fixed typos. Vladimir Homutov <vl@nginx.com> parents: 2412 diff changeset	2618 The <literal>ngx_post_event(ev, q)</literal> macro posts the event
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2619 <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	2620 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	2621 <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	2622 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	2623 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	2624 events are already handled.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2625 The function <literal>ngx_event_process_posted()</literal> is called to process
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2626 an event queue.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2627 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	2628 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	2629 within the current event loop iteration.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2630 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2631
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2632 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2633 An example:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2634 </para>
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2637 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2638 void
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2639 ngx_my_connection_read(ngx_connection_t *c)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2640 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2641 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 rev = c->read;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2644
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2645 ngx_add_timer(rev, 1000);
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 rev->handler = ngx_my_read_handler;
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 ngx_my_read(rev);
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2652
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2653 void
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2654 ngx_my_read_handler(ngx_event_t *rev)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2655 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2656 ssize_t n;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2657 ngx_connection_t *c;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2658 u_char buf[256];
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2659
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2660 if (rev->timedout) { /* timeout expired */ }
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 c = rev->data;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2663
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2664 while (rev->ready) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2665 n = c->recv(c, buf, sizeof(buf));
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 if (n == NGX_AGAIN) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2668 break;
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2671 if (n == NGX_ERROR) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2672
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2673 /* process buf */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2674 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2675
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2676 if (ngx_handle_read_event(rev, 0) != NGX_OK) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2677 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2678 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2679
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2680 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2681
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2682
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2683 <section name="Event loop" id="event_loop">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2684
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2685 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2686 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	2687 event loop.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2688 (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	2689 <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	2690 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	2691 <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	2692 repeatedly until the process exits.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2693 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2694
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2695 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2696 The event loop has the following stages:
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2697
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2698 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2699
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2700 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2701 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	2702 <literal>ngx_event_find_timer()</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2703 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	2704 number of milliseconds until the node expires.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2705 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2706
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2707 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2708 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	2709 mechanism, chosen by nginx configuration.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2710 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	2711 timeout expires.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2712 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	2713 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	2714 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	2715 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	2716 events.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2717 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2718
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2719 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2720 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	2721 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	2722 unexpired timeout is found.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2723 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	2724 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	2725 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2726
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2727 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2728 Process posted events by calling <literal>ngx_event_process_posted()</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2729 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	2730 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	2731 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2732
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2733 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2734 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2735
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2736 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2737 All nginx processes handle signals as well.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2738 Signal handlers only set global variables which are checked after the
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2739 <literal>ngx_process_events_and_timers()</literal> call.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2740 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2741
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2742 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2743
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 </section>
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2748 <section name="Processes" id="processes">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2749
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2750 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2751 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	2752 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	2753 global variable, and is one of the following:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2754 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2755
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2756 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2757
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2758 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2759
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2760 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2761 <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	2762 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	2763 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	2764 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	2765 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2766
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2767
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2768 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2769
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2770 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2771
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2772 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2773 <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	2774 connections.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2775 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	2776 commands as well.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2777 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	2778 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	2779 <literal>worker_processes</literal> directive.
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_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	2788 <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	2789 that mode.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2790 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	2791 (like the worker process does).
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2792 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	2793 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2794
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2795 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2796
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2797 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2798
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2799 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2800 <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	2801 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	2802 The cycle function for both is
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2803 <literal>ngx_cache_manager_process_cycle()</literal>.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2804 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2805
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2806 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2807
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2808 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2809
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2810 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2811 The nginx processes handle the following signals:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2812 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2813
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2814 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2815
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2816 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2817
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2818 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2819 <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	2820 systems) — Gracefully shutdown.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2821 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	2822 child processes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2823 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	2824 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	2825 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	2826 cycle pool and exits.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2827 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	2828 exits immediately.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2829 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	2830 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	2831 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	2832 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	2833 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2834
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2835 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2836
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2837 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2838
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 <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	2841 systems) — Terminate.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2842 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	2843 child processes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2844 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	2845 <literal>SIGKILL</literal> signal to kill it.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2846 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	2847 exits.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2848 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	2849 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	2850 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	2851 when this signal is received.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2852 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2853
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2854 </listitem>
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 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2859 <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	2860 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	2861 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	2862 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	2863 master are started again.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2864 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	2865 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	2866 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2867
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2868
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2869 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2870
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2871 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2872
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2873 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2874 <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	2875 systems) - Reconfigure.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2876 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	2877 creates a new cycle based on it.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2878 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	2879 child processes are started.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2880 Meanwhile, the old child processes receive the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2881 <literal>NGX_SHUTDOWN_SIGNAL</literal> signal.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2882 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	2883 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	2884 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	2885 </para>
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 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2890
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2891 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2892 <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	2893 systems) — Reopen files.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2894 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	2895 <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	2896 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2897
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2898 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2899
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2900 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2901
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2902 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2903 <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	2904 systems) — Change the nginx binary.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2905 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	2906 sockets.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2907 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	2908 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	2909 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	2910 sockets to its init cycle.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2911 Other processes ignore this signal.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2912 </para>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2913
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2914 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2915
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2916 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2917
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2918 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2919 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	2920 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	2921 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	2922 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	2923 between all nginx processes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2924 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	2925 The messages carry the standard signals.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2926 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2927
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2928 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2929
1983 7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2930 <section name="Threads" id="threads">
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2931
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2932 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2933 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	2934 block the nginx worker process.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2935 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	2936 <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	2937 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	2938 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	2939 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	2940 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	2941 intended as a replacement.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2942 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2943
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2944 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2945 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	2946 <literal>pthreads</literal> primitives are available:
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2947
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2948 <list type="bullet">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2949
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2950 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2951 <literal>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	2952
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2953 <list type="bullet">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2954
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2955 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2956 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2957 ngx_thread_mutex_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	2958 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2959
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2960 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2961 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2962 ngx_thread_mutex_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	2963 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2964
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2965 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2966 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2967 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	2968 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2969
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2970 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2971 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2972 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	2973 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2974
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2975 </list>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2976
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2977 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2978
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2979 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2980 <literal>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	2981
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2982 <list type="bullet">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2983
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2984 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2985 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2986 ngx_thread_cond_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	2987 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2988
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2989 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2990 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2991 ngx_thread_cond_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	2992 </listitem>
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 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2996 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	2997 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2998
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2999 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3000 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3001 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	3002 ngx_log_t *log);</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3003 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3004
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3005 </list>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3006
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3007 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3008
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3009 </list>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3010
1983 7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3011 </para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3012
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3013 <para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3014 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	3015 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	3016 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	3017 (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	3018 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	3019 that process a queue of tasks.
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3020 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	3021 </para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3022
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3023 <para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3024 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	3025 relevant definitions:
1983 7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3026 <programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3027 struct ngx_thread_task_s {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3028 ngx_thread_task_t *next;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3029 ngx_uint_t id;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3030 void *ctx;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3031 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	3032 ngx_event_t event;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3033 };
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3034
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3035 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	3036
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3037 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	3038 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	3039
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3040 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	3041 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	3042
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3043 </programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3044 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	3045 reference to a thread pool by calling
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3046 <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	3047 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	3048 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	3049 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3050
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3051 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3052 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	3053 <literal>tp</literal> at runtime, use the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3054 <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	3055
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3056 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	3057 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	3058 <programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3059 typedef struct {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3060 int foo;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3061 } my_thread_ctx_t;
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
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3064 static void
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3065 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	3066 {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3067 my_thread_ctx_t *ctx = data;
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 /* 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	3070 }
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3071
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3072
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3073 static void
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3074 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	3075 {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3076 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	3077
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3078 /* executed in nginx event loop */
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
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 ngx_int_t
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3083 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	3084 {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3085 my_thread_ctx_t *ctx;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3086 ngx_thread_task_t *task;
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 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	3089 if (task == NULL) {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3090 return NGX_ERROR;
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
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3093 ctx = task->ctx;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3094
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3095 ctx->foo = 42;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3096
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3097 task->handler = my_thread_func;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3098 task->event.handler = my_thread_completion;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3099 task->event.data = ctx;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3100
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3101 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	3102 return NGX_ERROR;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3103 }
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3104
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3105 return NGX_OK;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3106 }
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3107 </programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3108
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3109 </para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3110
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3111 </section>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3112
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3113
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3114 <section name="Modules" id="Modules">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3115
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3116 <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	3117 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3118 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	3119 at least two files:
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3120 <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	3121 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	3122 integrate the module, for example:
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3123 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3124 ngx_module_type=CORE
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3125 ngx_module_name=ngx_foo_module
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3126 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	3127
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3128 . auto/module
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3129
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3130 ngx_addon_name=$ngx_module_name
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3131 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3132 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	3133 and access the following variables:
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3134 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3135
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3136 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3137 <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	3138 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	3139 <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	3140 <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	3141 <literal>STREAM</literal>, or <literal>MISC</literal>.
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_name</literal> — Module names.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3146 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	3147 whitespace-separated list of names.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3148 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	3149 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	3150 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3151
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3152 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3153 <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	3154 on the console from the configure script.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3155 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3156
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3157 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3158 <literal>ngx_module_srcs</literal> — Whitespace-separated list of source
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3159 files used to compile the module.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3160 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	3161 to the module directory.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3162 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3163
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3164 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3165 <literal>ngx_module_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	3166 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3167
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3168 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3169 <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	3170 dependencies.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3171 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	3172 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3173
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3174 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3175 <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	3176 link with the module.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3177 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	3178 <literal>libpthread</literal> library.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3179 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	3180 nginx:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3181 <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	3182 <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	3183 <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	3184 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3185
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3186 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3187 <literal>ngx_module_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	3188 <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	3189 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	3190 depending on linking type.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3191 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3192
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3193 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3194 <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	3195 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	3196 <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	3197 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	3198 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	3199 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	3200 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	3201
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3202 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3203 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	3204 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	3205 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	3206 the first to be executed.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3207 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	3208 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	3209 executed.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3210 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3211
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3212 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3213 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	3214 <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	3215 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	3216 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	3217 </para>
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 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3220
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3221 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3222
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3223 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	3224 <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	3225 script.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3226 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	3227 <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	3228 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3229
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3230 </section>
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
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3233 <section name="Core Modules" id="core_modules">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3234
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3235 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3236 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	3237 implemented as modules.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3238 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	3239 <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	3240 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3241 struct ngx_module_s {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3242
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3243 /* private part is omitted */
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 *ctx;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3246 ngx_command_t *commands;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3247 ngx_uint_t type;
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 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	3250
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3251 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	3252
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3253 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	3254 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	3255 void (exit_thread)(ngx_cycle_t cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3256 void (exit_process)(ngx_cycle_t cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3257
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3258 void (exit_master)(ngx_cycle_t cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3259
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3260 /* stubs for future extensions are omitted */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3261 };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3262 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3263 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	3264 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	3265 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3266
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3267 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3268 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	3269 recognizes the configuration directives, specified in the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3270 <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	3271 nginx lifecycle.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3272 The module lifecycle consists of the following events:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3273
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3274 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3275
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3276 <listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3277 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	3278 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	3279 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3280
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3281 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3282 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	3283 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	3284 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	3285 time a configuration is loaded.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3286 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3287
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3288 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3289 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	3290 <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	3291 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3292
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3293 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3294 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	3295 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	3296 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3297
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3298 <listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3299 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	3300 exiting.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3301 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3302
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3303 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3304
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3305 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	3306 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	3307 handlers are not currently called.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3308 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	3309 unnecessary overhead.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3310 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3311
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3312 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3313 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	3314 <literal>ctx</literal> field.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3315 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	3316 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3317 <listitem><literal>NGX_CORE_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3318 <listitem><literal>NGX_EVENT_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3319 <listitem><literal>NGX_HTTP_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3320 <listitem><literal>NGX_MAIL_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3321 <listitem><literal>NGX_STREAM_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3322 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3323 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	3324 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	3325 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	3326 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	3327 requests.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3328 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3329
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3330 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3331 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	3332 <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	3333 <literal>ngx_thread_pool_module</literal> and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3334 <literal>ngx_openssl_module</literal> modules.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3335 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	3336 modules too.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3337 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	3338 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3339 typedef struct {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3340 ngx_str_t name;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3341 void (create_conf)(ngx_cycle_t *cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3342 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	3343 } ngx_core_module_t;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3344 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3345 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	3346 <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	3347 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	3348 respectively.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3349 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	3350 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	3351 is parsed successfully.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3352 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	3353 configuration and sets default values.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3354 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3355
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3356 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3357 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	3358 look like this:
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3359 <programlisting>
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 * Copyright (C) Author.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3362 */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3363
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3364
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3365 #include <ngx_config.h>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3366 #include <ngx_core.h>
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
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3369 typedef struct {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3370 ngx_flag_t enable;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3371 } ngx_foo_conf_t;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3372
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3373
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3374 static 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	3375 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	3376
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3377 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	3378 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	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_command_t ngx_foo_commands[] = {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3382
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3383 { ngx_string("foo_enabled"),
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3384 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	3385 ngx_conf_set_flag_slot,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3386 0,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3387 offsetof(ngx_foo_conf_t, enable),
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3388 &ngx_foo_enable_post },
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3389
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3390 ngx_null_command
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3391 };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3392
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3393
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3394 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	3395 ngx_string("foo"),
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3396 ngx_foo_create_conf,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3397 ngx_foo_init_conf
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3398 };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3399
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3400
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3401 ngx_module_t ngx_foo_module = {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3402 NGX_MODULE_V1,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3403 &ngx_foo_module_ctx, /* module context */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3404 ngx_foo_commands, /* module directives */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3405 NGX_CORE_MODULE, /* module type */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3406 NULL, /* init master */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3407 NULL, /* init module */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3408 NULL, /* init process */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3409 NULL, /* init thread */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3410 NULL, /* exit thread */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3411 NULL, /* exit process */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3412 NULL, /* exit master */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3413 NGX_MODULE_V1_PADDING
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3414 };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3415
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3416
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3417 static void *
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3418 ngx_foo_create_conf(ngx_cycle_t *cycle)
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 ngx_foo_conf_t *fcf;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3421
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3422 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	3423 if (fcf == NULL) {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3424 return NULL;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3425 }
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3426
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3427 fcf->enable = NGX_CONF_UNSET;
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 return fcf;
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
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3432
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3433 static char *
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3434 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	3435 {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3436 ngx_foo_conf_t *fcf = conf;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3437
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3438 ngx_conf_init_value(fcf->enable, 0);
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 return NGX_CONF_OK;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3441 }
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3442
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3443
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3444 static char *
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3445 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	3446 {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3447 ngx_flag_t *fp = data;
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 if (*fp == 0) {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3450 return NGX_CONF_OK;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3451 }
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3452
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3453 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	3454
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3455 return NGX_CONF_OK;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3456 }
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3457 </programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3458 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3459
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3460 </section>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3461
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3462
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3463 <section name="Configuration Directives" id="config_directives">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3464
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3465 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3466 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	3467 directive.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3468 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	3469 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	3470 <programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3471 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	3472
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3473 struct ngx_command_s {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3474 ngx_str_t name;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3475 ngx_uint_t type;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3476 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	3477 ngx_uint_t conf;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3478 ngx_uint_t offset;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3479 void *post;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3480 };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3481 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3482 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	3483 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	3484 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	3485 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	3486 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	3487 The flags are:
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3488
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3489 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3490
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3491 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3492 <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	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_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	3497 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3498
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3499 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3500 <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	3501 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3502
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 <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	3505 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	3506 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3507
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3508 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3509 <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	3510 <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	3511 <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	3512 arguments.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3513 Options are limited to the given numbers.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3514 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	3515 arguments.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3516 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3517
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3518 </list>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3519
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3520 The flags for directive types are:
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3521
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3522 <list type="bullet">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3523
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3524 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3525 <literal>NGX_CONF_BLOCK</literal> — Directive is a block, that is, it can
2153 ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	3526 contain other directives within its opening and closing braces, or even
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3527 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	3528 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3529
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 <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	3532 <literal>on</literal> or <literal>off</literal>.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3533 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3534
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3535 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3536
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3537 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	3538
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3539 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3540
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3541 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3542 <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	3543 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3544
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3545 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3546 <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	3547 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3548
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3549 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3550 <literal>NGX_HTTP_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	3551 within the <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3552 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3553
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3554 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3555 <literal>NGX_HTTP_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	3556 within the <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3557 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3558
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3559 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3560 <literal>NGX_HTTP_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	3561 within the <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3562 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3563
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3564 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3565 <literal>NGX_HTTP_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	3566 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	3567 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3568
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3569 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3570 <literal>NGX_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	3571 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	3572 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3573
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3574 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3575 <literal>NGX_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	3576 block within the <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3577 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3578
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3579 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3580 <literal>NGX_STREAM_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	3581 block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3582 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3583
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3584 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3585 <literal>NGX_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	3586 within the <literal>stream</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3587 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3588
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3589 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3590 <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	3591 within the <literal>stream</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_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	3596 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3597
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3598 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3599 <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	3600 within the <literal>mail</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3601 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3602
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3603 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3604 <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	3605 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3606
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3607 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3608 <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	3609 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	3610 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	3611 argument.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3612 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3613 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3614
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3615 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	3616 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	3617 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	3618 store their values in distinct places.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3619 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3620
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3621 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3622 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	3623 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	3624 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	3625
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3626 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3627
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3628 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3629 <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	3630 <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	3631 <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	3632 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3633
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3634 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3635 <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	3636 <literal>ngx_str_t</literal> type.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3637 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3638
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3639 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3640 <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	3641 <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	3642 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	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_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	3647 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	3648 <literal>ngx_keyval_t</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3649 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	3650 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	3651 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3652
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3653 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3654 <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	3655 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	3656 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3657
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3658 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3659 <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	3660 <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	3661 expressed in bytes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3662 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3663
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3664 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3665 <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	3666 <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	3667 expressed in bytes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3668 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3669
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3670 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3671 <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	3672 <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	3673 expressed in milliseconds.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3674 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3675
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3676 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3677 <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	3678 <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	3679 expressed in in seconds.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3680 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3681
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3682 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3683 <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	3684 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	3685 <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	3686 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3687
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3688 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3689 <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	3690 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	3691 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	3692 <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	3693 integer values.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3694 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3695
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3696 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3697 <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	3698 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	3699 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	3700 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	3701 <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	3702 mask values.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3703 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3704
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3705 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3706 <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	3707 <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	3708 For details, see the documentation for the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3709 <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	3710 proxy_temp_path</link> directive.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3711 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3712
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3713 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3714 <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	3715 permissions mask.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3716 For details, see the documentation for the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3717 <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	3718 proxy_store_access</link> directive.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3719 </listitem>
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>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3722
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3723 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3724
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3725 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3726 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	3727 passed to the directory handler.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3728 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	3729 <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	3730 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	3731 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	3732 <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	3733
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3734 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3735 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3736 <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	3737 <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3738 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3739
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3740 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3741 <literal>NGX_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	3742 <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	3743 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3744
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3745 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3746 <literal>NGX_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	3747 <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	3748 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3749
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3750 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3751 <literal>NGX_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	3752 <literal>stream</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3753 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3754
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3755 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3756 <literal>NGX_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	3757 <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	3758 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3759
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3760 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3761 <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	3762 <literal>mail</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3763 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3764
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3765 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3766 <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	3767 <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	3768 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3769
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3770 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3771
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3772 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3773
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3774 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3775 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	3776 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	3777 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	3778 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3779
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3780 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3781 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	3782 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	3783 additional data to the main handler.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3784 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	3785 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	3786 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3787 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	3788 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	3789 </programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3790 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	3791 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	3792 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	3793 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3794
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3795 </section>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3796
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3797 </section>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3798
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3799
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3800 <section name="HTTP" id="http">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3801
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3802
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3803 <section name="Connection" id="http_connection">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3804
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3805 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3806 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	3807 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3808
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3809 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3810
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3811 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3812 <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	3813 This handler is called in response to a read notification on a listen socket.
2422 eca8e37a34ef Fixed typos. Vladimir Homutov <vl@nginx.com> parents: 2412 diff changeset	3814 A new <literal>ngx_connection_t</literal> object is created at this stage
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3815 to wrap the newly accepted client socket.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3816 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	3817 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	3818 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3819
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3820 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3821 <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	3822 the HTTP connection.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3823 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	3824 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	3825 <literal>data</literal> field.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3826 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	3827 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	3828 this stage as well.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3829 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3830
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3831 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3832 <literal>ngx_http_wait_request_handler()</literal> read event handler
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3833 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	3834 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	3835 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	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_line()</literal> read event handler
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3840 reads client request line.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3841 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	3842 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	3843 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	3844 <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	3845 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	3846 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	3847 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	3848 directive.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3849 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3850
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3851 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3852 <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	3853 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	3854 the client request header.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3855 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3856
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3857 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3858 <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	3859 is completely read and parsed.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3860 This function runs request phases from
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3861 <literal>NGX_HTTP_POST_READ_PHASE</literal> to
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3862 <literal>NGX_HTTP_CONTENT_PHASE</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3863 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	3864 chain.
1979 ff28ca78bef3 Fixed a typo. Vladimir Homutov <vl@nginx.com> parents: 1976 diff changeset	3865 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	3866 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	3867 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3868
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3869 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3870 <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	3871 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	3872 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	3873 response.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3874 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	3875 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	3876 sending outstanding data.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3877 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3878
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3879 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3880 <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	3881 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	3882 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	3883 <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	3884 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	3885 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	3886 request and the connection.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3887 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3888
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3889 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3890
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3891 </section>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3892
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3893
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3894 <section name="Request" id="http_request">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3895
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3896 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3897 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	3898 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	3899 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3900
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3901 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3902
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3903 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3904
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3905 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3906 <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	3907 client connection object.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3908 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	3909 one main request and its subrequests.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3910 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	3911 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3912
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3913 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3914 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	3915 <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	3916 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	3917 connection.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3918 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	3919 output its response to the client.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3920 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	3921 output.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3922 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3923
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3924 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3925
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3926 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3927
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3928 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3929 <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	3930 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	3931 (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	3932 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	3933 <literal>ctx_index</literal> position.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3934 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	3935 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3936
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3937 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3938
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3939 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3940 <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	3941 the <literal>module</literal>'s context
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3942 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3943
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3944 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3945 <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	3946 as the <literal>module</literal>'s context
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3947 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3948
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3949 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3950
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3951 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3952
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3953 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3954 <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	3955 <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	3956 configurations.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3957 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	3958 positions.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3959 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3960
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3961 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3962 <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	3963 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	3964 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	3965 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	3966 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	3967 <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	3968 active request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3969 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3970
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3971 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3972 <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	3973 upstream response.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3974 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3975
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3976 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3977 <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	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>pool</literal> — Request pool.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3982 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	3983 the request is deleted.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3984 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	3985 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	3986 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3987
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 <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	3990 header is read.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3991 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3992
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3993 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3994 <literal>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	3995 output HTTP headers objects.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3996 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	3997 <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	3998 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	3999 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	4000 <literal>status</literal> etc.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4001 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4002
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4003 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4004 <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	4005 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4006
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4007 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4008 <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	4009 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	4010 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4011
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4012 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4013 <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	4014 representation of the client HTTP request method.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4015 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	4016 <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	4017 <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	4018 <literal>NGX_HTTP_POST</literal>, etc.
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
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4021 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4022 <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	4023 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	4024 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4025
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4026 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4027 <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	4028 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	4029 <literal>NGX_HTTP_VERSION_11</literal>, etc.).
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4030 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4031
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4032 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4033 <literal>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	4034 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	4035 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4036
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4037 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4038 <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	4039 and URI in the original client request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4040 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4041
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4042 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4043 <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	4044 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	4045 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	4046 normalization.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4047 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	4048 are performed.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4049 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4050
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4051 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4052 <literal>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	4053 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	4054 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	4055 request.
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
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4058 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4059 <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	4060 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4061
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4062 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4063 <literal>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	4064 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	4065 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	4066 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	4067 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4068
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4069 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4070 <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	4071 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	4072 Unused for main requests.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4073 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4074
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4075 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4076
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4077 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4078 <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	4079 resumed, which is done by calling the request's
1932 937e03180281 Fixed trailing spaces. Vladimir Homutov <vl@nginx.com> parents: 1929 diff changeset	4080 <literal>write_event_handler</literal>.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4081 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	4082 request phases and then produces the output.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4083 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4084
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4085 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4086 A request is usually posted by the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4087 <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	4088 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	4089 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	4090 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	4091 connection's active request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4092 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	4093 which can lead to new posted requests.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4094 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	4095 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4096
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4097 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4098
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4099 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4100 <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	4101 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4102
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4103 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4104 <literal>ncaptures</literal>, <literal>captures</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4105 <literal>captures_data</literal> — Regex captures produced
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4106 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	4107 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	4108 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	4109 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	4110 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	4111 <literal>captures</literal> holds captures boundaries and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4112 <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	4113 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	4114 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	4115 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4116
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4117 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4118 <literal>count</literal> — Request reference counter.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4119 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	4120 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	4121 To decrease the counter, call
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4122 <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	4123 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	4124 increment the counter.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4125 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4126
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4127 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4128 <literal>subrequests</literal> — Current subrequest nesting level.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4129 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	4130 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	4131 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	4132 <literal>NGX_HTTP_MAX_SUBREQUESTS</literal> constant.
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
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4135 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4136 <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	4137 the request.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4138 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	4139 <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	4140 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	4141 an error is generated.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4142 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	4143 changes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4144 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4145
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4146 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4147 <literal>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	4148 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	4149 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	4150 thread operations) and active cache lock.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4151 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4152
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4153 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4154 <literal>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	4155 output produced by the request.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4156 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	4157 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	4158 lack of free output buffers etc.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4159 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	4160 pending the flush.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4161 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4162
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 <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	4165 require a body.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4166 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	4167 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4168
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4169 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4170 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4171 <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	4172 keepalive is supported.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4173 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	4174 <header>Connection</header> header.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4175 </para>
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>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	4180 has already been sent by the request.
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>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	4185 is internal.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4186 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	4187 redirect or be a subrequest.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4188 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	4189 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4190
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4191 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4192 <literal>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	4193 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	4194 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4195
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4196 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4197 <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	4198 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	4199 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4200
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4201 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4202 <literal>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	4203 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	4204 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	4205 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	4206 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4207
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4208 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4209 <literal>main_filter_need_in_memory</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4210 <literal>filter_need_in_memory</literal> — Flags
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4211 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	4212 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	4213 sendfile is enabled.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4214 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	4215 set them.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4216 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	4217 <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	4218 request output come in memory buffers.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4219 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	4220 <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	4221 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	4222 while sending output.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4223 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4224
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4225 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4226 <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	4227 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	4228 file buffers.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4229 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	4230 it's sent.</listitem>
1929 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 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4233
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4234 </section>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4235
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4236
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4237 <section name="Configuration" id="http_conf">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4238
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4239 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4240 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	4241 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4242
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4243 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4244
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4245 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4246 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	4247 Functions as global settings for a module.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4248 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4249
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4250 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4251 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	4252 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	4253 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4254
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4255 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4256 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	4257 <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	4258 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	4259 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4260
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4261 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4262
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4263 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4264 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	4265 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	4266 and merge them.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4267 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	4268 configuration for a module.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4269 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	4270 unsigned integer.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4271 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4272
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4273 <programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4274 typedef struct {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4275 ngx_uint_t foo;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4276 } ngx_http_foo_loc_conf_t;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4277
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4278
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4279 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	4280 NULL, /* preconfiguration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4281 NULL, /* postconfiguration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4282
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4283 NULL, /* create main configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4284 NULL, /* init main configuration */
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 NULL, /* create server configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4287 NULL, /* merge server configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4288
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4289 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	4290 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	4291 };
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4292
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4293
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4294 static void *
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4295 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	4296 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4297 ngx_http_foo_loc_conf_t *conf;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4298
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4299 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	4300 if (conf == NULL) {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4301 return NULL;
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
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4304 conf->foo = NGX_CONF_UNSET_UINT;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4305
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4306 return conf;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4307 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4308
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4309
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4310 static char *
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4311 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	4312 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4313 ngx_http_foo_loc_conf_t *prev = parent;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4314 ngx_http_foo_loc_conf_t *conf = child;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4315
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4316 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	4317 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4318 </programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4319
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4320 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4321 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	4322 function creates a new configuration structure, and
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4323 <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	4324 configuration from a higher level.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4325 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	4326 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	4327 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	4328 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	4329 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	4330 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	4331 Eventually configurations are merged down.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4332 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	4333 <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	4334 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	4335 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	4336 <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	4337 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	4338 provided an explicit value.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4339 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	4340 <literal>src/core/ngx_conf_file.h</literal>.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4341 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4342
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4343 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4344 The following macros are available.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4345 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	4346 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	4347 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4348
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4349 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4350
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4351 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4352 <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	4353 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4354
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4355 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4356 <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	4357 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4358
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4359 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4360 <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	4361 </listitem>
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 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4364
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4365 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4366 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	4367 standard nginx core module
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4368 <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	4369 and replaces the location content handler kept
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4370 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	4371 </para>
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 <programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4374 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	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 ngx_command_t ngx_http_foo_commands[] = {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4378
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4379 { ngx_string("foo"),
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4380 NGX_HTTP_LOC_CONF\|NGX_CONF_NOARGS,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4381 ngx_http_foo,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4382 0,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4383 0,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4384 NULL },
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4385
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4386 ngx_null_command
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4387 };
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4388
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4389
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4390 static char *
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4391 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	4392 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4393 ngx_http_core_loc_conf_t *clcf;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4394
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4395 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	4396 clcf->handler = ngx_http_bar_handler;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4397
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4398 return NGX_CONF_OK;
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 </programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4401
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4402 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4403 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	4404 modules at runtime.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4405 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4406
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4407 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4408
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4409 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4410 <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	4411 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4412
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4413 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4414 <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	4415 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4416
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4417 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4418 <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	4419 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4420
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4421 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4422
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4423 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4424 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	4425 <literal>ngx_http_request_t</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4426 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	4427 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	4428 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	4429 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	4430 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	4431 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	4432 runtime.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4433 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4434
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4435 <programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4436 static ngx_int_t
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4437 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	4438 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4439 ngx_http_foo_loc_conf_t *flcf;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4440
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4441 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	4442
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4443 ...
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4444 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4445 </programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4446
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4447 </section>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4448
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4449
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4450 <section name="Phases" id="http_phases">
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 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4453 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	4454 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	4455 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	4456 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	4457 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	4458 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	4459 once the request reaches the phase.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4460 Following is the list of nginx HTTP phases.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4461 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4462
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4463 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4464
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4465 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4466 <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	4467 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	4468 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	4469 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	4470 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4471
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4472 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4473 <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	4474 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	4475 (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	4476 The
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4477 <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	4478 installs its handler at this phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4479 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4480
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4481 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4482 <literal>NGX_HTTP_FIND_CONFIG_PHASE</literal> — Special phase
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4483 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	4484 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	4485 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	4486 receives the configuration for the default server location.
2366 81a39b7032fd Removed obsolete symbol from devguide. Yaroslav Zhuravlev <yar@nginx.com> parents: 2294 diff changeset	4487 This phase assigns a new location to the request.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4488 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	4489 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4490
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 <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	4493 <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	4494 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	4495 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4496
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4497 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4498 <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	4499 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	4500 during a rewrite.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4501 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	4502 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	4503 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	4504 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4505
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4506 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4507 <literal>NGX_HTTP_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	4508 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	4509 The standard nginx modules
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4510 <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	4511 </link> and
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4512 <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	4513 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	4514 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4515
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4516 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4517 <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	4518 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	4519 Standard nginx modules such as
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4520 <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	4521 <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	4522 </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	4523 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	4524 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	4525 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	4526 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	4527 authorizes the client.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4528 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4529
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4530 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4531 <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	4532 <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	4533 directive is processed.
2146 c07cd947402f Development guide: typo fixed. Andrei Belov <defan@nginx.com> parents: 2081 diff changeset	4534 If some access phase handlers denied access and none explicitly allowed it, the
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4535 request is finalized.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4536 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	4537 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4538
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4539 <listitem>
2024 a8d1a748324f DevGuide: mentioned the precontent phase. Roman Arutyunyan <arut@nginx.com> parents: 2023 diff changeset	4540 <literal>NGX_HTTP_PRECONTENT_PHASE</literal> — Phase for handlers to be called
a8d1a748324f DevGuide: mentioned the precontent phase. Roman Arutyunyan <arut@nginx.com> parents: 2023 diff changeset	4541 prior to generating content.
a8d1a748324f DevGuide: mentioned the precontent phase. Roman Arutyunyan <arut@nginx.com> parents: 2023 diff changeset	4542 Standard modules such as
a8d1a748324f DevGuide: mentioned the precontent phase. Roman Arutyunyan <arut@nginx.com> parents: 2023 diff changeset	4543 <link doc="../http/ngx_http_core_module.xml" id="try_files">
a8d1a748324f DevGuide: mentioned the precontent phase. Roman Arutyunyan <arut@nginx.com> parents: 2023 diff changeset	4544 ngx_http_try_files_module</link> and
a8d1a748324f DevGuide: mentioned the precontent phase. Roman Arutyunyan <arut@nginx.com> parents: 2023 diff changeset	4545 <link doc="../http/ngx_http_mirror_module.xml">ngx_http_mirror_module</link>
a8d1a748324f DevGuide: mentioned the precontent phase. Roman Arutyunyan <arut@nginx.com> parents: 2023 diff changeset	4546 register their handlers at this phase.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4547 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4548
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4549 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4550 <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	4551 is normally generated.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4552 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	4553 including
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4554 <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	4555 <literal>ngx_http_static_module</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4556 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	4557 the output.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4558 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	4559 If the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4560 <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	4561 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	4562 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	4563 are ignored.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4564 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4565
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4566 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4567 <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	4568 is performed.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4569 Currently, only the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4570 <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	4571 registers its handler
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4572 at this stage for access logging.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4573 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	4574 before freeing the request.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4575 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4576
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4577 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4578
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4579 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4580 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	4581 </para>
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 <programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4584 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	4585 NULL, /* preconfiguration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4586 ngx_http_foo_init, /* postconfiguration */
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 NULL, /* create main configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4589 NULL, /* init main configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4590
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4591 NULL, /* create server configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4592 NULL, /* merge server configuration */
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 NULL, /* create location configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4595 NULL /* merge location configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4596 };
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4597
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 static ngx_int_t
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4600 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	4601 {
2994 537b98ec3c83 Development guide: fixed example code. Roman Arutyunyan <arut@nginx.com> parents: 2819 diff changeset	4602 ngx_table_elt_t *ua;
537b98ec3c83 Development guide: fixed example code. Roman Arutyunyan <arut@nginx.com> parents: 2819 diff changeset	4603
537b98ec3c83 Development guide: fixed example code. Roman Arutyunyan <arut@nginx.com> parents: 2819 diff changeset	4604 ua = r->headers_in.user_agent;
1929 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 if (ua == NULL) {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4607 return NGX_DECLINED;
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
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4610 /* reject requests with "User-Agent: foo" */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4611 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	4612 return NGX_HTTP_FORBIDDEN;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4613 }
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 return NGX_DECLINED;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4616 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4617
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4618
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4619 static ngx_int_t
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4620 ngx_http_foo_init(ngx_conf_t *cf)
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 ngx_http_handler_pt *h;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4623 ngx_http_core_main_conf_t *cmcf;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4624
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4625 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	4626
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4627 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	4628 if (h == NULL) {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4629 return NGX_ERROR;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4630 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4631
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4632 *h = ngx_http_foo_handler;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4633
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4634 return NGX_OK;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4635 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4636 </programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4637
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4638 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4639 Phase handlers are expected to return specific codes:
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4640 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4641
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4642 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4643
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4644 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4645 <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	4646 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4647
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4648 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4649 <literal>NGX_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	4650 phase.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4651 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	4652 move to the next phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4653 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4654
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4655 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4656 <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	4657 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	4658 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	4659 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	4660 <literal>ngx_http_core_run_phases()</literal>.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4661 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4662
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4663 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4664 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	4665 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	4666 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	4667 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4668
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4669 </list>
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 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4672 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	4673 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	4674 <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	4675 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	4676 finalization code.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4677 At the access phase, in
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4678 <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	4679 mode,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4680 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	4681 <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	4682 <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	4683 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	4684 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	4685 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4686
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4687 </section>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4688
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	4689
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4690 <section name="Variables" id="http_variables">
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4691
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4692 <section 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	4693
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4694 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4695 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	4696 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	4697 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	4698 to the configuration.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4699 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	4700 <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	4701 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4702 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	4703 ngx_int_t index;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4704
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4705 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	4706 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4707 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	4708 <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	4709 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	4710 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	4711 configuration for future use.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4712 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4713
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4714 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4715 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	4716 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	4717 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	4718 <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	4719 the variable value:
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4720 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4721 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	4722
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4723 typedef struct {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4724 unsigned len:28;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4725
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4726 unsigned valid:1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4727 unsigned no_cacheable:1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4728 unsigned not_found:1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4729 unsigned escape:1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4730
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4731 u_char *data;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4732 } ngx_variable_value_t;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4733 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4734 where:
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4735 <list type="bullet">
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4736
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4737 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4738 <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	4739 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4740
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4741 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4742 <literal>data</literal> — The value itself
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4743 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4744
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4745 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4746 <literal>valid</literal> — The value is valid
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4747 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4748
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4749 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4750 <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	4751 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	4752 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	4753 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	4754 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4755
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4756 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4757 <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	4758 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4759
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4760 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4761 <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	4762 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	4763 </listitem>
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 </list>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4766 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4767
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4768 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4769 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	4770 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	4771 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	4772 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	4773 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	4774 that identifies it.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4775 An example of typical usage:
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4776 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4777 ngx_http_variable_value_t *v;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4778
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4779 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	4780
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4781 if (v == NULL \|\| v->not_found) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4782 /* 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	4783 return NGX_ERROR;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4784 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4785
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4786 /* some meaningful value is found */
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4787 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4788 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	4789 <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	4790 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	4791 non-cacheable variables.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4792 </para>
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 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	4796 name is not known at configuration time.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4797 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	4798 <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	4799 is available.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4800 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	4801 <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	4802 from the name.
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4803 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4804
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4805 </section>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4806
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4807
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4808 <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	4809
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4810 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4811 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	4812 function.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4813 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	4814 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	4815
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4816 <list type="bullet">
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4817 <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	4818 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	4819 the same name.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4820 This allows the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4821 <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	4822 to override variables.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4823 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4824
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4825 <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	4826 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	4827 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4828
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4829 <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	4830 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	4831 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	4832 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	4833 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4834
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4835 <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	4836 variable is a prefix.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4837 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	4838 of a specific variable.
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4839 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	4840 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	4841 of a specific argument.
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4842 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4843
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4844 </list>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4845
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4846 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	4847 <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	4848 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4849 struct ngx_http_variable_s {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4850 ngx_str_t name;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4851 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	4852 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	4853 uintptr_t data;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4854 ngx_uint_t flags;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4855 ngx_uint_t index;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4856 };
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4857 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4858
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4859 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	4860 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	4861 <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	4862 <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	4863 the variable.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4864 </para>
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 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4867 Usually, a null-terminated static array of
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4868 <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	4869 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	4870 into the configuration, for example:
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4871 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4872 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	4873
2009 9b7302e3b21f DevGuide: fixed variables example. Vladimir Homutov <vl@nginx.com> parents: 2008 diff changeset	4874 { 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	4875
2023 ec34516cbd1b DevGuide: documented macros for null variables. Vladimir Homutov <vl@nginx.com> parents: 2009 diff changeset	4876 ngx_http_null_variable
1959 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
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4879 static ngx_int_t
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4880 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	4881 {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4882 ngx_http_variable_t var, v;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4883
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4884 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	4885 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	4886 if (var == NULL) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4887 return NGX_ERROR;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4888 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4889
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4890 var->get_handler = v->get_handler;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4891 var->data = v->data;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4892 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4893
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4894 return NGX_OK;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4895 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4896 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4897 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	4898 the <literal>preconfiguration</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4899 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	4900 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	4901 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4902
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4903 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4904 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	4905 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	4906 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4907 static ngx_int_t
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4908 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	4909 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	4910 {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4911 u_char *p;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4912
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4913 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	4914 if (p == NULL) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4915 return NGX_ERROR;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4916 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4917
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4918 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	4919 v->valid = 1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4920 v->no_cacheable = 0;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4921 v->not_found = 0;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4922 v->data = p;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4923
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4924 return NGX_OK;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4925 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4926 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4927 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	4928 (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	4929 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	4930 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	4931 <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	4932 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4933
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4934 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4935 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	4936 referenced by the variable.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4937 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	4938 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	4939 <programlisting>
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 { 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	4942 ngx_http_variable_request_get_size,
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4943 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	4944 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	4945 ...
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4946
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4947 static void
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4948 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	4949 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	4950 {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4951 ssize_t s, *sp;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4952 ngx_str_t val;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4953
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4954 val.len = v->len;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4955 val.data = v->data;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4956
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4957 s = ngx_parse_size(&val);
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 if (s == NGX_ERROR) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4960 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	4961 "invalid size \"%V\"", &val);
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4962 return;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4963 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4964
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4965 sp = (ssize_t ) ((char ) r + data);
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4966
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4967 *sp = s;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4968
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4969 return;
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 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4972
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4973 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4974
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4975 </section>
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 </section>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4978
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4979
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4980 <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	4981
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4982 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4983 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	4984 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	4985 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4986
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4987 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4988 The complex value description in
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4989 <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	4990 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	4991 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	4992
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4993 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4994 ngx_str_t *value;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4995 ngx_http_complex_value_t cv;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4996 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	4997
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4998 value = cf->args->elts; /* directive arguments */
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 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	5001
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5002 ccv.cf = cf;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5003 ccv.value = &value[1];
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5004 ccv.complex_value = &cv;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5005 ccv.zero = 1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5006 ccv.conf_prefix = 1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5007
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5008 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	5009 return NGX_CONF_ERROR;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5010 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5011 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5012
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5013 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	5014 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	5015
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5016 <list type="bullet">
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5017
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5018 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5019 <literal>cf</literal> — Configuration pointer
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5020 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5021
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 <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	5024 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5025
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5026 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5027 <literal>complex_value</literal> — Compiled value (output)
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5028 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5029
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5030 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5031 <literal>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	5032 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5033
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5034 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5035 <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	5036 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	5037 configuration)
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5038 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5039
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5040 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5041 <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	5042 (the normal nginx installation prefix)
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5043 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5044
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5045 </list>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5046 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	5047 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	5048 dealing with filenames.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5049 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5050
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5051 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5052 Upon successful compilation, <literal>cv.lengths</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5053 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	5054 in the expression.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5055 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	5056 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	5057 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5058
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5059 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5060 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	5061 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	5062 declaration itself.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5063 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5064
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5065 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5066 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	5067 <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	5068 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5069 ngx_str_t res;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5070
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5071 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	5072 return NGX_ERROR;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5073 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5074 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5075 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	5076 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	5077 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	5078 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5079
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5080 </section>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5081
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5082
1967 ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5083 <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	5084
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5085 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5086 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	5087 <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	5088 structure.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5089 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	5090 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	5091 <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	5092 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	5093 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	5094 request.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5095 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	5096 <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	5097 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	5098 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	5099 <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	5100 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	5101 configured for the server.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5102 The
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5103 <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	5104 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	5105 <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	5106 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	5107 directive and send the request back
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5108 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	5109 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	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 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	5114 calling one of
1967 ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5115 <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	5116 <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	5117 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5118
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5119 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5120 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	5121 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	5122 <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	5123 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	5124 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	5125 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	5126 </para>
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 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5129 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	5130 arguments.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5131 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5132
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5133 <programlisting>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5134 ngx_int_t
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5135 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	5136 {
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5137 ngx_str_t uri, args;
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 ngx_str_set(&uri, "/foo");
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5140 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	5141
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5142 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	5143 }
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5144 </programlisting>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5145
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5146 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5147 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	5148 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	5149 argument.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	5150 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	5151 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	5152 <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	5153 </para>
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>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5156 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	5157 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5158
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5159 <programlisting>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5160 ngx_int_t
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5161 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	5162 {
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5163 ngx_str_t name;
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5164
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5165 ngx_str_set(&name, "foo");
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5166
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5167 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	5168 }
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5169 </programlisting>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5170
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5171 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5172 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	5173 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	5174 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	5175 <literal>ctx</literal> field.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5176 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	5177 location configuration.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	5178 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	5179 erased by both redirect functions.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5180 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5181
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5182 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5183 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	5184 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	5185 <literal>count</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5186 For consistent request reference counting, call
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5187 <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	5188 request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5189 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	5190 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5191
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5192 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5193 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	5194 <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	5195 locations.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	5196 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	5197 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5198
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5199 </section>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5200
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5201
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5202 <section name="Subrequests" id="http_subrequests">
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5203
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5204 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5205 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	5206 possibly mixed with other data.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5207 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	5208 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	5209 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	5210 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	5211 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	5212 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	5213 a group of requests.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5214 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5215
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5216 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5217 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	5218 phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5219 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	5220 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	5221 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5222
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5223 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5224 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	5225 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	5226 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	5227 by the parent request.
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5228 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5229
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5230 <para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5231 Subrequests are 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	5232 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	5233 <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	5234 connection object.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5235 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	5236 to output its buffers to the client.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5237 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	5238 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	5239 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	5240 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	5241 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5242
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5243 <list type="bullet">
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5244
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5245 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5246 Initially, the main request is active.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5247 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5248
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5249 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5250 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	5251 </listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5252
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5253 <listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5254 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	5255 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	5256 are sent.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5257 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5258
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5259 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5260 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	5261 </listitem>
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 </list>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5264
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5265 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5266 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	5267 <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	5268 <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	5269 <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	5270 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	5271 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	5272 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	5273 <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	5274 The following flags are available:
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5275 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5276
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5277 <list type="bullet">
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5278
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5279 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5280 <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	5281 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	5282 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	5283 modules.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5284 After a subrequest is finalized its output is available in
2515 621ffbc159b6 Corrected output for NGX_HTTP_SUBREQUEST_IN_MEMORY in devguide. Yaroslav Zhuravlev <yar@nginx.com> parents: 2422 diff changeset	5285 <literal>r->out</literal> of type <literal>ngx_buf_t</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5286 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5287
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5288 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5289 <literal>NGX_HTTP_SUBREQUEST_WAITED</literal> - The subrequest's
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5290 <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	5291 it is finalized.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5292 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	5293 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5294
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5295 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5296 <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	5297 clone of its parent.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5298 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	5299 parent request.
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5300 </listitem>
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 </list>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5303
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5304 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5305 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	5306 of <literal>/foo</literal>.
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5307 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5308
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5309 <programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5310 ngx_int_t rc;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5311 ngx_str_t uri;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5312 ngx_http_request_t *sr;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5313
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5314 ...
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5315
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5316 ngx_str_set(&uri, "/foo");
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5317
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5318 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	5319 if (rc == NGX_ERROR) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5320 /* error */
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5321 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5322 </programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5323
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5324 <para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5325 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	5326 subrequest.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5327 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5328
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5329 <programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5330 ngx_int_t
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5331 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	5332 {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5333 ngx_http_request_t *sr;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5334 ngx_http_post_subrequest_t *ps;
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 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	5337 if (ps == NULL) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5338 return NGX_ERROR;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5339 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5340
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5341 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	5342 ps->data = "foo";
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5343
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5344 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	5345 NGX_HTTP_SUBREQUEST_CLONE);
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5346 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5347
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5348
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5349 ngx_int_t
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5350 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	5351 {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5352 char msg = (char ) data;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5353
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5354 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	5355 "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	5356
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5357 return rc;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5358 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5359 </programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5360
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5361 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5362 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	5363 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	5364 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	5365 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	5366 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	5367 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	5368 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	5369 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	5370 </para>
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 <programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5373 ngx_int_t
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5374 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	5375 {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5376 ngx_int_t rc;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5377 ngx_buf_t *b;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5378 ngx_uint_t last;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5379 ngx_chain_t *cl, out;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5380 ngx_http_request_t *sr;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5381 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	5382
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5383 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	5384 if (ctx == NULL) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5385 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	5386 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5387
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5388 last = 0;
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 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	5391 if (cl->buf->last_buf) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5392 cl->buf->last_buf = 0;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5393 cl->buf->last_in_chain = 1;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5394 cl->buf->sync = 1;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5395 last = 1;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5396 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5397 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5398
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5399 /* Output explicit output buffers */
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 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	5402
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5403 if (rc == NGX_ERROR \|\| !last) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5404 return rc;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5405 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5406
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5407 /*
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5408 * 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	5409 * 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	5410 * 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	5411 */
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5412
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5413 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	5414 return NGX_ERROR;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5415 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5416
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5417 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	5418
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5419 /* 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	5420
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5421 b = ngx_calloc_buf(r->pool);
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5422 if (b == NULL) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5423 return NGX_ERROR;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5424 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5425
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5426 b->last_buf = 1;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5427
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5428 out.buf = b;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5429 out.next = NULL;
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 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	5432 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5433 </programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5434
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5435 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5436 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	5437 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	5438 ngx_http_auth_request_module</link> module
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5439 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	5440 To disable output at this point, the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5441 <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	5442 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	5443 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	5444 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	5445 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5446
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5447 </section>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5448
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5449
1969 275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5450 <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	5451
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5452 <para>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5453 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	5454 <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	5455 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	5456 are sent to the filter chain.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5457 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	5458 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	5459 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	5460 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	5461 to finish sending the output.
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5462 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	5463 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	5464 </para>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5465
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5466 <para>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5467 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	5468 following <literal>rc</literal> values:
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5469 </para>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5470
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5471 <list type="bullet">
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5472
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5473 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5474 <literal>NGX_DONE</literal> - Fast finalization.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5475 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	5476 reaches zero.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5477 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	5478 is destroyed.
1969 275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5479 </listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5480
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5481 <listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5482 <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	5483 (<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	5484 (<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	5485 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	5486 </listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5487
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5488 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5489 <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	5490 <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	5491 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	5492 (<literal>300</literal>) - Special response finalization.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5493 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	5494 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	5495 <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	5496 is configured for the code.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5497 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5498
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5499 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5500 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	5501 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	5502 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	5503 is decremented.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5504 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	5505 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	5506 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	5507 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	5508 </listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5509
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5510 </list>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5511
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5512 </section>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5513
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5514
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5515 <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	5516
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5517 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5518 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	5519 <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	5520 <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	5521 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	5522 <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	5523 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	5524 body.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5525 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	5526 Normally, the content handler makes the call.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5527 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5528
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5529 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5530 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	5531 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	5532 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	5533 <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	5534 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	5535 </para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5536
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5537 <para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5538 The function
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5539 <literal>ngx_http_read_client_request_body(r, post_handler)</literal> starts
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5540 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	5541 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	5542 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	5543 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	5544 immediately.
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5545 The function
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5546 <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	5547 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	5548 <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	5549 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	5550 chain.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5551 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	5552 specified by the
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5553 <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	5554 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	5555 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5556
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5557 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5558 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	5559 </para>
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 <programlisting>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5562 ngx_int_t
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5563 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	5564 {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5565 ngx_int_t rc;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5566
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5567 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	5568
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5569 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	5570 /* error */
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5571 return rc;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5572 }
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 return NGX_DONE;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5575 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5576
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5577
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5578 void
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5579 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	5580 {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5581 off_t len;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5582 ngx_buf_t *b;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5583 ngx_int_t rc;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5584 ngx_chain_t *in, out;
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 if (r->request_body == NULL) {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5587 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	5588 return;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5589 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5590
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5591 len = 0;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5592
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5593 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	5594 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	5595 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5596
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5597 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	5598 if (b == NULL) {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5599 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	5600 return;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5601 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5602
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5603 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	5604 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	5605 b->last_in_chain = 1;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5606
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5607 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	5608 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	5609
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5610 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	5611
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5612 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	5613 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	5614 return;
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
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5617 out.buf = b;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5618 out.next = NULL;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5619
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5620 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	5621
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5622 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	5623 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5624 </programlisting>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5625
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5626 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5627 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	5628 </para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5629
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5630 <list type="bullet">
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5631
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5632 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5633 <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	5634 buffer.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5635 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5636
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 <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	5639 even if fits in the memory buffer.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5640 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5641
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 <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	5644 immediately after creation.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5645 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	5646 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5647
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5648 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5649 <literal>request_body_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	5650 request is finalized.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5651 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	5652 but was not moved for some reason.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5653 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5654
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5655 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5656 <literal>request_body_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	5657 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	5658 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5659
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5660 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5661 <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	5662 log file errors.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5663 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5664
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5665 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5666 <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	5667 buffering.
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5668 </listitem>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5669
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5670 </list>
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 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5673 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	5674 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	5675 In this mode, after calling
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5676 <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	5677 <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	5678 To read the next part, call the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5679 <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	5680 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	5681 <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	5682 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	5683 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	5684 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	5685 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	5686 </para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5687
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5688 </section>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5689
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5690
2765 5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5691 <section name="Request body filters" id="http_request_body_filters">
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5692
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5693 <para>
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5694 After a request body part is read, it's passed to the request
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5695 body filter chain by calling the first body filter handler stored in
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5696 the <literal>ngx_http_top_request_body_filter</literal> variable.
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5697 It's assumed that every body handler calls the next handler in the chain until
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5698 the final handler <literal>ngx_http_request_body_save_filter(r, cl)</literal>
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5699 is called.
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5700 This handler collects the buffers in
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5701 <literal>r->request_body->bufs</literal>
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5702 and writes them to a file if necessary.
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5703 The last request body buffer has nonzero <literal>last_buf</literal> flag.
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5704 </para>
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5705
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5706 <para>
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5707 If a filter is planning to delay data buffers, it should set the flag
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5708 <literal>r->request_body->filter_need_buffering</literal> to
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5709 <literal>1</literal> when called for the first time.
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5710 </para>
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5711
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5712 <para>
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5713 Following is an example of a simple request body filter that delays request
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5714 body by one second.
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5715 </para>
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5716
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5717 <programlisting>
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5718 #include <ngx_config.h>
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5719 #include <ngx_core.h>
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5720 #include <ngx_http.h>
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5721
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5722
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5723 #define NGX_HTTP_DELAY_BODY 1000
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5724
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5725
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5726 typedef struct {
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5727 ngx_event_t event;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5728 ngx_chain_t *out;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5729 } ngx_http_delay_body_ctx_t;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5730
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5731
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5732 static ngx_int_t ngx_http_delay_body_filter(ngx_http_request_t *r,
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5733 ngx_chain_t *in);
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5734 static void ngx_http_delay_body_cleanup(void *data);
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5735 static void ngx_http_delay_body_event_handler(ngx_event_t *ev);
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5736 static ngx_int_t ngx_http_delay_body_init(ngx_conf_t *cf);
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5737
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5738
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5739 static ngx_http_module_t ngx_http_delay_body_module_ctx = {
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5740 NULL, /* preconfiguration */
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5741 ngx_http_delay_body_init, /* postconfiguration */
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5742
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5743 NULL, /* create main configuration */
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5744 NULL, /* init main configuration */
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5745
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5746 NULL, /* create server configuration */
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5747 NULL, /* merge server configuration */
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5748
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5749 NULL, /* create location configuration */
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5750 NULL /* merge location configuration */
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5751 };
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5752
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5753
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5754 ngx_module_t ngx_http_delay_body_filter_module = {
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5755 NGX_MODULE_V1,
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5756 &ngx_http_delay_body_module_ctx, /* module context */
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5757 NULL, /* module directives */
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5758 NGX_HTTP_MODULE, /* module type */
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5759 NULL, /* init master */
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5760 NULL, /* init module */
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5761 NULL, /* init process */
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5762 NULL, /* init thread */
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5763 NULL, /* exit thread */
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5764 NULL, /* exit process */
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5765 NULL, /* exit master */
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5766 NGX_MODULE_V1_PADDING
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5767 };
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5768
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5769
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5770 static ngx_http_request_body_filter_pt ngx_http_next_request_body_filter;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5771
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5772
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5773 static ngx_int_t
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5774 ngx_http_delay_body_filter(ngx_http_request_t r, ngx_chain_t in)
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5775 {
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5776 ngx_int_t rc;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5777 ngx_chain_t cl, ln;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5778 ngx_http_cleanup_t *cln;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5779 ngx_http_delay_body_ctx_t *ctx;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5780
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5781 ngx_log_debug0(NGX_LOG_DEBUG_HTTP, r->connection->log, 0,
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5782 "delay request body filter");
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5783
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5784 ctx = ngx_http_get_module_ctx(r, ngx_http_delay_body_filter_module);
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5785
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5786 if (ctx == NULL) {
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5787 ctx = ngx_pcalloc(r->pool, sizeof(ngx_http_delay_body_ctx_t));
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5788 if (ctx == NULL) {
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5789 return NGX_HTTP_INTERNAL_SERVER_ERROR;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5790 }
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5791
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5792 ngx_http_set_ctx(r, ctx, ngx_http_delay_body_filter_module);
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5793
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5794 r->request_body->filter_need_buffering = 1;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5795 }
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5796
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5797 if (ngx_chain_add_copy(r->pool, &ctx->out, in) != NGX_OK) {
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5798 return NGX_HTTP_INTERNAL_SERVER_ERROR;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5799 }
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5800
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5801 if (!ctx->event.timedout) {
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5802 if (!ctx->event.timer_set) {
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5803
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5804 /* cleanup to remove the timer in case of abnormal termination */
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5805
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5806 cln = ngx_http_cleanup_add(r, 0);
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5807 if (cln == NULL) {
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5808 return NGX_HTTP_INTERNAL_SERVER_ERROR;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5809 }
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5810
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5811 cln->handler = ngx_http_delay_body_cleanup;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5812 cln->data = ctx;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5813
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5814 /* add timer */
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5815
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5816 ctx->event.handler = ngx_http_delay_body_event_handler;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5817 ctx->event.data = r;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5818 ctx->event.log = r->connection->log;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5819
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5820 ngx_add_timer(&ctx->event, NGX_HTTP_DELAY_BODY);
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5821 }
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5822
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5823 return ngx_http_next_request_body_filter(r, NULL);
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5824 }
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5825
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5826 rc = ngx_http_next_request_body_filter(r, ctx->out);
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5827
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5828 for (cl = ctx->out; cl; /* void */) {
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5829 ln = cl;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5830 cl = cl->next;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5831 ngx_free_chain(r->pool, ln);
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5832 }
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5833
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5834 ctx->out = NULL;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5835
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5836 return rc;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5837 }
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5838
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5839
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5840 static void
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5841 ngx_http_delay_body_cleanup(void *data)
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5842 {
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5843 ngx_http_delay_body_ctx_t *ctx = data;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5844
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5845 if (ctx->event.timer_set) {
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5846 ngx_del_timer(&ctx->event);
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5847 }
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5848 }
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5849
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5850
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5851 static void
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5852 ngx_http_delay_body_event_handler(ngx_event_t *ev)
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5853 {
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5854 ngx_connection_t *c;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5855 ngx_http_request_t *r;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5856
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5857 r = ev->data;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5858 c = r->connection;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5859
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5860 ngx_log_debug0(NGX_LOG_DEBUG_HTTP, c->log, 0,
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5861 "delay request body event");
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5862
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5863 ngx_post_event(c->read, &ngx_posted_events);
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5864 }
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5865
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5866
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5867 static ngx_int_t
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5868 ngx_http_delay_body_init(ngx_conf_t *cf)
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5869 {
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5870 ngx_http_next_request_body_filter = ngx_http_top_request_body_filter;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5871 ngx_http_top_request_body_filter = ngx_http_delay_body_filter;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5872
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5873 return NGX_OK;
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5874 }
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5875 </programlisting>
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5876
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5877 </section>
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5878
5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	5879
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5880 <section name="Response" id="http_response">
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 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5883 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	5884 the optional response body.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5885 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	5886 written to the client socket.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5887 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	5888 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	5889 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5890
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5891
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5892 <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	5893
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5894 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5895 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	5896 function sends the output header.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5897 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	5898 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	5899 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	5900 must always be set.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5901 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	5902 <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	5903 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	5904 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	5905 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	5906 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	5907 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5908
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5909 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5910 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5911 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	5912 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5913 ngx_int_t rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5914 ngx_table_elt_t *h;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5915
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5916 /* send header */
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 r->headers_out.status = NGX_HTTP_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5919 r->headers_out.content_length_n = 3;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5920
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5921 /* X-Foo: foo */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5922
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5923 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	5924 if (h == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5925 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5926 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5927
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5928 h->hash = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5929 ngx_str_set(&h->key, "X-Foo");
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5930 ngx_str_set(&h->value, "foo");
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5931
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5932 rc = ngx_http_send_header(r);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5933
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5934 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	5935 return rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5936 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5937
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5938 /* send body */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5939
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5940 ...
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5941 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5942 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5943
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5944 </section>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5945
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 <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	5948
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5949 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5950 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	5951 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	5952 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	5953 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	5954 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	5955 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	5956 <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	5957 <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	5958 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5959
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5960 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5961 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	5962 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	5963 at configuration time.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5964 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	5965 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	5966 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5967
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5968 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5969 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	5970 "<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	5971 <literal>200</literal>.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5972 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5973
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5974 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5975 #include <ngx_config.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5976 #include <ngx_core.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5977 #include <ngx_http.h>
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 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	5981 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	5982
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5983
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5984 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	5985 NULL, /* preconfiguration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5986 ngx_http_foo_header_filter_init, /* postconfiguration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5987
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5988 NULL, /* create main configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5989 NULL, /* init main configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5990
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5991 NULL, /* create server configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5992 NULL, /* merge server configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5993
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5994 NULL, /* create location configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5995 NULL /* merge location configuration */
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
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 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	6000 NGX_MODULE_V1,
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6001 &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	6002 NULL, /* module directives */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6003 NGX_HTTP_MODULE, /* module type */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6004 NULL, /* init master */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6005 NULL, /* init module */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6006 NULL, /* init process */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6007 NULL, /* init thread */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6008 NULL, /* exit thread */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6009 NULL, /* exit process */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6010 NULL, /* exit master */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6011 NGX_MODULE_V1_PADDING
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6012 };
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 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	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 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6019 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	6020 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6021 ngx_table_elt_t *h;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6022
1971 5fb870087b76 Fixed typo and removed trailing spaces. Vladimir Homutov <vl@nginx.com> parents: 1970 diff changeset	6023 /*
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6024 * 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	6025 * to every HTTP 200 response
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6026 */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6027
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6028 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	6029 return ngx_http_next_header_filter(r);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6030 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6031
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6032 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	6033 if (h == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6034 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6035 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6036
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6037 h->hash = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6038 ngx_str_set(&h->key, "X-Foo");
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6039 ngx_str_set(&h->value, "foo");
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6040
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6041 return ngx_http_next_header_filter(r);
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6045 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6046 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	6047 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6048 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	6049 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	6050
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6051 return NGX_OK;
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 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6054
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6055 </section>
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 </section>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6058
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6059
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6060 <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	6061
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6062 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6063 To send the response body, call the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6064 <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	6065 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	6066 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	6067 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	6068 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6069
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6070 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6071 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	6072 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	6073 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	6074 of the output.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6075 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	6076 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	6077 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6078
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6079 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6080 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6081 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	6082 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6083 ngx_int_t rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6084 ngx_buf_t *b;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6085 ngx_chain_t out;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6086
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6087 /* send header */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6088
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6089 r->headers_out.status = NGX_HTTP_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6090 r->headers_out.content_length_n = 3;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6091
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6092 rc = ngx_http_send_header(r);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6093
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6094 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	6095 return rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6096 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6097
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6098 /* send body */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6099
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6100 b = ngx_calloc_buf(r->pool);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6101 if (b == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6102 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6103 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6104
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6105 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	6106 b->last_in_chain = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6107
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6108 b->memory = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6109
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6110 b->pos = (u_char *) "foo";
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6111 b->last = b->pos + 3;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6112
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6113 out.buf = b;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6114 out.next = NULL;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6115
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6116 return ngx_http_output_filter(r, &out);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6117 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6118 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6119
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
2765 5e3591372bf6 Development guide: request body filters section. Roman Arutyunyan <arut@nginx.com> parents: 2611 diff changeset	6123 <section name="Response body filters" id="http_response_body_filters">
1960 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 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	6127 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	6128 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	6129 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	6130 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	6131 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6132
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6133 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6134 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	6135 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	6136 the next handler.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6137 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	6138 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	6139 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	6140 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	6141 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	6142 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	6143 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6144
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6145 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6146 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	6147 bytes in the body.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6148 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	6149 used in the access log.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6150 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6151
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6152 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6153 #include <ngx_config.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6154 #include <ngx_core.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6155 #include <ngx_http.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6156
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6157
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6158 typedef struct {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6159 off_t count;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6160 } ngx_http_counter_filter_ctx_t;
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6163 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	6164 ngx_chain_t *in);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6165 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	6166 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	6167 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	6168 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	6169
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6170
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6171 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	6172 ngx_http_counter_add_variables, /* preconfiguration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6173 ngx_http_counter_filter_init, /* postconfiguration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6174
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6175 NULL, /* create main configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6176 NULL, /* init main configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6177
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6178 NULL, /* create server configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6179 NULL, /* merge server configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6180
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6181 NULL, /* create location configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6182 NULL /* merge location configuration */
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
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 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	6187 NGX_MODULE_V1,
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6188 &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	6189 NULL, /* module directives */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6190 NGX_HTTP_MODULE, /* module type */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6191 NULL, /* init master */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6192 NULL, /* init module */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6193 NULL, /* init process */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6194 NULL, /* init thread */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6195 NULL, /* exit thread */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6196 NULL, /* exit process */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6197 NULL, /* exit master */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6198 NGX_MODULE_V1_PADDING
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6201
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6202 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	6203
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6204 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	6205
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6206
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6207 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6208 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	6209 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6210 ngx_chain_t *cl;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6211 ngx_http_counter_filter_ctx_t *ctx;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6212
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6213 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	6214 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6215 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	6216 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6217 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6218 }
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 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	6221 }
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 for (cl = in; cl; cl = cl->next) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6224 ctx->count += ngx_buf_size(cl->buf);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6225 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6226
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6227 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	6228 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6229
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6230
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6231 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6232 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	6233 uintptr_t data)
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6234 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6235 u_char *p;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6236 ngx_http_counter_filter_ctx_t *ctx;
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 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	6239 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6240 v->not_found = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6241 return NGX_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6242 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6243
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6244 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	6245 if (p == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6246 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6247 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6248
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6249 v->data = p;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6250 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	6251 v->valid = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6252 v->no_cacheable = 0;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6253 v->not_found = 0;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6254
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6255 return NGX_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6256 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6257
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6258
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6259 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6260 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	6261 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6262 ngx_http_variable_t *var;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6263
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6264 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	6265 if (var == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6266 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6267 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6268
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6269 var->get_handler = ngx_http_counter_variable;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6270
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6271 return NGX_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6272 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6273
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6274
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6275 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6276 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	6277 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6278 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	6279 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	6280
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6281 return NGX_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6282 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6283 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6284
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6285 </section>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6286
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6287
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6288 <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	6289
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6290 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6291 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	6292 position in the filter order.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6293 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	6294 modules.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6295 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	6296 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	6297 them.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6298 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	6299 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	6300 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	6301 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6302
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6303 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6304 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	6305 <literal>HTTP_AUX_FILTER_MODULES</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6306 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	6307 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	6308 <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	6309 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6310
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6311 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6312 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	6313 for a module with just
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6314 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	6315 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6316
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6317 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6318 ngx_module_type=HTTP_AUX_FILTER
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6319 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	6320 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	6321
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6322 . auto/module
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6323 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6324
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6325 </section>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6326
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6327
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6328 <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	6329
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6330 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6331 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	6332 allocated buffers.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6333 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	6334 two buffer chains for this purpose:
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6335 <literal>free</literal> and <literal>busy</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6336 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	6337 which can be reused.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6338 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	6339 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	6340 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	6341 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	6342 (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	6343 <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	6344 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	6345 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	6346 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	6347 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	6348 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	6349 <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	6350 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	6351 <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	6352 <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	6353 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	6354 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	6355 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6356
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6357 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6358 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	6359 incoming buffer.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6360 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	6361 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	6362 <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	6363 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	6364 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	6365 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6366
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6367 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6368 typedef struct {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6369 ngx_chain_t *free;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6370 ngx_chain_t *busy;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6371 } ngx_http_foo_filter_ctx_t;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6372
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6373
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6374 ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6375 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	6376 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6377 ngx_int_t rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6378 ngx_buf_t *b;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6379 ngx_chain_t cl, tl, out, *ll;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6380 ngx_http_foo_filter_ctx_t *ctx;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6381
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6382 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	6383 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6384 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	6385 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6386 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6387 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6388
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6389 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	6390 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6391
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6392 /* 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	6393
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6394 ll = &out;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6395
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6396 for (cl = in; cl; cl = cl->next) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6397
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6398 /* 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	6399
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6400 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	6401 if (tl == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6402 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6403 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6404
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6405 b = tl->buf;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6406 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	6407 b->memory = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6408 b->pos = (u_char *) "foo";
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6409 b->last = b->pos + 3;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6410
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6411 *ll = tl;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6412 ll = &tl->next;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6413
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6414 /* append the next incoming buffer */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6415
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6416 tl = ngx_alloc_chain_link(r->pool);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6417 if (tl == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6418 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6419 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6420
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6421 tl->buf = cl->buf;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6422 *ll = tl;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6423 ll = &tl->next;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6424 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6425
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6426 *ll = NULL;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6427
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6428 /* send the new chain */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6429
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6430 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	6431
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6432 /* update "busy" and "free" chains for reuse */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6433
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6434 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	6435 (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	6436
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6437 return rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6438 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6439 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6440
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6441 </section>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6442
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6443
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6444 <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	6445
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6446 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6447 The
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6448 <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	6449 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	6450 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	6451 this functionality.
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6452 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	6453 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	6454 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6455
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6456 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6457 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	6458 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	6459 modules implement alternative load-balancing methods, but
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6460 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	6461 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	6462 of a server group.
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6463 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	6464 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	6465 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6466
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6467 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6468 The
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6469 <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	6470 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	6471 <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	6472 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	6473 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	6474 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	6475 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	6476 upstream configuration.
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6477 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	6478 <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	6479 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	6480 <programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6481 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	6482 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	6483 void **srv_conf;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6484
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6485 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	6486
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6487 ngx_uint_t flags;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6488 ngx_str_t host;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6489 u_char *file_name;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6490 ngx_uint_t line;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6491 in_port_t port;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6492 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	6493
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6494 #if (NGX_HTTP_UPSTREAM_ZONE)
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6495 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	6496 #endif
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6497 };
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6498 </programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6499
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6500 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6501
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6502 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6503 <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	6504 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6505
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6506 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6507 <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	6508 <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	6509 <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	6510 in the <literal>upstream</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6511 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6512
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6513 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6514 <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	6515 are supported by the load-balancing method.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6516 The features are configured as parameters of
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6517 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	6518
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6519
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6520 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6521
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6522 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6523 <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	6524 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	6525 <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	6526 and “friends”
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6527 (FastCGI, SCGI, etc.)
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6528 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6529
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6530 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6531 <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	6532 parameter is supported
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6533 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6534
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6535 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6536 <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	6537 “<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	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>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6541 <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	6542 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	6543 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6544
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6545 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6546 <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	6547 parameter is supported
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
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6550 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6551 <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	6552 parameter is supported
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
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6555 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6556 <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	6557 “<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	6558 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6559
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6560 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6561
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6562 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6563
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6564 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6565 <literal>host</literal> — Name of the upstream.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6566 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6567
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 <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	6570 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	6571 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6572
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6573 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6574 <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	6575 explicitly defined upstream groups.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6576 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6577
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6578 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6579 <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	6580 if any.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6581 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6582
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6583 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6584 <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	6585 initializing upstream configuration:
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6586
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6587 <programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6588 typedef struct {
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6589 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	6590 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	6591 void *data;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6592 } ngx_http_upstream_peer_t;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6593 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6594 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	6595 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	6596 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	6597 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	6598 <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	6599
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6600 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6601 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6602 <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	6603 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	6604 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	6605 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	6606 <literal>upstream</literal> block
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6607 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	6608 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	6609 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6610
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6611 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6612 <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	6613 <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	6614 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	6615 <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	6616 is per-upstream).
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6617 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	6618 deal with server selection.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6619 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6620 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6621
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6622 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6623 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6624 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6625
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6626 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6627 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	6628 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	6629 The method is obtained from the
1994 effdf0747a05 Development guide: fixed a typo. Vladimir Homutov <vl@nginx.com> parents: 1993 diff changeset	6630 <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	6631 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	6632 <programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6633 struct ngx_peer_connection_s {
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6634 ...
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6635
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6636 struct sockaddr *sockaddr;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6637 socklen_t socklen;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6638 ngx_str_t *name;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6639
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6640 ngx_uint_t tries;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6641
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6642 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	6643 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	6644 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	6645 void *data;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6646
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6647 #if (NGX_SSL \|\| NGX_COMPAT)
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6648 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	6649 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	6650 #endif
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6651
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6652 ...
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6653 };
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6654 </programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6655
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6656 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	6657
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6658 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6659 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6660 <literal>sockaddr</literal>, <literal>socklen</literal>,
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6661 <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	6662 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	6663 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6664
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6665 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6666 <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	6667 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	6668 to the upstream configuration.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6669 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	6670 (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	6671 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6672
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6673 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6674 <literal>tries</literal> — Allowed
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6675 <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	6676 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	6677 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6678
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6679 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6680 <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	6681 <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	6682 - 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	6683 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6684
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6685 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6686
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6687 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6688
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6689 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6690 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	6691 <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	6692 <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	6693 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	6694 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	6695 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6696
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6697 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6698
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6699 <list type="bullet">
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6700 <listitem id="lb_method_get">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6701 <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	6702 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	6703 its address.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6704 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	6705 <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	6706 <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	6707 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	6708
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6709 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6710
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6711 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6712 <literal>NGX_OK</literal> — Server was selected.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6713 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6714
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6715 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6716 <literal>NGX_ERROR</literal> — Internal error occurred.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6717 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6718
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6719 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6720 <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	6721 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	6722 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	6723 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	6724 handling the maximum number of connections.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6725 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6726
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6727 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6728 <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	6729 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	6730 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	6731 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6732
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6733 <!--
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6734 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6735 <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	6736 processing of this request should be postponed.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6737 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	6738 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6739 -->
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6740
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6741 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6742
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6743 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6744
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6745 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6746 <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	6747 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	6748 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	6749 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	6750
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6751 <list type="bullet">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6752
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6753 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6754 <literal>NGX_PEER_FAILED</literal> — Attempt was
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6755 <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	6756 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6757
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6758 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6759 <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	6760 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	6761 which are not considered a
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6762 <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	6763 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6764
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6765 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6766 <literal>NGX_PEER_KEEPALIVE</literal> — Currently unused
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6767 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6768
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6769 </list>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6770
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6771 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	6772
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6773 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6774
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6775 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6776 <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	6777 in the OSS version.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6778 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6779
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6780 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6781 <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	6782 <literal>save_session(pc, data)</literal>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6783 — 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	6784 servers.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6785 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	6786 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6787
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6788 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6789
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6790 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6791
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	6792 </section>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	6793
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6794 </section>
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	6795
2073 75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6796 <section name="Examples" id="examples">
75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6797
75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6798 <para>
75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6799 The
2078 26e547b1022d DevGuide: changed nginx-dev-examples repository. Roman Arutyunyan <arut@nginx.com> parents: 2073 diff changeset	6800 <link url="http://hg.nginx.org/nginx-dev-examples">nginx-dev-examples</link>
2073 75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6801 repository provides nginx module examples.
75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6802
75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6803 </para>
75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6804
75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6805 </section>
75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6806
2153 ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6807
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6808 <section name="Code style" id="code_style">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6809
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6810 <section name="General rules" id="code_style_general_rules">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6811
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6812 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6813 <list type="bullet">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6814
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6815 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6816 maximum text width is 80 characters
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6817 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6818
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6819 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6820 indentation is 4 spaces
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6821 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6822
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6823 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6824 no tabs, no trailing spaces
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6825 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6826
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6827 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6828 list elements on the same line are separated with spaces
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6829 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6830
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6831 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6832 hexadecimal literals are lowercase
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6833 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6834
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6835 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6836 file names, function and type names, and global variables have the
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6837 <literal>ngx_</literal> or more specific prefix such as
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6838 <literal>ngx_http_</literal> and <literal>ngx_mail_</literal>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6839 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6840
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6841 </list>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6842
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6843 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6844 size_t
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6845 ngx_utf8_length(u_char *p, size_t n)
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6846 {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6847 u_char c, *last;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6848 size_t len;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6849
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6850 last = p + n;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6851
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6852 for (len = 0; p < last; len++) {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6853
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6854 c = *p;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6855
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6856 if (c < 0x80) {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6857 p++;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6858 continue;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6859 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6860
2572 c6c259d3601a Development guide: updated ngx_utf8_length() example. Sergey Kandaurov <pluknet@nginx.com> parents: 2515 diff changeset	6861 if (ngx_utf8_decode(&p, last - p) > 0x10ffff) {
2153 ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6862 /* invalid UTF-8 */
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6863 return n;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6864 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6865 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6866
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6867 return len;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6868 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6869 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6870
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6871 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6872
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6873 </section>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6874
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6875
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6876 <section name="Files" id="code_style_files">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6877
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6878 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6879 A typical source file may contain the following sections separated by
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6880 two empty lines:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6881
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6882 <list type="bullet">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6883 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6884 copyright statements
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6885 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6886
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6887 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6888 includes
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6889 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6890
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6891 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6892 preprocessor definitions
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6893 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6894
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6895 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6896 type definitions
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6897 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6898
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6899 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6900 function prototypes
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6901 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6902
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6903 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6904 variable definitions
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6905 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6906
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6907 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6908 function definitions
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6909 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6910
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6911 </list>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6912 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6913
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6914 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6915 Copyright statements look like this:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6916 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6917 /*
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6918 * Copyright (C) Author Name
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6919 * Copyright (C) Organization, Inc.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6920 */
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6921 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6922 If the file is modified significantly, the list of authors should be updated,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6923 the new author is added to the top.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6924 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6925
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6926 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6927 The <literal>ngx_config.h</literal> and <literal>ngx_core.h</literal> files
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6928 are always included first, followed by one of
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6929 <literal>ngx_http.h</literal>, <literal>ngx_stream.h</literal>,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6930 or <literal>ngx_mail.h</literal>.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6931 Then follow optional external header files:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6932 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6933 #include <ngx_config.h>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6934 #include <ngx_core.h>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6935 #include <ngx_http.h>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6936
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6937 #include <libxml/parser.h>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6938 #include <libxml/tree.h>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6939 #include <libxslt/xslt.h>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6940
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6941 #if (NGX_HAVE_EXSLT)
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6942 #include <libexslt/exslt.h>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6943 #endif
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6944 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6945
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6946 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6947
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6948 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6949 Header files should include the so called "header protection":
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6950 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6951 #ifndef _NGX_PROCESS_CYCLE_H_INCLUDED_
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6952 #define _NGX_PROCESS_CYCLE_H_INCLUDED_
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6953 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6954 #endif /* _NGX_PROCESS_CYCLE_H_INCLUDED_ */
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6955 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6956 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6957
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6958 </section>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6959
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6960
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6961 <section name="Comments" id="code_style_comments">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6962 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6963 <list type="bullet">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6964
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6965 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6966 “<literal>//</literal>” comments are not used
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6967 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6968
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6969 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6970 text is written in English, American spelling is preferred
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6971 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6972
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6973 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6974 multi-line comments are formatted like this:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6975 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6976 /*
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6977 * The red-black tree code is based on the algorithm described in
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6978 * the "Introduction to Algorithms" by Cormen, Leiserson and Rivest.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6979 */
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6980 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6981 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6982 /* find the server configuration for the address:port */
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6983 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6984 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6985
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6986 </list>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6987 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6988
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6989 </section>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6990
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6991
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6992 <section name="Preprocessor" id="code_style_preprocessor">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6993 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6994 Macro names start from <literal>ngx_</literal> or <literal>NGX_</literal>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6995 (or more specific) prefix.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6996 Macro names for constants are uppercase.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6997 Parameterized macros and macros for initializers are lowercase.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6998 The macro name and value are separated by at least two spaces:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6999 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7000 #define NGX_CONF_BUFFER 4096
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7001
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7002 #define ngx_buf_in_memory(b) (b->temporary \|\| b->memory \|\| b->mmap)
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7003
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7004 #define ngx_buf_size(b) \
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7005 (ngx_buf_in_memory(b) ? (off_t) (b->last - b->pos): \
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7006 (b->file_last - b->file_pos))
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7007
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7008 #define ngx_null_string { 0, NULL }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7009 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7010 Conditions are inside parentheses, negation is outside:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7011 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7012 #if (NGX_HAVE_KQUEUE)
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7013 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7014 #elif ((NGX_HAVE_DEVPOLL && !(NGX_TEST_BUILD_DEVPOLL)) \
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7015 \|\| (NGX_HAVE_EVENTPORT && !(NGX_TEST_BUILD_EVENTPORT)))
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7016 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7017 #elif (NGX_HAVE_EPOLL && !(NGX_TEST_BUILD_EPOLL))
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7018 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7019 #elif (NGX_HAVE_POLL)
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7020 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7021 #else /* select */
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7022 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7023 #endif /* NGX_HAVE_KQUEUE */
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7024 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7025 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7026 </section>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7027
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7028
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7029 <section name="Types" id="code_style_types">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7030
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7031 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7032 Type names end with the “<literal>_t</literal>” suffix.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7033 A defined type name is separated by at least two spaces:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7034 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7035 typedef ngx_uint_t ngx_rbtree_key_t;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7036 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7037 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7038
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7039 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7040 Structure types are defined using <literal>typedef</literal>.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7041 Inside structures, member types and names are aligned:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7042 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7043 typedef struct {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7044 size_t len;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7045 u_char *data;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7046 } ngx_str_t;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7047 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7048 Keep alignment identical among different structures in the file.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7049 A structure that points to itself has the name, ending with
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7050 “<literal>_s</literal>”.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7051 Adjacent structure definitions are separated with two empty lines:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7052 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7053 typedef struct ngx_list_part_s ngx_list_part_t;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7054
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7055 struct ngx_list_part_s {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7056 void *elts;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7057 ngx_uint_t nelts;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7058 ngx_list_part_t *next;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7059 };
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7060
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7061
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7062 typedef struct {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7063 ngx_list_part_t *last;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7064 ngx_list_part_t part;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7065 size_t size;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7066 ngx_uint_t nalloc;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7067 ngx_pool_t *pool;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7068 } ngx_list_t;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7069 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7070 Each structure member is declared on its own line:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7071 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7072 typedef struct {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7073 ngx_uint_t hash;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7074 ngx_str_t key;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7075 ngx_str_t value;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7076 u_char *lowcase_key;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7077 } ngx_table_elt_t;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7078 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7079 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7080
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7081 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7082 Function pointers inside structures have defined types ending
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7083 with “<literal>_pt</literal>”:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7084 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7085 typedef ssize_t (ngx_recv_pt)(ngx_connection_t c, u_char *buf, size_t size);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7086 typedef ssize_t (ngx_recv_chain_pt)(ngx_connection_t c, ngx_chain_t *in,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7087 off_t limit);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7088 typedef ssize_t (ngx_send_pt)(ngx_connection_t c, u_char *buf, size_t size);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7089 typedef ngx_chain_t (ngx_send_chain_pt)(ngx_connection_t c, ngx_chain_t in,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7090 off_t limit);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7091
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7092 typedef struct {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7093 ngx_recv_pt recv;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7094 ngx_recv_chain_pt recv_chain;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7095 ngx_recv_pt udp_recv;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7096 ngx_send_pt send;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7097 ngx_send_pt udp_send;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7098 ngx_send_chain_pt udp_send_chain;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7099 ngx_send_chain_pt send_chain;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7100 ngx_uint_t flags;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7101 } ngx_os_io_t;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7102 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7103 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7104
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7105 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7106 Enumerations have types ending with “<literal>_e</literal>”:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7107 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7108 typedef enum {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7109 ngx_http_fastcgi_st_version = 0,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7110 ngx_http_fastcgi_st_type,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7111 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7112 ngx_http_fastcgi_st_padding
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7113 } ngx_http_fastcgi_state_e;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7114 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7115 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7116
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7117 </section>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7118
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7119
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7120 <section name="Variables" id="code_style_variables">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7121
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7122 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7123 Variables are declared sorted by length of a base type, then alphabetically.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7124 Type names and variable names are aligned.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7125 The type and name “columns” are separated with two spaces.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7126 Large arrays are put at the end of a declaration block:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7127 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7128 u_char \| \| rv, p;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7129 ngx_conf_t \| \| *cf;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7130 ngx_uint_t \| \| i, j, k;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7131 unsigned int \| \| len;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7132 struct sockaddr \| \| *sa;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7133 const unsigned char \| \| *data;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7134 ngx_peer_connection_t \| \| *pc;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7135 ngx_http_core_srv_conf_t \| \|**cscfp;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7136 ngx_http_upstream_srv_conf_t\| \| us, uscf;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7137 u_char \| \| text[NGX_SOCKADDR_STRLEN];
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7138 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7139 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7140
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7141 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7142 Static and global variables may be initialized on declaration:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7143 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7144 static ngx_str_t ngx_http_memcached_key = ngx_string("memcached_key");
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7145 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7146
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7147 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7148 static ngx_uint_t mday[] = { 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 };
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7149 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7150
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7151 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7152 static uint32_t ngx_crc32_table16[] = {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7153 0x00000000, 0x1db71064, 0x3b6e20c8, 0x26d930ac,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7154 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7155 0x9b64c2b0, 0x86d3d2d4, 0xa00ae278, 0xbdbdf21c
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7156 };
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7157 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7158 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7159
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7160 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7161 There is a bunch of commonly used type/name combinations:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7162 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7163 u_char *rv;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7164 ngx_int_t rc;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7165 ngx_conf_t *cf;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7166 ngx_connection_t *c;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7167 ngx_http_request_t *r;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7168 ngx_peer_connection_t *pc;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7169 ngx_http_upstream_srv_conf_t us, uscf;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7170 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7171 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7172 </section>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7173
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7174
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7175 <section name="Functions" id="code_style_functions">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7176
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7177 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7178 All functions (even static ones) should have prototypes.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7179 Prototypes include argument names.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7180 Long prototypes are wrapped with a single indentation on continuation lines:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7181 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7182 static char ngx_http_block(ngx_conf_t cf, ngx_command_t cmd, void conf);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7183 static ngx_int_t ngx_http_init_phases(ngx_conf_t *cf,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7184 ngx_http_core_main_conf_t *cmcf);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7185
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7186 static char ngx_http_merge_servers(ngx_conf_t cf,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7187 ngx_http_core_main_conf_t cmcf, ngx_http_module_t module,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7188 ngx_uint_t ctx_index);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7189 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7190 The function name in a definition starts with a new line.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7191 The function body opening and closing braces are on separate lines.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7192 The body of a function is indented.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7193 There are two empty lines between functions:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7194 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7195 static ngx_int_t
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7196 ngx_http_find_virtual_server(ngx_http_request_t r, u_char host, size_t len)
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7197 {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7198 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7199 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7200
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7201
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7202 static ngx_int_t
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7203 ngx_http_add_addresses(ngx_conf_t cf, ngx_http_core_srv_conf_t cscf,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7204 ngx_http_conf_port_t port, ngx_http_listen_opt_t lsopt)
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7205 {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7206 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7207 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7208 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7209 There is no space after the function name and opening parenthesis.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7210 Long function calls are wrapped such that continuation lines start
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7211 from the position of the first function argument.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7212 If this is impossible, format the first continuation line such that it
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7213 ends at position 79:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7214 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7215 ngx_log_debug2(NGX_LOG_DEBUG_HTTP, r->connection->log, 0,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7216 "http header: \"%V: %V\"",
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7217 &h->key, &h->value);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7218
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7219 hc->busy = ngx_palloc(r->connection->pool,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7220 cscf->large_client_header_buffers.num * sizeof(ngx_buf_t *));
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7221 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7222 The <literal>ngx_inline</literal> macro should be used instead of
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7223 <literal>inline</literal>:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7224 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7225 static ngx_inline void ngx_cpuid(uint32_t i, uint32_t *buf);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7226 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7227 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7228
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7229 </section>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7230
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7231
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7232 <section name="Expressions" id="code_style_expressions">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7233
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7234 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7235 Binary operators except “<literal>.</literal>” and “<literal>−></literal>”
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7236 should be separated from their operands by one space.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7237 Unary operators and subscripts are not separated from their operands by spaces:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7238 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7239 width = width * 10 + (*fmt++ - '0');
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7240 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7241 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7242 ch = (u_char) ((decoded << 4) + (ch - '0'));
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7243 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7244 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7245 r->exten.data = &r->uri.data[i + 1];
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7246 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7247 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7248
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7249 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7250 Type casts are separated by one space from casted expressions.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7251 An asterisk inside type cast is separated with space from type name:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7252 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7253 len = ngx_sock_ntop((struct sockaddr *) sin6, p, len, 1);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7254 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7255 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7256
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7257 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7258 If an expression does not fit into single line, it is wrapped.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7259 The preferred point to break a line is a binary operator.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7260 The continuation line is lined up with the start of expression:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7261 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7262 if (status == NGX_HTTP_MOVED_PERMANENTLY
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7263 \|\| status == NGX_HTTP_MOVED_TEMPORARILY
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7264 \|\| status == NGX_HTTP_SEE_OTHER
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7265 \|\| status == NGX_HTTP_TEMPORARY_REDIRECT
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7266 \|\| status == NGX_HTTP_PERMANENT_REDIRECT)
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7267 {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7268 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7269 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7270 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7271 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7272 p->temp_file->warn = "an upstream response is buffered "
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7273 "to a temporary file";
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7274 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7275 As a last resort, it is possible to wrap an expression so that the
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7276 continuation line ends at position 79:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7277 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7278 hinit->hash = ngx_pcalloc(hinit->pool, sizeof(ngx_hash_wildcard_t)
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7279 + size * sizeof(ngx_hash_elt_t *));
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7280 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7281 The above rules also apply to sub-expressions,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7282 where each sub-expression has its own indentation level:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7283 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7284 if (((u->conf->cache_use_stale & NGX_HTTP_UPSTREAM_FT_UPDATING)
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7285 \|\| c->stale_updating) && !r->background
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7286 && u->conf->cache_background_update)
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7287 {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7288 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7289 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7290 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7291 Sometimes, it is convenient to wrap an expression after a cast.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7292 In this case, the continuation line is indented:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7293 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7294 node = (ngx_rbtree_node_t *)
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7295 ((u_char *) lr - offsetof(ngx_rbtree_node_t, color));
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7296 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7297 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7298
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7299 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7300 Pointers are explicitly compared to
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7301 <literal>NULL</literal> (not <literal>0</literal>):
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7302
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7303 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7304 if (ptr != NULL) {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7305 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7306 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7307 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7308 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7309
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7310 </section>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7311
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7312
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7313 <section name="Conditionals and Loops" id="code_style_conditionals_and_loops">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7314
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7315 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7316 The “<literal>if</literal>” keyword is separated from the condition by
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7317 one space.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7318 Opening brace is located on the same line, or on a
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7319 dedicated line if the condition takes several lines.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7320 Closing brace is located on a dedicated line, optionally followed
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7321 by “<literal>else if</literal> / <literal>else</literal>”.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7322 Usually, there is an empty line before the
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7323 “<literal>else if</literal> / <literal>else</literal>” part:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7324 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7325 if (node->left == sentinel) {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7326 temp = node->right;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7327 subst = node;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7328
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7329 } else if (node->right == sentinel) {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7330 temp = node->left;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7331 subst = node;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7332
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7333 } else {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7334 subst = ngx_rbtree_min(node->right, sentinel);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7335
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7336 if (subst->left != sentinel) {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7337 temp = subst->left;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7338
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7339 } else {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7340 temp = subst->right;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7341 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7342 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7343 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7344 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7345
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7346 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7347 Similar formatting rules are applied to “<literal>do</literal>”
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7348 and “<literal>while</literal>” loops:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7349 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7350 while (p < last && *p == ' ') {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7351 p++;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7352 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7353 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7354
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7355 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7356 do {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7357 ctx->node = rn;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7358 ctx = ctx->next;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7359 } while (ctx);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7360 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7361 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7362
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7363 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7364 The “<literal>switch</literal>” keyword is separated from the condition by
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7365 one space.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7366 Opening brace is located on the same line.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7367 Closing brace is located on a dedicated line.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7368 The “<literal>case</literal>” keywords are lined up with
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7369 “<literal>switch</literal>”:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7370 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7371 switch (ch) {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7372 case '!':
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7373 looked = 2;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7374 state = ssi_comment0_state;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7375 break;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7376
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7377 case '<':
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7378 copy_end = p;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7379 break;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7380
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7381 default:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7382 copy_end = p;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7383 looked = 0;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7384 state = ssi_start_state;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7385 break;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7386 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7387 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7388 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7389
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7390 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7391 Most “<literal>for</literal>” loops are formatted like this:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7392 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7393 for (i = 0; i < ccf->env.nelts; i++) {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7394 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7395 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7396 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7397 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7398 for (q = ngx_queue_head(locations);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7399 q != ngx_queue_sentinel(locations);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7400 q = ngx_queue_next(q))
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7401 {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7402 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7403 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7404 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7405 If some part of the “<literal>for</literal>” statement is omitted,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7406 this is indicated by the “<literal>/* void */</literal>” comment:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7407 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7408 for (i = 0; /* void */ ; i++) {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7409 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7410 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7411 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7412 A loop with an empty body is also indicated by the
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7413 “<literal>/* void */</literal>” comment which may be put on the same line:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7414 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7415 for (cl = busy; cl->next; cl = cl->next) { / void */ }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7416 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7417 An endless loop looks like this:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7418 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7419 for ( ;; ) {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7420 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7421 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7422 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7423 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7424
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7425 </section>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7426
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7427
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7428 <section name="Labels" id="code_style_labels">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7429
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7430 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7431 Labels are surrounded with empty lines and are indented at the previous level:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7432 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7433 if (i == 0) {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7434 u->err = "host not found";
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7435 goto failed;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7436 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7437
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7438 u->addrs = ngx_pcalloc(pool, i * sizeof(ngx_addr_t));
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7439 if (u->addrs == NULL) {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7440 goto failed;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7441 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7442
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7443 u->naddrs = i;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7444
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7445 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7446
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7447 return NGX_OK;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7448
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7449 failed:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7450
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7451 freeaddrinfo(res);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7452 return NGX_ERROR;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7453 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7454 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7455 </section>
2410 392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7456 </section>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7457
2611 454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7458 <section name="Debugging memory issues" id="debug_memory">
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7459
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7460 <para>
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7461 To debug memory issues such as buffer overruns or use-after-free errors, you
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7462 can use the <link url="https://en.wikipedia.org/wiki/AddressSanitizer">
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7463 AddressSanitizer</link> (ASan) supported by some modern compilers.
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7464 To enable ASan with <literal>gcc</literal> and <literal>clang</literal>,
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7465 use the <literal>-fsanitize=address</literal> compiler and linker option.
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7466 When building nginx, this can be done by adding the option to
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7467 <literal>--with-cc-opt</literal> and <literal>--with-ld-opt</literal>
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7468 parameters of the <literal>configure</literal> script.
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7469 </para>
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7470
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7471 <para>
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7472 Since most allocations in nginx are made from nginx internal
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7473 <link id="pool">pool</link>, enabling ASan may not always be enough to debug
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7474 memory issues.
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7475 The internal pool allocates a big chunk of memory from the system and cuts
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7476 smaller allocations from it.
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7477 However, this mechanism can be disabled by setting the
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7478 <literal>NGX_DEBUG_PALLOC</literal> macro to <literal>1</literal>.
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7479 In this case, allocations are passed directly to the system allocator giving it
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7480 full control over the buffers boundaries.
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7481 </para>
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7482
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7483 <para>
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7484 The following configuration line summarizes the information provided above.
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7485 It is recommended while developing third-party modules and testing nginx on
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7486 different platforms.
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7487 </para>
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7488
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7489 <programlisting>
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7490 auto/configure --with-cc-opt='-fsanitize=address -DNGX_DEBUG_PALLOC=1'
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7491 --with-ld-opt=-fsanitize=address
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7492 </programlisting>
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7493
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7494 </section>
454af1d39021 Development guide: Debugging memory issues section. Roman Arutyunyan <arut@nginx.com> parents: 2572 diff changeset	7495
2410 392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7496 <section name="Common Pitfalls" id="common_pitfals">
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7497
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7498 <section name="Writing a C module" id="module_pitfall">
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7499
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7500 <para>
2412 bd026d5898b8 Minor language improvements in Development guide. Yaroslav Zhuravlev <yar@nginx.com> parents: 2410 diff changeset	7501 The most common pitfall is an attempt to write a full-fledged C module
bd026d5898b8 Minor language improvements in Development guide. Yaroslav Zhuravlev <yar@nginx.com> parents: 2410 diff changeset	7502 when it can be avoided.
2410 392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7503 In most cases your task can be accomplished by creating a proper configuration.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7504 If writing a module is inevitable, try to make it
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7505 as small and simple as possible.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7506 For example, a module can only export some
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7507 <link id="http_variables">variables</link>.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7508 </para>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7509
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7510 <para>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7511 Before starting a module, consider the following questions:
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7512
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7513 <list type="bullet">
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7514
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7515 <listitem>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7516 Is it possible to implement a desired feature using already
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7517 <link doc="../../docs/index.xml">available modules</link>?
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7518 </listitem>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7519
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7520 <listitem>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7521 Is it possible to solve an issue using built-in scripting languages,
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7522 such as <link doc="../http/ngx_http_perl_module.xml">Perl</link>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7523 or <link doc="../njs/index.xml">njs</link>?
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7524 </listitem>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7525
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7526 </list>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7527
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7528 </para>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7529
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7530 </section>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7531
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7532 <section name="C Strings" id="c_strings">
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7533
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7534 <para>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7535 The most used string type in nginx,
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7536 <link id="string_overview">ngx_str_t</link> is not a C-Style
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7537 zero-terminated string.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7538 You cannot pass the data to standard C library functions
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7539 such as <c-func>strlen</c-func> or <c-func>strstr</c-func>.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7540 Instead, nginx <link id="string_overview">counterparts</link>
2412 bd026d5898b8 Minor language improvements in Development guide. Yaroslav Zhuravlev <yar@nginx.com> parents: 2410 diff changeset	7541 that accept either <literal>ngx_str_t</literal> should be used
2410 392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7542 or pointer to data and a length.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7543 However, there is a case when <literal>ngx_str_t</literal> holds
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7544 a pointer to a zero-terminated string: strings that come as a result of
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7545 configuration file parsing are zero-terminated.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7546 </para>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7547
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7548 </section>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7549
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7550 <section name="Global Variables" id="global_variables">
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7551
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7552 <para>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7553 Avoid using global variables in your modules.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7554 Most likely this is an error to have a global variable.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7555 Any global data should be tied to a <link id="cycle">configuration cycle</link>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7556 and be allocated from the corresponding <link id="pool">memory pool</link>.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7557 This allows nginx to perform graceful configuration reloads.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7558 An attempt to use global variables will likely break this feature,
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7559 because it will be impossible to have two configurations at
2412 bd026d5898b8 Minor language improvements in Development guide. Yaroslav Zhuravlev <yar@nginx.com> parents: 2410 diff changeset	7560 the same time and get rid of them.
2410 392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7561 Sometimes global variables are required.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7562 In this case, special attention is needed to manage reconfiguration
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7563 properly.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7564 Also, check if libraries used by your code have implicit
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7565 global state that may be broken on reload.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7566 </para>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7567
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7568 </section>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7569
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7570 <section name="Manual Memory Management" id="manual_memory_management">
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7571
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7572 <para>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7573 Instead of dealing with malloc/free approach which is error prone,
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7574 learn how to use nginx <link id="pool">pools</link>.
2412 bd026d5898b8 Minor language improvements in Development guide. Yaroslav Zhuravlev <yar@nginx.com> parents: 2410 diff changeset	7575 A pool is created and tied to an object -
2410 392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7576 <link id="http_conf">configuration</link>,
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7577 <link id="cycle">cycle</link>,
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7578 <link id="connection">connection</link>,
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7579 or <link id="http_request">HTTP request</link>.
2412 bd026d5898b8 Minor language improvements in Development guide. Yaroslav Zhuravlev <yar@nginx.com> parents: 2410 diff changeset	7580 When the object is destroyed, the associated pool is destroyed too.
bd026d5898b8 Minor language improvements in Development guide. Yaroslav Zhuravlev <yar@nginx.com> parents: 2410 diff changeset	7581 So when working with an object, it is possible to allocate the amount
bd026d5898b8 Minor language improvements in Development guide. Yaroslav Zhuravlev <yar@nginx.com> parents: 2410 diff changeset	7582 needed from the corresponding pool and don't care about freeing memory
2410 392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7583 even in case of errors.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7584 </para>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7585
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7586 </section>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7587
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7588 <section name="Threads" id="threads_pitfalls">
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7589
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7590 <para>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7591 It is recommended to avoid using threads in nginx because it will
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7592 definitely break things: most nginx functions are not thread-safe.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7593 It is expected that a thread will be executing only system calls and
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7594 thread-safe library functions.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7595 If you need to run some code that is not related to client request processing,
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7596 the proper way is to schedule a timer in the <literal>init_process</literal>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7597 module handler and perform required actions in timer handler.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7598 Internally nginx makes use of <link id="threads">threads</link> to
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7599 boost IO-related operations, but this is a special case with a lot
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7600 of limitations.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7601 </para>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7602
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7603 </section>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7604
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7605 <section name="Blocking Libraries" id="libraries">
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7606
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7607 <para>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7608 A common mistake is to use libraries that are blocking internally.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7609 Most libraries out there are synchronous and blocking by nature.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7610 In other words, they perform one operation at a time and waste
2412 bd026d5898b8 Minor language improvements in Development guide. Yaroslav Zhuravlev <yar@nginx.com> parents: 2410 diff changeset	7611 time waiting for response from other peer.
2410 392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7612 As a result, when a request is processed with such library, whole
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7613 nginx worker is blocked, thus destroying performance.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7614 Use only libraries that provide asynchronous interface and don't
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7615 block whole process.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7616 </para>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7617
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7618 </section>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7619
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7620
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7621 <section name="HTTP Requests to External Services" id="http_requests_to_ext">
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7622
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7623 <para>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7624 Often modules need to perform an HTTP call to some external service.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7625 A common mistake is to use some external library, such as libcurl,
2412 bd026d5898b8 Minor language improvements in Development guide. Yaroslav Zhuravlev <yar@nginx.com> parents: 2410 diff changeset	7626 to perform the HTTP request.
2410 392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7627 It is absolutely unnecessary to bring a huge amount of external
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7628 (probably <link id="using_libraries">blocking</link>!) code
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7629 for the task which can be accomplished by nginx itself.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7630 </para>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7631
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7632 <para>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7633 There are two basic usage scenarios when an external request is needed:
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7634
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7635 <list type="bullet">
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7636
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7637 <listitem>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7638 in the context of processing a client request (for example, in content handler)
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7639 </listitem>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7640
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7641 <listitem>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7642 in the context of a worker process (for example, timer handler)
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7643 </listitem>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7644
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7645 </list>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7646
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7647 </para>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7648
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7649 <para>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7650 In the first case, the best is to use
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7651 <link id="http_subrequests">subrequests API</link>.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7652 Instead of directly accessing external service, you declare a location
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7653 in nginx configuration and direct your subrequest to this location.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7654 This location is not limited to
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7655 <link doc="../http/ngx_http_proxy_module.xml" id="proxy_pass">proxying</link>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7656 requests, but may contain other nginx directives.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7657 An example of such approach is the
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7658 <link doc="../http/ngx_http_auth_request_module.xml" id="auth_request"/>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7659 directive implemented in
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7660 <link url="http://hg.nginx.org/nginx/file/tip/src/http/modules/ngx_http_auth_request_module.c">ngx_http_auth_request module</link>.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7661 </para>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7662
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7663 <para>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7664 For the second case, it is possible to use basic HTTP client functionality
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7665 available in nginx.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7666 For example,
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7667 <link url="http://hg.nginx.org/nginx/file/tip/src/event/ngx_event_openssl_stapling.c">OCSP module</link>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7668 implements simple HTTP client.
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7669 </para>
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7670
392e11db3260 Development guide: added the "Common Pitfalls" section. Vladimir Homutov <vl@nginx.com> parents: 2406 diff changeset	7671 </section>
2153 ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7672
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7673 </section>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7674
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	7675 </article>

Mercurial > hg > nginx-site

annotate xml/en/docs/dev/development_guide.xml @ 2994:537b98ec3c83