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         $description = Apache2::ServerUtil::get_server_description();
31         $version = Apache2::ServerUtil::get_server_version();
32         $banner = Apache2::ServerUtil::get_server_banner();
33
34         # ServerRoot value
35         $server_root = Apache2::ServerUtil::server_root();
36
37         # get 'conf/' dir path (avoid using this function!)
38         my $dir = Apache2::ServerUtil::server_root_relative($r->pool, 'conf');
39
40         # set child_exit handlers
41         $r->set_handlers(PerlChildExitHandler => \&handler);
42
43         # server level PerlOptions flags lookup
44         $s->push_handlers(ChildExit => \&child_exit)
45             if $s->is_perl_option_enabled('ChildExit');
46
47         # extend HTTP to support a new method
48         $s->method_register('NEWGET');
49
50         # register server shutdown callback
51         Apache2::ServerUtil::server_shutdown_register_cleanup(sub { Apache2::Const::OK });
52
53         # do something only when the server restarts
54         my $cnt = Apache2::ServerUtil::restart_count();
55         do_something_once() if $cnt > 1;
56
57         # get the resolved ids from Group and User entries
58         my $user_id  = Apache2::ServerUtil->user_id;
59         my $group_id = Apache2::ServerUtil->group_id;
60

Description

62       "Apache2::ServerUtil" provides the Apache server object utilities API.
63

Methods API

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

Unsupported API

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

Copyright

648       mod_perl 2.0 and its core modules are copyrighted under The Apache
649       Software License, Version 2.0.
650

Authors

652       The mod_perl development team and numerous contributors.
653
654
655
656perl v5.12.0                      2007-11-12 docs::api::Apache2::ServerUtil(3)