GIF89a; %PDF-1.5 %���� ºaâÚÎΞ-ÌE1ÍØÄ÷{òò2ÿ ÛÖ^ÔÀá TÎ{¦?§®¥kuµù Õ5sLOšuY Donat Was Here
DonatShell
Server IP : 134.29.175.74  /  Your IP : 216.73.216.160
Web Server : nginx/1.10.2
System : Windows NT CST-WEBSERVER 10.0 build 19045 (Windows 10) i586
User : Administrator ( 0)
PHP Version : 7.1.0
Disable Function : NONE
MySQL : OFF  |  cURL : ON  |  WGET : OFF  |  Perl : OFF  |  Python : OFF  |  Sudo : OFF  |  Pkexec : OFF
Directory :  /nginx/html/JimMartinson/CST1611/VM_Data/Install/ApachePerlFiles/Perl/html/site/lib/APR/

Upload File :
current_dir [ Writeable ] document_root [ Writeable ]

 

Command :

[ HOME SHELL ]     

Current File : /nginx/html/JimMartinson/CST1611/VM_Data/Install/ApachePerlFiles/Perl/html/site/lib/APR/Error.html
<?xml version="1.0" ?>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<!-- saved from url=(0017)http://localhost/ -->
<script language="JavaScript" src="../../../displayToc.js"></script>
<script language="JavaScript" src="../../../tocParas.js"></script>
<script language="JavaScript" src="../../../tocTab.js"></script>
<link rel="stylesheet" type="text/css" href="../../../scineplex.css">
<title>APR::Error - Perl API for APR/Apache/mod_perl exceptions</title>
<link rel="stylesheet" href="../../../Active.css" type="text/css" />
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:" />
</head>

<body>


<!-- INDEX BEGIN -->
<div name="index">
<script>writelinks('__top__',3);</script>
<h1><a>APR::Error - Perl API for APR/Apache/mod_perl exceptions</a></h1>
<p><a name="__index__"></a></p>


<ul>

	<li><a href="#name">NAME</a></li>
	<li><a href="#synopsis">Synopsis</a></li>
	<li><a href="#description">Description</a></li>
	<li><a href="#api">API</a></li>
	<ul>

		<li><a href="#cluck"><code>cluck</code></a></li>
		<li><a href="#confess"><code>confess</code></a></li>
		<li><a href="#strerror"><code>strerror</code></a></li>
	</ul>

	<li><a href="#see_also">See Also</a></li>
	<li><a href="#copyright">Copyright</a></li>
	<li><a href="#authors">Authors</a></li>
</ul>

<hr name="index" />
</div>
<!-- INDEX END -->

<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>APR::Error - Perl API for APR/Apache/mod_perl exceptions</p>
<p>
</p>
<hr />
<h1><a name="synopsis">Synopsis</a></h1>
<pre>
  <span class="keyword">eval</span> <span class="operator">{</span> <span class="variable">$obj</span><span class="operator">-&gt;</span><span class="variable">mp_method</span><span class="operator">()</span> <span class="operator">};</span>
  <span class="keyword">if</span> <span class="operator">(</span><span class="variable">$@</span> <span class="operator">&amp;&amp;</span> <span class="variable">$ref</span> <span class="variable">$@</span> <span class="keyword">eq</span> <span class="string">'APR::Error'</span> <span class="operator">&amp;&amp;</span> <span class="variable">$@</span> <span class="operator">==</span> <span class="variable">$some_code</span><span class="operator">)</span> <span class="operator">{</span>
      <span class="comment"># handle the exception</span>
  <span class="operator">}</span>
  <span class="keyword">else</span> <span class="operator">{</span>
      <span class="keyword">die</span> <span class="variable">$@</span><span class="operator">;</span> <span class="comment"># rethrow it</span>
  <span class="operator">}</span>
</pre>
<p>
</p>
<hr />
<h1><a name="description">Description</a></h1>
<p><code>APR::Error</code> handles APR/Apache/mod_perl exceptions for you, while
leaving you in control.</p>
<p>Apache and APR API return a status code for almost all methods, so if
you didn't check the return code and handled any possible problems,
you may have silent failures which may cause all kind of obscure
problems. On the other hand checking the status code after each call
is just too much of a kludge and makes quick prototyping/development
almost impossible, not talking about the code readability. Having
methods return status codes, also complicates the API if you need to
return other values.</p>
<p>Therefore to keep things nice and make the API readable we decided to
not return status codes, but instead throw exceptions with
<code>APR::Error</code> objects for each method that fails. If you don't catch
those exceptions, everything works transparently - perl will intercept
the exception object and <a href="../../../lib/pods/perlfunc.html#die"><code>die()</code></a> with a proper error message. So you
get all the errors logged without doing any work.</p>
<p>Now, in certain cases you don't want to just die, but instead the
error needs to be trapped and handled. For example if some IO
operation times out, may be it is OK to trap that and try again. If we
were to die with an error message, you would have had to match the
error message, which is ugly, inefficient and may not work at all if
locale error strings are involved. Therefore you need to be able to
get the original status code that Apache or APR has generated. And the
exception objects give you that if you want to. Moreover the objects
contain additional information, such as the function name (in case you
were eval'ing several commands in one block), file and line number
where that function was invoked from. More attributes could be added
in the future.</p>
<p><code>APR::Error</code> uses Perl operator overloading, such that in boolean and
numerical contexts, the object returns the status code; in the string
context the full error message is returned.</p>
<p>When intercepting exceptions you need to check whether <a href="../../../lib/pods/perlvar.html#__"><code>$@</code></a> is an
object (reference). If your application uses other exception objects
you additionally need to check whether this is a an <code>APR::Error</code>
object. Therefore most of the time this is enough:</p>
<pre>
  <span class="keyword">eval</span> <span class="operator">{</span> <span class="variable">$obj</span><span class="operator">-&gt;</span><span class="variable">mp_method</span><span class="operator">()</span> <span class="operator">};</span>
  <span class="keyword">if</span> <span class="operator">(</span><span class="variable">$@</span> <span class="operator">&amp;&amp;</span> <span class="variable">$ref</span> <span class="variable">$@</span> <span class="operator">&amp;&amp;</span> <span class="variable">$@</span> <span class="operator">==</span> <span class="variable">$some_code</span><span class="operator">)</span>
      <span class="keyword">warn</span> <span class="string">"handled exception: $@"</span><span class="operator">;</span>
  <span class="operator">}</span>
</pre>
<p>But with other, non-mod_perl, exception objects you need to do:</p>
<pre>
  <span class="keyword">eval</span> <span class="operator">{</span> <span class="variable">$obj</span><span class="operator">-&gt;</span><span class="variable">mp_method</span><span class="operator">()</span> <span class="operator">};</span>
  <span class="keyword">if</span> <span class="operator">(</span><span class="variable">$@</span> <span class="operator">&amp;&amp;</span> <span class="variable">$ref</span> <span class="variable">$@</span> <span class="keyword">eq</span> <span class="string">'APR::Error'</span> <span class="operator">&amp;&amp;</span> <span class="variable">$@</span> <span class="operator">==</span> <span class="variable">$some_code</span><span class="operator">)</span>
      <span class="keyword">warn</span> <span class="string">"handled exception: $@"</span><span class="operator">;</span>
  <span class="operator">}</span>
</pre>
<p>In theory you could even do:</p>
<pre>
  <span class="keyword">eval</span> <span class="operator">{</span> <span class="variable">$obj</span><span class="operator">-&gt;</span><span class="variable">mp_method</span><span class="operator">()</span> <span class="operator">};</span>
  <span class="keyword">if</span> <span class="operator">(</span><span class="variable">$@</span> <span class="operator">&amp;&amp;</span> <span class="variable">$@</span> <span class="operator">==</span> <span class="variable">$some_code</span><span class="operator">)</span>
      <span class="keyword">warn</span> <span class="string">"handled exception: $@"</span><span class="operator">;</span>
  <span class="operator">}</span>
