Mercurial > hg > nginx-site

comparison xml/en/docs/dev/development_guide.xml @ 1959:d0aebb2337ec

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added the "Variables" section to the development guide.
author Vladimir Homutov <vl@nginx.com>
date Fri, 07 Apr 2017 18:07:18 +0300
parents 95a7e6eb5270
children 9550ea66abdd
comparison
equal deleted inserted replaced
1958:95a7e6eb5270 1959:d0aebb2337ec
4244 </para> 4244 </para>
4245 4245
4246 </section> 4246 </section>
4247 4247
4248 4248
4249 <section name="Variables" id="http_variables">
4250
4251 <section name="Accessing existing variables" id="http_existing_variables">
4252
4253 <para>
4254 Variables may be referenced using index (this is the most common method)
4255 or names (see below in the section about creating variables).
4256 Index is created at configuration stage, when a variable is added
4257 to configuration.
4258 The variable index can be obtained using
4259 <literal>ngx_http_get_variable_index()</literal>:
4260 <programlisting>
4261 ngx_str_t name; /* ngx_string("foo") */
4262 ngx_int_t index;
4263
4264 index = ngx_http_get_variable_index(cf, &amp;name);
4265 </programlisting>
4266 Here, the <literal>cf</literal> is a pointer to nginx configuration and the
4267 <literal>name</literal> points to a string with the variable name.
4268 The function returns <literal>NGX_ERROR</literal> on error or valid index
4269 otherwise, which is typically stored somewhere in a module configuration for
4270 future use.
4271 </para>
4272
4273 <para>
4274 All HTTP variables are evaluated in the context of HTTP request and results
4275 are specific to and cached in HTTP request.
4276 All functions that evaluate variables return
4277 <literal>ngx_http_variable_value_t</literal> type, representing
4278 the variable value:
4279 <programlisting>
4280 typedef ngx_variable_value_t ngx_http_variable_value_t;
4281
4282 typedef struct {
4283 unsigned len:28;
4284
4285 unsigned valid:1;
4286 unsigned no_cacheable:1;
4287 unsigned not_found:1;
4288 unsigned escape:1;
4289
4290 u_char *data;
4291 } ngx_variable_value_t;
4292 </programlisting>
4293 where:
4294 <list type="bullet">
4295
4296 <listitem>
4297 <literal>len</literal> — length of a value
4298 </listitem>
4299
4300 <listitem>
4301 <literal>data</literal> — value itself
4302 </listitem>
4303
4304 <listitem>
4305 <literal>valid</literal> — value is valid
4306 </listitem>
4307
4308 <listitem>
4309 <literal>not_found</literal> — variable was not found and thus
4310 the <literal>data</literal> and <literal>len</literal> fields are irrelevant;
4311 this may happen, for example, with such variables as <var>$arg_foo</var>
4312 when a corresponding argument was not passed in a request
4313 </listitem>
4314
4315 <listitem>
4316 <literal>no_cacheable</literal> — do not cache result
4317 </listitem>
4318
4319 <listitem>
4320 <literal>escape</literal> — used internally by the logging module to mark
4321 values that require escaping on output
4322 </listitem>
4323
4324 </list>
4325 </para>
4326
4327 <para>
4328 The <literal>ngx_http_get_flushed_variable()</literal>
4329 and <literal>ngx_http_get_indexed_variable()</literal> functions
4330 are used to obtain the variable value.
4331 They have the same interface - accepting a HTTP request <literal>r</literal>
4332 as a context for evaluating the variable and an <literal>index</literal>,
4333 identifying it.
4334 Example of typical usage:
4335 <programlisting>
4336 ngx_http_variable_value_t *v;
4337
4338 v = ngx_http_get_flushed_variable(r, index);
4339
4340 if (v == NULL || v->not_found) {
4341 /* we failed to get value or there is no such variable, handle it */
4342 return NGX_ERROR;
4343 }
4344
4345 /* some meaningful value is found */
4346 </programlisting>
4347 The difference between functions is that the
4348 <literal>ngx_http_get_indexed_variable()</literal> returns cached value
4349 and <literal>ngx_http_get_flushed_variable()</literal> flushes cache for
4350 non-cacheable variables.
4351 </para>
4352
4353 <para>
4354 There are cases when it is required to deal with variables which names are
4355 not known at configuration time and thus they cannot be accessed using indexes,
4356 for example in modules like SSI or Perl.
4357 The <literal>ngx_http_get_variable(r, name, key)</literal> function may be
4358 used in such cases.
4359 It searches for the <literal>variable</literal> with a given
4360 <literal>name</literal> and its hash <literal>key</literal>.
4361 </para>
4362
4363 </section>
4364
4365
4366 <section name="Creating variables" id="http_creating_variables">
4367
4368 <para>
4369 To create a variable <literal>ngx_http_add_variable()</literal> function
4370 is used.
4371 It takes configuration (where variable is registered), variable name and
4372 flags that control its behaviour:
4373
4374 <list type="bullet">
4375 <listitem><literal>NGX_HTTP_VAR_CHANGEABLE</literal>  — allows redefining
4376 the variable; If another module will define a variable with such name,
4377 no conflict will happen.
4378 For example, this allows user to override variables using the
4379 <link doc="../http/ngx_http_rewrite_module.xml" id="set"/> directive.
4380 </listitem>
4381
4382 <listitem><literal>NGX_HTTP_VAR_NOCACHEABLE</literal>  — disables caching,
4383 is useful for such variables as <literal>$time_local</literal>
4384 </listitem>
4385
4386 <listitem><literal>NGX_HTTP_VAR_NOHASH</literal>  — indicates that
4387 this variable is only accessible by index, not by name.
4388 This is a small optimization which may be used when it is known that the
4389 variable is not needed in modules like SSI or Perl.
4390 </listitem>
4391
4392 <listitem><literal>NGX_HTTP_VAR_PREFIX</literal>  — the name of this
4393 variable is a prefix.
4394 A handler must implement additional logic to obtain value of specific
4395 variable.
4396 For example, all “<literal>arg_</literal>” variables are processed by the
4397 same handler which performs lookup in request arguments and returns value
4398 of specific argument.
4399 </listitem>
4400
4401 </list>
4402
4403 The function returns NULL in case of error or a pointer to
4404 <literal>ngx_http_variable_t</literal>:
4405 <programlisting>
4406 struct ngx_http_variable_s {
4407 ngx_str_t name;
4408 ngx_http_set_variable_pt set_handler;
4409 ngx_http_get_variable_pt get_handler;
4410 uintptr_t data;
4411 ngx_uint_t flags;
4412 ngx_uint_t index;
4413 };
4414 </programlisting>
4415
4416 The <literal>get</literal> and <literal>set</literal> handlers
4417 are called to obtain or set the variable value,
4418 <literal>data</literal> will be passed to variable handlers,
4419 <literal>index</literal> will hold assigned variable index, used to reference
4420 the variable.
4421 </para>
4422
4423 <para>
4424 Usually, a null-terminated static array of such structures is created
4425 by a module and processed at the preconfiguration stage to add variables
4426 into configuration:
4427 <programlisting>
4428 static ngx_http_variable_t ngx_http_foo_vars[] = {
4429
4430 { ngx_string("foo_v1"), NULL, ngx_http_foo_v1_variable, NULL, 0, 0 },
4431
4432 { ngx_null_string, NULL, NULL, 0, 0, 0 }
4433 };
4434
4435 static ngx_int_t
4436 ngx_http_foo_add_variables(ngx_conf_t *cf)
4437 {
4438 ngx_http_variable_t *var, *v;
4439
4440 for (v = ngx_http_foo_vars; v->name.len; v++) {
4441 var = ngx_http_add_variable(cf, &amp;v->name, v->flags);
4442 if (var == NULL) {
4443 return NGX_ERROR;
4444 }
4445
4446 var->get_handler = v->get_handler;
4447 var->data = v->data;
4448 }
4449
4450 return NGX_OK;
4451 }
4452 </programlisting>
4453 This function is used to initialize the <literal>preconfiguration</literal>
4454 field of the HTTP module context and is called before parsing HTTP configuration,
4455 so it could refer to these variables.
4456 </para>
4457
4458 <para>
4459 The <literal>get</literal> handler is responsible for evaluating the variable
4460 in a context of specific request, for example:
4461 <programlisting>
4462 static ngx_int_t
4463 ngx_http_variable_connection(ngx_http_request_t *r,
4464 ngx_http_variable_value_t *v, uintptr_t data)
4465 {
4466 u_char *p;
4467
4468 p = ngx_pnalloc(r->pool, NGX_ATOMIC_T_LEN);
4469 if (p == NULL) {
4470 return NGX_ERROR;
4471 }
4472
4473 v->len = ngx_sprintf(p, "%uA", r->connection->number) - p;
4474 v->valid = 1;
4475 v->no_cacheable = 0;
4476 v->not_found = 0;
4477 v->data = p;
4478
4479 return NGX_OK;
4480 }
4481 </programlisting>
4482 It returns <literal>NGX_ERROR</literal> in case of internal error
4483 (for example, failed memory allocation) or <literal>NGX_OK</literal> otherwise.
4484 The status of variable evaluation may be understood by inspecting flags
4485 of the <literal>ngx_http_variable_value_t</literal> (see description above).
4486 </para>
4487
4488 <para>
4489 The <literal>set</literal> handler allows setting the property
4490 referred by the variable.
4491 For example, the <literal>$limit_rate</literal> variable set handler
4492 modifies the request's <literal>limit_rate</literal> field:
4493 <programlisting>
4494 ...
4495 { ngx_string("limit_rate"), ngx_http_variable_request_set_size,
4496 ngx_http_variable_request_get_size,
4497 offsetof(ngx_http_request_t, limit_rate),
4498 NGX_HTTP_VAR_CHANGEABLE|NGX_HTTP_VAR_NOCACHEABLE, 0 },
4499 ...
4500
4501 static void
4502 ngx_http_variable_request_set_size(ngx_http_request_t *r,
4503 ngx_http_variable_value_t *v, uintptr_t data)
4504 {
4505 ssize_t s, *sp;
4506 ngx_str_t val;
4507
4508 val.len = v->len;
4509 val.data = v->data;
4510
4511 s = ngx_parse_size(&amp;val);
4512
4513 if (s == NGX_ERROR) {
4514 ngx_log_error(NGX_LOG_ERR, r->connection->log, 0,
4515 "invalid size \"%V\"", &amp;val);
4516 return;
4517 }
4518
4519 sp = (ssize_t *) ((char *) r + data);
4520
4521 *sp = s;
4522
4523 return;
4524 }
4525 </programlisting>
4526
4527 </para>
4528
4529 </section>
4530
4531 </section>
4532
4533
4534 <section name="Complex values" id="http_complex_values">
4535
4536 <para>
4537 A complex value, despite its name, provides an easy way to evaluate
4538 expressions that may contain text, variables, and their combination.
4539 </para>
4540
4541 <para>
4542 The complex value description in
4543 <literal>ngx_http_compile_complex_value</literal> is compiled at the
4544 configuration stage into <literal>ngx_http_complex_value_t</literal>
4545 which is used at runtime to obtain evaluated expression results.
4546
4547 <programlisting>
4548 ngx_str_t *value;
4549 ngx_http_complex_value_t cv;
4550 ngx_http_compile_complex_value_t ccv;
4551
4552 value = cf->args->elts; /* directive arguments */
4553
4554 ngx_memzero(&amp;ccv, sizeof(ngx_http_compile_complex_value_t));
4555
4556 ccv.cf = cf;
4557 ccv.value = &amp;value[1];
4558 ccv.complex_value = &amp;cv;
4559 ccv.zero = 1;
4560 ccv.conf_prefix = 1;
4561
4562 if (ngx_http_compile_complex_value(&amp;ccv) != NGX_OK) {
4563 return NGX_CONF_ERROR;
4564 }
4565 </programlisting>
4566
4567 Here, <literal>ccv</literal> holds all parameters that are required to
4568 initialize the complex value <literal>cv</literal>:
4569
4570 <list type="bullet">
4571
4572 <listitem>
4573 <literal>cf</literal> — configuration pointer
4574 </listitem>
4575
4576 <listitem>
4577 <literal>value</literal> — string for parsing (input)
4578 </listitem>
4579
4580 <listitem>
4581 <literal>complex_value</literal> — compiled value (output)
4582 </listitem>
4583
4584 <listitem>
4585 <literal>zero</literal> — flag that enables zero-terminating value
4586 </listitem>
4587
4588 <listitem>
4589 <literal>conf_prefix</literal> — prefixes result with configuration prefix
4590 (the directory where nginx is currently looking for configuration)
4591 </listitem>
4592
4593 <listitem>
4594 <literal>root_prefix</literal> — prefixes result with root prefix
4595 (this is the normal nginx installation prefix)
4596 </listitem>
4597
4598 </list>
4599 The <literal>zero</literal> flag is usable when results are to be passed to
4600 libraries that require zero-terminated strings, and prefixes are handy when
4601 dealing with filenames.
4602 </para>
4603
4604 <para>
4605 Upon successful compilation, <literal>cv.lengths</literal> may
4606 be inspected to get information about the presence of variables
4607 in the expression.
4608 The NULL value means that the expression contained static text only,
4609 and there is no need in storing it as a complex value,
4610 so a simple string can be used.
4611 </para>
4612
4613 <para>
4614 The <literal>ngx_http_set_complex_value_slot()</literal> is a convenient
4615 function used to initialize complex value completely right in the directive
4616 declaration.
4617 </para>
4618
4619 <para>
4620 At runtime, a complex value may be calculated using the
4621 <literal>ngx_http_complex_value()</literal> function:
4622 <programlisting>
4623 ngx_str_t res;
4624
4625 if (ngx_http_complex_value(r, &amp;cv, &amp;res) != NGX_OK) {
4626 return NGX_ERROR;
4627 }
4628 </programlisting>
4629 Given the request <literal>r</literal> and previously compiled
4630 value <literal>cv</literal> the function will evaluate
4631 expression and put result into <literal>res</literal>.
4632 </para>
4633
4634 </section>
4635
4636
4249 <section name="Load balancing" id="http_load_balancing"> 4637 <section name="Load balancing" id="http_load_balancing">
4250 4638
4251 <para> 4639 <para>
4252 The 4640 The
4253 <link doc="../http/ngx_http_upstream_module.xml">ngx_http_upstream_module</link> 4641 <link doc="../http/ngx_http_upstream_module.xml">ngx_http_upstream_module</link>