Apache2::ServerRec(3pm)

1docs::api::Apache2::SerUvseerrReCco(n3t)ributed Perl Docduomcesn:t:aatpiio:n:Apache2::ServerRec(3)
2
3
4

NAME

6       Apache2::ServerRec - Perl API for Apache server record accessors
7

Synopsis

9         use Apache2::ServerRec ();
10
11         $error_fname = $s->error_fname();
12
13         $is_virtual = $s->is_virtual();
14
15         $keep_alive         = $s->keep_alive();
16         $keep_alive_max     = $s->keep_alive_max();
17         $keep_alive_timeout = $s->keep_alive_timeout();
18
19         $limit_req_fields    = $s->limit_req_fields();
20         $limit_req_fieldsize = $s->limit_req_fieldsize();
21         $limit_req_line      = $s->limit_req_line();
22
23         $path = $s->path();
24
25         $hostname = $s->server_hostname();
26         $port     = $s->port();
27
28         $server_admin = $s->server_admin();
29
30         $proc = $s->process();
31
32         $timeout  = $s->timeout();
33         $loglevel = $s->loglevel();
34
35         my $server = Apache2::ServerUtil->server;
36         my $vhosts = 0;
37         for (my $s = $server->next; $s; $s = $s->next) {
38             $vhosts++;
39         }
40         print "There are $vhosts virtual hosts";
41

Description

43       "Apache2::ServerRec" provides the Perl API for Apache server_rec
44       object.
45
46       "Apache2::ServerUtil" provides an extra functionality.
47

API