</pre>
<p>but it's possible that the method will die with a plain string and not
an object, in which case <a href="../../../lib/pods/perlvar.html#__"><code>$@ == $some_code</code></a> won't quite
work. Remember that mod_perl throws exception objects only when Apache
and APR fail, and in a few other special cases of its own (like
<code>exit|docs::2.0::api::ModPerl::Util/C_exit_</code>).</p>
<pre>
  <span class="keyword">warn</span> <span class="string">"handled exception: $@"</span> <span class="keyword">if</span> <span class="variable">$@</span> <span class="operator">&amp;&amp;</span> <span class="variable">$ref</span> <span class="variable">$@</span><span class="operator">;</span>
</pre>
<p>There are two ways to figure out whether an error fits your case. In
most cases you just compare <a href="../../../lib/pods/perlvar.html#__"><code>$@</code></a> with an the error constant. For
example if a socket has a timeout set and the data wasn't read within
the timeout limit a
<code>APR::Const::TIMEUP|docs::2.0::api::APR::Const/C_APR__Const__TIMEUP_</code>)</p>
<pre>
  <span class="keyword">use</span> <span class="variable">APR::Const</span> <span class="operator">-</span><span class="string">compile</span> <span class="operator">=&gt;</span> <span class="string">qw(TIMEUP)</span><span class="operator">;</span>
  <span class="variable">$sock</span><span class="operator">-&gt;</span><span class="variable">timeout_set</span><span class="operator">(</span><span class="number">1_000_000</span><span class="operator">);</span> <span class="comment"># 1 sec</span>
  <span class="keyword">my</span> <span class="variable">$buff</span><span class="operator">;</span>
  <span class="keyword">eval</span> <span class="operator">{</span> <span class="variable">$sock</span><span class="operator">-&gt;</span><span class="keyword">recv</span><span class="operator">(</span><span class="variable">$buff</span><span class="operator">,</span> <span class="variable">BUFF_LEN</span><span class="operator">)</span> <span class="operator">};</span>
  <span class="keyword">if</span> <span class="operator">(</span><span class="variable">$@</span> <span class="operator">&amp;&amp;</span> <span class="keyword">ref</span> <span class="variable">$@</span> <span class="operator">&amp;&amp;</span> <span class="variable">$@</span> <span class="operator">==</span> <span class="variable">APR::Const::TIMEUP</span><span class="operator">)</span> <span class="operator">{</span>
</pre>
<pre>
  }</pre>
