Apache2::ServerUtil(3pm)

1docs::api::Apache2::SerUvseerrUtCioln(t3r)ibuted Perl Dodcoucmse:n:taaptii:o:nApache2::ServerUtil(3)
2
3
4

NAME

6       Apache2::ServerUtil - Perl API for Apache server record utils
7

Synopsis

9         use Apache2::ServerUtil ();
10         $s = Apache2::ServerUtil->server;
11
12         # push config
13         $s->add_config(['ServerTokens off']);
14
15         # add components to the Server signature
16         $s->add_version_component("MyModule/1.234");
17
18         # access PerlSetVar/PerlAddVar values
19         my $srv_cfg = $s->dir_config;
20
21         # check command line defines
22         print "this is mp2"
23             if Apache2::ServerUtil::exists_config_define('MODPERL2');
24
25         # get PerlChildExitHandler configured handlers
26         @handlers = @{ $s->get_handlers('PerlChildExitHandler') ⎪⎪ []};
27
28         # server build and version info:
29         $when_built = Apache2::ServerUtil::get_server_built();
30         $version = Apache2::ServerUtil::get_server_version();
31
32         # ServerRoot value
33         $server_root = Apache2::ServerUtil::server_root();
34
35         # get 'conf/' dir path (avoid using this function!)
36         my $dir = Apache2::ServerUtil::server_root_relative($r->pool, 'conf');
37
38         # set child_exit handlers
39         $r->set_handlers(PerlChildExitHandler => \&handler);
40
41         # server level PerlOptions flags lookup
42         $s->push_handlers(ChildExit => \&child_exit)
43             if $s->is_perl_option_enabled('ChildExit');
44
45         # extend HTTP to support a new method
46         $s->method_register('NEWGET');
47
48         # register server shutdown callback
49         Apache2::ServerUtil::server_shutdown_register_cleanup(sub { Apache2::Const::OK });
50
51         # do something only when the server restarts
52         my $cnt = Apache2::ServerUtil::restart_count();
53         do_something_once() if $cnt > 1;
54
55         # get the resolved ids from Group and User entries
56         my $user_id  = Apache2::ServerUtil->user_id;
57         my $group_id = Apache2::ServerUtil->group_id;
58

Description

60       "Apache2::ServerUtil" provides the Apache server object utilities API.
61

Methods API

