PAL.C.T MINI SHELL
.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "docs::api::Apache2::CmdParms 3"
.TH docs::api::Apache2::CmdParms 3 "2013-04-16" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Apache2::CmdParms \- Perl API for Apache command parameters object
.SH "Synopsis"
.IX Header "Synopsis"
.Vb 3
\& use Apache2::CmdParms ();
\& use Apache2::Module ();
\& use Apache2::Const \-compile => qw(NOT_IN_LOCATION);
\&
\& my @directives = (
\& {
\& name => \*(AqMyDirective\*(Aq,
\& cmd_data => \*(Aqsome extra data\*(Aq,
\& },
\& );
\&
\& Apache2::Module::add(_\|_PACKAGE_\|_, \e@directives);
\&
\& sub MyDirective {
\& my ($self, $parms, $args) = @_;
\&
\& # push config
\& $parms\->add_config([\*(AqServerTokens off\*(Aq]);
\&
\& # this command\*(Aqs command object
\& $cmd = $parms\->cmd;
\&
\& # check the current command\*(Aqs context
\& $error = $parms\->check_cmd_context(Apache2::Const::NOT_IN_LOCATION);
\&
\& # this command\*(Aqs context
\& $context = $parms\->context;
\&
\& # this command\*(Aqs directive object
\& $directive = $parms\->directive;
\&
\& # the extra information passed thru cmd_data to
\& # Apache2::Module::add()
\& $info = $parms\->info;
\&
\& # which methods are <Limit>ed ?
\& $is_limited = $parms\->method_is_limited(\*(AqGET\*(Aq);
\&
\& # which allow\-override bits are set
\& $override = $parms\->override;
\&
\& # which Options are allowed by AllowOverride (since Apache 2.2)
\& $override = $parms\->override_opts;
\&
\& # the path this command is being invoked in
\& $path = $parms\->path;
\&
\& # this command\*(Aqs pool
\& $p = $parms\->pool;
\&
\& # this command\*(Aqs configuration time pool
\& $p = $parms\->temp_pool;
\& }
.Ve
.SH "Description"
.IX Header "Description"
\&\f(CW\*(C`Apache2::CmdParms\*(C'\fR provides the Perl \s-1API\s0 for Apache command
parameters object.
.SH "API"
.IX Header "API"
\&\f(CW\*(C`Apache2::CmdParms\*(C'\fR provides the following functions and/or methods:
.ie n .SS """add_config"""
.el .SS "\f(CWadd_config\fP"
.IX Subsection "add_config"
Dynamically add Apache configuration at request processing runtime:
.PP
.Vb 1
\& $parms\->add_config($lines);
.Ve
.ie n .IP "obj: $parms ( ""Apache2::CmdParms object"" )" 4
.el .IP "obj: \f(CW$parms\fR ( \f(CWApache2::CmdParms object\fR )" 4
.IX Item "obj: $parms ( Apache2::CmdParms object )"
.PD 0
.ie n .IP "arg1: $lines (\s-1ARRAY\s0 ref)" 4
.el .IP "arg1: \f(CW$lines\fR (\s-1ARRAY\s0 ref)" 4
.IX Item "arg1: $lines (ARRAY ref)"
.PD
An \s-1ARRAY\s0 reference containing configuration lines per element, without
the new line terminators.
.IP "ret: no return value" 4
.IX Item "ret: no return value"
.PD 0
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.PP
See also:
\&\f(CW\*(C`$s\->add_config\*(C'\fR,
\&\f(CW\*(C`$r\->add_config\*(C'\fR
.ie n .SS """check_cmd_context"""
.el .SS "\f(CWcheck_cmd_context\fP"
.IX Subsection "check_cmd_context"
Check the current command against a context bitmask of forbidden contexts.
.PP
.Vb 1
\& $error = $parms\->check_cmd_context($check);
.Ve
.ie n .IP "obj: $parms ( ""Apache2::CmdParms object"" )" 4
.el .IP "obj: \f(CW$parms\fR ( \f(CWApache2::CmdParms object\fR )" 4
.IX Item "obj: $parms ( Apache2::CmdParms object )"
.PD 0
.ie n .IP "arg1: $check ( ""Apache2::Const :context constant"" )" 4
.el .IP "arg1: \f(CW$check\fR ( \f(CWApache2::Const :context constant\fR )" 4
.IX Item "arg1: $check ( Apache2::Const :context constant )"
.PD
the context to check against.
.ie n .IP "ret: $error ( string / undef )" 4
.el .IP "ret: \f(CW$error\fR ( string / undef )" 4
.IX Item "ret: $error ( string / undef )"
If the context is forbidden, this method returns a textual description
of why it was forbidden. If the context is permitted, this method returns
\&\f(CW\*(C`undef\*(C'\fR.
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PP
For example here is how to check whether a command is allowed in the
\&\f(CW\*(C`<Location>\*(C'\fR container:
.PP
.Vb 4
\& use Apache2::Const \-compile qw(NOT_IN_LOCATION);
\& if (my $error = $parms\->check_cmd_context(Apache2::Const::NOT_IN_LOCATION)) {
\& die "directive ... not allowed in <Location> context"
\& }
.Ve
.ie n .SS """cmd"""
.el .SS "\f(CWcmd\fP"
.IX Subsection "cmd"
This module's command information
.PP
.Vb 1
\& $cmd = $parms\->cmd();
.Ve
.ie n .IP "obj: $parms ( ""Apache2::CmdParms object"" )" 4
.el .IP "obj: \f(CW$parms\fR ( \f(CWApache2::CmdParms object\fR )" 4
.IX Item "obj: $parms ( Apache2::CmdParms object )"
.PD 0
.ie n .IP "ret: $cmd ( ""Apache2::Command object"" )" 4
.el .IP "ret: \f(CW$cmd\fR ( \f(CWApache2::Command object\fR )" 4
.IX Item "ret: $cmd ( Apache2::Command object )"
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.ie n .SS """directive"""
.el .SS "\f(CWdirective\fP"
.IX Subsection "directive"
This command's directive object in the configuration tree
.PP
.Vb 1
\& $directive = $parms\->directive;
.Ve
.ie n .IP "obj: $parms ( ""Apache2::CmdParms object"" )" 4
.el .IP "obj: \f(CW$parms\fR ( \f(CWApache2::CmdParms object\fR )" 4
.IX Item "obj: $parms ( Apache2::CmdParms object )"
.PD 0
.ie n .IP "ret: $directive ( ""Apache2::Directive object"" )" 4
.el .IP "ret: \f(CW$directive\fR ( \f(CWApache2::Directive object\fR )" 4
.IX Item "ret: $directive ( Apache2::Directive object )"
.PD
The current directive node in the configuration tree
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.ie n .SS """info"""
.el .SS "\f(CWinfo\fP"
.IX Subsection "info"
The extra information passed through \f(CW\*(C`cmd_data\*(C'\fR in
\&\f(CW\*(C`Apache2::Module::add()\*(C'\fR.
.PP
.Vb 1
\& $info = $parms\->info;
.Ve
.ie n .IP "obj: $parms ( ""Apache2::CmdParms object"" )" 4
.el .IP "obj: \f(CW$parms\fR ( \f(CWApache2::CmdParms object\fR )" 4
.IX Item "obj: $parms ( Apache2::CmdParms object )"
.PD 0
.ie n .IP "ret: $info ( string )" 4
.el .IP "ret: \f(CW$info\fR ( string )" 4
.IX Item "ret: $info ( string )"
.PD
The string passed in \f(CW\*(C`cmd_data\*(C'\fR
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PP
For example here is how to pass arbitrary information to a directive
subroutine:
.PP
.Vb 10
\& my @directives = (
\& {
\& name => \*(AqMyDirective1\*(Aq,
\& func => \e&MyDirective,
\& cmd_data => \*(AqOne\*(Aq,
\& },
\& {
\& name => \*(AqMyDirective2\*(Aq,
\& func => \e&MyDirective,
\& cmd_data => \*(AqTwo\*(Aq,
\& },
\& );
\& Apache2::Module::add(_\|_PACKAGE_\|_, \e@directives);
\&
\& sub MyDirective {
\& my ($self, $parms, $args) = @_;
\& my $info = $parms\->info;
\& }
.Ve
.PP
In this example \f(CW$info\fR will either be \f(CW\*(AqOne\*(Aq\fR or \f(CW\*(AqTwo\*(Aq\fR depending
on whether the directive was called as \fIMyDirective1\fR or
\&\fIMyDirective2\fR.
.ie n .SS """method_is_limited"""
.el .SS "\f(CWmethod_is_limited\fP"
.IX Subsection "method_is_limited"
Discover if a method is <Limit>ed in the current scope
.PP
.Vb 1
\& $is_limited = $parms\->method_is_limited($method);
.Ve
.ie n .IP "obj: $parms ( ""Apache2::CmdParms object"" )" 4
.el .IP "obj: \f(CW$parms\fR ( \f(CWApache2::CmdParms object\fR )" 4
.IX Item "obj: $parms ( Apache2::CmdParms object )"
.PD 0
.ie n .IP "arg1: $method (string)" 4
.el .IP "arg1: \f(CW$method\fR (string)" 4
.IX Item "arg1: $method (string)"
.PD
The name of the method to check for
.ie n .IP "ret: $is_limited ( boolean )" 4
.el .IP "ret: \f(CW$is_limited\fR ( boolean )" 4
.IX Item "ret: $is_limited ( boolean )"
.PD 0
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.PP
For example, to check if the \f(CW\*(C`GET\*(C'\fR method is being
\&\f(CW\*(C`<Limit>\*(C'\fRed in the current scope, do:
.PP
.Vb 3
\& if ($parms\->method_is_limited(\*(AqGET\*(Aq) {
\& die "...";
\& }
.Ve
.ie n .SS """override"""
.el .SS "\f(CWoverride\fP"
.IX Subsection "override"
Which allow-override bits are set (\f(CW\*(C`AllowOverride\*(C'\fR directive)
.PP
.Vb 1
\& $override = $parms\->override;
.Ve
.ie n .IP "obj: $parms ( ""Apache2::CmdParms object"" )" 4
.el .IP "obj: \f(CW$parms\fR ( \f(CWApache2::CmdParms object\fR )" 4
.IX Item "obj: $parms ( Apache2::CmdParms object )"
.PD 0
.ie n .IP "ret: $override ( bitmask )" 4
.el .IP "ret: \f(CW$override\fR ( bitmask )" 4
.IX Item "ret: $override ( bitmask )"
.PD
the allow-override bits bitmask, which can be tested against
\&\f(CW\*(C`Apache2::Const :override
constants\*(C'\fR.
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PP
For example to check that the \f(CW\*(C`AllowOverride\*(C'\fR's \f(CW\*(C`AuthConfig\*(C'\fR and
\&\f(CW\*(C`FileInfo\*(C'\fR options are enabled for this command, do:
.PP
.Vb 6
\& use Apache2::Const \-compile qw(:override);
\& $wanted = Apache2::Const::OR_AUTHCFG | Apache2::Const::OR_FILEINFO;
\& $masked = $parms\->override & $wanted;
\& unless ($wanted == $masked) {
\& die "...";
\& }
.Ve
.ie n .SS """override_opts"""
.el .SS "\f(CWoverride_opts\fP"
.IX Subsection "override_opts"
Which options are allowed to be overridden by \f(CW\*(C`.htaccess\*(C'\fR files. This is
set by \f(CW\*(C`AllowOverride Options=...\*(C'\fR.
.PP
.Vb 1
\& $override_opts = $parms\->override_opts;
.Ve
.PP
Enabling single options was introduced with Apache 2.2. For Apache 2.0 this
function simply returns a bitmask with all options allowed.
.ie n .IP "obj: $parms ( ""Apache2::CmdParms object"" )" 4
.el .IP "obj: \f(CW$parms\fR ( \f(CWApache2::CmdParms object\fR )" 4
.IX Item "obj: $parms ( Apache2::CmdParms object )"
.PD 0
.ie n .IP "ret: $override_opts ( bitmask )" 4
.el .IP "ret: \f(CW$override_opts\fR ( bitmask )" 4
.IX Item "ret: $override_opts ( bitmask )"
.PD
the bitmask, which can be tested against
\&\f(CW\*(C`Apache2::Const :options
constants\*(C'\fR.
.IP "since: 2.0.3" 4
.IX Item "since: 2.0.3"
.ie n .SS """path"""
.el .SS "\f(CWpath\fP"
.IX Subsection "path"
The current pathname/location/match of the block this command is in
.PP
.Vb 1
\& $path = $parms\->path;
.Ve
.ie n .IP "obj: $parms ( ""Apache2::CmdParms object"" )" 4
.el .IP "obj: \f(CW$parms\fR ( \f(CWApache2::CmdParms object\fR )" 4
.IX Item "obj: $parms ( Apache2::CmdParms object )"
.PD 0
.ie n .IP "ret: $path ( string / ""undef"" )" 4
.el .IP "ret: \f(CW$path\fR ( string / \f(CWundef\fR )" 4
.IX Item "ret: $path ( string / undef )"
.PD
If configuring for a block like <Location>,
<LocationMatch>, <Directory>, etc., the pathname part
of that directive. Otherwise, \f(CW\*(C`undef\*(C'\fR is returned.
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PP
For example for a container block:
.PP
.Vb 3
\& <Location /foo>
\& ...
\& </Location>
.Ve
.PP
\&\fI'/foo'\fR will be returned.
.ie n .SS """pool"""
.el .SS "\f(CWpool\fP"
.IX Subsection "pool"
Pool associated with this command
.PP
.Vb 1
\& $p = $parms\->pool;
.Ve
.ie n .IP "obj: $parms ( ""Apache2::CmdParms object"" )" 4
.el .IP "obj: \f(CW$parms\fR ( \f(CWApache2::CmdParms object\fR )" 4
.IX Item "obj: $parms ( Apache2::CmdParms object )"
.PD 0
.ie n .IP "ret: $p ( ""APR::Pool object"" )" 4
.el .IP "ret: \f(CW$p\fR ( \f(CWAPR::Pool object\fR )" 4
.IX Item "ret: $p ( APR::Pool object )"
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.ie n .SS """server"""
.el .SS "\f(CWserver\fP"
.IX Subsection "server"
The (vhost) server this command was defined in \fIhttpd.conf\fR
.PP
.Vb 1
\& $s = $parms\->server;
.Ve
.ie n .IP "obj: $parms ( ""Apache2::CmdParms object"" )" 4
.el .IP "obj: \f(CW$parms\fR ( \f(CWApache2::CmdParms object\fR )" 4
.IX Item "obj: $parms ( Apache2::CmdParms object )"
.PD 0
.ie n .IP "ret: $s ( ""Apache2::Server object"" )" 4
.el .IP "ret: \f(CW$s\fR ( \f(CWApache2::Server object\fR )" 4
.IX Item "ret: $s ( Apache2::Server object )"
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.ie n .SS """temp_pool"""
.el .SS "\f(CWtemp_pool\fP"
.IX Subsection "temp_pool"
Pool for scratch memory; persists during configuration, but destroyed
before the first request is served.
.PP
.Vb 1
\& $temp_pool = $parms\->temp_pool;
.Ve
.ie n .IP "obj: $parms ( ""Apache2::CmdParms object"" )" 4
.el .IP "obj: \f(CW$parms\fR ( \f(CWApache2::CmdParms object\fR )" 4
.IX Item "obj: $parms ( Apache2::CmdParms object )"
.PD 0
.ie n .IP "ret: $temp_pool ( ""APR::Pool object"" )" 4
.el .IP "ret: \f(CW$temp_pool\fR ( \f(CWAPR::Pool object\fR )" 4
.IX Item "ret: $temp_pool ( APR::Pool object )"
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.PP
Most likely you shouldn't use this pool object, unless you know what
you are doing. Use \f(CW\*(C`$parms\->pool\*(C'\fR instead.
.SH "Unsupported API"
.IX Header "Unsupported API"
\&\f(CW\*(C`Apache2::CmdParms\*(C'\fR also provides auto-generated Perl interface for
a few other methods which aren't tested at the moment and therefore
their \s-1API\s0 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 \s-1API\s0.
.ie n .SS """context"""
.el .SS "\f(CWcontext\fP"
.IX Subsection "context"
Get context containing pointers to modules' per-dir
config structures.
.PP
.Vb 1
\& $context = $parms\->context;
.Ve
.ie n .IP "obj: $parms ( ""Apache2::CmdParms object"" )" 4
.el .IP "obj: \f(CW$parms\fR ( \f(CWApache2::CmdParms object\fR )" 4
.IX Item "obj: $parms ( Apache2::CmdParms object )"
.PD 0
.ie n .IP "ret: $newval ( ""Apache2::ConfVector object"" )" 4
.el .IP "ret: \f(CW$newval\fR ( \f(CWApache2::ConfVector object\fR )" 4
.IX Item "ret: $newval ( Apache2::ConfVector object )"
.PD
Returns the commands' per-dir config structures
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.SH "See Also"
.IX Header "See Also"
mod_perl 2.0 documentation.
.SH "Copyright"
.IX Header "Copyright"
mod_perl 2.0 and its core modules are copyrighted under
The Apache Software License, Version 2.0.
.SH "Authors"
.IX Header "Authors"
The mod_perl development team and numerous
contributors.
y~or5J ={Eeu磝Qk ᯘG{?+]ן?wM3X^歌>{7پK>on\jy R g/=fOroNVv~Y+ NGuÝHWyw[eQʨSb> >}Gmx[o[<{Ϯ_qF vM IENDB`