Mercurial > hg > nginx-site
comparison xml/en/docs/http/ngx_http_perl_module.xml @ 416:c9c0550465c9
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<br/>"); | |
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 <!--# perl sub="<value>module</value>::<value>function</value>" arg="<value>parameter1</value>" arg="<value>parameter2</value>" ... | |
254 --> | |
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>\&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, "\"<br/>"); | |
311 $r->print("request_body_file: \"", $r->request_body_file, "\"<br/>\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>\&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> |