63       "Apache2::ServerUtil" provides the following functions and/or methods:
64
65       "add_config"
66
67       Dynamically add Apache configuration:
68
69         $s->add_config($lines);
70
71       obj: $s ( "Apache2::ServerRec object" )
72       arg1: $lines ( ARRAY ref )
73           An ARRAY reference containing configuration lines per element,
74           without the new line terminators.
75
76       ret: no return value
77       since: 2.0.00
78
79       See also: "$r->add_config"
80
81       For example:
82
83       Add a configuration section at the server startup (e.g. from
84       startup.pl):
85
86         use Apache2::ServerUtil ();
87         my $conf = <<'EOC';
88         PerlModule Apache2::MyExample
89         <Location /perl>
90           SetHandler perl-script
91           PerlResponseHandler Apache2::MyExample
92         </Location>
93         EOC
94         Apache2::ServerUtil->server->add_config([split /\n/, $conf]);
95
96       "add_version_component"
97
98       Add a component to the version string
99
100         $s->add_version_component($component);
101
102       obj: $s ( "Apache2::ServerRec object" )
103       arg1: $component ( string )
104           The string component to add
105
106       ret: no return value
107       since: 2.0.00
108
109       This function is usually used by modules to advertise themselves to the
110       world. It's picked up by such statistics collectors, like netcraft.com,
111       which accomplish that by connecting to various servers and grabbing the
112       server version response header ("Server"). Some servers choose to fully
113       or partially conceal that header.
114
115       This method should be invoked in the "PerlPostConfigHandler" phase,
116       which will ensure that the Apache core version number will appear
117       first.
118
119       For example let's add a component "Hikers, Inc/0.99999" to the server
120       string at the server startup:
121
122         use Apache2::ServerUtil ();
123         use Apache2::Const -compile => 'OK';
124
125         Apache2::ServerUtil->server->push_handlers(
126             PerlPostConfigHandler => \&add_my_version);
127
128         sub add_my_version {
129             my ($conf_pool, $log_pool, $temp_pool, $s) = @_;
130             $s->add_version_component("Hikers, Inc/0.99999");
131             return Apache2::Const::OK;
132         }
133
134       or of course you could register the "PerlPostConfigHandler" handler
135       directly in httpd.conf
136
137       Now when the server starts, you will something like:
138
139         [Thu Jul 15 12:15:28 2004] [notice] Apache/2.0.51-dev (Unix)
140         mod_perl/1.99_15-dev Perl/v5.8.5 Hikers, Inc/0.99999
141         configured -- resuming normal operations
142
143       Also remember that the "ServerTokens" directive value controls whether
144       the component information is displayed or not.
145
146       "dir_config"
147
148       "$s->dir_config()" provides an interface for the per-server variables
149       specified by the "PerlSetVar" and "PerlAddVar" directives, and also can
150       be manipulated via the "APR::Table" methods.
151
152         $table  = $s->dir_config();
153         $value  = $s->dir_config($key);
154         @values = $s->dir_config($key);
155         $s->dir_config($key, $val);
156
157       obj: $s ( "Apache2::ServerRec object" )
158       opt arg2: $key ( string )
159           Key string
160
161       opt arg3: $val ( string )
162           Value string
163
164       ret: ...
165           Depends on the passed arguments, see further discussion
166
167       since: 2.0.00
168
169       The keys are case-insensitive.
170
171         $t = $s->dir_config();
172
173       dir_config() called in a scalar context without the $key argument
174       returns a HASH reference blessed into the APR::Table class. This object
175       can be manipulated via the APR::Table methods. For available methods
176       see APR::Table.
177
178         @values = $s->dir_config($key);
179
180       If the $key argument is passed in the list context a list of all match‐
181       ing values will be returned. This method is ineffective for big tables,
182       as it does a linear search of the table. Thefore avoid using this way
183       of calling dir_config() unless you know that there could be more than
184       one value for the wanted key and all the values are wanted.
185
186         $value = $s->dir_config($key);
187
188       If the $key argument is passed in the scalar context only a single
189       value will be returned. Since the table preserves the insertion order,
190       if there is more than one value for the same key, the oldest value
191       assosiated with the desired key is returned. Calling in the scalar con‐
192       text is also much faster, as it'll stop searching the table as soon as
193       the first match happens.
194
195         $s->dir_config($key => $val);
196
197       If the $key and the $val arguments are used, the set() operation will
198       happen: all existing values associated with the key $key (and the key
199       itself) will be deleted and $value will be placed instead.
200
201         $s->dir_config($key => undef);
202
203       If $val is undef the unset() operation will happen: all existing values
204       associated with the key $key (and the key itself) will be deleted.
205
206       "exists_config_define"
207
208       Check for a definition from the server startup command line (e.g.
209       "-DMODPERL2")
210
211         $result = Apache2::ServerUtil::exists_config_define($name);
212
213       arg1: $name ( string )
214           The define string to check for
215
216       ret: $result ( boolean )
217           true if defined, false otherwise
218
219       since: 2.0.00
220
221       For example:
222
223         print "this is mp2"
224             if Apache2::ServerUtil::exists_config_define('MODPERL2');
225
226       "get_handlers"
227
228       Returns a reference to a list of handlers enabled for a given phase.
229
230         $handlers_list = $s->get_handlers($hook_name);
231
232       obj: $s ( "Apache2::ServerRec object" )
233       arg1: $hook_name ( string )
234           a string representing the phase to handle.
235
236       ret: $handlers_list (ref to an ARRAY of CODE refs)
237           a list of references to the handler subroutines
238
239       since: 2.0.00
240
241       See also: "$r->add_config"
242
243       For example:
244
245       A list of handlers configured to run at the child_exit phase:
246
247         @handlers = @{ $s->get_handlers('PerlChildExitHandler') ⎪⎪ []};
248
249       "get_server_built"
250
251       Get the date and time that the server was built
252
253         $when_built = Apache2::ServerUtil::get_server_built();
254
255       ret: $when_built ( string )
256           The server build time string
257
258       since: 2.0.00
259
260       "get_server_version"
261
262       Get the server version string
263
264         $version = Apache2::ServerUtil::get_server_version();
265
266       ret: $version ( string )
267           The server version string
268
269       since: 2.0.00
270
271       "group_id"
272
273       Get the group id corresponding to the "Group" directive in httpd.conf:
274
275         $gid = Apache2::ServerUtil->group_id;
276
277       obj: "Apache2::ServerUtil" (class name)
278       ret: $gid ( integer )
279           On Unix platforms returns the gid corresponding to the value used
280           in the "Group" directive in httpd.conf. On other platforms returns
281           0.
282
283       since: 2.0.03
284
285       "is_perl_option_enabled"
286
287       check whether a server level "PerlOptions" flag is enabled or not.
288
289         $result = $s->is_perl_option_enabled($flag);
290
291       obj: $s ( "Apache2::ServerRec object" )
292       arg1: $flag ( string )
293       ret: $result ( boolean )
294       since: 2.0.00
295
296       For example to check whether the "ChildExit" hook is enabled (which can
297       be disabled with "PerlOptions -ChildExit") and configure some handlers
298       to run if enabled:
299
300         $s->push_handlers(ChildExit => \&child_exit)
301             if $s->is_perl_option_enabled('ChildExit');
302
303       See also: PerlOptions and the equivalent function for directory level
304       PerlOptions flags.
305
306       "method_register"
307
308       Register a new request method, and return the offset that will be asso‐
309       ciated with that method.
310
311         $offset = $s->method_register($methname);
312
313       obj: $s ( "Apache2::ServerRec object" )
314       arg1: $methname ( string )
315           The name of the new method to register (in addition to the already
316           supported "GET", "HEAD", etc.)
317
318       ret: $offset ( integer )
319           An int value representing an offset into a bitmask. You can proba‐
320           bly ignore it.
321
322       since: 2.0.00
323
324       This method allows you to extend the HTTP protocol to support new meth‐
325       ods, which fit the HTTP paradigm.  Of course you will need to write a
326       client that understands that protocol extension.  For a good example,
327       refer to the "MyApache2::SendEmail" example presented in "the PerlHead‐
328       erParserHandler section", which demonstrates how a new method "EMAIL"
329       is registered and used.
330
331       "push_handlers"
332
333       Add one or more handlers to a list of handlers to be called for a given
334       phase.
335
336         $ok = $s->push_handlers($hook_name => \&handler);
337         $ok = $s->push_handlers($hook_name => [\&handler, \&handler2]);
338
339       obj: $s ( "Apache2::ServerRec object" )
340       arg1: $hook_name ( string )
341           the phase to add the handlers to
342
343       arg2: $handlers ( CODE ref or SUB name or an ARRAY ref )
344           a single handler CODE reference or just a name of the subroutine
345           (fully qualified unless defined in the current package).
346
347           if more than one passed, use a reference to an array of CODE refs
348           and/or subroutine names.
349
350       ret: $ok ( boolean )
351           returns a true value on success, otherwise a false value
352
353       since: 2.0.00
354
355       See also: "$r->add_config"
356
357       Examples:
358
359       A single handler:
360
361         $s->push_handlers(PerlChildExitHandler => \&handler);
362
363       Multiple handlers:
364
365         $s->push_handlers(PerlChildExitHandler => ['Foo::Bar::handler', \&handler2]);
366
367       Anonymous functions:
368
369         $s->push_handlers(PerlLogHandler => sub { return Apache2::Const::OK });
370
371       "restart_count"
372
373       How many times the server was restarted.
374
375         $restart_count = Apache2::ServerUtil::restart_count();
376
377       ret: "restart_count" ( number )
378       since: 2.0.00
379
380       The following demonstration should make it clear what values to expect
381       from this function. Let's add the following code to startup.pl, so it's
382       run every time httpd.conf is parsed:
383
384         use Apache2::ServerUtil ();
385         my $cnt = Apache2::ServerUtil::restart_count();
386         open my $fh, ">>/tmp/out" or die "$!";
387         print $fh "cnt: $cnt\n";
388         close $fh;
389
390       Now let's run a series of server starts and restarts and look at what
391       is logged into /tmp/out:
392
393         % httpd -k start
394         cnt: 1
395         cnt: 2
396
397         % httpd -k graceful
398         cnt: 1
399         cnt: 3
400
401         % httpd -k graceful
402         cnt: 1
403         cnt: 4
404
405         % httpd -k stop
406         cnt: 1
407
408       Remembering that Apache restarts itself immediately after starting, we
409       can see that the "restart_count" goes from 1 to 2 during the server
410       start. Moreover we can see that every operation forces the parsing of
411       httpd.conf and therefore reinitialization of mod_perl (and running all
412       the code found in httpd.conf). This happens even when the server is
413       shutdown via "httpd -k stop".
414
415       What conclusions can be drawn from this demonstration:
416
417       ·   "Apache2::ServerUtil::restart_count()" returns 1 every time some
418           "-k" command is passed to Apache (or "kill -USR1" or some alterna‐
419           tive signal is received).
420
421       ·   At all other times the count will be 2 or higher. So for example on
422           graceful restart the count will be 3 or higher.
423
424       For example if you want to run something every time "httpd -k" is run
425       you just need to check whether "restart_count()" returns 1:
426
427         my $cnt = Apache2::ServerUtil::restart_count();
428         do_something() if $cnt == 1;
429
430       To do something only when server restarts ("httpd -k start" or "httpd
431       -k graceful)", check whether "restart_count()" is bigger than 1:
432
433         my $cnt = Apache2::ServerUtil::restart_count();
434         do_something() if $cnt > 1;
435
436       "server"
437
438       Get the main server's object
439
440         $main_s = Apache2::ServerUtil->server();
441
442       obj: "Apache2::ServerUtil" (class name)
443       ret: $main_s ( "Apache2::ServerRec object" )
444       since: 2.0.00
445
446       "server_root"
447
448       returns the value set by the top-level "ServerRoot" directive.
449
450         $server_root = Apache2::ServerUtil::server_root();
451
452       ret: $server_root ( string )
453       since: 2.0.00
454
455       "server_root_relative"
456
457       Returns the canonical form of the filename made absolute to "Server‐
458       Root":
459
460         $path = Apache2::ServerUtil::server_root_relative($pool, $fname);
461
462       arg1: $pool ( "APR::Pool object" )
463           Make sure that you read the following explanation and understand
464           well which pool object you need to pass before using this function.
465
466       opt arg2: $fname ( string )
467       ret: $path ( string )
468           The concatenation of "ServerRoot" and the $fname.
469
470           If $fname is not specified, the value of "ServerRoot" is returned
471           with a trailing "/". (it's the same as using '' as $fname's value).
472
473       since: 2.0.00
474
475       $fname is appended to the value of "ServerRoot" and returned. For exam‐
476       ple:
477
478         my $dir = Apache2::ServerUtil::server_root_relative($r->pool, 'logs');
479
480       You must be extra-careful when using this function. If you aren't sure
481       what you are doing don't use it.
482
483       It's much safer to build the path by yourself using use
484       "Apache2::ServerUtil::server_root()", For example:
485
486         use File::Spec::Functions qw(catfile);
487         my $path = catfile Apache2::ServerUtil::server_root, qw(t logs);
488
489       In this example, no memory allocation happens on the Apache-side and
490       you aren't risking to get a memory leak.
491
492       The problem with "server_root_relative" is that Apache allocates memory
493       to concatenate the path string. The memory is allocated from the pool
494       object. If you call this method on the server pool object it'll allo‐
495       cate the memory from it.  If you do that at the server startup, it's
496       perfectly right, since you will do that only once. However if you do
497       that from within a request or a connection handler, you create a memory
498       leak every time it is called -- as the memory gets allocated from the
499       server pool, it will be freed only when the server is shutdown. There‐
500       fore if you need to build a relative to the root server path for the
501       duration of the request, use the request pool:
502
503         use Apache2::RequestRec ();
504         Apache2::ServerUtil::server_root_relative($r->pool, $fname);
505
506       If you need to have the path for the duration of a connection (e.g.
507       inside a protocol handler), you should use:
508
509         use Apache2::Connection ();
510         Apache2::ServerUtil::server_root_relative($c->pool, $fname);
511
512       And if you want it for the scope of the server file:
513
514         use Apache2::Process ();
515         use Apache2::ServerUtil ();
516         Apache2::ServerUtil::server_root_relative($s->process->pool, $fname);
517
518       Moreover, you could have encountered the opposite problem, where you
519       have used a short-lived pool object to construct the path, but tried to
520       use the resulting path variable, when that pool has been destructed
521       already. In order to avoid mysterious segmentation faults, mod_perl
522       does a wasteful copy of the path string when returning it to you --
523       another reason to avoid using this function.
524
525       "server_shutdown_cleanup_register"
526
527       Register server shutdown cleanup callback:
528
529         Apache2::ServerUtil::server_shutdown_cleanup_register($sub);
530
531       arg1: $sub ( CODE ref or SUB name )
532       ret: no return value
533       since: 2.0.00
534
535       This function can be used to register a callback to be run once at the
536       server shutdown (compared to "PerlChildExitHandler" which will execute
537       the callback for each exiting child process).
538
539       For example in order to arrange the function "do_my_cleanups()" to be
540       run every time the server shuts down (or restarts), run the following
541       code at the server startup:
542
543         Apache2::ServerUtil::server_shutdown_cleanup_register(\&do_my_cleanups);
544
545       It's necessary to run this code at the server startup (normally
546       startup.pl. The function will croak if run after the "PerlPostCon‐
547       figHandler" phase.
548
549       "set_handlers"
550
551       Set a list of handlers to be called for a given phase. Any previously
552       set handlers are forgotten.
553
554         $ok = $s->set_handlers($hook_name => \&handler);
555         $ok = $s->set_handlers($hook_name => [\&handler, \&handler2]);
556         $ok = $s->set_handlers($hook_name => []);
557         $ok = $s->set_handlers($hook_name => undef);
558
559       obj: $s ( "Apache2::ServerRec object" )
560       arg1: $hook_name ( string )
561           the phase to set the handlers in
562
563       arg2: $handlers ( CODE ref or SUB name or an ARRAY ref )
564           a reference to a single handler CODE reference or just a name of
565           the subroutine (fully qualified unless defined in the current pack‐
566           age).
567
568           if more than one passed, use a reference to an array of CODE refs
569           and/or subroutine names.
570
571           if the argument is "undef" or "[]" the list of handlers is reset to
572           zero.
573
574       ret: $ok ( boolean )
575           returns a true value on success, otherwise a false value
576
577       since: 2.0.00
578
579       See also: "$r->add_config"
580
581       Examples:
582
583       A single handler:
584
585         $r->set_handlers(PerlChildExitHandler => \&handler);
586
587       Multiple handlers:
588
589         $r->set_handlers(PerlFixupHandler => ['Foo::Bar::handler', \&handler2]);
590
591       Anonymous functions:
592
593         $r->set_handlers(PerlLogHandler => sub { return Apache2::Const::OK });
594
595       Reset any previously set handlers:
596
597         $r->set_handlers(PerlCleanupHandler => []);
598
599       or
600
601         $r->set_handlers(PerlCleanupHandler => undef);
602
603       "user_id"
604
605       Get the user id corresponding to the "User" directive in httpd.conf:
606
607         $uid = Apache2::ServerUtil->user_id;
608
609       obj: "Apache2::ServerUtil" (class name)
610       ret: $uid ( integer )
611           On Unix platforms returns the uid corresponding to the value used
612           in the "User" directive in httpd.conf. On other platforms returns
613           0.
614
615       since: 2.0.03
616

Unsupported API

618       "Apache2::ServerUtil" also provides auto-generated Perl interface for a
619       few other methods which aren't tested at the moment and therefore their
620       API is a subject to change. These methods will be finalized later as a
621       need arises. If you want to rely on any of the following methods please
622       contact the the mod_perl development mailing list so we can help each
623       other take the steps necessary to shift the method to an officially
624       supported API.
625
626       "error_log2stderr"
627
628       Start sending STDERR to the error_log file
629
630         $s->error_log2stderr();
631
632       obj: $s ( "Apache2::ServerRec object" )
633           The current server
634
635       ret: no return value
636       since: 2.0.00
637
638       This method may prove useful if you want to start redirecting STDERR to
639       the error_log file before Apache does that on the startup.
640

Copyright

645       mod_perl 2.0 and its core modules are copyrighted under The Apache
646       Software License, Version 2.0.
647

Authors

649       The mod_perl development team and numerous contributors.
650
651
652
653perl v5.8.8                       2006-11-19 docs::api::Apache2::ServerUtil(3)