49       "Apache2::ServerRec" provides the following functions and/or methods:
50
51   "error_fname"
52       Get/set the "ErrorLog" file value (e.g. logs/error_log)
53
54         $error_fname      = $s->error_fname();
55         $prev_error_fname = $s->error_fname($new_error_fname);
56
57       obj: $s ( "Apache2::ServerRec object" )
58       opt arg1: $new_error_fname ( string )
59           If passed, sets the new value for "ErrorLog"
60
61           Note the limited functionality under threaded MPMs.
62
63       ret: $error_fname ( string )
64           Returns the "ErrorLog" value setting.
65
66           If $new_error_fname is passed returns the setting before the
67           change.
68
69       since: 2.0.00
70
71   "is_virtual"
72       Test whether $s is a virtual host object
73
74         $is_virtual = $s->is_virtual();
75
76       obj: $s ( "Apache2::ServerRec object" )
77       ret: $is_virtual ( boolean )
78           Returns the is_virtual setting.
79
80           If $new_is_virtual is passed, returns the setting before the
81           change.
82
83       since: 2.0.00
84
85       Example:
86
87         print "This is a virtual host" if $s->is_virtual();
88
89   "keep_alive"
90       Get/set the "KeepAlive" setting, which specifies whether Apache should
91       accept more than one request over the same connection from the same
92       client.
93
94         $keep_alive      = $s->keep_alive();
95         $prev_keep_alive = $s->keep_alive($new_keep_alive);
96
97       obj: $s ( "Apache2::ServerRec object" )
98       opt arg1: $new_keep_alive ( boolean )
99           If passed, sets the new keep_alive.
100
101           Note the limited functionality under threaded MPMs.
102
103       ret: $keep_alive ( boolean )
104           Returns the "KeepAlive" setting.
105
106           If $new_keep_alive is passed, returns the setting before the
107           change.
108
109       since: 2.0.00
110
111   "keep_alive_max"
112       Get/set the "MaxKeepAliveRequest" setting, which specifies the maximum
113       number of requests Apache will serve over a "KeepAlive" connection.
114
115         $keep_alive_max      = $s->keep_alive_max();
116         $prev_keep_alive_max = $s->keep_alive_max($new_keep_alive_max);
117
118       obj: $s ( "Apache2::ServerRec object" )
119       opt arg1: $new_keep_alive_max ( integer )
120           If passed, sets the new keep_alive_max.
121
122           Note the limited functionality under threaded MPMs.
123
124       ret: $keep_alive_max ( integer )
125           Returns the keep_alive_max setting.
126
127           If $new_keep_alive_max is passed, returns the setting before the
128           change.
129
130       since: 2.0.00
131
132   "keep_alive_timeout"
133       Get/set the "KeepAliveTimeout" setting (in microsecs), which specifies
134       how long Apache will wait for another request before breaking a
135       "KeepAlive" connection.
136
137         $keep_alive_timeout      = $s->keep_alive_timeout();
138         $prev_keep_alive_timeout = $s->keep_alive_timeout($new_timeout);
139
140       obj: $s ( "Apache2::ServerRec object" )
141       opt arg1: $new_keep_alive_timeout ( integer )
142           The expected value is in microsecs.
143
144           If passed, sets the new "KeepAlive" timeout.
145
146           Note the limited functionality under threaded MPMs.
147
148       ret: $keep_alive_timeout ( integer )
149           Returns the "KeepAlive" timeout value (in microsecs).
150
151           If $new_timeout is passed, returns the setting before the change.
152
153       since: 2.0.00
154
155   "limit_req_fields"
156       Get/set limit on number of request header fields
157
158         $limit_req_fields      = $s->limit_req_fields();
159         $prev_limit_req_fields = $s->limit_req_fields($new_limit_req_fields);
160
161       obj: $s ( "Apache2::ServerRec object" )
162       opt arg1: $new_limit_req_fields ( integer )
163           If passed, sets the new request headers number limit.
164
165           Note the limited functionality under threaded MPMs.
166
167       ret: $limit_req_fields ( integer )
168           Returns the request headers number limit.
169
170           If $new_limit_req_fields is passed, returns the setting before the
171           change.
172
173       since: 2.0.00
174
175   "limit_req_fieldsize"
176       Get/set limit on size of any request header field
177
178         $limit_req_fieldsize = $s->limit_req_fieldsize();
179         $prev_limit          = $s->limit_req_fieldsize($new_limit);
180
181       obj: $s ( "Apache2::ServerRec object" )
182       opt arg1: $new_limit_req_fieldsize ( integer )
183           If passed, sets the new request header size limit.
184
185           Note the limited functionality under threaded MPMs.
186
187       ret: $limit_req_fieldsize ( integer )
188           Returns the request header size limit.
189
190           If $new_limit is passed, returns the setting before the change.
191
192       since: 2.0.00
193
194   "limit_req_line"
195       Get/set limit on size of the HTTP request line
196
197         $limit_req_line      = $s->limit_req_line();
198         $prev_limit_req_line = $s->limit_req_line($new_limit_req_line);
199
200       obj: $s ( "Apache2::ServerRec object" )
201       opt arg1: $new_limit_req_line ( integer )
202           If passed, sets the new request line limit value.
203
204           Note the limited functionality under threaded MPMs.
205
206       ret: $limit_req_line ( integer )
207           Returns the request line limit value
208
209           If $new_limit_req_line is passed, returns the setting before the
210           change.
211
212       since: 2.0.00
213
214   "loglevel"
215       Get/set the "LogLevel" directive value
216
217         $loglevel      = $s->loglevel();
218         $prev_loglevel = $s->loglevel($new_loglevel);
219
220       obj: $s ( "Apache2::ServerRec object" )
221       opt arg1: $new_loglevel ( "Apache2::Const :log constant" )
222           If passed, sets a new "LogLevel" value
223
224           Note the limited functionality under threaded MPMs.
225
226       ret: $loglevel ( "Apache2::Const :log constant" )
227           Returns the "LogLevel" value as a constant.
228
229           If $new_loglevel is passed, returns the setting before the change.
230
231       since: 2.0.00
232
233       For example, to set the "LogLevel" value to "info":
234
235         use Apache2::Const -compile => qw(LOG_INFO);
236         $s->loglevel(Apache2::Const::LOG_INFO);
237
238   "next"
239       The next server record in the list (if there are vhosts)
240
241         $s_next = $s->next();
242
243       obj: $s ( "Apache2::ServerRec object" )
244       ret: $s_next ( "Apache2::ServerRec object" )
245       since: 2.0.00
246
247       For example the following code traverses all the servers, starting from
248       the base server and continuing to vhost servers, counting all available
249       vhosts:
250
251         use Apache2::ServerRec ();
252         use Apache2::ServerUtil ();
253         my $server = Apache2::ServerUtil->server;
254         my $vhosts = 0;
255         for (my $s = $server->next; $s; $s = $s->next) {
256             $vhosts++;
257         }
258         print "There are $vhosts virtual hosts";
259
260   "path"
261       Get/set pathname for the "ServerPath" setting
262
263         $path      = $s->path();
264         $prev_path = $s->path($new_path);
265
266       obj: $s ( "Apache2::ServerRec object" )
267       opt arg1: $new_path ( string )
268           If passed, sets the new path.
269
270           Note the limited functionality under threaded MPMs.
271
272       ret: $path ( string )
273           Returns the path setting.
274
275           If $new_path is passed, returns the setting before the change.
276
277       since: 2.0.00
278
279   "port"
280       Get/set the port value
281
282         $port      = $s->port();
283         $prev_port = $s->port($new_port);
284
285       obj: $s ( "Apache2::ServerRec object" )
286       opt arg1: $new_port ( integer )
287           If passed, sets the new port.
288
289           Note the limited functionality under threaded MPMs.
290
291           META: I don't think one should be allowed to change port number
292           after the server has started.
293
294       ret: $port ( integer )
295           Returns the port setting.
296
297           If $new_port is passed returns the setting before the change.
298
299       since: 2.0.00
300
301   "process"
302       The process this server is running in
303
304         $proc = $s->process();
305
306       obj: $s ( "Apache2::ServerRec object" )
307       ret: $proc ( "Apache2::Process object" )
308       since: 2.0.00
309
310   "server_admin"
311       Get/set the "ServerAdmin" value
312
313         $server_admin      = $s->server_admin();
314         $prev_server_admin = $s->server_admin($new_server_admin);
315
316       obj: $s ( "Apache2::ServerRec object" )
317       opt arg1: $new_server_admin ( string )
318           If passed, sets the new "ServerAdmin" value.
319
320           Note the limited functionality under threaded MPMs.
321
322       ret: $server_admin ( string )
323           Returns the "ServerAdmin" value.
324
325           If $new_server_admin is passed, returns the setting before the
326           change.
327
328       since: 2.0.00
329
330   "server_hostname"
331       Get/set the "ServerName" value
332
333         $server_hostname      = $s->server_hostname();
334         $prev_server_hostname = $s->server_hostname($new_server_hostname);
335
336       obj: $s ( "Apache2::ServerRec object" )
337       opt arg1: $new_server_hostname ( string )
338           If passed, sets the "ServerName" value
339
340           Note the limited functionality under threaded MPMs.
341
342       ret: $server_hostname ( string )
343           Returns the "ServerName" value
344
345           If $new_server_hostname is passed, returns the setting before the
346           change.
347
348       since: 2.0.00
349
350   "timeout"
351       Get/set the timeout ("TimeOut") (in microsecs), which Apache will wait
352       for before it gives up doing something
353
354         $timeout      = $s->timeout();
355         $prev_timeout = $s->timeout($new_timeout);
356
357       obj: $s ( "Apache2::ServerRec object" )
358       opt arg1: $new_timeout ( integer )
359           If passed, sets the new timeout (the value should be in
360           microseconds).
361
362           Note the limited functionality under threaded MPMs.
363
364       ret: $timeout ( integer )
365           Returns the timeout setting in microseconds.
366
367           If $new_timeout is passed, returns the setting before the change.
368
369       since: 2.0.00
370
371       Let us repeat again: the timeout values is microseconds. For example to
372       set the timeout to 20 secs:
373
374         $s->timeout(20_000_000);
375

