nginx-site: xml/en/docs/http/ngx_http_perl

annotate xml/en/docs/http/ngx_http_perl_module.xml @ 1391:0702cc081c63

Revised descriptions of upstream module variables.

author	Ruslan Ermilov <ru@nginx.com>
date	Mon, 19 Jan 2015 15:23:46 +0300
parents	ac1b01d37929
children	31f21c7956dd

rev	line source
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1 <?xml version="1.0"?>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	2
580 be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 416 diff changeset	3 <!--
be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 416 diff changeset	4 Copyright (C) Igor Sysoev
be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 416 diff changeset	5 Copyright (C) Nginx, Inc.
be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 416 diff changeset	6 -->
be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 416 diff changeset	7
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	9
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	10 <module name="Module ngx_http_perl_module"
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	11 link="/en/docs/http/ngx_http_perl_module.html"
589 764fbac1b8b4 Added document revision. Ruslan Ermilov <ru@nginx.com> parents: 580 diff changeset	12 lang="en"
1251 ac1b01d37929 Perl module: removed info specific to nginx 0.6.22 and earlier. Yaroslav Zhuravlev <yar@nginx.com> parents: 1146 diff changeset	13 rev="3">
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	14
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	15 <section id="summary">
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	16
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	17 <para>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	18 The <literal>ngx_http_perl_module</literal> module is used to implement
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	19 location and variable handlers in Perl and insert Perl calls into SSI.
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	20 </para>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	21
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	22 <para>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	23 This module is not built by default, it should be enabled with the
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	24 <literal>--with-http_perl_module</literal>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	25 configuration parameter.
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	26 <note>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	27 This module requires Perl version 5.6.1 or higher.
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	28 The C compiler should be compatible with the one used to build Perl.
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	29 </note>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	30 </para>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	31
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	32 </section>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	33
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	34
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	35 <section id="bugs" name="Known Bugs">
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	36
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	37 <para>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	38 The module is experimental, caveat emptor applies.
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	39 </para>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	40
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	41 <para>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	42 In order for Perl to recompile the modified modules during
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	43 reconfiguration, it should be built with the
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	44 <literal>-Dusemultiplicity=yes</literal> or
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	45 <literal>-Dusethreads=yes</literal> parameters.
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	46 Also, to make Perl leak less memory at run time,
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	47 it should be built with the
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	48 <literal>-Dusemymalloc=no</literal> parameter.
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	49 To check the values of these parameters in an already built
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	50 Perl (preferred values are specified in the example), run:
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	51 <example>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	52 $ perl -V:usemultiplicity -V:usemymalloc
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	53 usemultiplicity='define';
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	54 usemymalloc='n';
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	55 </example>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	56 </para>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	57
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	58 <para>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	59 Note that after rebuilding Perl with the new
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	60 <literal>-Dusemultiplicity=yes</literal> or
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	61 <literal>-Dusethreads=yes</literal> parameters,
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	62 all binary Perl modules will have to be rebuilt as well —
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	63 they will just stop working with the new Perl.
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	64 </para>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	65
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	66 <para>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	67 There is a possibility that the main process and then worker processes will
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	68 grow in size after every reconfiguration.
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	69 If the main process grows to an unacceptable size, the
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	70 <link doc="../control.xml" id="upgrade">live upgrade</link>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	71 procedure can be applied without changing the executable file.
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	72 </para>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	73
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	74 <para>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	75 While the Perl module is performing a long-running operation, such as
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	76 resolving a domain name, connecting to another server, or querying a database,
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	77 other requests assigned to the current worker process will not be processed.
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	78 It is thus recommended to perform only such operations
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	79 that have predictable and short execution time, such as
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	80 accessing the local file system.
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	81 </para>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	82
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	83 </section>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	84
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	85
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	86 <section id="example" name="Example Configuration">
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	87
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	88 <para>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	89 <example>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	90 http {
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	91
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	92 perl_modules perl/lib;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	93 perl_require hello.pm;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	94
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	95 perl_set $msie6 '
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	96
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	97 sub {
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	98 my $r = shift;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	99 my $ua = $r->header_in("User-Agent");
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	100
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	101 return "" if $ua =~ /Opera/;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	102 return "1" if $ua =~ / MSIE [6-9]\.\d+/;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	103 return "";
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	104 }
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	105
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	106 ';
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	107
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	108 server {
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	109 location / {
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	110 perl hello::handler;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	111 }
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	112 }
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	113 </example>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	114 </para>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	115
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	116 <para>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	117 The <path>perl/lib/hello.pm</path> module:
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	118 <example>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	119 package hello;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	120
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	121 use nginx;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	122
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	123 sub handler {
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	124 my $r = shift;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	125
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	126 $r->send_http_header("text/html");
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	127 return OK if $r->header_only;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	128
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	129 $r->print("hello!\n<br/>");
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	130
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	131 if (-f $r->filename or -d _) {
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	132 $r->print($r->uri, " exists!\n");
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	133 }
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	134
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	135 return OK;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	136 }
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	137
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	138 1;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	139 __END__
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	140 </example>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	141 </para>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	142
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	143 </section>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	144
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	145
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	146 <section id="directives" name="Directives">
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	147
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	148 <directive name="perl">
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	149 <syntax><value>module</value>::<value>function</value>\|'sub { ... }'</syntax>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	150 <default/>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	151 <context>location</context>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	152 <context>limit_except</context>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	153
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	154 <para>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	155 Sets a Perl handler for the given location.
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	156 </para>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	157
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	158 </directive>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	159
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	160
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	161 <directive name="perl_modules">
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	162 <syntax><value>path</value></syntax>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	163 <default/>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	164 <context>http</context>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	165
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	166 <para>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	167 Sets an additional path for Perl modules.
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	168 </para>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	169
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	170 </directive>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	171
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	172
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	173 <directive name="perl_require">
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	174 <syntax><value>module</value></syntax>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	175 <default/>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	176 <context>http</context>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	177
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	178 <para>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	179 Defines the name of a module that will be loaded during each
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	180 reconfiguration.
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	181 Several <literal>perl_require</literal> directives can be present.
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	182 </para>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	183
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	184 </directive>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	185
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	186
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	187 <directive name="perl_set">
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	188 <syntax>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	189 <value>$variable</value>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	190 <value>module</value>::<value>function</value>\|'sub { ... }'</syntax>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	191 <default/>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	192 <context>http</context>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	193
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	194 <para>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	195 Installs a Perl handler for the specified variable.
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	196 </para>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	197
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	198 </directive>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	199
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	200 </section>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	201
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	202
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	203 <section id="ssi" name="Calling Perl from SSI">
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	204
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	205 <para>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	206 An SSI command calling Perl has the following format:
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	207 <example>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	208 <!--# perl sub="<value>module</value>::<value>function</value>" arg="<value>parameter1</value>" arg="<value>parameter2</value>" ...
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	209 -->
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	210 </example>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	211 </para>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	212
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	213 </section>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	214
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	215
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	216 <section id="methods" name="The $r Request Object Methods">
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	217
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	218 <para>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	219 <list type="tag">
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	220
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	221 <tag-name><literal>$r->args</literal></tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	222 <tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	223 returns request arguments.
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	224 </tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	225
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	226 <tag-name><literal>$r->filename</literal></tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	227 <tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	228 returns a filename corresponding to the request URI.
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	229 </tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	230
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	231 <tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	232 <literal>$r->has_request_body(<value>handler</value>)</literal>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	233 </tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	234 <tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	235 returns 0 if there is no body in a request.
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	236 If there is a body, the specified handler is set for the request
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	237 and 1 is returned.
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	238 After reading the request body, nginx will call the specified handler.
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	239 Note that the handler function should be passed by reference.
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	240 Example:
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	241 <example>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	242 package hello;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	243
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	244 use nginx;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	245
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	246 sub handler {
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	247 my $r = shift;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	248
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	249 if ($r->request_method ne "POST") {
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	250 return DECLINED;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	251 }
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	252
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	253 if ($r->has_request_body(<emphasis>\&post</emphasis>)) {
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	254 return OK;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	255 }
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	256
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	257 return HTTP_BAD_REQUEST;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	258 }
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	259
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	260 sub <emphasis>post</emphasis> {
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	261 my $r = shift;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	262
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	263 $r->send_http_header;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	264
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	265 $r->print("request_body: \"", $r->request_body, "\"<br/>");
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	266 $r->print("request_body_file: \"", $r->request_body_file, "\"<br/>\n");
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	267
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	268 return OK;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	269 }
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	270
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	271 1;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	272
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	273 __END__
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	274 </example>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	275 </tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	276
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	277 <tag-name><literal>$r->allow_ranges</literal></tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	278 <tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	279 enables the use of byte ranges when sending responses.
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	280 </tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	281
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	282 <tag-name><literal>$r->discard_request_body</literal></tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	283 <tag-desc>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	284 instructs nginx to discard the request body.
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	285 </tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	286
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	287 <tag-name><literal>$r->header_in(<value>field</value>)</literal></tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	288 <tag-desc>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	289 returns the value of the specified client request header field.
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	290 </tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	291
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	292 <tag-name><literal>$r->header_only</literal></tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	293 <tag-desc>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	294 determines whether the whole response or only its header should be sent to
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	295 the client.
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	296 </tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	297
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	298 <tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	299 <literal>$r->header_out(<value>field</value>,
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	300 <value>value</value>)</literal>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	301 </tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	302 <tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	303 sets a value for the specified response header field.
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	304 </tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	305
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	306 <tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	307 <literal>$r->internal_redirect(<value>uri</value>)</literal>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	308 </tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	309 <tag-desc>
747 ddec437b692b Fixed a number of typos. Vladimir Homutov <vl@nginx.com> parents: 589 diff changeset	310 does an internal redirect to the specified <value>uri</value>.
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	311 An actual redirect happens after the Perl handler execution is completed.
760 f0e3d07c66d8 Documented $r->log_error method, redirection limitation, removed outdated info. Vladimir Homutov <vl@nginx.com> parents: 747 diff changeset	312 <note>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	313 Redirections to named locations are currently not supported.
760 f0e3d07c66d8 Documented $r->log_error method, redirection limitation, removed outdated info. Vladimir Homutov <vl@nginx.com> parents: 747 diff changeset	314 </note>
f0e3d07c66d8 Documented $r->log_error method, redirection limitation, removed outdated info. Vladimir Homutov <vl@nginx.com> parents: 747 diff changeset	315 </tag-desc>
f0e3d07c66d8 Documented $r->log_error method, redirection limitation, removed outdated info. Vladimir Homutov <vl@nginx.com> parents: 747 diff changeset	316
f0e3d07c66d8 Documented $r->log_error method, redirection limitation, removed outdated info. Vladimir Homutov <vl@nginx.com> parents: 747 diff changeset	317 <tag-name><literal>$r->log_error(<value>errno</value>,
f0e3d07c66d8 Documented $r->log_error method, redirection limitation, removed outdated info. Vladimir Homutov <vl@nginx.com> parents: 747 diff changeset	318 <value>message</value>)</literal></tag-name>
f0e3d07c66d8 Documented $r->log_error method, redirection limitation, removed outdated info. Vladimir Homutov <vl@nginx.com> parents: 747 diff changeset	319 <tag-desc>
f0e3d07c66d8 Documented $r->log_error method, redirection limitation, removed outdated info. Vladimir Homutov <vl@nginx.com> parents: 747 diff changeset	320 writes the specified <value>message</value> into the
f0e3d07c66d8 Documented $r->log_error method, redirection limitation, removed outdated info. Vladimir Homutov <vl@nginx.com> parents: 747 diff changeset	321 <link doc="../ngx_core_module.xml" id="error_log"/>.
f0e3d07c66d8 Documented $r->log_error method, redirection limitation, removed outdated info. Vladimir Homutov <vl@nginx.com> parents: 747 diff changeset	322 If <value>errno</value> is non-zero, an error code and its description
f0e3d07c66d8 Documented $r->log_error method, redirection limitation, removed outdated info. Vladimir Homutov <vl@nginx.com> parents: 747 diff changeset	323 will be appended to the message.
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	324 </tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	325
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	326 <tag-name><literal>$r->print(<value>text</value>, ...)</literal></tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	327 <tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	328 passes data to a client.
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	329 </tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	330
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	331 <tag-name><literal>$r->request_body</literal></tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	332 <tag-desc>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	333 returns the client request body if it has not been
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	334 written to a temporary file.
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	335 To ensure that the client request body is in memory,
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	336 its size should be limited by
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	337 <link doc="ngx_http_core_module.xml" id="client_max_body_size"/>,
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	338 and a sufficient buffer size should be set using
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	339 <link doc="ngx_http_core_module.xml" id="client_body_buffer_size"/>.
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	340 </tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	341
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	342 <tag-name><literal>$r->request_body_file</literal></tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	343 <tag-desc>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	344 returns the name of the file with the client request body.
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	345 After the processing, the file should be removed.
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	346 To always write a request body to a file,
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	347 <link doc="ngx_http_core_module.xml" id="client_body_in_file_only"/>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	348 should be enabled.
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	349 </tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	350
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	351 <tag-name><literal>$r->request_method</literal></tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	352 <tag-desc>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	353 returns the client request HTTP method.
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	354 </tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	355
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	356 <tag-name><literal>$r->remote_addr</literal></tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	357 <tag-desc>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	358 returns the client IP address.
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	359 </tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	360
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	361 <tag-name><literal>$r->flush</literal></tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	362 <tag-desc>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	363 immediately sends data to the client.
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	364 </tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	365
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	366 <tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	367 <literal>$r->sendfile(<value>name</value>[,
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	368 <value>offset</value>[,
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	369 <value>length</value>]])</literal>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	370 </tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	371 <tag-desc>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	372 sends the specified file content to the client.
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	373 Optional parameters
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	374 specify the initial offset and length of the data to be transmitted.
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	375 The actual data transmission happens after the Perl handler
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	376 has completed.
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	377 </tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	378
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	379 <tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	380 <literal>$r->send_http_header([<value>type</value>])</literal>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	381 </tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	382 <tag-desc>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	383 sends the response header to the client.
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	384 The optional <value>type</value> parameter sets the value of
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	385 the <header>Content-Type</header> response header field.
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	386 If the value is an empty string, the <header>Content-Type</header>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	387 header field will not be sent.
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	388 </tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	389
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	390 <tag-name><literal>$r->status(<value>code</value>)</literal></tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	391 <tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	392 sets a response code.
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	393 </tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	394
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	395 <tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	396 <literal>$r->sleep(<value>milliseconds</value>,
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	397 <value>handler</value>)</literal>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	398 </tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	399 <tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	400 sets the specified handler
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	401 and stops request processing for the specified time.
1146 d37892ad69ab Corrected spelling in the "in the meantime" phrase. Yaroslav Zhuravlev <yar@nginx.com> parents: 966 diff changeset	402 In the meantime, nginx continues to process other requests.
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	403 After the specified time has elapsed, nginx will call the installed handler.
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	404 Note that the handler function should be passed by reference.
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	405 In order to pass data between handlers,
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	406 <literal>$r->variable()</literal> should be used.
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	407 Example:
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	408 <example>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	409 package hello;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	410
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	411 use nginx;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	412
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	413 sub handler {
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	414 my $r = shift;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	415
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	416 $r->discard_request_body;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	417 $r->variable("var", "OK");
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	418 $r->sleep(1000, <emphasis>\&next</emphasis>);
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	419
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	420 return OK;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	421 }
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	422
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	423 sub <emphasis>next</emphasis> {
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	424 my $r = shift;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	425
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	426 $r->send_http_header;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	427 $r->print($r->variable("var"));
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	428
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	429 return OK;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	430 }
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	431
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	432 1;
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	433
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	434 __END__
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	435 </example>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	436 </tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	437
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	438 <tag-name><literal>$r->unescape(<value>text</value>)</literal></tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	439 <tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	440 decodes a text encoded in the “%XX” form.
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	441 </tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	442
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	443 <tag-name><literal>$r->uri</literal></tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	444 <tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	445 returns a request URI.
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	446 </tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	447
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	448 <tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	449 <literal>$r->variable(<value>name</value>[,
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	450 <value>value</value>])</literal>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	451 </tag-name>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	452 <tag-desc>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 760 diff changeset	453 returns or sets the value of the specified variable.
416 c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	454 Variables are local to each request.
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	455 </tag-desc>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	456
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	457 </list>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	458 </para>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	459
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	460 </section>
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	461
c9c0550465c9 English translation of ngx_http_perl_module. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	462 </module>

Mercurial > hg > nginx-site

annotate xml/en/docs/http/ngx_http_perl_module.xml @ 1391:0702cc081c63