Apache - Perl-Schnittstelle zum Apache-Server-API
use Apache ();
Dieses Modul stellt eine Perl-Schnittstelle zum Apache-API zur Verfügung. Sie ist hauptsächlich für mod_perl gedacht, kann aber auch für andere Apache-Module verwendet werden, die einen Perl-Interpreter einbetten möchten. Wir möchten Ihnen empfehlen, sich auch die Beschreibung des Apache-C-APIs unter http://www.apache.org/docs/ anzusehen.
Das Request-Objekt enthält alle Informationen, die der Server benötigt, um einen Request (eine Anforderung) zu bedienen. Apache-Perl*Handlern wird eine Referenz auf das Request-Objekt als Parameter übergeben. Diese können es dann aktualisieren oder auf unterschiedliche Weise verwenden. Die meisten nachfolgend beschriebenen Methoden lesen Informationen aus dem Request-Objekt oder aktualisieren diese Informationen. Die Perl-Version des Request-Objekts wird über bless in das Apache-Paket aufgenommen und ist eigentlich eine "verkleidete" C-Strukrur request_rec*.
- Apache-request([$r])
Die Methode Apache->request liefert eine Referenz auf das Request-Objekt zurück.
Perl*Handler erhalten eine Referenz auf das Request-Objekt in @_ übergeben. Allerdings müssen zum Beispiel Skripten, die unter Apache::Registry laufen, eine Möglichkeit haben, auf das Request-Objekt zuzugreifen. Solche Skripten erhalten durch den Aufruf von Apache->request eine Referenz auf das Request-Objekt.
$r-as_string
Gibt ein String-Abbild des Request-Objekts zurück. Hauptsächlich zum Debugging gedacht.
$r-main
Handelt es sich beim aktuellen Request um einen Subrequest, gibt diese Methode eine mit bless gesicherte Referenz auf die Haupt-Request-Struktur zurück. Ist der aktuelle Request der Haupt-Request, gibt die Methode undef zurück.
$r-prev
Diese Methode gibt eine mit bless gesicherte Referenz auf die vorherige (interne) Request-Struktur zurück bzw. undef, wenn es keinen vorherigen Request gibt.
$r-next
Diese Methode gibt eine mit bless gesicherte Referenz auf die nächste (interne) Request-Struktur zurück bzw. undef, wenn es keinen nächsten Request gibt.
$r-last
Diese Methode gibt eine mit bless gesicherte Referenz auf die letzte (interne) Request-Struktur zurück. Nützlich zum Logging von Modulen.
$r-is_main
Gibt wahr zurück, wenn das aktuelle Request-Objekt für den Haupt-Request gedacht ist. (Sollte das gleiche Ergebnis zurückliefern wie !$r->main, ist aber effizienter.)
$r-is_initial_req
Gibt wahr zurück, wenn der aktuelle Request der erste interne Request ist. Gibt falsch zurück, wenn der Request ein Subrequest oder ein interner Redirect ist.
Apache stellt einen Subrequest-Mechanismus zur Verfügung, mit dem aus einer URI oder einem Dateinamen ein neuer (Sub-)Request abgeleitet werden kann. Dabei werden alle Zugriffprüfungen usw. durchgeführt, ohne die eigentliche Response-Phase des Requests durchzuführen. Beachten Sie, daß wir hier das Präfix sub_req_ weggelassen haben. Die von den Lookup-Methoden zurückgelieferte C-Struktur request_rec* ist über bless in der Apache::SubRequest-Klasse bekannt. Daher wird destroy_sub_request() automatisch bei Apache::SubRequest->DESTROY aufgerufen, wenn das Objekt aus dem Geltungsbereich verschwindet. Die Klasse Apache::SubRequest erbt alle Methoden von der Apache-Klasse.
- $r-lookup_uri($uri)
my $subr = $r->lookup_uri($uri);
my $filename = $subr->filename;
unless(-e $filename) {
warn "Kann $filename nicht abfragen!\n";
}
- $r-lookup_file($filename)
my $subr = $r->lookup_file($filename);
- $subr-run
if($subr->run != OK) {
$subr->log_error("Irgend etwas ist schiefgegangen!");
}
In diesem Abschnitt wollen wir einen Blick auf die verschiedenen Methoden werfen, mit denen die vom Client gesendeten Request-Parameter bestimmt werden können. In den nachfolgenden Beispielen ist $r ein Request-Objekt, das über bless in die Apache-Klasse eingebunden wurde. Dieses Objekt wird aus dem ersten Parameter bestimmt, der an eine Handler-Subroutine oder an Apache->request übergeben wird.
- $r-method( [$meth] )
Die Methode $r->method liefert die Request-Methode zurück. Dabei handelt es sich um einen String wie "GET", "HEAD" oder "POST". Die Übergabe eines Arguments legt die Methode fest, die hauptsächlich für interne Redirects verwendet wird.
$r-method_number( [$num] )
Die Methode $r->method_number liefert die Nummer der Request-Methode zurück. Die Methodennummern sind durch die Konstanten M_GET, M_POST,... definiert, die im Apache::Constants-Modul verfügbar sind. Die Übergabe eines Arguments legt die Methodennummer fest, die hauptsächlich für interne Redirects und zur Prüfung von Authorisierungsbeschränkungen verwendet wird.
$r-bytes_sent
Die Anzahl der an den Client übertragenen Bytes. Nützlich zum Logging etc.
$r-the_request
Die vom Client gesendete Request-Zeile. Nützlich zum Logging etc.
$r-proxyreq
Gibt wahr zurück, wenn es sich um einen Proxy-HTTP-Request handelt. Wird hauptsächlich in der Phase des Requests genutzt, in der der Dateiname übersetzt wird. Diese Phase kann von einem PerlTransHandler ausgeführt werden.
$r-header_only
Gibt wahr zurück, wenn der Client nur nach Headern fragt, d.h., wenn die Request-Methode HEAD war.
$r-protocol
Die Methode $r->protocol gibt einen String zurück, der das vom Client verwendete Protokoll identifiziert. Typische Werte sind "HTTP/1.0" oder "HTTP/1.1".
$r-uri( [$uri] )
Die Methode $r->uri gibt den angeforderten URI zurück. Optional kann dieser mit dem ersten Argument geändert werden.
$r-filename( [$filename] )
Die Methode $r->filename gibt das Ergebnis der Übersetzung URI --> Dateiname zurück. Optional wird es mit dem ersten Argument geändert, wenn Sie die Übersetzung übernehmen wollen.
$r-path_info( [$path_info] )
Die Methode $r->path_info liefert den Teil des Pfades zurück, der nach der Übersetzung URI --> Dateiname übrigbleibt. Optional wird dieser mit dem ersten Argument geändert, wenn Sie die Übersetzung übernehmen wollen.
$r-args
Die Methode $r->args gibt den Inhalt des URI-Query-Strings zurück. Im Skalarkontext wird der gesamte String zurückgegeben, im Listenkontext wird eine Liste der erkannten Schlüssel/Wert-Paare zurückgeliefert. Sie können sie also wie folgt verwenden:
$query = $r->args;
%in = $r->args;
$r-headers_in
Die Methode $r->headers_in liefert einen %hash der Client-Request-Header zurück. Sie kann zur Initialisierung eines Perl-Hashes verwendet werden, oder man kann die (weiter unten beschriebene) Methode $r->header_in() verwenden, um einen bestimmten Header-Wert direkt zu ermitteln.
$r-header_in( $header_name, [$value] )
Gibt den Wert eines Client-Headers zurück. Kann wie folgt verwendet werden:
$ct = $r->header_in("Content-type");
$r->header_in($key, $val); # Wert von Header '$key' setzen.
$r-content
Die Methode $r->content gibt den eigentlichen, vom Client gelesenen Body zurück, allerdings nur, wenn application/x-www-form-urlencoded der Inhaltstyp (Content-Type) ist. Beim Aufruf im Skalarkontext wird der gesamte String zurückgegeben. Der Aufruf im Listenkontext liefert eine Liste der erkannten Schlüssel/Wert-Paare zurück. *HINWEIS*: Sie können dies nur einmal abfragen, da beim Aufruf der gesamte Body vom Client gelesen wird.
$r-read($buf, $bytes_to_read)
Diese Methode wird verwendet, um Daten vom Client zu lesen. Dabei wird eine Schleife durchlaufen, bis $bytes_to_read Bytes eingelesen sind oder ein Timeout aufgetreten ist.
Zusätzlich legt diese Methode vor dem Lesen mit $r->hard_timeout einen Timeout fest.
$r-get_remote_host
Ermittelt den DNS-Hostnamen des Clients. Ist die Konfigurationsdirektive HostNameLookups ausgeschaltet, wird statt dessen die IP-Adresse des Clients in dezimaler Punktnotation zurückgegeben. Gibt undef zurück, wenn der Hostname unbekannt ist.
$r-get_remote_logname
Ermittelt den Systemnamen des entfernten Benutzers. Gibt undef zurück, wenn das entfernte System keinen RFC-1413-Server betreibt oder wenn die Konfigurationsdirektive IdentityCheck ausgeschaltet ist.
Weitere Informationen über den Client können Sie über das nachfolgend erläuterte Apache::Connection-Objekt erhalten.
- $c = $r-connection
Die Methode $r->connection gibt eine Referenz auf ein Verbindungsobjekt (connection-Objekt) für den Request zurück (das über bless im Apache::Connection-Paket aufgenommen wurde). In Wirklichkeit eine "verkleidete" C-Struktur conn_rec*. Die folgenden Methoden können auf das Verbindungsobjekt angewandt werden:
$c-remote_host
Wenn die Konfigurationsdirektive HostNameLookups eingeschaltet ist, führt der Server beim ersten Aufruf von $r->get_remote_host einen DNS-Lookup durch, um den Hostnamen des entfernten Clients zu ermitteln. Das Ergebnis wird in $c->remote_host zwischengespeichert und zurückgegeben. Ist der Server nicht in der Lage, den Hostnamen des entfernten Clients aufzulösen, wird der Wert auf "" gesetzt. Nachfolgende Aufrufe von $r->get_remote_host geben den zwischengespeicherten Wert zurück.
Ist die Konfigurationsdirektive HostNameLookups hingegen ausgeschaltet, geben Aufrufe von $r->get_remote_host einen String zurück, der die IP-Adresse des entfernten Clients in dezimaler Punktnotation enthält. Dieser String wird allerdings nicht im Cache abgelegt, und $c->remote_host bleibt undefiniert. Es ist daher besser, $r->get_remote_host aufzurufen, statt direkt auf diese Variable zuzugreifen.
$c-remote_ip
Die IP-Adresse des entfernten Clients in dezimaler Punktnotation. Wird gesetzt, wenn der Server das Connection-Record erzeugt, und ist daher immer definiert.
Dieser Wert kann auch mit einem Argument gesetzt werden. Dies ist von Nutzen, wenn Ihr Server sich hinter einem Squid-Accelerator-Proxy-Server befindet, was einen HTTP_X_FORWARDED_FOR-Header hinzufügt.
$c-local_addr
Eine gepackte SOCKADDR_IN. Sie besitzt das gleiche Format, wie es von Socket zurückgegeben wird, und enthält den Port und die Adresse des lokalen Hosts, mit dem der entfernte Client verbunden ist. Wird vom Server gesetzt, wenn er das Connection-Record erzeugt, und ist daher immer definiert.
$c-remote_addr
Eine gepackte SOCKADDR_IN. Sie besitzt das gleiche Format, wie es von Socket zurückgegeben wird, und enthält den Port und die Adresse des entfernten Hosts, mit dem der Server verbunden ist. Wird vom Server gesetzt, wenn er das Connection-Record erzeugt, und ist daher immer definiert.
Dies kann unter anderem zusammen mit $c->local_addr genutzt werden, um RFC-1413-basierte Identitätsprüfungen (Ident) auf dem entfernten Client durchzuführen, auch wenn die Konfigurationsdirektive IdentityCheck ausgeschaltet ist.
Kann wie folgt verwendet werden:
use Net::Ident qw (lookupFromInAddr);
...
my $remoteuser = lookupFromInAddr ($c->local_addr,
$c->remote_addr, 2);
Beachten Sie, daß die Schnittstelle lookupFromInAddr im Net::Ident-Modul nicht existiert. Der Autor plant aber, sie bald hinzuzufügen.
$c-remote_logname
Ist die Konfigurationsdirektive IdentityCheck eingeschaltet, führt der Server beim ersten Aufruf von $r->get_remote_logname einen RFC-1413-Lookup (Ident) durch, um den Systemnamen des entfernten Benutzers zu ermitteln. Generell ist das für alle UNI*-Systeme der Login-Name. Das Ergebnis wird in $c->remote_logname zwischengespeichert und dann zurückgeliefert. Nachfolgende Aufrufe von $r->get_remote_logname geben diesen zwischengespeicherten Wert zurück.
Ist die Konfigurationsdirektive IdentityCheck hingegen ausgeschaltet, macht $r->get_remote_logname nichts, und $c->remote_logname ist immer undefiniert.
$c-user
War eine Authentifizierungsprüfung erfolgreich, legt der Authentifizierungs-Handler den Benutzernamen hier ab.
$c-auth_type
Gibt (falls zutreffend) das Authentifizierungsschema zurück, das $c->user erfolgreich authentifiziert hat.
$c-aborted
Gibt wahr zurück, wenn der Client nicht mehr mit uns redet.
Die folgenden Methoden werden verwendet, um Informationen aus Server-Konfigurationsdateien und Zugriffs-Steuerdateien zu ermitteln.
- $r-dir_config( $key )
Gibt den Wert einer verzeichnisorientierten Variable zurück, die über die PerlSetVar-Direktive gesetzt wird.
# <Location /foo/bar>
# SetPerlVar Key Value
# </Location>
my $val = $r->dir_config('Key');
$r-requires
Gibt eine Arrayreferenz mit Hashreferenzen zurück, die mit der require-Direktive in Zusammenhang stehende Informationen enthält. Wird normalerweise für die Zugriffskontrolle verwendet. Ein Beispiel finden Sie in Apache::AuthzAge.
$r-auth_type
Gibt eine Referenz auf den aktuellen Wert der verzeichnisorientierten Konfigurationsdirektive AuthType zurück. Normalerweise steht dieser Wert auf Basic, um das in RFC 1945, Hypertext Transfer Protocol -- HTTP/1.0, definierte, grundlegende Authentifizierungsschema zu nutzen. Sie können aber auch einen anderen Wert einsetzen und Ihr eigenes Authentifizierungsschema implementieren.
$r-auth_name
Liefert eine Referenz auf den aktuellen Wert der verzeichnisorientierten Konfigurationsdirektive AuthName zurück. Die AuthName-Direktive erzeugt einen Sicherheitsbereich innerhalb des Server-Dokumentenraums. Frei übersetzt, äußert sich RFC 1945 wie folgt: "Diese Bereiche erlauben es, die geschützten Ressourcen auf einem Server in eine Reihe von Sicherheitskorridoren aufzuteilen, von denen jeder ein eigenes Authentifizierungsschema und/oder eine eigene Autorisierungsdatenbank besitzt." Der Client verwendet die Root-URL des Servers, um zu ermitteln, welche Authentifizierungsinformationen bei jedem HTTP-Request übertragen werden müssen. Diese Informationen werden mit dem Authentifizierungsbereich versehen, in welchem sie erzeugt wurden. Während der Authentifizierungsphase verwendet der Server dann den aktuellen Authentifizierungsbereich (aus $r->auth_name), um zu ermitteln, welche seiner Informationen er für die Authentifizierung benutzt.
$r-document_root
Gibt eine Referenz auf den aktuellen Wert der Server-basierten Konfigurationsdirektive DocumentRoot zurück. Frei übersetzt, steht in der Apache-Server-Dokumentation etwa folgendes: "Solange nicht eine Direktive wie Alias zutrifft, hängt der Server den Pfad der angeforderten URL an die Document-Root an, um den Pfad auf das Dokument zu generieren." Der gleiche Wert wird CGI-Skripten in der Umgebungsvariable DOCUMENT_ROOT übergeben.
$r-allow_options
Mit der Methode $r->allow_options können Sie prüfen, ob es erlaubt ist, ein Perl-Skript auszuführen. Im Modul Apache::Options stehen die Konstanten, gegen die geprüft wird.
if(!($r->allow_options & OPT_EXECCGI)) {
$r->log_reason("Option ExecCGI ist in diesem Verzeichnis deaktiviert.",
$filename);
}
$r-get_server_port
Gibt die Portnummer zurück, an der der Server horcht.
$s = $r-server
Gibt eine Referenz auf das Serverinfo-Objekt zurück (das durch bless im Apache::Server-Paket bekannt ist). In Wirklichkeit handelt es sich hier um eine "verkleidete" C-Struktur server_rec*. Die folgenden Methoden können auf das Server-Objekt angewandt werden:
$s = Apache-server
Wie oben, aber nur während des Server-Startups in <Perl>-Abschnitten, PerlScript oder PerlModule verfügbar.
$s-server_admin
Gibt die E-Mail-Adresse der für den Server verantwortlichen Person zurück.
$s-server_hostname
Gibt den von diesem Server verwendeten Hostnamen zurück.
$s-port
Gibt den Port zurück, an dem dieser Server horcht.
$s-is_virtual
Gibt wahr zurück, wenn dies ein virtueller Server ist.
$s-names
Gibt die (mit Wildcards versehenen) Namen für ServerAlias-Server zurück.
$s-warn
Alias für Apache::warn.
$s-log_error
Alias für Apache::log_error.
Mit den folgenden Methoden werden die Responses an den Client erstellt und zurückgegeben. Das umfaßt üblicherweise die Einrichtung von $r->status(), den verschiedenen Inhaltsattributen (Content) und einiger optionaler $r->header_out()-Aufrufe, bevor $r->send_http_header() aufgerufen werden kann (der die Header dann an den Client schickt). Danach ruft eine typische Anwendung die Methode $r->print() auf, um die Response (also die eigentlichen Daten) an den Client zu schicken.
- $r-send_http_header
Sende die Response-Zeile und alle Header an den Client.
Diese Methode erzeugt Header aus den (nachfolgend erklärten) $r->content_xxx()- und $r->no_cache()-Attributen und hängt dann die durch $r->header_out (oder, wenn der Status einen Fehler andeutet, $r->err_header_out) definierten Header an.
$r-get_basic_auth_pw
Ist der aktuelle Request über eine Basic-Authentifizierung geschützt, gibt die Methode 0 zurück, anderenfalls -1. Der zweite Rückgabewert enthält das vom Client gesendete, decodierte Paßwort.
($ret, $sent_pw) = $r->get_basic_auth_pw;
$r-note_basic_auth_failure
Bevor Basic-Authentifizierung vom Client angefordert wird, stellt diese Methode die ausgehenden HTTP-Header so ein, daß der Client nach der Authentifizierung für den in der Konfigurationsdirektive AuthName stehenden Bereich gefragt wird.
$r-handler( [$meth] )
Lege den Handler für einen Request fest. Wird normalerweise durch die Konfigurationsdirektive AddHandler festgelegt.
$r->handler( "perl-script" );
$r-notes( $key, [$value] )
Gib den Wert eines benannten Eintrags in der Apache-notes-Tabelle zurück. Optional kann der Wert eines benannten Eintrags auch gesetzt werden. Diese Tabelle wird von Apache-Modulen verwendet, um sich gegenseitig Nachrichten zu übergeben. Bei der Entwicklung von Handlern mit mod_perl können Sie hierzu generell Perl-Variablen verwenden.
$r->notes("MY_HANDLER", OK);
$val = $r->notes("MY_HANDLER");
$r-subprocess_env( $key, [$value] )
Gib den Wert eines benannten Eintrags in der Apache-Tabelle subprocess_env zurück. Optional kann der Wert eines benannten Eintrags auch gesetzt werden. Diese Tabelle wird von mod_include verwendet. Durch Setzen einiger spezieller Variablen innerhalb des Perl-Handlers ist es möglich, perl und mod_include auf elegante Weise zu kombinieren. Schreiben Sie in einem PerlHeaderParser-Handler beispielsweise
$r->subprocess_env(MyLanguage => "de");
können Sie in Ihrem .shtml-Dokument folgendes schreiben:
<!--#if expr="$MyLanguage = en" -->
English
<!--#elif expr="$MyLanguage = de" -->
Deutsch
<!--#else -->
Sorry
<!--#endif -->
$r-content_type( [$newval] )
Lies oder setze den an den Client gesendeten Inhaltstyp ("content type"). Inhaltstypen sind Strings wie "text/plain", "text/html" oder "image/gif". Entspricht dem "Content-Type"-Header im HTTP-Protokoll. Ein Beispiel für die Anwendung ist:
$previous_type = $r->content_type;
$r->content_type("text/plain");
$r-content_encoding( [$newval] )
Lies oder setze die Inhaltscodierung ("content encoding"). Inhaltscodierungen sind Strings wie "gzip" oder "compress". Entspricht dem "Content-Encoding"-Header im HTTP-Protokoll.
$r-content_languages( [$array_ref] )
Lies oder setze die Sprachen des Inhalts. Die Sprache des Inhalts entspricht dem "Content-Language"-HTTP-Header und ist eine Arrayreferenz auf Strings wie "en" oder "no".
$r-status( $integer )
Lies oder setze den Reply-Status (Antwortstatus) für den Client-Request. Das Modul Apache::Constants stellt mnemonische Namen für die Statuscodes zur Verfügung.
$r-status_line( $string )
Lies oder setze die Response-Statuszeile. Die Statuszeile ist ein String wie "200 Document follows" und hat Vorrang vor dem Wert, der mit der oben beschriebenen $r->status()-Methode festgelegt wurde.
$r-headers_out
Die Methode $r->headers_out liefert einen %hash mit Server-Response-Headern zurück. Kann zur Initialisierung eines Perl-Hashes verwendet werden. Sie können aber auch die (weiter unten beschriebene) Methode $r->header_out() verwenden, um einen bestimmten Header-Wert direkt zu ermitteln oder zu setzen.
$r-header_out( $header, $value )
Ändere den Wert eines Response-Headers oder erzeuge einen neuen. Sie dürfen mit dieser Methode keine "Content-XXX"-Header definieren, weil diese Header über eigene Methoden verfügen. Ein Beispiel für die Verwendung:
$r->header_out("WWW-Authenticate" => "Basic");
$val = $r->header_out($key);
$r-err_headers_out
Die Methode $r->err_headers_out gibt einen %hash mit Server-Response-Headern zurück. Kann zur Initialisierung eines Perl-Hashes verwendet werden. Sie können aber auch die (weiter unten beschriebene) Methode $r->err_header_out() verwenden, um einen bestimmten Header-Wert direkt zu ermitteln oder zu setzen.
Der Unterschied zwischen headers_out und err_headers_out besteht darin, daß der Letztgenannte auch bei einem Fehler ausgegeben wird und über interne Redirects hinweg erhalten bleibt (damit die für ErrorDocument-Handler ausgegebenen Header ihn enthalten).
$r-err_header_out( $header, [$value] )
Ändere den Wert eines Fehler-Response-Headers oder erzeuge einen neuen. Diese Header werden verwendet, wenn der Status einen Fehler anzeigt.
$r->err_header_out("Warnung" => "Pech gehabt");
$val = $r->err_header_out($key);
$r-no_cache( $boolean )
Dieses Flag zeigt an, daß die zurückgegebenen Daten sich laufend ändern ("volatile") und daß man dem Client mitteilen muß, diese Daten nicht im Cache abzulegen.
$r-print( @list )
Diese Methode sendet mit $r->write_client Daten an den Client, definiert vor dem Senden aber mit $r->hard_timeout einen Timeout.
$r-send_fd( $filehandle )
Sendet den Inhalt einer Datei an den Client. Kann beispielsweise wie folgt verwendet werden:
open(FILE, $r->filename) || return 404;
$r->send_fd(FILE);
close(FILE);
$r-internal_redirect( $newplace )
Redirect an eine andere Stelle im Server-Namensraum, ohne den Client darüber zu informieren. Beispiel:
$r->internal_redirect("/home/sweet/home.html");
$r-internal_redirect_handler( $newplace )
Wie internal_redirect, aber der handler von $r wird beibehalten.
$r-custom_response($code, $uri)
Diese Methode stellt einen Hook in den ErrorDocument-Mechanismus zur Verfügung. Auf diese Weise können Sie für einen gegebenen Response-Code während der Ausführung der Anforderung eine eigene Response konfigurieren.
Beispiel:
use Apache::Constants ':common';
sub handler {
my($r) = @_;
if($things_are_ok) {
return OK;
}
#<Location $r->uri>
#ErrorDocument 401 /error.html
#</Location>
$r->custom_response(AUTH_REQUIRED, "/error.html");
#Kann auch Strings senden.
#<Location $r->uri>
#ErrorDocument 401 "Geh weg!"
#</Location>
#$r->custom_response(AUTH_REQUIRED, "Geh weg!");
return AUTH_REQUIRED;
}
- $r-soft_timeout($message)
- $r-hard_timeout($message)
- $r-kill_timeout
- $r-reset_timeout
(Dokumentation aus http_main.h geborgt.)
Es gibt zwei Funktionen, die Module aufrufen können, um einen Timeout (mit der für jeden virtuellen Server eingerichteten Timeout-Dauer) festzulegen. Diese Funktionen sind hard_timeout und soft_timeout.
Der Unterschied zwischen den beiden besteht in der Reaktion nach einem Timeout (oder wenn der Client abbricht). Ein soft_timeout bringt die Verbindung zum Client nur in einen Abbruchzustand ("aborted"), was dazu führt, daß http_protocol.c sich nicht mehr mit dem Client unterhält, andererseits aber den Code normal weiterlaufen läßt. Im Gegensatz dazu loggt hard_timeout() den Request und bricht dann vollständig ab, d.h., es erfolgt ein longjmp() in die accept()-Schleife in http_main. Alle mit dem Request-Resource-Pool verbundenen ("tie") Ressourcen werden aufgeräumt, alle anderen bleiben bestehen, das heißt, sie führen unter Umständen zu einem (Speicher-)Leck.
soft_timeout() wird (als eine generelle Regel) empfohlen, weil es Ihrem Code die Chance gibt aufzuräumen. Allerdings ist hard_timeout() möglicherweise die bequemste Möglichkeit, mit Timeouts umzugehen, die auf eine andere Ressource als den Client warten (solange Sie mit den Einschränkungen leben können).
Sind harte Timeouts ein Thema, können kritische Abschnitte mit block_alarms() und unblock_alarms() gesichert werden. Diese sind in alloc.c deklariert, weil sie meist zusammen mit Routinen verwendet werden, die etwas allozieren, und um sicherzustellen, daß ein Aufräumen auch registriert wird, bevor ein Alarm auftritt, der ein Aufräumen erzwingen könnte. Implementiert sind sie hingegen in http_main.c.
kill_timeout() deaktiviert jede Form von Timeout.
reset_timeout() setzt den laufenden Timeout zurück.
$r-post_connection($code_ref)
$r-register_cleanup($code_ref)
Registriert eine Cleanup-Funktion, die aufgerufen wird, bevor $r->pool aufgelöst (zerstört) wird.
$r->register_cleanup(sub {
my $r = shift;
warn "Registrierter Cleanup für ", $r->uri, " aufgerufen.\n";
});
Die Methode post_connection ist einfach ein Alias für register_cleanup, da diese Methode Code ausführen kann, nachdem die Client-Verbindung schon beendet wurde. Bei diesem Code muß es sich nicht um cleanup handeln.
Wir stellen auch einige Methoden zur Verfügung, mit denen die Unterstützung der CGI-Schnittstelle vereinfacht wird.
- $r-cgi_env
Gibt einen %hash zurück, mit dem eine Standard-CGI-Umgebung eingerichtet werden kann. Die typische Verwendung ist wie folgt:
%ENV = $r->cgi_env
Hinweis: $ENV{GATEWAY_INTERFACE} ist auf CGI-Perl/1.1 gesetzt, d.h., Sie können folgendes tun:
if($ENV{GATEWAY_INTERFACE} =~ /^CGI-Perl/) {
# mod_perl-Dinge tun.
}
else {
# Normale CGI-Dinge tun.
}
Bei der Übergabe eines Schlüssel/Wert-Paares wird die Umgebungsvariable gesetzt.
$r->cgi_env(REMOTE_GROUP => "camels");
$r-cgi_var($key);
Ruft $r->cgi_env($key) in einem Skalarkontext auf, um den Fehler eines Aufrufs im Listenkontext zu vermeiden.
my $doc_root = $r->cgi_env('DOCUMENT_ROOT');
$r-send_cgi_header()
Macht mit verschiedenen Headern wie Status:, Location: und Content-type: das gleiche wie mod_cgi und ruft dann $r->send_http_header() auf. Ein Beispiel für die Verwendung:
$r->send_cgi_header(<<EOT);
Location: /foo/bar
Content-type: text/html
EOT
Die folgenden Methoden können zum Logging von Fehlern verwendet werden.
- $r-log_reason($message, $file)
Warum ist der Request fehlgeschlagen?? Schreiben Sie eine Meldung in den Fehler-Log des Servers.
$r->log_reason("Mir war danach", $r->filename);
$r-log_error($message)
Oha! Schreiben Sie eine Meldung in den Fehler-Log des Servers.
$r->log_error("Schreiben wir mal was in den error_log");
$r-warn($message)
Bei Apache-Versionen vor 1.3 ist dies einfach ein Alias für log_error. Seit der Version 1.3 wird diese Nachricht nur nach error_log gesendet, wenn LogLevel auf warn oder höher steht.
- Apache::unescape_url($string)
Nützliche Funktion zum Entfernen von Fluchtsymbolen bei Sonderzeichen ("Unescaping"). Verwenden Sie diese Variante für Dateinamen/Pfade. Für übertragene Formulardaten steht unescape_url_info zur Verfügung.
Apache::unescape_url_info($string)
Nützliche Funktion zum Entfernen von Fluchtsymbolen bei Sonderzeichen in Formulardaten. Im Gegensatz zu unescape_url wird hier das Pluszeichen in ein Leerzeichen umgewandelt.
Apache::perl_hook($hook)
Gibt wahr zurück, wenn der angegebene Callback-Hook aktiviert ist:
for (qw(Access Authen Authz ChildInit Cleanup Fixup
HeaderParser Init Log Trans Type))
{
print "$_-Hook aktiviert\n" if Apache::perl_hook($_);
}
perl(1),
Hinweise zum Apache-C-API finden Sie unter http://www.apache.org/docs/
Diese Manpage dokumentiert "Apache.pm" in der Version mod_perl-1.16.
Das Perl-Interface zum Apache-C-API wurde von Doug MacEachern geschrieben. Beigetragen haben Gisle Aas, Andreas König, Eric Bartley, Rob Hartill, Gerald Richter, Salvador Ortiz und andere.
Deutsche Übersetzung von Peter Klicman, Köln
© 1998 by O'Reilly Verlag, Köln