1docs::api::ModPerl::UtiUls(e3r)Contributed Perl Documentdaotciso:n:api::ModPerl::Util(3)
2
3
4

NAME

6       ModPerl::Util - Helper mod_perl Functions
7

Synopsis

9         use ModPerl::Util;
10
11         # e.g. PerlResponseHandler
12         $callback = ModPerl::Util::current_callback;
13
14         # exit w/o killing the interpreter
15         ModPerl::Util::exit();
16
17         # untaint a string (do not use it! see the doc)
18         ModPerl::Util::untaint($string);
19
20         # removes a stash (.so, %INC{$stash}, etc.) as best as it can
21         ModPerl::Util::unload_package($stash);
22
23         # current perl's address (0x92ac760 or 0x0 under non-threaded perl)
24         ModPerl::Util::current_perl_id();
25

Description

27       "ModPerl::Util" provides mod_perl utilities API.
28

API

30       "ModPerl::Util" provides the following functions and/or methods:
31
32       "current_callback"
33
34       Returns the currently running callback name, e.g. 'PerlResponseHan‐
35       dler'.
36
37         $callback = ModPerl::Util::current_callback();
38
39       ret: $callback ( string )
40       since: 2.0.00
41
42       "current_perl_id"
43
44       Return the memory address of the perl interpreter
45
46         $perl_id = ModPerl::Util::current_perl_id();
47
48       ret: $perl_id ( string )
49           Under threaded perl returns something like: 0x92ac760
50
51           Under non-thread perl returns 0x0
52
53       since: 2.0.00
54
55       Mainly useful for debugging applications running under threaded-perl.
56
57       "exit"
58
59       Terminate the request, but not the current process (or not the current
60       Perl interpreter with threaded mpms).
61
62         ModPerl::Util::exit($status);
63
64       opt arg1: $status ( integer )
65           The exit status, which as of this writing is ignored. (it's
66           accepted to be compatible with the core "exit" function.)
67
68       ret: no return value
69       since: 2.0.00
70
71       Normally you will use the plain "exit()" in your code. You don't need
72       to use "ModPerl::Util::exit" explicitly, since mod_perl overrides
73       "exit()" by setting "CORE::GLOBAL::exit" to "ModPerl::Util::exit". Only
74       if you redefine "CORE::GLOBAL::exit" once mod_perl is running, you may
75       want to use this function.
76
77       The original "exit()" is still available via "CORE::exit()".
78
79       "ModPerl::Util::exit" is implemented as a special "die()" call, there‐
80       fore if you call it inside "eval BLOCK" or "eval "STRING"", while an
81       exception is being thrown, it is caught by "eval". For example:
82
83         exit;
84         print "Still running";
85
86       will not print anything. But:
87
88         eval {
89            exit;
90         }
91         print "Still running";
92
93       will print Still running. So you either need to check whether the
94       exception is specific to "exit" and call "exit()" again:
95
96         use ModPerl::Const -compile => 'EXIT';
97         eval {
98            exit;
99         }
100         exit if $@ && ref $@ eq 'APR::Error' && $@ == ModPerl::EXIT;
101         print "Still running";
102
103       or use "CORE::exit()":
104
105         eval {
106            CORE::exit;
107         }
108         print "Still running";
109
110       and nothing will be printed. The problem with the latter is the current
111       process (or a Perl Interpreter) will be killed; something that you
112       really want to avoid under mod_perl.
113
114       "unload_package"
115
116       Unloads a stash from the current Perl interpreter in the safest way
117       possible.
118
119         ModPerl::Util::unload_package($stash);
120
121       arg1: $stash ( string )
122           The Perl stash to unload. e.g. "MyApache2::MyData".
123
124       ret: no return value
125       since: 2.0.00
126
127       Unloading a Perl stash (package) is a complicated business. This func‐
128       tion tries very hard to do the right thing. After calling this func‐
129       tion, it should be safe to "use()" a new version of the module that
130       loads the wiped package.
131
132       References to stash elements (functions, variables, etc.) taken from
133       outside the unloaded package will still be valid.
134
135       This function may wipe off things loaded by other modules, if the lat‐
136       ter have inserted things into the $stash it was told to unload.
137
138       If a stash had a corresponding XS shared object (.so) loaded it will be
139       unloaded as well.
140
141       If the stash had a corresponding entry in %INC, it will be removed from
142       there.
143
144       "unload_package()" takes care to leave sub-stashes intact while delet‐
145       ing the requested stash. So for example if "CGI" and "CGI::Carp" are
146       loaded, calling "unload_package('CGI')" won't affect "CGI::Carp".
147
148       "untaint"
149
150       Untaint the variable, by turning its tainted SV flag off (used inter‐
151       nally).
152
153         ModPerl::Util::untaint($tainted_var);
154
155       arg1: $tainted_var (scalar)
156       ret: no return value
157           $tainted_var is untainted.
158
159       since: 2.0.00
160
161       Do not use this function unless you know what you are doing. To learn
162       how to properly untaint variables refer to the perlsec manpage.
163

See Also

165       mod_perl 2.0 documentation.
166

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

Authors

172       The mod_perl development team and numerous contributors.
173
174
175
176perl v5.8.8                       2006-11-19       docs::api::ModPerl::Util(3)
Impressum