Mercurial > hg > nginx-site
comparison xml/en/docs/dev/development_guide.xml @ 1959:d0aebb2337ec
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, &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, &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(&val); | |
4512 | |
4513 if (s == NGX_ERROR) { | |
4514 ngx_log_error(NGX_LOG_ERR, r->connection->log, 0, | |
4515 "invalid size \"%V\"", &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(&ccv, sizeof(ngx_http_compile_complex_value_t)); | |
4555 | |
4556 ccv.cf = cf; | |
4557 ccv.value = &value[1]; | |
4558 ccv.complex_value = &cv; | |
4559 ccv.zero = 1; | |
4560 ccv.conf_prefix = 1; | |
4561 | |
4562 if (ngx_http_compile_complex_value(&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, &cv, &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> |