stas 2003/05/14 00:14:16
Modified: src/docs/2.0/api/Apache Log.pod
Log:
improving the manpage
Revision Changes Path
1.3 +81 -38 modperl-docs/src/docs/2.0/api/Apache/Log.pod
Index: Log.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/Log.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- Log.pod 14 May 2003 06:08:44 -0000 1.2
+++ Log.pod 14 May 2003 07:14:16 -0000 1.3
@@ -9,6 +9,10 @@
#in startup.pl
#-------------
use Apache::Log;
+
+ use Apache::Const -compile => qw(OK :log);
+ use APR::Const -compile => qw(:error SUCCESS);
+
my $s = Apache->server;
$s->log_error("server: log_error");
@@ -25,6 +29,13 @@
#in a handler
#------------
use Apache::Log;
+
+ use strict;
+ use warnings FATAL => 'all';
+
+ use Apache::Const -compile => qw(OK :log);
+ use APR::Const -compile => qw(:error SUCCESS);
+
sub handler{
my $r = shift;
$r->log_error("request: log_error");
@@ -43,13 +54,15 @@
$r->log_rerror(Apache::LOG_MARK, Apache::LOG_DEBUG,
APR::ENOTIME, "in debug");
- $s->log_serror(Apache::LOG_MARK, Apache::LOG_INFO, 0,
- "server info");
+ $s->log_serror(Apache::LOG_MARK, Apache::LOG_INFO,
+ APR::SUCESS, "server info");
$s->log_serror(Apache::LOG_MARK, Apache::LOG_ERR,
APR::ENOTIME, "fatal error");
$s->warn('routine server warning');
+
+ return Apache::OK;
}
@@ -58,67 +71,80 @@
C<Apache::Log> provides the Perl API for Apache logging methods.
+Depending on the the current C<LogLevel> setting, only logging with
+the same log level or higher will be loaded. For example if the
+current C<LogLevel> is set to I<warning>, only messages with log level
+of the level I<warning> or higher (I<err>, I<crit>, I<elert> and
+I<emerg>) will be logged. Therefore this:
+ $r->log_rerror(Apache::LOG_MARK, Apache::LOG_WARNING,
+ APR::ENOTIME, "warning!");
+will log the message, but this one won't:
-=head1 Constants
+ $r->log_rerror(Apache::LOG_MARK, Apache::LOG_INFO,
+ APR::ENOTIME, "just an info");
-The following constants (sorted from the most severe level to the
-least severe) are used in logging methods to specify the log level at
-which the message should be logged:
+It will be logged only if the server log level is set to I<info> or
+I<debug>. C<LogLevel> is set in the configuration file, but can be
+changed using the
+C<L<$s-E<gt>loglevel()|docs::2.0::api::Apache::Server/C_loglevel_>>
+method.
-=over
+The filename and the line number of the caller are logged only if
+C<Apache::LOG_DEBUG> is used (because that's how Apache 2.0 logging
+mechanism works).
-=item * C<Apache::LOG_EMERG>
-=item * C<Apache::LOG_ALERT>
+=head1 Constants
-=item * C<Apache::LOG_CRIT>
+Log level constants can be compiled all at once:
-=item * C<Apache::LOG_ERR>
+ use Apache::Const -compile => qw(:log);
-=item * C<Apache::LOG_WARNING>
+or individually:
-=item * C<Apache::LOG_NOTICE>
+ use Apache::Const -compile => qw(LOG_DEBUG LOG_INFO);
-=item * C<Apache::LOG_INFO>
+=head2 LogLevel Constants
-=item * C<Apache::LOG_DEBUG>
+The following constants (sorted from the most severe level to the
+least severe) are used in logging methods to specify the log level at
+which the message should be logged:
-=back
+=head3 C<Apache::LOG_EMERG>
-For example if the current C<LogLevel> is set to I<warning>, only
-messages with log level of the level I<warning> or higher (I<err>,
-I<crit>, I<elert> and I<emerg>) will be logged. Therefore this:
+=head3 C<Apache::LOG_ALERT>
- $r->log_rerror(Apache::LOG_MARK, Apache::LOG_WARNING,
- APR::ENOTIME, "warning!");
+=head3 C<Apache::LOG_CRIT>
-will log the message, but this one won't:
+=head3 C<Apache::LOG_ERR>
- $r->log_rerror(Apache::LOG_MARK, Apache::LOG_INFO,
- APR::ENOTIME, "just an info");
+=head3 C<Apache::LOG_WARNING>
-It will be logged only if the server log level is set to I<info> or
-I<debug>. (either in the configuration file or using the
-C<$s-E<gt>loglevel()> method.)
+=head3 C<Apache::LOG_NOTICE>
-The filename and the line number of the caller are logged only if
-C<Apache::LOG_DEBUG> is used (because that's how Apache 2.0 logging
-mechanism works).
+=head3 C<Apache::LOG_INFO>
+
+=head3 C<Apache::LOG_DEBUG>
-Other constants:
+Make sure to compile the APR status constants before using them. For
+example to compile C<APR::SUCESS> and all the APR error status
+constants do:
-=over
+ use APR::Const -compile => qw(:error SUCCESS);
-=item * C<Apache::LOG_LEVELMASK>
+
+=head2 Other Constants
+
+=head3 C<Apache::LOG_LEVELMASK>
used to mask off the level value, to make sure that the log level's
value is within the proper bits range. e.g.:
$loglevel &= LOG_LEVELMASK;
-=item * C<Apache::LOG_TOCLIENT>
+=head3 C<Apache::LOG_TOCLIENT>
used to give content handlers the option of including the error text
in the C<ErrorDocument> sent back to the client. When
@@ -138,14 +164,31 @@
$r->notes->get("error-notes");
-Remember that client generated text streams sent back to the client
+Remember that client-generated text streams sent back to the client
MUST be escaped to prevent CSS attacks.
-=item * C<Apache::LOG_STARTUP>
+=head3 C<Apache::LOG_STARTUP>
+
+is useful for startup message where no timestamps, logging level is
+wanted. For example:
+
+ $s->log_serror(Apache::LOG_MARK, Apache::LOG_INFO,
+ APR::SUCCESS, "This log message comes with a header");
+
+Will print:
+
+ [Wed May 14 16:47:09 2003] [info] This log message comes with a header
+
+whereas, when C<Apache::LOG_STARTUP> is binary ORed as in:
+
+ $s->log_serror(Apache::LOG_MARK, Apache::LOG_INFO|Apache::LOG_STARTUP,
+ APR::SUCCESS, "This log message comes with no header");
+
+then the logging will be:
+
+ This log message comes with no header
-is set only during the startup.
-=back
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