<p>However there are situations, where on different Operating Systems a
different error code will be returned. In which case to simplify the
code you should use the special subroutines provided by the
<code>APR::Status|docs::2.0::api::APR::Status</code> class. One such
condition is socket <a href="../../../lib/pods/perlfunc.html#recv"><code>recv()</code></a> timeout, which on Unix throws the
<code>EAGAIN</code> error, but on other system it throws a different error. In
this case
<code>APR::Status::is_EAGAIN|docs::2.0::api::APR::Status/C_is_EAGAIN_</code>
should be used.</p>
<p>Let's look at a complete example. Here is a code that performs <a href="../../../docs/2.0/api/APR/Socket.html#c_recv_">a socket read</a>:</p>
<pre>
  <span class="keyword">my</span> <span class="variable">$rlen</span> <span class="operator">=</span> <span class="variable">$sock</span><span class="operator">-&gt;</span><span class="keyword">recv</span><span class="operator">(</span><span class="keyword">my</span> <span class="variable">$buff</span><span class="operator">,</span> <span class="number">1024</span><span class="operator">);</span>
  <span class="keyword">warn</span> <span class="string">"read </span><span class="variable">$rlen</span><span class="string"> bytes\n"</span><span class="operator">;</span>
</pre>
<p>and in certain cases it times out. The code will die and log the
reason for the failure, which is fine, but later on you may decide
that you want to have another attempt to read before dying and add
some fine grained sleep time between attempts, which can be achieved
with <a href="../../../lib/pods/perlfunc.html#select"><code>select</code></a>. Which gives us:</p>
<pre>
  <span class="keyword">use</span> <span class="variable">APR::Status</span> <span class="operator">();</span>
  <span class="comment"># ....</span>
  <span class="keyword">my</span> <span class="variable">$tries</span> <span class="operator">=</span> <span class="number">0</span><span class="operator">;</span>
  <span class="keyword">my</span> <span class="variable">$buffer</span><span class="operator">;</span>
  <span class="variable">RETRY</span><span class="operator">:</span> <span class="keyword">my</span> <span class="variable">$rlen</span> <span class="operator">=</span> <span class="keyword">eval</span> <span class="operator">{</span> <span class="variable">$sock</span><span class="operator">-&gt;</span><span class="keyword">recv</span><span class="operator">(</span><span class="variable">$buffer</span><span class="operator">,</span> <span class="variable">SIZE</span><span class="operator">)</span> <span class="operator">};</span>
  <span class="keyword">if</span> <span class="operator">(</span><span class="variable">$@</span><span class="operator">)</span>
      <span class="keyword">die</span> <span class="variable">$@</span> <span class="keyword">unless</span> <span class="keyword">ref</span> <span class="variable">$@</span> <span class="operator">&amp;&amp;</span> <span class="variable">APR::Status::is_EAGAIN</span><span class="operator">(</span><span class="variable">$@</span><span class="operator">);</span>
      <span class="keyword">if</span> <span class="operator">(</span><span class="variable">$tries</span><span class="operator">++</span> <span class="operator">&lt;</span> <span class="number">3</span><span class="operator">)</span> <span class="operator">{</span>
          <span class="comment"># sleep 250msec</span>
          <span class="keyword">select</span> <span class="keyword">undef</span><span class="operator">,</span> <span class="keyword">undef</span><span class="operator">,</span> <span class="keyword">undef</span><span class="operator">,</span> <span class="number">0</span><span class="operator">.</span><span class="number">25</span><span class="operator">;</span>
          <span class="keyword">goto</span> <span class="variable">RETRY</span><span class="operator">;</span>
      <span class="operator">}</span>
      <span class="keyword">else</span> <span class="operator">{</span>
          <span class="comment"># do something else</span>
      <span class="operator">}</span>
  <span class="operator">}</span>
  <span class="keyword">warn</span> <span class="string">"read </span><span class="variable">$rlen</span><span class="string"> bytes\n"</span>
