man Apache2::ServerRec () - Perl API for Apache server record accessors

NAME

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

Synopsis

  use Apache2::ServerRec ();

  $error_fname = $s->error_fname();

  $is_virtual = $s->is_virtual();

  $keep_alive         = $s->keep_alive();
  $keep_alive_max     = $s->keep_alive_max();
  $keep_alive_timeout = $s->keep_alive_timeout();

  $limit_req_fields    = $s->limit_req_fields();
  $limit_req_fieldsize = $s->limit_req_fieldsize();
  $limit_req_line      = $s->limit_req_line();

  $path = $s->path();

  $hostname = $s->server_hostname();
  $port     = $s->port();

  $server_admin = $s->server_admin();

  $proc = $s->process();

  $timeout  = $s->timeout();
  $loglevel = $s->loglevel();

  my $server = Apache2::ServerUtil->server;
  my $vhosts = 0;
  for (my $s = $server->next; $s; $s = $s->next) {
      $vhosts++;
  }
  print "There are $vhosts virtual hosts";

Description

CWApache2::ServerRec provides the Perl API for Apache server_rec object.

CWApache2::ServerUtil provides an extra functionality.

API

CWApache2::ServerRec provides the following functions and/or methods: Get/set the CWErrorLog file value (e.g. logs/error_log)

  $error_fname      = $s->error_fname();
  $prev_error_fname = $s->error_fname($new_error_fname);
If passed, sets the new value for CWErrorLog Note the limited functionality under threaded MPMs. Returns the CWErrorLog value setting. If CW$new_error_fname is passed returns the setting before the change.
since: 2.0.00
Test whether CW$s is a virtual host object

  $is_virtual = $s->is_virtual();
Returns the is_virtual setting. If CW$new_is_virtual is passed, returns the setting before the change.
since: 2.0.00

Example:

  print "This is a virtual host" if $s->is_virtual();
Get/set the CWKeepAlive setting, which specifies whether Apache should accept more than one request over the same connection from the same client.

  $keep_alive      = $s->keep_alive();
  $prev_keep_alive = $s->keep_alive($new_keep_alive);
If passed, sets the new keep_alive. Note the limited functionality under threaded MPMs. Returns the CWKeepAlive setting. If CW$new_keep_alive is passed, returns the setting before the change.
since: 2.0.00
Get/set the CWMaxKeepAliveRequest setting, which specifies the maximum number of requests Apache will serve over a CWKeepAlive connection.

  $keep_alive_max      = $s->keep_alive_max();
  $prev_keep_alive_max = $s->keep_alive_max($new_keep_alive_max);
If passed, sets the new keep_alive_max. Note the limited functionality under threaded MPMs. Returns the keep_alive_max setting. If CW$new_keep_alive_max is passed, returns the setting before the change.
since: 2.0.00
Get/set the CWKeepAliveTimeout setting (in microsecs), which specifies how long Apache will wait for another request before breaking a CWKeepAlive connection.

  $keep_alive_timeout      = $s->keep_alive_timeout();
  $prev_keep_alive_timeout = $s->keep_alive_timeout($new_timeout);
The expected value is in microsecs. If passed, sets the new CWKeepAlive timeout. Note the limited functionality under threaded MPMs. Returns the CWKeepAlive timeout value (in microsecs). If CW$new_timeout is passed, returns the setting before the change.
since: 2.0.00
Get/set limit on number of request header fields

  $limit_req_fields      = $s->limit_req_fields();
  $prev_limit_req_fields = $s->limit_req_fields($new_limit_req_fields);
If passed, sets the new request headers number limit. Note the limited functionality under threaded MPMs. Returns the request headers number limit. If CW$new_limit_req_fields is passed, returns the setting before the change.
since: 2.0.00
Get/set limit on size of any request header field

  $limit_req_fieldsize = $s->limit_req_fieldsize();
  $prev_limit          = $s->limit_req_fieldsize($new_limit);
If passed, sets the new request header size limit. Note the limited functionality under threaded MPMs. Returns the request header size limit. If CW$new_limit is passed, returns the setting before the change.
since: 2.0.00
Get/set limit on size of the HTTP request line

  $limit_req_line      = $s->limit_req_line();
  $prev_limit_req_line = $s->limit_req_line($new_limit_req_line);
If passed, sets the new request line limit value. Note the limited functionality under threaded MPMs. Returns the request line limit value If CW$new_limit_req_line is passed, returns the setting before the change.
since: 2.0.00
Get/set the CWLogLevel directive value

  $loglevel      = $s->loglevel();
  $prev_loglevel = $s->loglevel($new_loglevel);
If passed, sets a new CWLogLevel value Note the limited functionality under threaded MPMs. Returns the CWLogLevel value as a constant. If CW$new_loglevel is passed, returns the setting before the change.
since: 2.0.00