Notes

377   Limited Functionality under Threaded MPMs
378       Note that under threaded MPMs, some of the read/write accessors, will
379       be able to set values only before threads are spawned (i.e. before the
380       "ChildInit phase").  Therefore if you are developing your application
381       on the non-threaded MPM, but planning to have it run under threaded
382       mpm, you should not use those methods to set values after the ChildInit
383       phase.
384
385       The affected accessor methods are marked as such in their respective
386       documentation entries.
387

Unsupported API

389       "Apache2::ServerRec" also provides auto-generated Perl interface for a
390       few other methods which aren't tested at the moment and therefore their
391       API is a subject to change. These methods will be finalized later as a
392       need arises. If you want to rely on any of the following methods please
393       contact the the mod_perl development mailing list so we can help each
394       other take the steps necessary to shift the method to an officially
395       supported API.
396
397   "addrs"
398       Get the addrs value
399
400         $addrs = $s->addrs();
401
402       obj: $s ( "Apache2::ServerRec object" )
403       ret: $addrs ( "Apache2::ServerAddr" )
404           Returns the addrs setting.
405
406       since: subject to change
407
408       META: this methods returns a vhost-specific Apache2::ServerAddr object,
409       which is not implemented at the moment. See the struct server_addr_rec
410       entry in httpd-2.0/include/httpd.h for more information. It seems that
411       most (all?) of the information in that record is available through
412       other APIs.
413
414   "lookup_defaults"
415       Get the lookup_defaults value.  MIME type info, etc., before we start
416       checking per-directory info.
417
418         $lookup_defaults = $s->lookup_defaults();
419
420       obj: $s ( "Apache2::ServerRec object" )
421       ret: $lookup_defaults ( "Apache2::ConfVector" )
422           Returns the lookup_defaults setting.
423
424       since: subject to change
425
426   "module_config"
427       Get config vector containing pointers to modules' per-server config
428       structures.
429
430         $module_config = $s->module_config();
431
432       obj: $s ( "Apache2::ServerRec object" )
433       ret: $module_config ( "Apache2::ConfVector" )
434           Returns the module_config setting.
435
436       since: subject to change
437
438   "names"
439       Get/set the value(s) for the "ServerAlias" setting
440
441         $names      = $s->names();
442         $prev_names = $s->names($new_names);
443
444       obj: $s ( "Apache2::ServerRec object" )
445       opt arg1: $new_names ( "APR::ArrayHeader" )
446           If passed, sets the new names.
447
448           Note the limited functionality under threaded MPMs.
449
450       ret: $names ( "APR::ArrayHeader" )
451           Returns the names setting.
452
453           If $new_names is passed, returns the setting before the change.
454
455       since: 2.0.00
456
457       META: we don't have "APR::ArrayHeader" yet
458
459   "wild_names"
460       Wildcarded names for ServerAlias servers
461
462         $wild_names      = $s->wild_names();
463         $prev_wild_names = $s->wild_names($new_wild_names);
464
465       obj: $s ( "Apache2::ServerRec object" )
466       opt arg1: $new_wild_names ( "APR::ArrayHeader" )
467           If passed, sets the new wild_names.
468
469           Note the limited functionality under threaded MPMs.
470
471       ret: $wild_names ( "APR::ArrayHeader" )
472           Returns the wild_names setting.
473
474           If $new_wild_names is passed, returns the setting before the
475           change.
476
477       since: 2.0.00
478
479       META: we don't have "APR::ArrayHeader" yet
480

Copyright

485       mod_perl 2.0 and its core modules are copyrighted under The Apache
486       Software License, Version 2.0.
487

Authors

489       The mod_perl development team and numerous contributors.
490
491
492
493perl v5.38.0                      2023-07-20  docs::api::Apache2::ServerRec(3)