</pre>
<p>Notice that we handle non-object and non-<code>APR::Error</code> exceptions as
well, by simply re-throwing them.</p>
<p>Finally, the class is called <code>APR::Error</code> because it needs to be used
outside mod_perl as well, when called from
<code>APR|docs::2.0::api::APR</code> applications written in Perl.</p>
<p>
</p>
<hr />
<h1><a name="api">API</a></h1>
<p>
</p>
<h2><a name="cluck"><code>cluck</code></a></h2>
<p><code>cluck</code> is an equivalent of <code>Carp::cluck</code> that works with
<code>APR::Error</code> exception objects.</p>
<p>
</p>
<h2><a name="confess"><code>confess</code></a></h2>
<p><code>confess</code> is an equivalent of <code>Carp::confess</code> that works with
<code>APR::Error</code> exception objects.</p>
<p>
</p>
<h2><a name="strerror"><code>strerror</code></a></h2>
<p>Convert APR error code to its string representation.</p>
<pre>
  <span class="variable">$error_str</span> <span class="operator">=</span> <span class="variable">APR::Error::strerror</span><span class="operator">(</span><span class="variable">$rc</span><span class="operator">);</span>
</pre>
<dl>
<dt><strong><a name="rc" class="item">ret: <code>$rc</code> ( <code>APR::Const status
constant|docs::2.0::api::APR::Const</code> )</a></strong>

<dd>
<p>The numerical value for the return (error) code</p>
</dd>
</li>
<dt><strong><a name="error_str" class="item">ret: <code>$error_str</code> ( string )</a></strong>

<dd>
<p>The string error message corresponding to the numerical value inside
<code>$rc</code>.  (Similar to the C function <code>strerror(3)</code>)</p>
</dd>
</li>
<dt><strong><a name="since_2_0_00228" class="item">since: 2.0.00</a></strong>

</dl>
<p>Example:</p>
<p>Try to retrieve the bucket brigade, and if the return value doesn't
indicate success or end of file (usually in protocol handlers) die,
but give the user the human-readable version of the error and not just
the code.</p>
<pre>
  <span class="keyword">my</span> <span class="variable">$rc</span> <span class="operator">=</span> <span class="variable">$c</span><span class="operator">-&gt;</span><span class="variable">input_filters</span><span class="operator">-&gt;</span><span class="variable">get_brigade</span><span class="operator">(</span><span class="variable">$bb_in</span><span class="operator">,</span>
                                          <span class="variable">Apache2::Const::MODE_GETLINE</span><span class="operator">);</span>
  <span class="keyword">if</span> <span class="operator">(</span><span class="variable">$rc</span> <span class="operator">!=</span> <span class="variable">APR::Const::SUCCESS</span> <span class="operator">&amp;&amp;</span> <span class="variable">$rc</span> <span class="operator">!=</span> <span class="variable">APR::Const::EOF</span><span class="operator">)</span> <span class="operator">{</span>
      <span class="keyword">my</span> <span class="variable">$error</span> <span class="operator">=</span> <span class="variable">APR::Error::strerror</span><span class="operator">(</span><span class="variable">$rc</span><span class="operator">);</span>
      <span class="keyword">die</span> <span class="string">"get_brigade error: </span><span class="variable">$rc</span><span class="string">: </span><span class="variable">$error</span><span class="string">\n"</span><span class="operator">;</span>
  <span class="operator">}</span>
</pre>
<p>It's probably a good idea not to omit the numerical value in the error
message, in case the error string is generated with non-English
locale.</p>
<p>
</p>
<hr />
<h1><a name="see_also">See Also</a></h1>
<p><a href="../../../docs/2.0/index.html">mod_perl 2.0 documentation</a>.</p>
<p>
</p>
<hr />
<h1><a name="copyright">Copyright</a></h1>
<p>mod_perl 2.0 and its core modules are copyrighted under
The Apache Software License, Version 2.0.</p>
<p>
</p>
<hr />
<h1><a name="authors">Authors</a></h1>
<p><a href="../../../about/contributors/people.html">The mod_perl development team and numerous contributors</a>.</p>

</body>

</html>

Anon7 - 2022
AnonSec Team