For example, to set the CWLogLevel value to CWinfo:

  use Apache2::Const -compile => qw(LOG_INFO);
  $s->loglevel(Apache2::Const::LOG_INFO);
The next server record in the list (if there are vhosts)

  $s_next = $s->next();
since: 2.0.00

For example the following code traverses all the servers, starting from the base server and continuing to vhost servers, counting all available vhosts:

  use Apache2::ServerRec ();
  use Apache2::ServerUtil ();
  my $server = Apache2::ServerUtil->server;
  my $vhosts = 0;
  for (my $s = $server->next; $s; $s = $s->next) {
      $vhosts++;
  }
  print "There are $vhosts virtual hosts";
Get/set pathname for the CWServerPath setting

  $path      = $s->path();
  $prev_path = $s->path($new_path);
If passed, sets the new path. Note the limited functionality under threaded MPMs. Returns the path setting. If CW$new_path is passed, returns the setting before the change.
since: 2.0.00
Get/set the port value

  $port      = $s->port();
  $prev_port = $s->port($new_port);
If passed, sets the new port. Note the limited functionality under threaded MPMs. META: I don't think one should be allowed to change port number after the server has started. Returns the port setting. If CW$new_port is passed returns the setting before the change.
since: 2.0.00
The process this server is running in

  $proc = $s->process();
since: 2.0.00
Get/set the CWServerAdmin value

  $server_admin      = $s->server_admin();
  $prev_server_admin = $s->server_admin($new_server_admin);
If passed, sets the new CWServerAdmin value. Note the limited functionality under threaded MPMs. Returns the CWServerAdmin value. If CW$new_server_admin is passed, returns the setting before the change.
since: 2.0.00
Get/set the CWServerName value

  $server_hostname      = $s->server_hostname();
  $prev_server_hostname = $s->server_hostname($new_server_hostname);
If passed, sets the CWServerName value Note the limited functionality under threaded MPMs. Returns the CWServerName value If CW$new_server_hostname is passed, returns the setting before the change.
since: 2.0.00
Get/set the timeout (CWTimeOut) (in microsecs), which Apache will wait for before it gives up doing something

  $timeout      = $s->timeout();
  $prev_timeout = $s->timeout($new_timeout);
If passed, sets the new timeout (the value should be in microseconds). Note the limited functionality under threaded MPMs. Returns the timeout setting in microseconds. If CW$new_timeout is passed, returns the setting before the change.
since: 2.0.00

Let us repeat again: the timeout values is microseconds. For example to set the timeout to 20 secs:

  $s->timeout(20_000_000);

Notes

Limited Functionality under Threaded MPMs

Note that under threaded MPMs, some of the read/write accessors, will be able to set values only before threads are spawned (i.e. before the CWChildInit phase). Therefore if you are developing your application on the non-threaded MPM, but planning to have it run under threaded mpm, you should not use those methods to set values after the ChildInit phase.

The affected accessor methods are marked as such in their respective documentation entries.

Unsupported API

CWApache2::ServerRec also provides auto-generated Perl interface for a few other methods which aren't tested at the moment and therefore their API is a subject to change. These methods will be finalized later as a need arises. If you want to rely on any of the following methods please contact the the mod_perl development mailing list so we can help each other take the steps necessary to shift the method to an officially supported API. Get the addrs value

  $addrs = $s->addrs();
Returns the addrs setting.
since: subject to change

META: this methods returns a vhost-specific Apache2::ServerAddr object, which is not implemented at the moment. See the struct server_addr_rec entry in httpd-2.0/include/httpd.h for more information. It seems that most (all?) of the information in that record is available through other APIs. Get the lookup_defaults value. MIME type info, etc., before we start checking per-directory info.

  $lookup_defaults = $s->lookup_defaults();
Returns the lookup_defaults setting.
since: subject to change
Get config vector containing pointers to modules' per-server config structures.

  $module_config = $s->module_config();
Returns the module_config setting.
since: subject to change
Get/set the value(s) for the CWServerAlias setting

  $names      = $s->names();
  $prev_names = $s->names($new_names);
If passed, sets the new names. Note the limited functionality under threaded MPMs. Returns the names setting. If CW$new_names is passed, returns the setting before the change.
since: 2.0.00

META: we don't have CWAPR::ArrayHeader yet Wildcarded names for ServerAlias servers

  $wild_names      = $s->wild_names();
  $prev_wild_names = $s->wild_names($new_wild_names);
If passed, sets the new wild_names. Note the limited functionality under threaded MPMs. Returns the wild_names setting. If CW$new_wild_names is passed, returns the setting before the change.
since: 2.0.00

META: we don't have CWAPR::ArrayHeader yet

See Also

mod_perl 2.0 documentation.

Copyright

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

Authors

The mod_perl development team and numerous contributors.