Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_perl_module.xml @ 416:c9c0550465c9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
English translation of ngx_http_perl_module.
author Ruslan Ermilov <ru@nginx.com>
date Wed, 15 Feb 2012 14:45:05 +0000
parents
children be54c443235a
comparison
equal deleted inserted replaced
415:c640e00858ed 416:c9c0550465c9
1 <?xml version="1.0"?>
2
3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
4
5 <module name="Module ngx_http_perl_module"
6 link="/en/docs/http/ngx_http_perl_module.html"
7 lang="en">
8
9 <section id="summary">
10
11 <para>
12 The <literal>ngx_http_perl_module</literal> module allows to implement
13 location and variable handlers in Perl, and to insert Perl calls into SSI.
14 </para>
15
16 <para>
17 This module is not built by default, it should be enabled with the
18 <literal>--with-http_perl_module</literal>
19 configuration parameter.
20 <note>
21 This module requires Perl version 5.6.1 or higher.
22 The C compiler should be compatible with that used to build Perl.
23 </note>
24 </para>
25
26 </section>
27
28
29 <section id="bugs" name="Known Bugs">
30
31 <para>
32 The module is experimental, caveat emptor applies.
33 </para>
34
35 <para>
36 In order for Perl to recompile the modified modules during
37 reconfiguration, it needs to be built with the parameters
38 <literal>-Dusemultiplicity=yes</literal> or
39 <literal>-Dusethreads=yes</literal>.
40 Also, in order for Perl to leak less memory at run time,
41 it needs to be built with the
42 <literal>-Dusemymalloc=no</literal> parameter.
43 To check the values of these parameters in an already built
44 Perl (preferred values are specified in the example), run:
45 <example>
46 $ perl -V:usemultiplicity -V:usemymalloc
47 usemultiplicity='define';
48 usemymalloc='n';
49 </example>
50 </para>
51
52 <para>
53 Note that after rebuilding Perl with the new parameters
54 <literal>-Dusemultiplicity=yes</literal> or
55 <literal>-Dusethreads=yes</literal>,
56 all binary Perl modules will have to be rebuilt as well —
57 they will just stop working with the new Perl.
58 </para>
59
60 <para>
61 It is possible for the main process and then worker processes
62 to grow in size after every reconfiguration.
63 If the main process grows to an unacceptable size, the
64 <link doc="../control.xml" id="upgrade">live upgrade</link>
65 procedure can be applied without changing an executable file.
66 </para>
67
68 <para>
69 While a Perl module performs long term operation, for example, resolves
70 a domain name, connects to another server, queries a database,
71 other requests assigned to this worker process will not be processed.
72 It is thus recommended to limit the work done to operations
73 that have predictable and short execution time, for example,
74 access local file system.
75 </para>
76
77 <para>
78 The below mentioned issues only affect versions of nginx before 0.6.22.
79
80 <note>
81 Data returned by the <literal>$r</literal> request object methods
82 only has a text value, and the value itself is stored in memory
83 allocated by nginx from its own pools, not by Perl.
84 This allows to reduce the number of copy operations involved in
85 most cases, however it can lead to errors in some cases.
86 For example, a worker process trying to use such a data in the
87 numeric context will terminate with an error (FreeBSD):
88 <example>
89 nginx in realloc(): warning: pointer to wrong page
90 Out of memory!
91 Callback called exit.
92 </example>
93 or (Linux):
94 <example>
95 *** glibc detected *** realloc(): invalid pointer: ... ***
96 Out of memory!
97 Callback called exit.
98 </example>
99 The workaround is simple — a method’s value should be assigned
100 to a variable.
101 For example, the following code
102 <example>
103 my $i = $r->variable('counter') + 1;
104 </example>
105 should be replaced by
106 <example>
107 my $i = $r->variable('counter');
108 $i++;
109 </example>
110 </note>
111
112 <note>
113 Since most strings inside nginx are stored without a terminating null
114 character, they are similarly returned by the <literal>$r</literal> request
115 object methods (except for the <literal>$r->filename</literal> and
116 <literal>$r->request_body_file</literal> methods).
117 Thus, such values cannot be used as filenames and the likes.
118 The workaround is similar to a previous case — the value should either be
119 assigned to a variable (this results in data copying that in turn adds
120 the necessary null character) or used in an expression, for example:
121 <example>
122 open FILE, '/path/' . $r->variable('name');
123 </example>
124 </note>
125
126 </para>
127
128 </section>
129
130
131 <section id="example" name="Example Configuration">
132
133 <para>
134 <example>
135 http {
136
137 perl_modules perl/lib;
138 perl_require hello.pm;
139
140 perl_set $msie6 '
141
142 sub {
143 my $r = shift;
144 my $ua = $r->header_in("User-Agent");
145
146 return "" if $ua =~ /Opera/;
147 return "1" if $ua =~ / MSIE [6-9]\.\d+/;
148 return "";
149 }
150
151 ';
152
153 server {
154 location / {
155 perl hello::handler;
156 }
157 }
158 </example>
159 </para>
160
161 <para>
162 The <path>perl/lib/hello.pm</path> module:
163 <example>
164 package hello;
165
166 use nginx;
167
168 sub handler {
169 my $r = shift;
170
171 $r->send_http_header("text/html");
172 return OK if $r->header_only;
173
174 $r->print("hello!\n&lt;br/&gt;");
175
176 if (-f $r->filename or -d _) {
177 $r->print($r->uri, " exists!\n");
178 }
179
180 return OK;
181 }
182
183 1;
184 __END__
185 </example>
186 </para>
187
188 </section>
189
190
191 <section id="directives" name="Directives">
192
193 <directive name="perl">
194 <syntax><value>module</value>::<value>function</value>|'sub { ... }'</syntax>
195 <default/>
196 <context>location</context>
197 <context>limit_except</context>
198
199 <para>
200 Installs a Perl handler for the given location.
201 </para>
202
203 </directive>
204
205
206 <directive name="perl_modules">
207 <syntax><value>path</value></syntax>
208 <default/>
209 <context>http</context>
210
211 <para>
212 Sets an additional path for Perl modules.
213 </para>
214
215 </directive>
216
217
218 <directive name="perl_require">
219 <syntax><value>module</value></syntax>
220 <default/>
221 <context>http</context>
222
223 <para>
224 Defines the name of a module that will be loaded during each
225 reconfiguration.
226 There could be several <literal>perl_require</literal> directives.
227 </para>
228
229 </directive>
230
231
232 <directive name="perl_set">
233 <syntax>
234 <value>$variable</value>
235 <value>module</value>::<value>function</value>|'sub { ... }'</syntax>
236 <default/>
237 <context>http</context>
238
239 <para>
240 Installs a Perl handler for the specified variable.
241 </para>
242
243 </directive>
244
245 </section>
246
247
248 <section id="ssi" name="Calling Perl from SSI">
249
250 <para>
251 An SSI command calling Perl has the following format:
252 <example>
253 &lt;!--# perl sub="<value>module</value>::<value>function</value>" arg="<value>parameter1</value>" arg="<value>parameter2</value>" ...
254 --&gt;
255 </example>
256 </para>
257
258 </section>
259
260
261 <section id="methods" name="The $r Request Object Methods">
262
263 <para>
264 <list type="tag">
265
266 <tag-name><literal>$r->args</literal></tag-name>
267 <tag-desc>
268 returns request arguments.
269 </tag-desc>
270
271 <tag-name><literal>$r->filename</literal></tag-name>
272 <tag-desc>
273 returns a filename corresponding to the request URI.
274 </tag-desc>
275
276 <tag-name>
277 <literal>$r->has_request_body(<value>handler</value>)</literal>
278 </tag-name>
279 <tag-desc>
280 returns 0 if there is no body in a request.
281 If there is a body, the specified handler is installed
282 and 1 is returned.
283 After reading the request body, nginx will call the installed handler.
284 Note that the handler function should be passed by reference.
285 Example:
286 <example>
287 package hello;
288
289 use nginx;
290
291 sub handler {
292 my $r = shift;
293
294 if ($r->request_method ne "POST") {
295 return DECLINED;
296 }
297
298 if ($r->has_request_body(<emphasis>\&amp;post</emphasis>)) {
299 return OK;
300 }
301
302 return HTTP_BAD_REQUEST;
303 }
304
305 sub <emphasis>post</emphasis> {
306 my $r = shift;
307
308 $r->send_http_header;
309
310 $r->print("request_body: \"", $r->request_body, "\"&lt;br/&gt;");
311 $r->print("request_body_file: \"", $r->request_body_file, "\"&lt;br/&gt;\n");
312
313 return OK;
314 }
315
316 1;
317
318 __END__
319 </example>
320 </tag-desc>
321
322 <tag-name><literal>$r->allow_ranges</literal></tag-name>
323 <tag-desc>
324 enables the use of byte ranges when sending responses.
325 </tag-desc>
326
327 <tag-name><literal>$r->discard_request_body</literal></tag-name>
328 <tag-desc>
329 instructs nginx to discard a request body.
330 </tag-desc>
331
332 <tag-name><literal>$r->header_in(<value>field</value>)</literal></tag-name>
333 <tag-desc>
334 returns value of the specified client request header field.
335 </tag-desc>
336
337 <tag-name><literal>$r->header_only</literal></tag-name>
338 <tag-desc>
339 determines should the whole response or only its header be sent to a client.
340 </tag-desc>
341
342 <tag-name>
343 <literal>$r->header_out(<value>field</value>,
344 <value>value</value>)</literal>
345 </tag-name>
346 <tag-desc>
347 sets a value for the specified response header field.
348 </tag-desc>
349
350 <tag-name>
351 <literal>$r->internal_redirect(<value>uri</value>)</literal>
352 </tag-name>
353 <tag-desc>
354 does an internal redirect to the speicified <value>uri</value>.
355 An actual redirect happens after the Perl handler has completed.
356 </tag-desc>
357
358 <tag-name><literal>$r->print(<value>text</value>, ...)</literal></tag-name>
359 <tag-desc>
360 passes data to a client.
361 </tag-desc>
362
363 <tag-name><literal>$r->request_body</literal></tag-name>
364 <tag-desc>
365 returns a client request body if it was not
366 written to a temporary file.
367 To ensure that a client request body is in memory,
368 its size should be limited with
369 <link doc="ngx_http_core_module.xml" id="client_max_body_size"/>,
370 and a sufficient buffer size should be set with
371 <link doc="ngx_http_core_module.xml" id="client_body_buffer_size"/>.
372 </tag-desc>
373
374 <tag-name><literal>$r->request_body_file</literal></tag-name>
375 <tag-desc>
376 returns the name of a file with the client request body.
377 At the end of processing, the file needs to be removed.
378 To always write a request body to a file,
379 <link doc="ngx_http_core_module.xml" id="client_body_in_file_only"/>
380 needs to be enabled.
381 </tag-desc>
382
383 <tag-name><literal>$r->request_method</literal></tag-name>
384 <tag-desc>
385 returns client request HTTP method.
386 </tag-desc>
387
388 <tag-name><literal>$r->remote_addr</literal></tag-name>
389 <tag-desc>
390 returns client IP address.
391 </tag-desc>
392
393 <tag-name><literal>$r->flush</literal></tag-name>
394 <tag-desc>
395 immediately sends data to a client.
396 </tag-desc>
397
398 <tag-name>
399 <literal>$r->sendfile(<value>name</value>[,
400 <value>offset</value>[,
401 <value>length</value>]])</literal>
402 </tag-name>
403 <tag-desc>
404 sends the specified file content to a client.
405 Optional parameters
406 specify an initial offset and length of data to be transmitted.
407 The actual data transmission happens after the Perl handler
408 has completed.
409 It should be noted that when using this method in a subrequest,
410 and <link doc="ngx_http_core_module.xml" id="sendfile"/>
411 is enabled, the file content will not be passed through the
412 <link doc="ngx_http_gzip_module.xml">gzip</link>,
413 <link doc="ngx_http_ssi_module.xml">SSI</link>, and
414 <link doc="ngx_http_charset_module.xml">charset</link>
415 filters.
416 </tag-desc>
417
418 <tag-name>
419 <literal>$r->send_http_header([<value>type</value>])</literal>
420 </tag-name>
421 <tag-desc>
422 sends the response header to a client.
423 An optional <value>type</value> parameter sets the value of
424 the <header>Content-Type</header> response header field.
425 If the value is an empty string, the <header>Content-Type</header>
426 header field will not be passed.
427 </tag-desc>
428
429 <tag-name><literal>$r->status(<value>code</value>)</literal></tag-name>
430 <tag-desc>
431 sets a response code.
432 </tag-desc>
433
434 <tag-name>
435 <literal>$r->sleep(<value>milliseconds</value>,
436 <value>handler</value>)</literal>
437 </tag-name>
438 <tag-desc>
439 sets the specified handler
440 and stops request processing for the specified time.
441 In the mean time, nginx continues to process other requests.
442 After the specified time has elapsed, nginx will call the installed handler.
443 Note that the handler function should be passed by reference.
444 In order to pass data between handlers,
445 <literal>$r->variable()</literal> should be used.
446 Example:
447 <example>
448 package hello;
449
450 use nginx;
451
452 sub handler {
453 my $r = shift;
454
455 $r->discard_request_body;
456 $r->variable("var", "OK");
457 $r->sleep(1000, <emphasis>\&amp;next</emphasis>);
458
459 return OK;
460 }
461
462 sub <emphasis>next</emphasis> {
463 my $r = shift;
464
465 $r->send_http_header;
466 $r->print($r->variable("var"));
467
468 return OK;
469 }
470
471 1;
472
473 __END__
474 </example>
475 </tag-desc>
476
477 <tag-name><literal>$r->unescape(<value>text</value>)</literal></tag-name>
478 <tag-desc>
479 decodes a text encoded in the “%XX” form.
480 </tag-desc>
481
482 <tag-name><literal>$r->uri</literal></tag-name>
483 <tag-desc>
484 returns a request URI.
485 </tag-desc>
486
487 <tag-name>
488 <literal>$r->variable(<value>name</value>[,
489 <value>value</value>])</literal>
490 </tag-name>
491 <tag-desc>
492 returns or sets a value of the specified variable.
493 Variables are local to each request.
494 </tag-desc>
495
496 </list>
497 </para>
498
499 </section>
500
501 </module>