data.perl5.xml Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of languagesupport Show documentation
Show all versions of languagesupport Show documentation
A library adding code completion and other advanced features for Java, JavaScript, Perl, and other languages to RSyntaxTextArea.
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE api SYSTEM "CompletionXml.dtd">
<!--
perl5.xml - API specification for the Perl 5.
Used by RSyntaxTextArea to provide code completion.
Author: Robert Futrell
Version: 0.1
This file was generated from: C:/dev/rsta/RSTALanguageSupport/data/perl\perl5.txt
on date: 2012-04-29 00:17:32
-->
<api language="Perl">
<environment paramStartChar="(" paramEndChar=")" paramSeparator=", " terminal=";"/>
<completionTypes>
<functionCompletionType type="org.fife.rsta.ac.perl.PerlFunctionCompletion"/>
</completionTypes>
<keywords>
<keyword name="-X" type="function">
<params>
<param name='dirhandle'/>
</params>
<desc><![CDATA[A file test, where X is one of the letters listed below. This unary<br>
operator takes one argument, either a filename, a filehandle, or a dirhandle, <br>
and tests the associated file to see if something is true about it. If the<br>
argument is omitted, tests <code class="inline"><span class="i">$_</span></code>
, except for <code class="inline">-t</code>
, which tests STDIN.<br>
Unless otherwise documented, it returns <code class="inline"><span class="n">1</span></code>
for true and <code class="inline"><span class="q">''</span></code>
for false, or<br>
the undefined value if the file doesn't exist. Despite the funny<br>
names, precedence is the same as any other named unary operator. The<br>
operator may be any of:</p>
<pre class="verbatim"><ol><li> -r File is readable by effective uid/gid.</li><li> -w File is writable by effective uid/gid.</li><li> -x File is executable by effective uid/gid.</li><li> -o File is owned by effective uid.</li><li></li><li> -R File is readable by real uid/gid.</li><li> -W File is writable by real uid/gid.</li><li> -X File is executable by real uid/gid.</li><li> -O File is owned by real uid.</li><li></li><li> -e File exists.</li><li> -z File has zero size (is empty).</li><li> -s File has nonzero size (returns size in bytes).</li><li></li><li> -f File is a plain file.</li><li> -d File is a directory.</li><li> -l File is a symbolic link.</li><li> -p File is a named pipe (FIFO), or Filehandle is a pipe.</li><li> -S File is a socket.</li><li> -b File is a block special file.</li><li> -c File is a character special file.</li><li> -t Filehandle is opened to a tty.</li><li></li><li> -u File has setuid bit set.</li><li> -g File has setgid bit set.</li><li> -k File has sticky bit set.</li><li></li><li> -T File is an ASCII text file (heuristic guess).</li><li> -B File is a "binary" file (opposite of -T).</li><li></li><li> -M Script start time minus file modification time, in days.</li><li> -A Same for access time.</li><li> -C Same for inode change time (Unix, may differ for other platforms)</li></ol></pre><p>Example:</p>
<pre class="verbatim"><ol><li> while <span class="s">(</span><><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/chomp.html">chomp</a><span class="sc">;</span></li><li> <a class="l_k" href="../functions/next.html">next</a> unless -f <span class="i">$_</span><span class="sc">;</span> <span class="c"># ignore specials</span></li><li> <span class="c">#...</span></li><li> <span class="s">}</span></li></ol></pre><p>The interpretation of the file permission operators <code class="inline">-r</code>
, <code class="inline">-R</code>
,<br>
<code class="inline">-w</code>
, <code class="inline">-W</code>
, <code class="inline">-x</code>
, and <code class="inline"><a class="l_k" href="../functions/-X.html">-X</a></code> is by default based solely on the mode<br>
of the file and the uids and gids of the user. There may be other<br>
reasons you can't actually read, write, or execute the file: for<br>
example network filesystem access controls, ACLs (access control lists),<br>
read-only filesystems, and unrecognized executable formats. Note<br>
that the use of these six specific operators to verify if some operation<br>
is possible is usually a mistake, because it may be open to race<br>
conditions.</p>
<p>Also note that, for the superuser on the local filesystems, the <code class="inline">-r</code>
,<br>
<code class="inline">-R</code>
, <code class="inline">-w</code>
, and <code class="inline">-W</code>
tests always return 1, and <code class="inline">-x</code>
and <code class="inline"><a class="l_k" href="../functions/-X.html">-X</a></code> return 1<br>
if any execute bit is set in the mode. Scripts run by the superuser<br>
may thus need to do a stat() to determine the actual mode of the file,<br>
or temporarily set their effective uid to something else.</p>
<p>If you are using ACLs, there is a pragma called <code class="inline"><span class="w">filetest</span></code>
that may<br>
produce more accurate results than the bare stat() mode bits.<br>
When under the <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">filetest</span> <span class="q">'access'</span></code>
the above-mentioned filetests<br>
will test whether the permission can (not) be granted using the<br>
access() family of system calls. Also note that the <code class="inline">-x</code>
and <code class="inline"><a class="l_k" href="../functions/-X.html">-X</a></code> may<br>
under this pragma return true even if there are no execute permission<br>
bits set (nor any extra execute permission ACLs). This strangeness is<br>
due to the underlying system calls' definitions. Note also that, due to<br>
the implementation of <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">filetest</span> <span class="q">'access'</span></code>
, the <code class="inline"><span class="w">_</span></code>
special<br>
filehandle won't cache the results of the file tests when this pragma is<br>
in effect. Read the documentation for the <code class="inline"><span class="w">filetest</span></code>
pragma for more<br>
information.</p>
<p>Note that <code class="inline">-s/a/b/</code> does not do a negated substitution. Saying<br>
<code class="inline">-<a class="l_k" href="../functions/exp.html">exp</a><span class="s">(</span><span class="i">$foo</span><span class="s">)</span></code>
still works as expected, however--only single letters<br>
following a minus are interpreted as file tests.</p>
<p>The <code class="inline">-T</code>
and <code class="inline">-B</code>
switches work as follows. The first block or so of the<br>
file is examined for odd characters such as strange control codes or<br>
characters with the high bit set. If too many strange characters (>30%)<br>
are found, it's a <code class="inline">-B</code>
file; otherwise it's a <code class="inline">-T</code>
file. Also, any file<br>
containing null in the first block is considered a binary file. If <code class="inline">-T</code>
<br>
or <code class="inline">-B</code>
is used on a filehandle, the current IO buffer is examined<br>
rather than the first block. Both <code class="inline">-T</code>
and <code class="inline">-B</code>
return true on a null<br>
file, or a file at EOF when testing a filehandle. Because you have to<br>
read a file to do the <code class="inline">-T</code>
test, on most occasions you want to use a <code class="inline">-f</code>
<br>
against the file first, as in <code class="inline"><a class="l_k" href="../functions/next.html">next</a> unless -f <span class="i">$file</span> && -T <span class="i">$file</span></code>
.</p>
<p>If any of the file tests (or either the <code class="inline"><a class="l_k" href="../functions/stat.html">stat</a></code> or <code class="inline"><a class="l_k" href="../functions/lstat.html">lstat</a></code> operators) are given<br>
the special filehandle consisting of a solitary underline, then the stat<br>
structure of the previous file test (or stat operator) is used, saving<br>
a system call. (This doesn't work with <code class="inline">-t</code>
, and you need to remember<br>
that lstat() and <code class="inline">-l</code>
will leave values in the stat structure for the<br>
symbolic link, not the real file.) (Also, if the stat buffer was filled by<br>
an <code class="inline"><a class="l_k" href="../functions/lstat.html">lstat</a></code> call, <code class="inline">-T</code>
and <code class="inline">-B</code>
will reset it with the results of <code class="inline"><a class="l_k" href="../functions/stat.html">stat</a> <span class="w">_</span></code>
).<br>
Example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Can do.\n"</span> if -r <span class="i">$a</span> || -w <span class="i">_</span> || -x <span class="i">_</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Readable\n"</span> if -r <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Writable\n"</span> if -w <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Executable\n"</span> if -x <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Setuid\n"</span> if -u <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Setgid\n"</span> if -g <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Sticky\n"</span> if -k <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Text\n"</span> if -T <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Binary\n"</span> if -B <span class="i">_</span><span class="sc">;</span></li></ol></pre><p>As of Perl 5.9.1, as a form of purely syntactic sugar, you can stack file<br>
test operators, in a way that <code class="inline">-f -w -x <span class="i">$file</span></code>
is equivalent to<br>
<code class="inline">-x <span class="i">$file</span> && -w <span class="i">_</span> && -f <span class="i">_</span></code>
. (This is only syntax fancy: if you use<br>
the return value of <code class="inline">-f <span class="i">$file</span></code>
as an argument to another filetest<br>
operator, no special magic will happen.)]]></desc>
</keyword>
<keyword name="-X" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[A file test, where X is one of the letters listed below. This unary<br>
operator takes one argument, either a filename, a filehandle, or a dirhandle, <br>
and tests the associated file to see if something is true about it. If the<br>
argument is omitted, tests <code class="inline"><span class="i">$_</span></code>
, except for <code class="inline">-t</code>
, which tests STDIN.<br>
Unless otherwise documented, it returns <code class="inline"><span class="n">1</span></code>
for true and <code class="inline"><span class="q">''</span></code>
for false, or<br>
the undefined value if the file doesn't exist. Despite the funny<br>
names, precedence is the same as any other named unary operator. The<br>
operator may be any of:</p>
<pre class="verbatim"><ol><li> -r File is readable by effective uid/gid.</li><li> -w File is writable by effective uid/gid.</li><li> -x File is executable by effective uid/gid.</li><li> -o File is owned by effective uid.</li><li></li><li> -R File is readable by real uid/gid.</li><li> -W File is writable by real uid/gid.</li><li> -X File is executable by real uid/gid.</li><li> -O File is owned by real uid.</li><li></li><li> -e File exists.</li><li> -z File has zero size (is empty).</li><li> -s File has nonzero size (returns size in bytes).</li><li></li><li> -f File is a plain file.</li><li> -d File is a directory.</li><li> -l File is a symbolic link.</li><li> -p File is a named pipe (FIFO), or Filehandle is a pipe.</li><li> -S File is a socket.</li><li> -b File is a block special file.</li><li> -c File is a character special file.</li><li> -t Filehandle is opened to a tty.</li><li></li><li> -u File has setuid bit set.</li><li> -g File has setgid bit set.</li><li> -k File has sticky bit set.</li><li></li><li> -T File is an ASCII text file (heuristic guess).</li><li> -B File is a "binary" file (opposite of -T).</li><li></li><li> -M Script start time minus file modification time, in days.</li><li> -A Same for access time.</li><li> -C Same for inode change time (Unix, may differ for other platforms)</li></ol></pre><p>Example:</p>
<pre class="verbatim"><ol><li> while <span class="s">(</span><><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/chomp.html">chomp</a><span class="sc">;</span></li><li> <a class="l_k" href="../functions/next.html">next</a> unless -f <span class="i">$_</span><span class="sc">;</span> <span class="c"># ignore specials</span></li><li> <span class="c">#...</span></li><li> <span class="s">}</span></li></ol></pre><p>The interpretation of the file permission operators <code class="inline">-r</code>
, <code class="inline">-R</code>
,<br>
<code class="inline">-w</code>
, <code class="inline">-W</code>
, <code class="inline">-x</code>
, and <code class="inline"><a class="l_k" href="../functions/-X.html">-X</a></code> is by default based solely on the mode<br>
of the file and the uids and gids of the user. There may be other<br>
reasons you can't actually read, write, or execute the file: for<br>
example network filesystem access controls, ACLs (access control lists),<br>
read-only filesystems, and unrecognized executable formats. Note<br>
that the use of these six specific operators to verify if some operation<br>
is possible is usually a mistake, because it may be open to race<br>
conditions.</p>
<p>Also note that, for the superuser on the local filesystems, the <code class="inline">-r</code>
,<br>
<code class="inline">-R</code>
, <code class="inline">-w</code>
, and <code class="inline">-W</code>
tests always return 1, and <code class="inline">-x</code>
and <code class="inline"><a class="l_k" href="../functions/-X.html">-X</a></code> return 1<br>
if any execute bit is set in the mode. Scripts run by the superuser<br>
may thus need to do a stat() to determine the actual mode of the file,<br>
or temporarily set their effective uid to something else.</p>
<p>If you are using ACLs, there is a pragma called <code class="inline"><span class="w">filetest</span></code>
that may<br>
produce more accurate results than the bare stat() mode bits.<br>
When under the <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">filetest</span> <span class="q">'access'</span></code>
the above-mentioned filetests<br>
will test whether the permission can (not) be granted using the<br>
access() family of system calls. Also note that the <code class="inline">-x</code>
and <code class="inline"><a class="l_k" href="../functions/-X.html">-X</a></code> may<br>
under this pragma return true even if there are no execute permission<br>
bits set (nor any extra execute permission ACLs). This strangeness is<br>
due to the underlying system calls' definitions. Note also that, due to<br>
the implementation of <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">filetest</span> <span class="q">'access'</span></code>
, the <code class="inline"><span class="w">_</span></code>
special<br>
filehandle won't cache the results of the file tests when this pragma is<br>
in effect. Read the documentation for the <code class="inline"><span class="w">filetest</span></code>
pragma for more<br>
information.</p>
<p>Note that <code class="inline">-s/a/b/</code> does not do a negated substitution. Saying<br>
<code class="inline">-<a class="l_k" href="../functions/exp.html">exp</a><span class="s">(</span><span class="i">$foo</span><span class="s">)</span></code>
still works as expected, however--only single letters<br>
following a minus are interpreted as file tests.</p>
<p>The <code class="inline">-T</code>
and <code class="inline">-B</code>
switches work as follows. The first block or so of the<br>
file is examined for odd characters such as strange control codes or<br>
characters with the high bit set. If too many strange characters (>30%)<br>
are found, it's a <code class="inline">-B</code>
file; otherwise it's a <code class="inline">-T</code>
file. Also, any file<br>
containing null in the first block is considered a binary file. If <code class="inline">-T</code>
<br>
or <code class="inline">-B</code>
is used on a filehandle, the current IO buffer is examined<br>
rather than the first block. Both <code class="inline">-T</code>
and <code class="inline">-B</code>
return true on a null<br>
file, or a file at EOF when testing a filehandle. Because you have to<br>
read a file to do the <code class="inline">-T</code>
test, on most occasions you want to use a <code class="inline">-f</code>
<br>
against the file first, as in <code class="inline"><a class="l_k" href="../functions/next.html">next</a> unless -f <span class="i">$file</span> && -T <span class="i">$file</span></code>
.</p>
<p>If any of the file tests (or either the <code class="inline"><a class="l_k" href="../functions/stat.html">stat</a></code> or <code class="inline"><a class="l_k" href="../functions/lstat.html">lstat</a></code> operators) are given<br>
the special filehandle consisting of a solitary underline, then the stat<br>
structure of the previous file test (or stat operator) is used, saving<br>
a system call. (This doesn't work with <code class="inline">-t</code>
, and you need to remember<br>
that lstat() and <code class="inline">-l</code>
will leave values in the stat structure for the<br>
symbolic link, not the real file.) (Also, if the stat buffer was filled by<br>
an <code class="inline"><a class="l_k" href="../functions/lstat.html">lstat</a></code> call, <code class="inline">-T</code>
and <code class="inline">-B</code>
will reset it with the results of <code class="inline"><a class="l_k" href="../functions/stat.html">stat</a> <span class="w">_</span></code>
).<br>
Example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Can do.\n"</span> if -r <span class="i">$a</span> || -w <span class="i">_</span> || -x <span class="i">_</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Readable\n"</span> if -r <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Writable\n"</span> if -w <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Executable\n"</span> if -x <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Setuid\n"</span> if -u <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Setgid\n"</span> if -g <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Sticky\n"</span> if -k <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Text\n"</span> if -T <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Binary\n"</span> if -B <span class="i">_</span><span class="sc">;</span></li></ol></pre><p>As of Perl 5.9.1, as a form of purely syntactic sugar, you can stack file<br>
test operators, in a way that <code class="inline">-f -w -x <span class="i">$file</span></code>
is equivalent to<br>
<code class="inline">-x <span class="i">$file</span> && -w <span class="i">_</span> && -f <span class="i">_</span></code>
. (This is only syntax fancy: if you use<br>
the return value of <code class="inline">-f <span class="i">$file</span></code>
as an argument to another filetest<br>
operator, no special magic will happen.)]]></desc>
</keyword>
<keyword name="-X" type="function">
<params>
<param name='filehandle'/>
</params>
<desc><![CDATA[A file test, where X is one of the letters listed below. This unary<br>
operator takes one argument, either a filename, a filehandle, or a dirhandle, <br>
and tests the associated file to see if something is true about it. If the<br>
argument is omitted, tests <code class="inline"><span class="i">$_</span></code>
, except for <code class="inline">-t</code>
, which tests STDIN.<br>
Unless otherwise documented, it returns <code class="inline"><span class="n">1</span></code>
for true and <code class="inline"><span class="q">''</span></code>
for false, or<br>
the undefined value if the file doesn't exist. Despite the funny<br>
names, precedence is the same as any other named unary operator. The<br>
operator may be any of:</p>
<pre class="verbatim"><ol><li> -r File is readable by effective uid/gid.</li><li> -w File is writable by effective uid/gid.</li><li> -x File is executable by effective uid/gid.</li><li> -o File is owned by effective uid.</li><li></li><li> -R File is readable by real uid/gid.</li><li> -W File is writable by real uid/gid.</li><li> -X File is executable by real uid/gid.</li><li> -O File is owned by real uid.</li><li></li><li> -e File exists.</li><li> -z File has zero size (is empty).</li><li> -s File has nonzero size (returns size in bytes).</li><li></li><li> -f File is a plain file.</li><li> -d File is a directory.</li><li> -l File is a symbolic link.</li><li> -p File is a named pipe (FIFO), or Filehandle is a pipe.</li><li> -S File is a socket.</li><li> -b File is a block special file.</li><li> -c File is a character special file.</li><li> -t Filehandle is opened to a tty.</li><li></li><li> -u File has setuid bit set.</li><li> -g File has setgid bit set.</li><li> -k File has sticky bit set.</li><li></li><li> -T File is an ASCII text file (heuristic guess).</li><li> -B File is a "binary" file (opposite of -T).</li><li></li><li> -M Script start time minus file modification time, in days.</li><li> -A Same for access time.</li><li> -C Same for inode change time (Unix, may differ for other platforms)</li></ol></pre><p>Example:</p>
<pre class="verbatim"><ol><li> while <span class="s">(</span><><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/chomp.html">chomp</a><span class="sc">;</span></li><li> <a class="l_k" href="../functions/next.html">next</a> unless -f <span class="i">$_</span><span class="sc">;</span> <span class="c"># ignore specials</span></li><li> <span class="c">#...</span></li><li> <span class="s">}</span></li></ol></pre><p>The interpretation of the file permission operators <code class="inline">-r</code>
, <code class="inline">-R</code>
,<br>
<code class="inline">-w</code>
, <code class="inline">-W</code>
, <code class="inline">-x</code>
, and <code class="inline"><a class="l_k" href="../functions/-X.html">-X</a></code> is by default based solely on the mode<br>
of the file and the uids and gids of the user. There may be other<br>
reasons you can't actually read, write, or execute the file: for<br>
example network filesystem access controls, ACLs (access control lists),<br>
read-only filesystems, and unrecognized executable formats. Note<br>
that the use of these six specific operators to verify if some operation<br>
is possible is usually a mistake, because it may be open to race<br>
conditions.</p>
<p>Also note that, for the superuser on the local filesystems, the <code class="inline">-r</code>
,<br>
<code class="inline">-R</code>
, <code class="inline">-w</code>
, and <code class="inline">-W</code>
tests always return 1, and <code class="inline">-x</code>
and <code class="inline"><a class="l_k" href="../functions/-X.html">-X</a></code> return 1<br>
if any execute bit is set in the mode. Scripts run by the superuser<br>
may thus need to do a stat() to determine the actual mode of the file,<br>
or temporarily set their effective uid to something else.</p>
<p>If you are using ACLs, there is a pragma called <code class="inline"><span class="w">filetest</span></code>
that may<br>
produce more accurate results than the bare stat() mode bits.<br>
When under the <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">filetest</span> <span class="q">'access'</span></code>
the above-mentioned filetests<br>
will test whether the permission can (not) be granted using the<br>
access() family of system calls. Also note that the <code class="inline">-x</code>
and <code class="inline"><a class="l_k" href="../functions/-X.html">-X</a></code> may<br>
under this pragma return true even if there are no execute permission<br>
bits set (nor any extra execute permission ACLs). This strangeness is<br>
due to the underlying system calls' definitions. Note also that, due to<br>
the implementation of <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">filetest</span> <span class="q">'access'</span></code>
, the <code class="inline"><span class="w">_</span></code>
special<br>
filehandle won't cache the results of the file tests when this pragma is<br>
in effect. Read the documentation for the <code class="inline"><span class="w">filetest</span></code>
pragma for more<br>
information.</p>
<p>Note that <code class="inline">-s/a/b/</code> does not do a negated substitution. Saying<br>
<code class="inline">-<a class="l_k" href="../functions/exp.html">exp</a><span class="s">(</span><span class="i">$foo</span><span class="s">)</span></code>
still works as expected, however--only single letters<br>
following a minus are interpreted as file tests.</p>
<p>The <code class="inline">-T</code>
and <code class="inline">-B</code>
switches work as follows. The first block or so of the<br>
file is examined for odd characters such as strange control codes or<br>
characters with the high bit set. If too many strange characters (>30%)<br>
are found, it's a <code class="inline">-B</code>
file; otherwise it's a <code class="inline">-T</code>
file. Also, any file<br>
containing null in the first block is considered a binary file. If <code class="inline">-T</code>
<br>
or <code class="inline">-B</code>
is used on a filehandle, the current IO buffer is examined<br>
rather than the first block. Both <code class="inline">-T</code>
and <code class="inline">-B</code>
return true on a null<br>
file, or a file at EOF when testing a filehandle. Because you have to<br>
read a file to do the <code class="inline">-T</code>
test, on most occasions you want to use a <code class="inline">-f</code>
<br>
against the file first, as in <code class="inline"><a class="l_k" href="../functions/next.html">next</a> unless -f <span class="i">$file</span> && -T <span class="i">$file</span></code>
.</p>
<p>If any of the file tests (or either the <code class="inline"><a class="l_k" href="../functions/stat.html">stat</a></code> or <code class="inline"><a class="l_k" href="../functions/lstat.html">lstat</a></code> operators) are given<br>
the special filehandle consisting of a solitary underline, then the stat<br>
structure of the previous file test (or stat operator) is used, saving<br>
a system call. (This doesn't work with <code class="inline">-t</code>
, and you need to remember<br>
that lstat() and <code class="inline">-l</code>
will leave values in the stat structure for the<br>
symbolic link, not the real file.) (Also, if the stat buffer was filled by<br>
an <code class="inline"><a class="l_k" href="../functions/lstat.html">lstat</a></code> call, <code class="inline">-T</code>
and <code class="inline">-B</code>
will reset it with the results of <code class="inline"><a class="l_k" href="../functions/stat.html">stat</a> <span class="w">_</span></code>
).<br>
Example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Can do.\n"</span> if -r <span class="i">$a</span> || -w <span class="i">_</span> || -x <span class="i">_</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Readable\n"</span> if -r <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Writable\n"</span> if -w <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Executable\n"</span> if -x <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Setuid\n"</span> if -u <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Setgid\n"</span> if -g <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Sticky\n"</span> if -k <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Text\n"</span> if -T <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Binary\n"</span> if -B <span class="i">_</span><span class="sc">;</span></li></ol></pre><p>As of Perl 5.9.1, as a form of purely syntactic sugar, you can stack file<br>
test operators, in a way that <code class="inline">-f -w -x <span class="i">$file</span></code>
is equivalent to<br>
<code class="inline">-x <span class="i">$file</span> && -w <span class="i">_</span> && -f <span class="i">_</span></code>
. (This is only syntax fancy: if you use<br>
the return value of <code class="inline">-f <span class="i">$file</span></code>
as an argument to another filetest<br>
operator, no special magic will happen.)]]></desc>
</keyword>
<keyword name="-X" type="function">
<params>
</params>
<desc><![CDATA[A file test, where X is one of the letters listed below. This unary<br>
operator takes one argument, either a filename, a filehandle, or a dirhandle, <br>
and tests the associated file to see if something is true about it. If the<br>
argument is omitted, tests <code class="inline"><span class="i">$_</span></code>
, except for <code class="inline">-t</code>
, which tests STDIN.<br>
Unless otherwise documented, it returns <code class="inline"><span class="n">1</span></code>
for true and <code class="inline"><span class="q">''</span></code>
for false, or<br>
the undefined value if the file doesn't exist. Despite the funny<br>
names, precedence is the same as any other named unary operator. The<br>
operator may be any of:</p>
<pre class="verbatim"><ol><li> -r File is readable by effective uid/gid.</li><li> -w File is writable by effective uid/gid.</li><li> -x File is executable by effective uid/gid.</li><li> -o File is owned by effective uid.</li><li></li><li> -R File is readable by real uid/gid.</li><li> -W File is writable by real uid/gid.</li><li> -X File is executable by real uid/gid.</li><li> -O File is owned by real uid.</li><li></li><li> -e File exists.</li><li> -z File has zero size (is empty).</li><li> -s File has nonzero size (returns size in bytes).</li><li></li><li> -f File is a plain file.</li><li> -d File is a directory.</li><li> -l File is a symbolic link.</li><li> -p File is a named pipe (FIFO), or Filehandle is a pipe.</li><li> -S File is a socket.</li><li> -b File is a block special file.</li><li> -c File is a character special file.</li><li> -t Filehandle is opened to a tty.</li><li></li><li> -u File has setuid bit set.</li><li> -g File has setgid bit set.</li><li> -k File has sticky bit set.</li><li></li><li> -T File is an ASCII text file (heuristic guess).</li><li> -B File is a "binary" file (opposite of -T).</li><li></li><li> -M Script start time minus file modification time, in days.</li><li> -A Same for access time.</li><li> -C Same for inode change time (Unix, may differ for other platforms)</li></ol></pre><p>Example:</p>
<pre class="verbatim"><ol><li> while <span class="s">(</span><><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/chomp.html">chomp</a><span class="sc">;</span></li><li> <a class="l_k" href="../functions/next.html">next</a> unless -f <span class="i">$_</span><span class="sc">;</span> <span class="c"># ignore specials</span></li><li> <span class="c">#...</span></li><li> <span class="s">}</span></li></ol></pre><p>The interpretation of the file permission operators <code class="inline">-r</code>
, <code class="inline">-R</code>
,<br>
<code class="inline">-w</code>
, <code class="inline">-W</code>
, <code class="inline">-x</code>
, and <code class="inline"><a class="l_k" href="../functions/-X.html">-X</a></code> is by default based solely on the mode<br>
of the file and the uids and gids of the user. There may be other<br>
reasons you can't actually read, write, or execute the file: for<br>
example network filesystem access controls, ACLs (access control lists),<br>
read-only filesystems, and unrecognized executable formats. Note<br>
that the use of these six specific operators to verify if some operation<br>
is possible is usually a mistake, because it may be open to race<br>
conditions.</p>
<p>Also note that, for the superuser on the local filesystems, the <code class="inline">-r</code>
,<br>
<code class="inline">-R</code>
, <code class="inline">-w</code>
, and <code class="inline">-W</code>
tests always return 1, and <code class="inline">-x</code>
and <code class="inline"><a class="l_k" href="../functions/-X.html">-X</a></code> return 1<br>
if any execute bit is set in the mode. Scripts run by the superuser<br>
may thus need to do a stat() to determine the actual mode of the file,<br>
or temporarily set their effective uid to something else.</p>
<p>If you are using ACLs, there is a pragma called <code class="inline"><span class="w">filetest</span></code>
that may<br>
produce more accurate results than the bare stat() mode bits.<br>
When under the <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">filetest</span> <span class="q">'access'</span></code>
the above-mentioned filetests<br>
will test whether the permission can (not) be granted using the<br>
access() family of system calls. Also note that the <code class="inline">-x</code>
and <code class="inline"><a class="l_k" href="../functions/-X.html">-X</a></code> may<br>
under this pragma return true even if there are no execute permission<br>
bits set (nor any extra execute permission ACLs). This strangeness is<br>
due to the underlying system calls' definitions. Note also that, due to<br>
the implementation of <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">filetest</span> <span class="q">'access'</span></code>
, the <code class="inline"><span class="w">_</span></code>
special<br>
filehandle won't cache the results of the file tests when this pragma is<br>
in effect. Read the documentation for the <code class="inline"><span class="w">filetest</span></code>
pragma for more<br>
information.</p>
<p>Note that <code class="inline">-s/a/b/</code> does not do a negated substitution. Saying<br>
<code class="inline">-<a class="l_k" href="../functions/exp.html">exp</a><span class="s">(</span><span class="i">$foo</span><span class="s">)</span></code>
still works as expected, however--only single letters<br>
following a minus are interpreted as file tests.</p>
<p>The <code class="inline">-T</code>
and <code class="inline">-B</code>
switches work as follows. The first block or so of the<br>
file is examined for odd characters such as strange control codes or<br>
characters with the high bit set. If too many strange characters (>30%)<br>
are found, it's a <code class="inline">-B</code>
file; otherwise it's a <code class="inline">-T</code>
file. Also, any file<br>
containing null in the first block is considered a binary file. If <code class="inline">-T</code>
<br>
or <code class="inline">-B</code>
is used on a filehandle, the current IO buffer is examined<br>
rather than the first block. Both <code class="inline">-T</code>
and <code class="inline">-B</code>
return true on a null<br>
file, or a file at EOF when testing a filehandle. Because you have to<br>
read a file to do the <code class="inline">-T</code>
test, on most occasions you want to use a <code class="inline">-f</code>
<br>
against the file first, as in <code class="inline"><a class="l_k" href="../functions/next.html">next</a> unless -f <span class="i">$file</span> && -T <span class="i">$file</span></code>
.</p>
<p>If any of the file tests (or either the <code class="inline"><a class="l_k" href="../functions/stat.html">stat</a></code> or <code class="inline"><a class="l_k" href="../functions/lstat.html">lstat</a></code> operators) are given<br>
the special filehandle consisting of a solitary underline, then the stat<br>
structure of the previous file test (or stat operator) is used, saving<br>
a system call. (This doesn't work with <code class="inline">-t</code>
, and you need to remember<br>
that lstat() and <code class="inline">-l</code>
will leave values in the stat structure for the<br>
symbolic link, not the real file.) (Also, if the stat buffer was filled by<br>
an <code class="inline"><a class="l_k" href="../functions/lstat.html">lstat</a></code> call, <code class="inline">-T</code>
and <code class="inline">-B</code>
will reset it with the results of <code class="inline"><a class="l_k" href="../functions/stat.html">stat</a> <span class="w">_</span></code>
).<br>
Example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Can do.\n"</span> if -r <span class="i">$a</span> || -w <span class="i">_</span> || -x <span class="i">_</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Readable\n"</span> if -r <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Writable\n"</span> if -w <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Executable\n"</span> if -x <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Setuid\n"</span> if -u <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Setgid\n"</span> if -g <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Sticky\n"</span> if -k <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Text\n"</span> if -T <span class="i">_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Binary\n"</span> if -B <span class="i">_</span><span class="sc">;</span></li></ol></pre><p>As of Perl 5.9.1, as a form of purely syntactic sugar, you can stack file<br>
test operators, in a way that <code class="inline">-f -w -x <span class="i">$file</span></code>
is equivalent to<br>
<code class="inline">-x <span class="i">$file</span> && -w <span class="i">_</span> && -f <span class="i">_</span></code>
. (This is only syntax fancy: if you use<br>
the return value of <code class="inline">-f <span class="i">$file</span></code>
as an argument to another filetest<br>
operator, no special magic will happen.)]]></desc>
</keyword>
<keyword name="abs" type="function">
<params>
<param name='value'/>
</params>
<desc><![CDATA[Returns the absolute value of its argument.<br>
If VALUE is omitted, uses <code class="inline"><span class="i">$_</span></code>
.]]></desc>
</keyword>
<keyword name="abs" type="function">
<params>
</params>
<desc><![CDATA[Returns the absolute value of its argument.<br>
If VALUE is omitted, uses <code class="inline"><span class="i">$_</span></code>
.]]></desc>
</keyword>
<keyword name="accept" type="function">
<params>
<param name='newsocket'/>
<param name='genericsocket'/>
</params>
<desc><![CDATA[Accepts an incoming socket connect, just as the accept(2) system call<br>
does. Returns the packed address if it succeeded, false otherwise.<br>
See the example in <a href="../perlipc.html#Sockets%3a-Client%2fServer-Communication">"Sockets: Client/Server Communication" in perlipc</a>.</p>
<p>On systems that support a close-on-exec flag on files, the flag will<br>
be set for the newly opened file descriptor, as determined by the<br>
value of $^F. See <a href="../perlvar.html#%24%5eF">"$^F" in perlvar</a>.]]></desc>
</keyword>
<keyword name="alarm" type="function">
<params>
<param name='seconds'/>
</params>
<desc><![CDATA[Arranges to have a SIGALRM delivered to this process after the<br>
specified number of wallclock seconds has elapsed. If SECONDS is not<br>
specified, the value stored in <code class="inline"><span class="i">$_</span></code>
is used. (On some machines,<br>
unfortunately, the elapsed time may be up to one second less or more<br>
than you specified because of how seconds are counted, and process<br>
scheduling may delay the delivery of the signal even further.)</p>
<p>Only one timer may be counting at once. Each call disables the<br>
previous timer, and an argument of <code class="inline"><span class="n">0</span></code>
may be supplied to cancel the<br>
previous timer without starting a new one. The returned value is the<br>
amount of time remaining on the previous timer.</p>
<p>For delays of finer granularity than one second, the Time::HiRes module<br>
(from CPAN, and starting from Perl 5.8 part of the standard<br>
distribution) provides ualarm(). You may also use Perl's four-argument<br>
version of select() leaving the first three arguments undefined, or you<br>
might be able to use the <code class="inline"><a class="l_k" href="../functions/syscall.html">syscall</a></code> interface to access setitimer(2) if<br>
your system supports it. See <a href="../perlfaq8.html">perlfaq8</a> for details.</p>
<p>It is usually a mistake to intermix <code class="inline"><a class="l_k" href="../functions/alarm.html">alarm</a></code> and <code class="inline"><a class="l_k" href="../functions/sleep.html">sleep</a></code> calls.<br>
(<code class="inline"><a class="l_k" href="../functions/sleep.html">sleep</a></code> may be internally implemented in your system with <code class="inline"><a class="l_k" href="../functions/alarm.html">alarm</a></code>)</p>
<p>If you want to use <code class="inline"><a class="l_k" href="../functions/alarm.html">alarm</a></code> to time out a system call you need to use an<br>
<code class="inline"><a class="l_k" href="../functions/eval.html">eval</a></code>/<code class="inline"><a class="l_k" href="../functions/die.html">die</a></code> pair. You can't rely on the alarm causing the system call to<br>
fail with <code class="inline"><span class="i">$!</span></code>
set to <code class="inline"><span class="w">EINTR</span></code>
because Perl sets up signal handlers to<br>
restart system calls on some systems. Using <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a></code>/<code class="inline"><a class="l_k" href="../functions/die.html">die</a></code> always works,<br>
modulo the caveats given in <a href="../perlipc.html#Signals">"Signals" in perlipc</a>.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/eval.html">eval</a> <span class="s">{</span></li><li> <a class="l_k" href="../functions/local.html">local</a> <span class="i">$SIG</span>{<span class="w">ALRM</span>} = <a class="l_k" href="../functions/sub.html">sub</a> <span class="s">{</span> <a class="l_k" href="../functions/die.html">die</a> <span class="q">"alarm\n"</span> <span class="s">}</span><span class="sc">;</span> <span class="c"># NB: \n required</span></li><li> <a class="l_k" href="../functions/alarm.html">alarm</a> <span class="i">$timeout</span><span class="sc">;</span></li><li> <span class="i">$nread</span> = <a class="l_k" href="../functions/sysread.html">sysread</a> <span class="w">SOCKET</span><span class="cm">,</span> <span class="i">$buffer</span><span class="cm">,</span> <span class="i">$size</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/alarm.html">alarm</a> <span class="n">0</span><span class="sc">;</span></li><li> <span class="s">}</span><span class="sc">;</span></li><li> if <span class="s">(</span><span class="i">$@</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/die.html">die</a> unless <span class="i">$@</span> eq <span class="q">"alarm\n"</span><span class="sc">;</span> <span class="c"># propagate unexpected errors</span></li><li> <span class="c"># timed out</span></li><li> <span class="s">}</span></li><li> else <span class="s">{</span></li><li> <span class="c"># didn't</span></li><li> <span class="s">}</span></li></ol></pre><p>For more information see <a href="../perlipc.html">perlipc</a>.]]></desc>
</keyword>
<keyword name="alarm" type="function">
<params>
</params>
<desc><![CDATA[Arranges to have a SIGALRM delivered to this process after the<br>
specified number of wallclock seconds has elapsed. If SECONDS is not<br>
specified, the value stored in <code class="inline"><span class="i">$_</span></code>
is used. (On some machines,<br>
unfortunately, the elapsed time may be up to one second less or more<br>
than you specified because of how seconds are counted, and process<br>
scheduling may delay the delivery of the signal even further.)</p>
<p>Only one timer may be counting at once. Each call disables the<br>
previous timer, and an argument of <code class="inline"><span class="n">0</span></code>
may be supplied to cancel the<br>
previous timer without starting a new one. The returned value is the<br>
amount of time remaining on the previous timer.</p>
<p>For delays of finer granularity than one second, the Time::HiRes module<br>
(from CPAN, and starting from Perl 5.8 part of the standard<br>
distribution) provides ualarm(). You may also use Perl's four-argument<br>
version of select() leaving the first three arguments undefined, or you<br>
might be able to use the <code class="inline"><a class="l_k" href="../functions/syscall.html">syscall</a></code> interface to access setitimer(2) if<br>
your system supports it. See <a href="../perlfaq8.html">perlfaq8</a> for details.</p>
<p>It is usually a mistake to intermix <code class="inline"><a class="l_k" href="../functions/alarm.html">alarm</a></code> and <code class="inline"><a class="l_k" href="../functions/sleep.html">sleep</a></code> calls.<br>
(<code class="inline"><a class="l_k" href="../functions/sleep.html">sleep</a></code> may be internally implemented in your system with <code class="inline"><a class="l_k" href="../functions/alarm.html">alarm</a></code>)</p>
<p>If you want to use <code class="inline"><a class="l_k" href="../functions/alarm.html">alarm</a></code> to time out a system call you need to use an<br>
<code class="inline"><a class="l_k" href="../functions/eval.html">eval</a></code>/<code class="inline"><a class="l_k" href="../functions/die.html">die</a></code> pair. You can't rely on the alarm causing the system call to<br>
fail with <code class="inline"><span class="i">$!</span></code>
set to <code class="inline"><span class="w">EINTR</span></code>
because Perl sets up signal handlers to<br>
restart system calls on some systems. Using <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a></code>/<code class="inline"><a class="l_k" href="../functions/die.html">die</a></code> always works,<br>
modulo the caveats given in <a href="../perlipc.html#Signals">"Signals" in perlipc</a>.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/eval.html">eval</a> <span class="s">{</span></li><li> <a class="l_k" href="../functions/local.html">local</a> <span class="i">$SIG</span>{<span class="w">ALRM</span>} = <a class="l_k" href="../functions/sub.html">sub</a> <span class="s">{</span> <a class="l_k" href="../functions/die.html">die</a> <span class="q">"alarm\n"</span> <span class="s">}</span><span class="sc">;</span> <span class="c"># NB: \n required</span></li><li> <a class="l_k" href="../functions/alarm.html">alarm</a> <span class="i">$timeout</span><span class="sc">;</span></li><li> <span class="i">$nread</span> = <a class="l_k" href="../functions/sysread.html">sysread</a> <span class="w">SOCKET</span><span class="cm">,</span> <span class="i">$buffer</span><span class="cm">,</span> <span class="i">$size</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/alarm.html">alarm</a> <span class="n">0</span><span class="sc">;</span></li><li> <span class="s">}</span><span class="sc">;</span></li><li> if <span class="s">(</span><span class="i">$@</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/die.html">die</a> unless <span class="i">$@</span> eq <span class="q">"alarm\n"</span><span class="sc">;</span> <span class="c"># propagate unexpected errors</span></li><li> <span class="c"># timed out</span></li><li> <span class="s">}</span></li><li> else <span class="s">{</span></li><li> <span class="c"># didn't</span></li><li> <span class="s">}</span></li></ol></pre><p>For more information see <a href="../perlipc.html">perlipc</a>.]]></desc>
</keyword>
<keyword name="atan2" type="function">
<params>
<param name='y'/>
<param name='x'/>
</params>
<desc><![CDATA[Returns the arctangent of Y/X in the range -PI to PI.</p>
<p>For the tangent operation, you may use the <code class="inline"><span class="w">Math::Trig::tan</span></code>
<br>
function, or use the familiar relation:</p>
<pre class="verbatim"><ol><li><a name="tan"></a> sub <span class="m">tan</span> <span class="s">{</span> <a class="l_k" href="../functions/sin.html">sin</a><span class="s">(</span><span class="i">$_</span>[<span class="n">0</span>]<span class="s">)</span> / <a class="l_k" href="../functions/cos.html">cos</a><span class="s">(</span><span class="i">$_</span>[<span class="n">0</span>]<span class="s">)</span> <span class="s">}</span></li></ol></pre><p>The return value for <code class="inline"><a class="l_k" href="../functions/atan2.html">atan2(0,0)</a></code> is implementation-defined; consult<br>
your atan2(3) manpage for more information.]]></desc>
</keyword>
<keyword name="bind" type="function">
<params>
<param name='socket'/>
<param name='name'/>
</params>
<desc><![CDATA[Binds a network address to a socket, just as the bind system call<br>
does. Returns true if it succeeded, false otherwise. NAME should be a<br>
packed address of the appropriate type for the socket. See the examples in<br>
<a href="../perlipc.html#Sockets%3a-Client%2fServer-Communication">"Sockets: Client/Server Communication" in perlipc</a>.]]></desc>
</keyword>
<keyword name="binmode" type="function">
<params>
<param name='filehandle'/>
<param name='layer'/>
</params>
<desc><![CDATA[Arranges for FILEHANDLE to be read or written in "binary" or "text"<br>
mode on systems where the run-time libraries distinguish between<br>
binary and text files. If FILEHANDLE is an expression, the value is<br>
taken as the name of the filehandle. Returns true on success,<br>
otherwise it returns <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> and sets <code class="inline"><span class="i">$!</span></code>
(errno).</p>
<p>On some systems (in general, DOS and Windows-based systems) binmode()<br>
is necessary when you're not working with a text file. For the sake<br>
of portability it is a good idea to always use it when appropriate,<br>
and to never use it when it isn't appropriate. Also, people can<br>
set their I/O to be by default UTF-8 encoded Unicode, not bytes.</p>
<p>In other words: regardless of platform, use binmode() on binary data,<br>
like for example images.</p>
<p>If LAYER is present it is a single string, but may contain multiple<br>
directives. The directives alter the behaviour of the file handle.<br>
When LAYER is present using binmode on a text file makes sense.</p>
<p>If LAYER is omitted or specified as <code class="inline"><span class="j">:</span><span class="w">raw</span></code>
the filehandle is made<br>
suitable for passing binary data. This includes turning off possible CRLF<br>
translation and marking it as bytes (as opposed to Unicode characters).<br>
Note that, despite what may be implied in <i>"Programming Perl"</i> (the<br>
Camel) or elsewhere, <code class="inline"><span class="j">:</span><span class="w">raw</span></code>
is <i>not</i> simply the inverse of <code class="inline"><span class="j">:</span><span class="w">crlf</span></code>
<br>
-- other layers which would affect the binary nature of the stream are<br>
<i>also</i> disabled. See <a href="../PerlIO.html">PerlIO</a>, <a href="../perlrun.html">perlrun</a> and the discussion about the<br>
PERLIO environment variable.</p>
<p>The <code class="inline"><span class="j">:</span><span class="w">bytes</span></code>
, <code class="inline"><span class="j">:</span><span class="w">crlf</span></code>
, and <code class="inline"><span class="j">:</span><span class="w">utf8</span></code>
, and any other directives of the<br>
form <code class="inline"><span class="j">:</span>...</code>
, are called I/O <i>layers</i>. The <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> pragma can be used to<br>
establish default I/O layers. See <a href="../open.html">open</a>.</p>
<p><i>The LAYER parameter of the binmode() function is described as "DISCIPLINE"<br>
in "Programming Perl, 3rd Edition". However, since the publishing of this<br>
book, by many known as "Camel III", the consensus of the naming of this<br>
functionality has moved from "discipline" to "layer". All documentation<br>
of this version of Perl therefore refers to "layers" rather than to<br>
"disciplines". Now back to the regularly scheduled documentation...</i></p>
<p>To mark FILEHANDLE as UTF-8, use <code class="inline"><span class="j">:</span><span class="w">utf8</span></code>
or <code class="inline"><span class="j">:</span><span class="i">encoding</span><span class="s">(</span><span class="w">utf8</span><span class="s">)</span></code>
.<br>
<code class="inline"><span class="j">:</span><span class="w">utf8</span></code>
just marks the data as UTF-8 without further checking,<br>
while <code class="inline"><span class="j">:</span><span class="i">encoding</span><span class="s">(</span><span class="w">utf8</span><span class="s">)</span></code>
checks the data for actually being valid<br>
UTF-8. More details can be found in <a href="../PerlIO/encoding.html">PerlIO::encoding</a>.</p>
<p>In general, binmode() should be called after open() but before any I/O<br>
is done on the filehandle. Calling binmode() will normally flush any<br>
pending buffered output data (and perhaps pending input data) on the<br>
handle. An exception to this is the <code class="inline"><span class="j">:</span><span class="w">encoding</span></code>
layer that<br>
changes the default character encoding of the handle, see <a href="../open.html">open</a>.<br>
The <code class="inline"><span class="j">:</span><span class="w">encoding</span></code>
layer sometimes needs to be called in<br>
mid-stream, and it doesn't flush the stream. The <code class="inline"><span class="j">:</span><span class="w">encoding</span></code>
<br>
also implicitly pushes on top of itself the <code class="inline"><span class="j">:</span><span class="w">utf8</span></code>
layer because<br>
internally Perl will operate on UTF-8 encoded Unicode characters.</p>
<p>The operating system, device drivers, C libraries, and Perl run-time<br>
system all work together to let the programmer treat a single<br>
character (<code class="inline">\<span class="w">n</span></code>
) as the line terminator, irrespective of the external<br>
representation. On many operating systems, the native text file<br>
representation matches the internal representation, but on some<br>
platforms the external representation of <code class="inline">\<span class="w">n</span></code>
is made up of more than<br>
one character.</p>
<p>Mac OS, all variants of Unix, and Stream_LF files on VMS use a single<br>
character to end each line in the external representation of text (even<br>
though that single character is CARRIAGE RETURN on Mac OS and LINE FEED<br>
on Unix and most VMS files). In other systems like OS/2, DOS and the<br>
various flavors of MS-Windows your program sees a <code class="inline">\<span class="w">n</span></code>
as a simple <code class="inline">\<span class="w">cJ</span></code>
,<br>
but what's stored in text files are the two characters <code class="inline">\<span class="w">cM</span>\<span class="w">cJ</span></code>
. That<br>
means that, if you don't use binmode() on these systems, <code class="inline">\<span class="w">cM</span>\<span class="w">cJ</span></code>
<br>
sequences on disk will be converted to <code class="inline">\<span class="w">n</span></code>
on input, and any <code class="inline">\<span class="w">n</span></code>
in<br>
your program will be converted back to <code class="inline">\<span class="w">cM</span>\<span class="w">cJ</span></code>
on output. This is what<br>
you want for text files, but it can be disastrous for binary files.</p>
<p>Another consequence of using binmode() (on some systems) is that<br>
special end-of-file markers will be seen as part of the data stream.<br>
For systems from the Microsoft family this means that if your binary<br>
data contains <code class="inline">\<span class="w">cZ</span></code>
, the I/O subsystem will regard it as the end of<br>
the file, unless you use binmode().</p>
<p>binmode() is not only important for readline() and print() operations,<br>
but also when using read(), seek(), sysread(), syswrite() and tell()<br>
(see <a href="../perlport.html">perlport</a> for more details). See the <code class="inline"><span class="i">$/</span></code>
and <code class="inline"><span class="i">$\</span></code>
variables<br>
in <a href="../perlvar.html">perlvar</a> for how to manually set your input and output<br>
line-termination sequences.]]></desc>
</keyword>
<keyword name="binmode" type="function">
<params>
<param name='filehandle'/>
</params>
<desc><![CDATA[Arranges for FILEHANDLE to be read or written in "binary" or "text"<br>
mode on systems where the run-time libraries distinguish between<br>
binary and text files. If FILEHANDLE is an expression, the value is<br>
taken as the name of the filehandle. Returns true on success,<br>
otherwise it returns <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> and sets <code class="inline"><span class="i">$!</span></code>
(errno).</p>
<p>On some systems (in general, DOS and Windows-based systems) binmode()<br>
is necessary when you're not working with a text file. For the sake<br>
of portability it is a good idea to always use it when appropriate,<br>
and to never use it when it isn't appropriate. Also, people can<br>
set their I/O to be by default UTF-8 encoded Unicode, not bytes.</p>
<p>In other words: regardless of platform, use binmode() on binary data,<br>
like for example images.</p>
<p>If LAYER is present it is a single string, but may contain multiple<br>
directives. The directives alter the behaviour of the file handle.<br>
When LAYER is present using binmode on a text file makes sense.</p>
<p>If LAYER is omitted or specified as <code class="inline"><span class="j">:</span><span class="w">raw</span></code>
the filehandle is made<br>
suitable for passing binary data. This includes turning off possible CRLF<br>
translation and marking it as bytes (as opposed to Unicode characters).<br>
Note that, despite what may be implied in <i>"Programming Perl"</i> (the<br>
Camel) or elsewhere, <code class="inline"><span class="j">:</span><span class="w">raw</span></code>
is <i>not</i> simply the inverse of <code class="inline"><span class="j">:</span><span class="w">crlf</span></code>
<br>
-- other layers which would affect the binary nature of the stream are<br>
<i>also</i> disabled. See <a href="../PerlIO.html">PerlIO</a>, <a href="../perlrun.html">perlrun</a> and the discussion about the<br>
PERLIO environment variable.</p>
<p>The <code class="inline"><span class="j">:</span><span class="w">bytes</span></code>
, <code class="inline"><span class="j">:</span><span class="w">crlf</span></code>
, and <code class="inline"><span class="j">:</span><span class="w">utf8</span></code>
, and any other directives of the<br>
form <code class="inline"><span class="j">:</span>...</code>
, are called I/O <i>layers</i>. The <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> pragma can be used to<br>
establish default I/O layers. See <a href="../open.html">open</a>.</p>
<p><i>The LAYER parameter of the binmode() function is described as "DISCIPLINE"<br>
in "Programming Perl, 3rd Edition". However, since the publishing of this<br>
book, by many known as "Camel III", the consensus of the naming of this<br>
functionality has moved from "discipline" to "layer". All documentation<br>
of this version of Perl therefore refers to "layers" rather than to<br>
"disciplines". Now back to the regularly scheduled documentation...</i></p>
<p>To mark FILEHANDLE as UTF-8, use <code class="inline"><span class="j">:</span><span class="w">utf8</span></code>
or <code class="inline"><span class="j">:</span><span class="i">encoding</span><span class="s">(</span><span class="w">utf8</span><span class="s">)</span></code>
.<br>
<code class="inline"><span class="j">:</span><span class="w">utf8</span></code>
just marks the data as UTF-8 without further checking,<br>
while <code class="inline"><span class="j">:</span><span class="i">encoding</span><span class="s">(</span><span class="w">utf8</span><span class="s">)</span></code>
checks the data for actually being valid<br>
UTF-8. More details can be found in <a href="../PerlIO/encoding.html">PerlIO::encoding</a>.</p>
<p>In general, binmode() should be called after open() but before any I/O<br>
is done on the filehandle. Calling binmode() will normally flush any<br>
pending buffered output data (and perhaps pending input data) on the<br>
handle. An exception to this is the <code class="inline"><span class="j">:</span><span class="w">encoding</span></code>
layer that<br>
changes the default character encoding of the handle, see <a href="../open.html">open</a>.<br>
The <code class="inline"><span class="j">:</span><span class="w">encoding</span></code>
layer sometimes needs to be called in<br>
mid-stream, and it doesn't flush the stream. The <code class="inline"><span class="j">:</span><span class="w">encoding</span></code>
<br>
also implicitly pushes on top of itself the <code class="inline"><span class="j">:</span><span class="w">utf8</span></code>
layer because<br>
internally Perl will operate on UTF-8 encoded Unicode characters.</p>
<p>The operating system, device drivers, C libraries, and Perl run-time<br>
system all work together to let the programmer treat a single<br>
character (<code class="inline">\<span class="w">n</span></code>
) as the line terminator, irrespective of the external<br>
representation. On many operating systems, the native text file<br>
representation matches the internal representation, but on some<br>
platforms the external representation of <code class="inline">\<span class="w">n</span></code>
is made up of more than<br>
one character.</p>
<p>Mac OS, all variants of Unix, and Stream_LF files on VMS use a single<br>
character to end each line in the external representation of text (even<br>
though that single character is CARRIAGE RETURN on Mac OS and LINE FEED<br>
on Unix and most VMS files). In other systems like OS/2, DOS and the<br>
various flavors of MS-Windows your program sees a <code class="inline">\<span class="w">n</span></code>
as a simple <code class="inline">\<span class="w">cJ</span></code>
,<br>
but what's stored in text files are the two characters <code class="inline">\<span class="w">cM</span>\<span class="w">cJ</span></code>
. That<br>
means that, if you don't use binmode() on these systems, <code class="inline">\<span class="w">cM</span>\<span class="w">cJ</span></code>
<br>
sequences on disk will be converted to <code class="inline">\<span class="w">n</span></code>
on input, and any <code class="inline">\<span class="w">n</span></code>
in<br>
your program will be converted back to <code class="inline">\<span class="w">cM</span>\<span class="w">cJ</span></code>
on output. This is what<br>
you want for text files, but it can be disastrous for binary files.</p>
<p>Another consequence of using binmode() (on some systems) is that<br>
special end-of-file markers will be seen as part of the data stream.<br>
For systems from the Microsoft family this means that if your binary<br>
data contains <code class="inline">\<span class="w">cZ</span></code>
, the I/O subsystem will regard it as the end of<br>
the file, unless you use binmode().</p>
<p>binmode() is not only important for readline() and print() operations,<br>
but also when using read(), seek(), sysread(), syswrite() and tell()<br>
(see <a href="../perlport.html">perlport</a> for more details). See the <code class="inline"><span class="i">$/</span></code>
and <code class="inline"><span class="i">$\</span></code>
variables<br>
in <a href="../perlvar.html">perlvar</a> for how to manually set your input and output<br>
line-termination sequences.]]></desc>
</keyword>
<keyword name="bless" type="function">
<params>
<param name='ref'/>
<param name='classname'/>
</params>
<desc><![CDATA[This function tells the thingy referenced by REF that it is now an object<br>
in the CLASSNAME package. If CLASSNAME is omitted, the current package<br>
is used. Because a <code class="inline"><a class="l_k" href="../functions/bless.html">bless</a></code> is often the last thing in a constructor,<br>
it returns the reference for convenience. Always use the two-argument<br>
version if a derived class might inherit the function doing the blessing.<br>
See <a href="../perltoot.html">perltoot</a> and <a href="../perlobj.html">perlobj</a> for more about the blessing (and blessings)<br>
of objects.</p>
<p>Consider always blessing objects in CLASSNAMEs that are mixed case.<br>
Namespaces with all lowercase names are considered reserved for<br>
Perl pragmata. Builtin types have all uppercase names. To prevent<br>
confusion, you may wish to avoid such package names as well. Make sure<br>
that CLASSNAME is a true value.</p>
<p>See <a href="../perlmod.html#Perl-Modules">"Perl Modules" in perlmod</a>.]]></desc>
</keyword>
<keyword name="bless" type="function">
<params>
<param name='ref'/>
</params>
<desc><![CDATA[This function tells the thingy referenced by REF that it is now an object<br>
in the CLASSNAME package. If CLASSNAME is omitted, the current package<br>
is used. Because a <code class="inline"><a class="l_k" href="../functions/bless.html">bless</a></code> is often the last thing in a constructor,<br>
it returns the reference for convenience. Always use the two-argument<br>
version if a derived class might inherit the function doing the blessing.<br>
See <a href="../perltoot.html">perltoot</a> and <a href="../perlobj.html">perlobj</a> for more about the blessing (and blessings)<br>
of objects.</p>
<p>Consider always blessing objects in CLASSNAMEs that are mixed case.<br>
Namespaces with all lowercase names are considered reserved for<br>
Perl pragmata. Builtin types have all uppercase names. To prevent<br>
confusion, you may wish to avoid such package names as well. Make sure<br>
that CLASSNAME is a true value.</p>
<p>See <a href="../perlmod.html#Perl-Modules">"Perl Modules" in perlmod</a>.]]></desc>
</keyword>
<keyword name="break" type="function">
<params>
</params>
<desc><![CDATA[Break out of a <code class="inline">given<span class="s">(</span><span class="s">)</span></code>
block.</p>
<p>This keyword is enabled by the "switch" feature: see <a href="../feature.html">feature</a>
for more information.]]></desc>
</keyword>
<keyword name="caller" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Returns the context of the current subroutine call. In scalar context,<br>
returns the caller's package name if there is a caller, that is, if<br>
we're in a subroutine or <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a></code> or <code class="inline"><a class="l_k" href="../functions/require.html">require</a></code>, and the undefined value<br>
otherwise. In list context, returns</p>
<pre class="verbatim"><ol><li> <span class="c"># 0 1 2</span></li><li> <span class="s">(</span><span class="i">$package</span><span class="cm">,</span> <span class="i">$filename</span><span class="cm">,</span> <span class="i">$line</span><span class="s">)</span> = <a class="l_k" href="../functions/caller.html">caller</a><span class="sc">;</span></li></ol></pre><p>With EXPR, it returns some extra information that the debugger uses to<br>
print a stack trace. The value of EXPR indicates how many call frames<br>
to go back before the current one.</p>
<pre class="verbatim"><ol><li> <span class="c"># 0 1 2 3 4</span></li><li> <span class="s">(</span><span class="i">$package</span><span class="cm">,</span> <span class="i">$filename</span><span class="cm">,</span> <span class="i">$line</span><span class="cm">,</span> <span class="i">$subroutine</span><span class="cm">,</span> <span class="i">$hasargs</span><span class="cm">,</span></li><li></li><li> <span class="c"># 5 6 7 8 9 10</span></li><li> <span class="i">$wantarray</span><span class="cm">,</span> <span class="i">$evaltext</span><span class="cm">,</span> <span class="i">$is_require</span><span class="cm">,</span> <span class="i">$hints</span><span class="cm">,</span> <span class="i">$bitmask</span><span class="cm">,</span> <span class="i">$hinthash</span><span class="s">)</span></li><li> = <a class="l_k" href="../functions/caller.html">caller</a><span class="s">(</span><span class="i">$i</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Here $subroutine may be <code class="inline"><span class="s">(</span><a class="l_k" href="../functions/eval.html">eval</a><span class="s">)</span></code>
if the frame is not a subroutine<br>
call, but an <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a></code>. In such a case additional elements $evaltext and<br>
<code class="inline"><span class="i">$is_require</span></code>
are set: <code class="inline"><span class="i">$is_require</span></code>
is true if the frame is created by a<br>
<code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> or <code class="inline"><a class="l_k" href="../functions/use.html">use</a></code> statement, $evaltext contains the text of the<br>
<code class="inline"><a class="l_k" href="../functions/eval.html">eval</a> <span class="w">EXPR</span></code>
statement. In particular, for an <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a> <span class="w">BLOCK</span></code>
statement,<br>
$subroutine is <code class="inline"><span class="s">(</span><a class="l_k" href="../functions/eval.html">eval</a><span class="s">)</span></code>
, but $evaltext is undefined. (Note also that<br>
each <code class="inline"><a class="l_k" href="../functions/use.html">use</a></code> statement creates a <code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> frame inside an <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a> <span class="w">EXPR</span></code>
<br>
frame.) $subroutine may also be <code class="inline"><span class="s">(</span><span class="w">unknown</span><span class="s">)</span></code>
if this particular<br>
subroutine happens to have been deleted from the symbol table.<br>
<code class="inline"><span class="i">$hasargs</span></code>
is true if a new instance of <code class="inline"><span class="i">@_</span></code>
was set up for the frame.<br>
<code class="inline"><span class="i">$hints</span></code>
and <code class="inline"><span class="i">$bitmask</span></code>
contain pragmatic hints that the caller was<br>
compiled with. The <code class="inline"><span class="i">$hints</span></code>
and <code class="inline"><span class="i">$bitmask</span></code>
values are subject to change<br>
between versions of Perl, and are not meant for external use.</p>
<p><code class="inline"><span class="i">$hinthash</span></code>
is a reference to a hash containing the value of <code class="inline"><span class="i">%^H</span></code>
when the<br>
caller was compiled, or <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> if <code class="inline"><span class="i">%^H</span></code>
was empty. Do not modify the values<br>
of this hash, as they are the actual values stored in the optree.</p>
<p>Furthermore, when called from within the DB package, caller returns more<br>
detailed information: it sets the list variable <code class="inline"><span class="i">@DB::args</span></code>
to be the<br>
arguments with which the subroutine was invoked.</p>
<p>Be aware that the optimizer might have optimized call frames away before<br>
<code class="inline"><a class="l_k" href="../functions/caller.html">caller</a></code> had a chance to get the information. That means that <code class="inline"><a class="l_k" href="../functions/caller.html">caller(N)</a></code>
might not return information about the call frame you expect it do, for<br>
<code class="inline"><span class="w">N</span> > <span class="n">1</span></code>
. In particular, <code class="inline"><span class="i">@DB::args</span></code>
might have information from the<br>
previous time <code class="inline"><a class="l_k" href="../functions/caller.html">caller</a></code> was called.]]></desc>
</keyword>
<keyword name="caller" type="function">
<params>
</params>
<desc><![CDATA[Returns the context of the current subroutine call. In scalar context,<br>
returns the caller's package name if there is a caller, that is, if<br>
we're in a subroutine or <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a></code> or <code class="inline"><a class="l_k" href="../functions/require.html">require</a></code>, and the undefined value<br>
otherwise. In list context, returns</p>
<pre class="verbatim"><ol><li> <span class="c"># 0 1 2</span></li><li> <span class="s">(</span><span class="i">$package</span><span class="cm">,</span> <span class="i">$filename</span><span class="cm">,</span> <span class="i">$line</span><span class="s">)</span> = <a class="l_k" href="../functions/caller.html">caller</a><span class="sc">;</span></li></ol></pre><p>With EXPR, it returns some extra information that the debugger uses to<br>
print a stack trace. The value of EXPR indicates how many call frames<br>
to go back before the current one.</p>
<pre class="verbatim"><ol><li> <span class="c"># 0 1 2 3 4</span></li><li> <span class="s">(</span><span class="i">$package</span><span class="cm">,</span> <span class="i">$filename</span><span class="cm">,</span> <span class="i">$line</span><span class="cm">,</span> <span class="i">$subroutine</span><span class="cm">,</span> <span class="i">$hasargs</span><span class="cm">,</span></li><li></li><li> <span class="c"># 5 6 7 8 9 10</span></li><li> <span class="i">$wantarray</span><span class="cm">,</span> <span class="i">$evaltext</span><span class="cm">,</span> <span class="i">$is_require</span><span class="cm">,</span> <span class="i">$hints</span><span class="cm">,</span> <span class="i">$bitmask</span><span class="cm">,</span> <span class="i">$hinthash</span><span class="s">)</span></li><li> = <a class="l_k" href="../functions/caller.html">caller</a><span class="s">(</span><span class="i">$i</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Here $subroutine may be <code class="inline"><span class="s">(</span><a class="l_k" href="../functions/eval.html">eval</a><span class="s">)</span></code>
if the frame is not a subroutine<br>
call, but an <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a></code>. In such a case additional elements $evaltext and<br>
<code class="inline"><span class="i">$is_require</span></code>
are set: <code class="inline"><span class="i">$is_require</span></code>
is true if the frame is created by a<br>
<code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> or <code class="inline"><a class="l_k" href="../functions/use.html">use</a></code> statement, $evaltext contains the text of the<br>
<code class="inline"><a class="l_k" href="../functions/eval.html">eval</a> <span class="w">EXPR</span></code>
statement. In particular, for an <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a> <span class="w">BLOCK</span></code>
statement,<br>
$subroutine is <code class="inline"><span class="s">(</span><a class="l_k" href="../functions/eval.html">eval</a><span class="s">)</span></code>
, but $evaltext is undefined. (Note also that<br>
each <code class="inline"><a class="l_k" href="../functions/use.html">use</a></code> statement creates a <code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> frame inside an <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a> <span class="w">EXPR</span></code>
<br>
frame.) $subroutine may also be <code class="inline"><span class="s">(</span><span class="w">unknown</span><span class="s">)</span></code>
if this particular<br>
subroutine happens to have been deleted from the symbol table.<br>
<code class="inline"><span class="i">$hasargs</span></code>
is true if a new instance of <code class="inline"><span class="i">@_</span></code>
was set up for the frame.<br>
<code class="inline"><span class="i">$hints</span></code>
and <code class="inline"><span class="i">$bitmask</span></code>
contain pragmatic hints that the caller was<br>
compiled with. The <code class="inline"><span class="i">$hints</span></code>
and <code class="inline"><span class="i">$bitmask</span></code>
values are subject to change<br>
between versions of Perl, and are not meant for external use.</p>
<p><code class="inline"><span class="i">$hinthash</span></code>
is a reference to a hash containing the value of <code class="inline"><span class="i">%^H</span></code>
when the<br>
caller was compiled, or <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> if <code class="inline"><span class="i">%^H</span></code>
was empty. Do not modify the values<br>
of this hash, as they are the actual values stored in the optree.</p>
<p>Furthermore, when called from within the DB package, caller returns more<br>
detailed information: it sets the list variable <code class="inline"><span class="i">@DB::args</span></code>
to be the<br>
arguments with which the subroutine was invoked.</p>
<p>Be aware that the optimizer might have optimized call frames away before<br>
<code class="inline"><a class="l_k" href="../functions/caller.html">caller</a></code> had a chance to get the information. That means that <code class="inline"><a class="l_k" href="../functions/caller.html">caller(N)</a></code>
might not return information about the call frame you expect it do, for<br>
<code class="inline"><span class="w">N</span> > <span class="n">1</span></code>
. In particular, <code class="inline"><span class="i">@DB::args</span></code>
might have information from the<br>
previous time <code class="inline"><a class="l_k" href="../functions/caller.html">caller</a></code> was called.]]></desc>
</keyword>
<keyword name="chdir" type="function">
<params>
<param name='dirhandle'/>
</params>
<desc><![CDATA[Changes the working directory to EXPR, if possible. If EXPR is omitted,<br>
changes to the directory specified by <code class="inline"><span class="i">$ENV</span>{<span class="w">HOME</span>}</code>
, if set; if not,<br>
changes to the directory specified by <code class="inline"><span class="i">$ENV</span>{<span class="w">LOGDIR</span>}</code>
. (Under VMS, the<br>
variable <code class="inline"><span class="i">$ENV</span>{<span class="w">SYS</span><span class="i">$LOGIN</span>}</code>
is also checked, and used if it is set.) If<br>
neither is set, <code class="inline"><a class="l_k" href="../functions/chdir.html">chdir</a></code> does nothing. It returns true upon success,<br>
false otherwise. See the example under <code class="inline"><a class="l_k" href="../functions/die.html">die</a></code>.</p>
<p>On systems that support fchdir, you might pass a file handle or<br>
directory handle as argument. On systems that don't support fchdir,<br>
passing handles produces a fatal error at run time.]]></desc>
</keyword>
<keyword name="chdir" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Changes the working directory to EXPR, if possible. If EXPR is omitted,<br>
changes to the directory specified by <code class="inline"><span class="i">$ENV</span>{<span class="w">HOME</span>}</code>
, if set; if not,<br>
changes to the directory specified by <code class="inline"><span class="i">$ENV</span>{<span class="w">LOGDIR</span>}</code>
. (Under VMS, the<br>
variable <code class="inline"><span class="i">$ENV</span>{<span class="w">SYS</span><span class="i">$LOGIN</span>}</code>
is also checked, and used if it is set.) If<br>
neither is set, <code class="inline"><a class="l_k" href="../functions/chdir.html">chdir</a></code> does nothing. It returns true upon success,<br>
false otherwise. See the example under <code class="inline"><a class="l_k" href="../functions/die.html">die</a></code>.</p>
<p>On systems that support fchdir, you might pass a file handle or<br>
directory handle as argument. On systems that don't support fchdir,<br>
passing handles produces a fatal error at run time.]]></desc>
</keyword>
<keyword name="chdir" type="function">
<params>
<param name='filehandle'/>
</params>
<desc><![CDATA[Changes the working directory to EXPR, if possible. If EXPR is omitted,<br>
changes to the directory specified by <code class="inline"><span class="i">$ENV</span>{<span class="w">HOME</span>}</code>
, if set; if not,<br>
changes to the directory specified by <code class="inline"><span class="i">$ENV</span>{<span class="w">LOGDIR</span>}</code>
. (Under VMS, the<br>
variable <code class="inline"><span class="i">$ENV</span>{<span class="w">SYS</span><span class="i">$LOGIN</span>}</code>
is also checked, and used if it is set.) If<br>
neither is set, <code class="inline"><a class="l_k" href="../functions/chdir.html">chdir</a></code> does nothing. It returns true upon success,<br>
false otherwise. See the example under <code class="inline"><a class="l_k" href="../functions/die.html">die</a></code>.</p>
<p>On systems that support fchdir, you might pass a file handle or<br>
directory handle as argument. On systems that don't support fchdir,<br>
passing handles produces a fatal error at run time.]]></desc>
</keyword>
<keyword name="chdir" type="function">
<params>
</params>
<desc><![CDATA[Changes the working directory to EXPR, if possible. If EXPR is omitted,<br>
changes to the directory specified by <code class="inline"><span class="i">$ENV</span>{<span class="w">HOME</span>}</code>
, if set; if not,<br>
changes to the directory specified by <code class="inline"><span class="i">$ENV</span>{<span class="w">LOGDIR</span>}</code>
. (Under VMS, the<br>
variable <code class="inline"><span class="i">$ENV</span>{<span class="w">SYS</span><span class="i">$LOGIN</span>}</code>
is also checked, and used if it is set.) If<br>
neither is set, <code class="inline"><a class="l_k" href="../functions/chdir.html">chdir</a></code> does nothing. It returns true upon success,<br>
false otherwise. See the example under <code class="inline"><a class="l_k" href="../functions/die.html">die</a></code>.</p>
<p>On systems that support fchdir, you might pass a file handle or<br>
directory handle as argument. On systems that don't support fchdir,<br>
passing handles produces a fatal error at run time.]]></desc>
</keyword>
<keyword name="chmod" type="function">
<params>
<param name='list'/>
</params>
<desc><![CDATA[Changes the permissions of a list of files. The first element of the<br>
list must be the numerical mode, which should probably be an octal<br>
number, and which definitely should <i>not</i> be a string of octal digits:<br>
<code class="inline"><span class="n">0644</span></code>
is okay, <code class="inline"><span class="q">'0644'</span></code>
is not. Returns the number of files<br>
successfully changed. See also <a href="../functions/oct.html">"oct"</a>, if all you have is a string.</p>
<pre class="verbatim"><ol><li> <span class="i">$cnt</span> = <a class="l_k" href="../functions/chmod.html">chmod</a> <span class="n">0755</span><span class="cm">,</span> <span class="q">'foo'</span><span class="cm">,</span> <span class="q">'bar'</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/chmod.html">chmod</a> <span class="n">0755</span><span class="cm">,</span> <span class="i">@executables</span><span class="sc">;</span></li><li> <span class="i">$mode</span> = <span class="q">'0644'</span><span class="sc">;</span> <a class="l_k" href="../functions/chmod.html">chmod</a> <span class="i">$mode</span><span class="cm">,</span> <span class="q">'foo'</span><span class="sc">;</span> <span class="c"># !!! sets mode to</span></li><li> <span class="c"># --w----r-T</span></li><li> <span class="i">$mode</span> = <span class="q">'0644'</span><span class="sc">;</span> <a class="l_k" href="../functions/chmod.html">chmod</a> <a class="l_k" href="../functions/oct.html">oct</a><span class="s">(</span><span class="i">$mode</span><span class="s">)</span><span class="cm">,</span> <span class="q">'foo'</span><span class="sc">;</span> <span class="c"># this is better</span></li><li> <span class="i">$mode</span> = <span class="n">0644</span><span class="sc">;</span> <a class="l_k" href="../functions/chmod.html">chmod</a> <span class="i">$mode</span><span class="cm">,</span> <span class="q">'foo'</span><span class="sc">;</span> <span class="c"># this is best</span></li></ol></pre><p>On systems that support fchmod, you might pass file handles among the<br>
files. On systems that don't support fchmod, passing file handles<br>
produces a fatal error at run time. The file handles must be passed<br>
as globs or references to be recognized. Barewords are considered<br>
file names.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$fh</span><span class="cm">,</span> <span class="q">"<"</span><span class="cm">,</span> <span class="q">"foo"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$perm</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a> <span class="i">$fh</span><span class="s">)</span>[<span class="n">2</span>] & <span class="n">07777</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/chmod.html">chmod</a><span class="s">(</span><span class="i">$perm</span> | <span class="n">0600</span><span class="cm">,</span> <span class="i">$fh</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>You can also import the symbolic <code class="inline"><span class="w">S_I</span>*</code>
constants from the Fcntl<br>
module:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Fcntl</span> <span class="q">':mode'</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/chmod.html">chmod</a> <span class="w">S_IRWXU</span>|<span class="w">S_IRGRP</span>|<span class="w">S_IXGRP</span>|<span class="w">S_IROTH</span>|<span class="w">S_IXOTH</span><span class="cm">,</span> <span class="i">@executables</span><span class="sc">;</span></li><li> <span class="c"># This is identical to the chmod 0755 of the above example.</span></li></ol><]]></desc>
</keyword>
<keyword name="chomp" type="function">
<params>
<param name='( list )'/>
</params>
<desc><![CDATA[This safer version of <a href="../functions/chop.html">"chop"</a> removes any trailing string<br>
that corresponds to the current value of <code class="inline"><span class="i">$/</span></code>
(also known as<br>
$INPUT_RECORD_SEPARATOR in the <code class="inline"><span class="w">English</span></code>
module). It returns the total<br>
number of characters removed from all its arguments. It's often used to<br>
remove the newline from the end of an input record when you're worried<br>
that the final record may be missing its newline. When in paragraph<br>
mode (<code class="inline"><span class="i">$/</span> = <span class="q">""</span></code>
), it removes all trailing newlines from the string.<br>
When in slurp mode (<code class="inline"><span class="i">$/</span> = <a class="l_k" href="../functions/undef.html">undef</a></code>
) or fixed-length record mode (<code class="inline"><span class="i">$/</span></code>
is<br>
a reference to an integer or the like, see <a href="../perlvar.html">perlvar</a>) chomp() won't<br>
remove anything.<br>
If VARIABLE is omitted, it chomps <code class="inline"><span class="i">$_</span></code>
. Example:</p>
<pre class="verbatim"><ol><li> while <span class="s">(</span><><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/chomp.html">chomp</a><span class="sc">;</span> <span class="c"># avoid \n on last field</span></li><li> <span class="i">@array</span> = <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/:/</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c"># ...</span></li><li> <span class="s">}</span></li></ol></pre><p>If VARIABLE is a hash, it chomps the hash's values, but not its keys.</p>
<p>You can actually chomp anything that's an lvalue, including an assignment:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/chomp.html">chomp</a><span class="s">(</span><span class="i">$cwd</span> = <span class="q">`pwd`</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/chomp.html">chomp</a><span class="s">(</span><span class="i">$answer</span> = <span class="q"><STDIN></span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>If you chomp a list, each element is chomped, and the total number of<br>
characters removed is returned.</p>
<p>Note that parentheses are necessary when you're chomping anything<br>
that is not a simple variable. This is because <code class="inline"><a class="l_k" href="../functions/chomp.html">chomp</a> <span class="i">$cwd</span> = <span class="q">`pwd`</span><span class="sc">;</span></code>
<br>
is interpreted as <code class="inline"><span class="s">(</span><a class="l_k" href="../functions/chomp.html">chomp</a> <span class="i">$cwd</span><span class="s">)</span> = <span class="q">`pwd`</span><span class="sc">;</span></code>
, rather than as<br>
<code class="inline"><a class="l_k" href="../functions/chomp.html">chomp</a><span class="s">(</span> <span class="i">$cwd</span> = <span class="q">`pwd`</span> <span class="s">)</span></code>
which you might expect. Similarly,<br>
<code class="inline"><a class="l_k" href="../functions/chomp.html">chomp</a> <span class="i">$a</span><span class="cm">,</span> <span class="i">$b</span></code>
is interpreted as <code class="inline"><a class="l_k" href="../functions/chomp.html">chomp</a><span class="s">(</span><span class="i">$a</span><span class="s">)</span><span class="cm">,</span> <span class="i">$b</span></code>
rather than<br>
as <code class="inline"><a class="l_k" href="../functions/chomp.html">chomp</a><span class="s">(</span><span class="i">$a</span><span class="cm">,</span> <span class="i">$b</span><span class="s">)</span></code>
.]]></desc>
</keyword>
<keyword name="chomp" type="function">
<params>
<param name='variable'/>
</params>
<desc><![CDATA[This safer version of <a href="../functions/chop.html">"chop"</a> removes any trailing string<br>
that corresponds to the current value of <code class="inline"><span class="i">$/</span></code>
(also known as<br>
$INPUT_RECORD_SEPARATOR in the <code class="inline"><span class="w">English</span></code>
module). It returns the total<br>
number of characters removed from all its arguments. It's often used to<br>
remove the newline from the end of an input record when you're worried<br>
that the final record may be missing its newline. When in paragraph<br>
mode (<code class="inline"><span class="i">$/</span> = <span class="q">""</span></code>
), it removes all trailing newlines from the string.<br>
When in slurp mode (<code class="inline"><span class="i">$/</span> = <a class="l_k" href="../functions/undef.html">undef</a></code>
) or fixed-length record mode (<code class="inline"><span class="i">$/</span></code>
is<br>
a reference to an integer or the like, see <a href="../perlvar.html">perlvar</a>) chomp() won't<br>
remove anything.<br>
If VARIABLE is omitted, it chomps <code class="inline"><span class="i">$_</span></code>
. Example:</p>
<pre class="verbatim"><ol><li> while <span class="s">(</span><><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/chomp.html">chomp</a><span class="sc">;</span> <span class="c"># avoid \n on last field</span></li><li> <span class="i">@array</span> = <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/:/</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c"># ...</span></li><li> <span class="s">}</span></li></ol></pre><p>If VARIABLE is a hash, it chomps the hash's values, but not its keys.</p>
<p>You can actually chomp anything that's an lvalue, including an assignment:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/chomp.html">chomp</a><span class="s">(</span><span class="i">$cwd</span> = <span class="q">`pwd`</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/chomp.html">chomp</a><span class="s">(</span><span class="i">$answer</span> = <span class="q"><STDIN></span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>If you chomp a list, each element is chomped, and the total number of<br>
characters removed is returned.</p>
<p>Note that parentheses are necessary when you're chomping anything<br>
that is not a simple variable. This is because <code class="inline"><a class="l_k" href="../functions/chomp.html">chomp</a> <span class="i">$cwd</span> = <span class="q">`pwd`</span><span class="sc">;</span></code>
<br>
is interpreted as <code class="inline"><span class="s">(</span><a class="l_k" href="../functions/chomp.html">chomp</a> <span class="i">$cwd</span><span class="s">)</span> = <span class="q">`pwd`</span><span class="sc">;</span></code>
, rather than as<br>
<code class="inline"><a class="l_k" href="../functions/chomp.html">chomp</a><span class="s">(</span> <span class="i">$cwd</span> = <span class="q">`pwd`</span> <span class="s">)</span></code>
which you might expect. Similarly,<br>
<code class="inline"><a class="l_k" href="../functions/chomp.html">chomp</a> <span class="i">$a</span><span class="cm">,</span> <span class="i">$b</span></code>
is interpreted as <code class="inline"><a class="l_k" href="../functions/chomp.html">chomp</a><span class="s">(</span><span class="i">$a</span><span class="s">)</span><span class="cm">,</span> <span class="i">$b</span></code>
rather than<br>
as <code class="inline"><a class="l_k" href="../functions/chomp.html">chomp</a><span class="s">(</span><span class="i">$a</span><span class="cm">,</span> <span class="i">$b</span><span class="s">)</span></code>
.]]></desc>
</keyword>
<keyword name="chomp" type="function">
<params>
</params>
<desc><![CDATA[This safer version of <a href="../functions/chop.html">"chop"</a> removes any trailing string<br>
that corresponds to the current value of <code class="inline"><span class="i">$/</span></code>
(also known as<br>
$INPUT_RECORD_SEPARATOR in the <code class="inline"><span class="w">English</span></code>
module). It returns the total<br>
number of characters removed from all its arguments. It's often used to<br>
remove the newline from the end of an input record when you're worried<br>
that the final record may be missing its newline. When in paragraph<br>
mode (<code class="inline"><span class="i">$/</span> = <span class="q">""</span></code>
), it removes all trailing newlines from the string.<br>
When in slurp mode (<code class="inline"><span class="i">$/</span> = <a class="l_k" href="../functions/undef.html">undef</a></code>
) or fixed-length record mode (<code class="inline"><span class="i">$/</span></code>
is<br>
a reference to an integer or the like, see <a href="../perlvar.html">perlvar</a>) chomp() won't<br>
remove anything.<br>
If VARIABLE is omitted, it chomps <code class="inline"><span class="i">$_</span></code>
. Example:</p>
<pre class="verbatim"><ol><li> while <span class="s">(</span><><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/chomp.html">chomp</a><span class="sc">;</span> <span class="c"># avoid \n on last field</span></li><li> <span class="i">@array</span> = <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/:/</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c"># ...</span></li><li> <span class="s">}</span></li></ol></pre><p>If VARIABLE is a hash, it chomps the hash's values, but not its keys.</p>
<p>You can actually chomp anything that's an lvalue, including an assignment:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/chomp.html">chomp</a><span class="s">(</span><span class="i">$cwd</span> = <span class="q">`pwd`</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/chomp.html">chomp</a><span class="s">(</span><span class="i">$answer</span> = <span class="q"><STDIN></span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>If you chomp a list, each element is chomped, and the total number of<br>
characters removed is returned.</p>
<p>Note that parentheses are necessary when you're chomping anything<br>
that is not a simple variable. This is because <code class="inline"><a class="l_k" href="../functions/chomp.html">chomp</a> <span class="i">$cwd</span> = <span class="q">`pwd`</span><span class="sc">;</span></code>
<br>
is interpreted as <code class="inline"><span class="s">(</span><a class="l_k" href="../functions/chomp.html">chomp</a> <span class="i">$cwd</span><span class="s">)</span> = <span class="q">`pwd`</span><span class="sc">;</span></code>
, rather than as<br>
<code class="inline"><a class="l_k" href="../functions/chomp.html">chomp</a><span class="s">(</span> <span class="i">$cwd</span> = <span class="q">`pwd`</span> <span class="s">)</span></code>
which you might expect. Similarly,<br>
<code class="inline"><a class="l_k" href="../functions/chomp.html">chomp</a> <span class="i">$a</span><span class="cm">,</span> <span class="i">$b</span></code>
is interpreted as <code class="inline"><a class="l_k" href="../functions/chomp.html">chomp</a><span class="s">(</span><span class="i">$a</span><span class="s">)</span><span class="cm">,</span> <span class="i">$b</span></code>
rather than<br>
as <code class="inline"><a class="l_k" href="../functions/chomp.html">chomp</a><span class="s">(</span><span class="i">$a</span><span class="cm">,</span> <span class="i">$b</span><span class="s">)</span></code>
.]]></desc>
</keyword>
<keyword name="chop" type="function">
<params>
<param name='( list )'/>
</params>
<desc><![CDATA[Chops off the last character of a string and returns the character<br>
chopped. It is much more efficient than <code class="inline"><a class="l_k" href="../functions/s.html">s/.$//s</a></code> because it neither<br>
scans nor copies the string. If VARIABLE is omitted, chops <code class="inline"><span class="i">$_</span></code>
.<br>
If VARIABLE is a hash, it chops the hash's values, but not its keys.</p>
<p>You can actually chop anything that's an lvalue, including an assignment.</p>
<p>If you chop a list, each element is chopped. Only the value of the<br>
last <code class="inline"><a class="l_k" href="../functions/chop.html">chop</a></code> is returned.</p>
<p>Note that <code class="inline"><a class="l_k" href="../functions/chop.html">chop</a></code> returns the last character. To return all but the last<br>
character, use <code class="inline"><a class="l_k" href="../functions/substr.html">substr</a><span class="s">(</span><span class="i">$string</span><span class="cm">,</span> <span class="n">0</span><span class="cm">,</span> <span class="n">-1</span><span class="s">)</span></code>
.</p>
<p>See also <a href="../functions/chomp.html">"chomp"</a>.]]></desc>
</keyword>
<keyword name="chop" type="function">
<params>
<param name='variable'/>
</params>
<desc><![CDATA[Chops off the last character of a string and returns the character<br>
chopped. It is much more efficient than <code class="inline"><a class="l_k" href="../functions/s.html">s/.$//s</a></code> because it neither<br>
scans nor copies the string. If VARIABLE is omitted, chops <code class="inline"><span class="i">$_</span></code>
.<br>
If VARIABLE is a hash, it chops the hash's values, but not its keys.</p>
<p>You can actually chop anything that's an lvalue, including an assignment.</p>
<p>If you chop a list, each element is chopped. Only the value of the<br>
last <code class="inline"><a class="l_k" href="../functions/chop.html">chop</a></code> is returned.</p>
<p>Note that <code class="inline"><a class="l_k" href="../functions/chop.html">chop</a></code> returns the last character. To return all but the last<br>
character, use <code class="inline"><a class="l_k" href="../functions/substr.html">substr</a><span class="s">(</span><span class="i">$string</span><span class="cm">,</span> <span class="n">0</span><span class="cm">,</span> <span class="n">-1</span><span class="s">)</span></code>
.</p>
<p>See also <a href="../functions/chomp.html">"chomp"</a>.]]></desc>
</keyword>
<keyword name="chop" type="function">
<params>
</params>
<desc><![CDATA[Chops off the last character of a string and returns the character<br>
chopped. It is much more efficient than <code class="inline"><a class="l_k" href="../functions/s.html">s/.$//s</a></code> because it neither<br>
scans nor copies the string. If VARIABLE is omitted, chops <code class="inline"><span class="i">$_</span></code>
.<br>
If VARIABLE is a hash, it chops the hash's values, but not its keys.</p>
<p>You can actually chop anything that's an lvalue, including an assignment.</p>
<p>If you chop a list, each element is chopped. Only the value of the<br>
last <code class="inline"><a class="l_k" href="../functions/chop.html">chop</a></code> is returned.</p>
<p>Note that <code class="inline"><a class="l_k" href="../functions/chop.html">chop</a></code> returns the last character. To return all but the last<br>
character, use <code class="inline"><a class="l_k" href="../functions/substr.html">substr</a><span class="s">(</span><span class="i">$string</span><span class="cm">,</span> <span class="n">0</span><span class="cm">,</span> <span class="n">-1</span><span class="s">)</span></code>
.</p>
<p>See also <a href="../functions/chomp.html">"chomp"</a>.]]></desc>
</keyword>
<keyword name="chown" type="function">
<params>
<param name='list'/>
</params>
<desc><![CDATA[Changes the owner (and group) of a list of files. The first two<br>
elements of the list must be the <i>numeric</i> uid and gid, in that<br>
order. A value of -1 in either position is interpreted by most<br>
systems to leave that value unchanged. Returns the number of files<br>
successfully changed.</p>
<pre class="verbatim"><ol><li> <span class="i">$cnt</span> = <a class="l_k" href="../functions/chown.html">chown</a> <span class="i">$uid</span><span class="cm">,</span> <span class="i">$gid</span><span class="cm">,</span> <span class="q">'foo'</span><span class="cm">,</span> <span class="q">'bar'</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/chown.html">chown</a> <span class="i">$uid</span><span class="cm">,</span> <span class="i">$gid</span><span class="cm">,</span> <span class="i">@filenames</span><span class="sc">;</span></li></ol></pre><p>On systems that support fchown, you might pass file handles among the<br>
files. On systems that don't support fchown, passing file handles<br>
produces a fatal error at run time. The file handles must be passed<br>
as globs or references to be recognized. Barewords are considered<br>
file names.</p>
<p>Here's an example that looks up nonnumeric uids in the passwd file:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"User: "</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/chomp.html">chomp</a><span class="s">(</span><span class="i">$user</span> = <span class="q"><STDIN></span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Files: "</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/chomp.html">chomp</a><span class="s">(</span><span class="i">$pattern</span> = <span class="q"><STDIN></span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="s">(</span><span class="i">$login</span><span class="cm">,</span><span class="i">$pass</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="s">)</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$user</span><span class="s">)</span></li><li> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"$user not in passwd file"</span><span class="sc">;</span></li><li></li><li> <span class="i">@ary</span> = <a class="l_k" href="../functions/glob.html">glob</a><span class="s">(</span><span class="i">$pattern</span><span class="s">)</span><span class="sc">;</span> <span class="c"># expand filenames</span></li><li> <a class="l_k" href="../functions/chown.html">chown</a> <span class="i">$uid</span><span class="cm">,</span> <span class="i">$gid</span><span class="cm">,</span> <span class="i">@ary</span><span class="sc">;</span></li></ol></pre><p>On most systems, you are not allowed to change the ownership of the<br>
file unless you're the superuser, although you should be able to change<br>
the group to any of your secondary groups. On insecure systems, these<br>
restrictions may be relaxed, but this is not a portable assumption.<br>
On POSIX systems, you can detect this condition this way:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">POSIX</span> <span class="q">qw(sysconf _PC_CHOWN_RESTRICTED)</span><span class="sc">;</span></li><li> <span class="i">$can_chown_giveaway</span> = not <span class="i">sysconf</span><span class="s">(</span><span class="w">_PC_CHOWN_RESTRICTED</span><span class="s">)</span><span class="sc">;</span></li></ol><]]></desc>
</keyword>
<keyword name="chr" type="function">
<params>
<param name='number'/>
</params>
<desc><![CDATA[Returns the character represented by that NUMBER in the character set.<br>
For example, <code class="inline"><a class="l_k" href="../functions/chr.html">chr(65)</a></code> is <code class="inline"><span class="q">"A"</span></code>
in either ASCII or Unicode, and<br>
chr(0x263a) is a Unicode smiley face.</p>
<p>Negative values give the Unicode replacement character (chr(0xfffd)),<br>
except under the <a href="../bytes.html">bytes</a> pragma, where low eight bits of the value<br>
(truncated to an integer) are used.</p>
<p>If NUMBER is omitted, uses <code class="inline"><span class="i">$_</span></code>
.</p>
<p>For the reverse, use <a href="../functions/ord.html">"ord"</a>.</p>
<p>Note that characters from 128 to 255 (inclusive) are by default<br>
internally not encoded as UTF-8 for backward compatibility reasons.</p>
<p>See <a href="../perlunicode.html">perlunicode</a> for more about Unicode.]]></desc>
</keyword>
<keyword name="chr" type="function">
<params>
</params>
<desc><![CDATA[Returns the character represented by that NUMBER in the character set.<br>
For example, <code class="inline"><a class="l_k" href="../functions/chr.html">chr(65)</a></code> is <code class="inline"><span class="q">"A"</span></code>
in either ASCII or Unicode, and<br>
chr(0x263a) is a Unicode smiley face.</p>
<p>Negative values give the Unicode replacement character (chr(0xfffd)),<br>
except under the <a href="../bytes.html">bytes</a> pragma, where low eight bits of the value<br>
(truncated to an integer) are used.</p>
<p>If NUMBER is omitted, uses <code class="inline"><span class="i">$_</span></code>
.</p>
<p>For the reverse, use <a href="../functions/ord.html">"ord"</a>.</p>
<p>Note that characters from 128 to 255 (inclusive) are by default<br>
internally not encoded as UTF-8 for backward compatibility reasons.</p>
<p>See <a href="../perlunicode.html">perlunicode</a> for more about Unicode.]]></desc>
</keyword>
<keyword name="chroot" type="function">
<params>
<param name='filename'/>
</params>
<desc><![CDATA[This function works like the system call by the same name: it makes the<br>
named directory the new root directory for all further pathnames that<br>
begin with a <code class="inline">/</code> by your process and all its children. (It doesn't<br>
change your current working directory, which is unaffected.) For security<br>
reasons, this call is restricted to the superuser. If FILENAME is<br>
omitted, does a <code class="inline"><a class="l_k" href="../functions/chroot.html">chroot</a></code> to <code class="inline"><span class="i">$_</span></code>
.]]></desc>
</keyword>
<keyword name="chroot" type="function">
<params>
</params>
<desc><![CDATA[This function works like the system call by the same name: it makes the<br>
named directory the new root directory for all further pathnames that<br>
begin with a <code class="inline">/</code> by your process and all its children. (It doesn't<br>
change your current working directory, which is unaffected.) For security<br>
reasons, this call is restricted to the superuser. If FILENAME is<br>
omitted, does a <code class="inline"><a class="l_k" href="../functions/chroot.html">chroot</a></code> to <code class="inline"><span class="i">$_</span></code>
.]]></desc>
</keyword>
<keyword name="close" type="function">
<params>
<param name='filehandle'/>
</params>
<desc><![CDATA[Closes the file or pipe associated with the file handle, flushes the IO<br>
buffers, and closes the system file descriptor. Returns true if those<br>
operations have succeeded and if no error was reported by any PerlIO<br>
layer. Closes the currently selected filehandle if the argument is<br>
omitted.</p>
<p>You don't have to close FILEHANDLE if you are immediately going to do<br>
another <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> on it, because <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> will close it for you. (See<br>
<code class="inline"><a class="l_k" href="../functions/open.html">open</a></code>.) However, an explicit <code class="inline"><a class="l_k" href="../functions/close.html">close</a></code> on an input file resets the line<br>
counter (<code class="inline"><span class="i">$.</span></code>
), while the implicit close done by <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> does not.</p>
<p>If the file handle came from a piped open, <code class="inline"><a class="l_k" href="../functions/close.html">close</a></code> will additionally<br>
return false if one of the other system calls involved fails, or if the<br>
program exits with non-zero status. (If the only problem was that the<br>
program exited non-zero, <code class="inline"><span class="i">$!</span></code>
will be set to <code class="inline"><span class="n">0</span></code>
.) Closing a pipe<br>
also waits for the process executing on the pipe to complete, in case you<br>
want to look at the output of the pipe afterwards, and<br>
implicitly puts the exit status value of that command into <code class="inline"><span class="i">$?</span></code>
and<br>
<code class="inline"><span class="i">$</span>{<span class="w">^CHILD_ERROR_NATIVE</span>}</code>
.</p>
<p>Prematurely closing the read end of a pipe (i.e. before the process<br>
writing to it at the other end has closed it) will result in a<br>
SIGPIPE being delivered to the writer. If the other end can't<br>
handle that, be sure to read all the data before closing the pipe.</p>
<p>Example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">OUTPUT</span><span class="cm">,</span> <span class="q">'|sort >foo'</span><span class="s">)</span> <span class="c"># pipe to sort</span></li><li> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't start sort: $!"</span><span class="sc">;</span></li><li> <span class="c">#... # print stuff to output</span></li><li> <a class="l_k" href="../functions/close.html">close</a> <span class="w">OUTPUT</span> <span class="c"># wait for sort to finish</span></li><li> or <a class="l_k" href="../functions/warn.html">warn</a> <span class="i">$!</span> ? <span class="q">"Error closing sort pipe: $!"</span></li><li> <span class="co">:</span> <span class="q">"Exit status $? from sort"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">INPUT</span><span class="cm">,</span> <span class="q">'foo'</span><span class="s">)</span> <span class="c"># get sort's results</span></li><li> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't open 'foo' for input: $!"</span><span class="sc">;</span></li></ol></pre><p>FILEHANDLE may be an expression whose value can be used as an indirect<br>
filehandle, usually the real filehandle name.]]></desc>
</keyword>
<keyword name="close" type="function">
<params>
</params>
<desc><![CDATA[Closes the file or pipe associated with the file handle, flushes the IO<br>
buffers, and closes the system file descriptor. Returns true if those<br>
operations have succeeded and if no error was reported by any PerlIO<br>
layer. Closes the currently selected filehandle if the argument is<br>
omitted.</p>
<p>You don't have to close FILEHANDLE if you are immediately going to do<br>
another <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> on it, because <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> will close it for you. (See<br>
<code class="inline"><a class="l_k" href="../functions/open.html">open</a></code>.) However, an explicit <code class="inline"><a class="l_k" href="../functions/close.html">close</a></code> on an input file resets the line<br>
counter (<code class="inline"><span class="i">$.</span></code>
), while the implicit close done by <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> does not.</p>
<p>If the file handle came from a piped open, <code class="inline"><a class="l_k" href="../functions/close.html">close</a></code> will additionally<br>
return false if one of the other system calls involved fails, or if the<br>
program exits with non-zero status. (If the only problem was that the<br>
program exited non-zero, <code class="inline"><span class="i">$!</span></code>
will be set to <code class="inline"><span class="n">0</span></code>
.) Closing a pipe<br>
also waits for the process executing on the pipe to complete, in case you<br>
want to look at the output of the pipe afterwards, and<br>
implicitly puts the exit status value of that command into <code class="inline"><span class="i">$?</span></code>
and<br>
<code class="inline"><span class="i">$</span>{<span class="w">^CHILD_ERROR_NATIVE</span>}</code>
.</p>
<p>Prematurely closing the read end of a pipe (i.e. before the process<br>
writing to it at the other end has closed it) will result in a<br>
SIGPIPE being delivered to the writer. If the other end can't<br>
handle that, be sure to read all the data before closing the pipe.</p>
<p>Example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">OUTPUT</span><span class="cm">,</span> <span class="q">'|sort >foo'</span><span class="s">)</span> <span class="c"># pipe to sort</span></li><li> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't start sort: $!"</span><span class="sc">;</span></li><li> <span class="c">#... # print stuff to output</span></li><li> <a class="l_k" href="../functions/close.html">close</a> <span class="w">OUTPUT</span> <span class="c"># wait for sort to finish</span></li><li> or <a class="l_k" href="../functions/warn.html">warn</a> <span class="i">$!</span> ? <span class="q">"Error closing sort pipe: $!"</span></li><li> <span class="co">:</span> <span class="q">"Exit status $? from sort"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">INPUT</span><span class="cm">,</span> <span class="q">'foo'</span><span class="s">)</span> <span class="c"># get sort's results</span></li><li> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't open 'foo' for input: $!"</span><span class="sc">;</span></li></ol></pre><p>FILEHANDLE may be an expression whose value can be used as an indirect<br>
filehandle, usually the real filehandle name.]]></desc>
</keyword>
<keyword name="closedir" type="function">
<params>
<param name='dirhandle'/>
</params>
<desc><![CDATA[Closes a directory opened by <code class="inline"><a class="l_k" href="../functions/opendir.html">opendir</a></code> and returns the success of that<br>
system call.]]></desc>
</keyword>
<keyword name="connect" type="function">
<params>
<param name='socket'/>
<param name='name'/>
</params>
<desc><![CDATA[Attempts to connect to a remote socket, just as the connect system call<br>
does. Returns true if it succeeded, false otherwise. NAME should be a<br>
packed address of the appropriate type for the socket. See the examples in<br>
<a href="../perlipc.html#Sockets%3a-Client%2fServer-Communication">"Sockets: Client/Server Communication" in perlipc</a>.]]></desc>
</keyword>
<keyword name="continue" type="function">
<params>
<param name='block'/>
</params>
<desc><![CDATA[<code class="inline"><a class="l_k" href="../functions/continue.html">continue</a></code> is actually a flow control statement rather than a function. If<br>
there is a <code class="inline"><a class="l_k" href="../functions/continue.html">continue</a></code> BLOCK attached to a BLOCK (typically in a <code class="inline">while</code>
or<br>
<code class="inline">foreach</code>
), it is always executed just before the conditional is about to<br>
be evaluated again, just like the third part of a <code class="inline">for</code>
loop in C. Thus<br>
it can be used to increment a loop variable, even when the loop has been<br>
continued via the <code class="inline"><a class="l_k" href="../functions/next.html">next</a></code> statement (which is similar to the C <code class="inline"><a class="l_k" href="../functions/continue.html">continue</a></code>
statement).</p>
<p><code class="inline"><a class="l_k" href="../functions/last.html">last</a></code>, <code class="inline"><a class="l_k" href="../functions/next.html">next</a></code>, or <code class="inline"><a class="l_k" href="../functions/redo.html">redo</a></code> may appear within a <code class="inline"><a class="l_k" href="../functions/continue.html">continue</a></code>
block. <code class="inline"><a class="l_k" href="../functions/last.html">last</a></code> and <code class="inline"><a class="l_k" href="../functions/redo.html">redo</a></code> will behave as if they had been executed within<br>
the main block. So will <code class="inline"><a class="l_k" href="../functions/next.html">next</a></code>, but since it will execute a <code class="inline"><a class="l_k" href="../functions/continue.html">continue</a></code>
block, it may be more entertaining.</p>
<pre class="verbatim"><ol><li> while <span class="s">(</span><span class="w">EXPR</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="c">### redo always comes here</span></li><li> <span class="w">do_something</span><span class="sc">;</span></li><li> <span class="s">}</span> <a class="l_k" href="../functions/continue.html">continue</a> <span class="s">{</span></li><li> <span class="c">### next always comes here</span></li><li> <span class="w">do_something_else</span><span class="sc">;</span></li><li> <span class="c"># then back the top to re-check EXPR</span></li><li> <span class="s">}</span></li><li> <span class="c">### last always comes here</span></li></ol></pre><p>Omitting the <code class="inline"><a class="l_k" href="../functions/continue.html">continue</a></code> section is semantically equivalent to using an<br>
empty one, logically enough. In that case, <code class="inline"><a class="l_k" href="../functions/next.html">next</a></code> goes directly back<br>
to check the condition at the top of the loop.</p>
<p>If the "switch" feature is enabled, <code class="inline"><a class="l_k" href="../functions/continue.html">continue</a></code> is also a<br>
function that will break out of the current <code class="inline">when</code>
or <code class="inline"><span class="w">default</span></code>
<br>
block, and fall through to the next case. See <a href="../feature.html">feature</a> and<br>
<a href="../perlsyn.html#Switch-statements">"Switch statements" in perlsyn</a> for more information.]]></desc>
</keyword>
<keyword name="continue" type="function">
<params>
</params>
<desc><![CDATA[<code class="inline"><a class="l_k" href="../functions/continue.html">continue</a></code> is actually a flow control statement rather than a function. If<br>
there is a <code class="inline"><a class="l_k" href="../functions/continue.html">continue</a></code> BLOCK attached to a BLOCK (typically in a <code class="inline">while</code>
or<br>
<code class="inline">foreach</code>
), it is always executed just before the conditional is about to<br>
be evaluated again, just like the third part of a <code class="inline">for</code>
loop in C. Thus<br>
it can be used to increment a loop variable, even when the loop has been<br>
continued via the <code class="inline"><a class="l_k" href="../functions/next.html">next</a></code> statement (which is similar to the C <code class="inline"><a class="l_k" href="../functions/continue.html">continue</a></code>
statement).</p>
<p><code class="inline"><a class="l_k" href="../functions/last.html">last</a></code>, <code class="inline"><a class="l_k" href="../functions/next.html">next</a></code>, or <code class="inline"><a class="l_k" href="../functions/redo.html">redo</a></code> may appear within a <code class="inline"><a class="l_k" href="../functions/continue.html">continue</a></code>
block. <code class="inline"><a class="l_k" href="../functions/last.html">last</a></code> and <code class="inline"><a class="l_k" href="../functions/redo.html">redo</a></code> will behave as if they had been executed within<br>
the main block. So will <code class="inline"><a class="l_k" href="../functions/next.html">next</a></code>, but since it will execute a <code class="inline"><a class="l_k" href="../functions/continue.html">continue</a></code>
block, it may be more entertaining.</p>
<pre class="verbatim"><ol><li> while <span class="s">(</span><span class="w">EXPR</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="c">### redo always comes here</span></li><li> <span class="w">do_something</span><span class="sc">;</span></li><li> <span class="s">}</span> <a class="l_k" href="../functions/continue.html">continue</a> <span class="s">{</span></li><li> <span class="c">### next always comes here</span></li><li> <span class="w">do_something_else</span><span class="sc">;</span></li><li> <span class="c"># then back the top to re-check EXPR</span></li><li> <span class="s">}</span></li><li> <span class="c">### last always comes here</span></li></ol></pre><p>Omitting the <code class="inline"><a class="l_k" href="../functions/continue.html">continue</a></code> section is semantically equivalent to using an<br>
empty one, logically enough. In that case, <code class="inline"><a class="l_k" href="../functions/next.html">next</a></code> goes directly back<br>
to check the condition at the top of the loop.</p>
<p>If the "switch" feature is enabled, <code class="inline"><a class="l_k" href="../functions/continue.html">continue</a></code> is also a<br>
function that will break out of the current <code class="inline">when</code>
or <code class="inline"><span class="w">default</span></code>
<br>
block, and fall through to the next case. See <a href="../feature.html">feature</a> and<br>
<a href="../perlsyn.html#Switch-statements">"Switch statements" in perlsyn</a> for more information.]]></desc>
</keyword>
<keyword name="cos" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Returns the cosine of EXPR (expressed in radians). If EXPR is omitted,<br>
takes cosine of <code class="inline"><span class="i">$_</span></code>
.</p>
<p>For the inverse cosine operation, you may use the <code class="inline"><span class="i">Math::Trig::acos</span><span class="s">(</span><span class="s">)</span></code>
<br>
function, or use this relation:</p>
<pre class="verbatim"><ol><li><a name="acos"></a> sub <span class="m">acos</span> <span class="s">{</span> <a class="l_k" href="../functions/atan2.html">atan2</a><span class="s">(</span> <a class="l_k" href="../functions/sqrt.html">sqrt</a><span class="s">(</span><span class="n">1</span> - <span class="i">$_</span>[<span class="n">0</span>] * <span class="i">$_</span>[<span class="n">0</span>]<span class="s">)</span><span class="cm">,</span> <span class="i">$_</span>[<span class="n">0</span>] <span class="s">)</span> <span class="s">}</span></li></ol><]]></desc>
</keyword>
<keyword name="cos" type="function">
<params>
</params>
<desc><![CDATA[Returns the cosine of EXPR (expressed in radians). If EXPR is omitted,<br>
takes cosine of <code class="inline"><span class="i">$_</span></code>
.</p>
<p>For the inverse cosine operation, you may use the <code class="inline"><span class="i">Math::Trig::acos</span><span class="s">(</span><span class="s">)</span></code>
<br>
function, or use this relation:</p>
<pre class="verbatim"><ol><li><a name="acos"></a> sub <span class="m">acos</span> <span class="s">{</span> <a class="l_k" href="../functions/atan2.html">atan2</a><span class="s">(</span> <a class="l_k" href="../functions/sqrt.html">sqrt</a><span class="s">(</span><span class="n">1</span> - <span class="i">$_</span>[<span class="n">0</span>] * <span class="i">$_</span>[<span class="n">0</span>]<span class="s">)</span><span class="cm">,</span> <span class="i">$_</span>[<span class="n">0</span>] <span class="s">)</span> <span class="s">}</span></li></ol><]]></desc>
</keyword>
<keyword name="crypt" type="function">
<params>
<param name='plaintext'/>
<param name='salt'/>
</params>
<desc><![CDATA[</p>
<p>Creates a digest string exactly like the crypt(3) function in the C<br>
library (assuming that you actually have a version there that has not<br>
been extirpated as a potential munition).</p>
<p>crypt() is a one-way hash function. The PLAINTEXT and SALT is turned<br>
into a short string, called a digest, which is returned. The same<br>
PLAINTEXT and SALT will always return the same string, but there is no<br>
(known) way to get the original PLAINTEXT from the hash. Small<br>
changes in the PLAINTEXT or SALT will result in large changes in the<br>
digest.</p>
<p>There is no decrypt function. This function isn't all that useful for<br>
cryptography (for that, look for <i>Crypt</i> modules on your nearby CPAN<br>
mirror) and the name "crypt" is a bit of a misnomer. Instead it is<br>
primarily used to check if two pieces of text are the same without<br>
having to transmit or store the text itself. An example is checking<br>
if a correct password is given. The digest of the password is stored,<br>
not the password itself. The user types in a password that is<br>
crypt()'d with the same salt as the stored digest. If the two digests<br>
match the password is correct.</p>
<p>When verifying an existing digest string you should use the digest as<br>
the salt (like <code class="inline"><a class="l_k" href="../functions/crypt.html">crypt</a><span class="s">(</span><span class="i">$plain</span><span class="cm">,</span> <span class="i">$digest</span><span class="s">)</span> eq <span class="i">$digest</span></code>
). The SALT used<br>
to create the digest is visible as part of the digest. This ensures<br>
crypt() will hash the new string with the same salt as the digest.<br>
This allows your code to work with the standard <a href="../functions/crypt.html">crypt</a> and<br>
with more exotic implementations. In other words, do not assume<br>
anything about the returned string itself, or how many bytes in the<br>
digest matter.</p>
<p>Traditionally the result is a string of 13 bytes: two first bytes of<br>
the salt, followed by 11 bytes from the set <code class="inline">[./0-9A-Za-z]</code>, and only<br>
the first eight bytes of PLAINTEXT mattered. But alternative<br>
hashing schemes (like MD5), higher level security schemes (like C2),<br>
and implementations on non-UNIX platforms may produce different<br>
strings.</p>
<p>When choosing a new salt create a random two character string whose<br>
characters come from the set <code class="inline">[./0-9A-Za-z]</code> (like <code class="inline"><a class="l_k" href="../functions/join.html">join</a> <span class="q">''</span><span class="cm">,</span> <span class="s">(</span><span class="q">'.'</span><span class="cm">,</span>
<span class="q">'/'</span><span class="cm">,</span> <span class="n">0</span>..<span class="n">9</span><span class="cm">,</span> <span class="q">'A'</span>..<span class="q">'Z'</span><span class="cm">,</span> <span class="q">'a'</span>..<span class="q">'z'</span><span class="s">)</span>[<a class="l_k" href="../functions/rand.html">rand</a> <span class="n">64</span><span class="cm">,</span> <a class="l_k" href="../functions/rand.html">rand</a> <span class="n">64</span>]</code>
). This set of<br>
characters is just a recommendation; the characters allowed in<br>
the salt depend solely on your system's crypt library, and Perl can't<br>
restrict what salts <code class="inline"><a class="l_k" href="../functions/crypt.html">crypt()</a></code> accepts.</p>
<p>Here's an example that makes sure that whoever runs this program knows<br>
their password:</p>
<pre class="verbatim"><ol><li> <span class="i">$pwd</span> = <span class="s">(</span><a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$<</span><span class="s">)</span><span class="s">)</span>[<span class="n">1</span>]<span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/system.html">system</a> <span class="q">"stty -echo"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Password: "</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/chomp.html">chomp</a><span class="s">(</span><span class="i">$word</span> = <span class="q"><STDIN></span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"\n"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/system.html">system</a> <span class="q">"stty echo"</span><span class="sc">;</span></li><li></li><li> if <span class="s">(</span><a class="l_k" href="../functions/crypt.html">crypt</a><span class="s">(</span><span class="i">$word</span><span class="cm">,</span> <span class="i">$pwd</span><span class="s">)</span> ne <span class="i">$pwd</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Sorry...\n"</span><span class="sc">;</span></li><li> <span class="s">}</span> else <span class="s">{</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"ok\n"</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Of course, typing in your own password to whoever asks you<br>
for it is unwise.</p>
<p>The <a href="../functions/crypt.html">crypt</a> function is unsuitable for hashing large quantities<br>
of data, not least of all because you can't get the information<br>
back. Look at the <a href="../Digest.html">Digest</a> module for more robust algorithms.</p>
<p>If using crypt() on a Unicode string (which <i>potentially</i> has<br>
characters with codepoints above 255), Perl tries to make sense<br>
of the situation by trying to downgrade (a copy of the string)<br>
the string back to an eight-bit byte string before calling crypt()<br>
(on that copy). If that works, good. If not, crypt() dies with<br>
<code class="inline"><span class="w">Wide</span> <span class="w">character</span> <span class="w">in</span> <a class="l_k" href="../functions/crypt.html">crypt</a></code>
.]]></desc>
</keyword>
<keyword name="dbmclose" type="function">
<params>
<param name='hash'/>
</params>
<desc><![CDATA[[This function has been largely superseded by the <code class="inline"><a class="l_k" href="../functions/untie.html">untie</a></code> function.]</p>
<p>Breaks the binding between a DBM file and a hash.]]></desc>
</keyword>
<keyword name="dbmopen" type="function">
<params>
<param name='hash'/>
<param name='dbname'/>
<param name='mask'/>
</params>
<desc><![CDATA[[This function has been largely superseded by the <code class="inline"><a class="l_k" href="../functions/tie.html">tie</a></code> function.]</p>
<p>This binds a dbm(3), ndbm(3), sdbm(3), gdbm(3), or Berkeley DB file to a<br>
hash. HASH is the name of the hash. (Unlike normal <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code>, the first<br>
argument is <i>not</i> a filehandle, even though it looks like one). DBNAME<br>
is the name of the database (without the <i>.dir</i> or <i>.pag</i> extension if<br>
any). If the database does not exist, it is created with protection<br>
specified by MASK (as modified by the <code class="inline"><a class="l_k" href="../functions/umask.html">umask</a></code>). If your system supports<br>
only the older DBM functions, you may perform only one <code class="inline"><a class="l_k" href="../functions/dbmopen.html">dbmopen</a></code> in your<br>
program. In older versions of Perl, if your system had neither DBM nor<br>
ndbm, calling <code class="inline"><a class="l_k" href="../functions/dbmopen.html">dbmopen</a></code> produced a fatal error; it now falls back to<br>
sdbm(3).</p>
<p>If you don't have write access to the DBM file, you can only read hash<br>
variables, not set them. If you want to test whether you can write,<br>
either use file tests or try setting a dummy hash entry inside an <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a></code>,<br>
which will trap the error.</p>
<p>Note that functions such as <code class="inline"><a class="l_k" href="../functions/keys.html">keys</a></code> and <code class="inline"><a class="l_k" href="../functions/values.html">values</a></code> may return huge lists<br>
when used on large DBM files. You may prefer to use the <code class="inline"><a class="l_k" href="../functions/each.html">each</a></code>
function to iterate over large DBM files. Example:</p>
<pre class="verbatim"><ol><li> <span class="c"># print out history file offsets</span></li><li> <a class="l_k" href="../functions/dbmopen.html">dbmopen</a><span class="s">(</span><span class="i">%HIST</span><span class="cm">,</span><span class="q">'/usr/lib/news/history'</span><span class="cm">,</span><span class="n">0666</span><span class="s">)</span><span class="sc">;</span></li><li> while <span class="s">(</span><span class="s">(</span><span class="i">$key</span><span class="cm">,</span><span class="i">$val</span><span class="s">)</span> = <a class="l_k" href="../functions/each.html">each</a> <span class="i">%HIST</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$key</span><span class="cm">,</span> <span class="q">' = '</span><span class="cm">,</span> <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'L'</span><span class="cm">,</span><span class="i">$val</span><span class="s">)</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> <a class="l_k" href="../functions/dbmclose.html">dbmclose</a><span class="s">(</span><span class="i">%HIST</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>See also <a href="../AnyDBM_File.html">AnyDBM_File</a> for a more general description of the pros and<br>
cons of the various dbm approaches, as well as <a href="../DB_File.html">DB_File</a> for a particularly<br>
rich implementation.</p>
<p>You can control which DBM library you use by loading that library<br>
before you call dbmopen():</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">DB_File</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/dbmopen.html">dbmopen</a><span class="s">(</span><span class="i">%NS_Hist</span><span class="cm">,</span> <span class="q">"$ENV{HOME}/.netscape/history.db"</span><span class="s">)</span></li><li> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't open netscape history file: $!"</span><span class="sc">;</span></li></ol><]]></desc>
</keyword>
<keyword name="defined" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Returns a Boolean value telling whether EXPR has a value other than<br>
the undefined value <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code>. If EXPR is not present, <code class="inline"><span class="i">$_</span></code>
will be<br>
checked.</p>
<p>Many operations return <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> to indicate failure, end of file,<br>
system error, uninitialized variable, and other exceptional<br>
conditions. This function allows you to distinguish <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> from<br>
other values. (A simple Boolean test will not distinguish among<br>
<code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code>, zero, the empty string, and <code class="inline"><span class="q">"0"</span></code>
, which are all equally<br>
false.) Note that since <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> is a valid scalar, its presence<br>
doesn't <i>necessarily</i> indicate an exceptional condition: <code class="inline"><a class="l_k" href="../functions/pop.html">pop</a></code>
returns <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> when its argument is an empty array, <i>or</i> when the<br>
element to return happens to be <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code>.</p>
<p>You may also use <code class="inline"><a class="l_k" href="../functions/defined.html">defined(&func)</a></code> to check whether subroutine <code class="inline"><span class="i">&func</span></code>
<br>
has ever been defined. The return value is unaffected by any forward<br>
declarations of <code class="inline"><span class="i">&func</span></code>
. Note that a subroutine which is not defined<br>
may still be callable: its package may have an <code class="inline">AUTOLOAD</code>
method that<br>
makes it spring into existence the first time that it is called -- see<br>
<a href="../perlsub.html">perlsub</a>.</p>
<p>Use of <code class="inline"><a class="l_k" href="../functions/defined.html">defined</a></code> on aggregates (hashes and arrays) is deprecated. It<br>
used to report whether memory for that aggregate has ever been<br>
allocated. This behavior may disappear in future versions of Perl.<br>
You should instead use a simple test for size:</p>
<pre class="verbatim"><ol><li> if <span class="s">(</span><span class="i">@an_array</span><span class="s">)</span> <span class="s">{</span> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"has array elements\n"</span> <span class="s">}</span></li><li> if <span class="s">(</span><span class="i">%a_hash</span><span class="s">)</span> <span class="s">{</span> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"has hash members\n"</span> <span class="s">}</span></li></ol></pre><p>When used on a hash element, it tells you whether the value is defined,<br>
not whether the key exists in the hash. Use <a href="../functions/exists.html">"exists"</a> for the latter<br>
purpose.</p>
<p>Examples:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> if <a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$switch</span>{<span class="q">'D'</span>}<span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"$val\n"</span> while <a class="l_k" href="../functions/defined.html">defined</a><span class="s">(</span><span class="i">$val</span> = <a class="l_k" href="../functions/pop.html">pop</a><span class="s">(</span><span class="i">@ary</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't readlink $sym: $!"</span></li><li> unless <a class="l_k" href="../functions/defined.html">defined</a><span class="s">(</span><span class="i">$value</span> = <a class="l_k" href="../functions/readlink.html">readlink</a> <span class="i">$sym</span><span class="s">)</span><span class="sc">;</span></li><li><a name="foo"></a> sub <span class="m">foo</span> <span class="s">{</span> <a class="l_k" href="../functions/defined.html">defined</a> <span class="i">&$bar</span> ? <span class="i">&$bar</span><span class="s">(</span><span class="i">@_</span><span class="s">)</span> <span class="co">:</span> <a class="l_k" href="../functions/die.html">die</a> <span class="q">"No bar"</span><span class="sc">;</span> <span class="s">}</span></li><li> <span class="i">$debugging</span> = <span class="n">0</span> unless <a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$debugging</span><span class="sc">;</span></li></ol></pre><p>Note: Many folks tend to overuse <code class="inline"><a class="l_k" href="../functions/defined.html">defined</a></code>, and then are surprised to<br>
discover that the number <code class="inline"><span class="n">0</span></code>
and <code class="inline"><span class="q">""</span></code>
(the zero-length string) are, in fact,<br>
defined values. For example, if you say</p>
<pre class="verbatim"><ol><li> <span class="q">"ab"</span> =~ <span class="q">/a(.*)b/</span><span class="sc">;</span></li></ol></pre><p>The pattern match succeeds, and <code class="inline"><span class="i">$1</span></code>
is defined, despite the fact that it<br>
matched "nothing". It didn't really fail to match anything. Rather, it<br>
matched something that happened to be zero characters long. This is all<br>
very above-board and honest. When a function returns an undefined value,<br>
it's an admission that it couldn't give you an honest answer. So you<br>
should use <code class="inline"><a class="l_k" href="../functions/defined.html">defined</a></code> only when you're questioning the integrity of what<br>
you're trying to do. At other times, a simple comparison to <code class="inline"><span class="n">0</span></code>
or <code class="inline"><span class="q">""</span></code>
is<br>
what you want.</p>
<p>See also <a href="../functions/undef.html">"undef"</a>, <a href="../functions/exists.html">"exists"</a>, <a href="../functions/ref.html">"ref"</a>.]]></desc>
</keyword>
<keyword name="defined" type="function">
<params>
</params>
<desc><![CDATA[Returns a Boolean value telling whether EXPR has a value other than<br>
the undefined value <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code>. If EXPR is not present, <code class="inline"><span class="i">$_</span></code>
will be<br>
checked.</p>
<p>Many operations return <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> to indicate failure, end of file,<br>
system error, uninitialized variable, and other exceptional<br>
conditions. This function allows you to distinguish <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> from<br>
other values. (A simple Boolean test will not distinguish among<br>
<code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code>, zero, the empty string, and <code class="inline"><span class="q">"0"</span></code>
, which are all equally<br>
false.) Note that since <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> is a valid scalar, its presence<br>
doesn't <i>necessarily</i> indicate an exceptional condition: <code class="inline"><a class="l_k" href="../functions/pop.html">pop</a></code>
returns <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> when its argument is an empty array, <i>or</i> when the<br>
element to return happens to be <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code>.</p>
<p>You may also use <code class="inline"><a class="l_k" href="../functions/defined.html">defined(&func)</a></code> to check whether subroutine <code class="inline"><span class="i">&func</span></code>
<br>
has ever been defined. The return value is unaffected by any forward<br>
declarations of <code class="inline"><span class="i">&func</span></code>
. Note that a subroutine which is not defined<br>
may still be callable: its package may have an <code class="inline">AUTOLOAD</code>
method that<br>
makes it spring into existence the first time that it is called -- see<br>
<a href="../perlsub.html">perlsub</a>.</p>
<p>Use of <code class="inline"><a class="l_k" href="../functions/defined.html">defined</a></code> on aggregates (hashes and arrays) is deprecated. It<br>
used to report whether memory for that aggregate has ever been<br>
allocated. This behavior may disappear in future versions of Perl.<br>
You should instead use a simple test for size:</p>
<pre class="verbatim"><ol><li> if <span class="s">(</span><span class="i">@an_array</span><span class="s">)</span> <span class="s">{</span> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"has array elements\n"</span> <span class="s">}</span></li><li> if <span class="s">(</span><span class="i">%a_hash</span><span class="s">)</span> <span class="s">{</span> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"has hash members\n"</span> <span class="s">}</span></li></ol></pre><p>When used on a hash element, it tells you whether the value is defined,<br>
not whether the key exists in the hash. Use <a href="../functions/exists.html">"exists"</a> for the latter<br>
purpose.</p>
<p>Examples:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> if <a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$switch</span>{<span class="q">'D'</span>}<span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"$val\n"</span> while <a class="l_k" href="../functions/defined.html">defined</a><span class="s">(</span><span class="i">$val</span> = <a class="l_k" href="../functions/pop.html">pop</a><span class="s">(</span><span class="i">@ary</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't readlink $sym: $!"</span></li><li> unless <a class="l_k" href="../functions/defined.html">defined</a><span class="s">(</span><span class="i">$value</span> = <a class="l_k" href="../functions/readlink.html">readlink</a> <span class="i">$sym</span><span class="s">)</span><span class="sc">;</span></li><li><a name="foo"></a> sub <span class="m">foo</span> <span class="s">{</span> <a class="l_k" href="../functions/defined.html">defined</a> <span class="i">&$bar</span> ? <span class="i">&$bar</span><span class="s">(</span><span class="i">@_</span><span class="s">)</span> <span class="co">:</span> <a class="l_k" href="../functions/die.html">die</a> <span class="q">"No bar"</span><span class="sc">;</span> <span class="s">}</span></li><li> <span class="i">$debugging</span> = <span class="n">0</span> unless <a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$debugging</span><span class="sc">;</span></li></ol></pre><p>Note: Many folks tend to overuse <code class="inline"><a class="l_k" href="../functions/defined.html">defined</a></code>, and then are surprised to<br>
discover that the number <code class="inline"><span class="n">0</span></code>
and <code class="inline"><span class="q">""</span></code>
(the zero-length string) are, in fact,<br>
defined values. For example, if you say</p>
<pre class="verbatim"><ol><li> <span class="q">"ab"</span> =~ <span class="q">/a(.*)b/</span><span class="sc">;</span></li></ol></pre><p>The pattern match succeeds, and <code class="inline"><span class="i">$1</span></code>
is defined, despite the fact that it<br>
matched "nothing". It didn't really fail to match anything. Rather, it<br>
matched something that happened to be zero characters long. This is all<br>
very above-board and honest. When a function returns an undefined value,<br>
it's an admission that it couldn't give you an honest answer. So you<br>
should use <code class="inline"><a class="l_k" href="../functions/defined.html">defined</a></code> only when you're questioning the integrity of what<br>
you're trying to do. At other times, a simple comparison to <code class="inline"><span class="n">0</span></code>
or <code class="inline"><span class="q">""</span></code>
is<br>
what you want.</p>
<p>See also <a href="../functions/undef.html">"undef"</a>, <a href="../functions/exists.html">"exists"</a>, <a href="../functions/ref.html">"ref"</a>.]]></desc>
</keyword>
<keyword name="delete" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Given an expression that specifies a hash element, array element, hash slice,<br>
or array slice, deletes the specified element(s) from the hash or array.<br>
In the case of an array, if the array elements happen to be at the end,<br>
the size of the array will shrink to the highest element that tests<br>
true for exists() (or 0 if no such element exists).</p>
<p>Returns a list with the same number of elements as the number of elements<br>
for which deletion was attempted. Each element of that list consists of<br>
either the value of the element deleted, or the undefined value. In scalar<br>
context, this means that you get the value of the last element deleted (or<br>
the undefined value if that element did not exist).</p>
<pre class="verbatim"><ol><li> <span class="i">%hash</span> = <span class="s">(</span><span class="w">foo</span> <span class="cm">=></span> <span class="n">11</span><span class="cm">,</span> <span class="w">bar</span> <span class="cm">=></span> <span class="n">22</span><span class="cm">,</span> <span class="w">baz</span> <span class="cm">=></span> <span class="n">33</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$scalar</span> = <a class="l_k" href="../functions/delete.html">delete</a> <span class="i">$hash</span>{<span class="w">foo</span>}<span class="sc">;</span> <span class="c"># $scalar is 11</span></li><li> <span class="i">$scalar</span> = <a class="l_k" href="../functions/delete.html">delete</a> <span class="i">@hash</span>{<span class="q">qw(foo bar)</span>}<span class="sc">;</span> <span class="c"># $scalar is 22</span></li><li> <span class="i">@array</span> = <a class="l_k" href="../functions/delete.html">delete</a> <span class="i">@hash</span>{<span class="q">qw(foo bar baz)</span>}<span class="sc">;</span> <span class="c"># @array is (undef,undef,33)</span></li></ol></pre><p>Deleting from <code class="inline"><span class="i">%ENV</span></code>
modifies the environment. Deleting from<br>
a hash tied to a DBM file deletes the entry from the DBM file. Deleting<br>
from a <code class="inline"><a class="l_k" href="../functions/tie.html">tie</a></code>d hash or array may not necessarily return anything.</p>
<p>Deleting an array element effectively returns that position of the array<br>
to its initial, uninitialized state. Subsequently testing for the same<br>
element with exists() will return false. Also, deleting array elements<br>
in the middle of an array will not shift the index of the elements<br>
after them down. Use splice() for that. See <a href="../functions/exists.html">"exists"</a>.</p>
<p>The following (inefficiently) deletes all the values of %HASH and @ARRAY:</p>
<pre class="verbatim"><ol><li> foreach <span class="i">$key</span> <span class="s">(</span><a class="l_k" href="../functions/keys.html">keys</a> <span class="i">%HASH</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/delete.html">delete</a> <span class="i">$HASH</span>{<span class="i">$key</span>}<span class="sc">;</span></li><li> <span class="s">}</span></li><li></li><li> foreach <span class="i">$index</span> <span class="s">(</span><span class="n">0</span> .. <span class="i">$#ARRAY</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/delete.html">delete</a> <span class="i">$ARRAY</span>[<span class="i">$index</span>]<span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>And so do these:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/delete.html">delete</a> <span class="i">@HASH</span>{<a class="l_k" href="../functions/keys.html">keys</a> <span class="i">%HASH</span>}<span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/delete.html">delete</a> <span class="i">@ARRAY</span>[<span class="n">0</span> .. <span class="i">$#ARRAY</span>]<span class="sc">;</span></li></ol></pre><p>But both of these are slower than just assigning the empty list<br>
or undefining %HASH or @ARRAY:</p>
<pre class="verbatim"><ol><li> <span class="i">%HASH</span> = <span class="s">(</span><span class="s">)</span><span class="sc">;</span> <span class="c"># completely empty %HASH</span></li><li> <a class="l_k" href="../functions/undef.html">undef</a> <span class="i">%HASH</span><span class="sc">;</span> <span class="c"># forget %HASH ever existed</span></li><li></li><li> <span class="i">@ARRAY</span> = <span class="s">(</span><span class="s">)</span><span class="sc">;</span> <span class="c"># completely empty @ARRAY</span></li><li> <a class="l_k" href="../functions/undef.html">undef</a> <span class="i">@ARRAY</span><span class="sc">;</span> <span class="c"># forget @ARRAY ever existed</span></li></ol></pre><p>Note that the EXPR can be arbitrarily complicated as long as the final<br>
operation is a hash element, array element, hash slice, or array slice<br>
lookup:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/delete.html">delete</a> <span class="i">$ref</span>->[<span class="i">$x</span>][<span class="i">$y</span>]{<span class="i">$key</span>}<span class="sc">;</span></li><li> <a class="l_k" href="../functions/delete.html">delete</a> <span class="i">@</span>{<span class="i">$ref</span>->[<span class="i">$x</span>][<span class="i">$y</span>]}{<span class="i">$key1</span><span class="cm">,</span> <span class="i">$key2</span><span class="cm">,</span> <span class="i">@morekeys</span>}<span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/delete.html">delete</a> <span class="i">$ref</span>->[<span class="i">$x</span>][<span class="i">$y</span>][<span class="i">$index</span>]<span class="sc">;</span></li><li> <a class="l_k" href="../functions/delete.html">delete</a> <span class="i">@</span>{<span class="i">$ref</span>->[<span class="i">$x</span>][<span class="i">$y</span>]}[<span class="i">$index1</span><span class="cm">,</span> <span class="i">$index2</span><span class="cm">,</span> <span class="i">@moreindices</span>]<span class="sc">;</span></li></ol><]]></desc>
</keyword>
<keyword name="die" type="function">
<params>
<param name='list'/>
</params>
<desc><![CDATA[Outside an <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a></code>, prints the value of LIST to <code class="inline"><span class="w">STDERR</span></code>
and<br>
exits with the current value of <code class="inline"><span class="i">$!</span></code>
(errno). If <code class="inline"><span class="i">$!</span></code>
is <code class="inline"><span class="n">0</span></code>
,<br>
exits with the value of <code class="inline"><span class="s">(</span><span class="i">$?</span>>> <span class="n">8</span><span class="s">)</span></code>
(backtick `command`<br>
status). If <code class="inline"><span class="s">(</span><span class="i">$?</span>>> <span class="n">8</span><span class="s">)</span></code>
is <code class="inline"><span class="n">0</span></code>
, exits with <code class="inline"><span class="n">255</span></code>
. Inside<br>
an <code class="inline"><a class="l_k" href="../functions/eval.html">eval(),</a></code> the error message is stuffed into <code class="inline"><span class="i">$@</span></code>
and the<br>
<code class="inline"><a class="l_k" href="../functions/eval.html">eval</a></code> is terminated with the undefined value. This makes<br>
<code class="inline"><a class="l_k" href="../functions/die.html">die</a></code> the way to raise an exception.</p>
<p>Equivalent examples:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't cd to spool: $!\n"</span> unless <a class="l_k" href="../functions/chdir.html">chdir</a> <span class="q">'/usr/spool/news'</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/chdir.html">chdir</a> <span class="q">'/usr/spool/news'</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't cd to spool: $!\n"</span></li></ol></pre><p>If the last element of LIST does not end in a newline, the current<br>
script line number and input line number (if any) are also printed,<br>
and a newline is supplied. Note that the "input line number" (also<br>
known as "chunk") is subject to whatever notion of "line" happens to<br>
be currently in effect, and is also available as the special variable<br>
<code class="inline"><span class="i">$.</span></code>
. See <a href="../perlvar.html#%24%2f">"$/" in perlvar</a> and <a href="../perlvar.html#%24.">"$." in perlvar</a>.</p>
<p>Hint: sometimes appending <code class="inline"><span class="q">", stopped"</span></code>
to your message will cause it<br>
to make better sense when the string <code class="inline"><span class="q">"at foo line 123"</span></code>
is appended.<br>
Suppose you are running script "canasta".</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/die.html">die</a> <span class="q">"/etc/games is no good"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/die.html">die</a> <span class="q">"/etc/games is no good, stopped"</span><span class="sc">;</span></li></ol></pre><p>produce, respectively</p>
<pre class="verbatim"><ol><li> /etc/games is no good at canasta line 123.</li><li> /etc/games is no good, stopped at canasta line 123.</li></ol></pre><p>See also exit(), warn(), and the Carp module.</p>
<p>If LIST is empty and <code class="inline"><span class="i">$@</span></code>
already contains a value (typically from a<br>
previous eval) that value is reused after appending <code class="inline"><span class="q">"\t...propagated"</span></code>
.<br>
This is useful for propagating exceptions:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/eval.html">eval</a> <span class="s">{</span> ... <span class="s">}</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/die.html">die</a> unless <span class="i">$@</span> =~ <span class="q">/Expected exception/</span><span class="sc">;</span></li></ol></pre><p>If LIST is empty and <code class="inline"><span class="i">$@</span></code>
contains an object reference that has a<br>
<code class="inline"><span class="w">PROPAGATE</span></code>
method, that method will be called with additional file<br>
and line number parameters. The return value replaces the value in<br>
<code class="inline"><span class="i">$@</span></code>
. i.e. as if <code class="inline"><span class="i">$@</span> = <a class="l_k" href="../functions/eval.html">eval</a> <span class="s">{</span> <span class="i">$@</span><span class="i">->PROPAGATE</span><span class="s">(</span><span class="w">__FILE__</span><span class="cm">,</span> <span class="w">__LINE__</span><span class="s">)</span> <span class="s">}</span><span class="sc">;</span></code>
<br>
were called.</p>
<p>If <code class="inline"><span class="i">$@</span></code>
is empty then the string <code class="inline"><span class="q">"Died"</span></code>
is used.</p>
<p>die() can also be called with a reference argument. If this happens to be<br>
trapped within an eval(), $@ contains the reference. This behavior permits<br>
a more elaborate exception handling implementation using objects that<br>
maintain arbitrary state about the nature of the exception. Such a scheme<br>
is sometimes preferable to matching particular string values of $@ using<br>
regular expressions. Because $@ is a global variable, and eval() may be<br>
used within object implementations, care must be taken that analyzing the<br>
error object doesn't replace the reference in the global variable. The<br>
easiest solution is to make a local copy of the reference before doing<br>
other manipulations. Here's an example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Scalar::Util</span> <span class="q">'blessed'</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/eval.html">eval</a> <span class="s">{</span> ... <span class="sc">;</span> <a class="l_k" href="../functions/die.html">die</a> <span class="w">Some::Module::Exception</span><span class="w">->new</span><span class="s">(</span> <span class="w">FOO</span> <span class="cm">=></span> <span class="q">"bar"</span> <span class="s">)</span> <span class="s">}</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$ev_err</span> = <span class="i">$@</span><span class="s">)</span> <span class="s">{</span></li><li> if <span class="s">(</span><span class="i">blessed</span><span class="s">(</span><span class="i">$ev_err</span><span class="s">)</span> && <span class="i">$ev_err</span><span class="i">->isa</span><span class="s">(</span><span class="q">"Some::Module::Exception"</span><span class="s">)</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="c"># handle Some::Module::Exception</span></li><li> <span class="s">}</span></li><li> else <span class="s">{</span></li><li> <span class="c"># handle all other possible exceptions</span></li><li> <span class="s">}</span></li><li> <span class="s">}</span></li></ol></pre><p>Because perl will stringify uncaught exception messages before displaying<br>
them, you may want to overload stringification operations on such custom<br>
exception objects. See <a href="../overload.html">overload</a> for details about that.</p>
<p>You can arrange for a callback to be run just before the <code class="inline"><a class="l_k" href="../functions/die.html">die</a></code>
does its deed, by setting the <code class="inline"><span class="i">$SIG</span>{<span class="w">__DIE__</span>}</code>
hook. The associated<br>
handler will be called with the error text and can change the error<br>
message, if it sees fit, by calling <code class="inline"><a class="l_k" href="../functions/die.html">die</a></code> again. See<br>
<a href="../perlvar.html#%24SIG%7bexpr%7d">"$SIG{expr}" in perlvar</a> for details on setting <code class="inline"><span class="i">%SIG</span></code>
entries, and<br>
<a href="#eval-BLOCK">"eval BLOCK"</a> for some examples. Although this feature was <br>
to be run only right before your program was to exit, this is not<br>
currently the case--the <code class="inline"><span class="i">$SIG</span>{<span class="w">__DIE__</span>}</code>
hook is currently called<br>
even inside eval()ed blocks/strings! If one wants the hook to do<br>
nothing in such situations, put</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/die.html">die</a> <span class="i">@_</span> if <span class="i">$^S</span><span class="sc">;</span></li></ol></pre><p>as the first line of the handler (see <a href="../perlvar.html#%24%5eS">"$^S" in perlvar</a>). Because<br>
this promotes strange action at a distance, this counterintuitive<br>
behavior may be fixed in a future release.]]></desc>
</keyword>
<keyword name="do" type="function">
<params>
<param name='block'/>
</params>
<desc><![CDATA[Not really a function. Returns the value of the last command in the<br>
sequence of commands indicated by BLOCK. When modified by the <code class="inline">while</code>
or<br>
<code class="inline">until</code>
loop modifier, executes the BLOCK once before testing the loop<br>
condition. (On other statements the loop modifiers test the conditional<br>
first.)</p>
<p><code class="inline"><a class="l_k" href="../functions/do.html">do</a> <span class="w">BLOCK</span></code>
does <i>not</i> count as a loop, so the loop control statements<br>
<code class="inline"><a class="l_k" href="../functions/next.html">next</a></code>, <code class="inline"><a class="l_k" href="../functions/last.html">last</a></code>, or <code class="inline"><a class="l_k" href="../functions/redo.html">redo</a></code> cannot be used to leave or restart the block.<br>
See <a href="../perlsyn.html">perlsyn</a> for alternative strategies.]]></desc>
</keyword>
<keyword name="dump" type="function">
<params>
<param name='label'/>
</params>
<desc><![CDATA[This function causes an immediate core dump. See also the <b>-u</b>
command-line switch in <a href="../perlrun.html">perlrun</a>, which does the same thing.<br>
Primarily this is so that you can use the <b>undump</b> program (not<br>
supplied) to turn your core dump into an executable binary after<br>
having initialized all your variables at the beginning of the<br>
program. When the new binary is executed it will begin by executing<br>
a <code class="inline"><a class="l_k" href="../functions/goto.html">goto</a> <span class="j">LABEL</span></code>
(with all the restrictions that <code class="inline"><a class="l_k" href="../functions/goto.html">goto</a></code> suffers).<br>
Think of it as a goto with an intervening core dump and reincarnation.<br>
If <code class="inline"><span class="w">LABEL</span></code>
is omitted, restarts the program from the top.</p>
<p><b>WARNING</b>: Any files opened at the time of the dump will <i>not</i>
be open any more when the program is reincarnated, with possible<br>
resulting confusion on the part of Perl.</p>
<p>This function is now largely obsolete, mostly because it's very hard to<br>
convert a core file into an executable. That's why you should now invoke<br>
it as <code class="inline"><span class="i">CORE::dump</span><span class="s">(</span><span class="s">)</span></code>
, if you don't want to be warned against a possible<br>
typo.]]></desc>
</keyword>
<keyword name="dump" type="function">
<params>
</params>
<desc><![CDATA[This function causes an immediate core dump. See also the <b>-u</b>
command-line switch in <a href="../perlrun.html">perlrun</a>, which does the same thing.<br>
Primarily this is so that you can use the <b>undump</b> program (not<br>
supplied) to turn your core dump into an executable binary after<br>
having initialized all your variables at the beginning of the<br>
program. When the new binary is executed it will begin by executing<br>
a <code class="inline"><a class="l_k" href="../functions/goto.html">goto</a> <span class="j">LABEL</span></code>
(with all the restrictions that <code class="inline"><a class="l_k" href="../functions/goto.html">goto</a></code> suffers).<br>
Think of it as a goto with an intervening core dump and reincarnation.<br>
If <code class="inline"><span class="w">LABEL</span></code>
is omitted, restarts the program from the top.</p>
<p><b>WARNING</b>: Any files opened at the time of the dump will <i>not</i>
be open any more when the program is reincarnated, with possible<br>
resulting confusion on the part of Perl.</p>
<p>This function is now largely obsolete, mostly because it's very hard to<br>
convert a core file into an executable. That's why you should now invoke<br>
it as <code class="inline"><span class="i">CORE::dump</span><span class="s">(</span><span class="s">)</span></code>
, if you don't want to be warned against a possible<br>
typo.]]></desc>
</keyword>
<keyword name="each" type="function">
<params>
<param name='hash'/>
</params>
<desc><![CDATA[When called in list context, returns a 2-element list consisting of the<br>
key and value for the next element of a hash, so that you can iterate over<br>
it. When called in scalar context, returns only the key for the next<br>
element in the hash.</p>
<p>Entries are returned in an apparently random order. The actual random<br>
order is subject to change in future versions of perl, but it is<br>
guaranteed to be in the same order as either the <code class="inline"><a class="l_k" href="../functions/keys.html">keys</a></code> or <code class="inline"><a class="l_k" href="../functions/values.html">values</a></code>
function would produce on the same (unmodified) hash. Since Perl<br>
5.8.2 the ordering can be different even between different runs of Perl<br>
for security reasons (see <a href="../perlsec.html#Algorithmic-Complexity-Attacks">"Algorithmic Complexity Attacks" in perlsec</a>).</p>
<p>When the hash is entirely read, a null array is returned in list context<br>
(which when assigned produces a false (<code class="inline"><span class="n">0</span></code>
) value), and <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> in<br>
scalar context. The next call to <code class="inline"><a class="l_k" href="../functions/each.html">each</a></code> after that will start iterating<br>
again. There is a single iterator for each hash, shared by all <code class="inline"><a class="l_k" href="../functions/each.html">each</a></code>,<br>
<code class="inline"><a class="l_k" href="../functions/keys.html">keys</a></code>, and <code class="inline"><a class="l_k" href="../functions/values.html">values</a></code> function calls in the program; it can be reset by<br>
reading all the elements from the hash, or by evaluating <code class="inline"><a class="l_k" href="../functions/keys.html">keys</a> <span class="w">HASH</span></code>
or<br>
<code class="inline"><a class="l_k" href="../functions/values.html">values</a> <span class="w">HASH</span></code>
. If you add or delete elements of a hash while you're<br>
iterating over it, you may get entries skipped or duplicated, so<br>
don't. Exception: It is always safe to delete the item most recently<br>
returned by <code class="inline"><a class="l_k" href="../functions/each.html">each()</a></code>, which means that the following code will work:</p>
<pre class="verbatim"><ol><li> while <span class="s">(</span><span class="s">(</span><span class="i">$key</span><span class="cm">,</span> <span class="i">$value</span><span class="s">)</span> = <a class="l_k" href="../functions/each.html">each</a> <span class="i">%hash</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$key</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/delete.html">delete</a> <span class="i">$hash</span>{<span class="i">$key</span>}<span class="sc">;</span> <span class="c"># This is safe</span></li><li> <span class="s">}</span></li></ol></pre><p>The following prints out your environment like the printenv(1) program,<br>
only in a different order:</p>
<pre class="verbatim"><ol><li> while <span class="s">(</span><span class="s">(</span><span class="i">$key</span><span class="cm">,</span><span class="i">$value</span><span class="s">)</span> = <a class="l_k" href="../functions/each.html">each</a> <span class="i">%ENV</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"$key=$value\n"</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>See also <code class="inline"><a class="l_k" href="../functions/keys.html">keys</a></code>, <code class="inline"><a class="l_k" href="../functions/values.html">values</a></code> and <code class="inline"><a class="l_k" href="../functions/sort.html">sort</a></code>.]]></desc>
</keyword>
<keyword name="endgrent" type="function">
<params>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="endhostent" type="function">
<params>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="endnetent" type="function">
<params>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="endprotoent" type="function">
<params>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="endpwent" type="function">
<params>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="endservent" type="function">
<params>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="eof" type="function">
<params>
<param name='()'/>
</params>
<desc><![CDATA[Returns 1 if the next read on FILEHANDLE will return end of file, or if<br>
FILEHANDLE is not open. FILEHANDLE may be an expression whose value<br>
gives the real filehandle. (Note that this function actually<br>
reads a character and then <code class="inline"><span class="w">ungetc</span></code>
s it, so isn't very useful in an<br>
interactive context.) Do not read from a terminal file (or call<br>
<code class="inline"><a class="l_k" href="../functions/eof.html">eof(FILEHANDLE)</a></code> on it) after end-of-file is reached. File types such<br>
as terminals may lose the end-of-file condition if you do.</p>
<p>An <code class="inline"><a class="l_k" href="../functions/eof.html">eof</a></code> without an argument uses the last file read. Using <code class="inline"><a class="l_k" href="../functions/eof.html">eof()</a></code>
with empty parentheses is very different. It refers to the pseudo file<br>
formed from the files listed on the command line and accessed via the<br>
<code class="inline"><></code>
operator. Since <code class="inline"><></code>
isn't explicitly opened,<br>
as a normal filehandle is, an <code class="inline"><a class="l_k" href="../functions/eof.html">eof()</a></code> before <code class="inline"><></code>
has been<br>
used will cause <code class="inline"><span class="i">@ARGV</span></code>
to be examined to determine if input is<br>
available. Similarly, an <code class="inline"><a class="l_k" href="../functions/eof.html">eof()</a></code> after <code class="inline"><></code>
has returned<br>
end-of-file will assume you are processing another <code class="inline"><span class="i">@ARGV</span></code>
list,<br>
and if you haven't set <code class="inline"><span class="i">@ARGV</span></code>
, will read input from <code class="inline"><span class="w">STDIN</span></code>
;<br>
see <a href="../perlop.html#I%2fO-Operators">"I/O Operators" in perlop</a>.</p>
<p>In a <code class="inline">while <span class="s">(</span><><span class="s">)</span></code>
loop, <code class="inline"><a class="l_k" href="../functions/eof.html">eof</a></code> or <code class="inline"><a class="l_k" href="../functions/eof.html">eof(ARGV)</a></code> can be used to<br>
detect the end of each file, <code class="inline"><a class="l_k" href="../functions/eof.html">eof()</a></code> will only detect the end of the<br>
last file. Examples:</p>
<pre class="verbatim"><ol><li> <span class="c"># reset line numbering on each input file</span></li><li> while <span class="s">(</span><><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/next.html">next</a> if <span class="q">/^\s*#/</span><span class="sc">;</span> <span class="c"># skip comments</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"$.\t$_"</span><span class="sc">;</span></li><li> <span class="s">}</span> <a class="l_k" href="../functions/continue.html">continue</a> <span class="s">{</span></li><li> <a class="l_k" href="../functions/close.html">close</a> <span class="w">ARGV</span> if <a class="l_k" href="../functions/eof.html">eof</a><span class="sc">;</span> <span class="c"># Not eof()!</span></li><li> <span class="s">}</span></li><li></li><li> <span class="c"># insert dashes just before last line of last file</span></li><li> while <span class="s">(</span><><span class="s">)</span> <span class="s">{</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/eof.html">eof</a><span class="s">(</span><span class="s">)</span><span class="s">)</span> <span class="s">{</span> <span class="c"># check for end of last file</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"--------------\n"</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> <a class="l_k" href="../functions/print.html">print</a><span class="sc">;</span></li><li> <a class="l_k" href="../functions/last.html">last</a> if <a class="l_k" href="../functions/eof.html">eof</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span> <span class="c"># needed if we're reading from a terminal</span></li><li> <span class="s">}</span></li></ol></pre><p>Practical hint: you almost never need to use <code class="inline"><a class="l_k" href="../functions/eof.html">eof</a></code> in Perl, because the<br>
input operators typically return <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> when they run out of data, or if<br>
there was an error.]]></desc>
</keyword>
<keyword name="eof" type="function">
<params>
<param name='filehandle'/>
</params>
<desc><![CDATA[Returns 1 if the next read on FILEHANDLE will return end of file, or if<br>
FILEHANDLE is not open. FILEHANDLE may be an expression whose value<br>
gives the real filehandle. (Note that this function actually<br>
reads a character and then <code class="inline"><span class="w">ungetc</span></code>
s it, so isn't very useful in an<br>
interactive context.) Do not read from a terminal file (or call<br>
<code class="inline"><a class="l_k" href="../functions/eof.html">eof(FILEHANDLE)</a></code> on it) after end-of-file is reached. File types such<br>
as terminals may lose the end-of-file condition if you do.</p>
<p>An <code class="inline"><a class="l_k" href="../functions/eof.html">eof</a></code> without an argument uses the last file read. Using <code class="inline"><a class="l_k" href="../functions/eof.html">eof()</a></code>
with empty parentheses is very different. It refers to the pseudo file<br>
formed from the files listed on the command line and accessed via the<br>
<code class="inline"><></code>
operator. Since <code class="inline"><></code>
isn't explicitly opened,<br>
as a normal filehandle is, an <code class="inline"><a class="l_k" href="../functions/eof.html">eof()</a></code> before <code class="inline"><></code>
has been<br>
used will cause <code class="inline"><span class="i">@ARGV</span></code>
to be examined to determine if input is<br>
available. Similarly, an <code class="inline"><a class="l_k" href="../functions/eof.html">eof()</a></code> after <code class="inline"><></code>
has returned<br>
end-of-file will assume you are processing another <code class="inline"><span class="i">@ARGV</span></code>
list,<br>
and if you haven't set <code class="inline"><span class="i">@ARGV</span></code>
, will read input from <code class="inline"><span class="w">STDIN</span></code>
;<br>
see <a href="../perlop.html#I%2fO-Operators">"I/O Operators" in perlop</a>.</p>
<p>In a <code class="inline">while <span class="s">(</span><><span class="s">)</span></code>
loop, <code class="inline"><a class="l_k" href="../functions/eof.html">eof</a></code> or <code class="inline"><a class="l_k" href="../functions/eof.html">eof(ARGV)</a></code> can be used to<br>
detect the end of each file, <code class="inline"><a class="l_k" href="../functions/eof.html">eof()</a></code> will only detect the end of the<br>
last file. Examples:</p>
<pre class="verbatim"><ol><li> <span class="c"># reset line numbering on each input file</span></li><li> while <span class="s">(</span><><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/next.html">next</a> if <span class="q">/^\s*#/</span><span class="sc">;</span> <span class="c"># skip comments</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"$.\t$_"</span><span class="sc">;</span></li><li> <span class="s">}</span> <a class="l_k" href="../functions/continue.html">continue</a> <span class="s">{</span></li><li> <a class="l_k" href="../functions/close.html">close</a> <span class="w">ARGV</span> if <a class="l_k" href="../functions/eof.html">eof</a><span class="sc">;</span> <span class="c"># Not eof()!</span></li><li> <span class="s">}</span></li><li></li><li> <span class="c"># insert dashes just before last line of last file</span></li><li> while <span class="s">(</span><><span class="s">)</span> <span class="s">{</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/eof.html">eof</a><span class="s">(</span><span class="s">)</span><span class="s">)</span> <span class="s">{</span> <span class="c"># check for end of last file</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"--------------\n"</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> <a class="l_k" href="../functions/print.html">print</a><span class="sc">;</span></li><li> <a class="l_k" href="../functions/last.html">last</a> if <a class="l_k" href="../functions/eof.html">eof</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span> <span class="c"># needed if we're reading from a terminal</span></li><li> <span class="s">}</span></li></ol></pre><p>Practical hint: you almost never need to use <code class="inline"><a class="l_k" href="../functions/eof.html">eof</a></code> in Perl, because the<br>
input operators typically return <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> when they run out of data, or if<br>
there was an error.]]></desc>
</keyword>
<keyword name="eof" type="function">
<params>
</params>
<desc><![CDATA[Returns 1 if the next read on FILEHANDLE will return end of file, or if<br>
FILEHANDLE is not open. FILEHANDLE may be an expression whose value<br>
gives the real filehandle. (Note that this function actually<br>
reads a character and then <code class="inline"><span class="w">ungetc</span></code>
s it, so isn't very useful in an<br>
interactive context.) Do not read from a terminal file (or call<br>
<code class="inline"><a class="l_k" href="../functions/eof.html">eof(FILEHANDLE)</a></code> on it) after end-of-file is reached. File types such<br>
as terminals may lose the end-of-file condition if you do.</p>
<p>An <code class="inline"><a class="l_k" href="../functions/eof.html">eof</a></code> without an argument uses the last file read. Using <code class="inline"><a class="l_k" href="../functions/eof.html">eof()</a></code>
with empty parentheses is very different. It refers to the pseudo file<br>
formed from the files listed on the command line and accessed via the<br>
<code class="inline"><></code>
operator. Since <code class="inline"><></code>
isn't explicitly opened,<br>
as a normal filehandle is, an <code class="inline"><a class="l_k" href="../functions/eof.html">eof()</a></code> before <code class="inline"><></code>
has been<br>
used will cause <code class="inline"><span class="i">@ARGV</span></code>
to be examined to determine if input is<br>
available. Similarly, an <code class="inline"><a class="l_k" href="../functions/eof.html">eof()</a></code> after <code class="inline"><></code>
has returned<br>
end-of-file will assume you are processing another <code class="inline"><span class="i">@ARGV</span></code>
list,<br>
and if you haven't set <code class="inline"><span class="i">@ARGV</span></code>
, will read input from <code class="inline"><span class="w">STDIN</span></code>
;<br>
see <a href="../perlop.html#I%2fO-Operators">"I/O Operators" in perlop</a>.</p>
<p>In a <code class="inline">while <span class="s">(</span><><span class="s">)</span></code>
loop, <code class="inline"><a class="l_k" href="../functions/eof.html">eof</a></code> or <code class="inline"><a class="l_k" href="../functions/eof.html">eof(ARGV)</a></code> can be used to<br>
detect the end of each file, <code class="inline"><a class="l_k" href="../functions/eof.html">eof()</a></code> will only detect the end of the<br>
last file. Examples:</p>
<pre class="verbatim"><ol><li> <span class="c"># reset line numbering on each input file</span></li><li> while <span class="s">(</span><><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/next.html">next</a> if <span class="q">/^\s*#/</span><span class="sc">;</span> <span class="c"># skip comments</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"$.\t$_"</span><span class="sc">;</span></li><li> <span class="s">}</span> <a class="l_k" href="../functions/continue.html">continue</a> <span class="s">{</span></li><li> <a class="l_k" href="../functions/close.html">close</a> <span class="w">ARGV</span> if <a class="l_k" href="../functions/eof.html">eof</a><span class="sc">;</span> <span class="c"># Not eof()!</span></li><li> <span class="s">}</span></li><li></li><li> <span class="c"># insert dashes just before last line of last file</span></li><li> while <span class="s">(</span><><span class="s">)</span> <span class="s">{</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/eof.html">eof</a><span class="s">(</span><span class="s">)</span><span class="s">)</span> <span class="s">{</span> <span class="c"># check for end of last file</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"--------------\n"</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> <a class="l_k" href="../functions/print.html">print</a><span class="sc">;</span></li><li> <a class="l_k" href="../functions/last.html">last</a> if <a class="l_k" href="../functions/eof.html">eof</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span> <span class="c"># needed if we're reading from a terminal</span></li><li> <span class="s">}</span></li></ol></pre><p>Practical hint: you almost never need to use <code class="inline"><a class="l_k" href="../functions/eof.html">eof</a></code> in Perl, because the<br>
input operators typically return <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> when they run out of data, or if<br>
there was an error.]]></desc>
</keyword>
<keyword name="eval" type="function">
<params>
<param name='expr'/>
</params>
<desc></desc>
</keyword>
<keyword name="exec" type="function">
<params>
<param name='list'/>
</params>
<desc><![CDATA[The <code class="inline"><a class="l_k" href="../functions/exec.html">exec</a></code> function executes a system command <i>and never returns</i>--<br>
use <code class="inline"><a class="l_k" href="../functions/system.html">system</a></code> instead of <code class="inline"><a class="l_k" href="../functions/exec.html">exec</a></code> if you want it to return. It fails and<br>
returns false only if the command does not exist <i>and</i> it is executed<br>
directly instead of via your system's command shell (see below).</p>
<p>Since it's a common mistake to use <code class="inline"><a class="l_k" href="../functions/exec.html">exec</a></code> instead of <code class="inline"><a class="l_k" href="../functions/system.html">system</a></code>, Perl<br>
warns you if there is a following statement which isn't <code class="inline"><a class="l_k" href="../functions/die.html">die</a></code>, <code class="inline"><a class="l_k" href="../functions/warn.html">warn</a></code>,<br>
or <code class="inline"><a class="l_k" href="../functions/exit.html">exit</a></code> (if <code class="inline">-w</code>
is set - but you always do that). If you<br>
<i>really</i> want to follow an <code class="inline"><a class="l_k" href="../functions/exec.html">exec</a></code> with some other statement, you<br>
can use one of these styles to avoid the warning:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/exec.html">exec</a> <span class="s">(</span><span class="q">'foo'</span><span class="s">)</span> or <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDERR</span> <span class="q">"couldn't exec foo: $!"</span><span class="sc">;</span></li><li> <span class="s">{</span> <a class="l_k" href="../functions/exec.html">exec</a> <span class="s">(</span><span class="q">'foo'</span><span class="s">)</span> <span class="s">}</span><span class="sc">;</span> <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDERR</span> <span class="q">"couldn't exec foo: $!"</span><span class="sc">;</span></li></ol></pre><p>If there is more than one argument in LIST, or if LIST is an array<br>
with more than one value, calls execvp(3) with the arguments in LIST.<br>
If there is only one scalar argument or an array with one element in it,<br>
the argument is checked for shell metacharacters, and if there are any,<br>
the entire argument is passed to the system's command shell for parsing<br>
(this is <code class="inline">/bin/sh -c</code> on Unix platforms, but varies on other platforms).<br>
If there are no shell metacharacters in the argument, it is split into<br>
words and passed directly to <code class="inline"><span class="w">execvp</span></code>
, which is more efficient.<br>
Examples:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/exec.html">exec</a> <span class="q">'/bin/echo'</span><span class="cm">,</span> <span class="q">'Your arguments are: '</span><span class="cm">,</span> <span class="i">@ARGV</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/exec.html">exec</a> <span class="q">"sort $outfile | uniq"</span><span class="sc">;</span></li></ol></pre><p>If you don't really want to execute the first argument, but want to lie<br>
to the program you are executing about its own name, you can specify<br>
the program you actually want to run as an "indirect object" (without a<br>
comma) in front of the LIST. (This always forces interpretation of the<br>
LIST as a multivalued list, even if there is only a single scalar in<br>
the list.) Example:</p>
<pre class="verbatim"><ol><li> <span class="i">$shell</span> = <span class="q">'/bin/csh'</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/exec.html">exec</a> <span class="i">$shell</span> <span class="q">'-sh'</span><span class="sc">;</span> <span class="c"># pretend it's a login shell</span></li></ol></pre><p>or, more directly,</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/exec.html">exec</a> <span class="s">{</span><span class="q">'/bin/csh'</span><span class="s">}</span> <span class="q">'-sh'</span><span class="sc">;</span> <span class="c"># pretend it's a login shell</span></li></ol></pre><p>When the arguments get executed via the system shell, results will<br>
be subject to its quirks and capabilities. See <a href="../perlop.html#%60STRING%60">"`STRING`" in perlop</a>
for details.</p>
<p>Using an indirect object with <code class="inline"><a class="l_k" href="../functions/exec.html">exec</a></code> or <code class="inline"><a class="l_k" href="../functions/system.html">system</a></code> is also more<br>
secure. This usage (which also works fine with system()) forces<br>
interpretation of the arguments as a multivalued list, even if the<br>
list had just one argument. That way you're safe from the shell<br>
expanding wildcards or splitting up words with whitespace in them.</p>
<pre class="verbatim"><ol><li> <span class="i">@args</span> = <span class="s">(</span> <span class="q">"echo surprise"</span> <span class="s">)</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/exec.html">exec</a> <span class="i">@args</span><span class="sc">;</span> <span class="c"># subject to shell escapes</span></li><li> <span class="c"># if @args == 1</span></li><li> <a class="l_k" href="../functions/exec.html">exec</a> <span class="s">{</span> <span class="i">$args</span>[<span class="n">0</span>] <span class="s">}</span> <span class="i">@args</span><span class="sc">;</span> <span class="c"># safe even with one-arg list</span></li></ol></pre><p>The first version, the one without the indirect object, ran the <i>echo</i>
program, passing it <code class="inline"><span class="q">"surprise"</span></code>
an argument. The second version<br>
didn't--it tried to run a program literally called <i>"echo surprise"</i>,<br>
didn't find it, and set <code class="inline"><span class="i">$?</span></code>
to a non-zero value indicating failure.</p>
<p>Beginning with v5.6.0, Perl will attempt to flush all files opened for<br>
output before the exec, but this may not be supported on some platforms<br>
(see <a href="../perlport.html">perlport</a>). To be safe, you may need to set <code class="inline"><span class="i">$|</span></code>
($AUTOFLUSH<br>
in English) or call the <code class="inline"><span class="i">autoflush</span><span class="s">(</span><span class="s">)</span></code>
method of <code class="inline"><span class="w">IO::Handle</span></code>
on any<br>
open handles in order to avoid lost output.</p>
<p>Note that <code class="inline"><a class="l_k" href="../functions/exec.html">exec</a></code> will not call your <code class="inline">END</code>
blocks, nor will it call<br>
any <code class="inline">DESTROY</code>
methods in your objects.]]></desc>
</keyword>
<keyword name="exec" type="function">
<params>
<param name='program list'/>
</params>
<desc><![CDATA[The <code class="inline"><a class="l_k" href="../functions/exec.html">exec</a></code> function executes a system command <i>and never returns</i>--<br>
use <code class="inline"><a class="l_k" href="../functions/system.html">system</a></code> instead of <code class="inline"><a class="l_k" href="../functions/exec.html">exec</a></code> if you want it to return. It fails and<br>
returns false only if the command does not exist <i>and</i> it is executed<br>
directly instead of via your system's command shell (see below).</p>
<p>Since it's a common mistake to use <code class="inline"><a class="l_k" href="../functions/exec.html">exec</a></code> instead of <code class="inline"><a class="l_k" href="../functions/system.html">system</a></code>, Perl<br>
warns you if there is a following statement which isn't <code class="inline"><a class="l_k" href="../functions/die.html">die</a></code>, <code class="inline"><a class="l_k" href="../functions/warn.html">warn</a></code>,<br>
or <code class="inline"><a class="l_k" href="../functions/exit.html">exit</a></code> (if <code class="inline">-w</code>
is set - but you always do that). If you<br>
<i>really</i> want to follow an <code class="inline"><a class="l_k" href="../functions/exec.html">exec</a></code> with some other statement, you<br>
can use one of these styles to avoid the warning:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/exec.html">exec</a> <span class="s">(</span><span class="q">'foo'</span><span class="s">)</span> or <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDERR</span> <span class="q">"couldn't exec foo: $!"</span><span class="sc">;</span></li><li> <span class="s">{</span> <a class="l_k" href="../functions/exec.html">exec</a> <span class="s">(</span><span class="q">'foo'</span><span class="s">)</span> <span class="s">}</span><span class="sc">;</span> <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDERR</span> <span class="q">"couldn't exec foo: $!"</span><span class="sc">;</span></li></ol></pre><p>If there is more than one argument in LIST, or if LIST is an array<br>
with more than one value, calls execvp(3) with the arguments in LIST.<br>
If there is only one scalar argument or an array with one element in it,<br>
the argument is checked for shell metacharacters, and if there are any,<br>
the entire argument is passed to the system's command shell for parsing<br>
(this is <code class="inline">/bin/sh -c</code> on Unix platforms, but varies on other platforms).<br>
If there are no shell metacharacters in the argument, it is split into<br>
words and passed directly to <code class="inline"><span class="w">execvp</span></code>
, which is more efficient.<br>
Examples:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/exec.html">exec</a> <span class="q">'/bin/echo'</span><span class="cm">,</span> <span class="q">'Your arguments are: '</span><span class="cm">,</span> <span class="i">@ARGV</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/exec.html">exec</a> <span class="q">"sort $outfile | uniq"</span><span class="sc">;</span></li></ol></pre><p>If you don't really want to execute the first argument, but want to lie<br>
to the program you are executing about its own name, you can specify<br>
the program you actually want to run as an "indirect object" (without a<br>
comma) in front of the LIST. (This always forces interpretation of the<br>
LIST as a multivalued list, even if there is only a single scalar in<br>
the list.) Example:</p>
<pre class="verbatim"><ol><li> <span class="i">$shell</span> = <span class="q">'/bin/csh'</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/exec.html">exec</a> <span class="i">$shell</span> <span class="q">'-sh'</span><span class="sc">;</span> <span class="c"># pretend it's a login shell</span></li></ol></pre><p>or, more directly,</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/exec.html">exec</a> <span class="s">{</span><span class="q">'/bin/csh'</span><span class="s">}</span> <span class="q">'-sh'</span><span class="sc">;</span> <span class="c"># pretend it's a login shell</span></li></ol></pre><p>When the arguments get executed via the system shell, results will<br>
be subject to its quirks and capabilities. See <a href="../perlop.html#%60STRING%60">"`STRING`" in perlop</a>
for details.</p>
<p>Using an indirect object with <code class="inline"><a class="l_k" href="../functions/exec.html">exec</a></code> or <code class="inline"><a class="l_k" href="../functions/system.html">system</a></code> is also more<br>
secure. This usage (which also works fine with system()) forces<br>
interpretation of the arguments as a multivalued list, even if the<br>
list had just one argument. That way you're safe from the shell<br>
expanding wildcards or splitting up words with whitespace in them.</p>
<pre class="verbatim"><ol><li> <span class="i">@args</span> = <span class="s">(</span> <span class="q">"echo surprise"</span> <span class="s">)</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/exec.html">exec</a> <span class="i">@args</span><span class="sc">;</span> <span class="c"># subject to shell escapes</span></li><li> <span class="c"># if @args == 1</span></li><li> <a class="l_k" href="../functions/exec.html">exec</a> <span class="s">{</span> <span class="i">$args</span>[<span class="n">0</span>] <span class="s">}</span> <span class="i">@args</span><span class="sc">;</span> <span class="c"># safe even with one-arg list</span></li></ol></pre><p>The first version, the one without the indirect object, ran the <i>echo</i>
program, passing it <code class="inline"><span class="q">"surprise"</span></code>
an argument. The second version<br>
didn't--it tried to run a program literally called <i>"echo surprise"</i>,<br>
didn't find it, and set <code class="inline"><span class="i">$?</span></code>
to a non-zero value indicating failure.</p>
<p>Beginning with v5.6.0, Perl will attempt to flush all files opened for<br>
output before the exec, but this may not be supported on some platforms<br>
(see <a href="../perlport.html">perlport</a>). To be safe, you may need to set <code class="inline"><span class="i">$|</span></code>
($AUTOFLUSH<br>
in English) or call the <code class="inline"><span class="i">autoflush</span><span class="s">(</span><span class="s">)</span></code>
method of <code class="inline"><span class="w">IO::Handle</span></code>
on any<br>
open handles in order to avoid lost output.</p>
<p>Note that <code class="inline"><a class="l_k" href="../functions/exec.html">exec</a></code> will not call your <code class="inline">END</code>
blocks, nor will it call<br>
any <code class="inline">DESTROY</code>
methods in your objects.]]></desc>
</keyword>
<keyword name="exists" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Given an expression that specifies a hash element or array element,<br>
returns true if the specified element in the hash or array has ever<br>
been initialized, even if the corresponding value is undefined.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Exists\n"</span> if <a class="l_k" href="../functions/exists.html">exists</a> <span class="i">$hash</span>{<span class="i">$key</span>}<span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Defined\n"</span> if <a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$hash</span>{<span class="i">$key</span>}<span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"True\n"</span> if <span class="i">$hash</span>{<span class="i">$key</span>}<span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Exists\n"</span> if <a class="l_k" href="../functions/exists.html">exists</a> <span class="i">$array</span>[<span class="i">$index</span>]<span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Defined\n"</span> if <a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$array</span>[<span class="i">$index</span>]<span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"True\n"</span> if <span class="i">$array</span>[<span class="i">$index</span>]<span class="sc">;</span></li></ol></pre><p>A hash or array element can be true only if it's defined, and defined if<br>
it exists, but the reverse doesn't necessarily hold true.</p>
<p>Given an expression that specifies the name of a subroutine,<br>
returns true if the specified subroutine has ever been declared, even<br>
if it is undefined. Mentioning a subroutine name for exists or defined<br>
does not count as declaring it. Note that a subroutine which does not<br>
exist may still be callable: its package may have an <code class="inline">AUTOLOAD</code>
<br>
method that makes it spring into existence the first time that it is<br>
called -- see <a href="../perlsub.html">perlsub</a>.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Exists\n"</span> if <a class="l_k" href="../functions/exists.html">exists</a> <span class="i">&subroutine</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Defined\n"</span> if <a class="l_k" href="../functions/defined.html">defined</a> <span class="i">&subroutine</span><span class="sc">;</span></li></ol></pre><p>Note that the EXPR can be arbitrarily complicated as long as the final<br>
operation is a hash or array key lookup or subroutine name:</p>
<pre class="verbatim"><ol><li> if <span class="s">(</span><a class="l_k" href="../functions/exists.html">exists</a> <span class="i">$ref</span>->{<span class="w">A</span>}->{<span class="w">B</span>}->{<span class="i">$key</span>}<span class="s">)</span> <span class="s">{</span> <span class="s">}</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/exists.html">exists</a> <span class="i">$hash</span>{<span class="w">A</span>}{<span class="w">B</span>}{<span class="i">$key</span>}<span class="s">)</span> <span class="s">{</span> <span class="s">}</span></li><li></li><li> if <span class="s">(</span><a class="l_k" href="../functions/exists.html">exists</a> <span class="i">$ref</span>->{<span class="w">A</span>}->{<span class="w">B</span>}->[<span class="i">$ix</span>]<span class="s">)</span> <span class="s">{</span> <span class="s">}</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/exists.html">exists</a> <span class="i">$hash</span>{<span class="w">A</span>}{<span class="w">B</span>}[<span class="i">$ix</span>]<span class="s">)</span> <span class="s">{</span> <span class="s">}</span></li><li></li><li> if <span class="s">(</span><a class="l_k" href="../functions/exists.html">exists</a> <span class="i">&</span>{<span class="i">$ref</span>->{<span class="w">A</span>}{<span class="w">B</span>}{<span class="i">$key</span>}}<span class="s">)</span> <span class="s">{</span> <span class="s">}</span></li></ol></pre><p>Although the deepest nested array or hash will not spring into existence<br>
just because its existence was tested, any intervening ones will.<br>
Thus <code class="inline"><span class="i">$ref</span>->{<span class="q">"A"</span>}</code>
and <code class="inline"><span class="i">$ref</span>->{<span class="q">"A"</span>}->{<span class="q">"B"</span>}</code>
will spring<br>
into existence due to the existence test for the $key element above.<br>
This happens anywhere the arrow operator is used, including even:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/undef.html">undef</a> <span class="i">$ref</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/exists.html">exists</a> <span class="i">$ref</span>->{<span class="q">"Some key"</span>}<span class="s">)</span> <span class="s">{</span> <span class="s">}</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$ref</span><span class="sc">;</span> <span class="c"># prints HASH(0x80d3d5c)</span></li></ol></pre><p>This surprising autovivification in what does not at first--or even<br>
second--glance appear to be an lvalue context may be fixed in a future<br>
release.</p>
<p>Use of a subroutine call, rather than a subroutine name, as an argument<br>
to exists() is an error.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/exists.html">exists</a> <span class="i">&sub</span><span class="sc">;</span> <span class="c"># OK</span></li><li> <a class="l_k" href="../functions/exists.html">exists</a> <span class="i">&sub</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span> <span class="c"># Error</span></li></ol><]]></desc>
</keyword>
<keyword name="exit" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Evaluates EXPR and exits immediately with that value. Example:</p>
<pre class="verbatim"><ol><li> <span class="i">$ans</span> = <span class="q"><STDIN></span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/exit.html">exit</a> <span class="n">0</span> if <span class="i">$ans</span> =~ <span class="q">/^[Xx]/</span><span class="sc">;</span></li></ol></pre><p>See also <code class="inline"><a class="l_k" href="../functions/die.html">die</a></code>. If EXPR is omitted, exits with <code class="inline"><span class="n">0</span></code>
status. The only<br>
universally recognized values for EXPR are <code class="inline"><span class="n">0</span></code>
for success and <code class="inline"><span class="n">1</span></code>
<br>
for error; other values are subject to interpretation depending on the<br>
environment in which the Perl program is running. For example, exiting<br>
69 (EX_UNAVAILABLE) from a <i>sendmail</i> incoming-mail filter will cause<br>
the mailer to return the item undelivered, but that's not true everywhere.</p>
<p>Don't use <code class="inline"><a class="l_k" href="../functions/exit.html">exit</a></code> to abort a subroutine if there's any chance that<br>
someone might want to trap whatever error happened. Use <code class="inline"><a class="l_k" href="../functions/die.html">die</a></code> instead,<br>
which can be trapped by an <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a></code>.</p>
<p>The exit() function does not always exit immediately. It calls any<br>
defined <code class="inline">END</code>
routines first, but these <code class="inline">END</code>
routines may not<br>
themselves abort the exit. Likewise any object destructors that need to<br>
be called are called before the real exit. If this is a problem, you<br>
can call <code class="inline"><span class="j">POSIX:</span><span class="i">_exit</span><span class="s">(</span><span class="i">$status</span><span class="s">)</span></code>
to avoid END and destructor processing.<br>
See <a href="../perlmod.html">perlmod</a> for details.]]></desc>
</keyword>
<keyword name="exit" type="function">
<params>
</params>
<desc><![CDATA[Evaluates EXPR and exits immediately with that value. Example:</p>
<pre class="verbatim"><ol><li> <span class="i">$ans</span> = <span class="q"><STDIN></span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/exit.html">exit</a> <span class="n">0</span> if <span class="i">$ans</span> =~ <span class="q">/^[Xx]/</span><span class="sc">;</span></li></ol></pre><p>See also <code class="inline"><a class="l_k" href="../functions/die.html">die</a></code>. If EXPR is omitted, exits with <code class="inline"><span class="n">0</span></code>
status. The only<br>
universally recognized values for EXPR are <code class="inline"><span class="n">0</span></code>
for success and <code class="inline"><span class="n">1</span></code>
<br>
for error; other values are subject to interpretation depending on the<br>
environment in which the Perl program is running. For example, exiting<br>
69 (EX_UNAVAILABLE) from a <i>sendmail</i> incoming-mail filter will cause<br>
the mailer to return the item undelivered, but that's not true everywhere.</p>
<p>Don't use <code class="inline"><a class="l_k" href="../functions/exit.html">exit</a></code> to abort a subroutine if there's any chance that<br>
someone might want to trap whatever error happened. Use <code class="inline"><a class="l_k" href="../functions/die.html">die</a></code> instead,<br>
which can be trapped by an <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a></code>.</p>
<p>The exit() function does not always exit immediately. It calls any<br>
defined <code class="inline">END</code>
routines first, but these <code class="inline">END</code>
routines may not<br>
themselves abort the exit. Likewise any object destructors that need to<br>
be called are called before the real exit. If this is a problem, you<br>
can call <code class="inline"><span class="j">POSIX:</span><span class="i">_exit</span><span class="s">(</span><span class="i">$status</span><span class="s">)</span></code>
to avoid END and destructor processing.<br>
See <a href="../perlmod.html">perlmod</a> for details.]]></desc>
</keyword>
<keyword name="exp" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Returns <i>e</i> (the natural logarithm base) to the power of EXPR.<br>
If EXPR is omitted, gives <code class="inline"><a class="l_k" href="../functions/exp.html">exp($_)</a></code>.]]></desc>
</keyword>
<keyword name="exp" type="function">
<params>
</params>
<desc><![CDATA[Returns <i>e</i> (the natural logarithm base) to the power of EXPR.<br>
If EXPR is omitted, gives <code class="inline"><a class="l_k" href="../functions/exp.html">exp($_)</a></code>.]]></desc>
</keyword>
<keyword name="fcntl" type="function">
<params>
<param name='filehandle'/>
<param name='function'/>
<param name='scalar'/>
</params>
<desc><![CDATA[Implements the fcntl(2) function. You'll probably have to say</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Fcntl</span><span class="sc">;</span></li></ol></pre><p>first to get the correct constant definitions. Argument processing and<br>
value return works just like <code class="inline"><a class="l_k" href="../functions/ioctl.html">ioctl</a></code> below.<br>
For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Fcntl</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/fcntl.html">fcntl</a><span class="s">(</span><span class="i">$filehandle</span><span class="cm">,</span> <span class="w">F_GETFL</span><span class="cm">,</span> <span class="i">$packed_return_buffer</span><span class="s">)</span></li><li> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"can't fcntl F_GETFL: $!"</span><span class="sc">;</span></li></ol></pre><p>You don't have to check for <code class="inline"><a class="l_k" href="../functions/defined.html">defined</a></code> on the return from <code class="inline"><a class="l_k" href="../functions/fcntl.html">fcntl</a></code>.<br>
Like <code class="inline"><a class="l_k" href="../functions/ioctl.html">ioctl</a></code>, it maps a <code class="inline"><span class="n">0</span></code>
return from the system call into<br>
<code class="inline"><span class="q">"0 but true"</span></code>
in Perl. This string is true in boolean context and <code class="inline"><span class="n">0</span></code>
<br>
in numeric context. It is also exempt from the normal <b>-w</b> warnings<br>
on improper numeric conversions.</p>
<p>Note that <code class="inline"><a class="l_k" href="../functions/fcntl.html">fcntl</a></code> will produce a fatal error if used on a machine that<br>
doesn't implement fcntl(2). See the Fcntl module or your fcntl(2)<br>
manpage to learn what functions are available on your system.</p>
<p>Here's an example of setting a filehandle named <code class="inline"><span class="w">REMOTE</span></code>
to be<br>
non-blocking at the system level. You'll have to negotiate <code class="inline"><span class="i">$|</span></code>
<br>
on your own, though.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Fcntl</span> <span class="q">qw(F_GETFL F_SETFL O_NONBLOCK)</span><span class="sc">;</span></li><li></li><li> <span class="i">$flags</span> = <a class="l_k" href="../functions/fcntl.html">fcntl</a><span class="s">(</span><span class="w">REMOTE</span><span class="cm">,</span> <span class="w">F_GETFL</span><span class="cm">,</span> <span class="n">0</span><span class="s">)</span></li><li> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't get flags for the socket: $!\n"</span><span class="sc">;</span></li><li></li><li> <span class="i">$flags</span> = <a class="l_k" href="../functions/fcntl.html">fcntl</a><span class="s">(</span><span class="w">REMOTE</span><span class="cm">,</span> <span class="w">F_SETFL</span><span class="cm">,</span> <span class="i">$flags</span> | <span class="w">O_NONBLOCK</span><span class="s">)</span></li><li> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't set flags for the socket: $!\n"</span><span class="sc">;</span></li></ol><]]></desc>
</keyword>
<keyword name="fileno" type="function">
<params>
<param name='filehandle'/>
</params>
<desc><![CDATA[Returns the file descriptor for a filehandle, or undefined if the<br>
filehandle is not open. This is mainly useful for constructing<br>
bitmaps for <code class="inline"><a class="l_k" href="../functions/select.html">select</a></code> and low-level POSIX tty-handling operations.<br>
If FILEHANDLE is an expression, the value is taken as an indirect<br>
filehandle, generally its name.</p>
<p>You can use this to find out whether two handles refer to the<br>
same underlying descriptor:</p>
<pre class="verbatim"><ol><li> if <span class="s">(</span><a class="l_k" href="../functions/fileno.html">fileno</a><span class="s">(</span><span class="w">THIS</span><span class="s">)</span> == <a class="l_k" href="../functions/fileno.html">fileno</a><span class="s">(</span><span class="w">THAT</span><span class="s">)</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"THIS and THAT are dups\n"</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>(Filehandles connected to memory objects via new features of <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> may<br>
return undefined even though they are open.)]]></desc>
</keyword>
<keyword name="flock" type="function">
<params>
<param name='filehandle'/>
<param name='operation'/>
</params>
<desc><![CDATA[Calls flock(2), or an emulation of it, on FILEHANDLE. Returns true<br>
for success, false on failure. Produces a fatal error if used on a<br>
machine that doesn't implement flock(2), fcntl(2) locking, or lockf(3).<br>
<code class="inline"><a class="l_k" href="../functions/flock.html">flock</a></code> is Perl's portable file locking interface, although it locks<br>
only entire files, not records.</p>
<p>Two potentially non-obvious but traditional <code class="inline"><a class="l_k" href="../functions/flock.html">flock</a></code> semantics are<br>
that it waits indefinitely until the lock is granted, and that its locks<br>
<b>merely advisory</b>. Such discretionary locks are more flexible, but offer<br>
fewer guarantees. This means that programs that do not also use <code class="inline"><a class="l_k" href="../functions/flock.html">flock</a></code>
may modify files locked with <code class="inline"><a class="l_k" href="../functions/flock.html">flock</a></code>. See <a href="../perlport.html">perlport</a>, <br>
your port's specific documentation, or your system-specific local manpages<br>
for details. It's best to assume traditional behavior if you're writing<br>
portable programs. (But if you're not, you should as always feel perfectly<br>
free to write for your own system's idiosyncrasies (sometimes called<br>
"features"). Slavish adherence to portability concerns shouldn't get<br>
in the way of your getting your job done.)</p>
<p>OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN, possibly combined with<br>
LOCK_NB. These constants are traditionally valued 1, 2, 8 and 4, but<br>
you can use the symbolic names if you import them from the Fcntl module,<br>
either individually, or as a group using the ':flock' tag. LOCK_SH<br>
requests a shared lock, LOCK_EX requests an exclusive lock, and LOCK_UN<br>
releases a previously requested lock. If LOCK_NB is bitwise-or'ed with<br>
LOCK_SH or LOCK_EX then <code class="inline"><a class="l_k" href="../functions/flock.html">flock</a></code> will return immediately rather than blocking<br>
waiting for the lock (check the return status to see if you got it).</p>
<p>To avoid the possibility of miscoordination, Perl now flushes FILEHANDLE<br>
before locking or unlocking it.</p>
<p>Note that the emulation built with lockf(3) doesn't provide shared<br>
locks, and it requires that FILEHANDLE be open with write intent. These<br>
are the semantics that lockf(3) implements. Most if not all systems<br>
implement lockf(3) in terms of fcntl(2) locking, though, so the<br>
differing semantics shouldn't bite too many people.</p>
<p>Note that the fcntl(2) emulation of flock(3) requires that FILEHANDLE<br>
be open with read intent to use LOCK_SH and requires that it be open<br>
with write intent to use LOCK_EX.</p>
<p>Note also that some versions of <code class="inline"><a class="l_k" href="../functions/flock.html">flock</a></code> cannot lock things over the<br>
network; you would need to use the more system-specific <code class="inline"><a class="l_k" href="../functions/fcntl.html">fcntl</a></code> for<br>
that. If you like you can force Perl to ignore your system's flock(2)<br>
function, and so provide its own fcntl(2)-based emulation, by passing<br>
the switch <code class="inline">-<span class="w">Ud_flock</span></code>
to the <i>Configure</i> program when you configure<br>
perl.</p>
<p>Here's a mailbox appender for BSD systems.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Fcntl</span> <span class="q">qw(:flock SEEK_END)</span><span class="sc">;</span> <span class="c"># import LOCK_* and SEEK_END constants</span></li><li></li><li><a name="lock"></a> sub <span class="m">lock</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="s">(</span><span class="i">$fh</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/flock.html">flock</a><span class="s">(</span><span class="i">$fh</span><span class="cm">,</span> <span class="w">LOCK_EX</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Cannot lock mailbox - $!\n"</span><span class="sc">;</span></li><li></li><li> <span class="c"># and, in case someone appended while we were waiting...</span></li><li> <a class="l_k" href="../functions/seek.html">seek</a><span class="s">(</span><span class="i">$fh</span><span class="cm">,</span> <span class="n">0</span><span class="cm">,</span> <span class="w">SEEK_END</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Cannot seek - $!\n"</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li></li><li><a name="unlock"></a> sub <span class="m">unlock</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="s">(</span><span class="i">$fh</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/flock.html">flock</a><span class="s">(</span><span class="i">$fh</span><span class="cm">,</span> <span class="w">LOCK_UN</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Cannot unlock mailbox - $!\n"</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$mbox</span><span class="cm">,</span> <span class="q">">>"</span><span class="cm">,</span> <span class="q">"/usr/spool/mail/$ENV{'USER'}"</span><span class="s">)</span></li><li> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't open mailbox: $!"</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/lock.html">lock</a><span class="s">(</span><span class="i">$mbox</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$mbox</span> <span class="i">$msg</span><span class="cm">,</span><span class="q">"\n\n"</span><span class="sc">;</span></li><li> <span class="i">unlock</span><span class="s">(</span><span class="i">$mbox</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>On systems that support a real flock(), locks are inherited across fork()<br>
calls, whereas those that must resort to the more capricious fcntl()<br>
function lose the locks, making it harder to write servers.</p>
<p>See also <a href="../DB_File.html">DB_File</a> for other flock() examples.]]></desc>
</keyword>
<keyword name="fork" type="function">
<params>
</params>
<desc><![CDATA[Does a fork(2) system call to create a new process running the<br>
same program at the same point. It returns the child pid to the<br>
parent process, <code class="inline"><span class="n">0</span></code>
to the child process, or <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> if the fork is<br>
unsuccessful. File descriptors (and sometimes locks on those descriptors)<br>
are shared, while everything else is copied. On most systems supporting<br>
fork(), great care has gone into making it extremely efficient (for<br>
example, using copy-on-write technology on data pages), making it the<br>
dominant paradigm for multitasking over the last few decades.</p>
<p>Beginning with v5.6.0, Perl will attempt to flush all files opened for<br>
output before forking the child process, but this may not be supported<br>
on some platforms (see <a href="../perlport.html">perlport</a>). To be safe, you may need to set<br>
<code class="inline"><span class="i">$|</span></code>
($AUTOFLUSH in English) or call the <code class="inline"><span class="i">autoflush</span><span class="s">(</span><span class="s">)</span></code>
method of<br>
<code class="inline"><span class="w">IO::Handle</span></code>
on any open handles in order to avoid duplicate output.</p>
<p>If you <code class="inline"><a class="l_k" href="../functions/fork.html">fork</a></code> without ever waiting on your children, you will<br>
accumulate zombies. On some systems, you can avoid this by setting<br>
<code class="inline"><span class="i">$SIG</span>{<span class="w">CHLD</span>}</code>
to <code class="inline"><span class="q">"IGNORE"</span></code>
. See also <a href="../perlipc.html">perlipc</a> for more examples of<br>
forking and reaping moribund children.</p>
<p>Note that if your forked child inherits system file descriptors like<br>
STDIN and STDOUT that are actually connected by a pipe or socket, even<br>
if you exit, then the remote server (such as, say, a CGI script or a<br>
backgrounded job launched from a remote shell) won't think you're done.<br>
You should reopen those to <i>/dev/null</i> if it's any issue.]]></desc>
</keyword>
<keyword name="format" type="function">
<params>
</params>
<desc><![CDATA[Declare a picture format for use by the <code class="inline"><a class="l_k" href="../functions/write.html">write</a></code> function. For<br>
example:</p>
<pre class="verbatim"><ol><li> format Something =</li><li> Test: @<<<<<<<< @||||| @>>>>></li><li> $str, $%, '$' . int($num)</li><li> .</li><li></li><li> $str = "widget";</li><li> $num = $cost/$quantity;</li><li> $~ = 'Something';</li><li> write;</li></ol></pre><p>See <a href="../perlform.html">perlform</a> for many details and examples.]]></desc>
</keyword>
<keyword name="formline" type="function">
<params>
<param name='picture'/>
<param name='list'/>
</params>
<desc><![CDATA[This is an internal function used by <code class="inline"><a class="l_k" href="../functions/format.html">format</a></code>s, though you may call it,<br>
too. It formats (see <a href="../perlform.html">perlform</a>) a list of values according to the<br>
contents of PICTURE, placing the output into the format output<br>
accumulator, <code class="inline"><span class="i">$^A</span></code>
(or <code class="inline"><span class="i">$ACCUMULATOR</span></code>
in English).<br>
Eventually, when a <code class="inline"><a class="l_k" href="../functions/write.html">write</a></code> is done, the contents of<br>
<code class="inline"><span class="i">$^A</span></code>
are written to some filehandle. You could also read <code class="inline"><span class="i">$^A</span></code>
<br>
and then set <code class="inline"><span class="i">$^A</span></code>
back to <code class="inline"><span class="q">""</span></code>
. Note that a format typically<br>
does one <code class="inline"><a class="l_k" href="../functions/formline.html">formline</a></code> per line of form, but the <code class="inline"><a class="l_k" href="../functions/formline.html">formline</a></code> function itself<br>
doesn't care how many newlines are embedded in the PICTURE. This means<br>
that the <code class="inline">~</code>
and <code class="inline">~~</code>
tokens will treat the entire PICTURE as a single line.<br>
You may therefore need to use multiple formlines to implement a single<br>
record format, just like the format compiler.</p>
<p>Be careful if you put double quotes around the picture, because an <code class="inline"><span class="i">@</span></code>
<br>
character may be taken to mean the beginning of an array name.<br>
<code class="inline"><a class="l_k" href="../functions/formline.html">formline</a></code> always returns true. See <a href="../perlform.html">perlform</a> for other examples.]]></desc>
</keyword>
<keyword name="getc" type="function">
<params>
<param name='filehandle'/>
</params>
<desc><![CDATA[Returns the next character from the input file attached to FILEHANDLE,<br>
or the undefined value at end of file, or if there was an error (in<br>
the latter case <code class="inline"><span class="i">$!</span></code>
is set). If FILEHANDLE is omitted, reads from<br>
STDIN. This is not particularly efficient. However, it cannot be<br>
used by itself to fetch single characters without waiting for the user<br>
to hit enter. For that, try something more like:</p>
<pre class="verbatim"><ol><li> if <span class="s">(</span><span class="i">$BSD_STYLE</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/system.html">system</a> <span class="q">"stty cbreak </dev/tty >/dev/tty 2>&1"</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> else <span class="s">{</span></li><li> <a class="l_k" href="../functions/system.html">system</a> <span class="q">"stty"</span><span class="cm">,</span> <span class="q">'-icanon'</span><span class="cm">,</span> <span class="q">'eol'</span><span class="cm">,</span> <span class="q">"\001"</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li></li><li> <span class="i">$key</span> = <a class="l_k" href="../functions/getc.html">getc</a><span class="s">(</span><span class="w">STDIN</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> if <span class="s">(</span><span class="i">$BSD_STYLE</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/system.html">system</a> <span class="q">"stty -cbreak </dev/tty >/dev/tty 2>&1"</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> else <span class="s">{</span></li><li> <a class="l_k" href="../functions/system.html">system</a> <span class="q">"stty"</span><span class="cm">,</span> <span class="q">'icanon'</span><span class="cm">,</span> <span class="q">'eol'</span><span class="cm">,</span> <span class="q">'^@'</span><span class="sc">;</span> <span class="c"># ASCII null</span></li><li> <span class="s">}</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"\n"</span><span class="sc">;</span></li></ol></pre><p>Determination of whether $BSD_STYLE should be set<br>
is left as an exercise to the reader.</p>
<p>The <code class="inline"><span class="w">POSIX::getattr</span></code>
function can do this more portably on<br>
systems purporting POSIX compliance. See also the <code class="inline"><span class="w">Term::ReadKey</span></code>
<br>
module from your nearest CPAN site; details on CPAN can be found on<br>
<a href="../perlmodlib.html#CPAN">"CPAN" in perlmodlib</a>.]]></desc>
</keyword>
<keyword name="getc" type="function">
<params>
</params>
<desc><![CDATA[Returns the next character from the input file attached to FILEHANDLE,<br>
or the undefined value at end of file, or if there was an error (in<br>
the latter case <code class="inline"><span class="i">$!</span></code>
is set). If FILEHANDLE is omitted, reads from<br>
STDIN. This is not particularly efficient. However, it cannot be<br>
used by itself to fetch single characters without waiting for the user<br>
to hit enter. For that, try something more like:</p>
<pre class="verbatim"><ol><li> if <span class="s">(</span><span class="i">$BSD_STYLE</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/system.html">system</a> <span class="q">"stty cbreak </dev/tty >/dev/tty 2>&1"</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> else <span class="s">{</span></li><li> <a class="l_k" href="../functions/system.html">system</a> <span class="q">"stty"</span><span class="cm">,</span> <span class="q">'-icanon'</span><span class="cm">,</span> <span class="q">'eol'</span><span class="cm">,</span> <span class="q">"\001"</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li></li><li> <span class="i">$key</span> = <a class="l_k" href="../functions/getc.html">getc</a><span class="s">(</span><span class="w">STDIN</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> if <span class="s">(</span><span class="i">$BSD_STYLE</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/system.html">system</a> <span class="q">"stty -cbreak </dev/tty >/dev/tty 2>&1"</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> else <span class="s">{</span></li><li> <a class="l_k" href="../functions/system.html">system</a> <span class="q">"stty"</span><span class="cm">,</span> <span class="q">'icanon'</span><span class="cm">,</span> <span class="q">'eol'</span><span class="cm">,</span> <span class="q">'^@'</span><span class="sc">;</span> <span class="c"># ASCII null</span></li><li> <span class="s">}</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"\n"</span><span class="sc">;</span></li></ol></pre><p>Determination of whether $BSD_STYLE should be set<br>
is left as an exercise to the reader.</p>
<p>The <code class="inline"><span class="w">POSIX::getattr</span></code>
function can do this more portably on<br>
systems purporting POSIX compliance. See also the <code class="inline"><span class="w">Term::ReadKey</span></code>
<br>
module from your nearest CPAN site; details on CPAN can be found on<br>
<a href="../perlmodlib.html#CPAN">"CPAN" in perlmodlib</a>.]]></desc>
</keyword>
<keyword name="getgrent" type="function">
<params>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="getgrgid" type="function">
<params>
<param name='gid'/>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="getgrnam" type="function">
<params>
<param name='name'/>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="gethostbyaddr" type="function">
<params>
<param name='addr'/>
<param name='addrtype'/>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="gethostbyname" type="function">
<params>
<param name='name'/>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="gethostent" type="function">
<params>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="getlogin" type="function">
<params>
</params>
<desc><![CDATA[This implements the C library function of the same name, which on most<br>
systems returns the current login from <i>/etc/utmp</i>, if any. If null,<br>
use <code class="inline"><a class="l_k" href="../functions/getpwuid.html">getpwuid</a></code>.</p>
<pre class="verbatim"><ol><li> <span class="i">$login</span> = <a class="l_k" href="../functions/getlogin.html">getlogin</a> || <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$<</span><span class="s">)</span> || <span class="q">"Kilroy"</span><span class="sc">;</span></li></ol></pre><p>Do not consider <code class="inline"><a class="l_k" href="../functions/getlogin.html">getlogin</a></code> for authentication: it is not as<br>
secure as <code class="inline"><a class="l_k" href="../functions/getpwuid.html">getpwuid</a></code>.]]></desc>
</keyword>
<keyword name="getnetbyaddr" type="function">
<params>
<param name='addr'/>
<param name='addrtype'/>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="getnetbyname" type="function">
<params>
<param name='name'/>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="getnetent" type="function">
<params>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="getpeername" type="function">
<params>
<param name='socket'/>
</params>
<desc><![CDATA[Returns the packed sockaddr address of other end of the SOCKET connection.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$hersockaddr</span> = <a class="l_k" href="../functions/getpeername.html">getpeername</a><span class="s">(</span><span class="w">SOCK</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">(</span><span class="i">$port</span><span class="cm">,</span> <span class="i">$iaddr</span><span class="s">)</span> = <span class="i">sockaddr_in</span><span class="s">(</span><span class="i">$hersockaddr</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$herhostname</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$herstraddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol><]]></desc>
</keyword>
<keyword name="getpgrp" type="function">
<params>
<param name='pid'/>
</params>
<desc><![CDATA[Returns the current process group for the specified PID. Use<br>
a PID of <code class="inline"><span class="n">0</span></code>
to get the current process group for the<br>
current process. Will raise an exception if used on a machine that<br>
doesn't implement getpgrp(2). If PID is omitted, returns process<br>
group of current process. Note that the POSIX version of <code class="inline"><a class="l_k" href="../functions/getpgrp.html">getpgrp</a></code>
does not accept a PID argument, so only <code class="inline"><span class="w">PID</span>==<span class="n">0</span></code>
is truly portable.]]></desc>
</keyword>
<keyword name="getppid" type="function">
<params>
</params>
<desc><![CDATA[Returns the process id of the parent process.</p>
<p>Note for Linux users: on Linux, the C functions <code class="inline"><span class="i">getpid</span><span class="s">(</span><span class="s">)</span></code>
and<br>
<code class="inline"><a class="l_k" href="../functions/getppid.html">getppid()</a></code> return different values from different threads. In order to<br>
be portable, this behavior is not reflected by the perl-level function<br>
<code class="inline"><a class="l_k" href="../functions/getppid.html">getppid()</a></code>, that returns a consistent value across threads. If you want<br>
to call the underlying <code class="inline"><a class="l_k" href="../functions/getppid.html">getppid()</a></code>, you may use the CPAN module<br>
<code class="inline"><span class="w">Linux::Pid</span></code>
.]]></desc>
</keyword>
<keyword name="getpriority" type="function">
<params>
<param name='which'/>
<param name='who'/>
</params>
<desc><![CDATA[Returns the current priority for a process, a process group, or a user.<br>
(See <code class="inline"><a class="l_k" href="../functions/getpriority.html">getpriority(2)</a></code>.) Will raise a fatal exception if used on a<br>
machine that doesn't implement getpriority(2).]]></desc>
</keyword>
<keyword name="getprotobyname" type="function">
<params>
<param name='name'/>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="getprotobynumber" type="function">
<params>
<param name='number'/>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="getprotoent" type="function">
<params>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="getpwent" type="function">
<params>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="getpwnam" type="function">
<params>
<param name='name'/>
</params>
<desc></desc>
</keyword>
<keyword name="getpwuid" type="function">
<params>
<param name='uid'/>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="getservbyname" type="function">
<params>
<param name='name'/>
<param name='proto'/>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="getservbyport" type="function">
<params>
<param name='port'/>
<param name='proto'/>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="getservent" type="function">
<params>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="getsockname" type="function">
<params>
<param name='socket'/>
</params>
<desc><![CDATA[Returns the packed sockaddr address of this end of the SOCKET connection,<br>
in case you don't know the address because you have several different<br>
IPs that the connection might have come in on.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$mysockaddr</span> = <a class="l_k" href="../functions/getsockname.html">getsockname</a><span class="s">(</span><span class="w">SOCK</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">(</span><span class="i">$port</span><span class="cm">,</span> <span class="i">$myaddr</span><span class="s">)</span> = <span class="i">sockaddr_in</span><span class="s">(</span><span class="i">$mysockaddr</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"Connect to %s [%s]\n"</span><span class="cm">,</span></li><li> <a class="l_k" href="../functions/scalar.html">scalar</a> <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$myaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="cm">,</span></li><li> <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$myaddr</span><span class="s">)</span><span class="sc">;</span></li></ol><]]></desc>
</keyword>
<keyword name="getsockopt" type="function">
<params>
<param name='socket'/>
<param name='level'/>
<param name='optname'/>
</params>
<desc><![CDATA[Queries the option named OPTNAME associated with SOCKET at a given LEVEL.<br>
Options may exist at multiple protocol levels depending on the socket<br>
type, but at least the uppermost socket level SOL_SOCKET (defined in the<br>
<code class="inline"><span class="w">Socket</span></code>
module) will exist. To query options at another level the<br>
protocol number of the appropriate protocol controlling the option<br>
should be supplied. For example, to indicate that an option is to be<br>
interpreted by the TCP protocol, LEVEL should be set to the protocol<br>
number of TCP, which you can get using getprotobyname.</p>
<p>The call returns a packed string representing the requested socket option,<br>
or <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> if there is an error (the error reason will be in $!). What<br>
exactly is in the packed string depends in the LEVEL and OPTNAME, consult<br>
your system documentation for details. A very common case however is that<br>
the option is an integer, in which case the result will be a packed<br>
integer which you can decode using unpack with the <code class="inline"><span class="w">i</span></code>
(or <code class="inline"><span class="w">I</span></code>
) format.</p>
<p>An example testing if Nagle's algorithm is turned on on a socket:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span> <span class="q">qw(:all)</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/defined.html">defined</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$tcp</span> = <a class="l_k" href="../functions/getprotobyname.html">getprotobyname</a><span class="s">(</span><span class="q">"tcp"</span><span class="s">)</span><span class="s">)</span></li><li> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Could not determine the protocol number for tcp"</span><span class="sc">;</span></li><li> <span class="c"># my $tcp = IPPROTO_TCP; # Alternative</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$packed</span> = <a class="l_k" href="../functions/getsockopt.html">getsockopt</a><span class="s">(</span><span class="i">$socket</span><span class="cm">,</span> <span class="i">$tcp</span><span class="cm">,</span> <span class="w">TCP_NODELAY</span><span class="s">)</span></li><li> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Could not query TCP_NODELAY socket option: $!"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$nodelay</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">"I"</span><span class="cm">,</span> <span class="i">$packed</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"Nagle's algorithm is turned "</span><span class="cm">,</span> <span class="i">$nodelay</span> ? <span class="q">"off\n"</span> <span class="co">:</span> <span class="q">"on\n"</span><span class="sc">;</span></li></ol><]]></desc>
</keyword>
<keyword name="glob" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[In list context, returns a (possibly empty) list of filename expansions on<br>
the value of EXPR such as the standard Unix shell <i>/bin/csh</i> would do. In<br>
scalar context, glob iterates through such filename expansions, returning<br>
undef when the list is exhausted. This is the internal function<br>
implementing the <code class="inline"><span class="q"><*.c></span></code>
operator, but you can use it directly. If<br>
EXPR is omitted, <code class="inline"><span class="i">$_</span></code>
is used. The <code class="inline"><span class="q"><*.c></span></code>
operator is discussed in<br>
more detail in <a href="../perlop.html#I%2fO-Operators">"I/O Operators" in perlop</a>.</p>
<p>Note that <code class="inline"><a class="l_k" href="../functions/glob.html">glob</a></code> will split its arguments on whitespace, treating<br>
each segment as separate pattern. As such, <code class="inline"><a class="l_k" href="../functions/glob.html">glob</a><span class="s">(</span><span class="q">'*.c *.h'</span><span class="s">)</span></code>
would<br>
match all files with a <i>.c</i> or <i>.h</i> extension. The expression<br>
<code class="inline"><a class="l_k" href="../functions/glob.html">glob</a><span class="s">(</span><span class="q">'.* *'</span><span class="s">)</span></code>
would match all files in the current working directory.</p>
<p>Beginning with v5.6.0, this operator is implemented using the standard<br>
<code class="inline"><span class="w">File::Glob</span></code>
extension. See <a href="../File/Glob.html">File::Glob</a> for details, including<br>
<code class="inline"><span class="w">bsd_glob</span></code>
which does not treat whitespace as a pattern separator.]]></desc>
</keyword>
<keyword name="glob" type="function">
<params>
</params>
<desc><![CDATA[In list context, returns a (possibly empty) list of filename expansions on<br>
the value of EXPR such as the standard Unix shell <i>/bin/csh</i> would do. In<br>
scalar context, glob iterates through such filename expansions, returning<br>
undef when the list is exhausted. This is the internal function<br>
implementing the <code class="inline"><span class="q"><*.c></span></code>
operator, but you can use it directly. If<br>
EXPR is omitted, <code class="inline"><span class="i">$_</span></code>
is used. The <code class="inline"><span class="q"><*.c></span></code>
operator is discussed in<br>
more detail in <a href="../perlop.html#I%2fO-Operators">"I/O Operators" in perlop</a>.</p>
<p>Note that <code class="inline"><a class="l_k" href="../functions/glob.html">glob</a></code> will split its arguments on whitespace, treating<br>
each segment as separate pattern. As such, <code class="inline"><a class="l_k" href="../functions/glob.html">glob</a><span class="s">(</span><span class="q">'*.c *.h'</span><span class="s">)</span></code>
would<br>
match all files with a <i>.c</i> or <i>.h</i> extension. The expression<br>
<code class="inline"><a class="l_k" href="../functions/glob.html">glob</a><span class="s">(</span><span class="q">'.* *'</span><span class="s">)</span></code>
would match all files in the current working directory.</p>
<p>Beginning with v5.6.0, this operator is implemented using the standard<br>
<code class="inline"><span class="w">File::Glob</span></code>
extension. See <a href="../File/Glob.html">File::Glob</a> for details, including<br>
<code class="inline"><span class="w">bsd_glob</span></code>
which does not treat whitespace as a pattern separator.]]></desc>
</keyword>
<keyword name="gmtime" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Works just like <a href="../functions/localtime.html">localtime</a> but the returned values are<br>
localized for the standard Greenwich time zone.</p>
<p>Note: when called in list context, $isdst, the last value<br>
returned by gmtime is always <code class="inline"><span class="n">0</span></code>
. There is no<br>
Daylight Saving Time in GMT.</p>
<p>See <a href="../perlport.html#gmtime">"gmtime" in perlport</a> for portability concerns.]]></desc>
</keyword>
<keyword name="gmtime" type="function">
<params>
</params>
<desc><![CDATA[Works just like <a href="../functions/localtime.html">localtime</a> but the returned values are<br>
localized for the standard Greenwich time zone.</p>
<p>Note: when called in list context, $isdst, the last value<br>
returned by gmtime is always <code class="inline"><span class="n">0</span></code>
. There is no<br>
Daylight Saving Time in GMT.</p>
<p>See <a href="../perlport.html#gmtime">"gmtime" in perlport</a> for portability concerns.]]></desc>
</keyword>
<keyword name="goto" type="function">
<params>
<param name='&name'/>
</params>
<desc><![CDATA[The <code class="inline"><a class="l_k" href="../functions/goto.html">goto-LABEL</a></code> form finds the statement labeled with LABEL and resumes<br>
execution there. It may not be used to go into any construct that<br>
requires initialization, such as a subroutine or a <code class="inline">foreach</code>
loop. It<br>
also can't be used to go into a construct that is optimized away,<br>
or to get out of a block or subroutine given to <code class="inline"><a class="l_k" href="../functions/sort.html">sort</a></code>.<br>
It can be used to go almost anywhere else within the dynamic scope,<br>
including out of subroutines, but it's usually better to use some other<br>
construct such as <code class="inline"><a class="l_k" href="../functions/last.html">last</a></code> or <code class="inline"><a class="l_k" href="../functions/die.html">die</a></code>. The author of Perl has never felt the<br>
need to use this form of <code class="inline"><a class="l_k" href="../functions/goto.html">goto</a></code> (in Perl, that is--C is another matter).<br>
(The difference being that C does not offer named loops combined with<br>
loop control. Perl does, and this replaces most structured uses of <code class="inline"><a class="l_k" href="../functions/goto.html">goto</a></code>
in other languages.)</p>
<p>The <code class="inline"><a class="l_k" href="../functions/goto.html">goto-EXPR</a></code> form expects a label name, whose scope will be resolved<br>
dynamically. This allows for computed <code class="inline"><a class="l_k" href="../functions/goto.html">goto</a></code>s per FORTRAN, but isn't<br>
necessarily recommended if you're optimizing for maintainability:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/goto.html">goto</a> <span class="s">(</span><span class="q">"FOO"</span><span class="cm">,</span> <span class="q">"BAR"</span><span class="cm">,</span> <span class="q">"GLARCH"</span><span class="s">)</span>[<span class="i">$i</span>]<span class="sc">;</span></li></ol></pre><p>The <code class="inline"><a class="l_k" href="../functions/goto.html">goto-&NAME</a></code> form is quite different from the other forms of<br>
<code class="inline"><a class="l_k" href="../functions/goto.html">goto</a></code>. In fact, it isn't a goto in the normal sense at all, and<br>
doesn't have the stigma associated with other gotos. Instead, it<br>
exits the current subroutine (losing any changes set by local()) and<br>
immediately calls in its place the named subroutine using the current<br>
value of @_. This is used by <code class="inline">AUTOLOAD</code>
subroutines that wish to<br>
load another subroutine and then pretend that the other subroutine had<br>
been called in the first place (except that any modifications to <code class="inline"><span class="i">@_</span></code>
<br>
in the current subroutine are propagated to the other subroutine.)<br>
After the <code class="inline"><a class="l_k" href="../functions/goto.html">goto</a></code>, not even <code class="inline"><a class="l_k" href="../functions/caller.html">caller</a></code> will be able to tell that this<br>
routine was called first.</p>
<p>NAME needn't be the name of a subroutine; it can be a scalar variable<br>
containing a code reference, or a block that evaluates to a code<br>
reference.]]></desc>
</keyword>
<keyword name="goto" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[The <code class="inline"><a class="l_k" href="../functions/goto.html">goto-LABEL</a></code> form finds the statement labeled with LABEL and resumes<br>
execution there. It may not be used to go into any construct that<br>
requires initialization, such as a subroutine or a <code class="inline">foreach</code>
loop. It<br>
also can't be used to go into a construct that is optimized away,<br>
or to get out of a block or subroutine given to <code class="inline"><a class="l_k" href="../functions/sort.html">sort</a></code>.<br>
It can be used to go almost anywhere else within the dynamic scope,<br>
including out of subroutines, but it's usually better to use some other<br>
construct such as <code class="inline"><a class="l_k" href="../functions/last.html">last</a></code> or <code class="inline"><a class="l_k" href="../functions/die.html">die</a></code>. The author of Perl has never felt the<br>
need to use this form of <code class="inline"><a class="l_k" href="../functions/goto.html">goto</a></code> (in Perl, that is--C is another matter).<br>
(The difference being that C does not offer named loops combined with<br>
loop control. Perl does, and this replaces most structured uses of <code class="inline"><a class="l_k" href="../functions/goto.html">goto</a></code>
in other languages.)</p>
<p>The <code class="inline"><a class="l_k" href="../functions/goto.html">goto-EXPR</a></code> form expects a label name, whose scope will be resolved<br>
dynamically. This allows for computed <code class="inline"><a class="l_k" href="../functions/goto.html">goto</a></code>s per FORTRAN, but isn't<br>
necessarily recommended if you're optimizing for maintainability:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/goto.html">goto</a> <span class="s">(</span><span class="q">"FOO"</span><span class="cm">,</span> <span class="q">"BAR"</span><span class="cm">,</span> <span class="q">"GLARCH"</span><span class="s">)</span>[<span class="i">$i</span>]<span class="sc">;</span></li></ol></pre><p>The <code class="inline"><a class="l_k" href="../functions/goto.html">goto-&NAME</a></code> form is quite different from the other forms of<br>
<code class="inline"><a class="l_k" href="../functions/goto.html">goto</a></code>. In fact, it isn't a goto in the normal sense at all, and<br>
doesn't have the stigma associated with other gotos. Instead, it<br>
exits the current subroutine (losing any changes set by local()) and<br>
immediately calls in its place the named subroutine using the current<br>
value of @_. This is used by <code class="inline">AUTOLOAD</code>
subroutines that wish to<br>
load another subroutine and then pretend that the other subroutine had<br>
been called in the first place (except that any modifications to <code class="inline"><span class="i">@_</span></code>
<br>
in the current subroutine are propagated to the other subroutine.)<br>
After the <code class="inline"><a class="l_k" href="../functions/goto.html">goto</a></code>, not even <code class="inline"><a class="l_k" href="../functions/caller.html">caller</a></code> will be able to tell that this<br>
routine was called first.</p>
<p>NAME needn't be the name of a subroutine; it can be a scalar variable<br>
containing a code reference, or a block that evaluates to a code<br>
reference.]]></desc>
</keyword>
<keyword name="goto" type="function">
<params>
<param name='label'/>
</params>
<desc><![CDATA[The <code class="inline"><a class="l_k" href="../functions/goto.html">goto-LABEL</a></code> form finds the statement labeled with LABEL and resumes<br>
execution there. It may not be used to go into any construct that<br>
requires initialization, such as a subroutine or a <code class="inline">foreach</code>
loop. It<br>
also can't be used to go into a construct that is optimized away,<br>
or to get out of a block or subroutine given to <code class="inline"><a class="l_k" href="../functions/sort.html">sort</a></code>.<br>
It can be used to go almost anywhere else within the dynamic scope,<br>
including out of subroutines, but it's usually better to use some other<br>
construct such as <code class="inline"><a class="l_k" href="../functions/last.html">last</a></code> or <code class="inline"><a class="l_k" href="../functions/die.html">die</a></code>. The author of Perl has never felt the<br>
need to use this form of <code class="inline"><a class="l_k" href="../functions/goto.html">goto</a></code> (in Perl, that is--C is another matter).<br>
(The difference being that C does not offer named loops combined with<br>
loop control. Perl does, and this replaces most structured uses of <code class="inline"><a class="l_k" href="../functions/goto.html">goto</a></code>
in other languages.)</p>
<p>The <code class="inline"><a class="l_k" href="../functions/goto.html">goto-EXPR</a></code> form expects a label name, whose scope will be resolved<br>
dynamically. This allows for computed <code class="inline"><a class="l_k" href="../functions/goto.html">goto</a></code>s per FORTRAN, but isn't<br>
necessarily recommended if you're optimizing for maintainability:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/goto.html">goto</a> <span class="s">(</span><span class="q">"FOO"</span><span class="cm">,</span> <span class="q">"BAR"</span><span class="cm">,</span> <span class="q">"GLARCH"</span><span class="s">)</span>[<span class="i">$i</span>]<span class="sc">;</span></li></ol></pre><p>The <code class="inline"><a class="l_k" href="../functions/goto.html">goto-&NAME</a></code> form is quite different from the other forms of<br>
<code class="inline"><a class="l_k" href="../functions/goto.html">goto</a></code>. In fact, it isn't a goto in the normal sense at all, and<br>
doesn't have the stigma associated with other gotos. Instead, it<br>
exits the current subroutine (losing any changes set by local()) and<br>
immediately calls in its place the named subroutine using the current<br>
value of @_. This is used by <code class="inline">AUTOLOAD</code>
subroutines that wish to<br>
load another subroutine and then pretend that the other subroutine had<br>
been called in the first place (except that any modifications to <code class="inline"><span class="i">@_</span></code>
<br>
in the current subroutine are propagated to the other subroutine.)<br>
After the <code class="inline"><a class="l_k" href="../functions/goto.html">goto</a></code>, not even <code class="inline"><a class="l_k" href="../functions/caller.html">caller</a></code> will be able to tell that this<br>
routine was called first.</p>
<p>NAME needn't be the name of a subroutine; it can be a scalar variable<br>
containing a code reference, or a block that evaluates to a code<br>
reference.]]></desc>
</keyword>
<keyword name="grep" type="function">
<params>
<param name='block list'/>
</params>
<desc><![CDATA[This is similar in spirit to, but not the same as, grep(1) and its<br>
relatives. In particular, it is not limited to using regular expressions.</p>
<p>Evaluates the BLOCK or EXPR for each element of LIST (locally setting<br>
<code class="inline"><span class="i">$_</span></code>
to each element) and returns the list value consisting of those<br>
elements for which the expression evaluated to true. In scalar<br>
context, returns the number of times the expression was true.</p>
<pre class="verbatim"><ol><li> <span class="i">@foo</span> = <a class="l_k" href="../functions/grep.html">grep</a><span class="s">(</span>!<span class="q">/^#/</span><span class="cm">,</span> <span class="i">@bar</span><span class="s">)</span><span class="sc">;</span> <span class="c"># weed out comments</span></li></ol></pre><p>or equivalently,</p>
<pre class="verbatim"><ol><li> <span class="i">@foo</span> = <a class="l_k" href="../functions/grep.html">grep</a> <span class="s">{</span>!<span class="q">/^#/</span><span class="s">}</span> <span class="i">@bar</span><span class="sc">;</span> <span class="c"># weed out comments</span></li></ol></pre><p>Note that <code class="inline"><span class="i">$_</span></code>
is an alias to the list value, so it can be used to<br>
modify the elements of the LIST. While this is useful and supported,<br>
it can cause bizarre results if the elements of LIST are not variables.<br>
Similarly, grep returns aliases into the original list, much as a for<br>
loop's index variable aliases the list elements. That is, modifying an<br>
element of a list returned by grep (for example, in a <code class="inline">foreach</code>
, <code class="inline"><a class="l_k" href="../functions/map.html">map</a></code>
or another <code class="inline"><a class="l_k" href="../functions/grep.html">grep</a></code>) actually modifies the element in the original list.<br>
This is usually something to be avoided when writing clear code.</p>
<p>If <code class="inline"><span class="i">$_</span></code>
is lexical in the scope where the <code class="inline"><a class="l_k" href="../functions/grep.html">grep</a></code> appears (because it has<br>
been declared with <code class="inline"><a class="l_k" href="../functions/my.html">my</a> <span class="i">$_</span></code>
) then, in addition to being locally aliased to<br>
the list elements, <code class="inline"><span class="i">$_</span></code>
keeps being lexical inside the block; i.e. it<br>
can't be seen from the outside, avoiding any potential side-effects.</p>
<p>See also <a href="../functions/map.html">"map"</a> for a list composed of the results of the BLOCK or EXPR.]]></desc>
</keyword>
<keyword name="grep" type="function">
<params>
<param name='expr'/>
<param name='list'/>
</params>
<desc><![CDATA[This is similar in spirit to, but not the same as, grep(1) and its<br>
relatives. In particular, it is not limited to using regular expressions.</p>
<p>Evaluates the BLOCK or EXPR for each element of LIST (locally setting<br>
<code class="inline"><span class="i">$_</span></code>
to each element) and returns the list value consisting of those<br>
elements for which the expression evaluated to true. In scalar<br>
context, returns the number of times the expression was true.</p>
<pre class="verbatim"><ol><li> <span class="i">@foo</span> = <a class="l_k" href="../functions/grep.html">grep</a><span class="s">(</span>!<span class="q">/^#/</span><span class="cm">,</span> <span class="i">@bar</span><span class="s">)</span><span class="sc">;</span> <span class="c"># weed out comments</span></li></ol></pre><p>or equivalently,</p>
<pre class="verbatim"><ol><li> <span class="i">@foo</span> = <a class="l_k" href="../functions/grep.html">grep</a> <span class="s">{</span>!<span class="q">/^#/</span><span class="s">}</span> <span class="i">@bar</span><span class="sc">;</span> <span class="c"># weed out comments</span></li></ol></pre><p>Note that <code class="inline"><span class="i">$_</span></code>
is an alias to the list value, so it can be used to<br>
modify the elements of the LIST. While this is useful and supported,<br>
it can cause bizarre results if the elements of LIST are not variables.<br>
Similarly, grep returns aliases into the original list, much as a for<br>
loop's index variable aliases the list elements. That is, modifying an<br>
element of a list returned by grep (for example, in a <code class="inline">foreach</code>
, <code class="inline"><a class="l_k" href="../functions/map.html">map</a></code>
or another <code class="inline"><a class="l_k" href="../functions/grep.html">grep</a></code>) actually modifies the element in the original list.<br>
This is usually something to be avoided when writing clear code.</p>
<p>If <code class="inline"><span class="i">$_</span></code>
is lexical in the scope where the <code class="inline"><a class="l_k" href="../functions/grep.html">grep</a></code> appears (because it has<br>
been declared with <code class="inline"><a class="l_k" href="../functions/my.html">my</a> <span class="i">$_</span></code>
) then, in addition to being locally aliased to<br>
the list elements, <code class="inline"><span class="i">$_</span></code>
keeps being lexical inside the block; i.e. it<br>
can't be seen from the outside, avoiding any potential side-effects.</p>
<p>See also <a href="../functions/map.html">"map"</a> for a list composed of the results of the BLOCK or EXPR.]]></desc>
</keyword>
<keyword name="hex" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Interprets EXPR as a hex string and returns the corresponding value.<br>
(To convert strings that might start with either <code class="inline"><span class="n">0</span></code>
, <code class="inline"><span class="n">0</span>x</code>
, or <code class="inline">0b</code>, see<br>
<a href="../functions/oct.html">"oct"</a>.) If EXPR is omitted, uses <code class="inline"><span class="i">$_</span></code>
.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/hex.html">hex</a> <span class="q">'0xAf'</span><span class="sc">;</span> <span class="c"># prints '175'</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/hex.html">hex</a> <span class="q">'aF'</span><span class="sc">;</span> <span class="c"># same</span></li></ol></pre><p>Hex strings may only represent integers. Strings that would cause<br>
integer overflow trigger a warning. Leading whitespace is not stripped,<br>
unlike oct(). To present something as hex, look into <a href="../functions/printf.html">"printf"</a>,<br>
<a href="../functions/sprintf.html">"sprintf"</a>, or <a href="../functions/unpack.html">"unpack"</a>.]]></desc>
</keyword>
<keyword name="hex" type="function">
<params>
</params>
<desc><![CDATA[Interprets EXPR as a hex string and returns the corresponding value.<br>
(To convert strings that might start with either <code class="inline"><span class="n">0</span></code>
, <code class="inline"><span class="n">0</span>x</code>
, or <code class="inline">0b</code>, see<br>
<a href="../functions/oct.html">"oct"</a>.) If EXPR is omitted, uses <code class="inline"><span class="i">$_</span></code>
.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/hex.html">hex</a> <span class="q">'0xAf'</span><span class="sc">;</span> <span class="c"># prints '175'</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/hex.html">hex</a> <span class="q">'aF'</span><span class="sc">;</span> <span class="c"># same</span></li></ol></pre><p>Hex strings may only represent integers. Strings that would cause<br>
integer overflow trigger a warning. Leading whitespace is not stripped,<br>
unlike oct(). To present something as hex, look into <a href="../functions/printf.html">"printf"</a>,<br>
<a href="../functions/sprintf.html">"sprintf"</a>, or <a href="../functions/unpack.html">"unpack"</a>.]]></desc>
</keyword>
<keyword name="import" type="function">
<params>
<param name='list'/>
</params>
<desc><![CDATA[There is no builtin <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> function. It is just an ordinary<br>
method (subroutine) defined (or inherited) by modules that wish to export<br>
names to another module. The <code class="inline"><a class="l_k" href="../functions/use.html">use</a></code> function calls the <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> method<br>
for the package used. See also <a href="../functions/use.html">"use"</a>, <a href="../perlmod.html">perlmod</a>, and <a href="../Exporter.html">Exporter</a>.]]></desc>
</keyword>
<keyword name="index" type="function">
<params>
<param name='str'/>
<param name='substr'/>
<param name='position'/>
</params>
<desc><![CDATA[The index function searches for one string within another, but without<br>
the wildcard-like behavior of a full regular-expression pattern match.<br>
It returns the position of the first occurrence of SUBSTR in STR at<br>
or after POSITION. If POSITION is omitted, starts searching from the<br>
beginning of the string. POSITION before the beginning of the string<br>
or after its end is treated as if it were the beginning or the end,<br>
respectively. POSITION and the return value are based at <code class="inline"><span class="n">0</span></code>
(or whatever<br>
you've set the <code class="inline"><span class="i">$[</span></code>
variable to--but don't do that). If the substring<br>
is not found, <code class="inline"><a class="l_k" href="../functions/index.html">index</a></code> returns one less than the base, ordinarily <code class="inline"><span class="n">-1</span></code>
.]]></desc>
</keyword>
<keyword name="index" type="function">
<params>
<param name='str'/>
<param name='substr'/>
</params>
<desc><![CDATA[The index function searches for one string within another, but without<br>
the wildcard-like behavior of a full regular-expression pattern match.<br>
It returns the position of the first occurrence of SUBSTR in STR at<br>
or after POSITION. If POSITION is omitted, starts searching from the<br>
beginning of the string. POSITION before the beginning of the string<br>
or after its end is treated as if it were the beginning or the end,<br>
respectively. POSITION and the return value are based at <code class="inline"><span class="n">0</span></code>
(or whatever<br>
you've set the <code class="inline"><span class="i">$[</span></code>
variable to--but don't do that). If the substring<br>
is not found, <code class="inline"><a class="l_k" href="../functions/index.html">index</a></code> returns one less than the base, ordinarily <code class="inline"><span class="n">-1</span></code>
.]]></desc>
</keyword>
<keyword name="int" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Returns the integer portion of EXPR. If EXPR is omitted, uses <code class="inline"><span class="i">$_</span></code>
.<br>
You should not use this function for rounding: one because it truncates<br>
towards <code class="inline"><span class="n">0</span></code>
, and two because machine representations of floating point<br>
numbers can sometimes produce counterintuitive results. For example,<br>
<code class="inline"><a class="l_k" href="../functions/int.html">int(-6.725/0.025)</a></code> produces -268 rather than the correct -269; that's<br>
because it's really more like -268.99999999999994315658 instead. Usually,<br>
the <code class="inline"><a class="l_k" href="../functions/sprintf.html">sprintf</a></code>, <code class="inline"><a class="l_k" href="../functions/printf.html">printf</a></code>, or the <code class="inline"><span class="w">POSIX::floor</span></code>
and <code class="inline"><span class="w">POSIX::ceil</span></code>
<br>
functions will serve you better than will int().]]></desc>
</keyword>
<keyword name="int" type="function">
<params>
</params>
<desc><![CDATA[Returns the integer portion of EXPR. If EXPR is omitted, uses <code class="inline"><span class="i">$_</span></code>
.<br>
You should not use this function for rounding: one because it truncates<br>
towards <code class="inline"><span class="n">0</span></code>
, and two because machine representations of floating point<br>
numbers can sometimes produce counterintuitive results. For example,<br>
<code class="inline"><a class="l_k" href="../functions/int.html">int(-6.725/0.025)</a></code> produces -268 rather than the correct -269; that's<br>
because it's really more like -268.99999999999994315658 instead. Usually,<br>
the <code class="inline"><a class="l_k" href="../functions/sprintf.html">sprintf</a></code>, <code class="inline"><a class="l_k" href="../functions/printf.html">printf</a></code>, or the <code class="inline"><span class="w">POSIX::floor</span></code>
and <code class="inline"><span class="w">POSIX::ceil</span></code>
<br>
functions will serve you better than will int().]]></desc>
</keyword>
<keyword name="ioctl" type="function">
<params>
<param name='filehandle'/>
<param name='function'/>
<param name='scalar'/>
</params>
<desc><![CDATA[Implements the ioctl(2) function. You'll probably first have to say</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/require.html">require</a> <span class="q">"sys/ioctl.ph"</span><span class="sc">;</span> <span class="c"># probably in $Config{archlib}/sys/ioctl.ph</span></li></ol></pre><p>to get the correct function definitions. If <i>sys/ioctl.ph</i> doesn't<br>
exist or doesn't have the correct definitions you'll have to roll your<br>
own, based on your C header files such as <i><sys/ioctl.h></i>.<br>
(There is a Perl script called <b>h2ph</b> that comes with the Perl kit that<br>
may help you in this, but it's nontrivial.) SCALAR will be read and/or<br>
written depending on the FUNCTION--a pointer to the string value of SCALAR<br>
will be passed as the third argument of the actual <code class="inline"><a class="l_k" href="../functions/ioctl.html">ioctl</a></code> call. (If SCALAR<br>
has no string value but does have a numeric value, that value will be<br>
passed rather than a pointer to the string value. To guarantee this to be<br>
true, add a <code class="inline"><span class="n">0</span></code>
to the scalar before using it.) The <code class="inline"><a class="l_k" href="../functions/pack.html">pack</a></code> and <code class="inline"><a class="l_k" href="../functions/unpack.html">unpack</a></code>
functions may be needed to manipulate the values of structures used by<br>
<code class="inline"><a class="l_k" href="../functions/ioctl.html">ioctl</a></code>.</p>
<p>The return value of <code class="inline"><a class="l_k" href="../functions/ioctl.html">ioctl</a></code> (and <code class="inline"><a class="l_k" href="../functions/fcntl.html">fcntl</a></code>) is as follows:</p>
<pre class="verbatim"><ol><li> if OS returns: then Perl returns:</li><li> -1 undefined value</li><li> 0 string "0 but true"</li><li> anything else that number</li></ol></pre><p>Thus Perl returns true on success and false on failure, yet you can<br>
still easily determine the actual value returned by the operating<br>
system:</p>
<pre class="verbatim"><ol><li> <span class="i">$retval</span> = <a class="l_k" href="../functions/ioctl.html">ioctl</a><span class="s">(</span>...<span class="s">)</span> || <span class="n">-1</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"System returned %d\n"</span><span class="cm">,</span> <span class="i">$retval</span><span class="sc">;</span></li></ol></pre><p>The special string <code class="inline"><span class="q">"0 but true"</span></code>
is exempt from <b>-w</b> complaints<br>
about improper numeric conversions.]]></desc>
</keyword>
<keyword name="join" type="function">
<params>
<param name='expr'/>
<param name='list'/>
</params>
<desc><![CDATA[Joins the separate strings of LIST into a single string with fields<br>
separated by the value of EXPR, and returns that new string. Example:</p>
<pre class="verbatim"><ol><li> <span class="i">$rec</span> = <a class="l_k" href="../functions/join.html">join</a><span class="s">(</span><span class="q">':'</span><span class="cm">,</span> <span class="i">$login</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$home</span><span class="cm">,</span><span class="i">$shell</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Beware that unlike <code class="inline"><a class="l_k" href="../functions/split.html">split</a></code>, <code class="inline"><a class="l_k" href="../functions/join.html">join</a></code> doesn't take a pattern as its<br>
first argument. Compare <a href="../functions/split.html">"split"</a>.]]></desc>
</keyword>
<keyword name="keys" type="function">
<params>
<param name='hash'/>
</params>
<desc><![CDATA[Returns a list consisting of all the keys of the named hash.<br>
(In scalar context, returns the number of keys.)</p>
<p>The keys are returned in an apparently random order. The actual<br>
random order is subject to change in future versions of perl, but it<br>
is guaranteed to be the same order as either the <code class="inline"><a class="l_k" href="../functions/values.html">values</a></code> or <code class="inline"><a class="l_k" href="../functions/each.html">each</a></code>
function produces (given that the hash has not been modified). Since<br>
Perl 5.8.1 the ordering is different even between different runs of<br>
Perl for security reasons (see <a href="../perlsec.html#Algorithmic-Complexity-Attacks">"Algorithmic Complexity Attacks" in perlsec</a>).</p>
<p>As a side effect, calling keys() resets the HASH's internal iterator<br>
(see <a href="../functions/each.html">"each"</a>). In particular, calling keys() in void context resets<br>
the iterator with no other overhead.</p>
<p>Here is yet another way to print your environment:</p>
<pre class="verbatim"><ol><li> <span class="i">@keys</span> = <a class="l_k" href="../functions/keys.html">keys</a> <span class="i">%ENV</span><span class="sc">;</span></li><li> <span class="i">@values</span> = <a class="l_k" href="../functions/values.html">values</a> <span class="i">%ENV</span><span class="sc">;</span></li><li> while <span class="s">(</span><span class="i">@keys</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/pop.html">pop</a><span class="s">(</span><span class="i">@keys</span><span class="s">)</span><span class="cm">,</span> <span class="q">'='</span><span class="cm">,</span> <a class="l_k" href="../functions/pop.html">pop</a><span class="s">(</span><span class="i">@values</span><span class="s">)</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>or how about sorted by key:</p>
<pre class="verbatim"><ol><li> foreach <span class="i">$key</span> <span class="s">(</span><a class="l_k" href="../functions/sort.html">sort</a><span class="s">(</span><a class="l_k" href="../functions/keys.html">keys</a> <span class="i">%ENV</span><span class="s">)</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$key</span><span class="cm">,</span> <span class="q">'='</span><span class="cm">,</span> <span class="i">$ENV</span>{<span class="i">$key</span>}<span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>The returned values are copies of the original keys in the hash, so<br>
modifying them will not affect the original hash. Compare <a href="../functions/values.html">"values"</a>.</p>
<p>To sort a hash by value, you'll need to use a <code class="inline"><a class="l_k" href="../functions/sort.html">sort</a></code> function.<br>
Here's a descending numeric sort of a hash by its values:</p>
<pre class="verbatim"><ol><li> foreach <span class="i">$key</span> <span class="s">(</span><a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span> <span class="i">$hash</span>{<span class="i">$b</span>} <=> <span class="i">$hash</span>{<span class="i">$a</span>} <span class="s">}</span> <a class="l_k" href="../functions/keys.html">keys</a> <span class="i">%hash</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"%4d %s\n"</span><span class="cm">,</span> <span class="i">$hash</span>{<span class="i">$key</span>}<span class="cm">,</span> <span class="i">$key</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>As an lvalue <code class="inline"><a class="l_k" href="../functions/keys.html">keys</a></code> allows you to increase the number of hash buckets<br>
allocated for the given hash. This can gain you a measure of efficiency if<br>
you know the hash is going to get big. (This is similar to pre-extending<br>
an array by assigning a larger number to $#array.) If you say</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/keys.html">keys</a> <span class="i">%hash</span> = <span class="n">200</span><span class="sc">;</span></li></ol></pre><p>then <code class="inline"><span class="i">%hash</span></code>
will have at least 200 buckets allocated for it--256 of them,<br>
in fact, since it rounds up to the next power of two. These<br>
buckets will be retained even if you do <code class="inline"><span class="i">%hash</span> = <span class="s">(</span><span class="s">)</span></code>
, use <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a>
<span class="i">%hash</span></code>
if you want to free the storage while <code class="inline"><span class="i">%hash</span></code>
is still in scope.<br>
You can't shrink the number of buckets allocated for the hash using<br>
<code class="inline"><a class="l_k" href="../functions/keys.html">keys</a></code> in this way (but you needn't worry about doing this by accident,<br>
as trying has no effect).</p>
<p>See also <code class="inline"><a class="l_k" href="../functions/each.html">each</a></code>, <code class="inline"><a class="l_k" href="../functions/values.html">values</a></code> and <code class="inline"><a class="l_k" href="../functions/sort.html">sort</a></code>.]]></desc>
</keyword>
<keyword name="kill" type="function">
<params>
<param name='signal'/>
<param name='list'/>
</params>
<desc><![CDATA[Sends a signal to a list of processes. Returns the number of<br>
processes successfully signaled (which is not necessarily the<br>
same as the number actually killed).</p>
<pre class="verbatim"><ol><li> <span class="i">$cnt</span> = <a class="l_k" href="../functions/kill.html">kill</a> <span class="n">1</span><span class="cm">,</span> <span class="i">$child1</span><span class="cm">,</span> <span class="i">$child2</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/kill.html">kill</a> <span class="n">9</span><span class="cm">,</span> <span class="i">@goners</span><span class="sc">;</span></li></ol></pre><p>If SIGNAL is zero, no signal is sent to the process, but the kill(2)<br>
system call will check whether it's possible to send a signal to it (that<br>
means, to be brief, that the process is owned by the same user, or we are<br>
the super-user). This is a useful way to check that a child process is<br>
alive (even if only as a zombie) and hasn't changed its UID. See<br>
<a href="../perlport.html">perlport</a> for notes on the portability of this construct.</p>
<p>Unlike in the shell, if SIGNAL is negative, it kills<br>
process groups instead of processes. (On System V, a negative <i>PROCESS</i>
number will also kill process groups, but that's not portable.) That<br>
means you usually want to use positive not negative signals. You may also<br>
use a signal name in quotes.</p>
<p>See <a href="../perlipc.html#Signals">"Signals" in perlipc</a> for more details.]]></desc>
</keyword>
<keyword name="last" type="function">
<params>
<param name='label'/>
</params>
<desc><![CDATA[The <code class="inline"><a class="l_k" href="../functions/last.html">last</a></code> command is like the <code class="inline"><span class="w">break</span></code>
statement in C (as used in<br>
loops); it immediately exits the loop in question. If the LABEL is<br>
omitted, the command refers to the innermost enclosing loop. The<br>
<code class="inline"><a class="l_k" href="../functions/continue.html">continue</a></code> block, if any, is not executed:</p>
<pre class="verbatim"><ol><li> <span class="j">LINE:</span> while <span class="s">(</span><span class="q"><STDIN></span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/last.html">last</a> <span class="j">LINE</span> if <span class="q">/^$/</span><span class="sc">;</span> <span class="c"># exit when done with header</span></li><li> <span class="c">#...</span></li><li> <span class="s">}</span></li></ol></pre><p><code class="inline"><a class="l_k" href="../functions/last.html">last</a></code> cannot be used to exit a block which returns a value such as<br>
<code class="inline"><a class="l_k" href="../functions/eval.html">eval</a> <span class="s">{</span><span class="s">}</span></code>
, <code class="inline"><a class="l_k" href="../functions/sub.html">sub</a> <span class="s">{</span><span class="s">}</span></code>
or <code class="inline"><a class="l_k" href="../functions/do.html">do</a> <span class="s">{</span><span class="s">}</span></code>
, and should not be used to exit<br>
a grep() or map() operation.</p>
<p>Note that a block by itself is semantically identical to a loop<br>
that executes once. Thus <code class="inline"><a class="l_k" href="../functions/last.html">last</a></code> can be used to effect an early<br>
exit out of such a block.</p>
<p>See also <a href="../functions/continue.html">"continue"</a> for an illustration of how <code class="inline"><a class="l_k" href="../functions/last.html">last</a></code>, <code class="inline"><a class="l_k" href="../functions/next.html">next</a></code>, and<br>
<code class="inline"><a class="l_k" href="../functions/redo.html">redo</a></code> work.]]></desc>
</keyword>
<keyword name="last" type="function">
<params>
</params>
<desc><![CDATA[The <code class="inline"><a class="l_k" href="../functions/last.html">last</a></code> command is like the <code class="inline"><span class="w">break</span></code>
statement in C (as used in<br>
loops); it immediately exits the loop in question. If the LABEL is<br>
omitted, the command refers to the innermost enclosing loop. The<br>
<code class="inline"><a class="l_k" href="../functions/continue.html">continue</a></code> block, if any, is not executed:</p>
<pre class="verbatim"><ol><li> <span class="j">LINE:</span> while <span class="s">(</span><span class="q"><STDIN></span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/last.html">last</a> <span class="j">LINE</span> if <span class="q">/^$/</span><span class="sc">;</span> <span class="c"># exit when done with header</span></li><li> <span class="c">#...</span></li><li> <span class="s">}</span></li></ol></pre><p><code class="inline"><a class="l_k" href="../functions/last.html">last</a></code> cannot be used to exit a block which returns a value such as<br>
<code class="inline"><a class="l_k" href="../functions/eval.html">eval</a> <span class="s">{</span><span class="s">}</span></code>
, <code class="inline"><a class="l_k" href="../functions/sub.html">sub</a> <span class="s">{</span><span class="s">}</span></code>
or <code class="inline"><a class="l_k" href="../functions/do.html">do</a> <span class="s">{</span><span class="s">}</span></code>
, and should not be used to exit<br>
a grep() or map() operation.</p>
<p>Note that a block by itself is semantically identical to a loop<br>
that executes once. Thus <code class="inline"><a class="l_k" href="../functions/last.html">last</a></code> can be used to effect an early<br>
exit out of such a block.</p>
<p>See also <a href="../functions/continue.html">"continue"</a> for an illustration of how <code class="inline"><a class="l_k" href="../functions/last.html">last</a></code>, <code class="inline"><a class="l_k" href="../functions/next.html">next</a></code>, and<br>
<code class="inline"><a class="l_k" href="../functions/redo.html">redo</a></code> work.]]></desc>
</keyword>
<keyword name="lc" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Returns a lowercased version of EXPR. This is the internal function<br>
implementing the <code class="inline">\<span class="w">L</span></code>
escape in double-quoted strings. Respects<br>
current LC_CTYPE locale if <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">locale</span></code>
in force. See <a href="../perllocale.html">perllocale</a>
and <a href="../perlunicode.html">perlunicode</a> for more details about locale and Unicode support.</p>
<p>If EXPR is omitted, uses <code class="inline"><span class="i">$_</span></code>
.]]></desc>
</keyword>
<keyword name="lc" type="function">
<params>
</params>
<desc><![CDATA[Returns a lowercased version of EXPR. This is the internal function<br>
implementing the <code class="inline">\<span class="w">L</span></code>
escape in double-quoted strings. Respects<br>
current LC_CTYPE locale if <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">locale</span></code>
in force. See <a href="../perllocale.html">perllocale</a>
and <a href="../perlunicode.html">perlunicode</a> for more details about locale and Unicode support.</p>
<p>If EXPR is omitted, uses <code class="inline"><span class="i">$_</span></code>
.]]></desc>
</keyword>
<keyword name="lcfirst" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Returns the value of EXPR with the first character lowercased. This<br>
is the internal function implementing the <code class="inline">\<span class="w">l</span></code>
escape in<br>
double-quoted strings. Respects current LC_CTYPE locale if <code class="inline"><a class="l_k" href="../functions/use.html">use</a>
<span class="w">locale</span></code>
in force. See <a href="../perllocale.html">perllocale</a> and <a href="../perlunicode.html">perlunicode</a> for more<br>
details about locale and Unicode support.</p>
<p>If EXPR is omitted, uses <code class="inline"><span class="i">$_</span></code>
.]]></desc>
</keyword>
<keyword name="lcfirst" type="function">
<params>
</params>
<desc><![CDATA[Returns the value of EXPR with the first character lowercased. This<br>
is the internal function implementing the <code class="inline">\<span class="w">l</span></code>
escape in<br>
double-quoted strings. Respects current LC_CTYPE locale if <code class="inline"><a class="l_k" href="../functions/use.html">use</a>
<span class="w">locale</span></code>
in force. See <a href="../perllocale.html">perllocale</a> and <a href="../perlunicode.html">perlunicode</a> for more<br>
details about locale and Unicode support.</p>
<p>If EXPR is omitted, uses <code class="inline"><span class="i">$_</span></code>
.]]></desc>
</keyword>
<keyword name="length" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Returns the length in <i>characters</i> of the value of EXPR. If EXPR is<br>
omitted, returns length of <code class="inline"><span class="i">$_</span></code>
. Note that this cannot be used on<br>
an entire array or hash to find out how many elements these have.<br>
For that, use <code class="inline"><a class="l_k" href="../functions/scalar.html">scalar</a> <span class="i">@array</span></code>
and <code class="inline"><a class="l_k" href="../functions/scalar.html">scalar</a> <a class="l_k" href="../functions/keys.html">keys</a> <span class="i">%hash</span></code>
respectively.</p>
<p>Note the <i>characters</i>: if the EXPR is in Unicode, you will get the<br>
number of characters, not the number of bytes. To get the length<br>
of the internal string in bytes, use <code class="inline"><span class="i">bytes::length</span><span class="s">(</span><span class="w">EXPR</span><span class="s">)</span></code>
, see<br>
<a href="../bytes.html">bytes</a>. Note that the internal encoding is variable, and the number<br>
of bytes usually meaningless. To get the number of bytes that the<br>
string would have when encoded as UTF-8, use<br>
<code class="inline"><a class="l_k" href="../functions/length.html">length(Encoding::encode_utf8(EXPR))</a></code>.]]></desc>
</keyword>
<keyword name="length" type="function">
<params>
</params>
<desc><![CDATA[Returns the length in <i>characters</i> of the value of EXPR. If EXPR is<br>
omitted, returns length of <code class="inline"><span class="i">$_</span></code>
. Note that this cannot be used on<br>
an entire array or hash to find out how many elements these have.<br>
For that, use <code class="inline"><a class="l_k" href="../functions/scalar.html">scalar</a> <span class="i">@array</span></code>
and <code class="inline"><a class="l_k" href="../functions/scalar.html">scalar</a> <a class="l_k" href="../functions/keys.html">keys</a> <span class="i">%hash</span></code>
respectively.</p>
<p>Note the <i>characters</i>: if the EXPR is in Unicode, you will get the<br>
number of characters, not the number of bytes. To get the length<br>
of the internal string in bytes, use <code class="inline"><span class="i">bytes::length</span><span class="s">(</span><span class="w">EXPR</span><span class="s">)</span></code>
, see<br>
<a href="../bytes.html">bytes</a>. Note that the internal encoding is variable, and the number<br>
of bytes usually meaningless. To get the number of bytes that the<br>
string would have when encoded as UTF-8, use<br>
<code class="inline"><a class="l_k" href="../functions/length.html">length(Encoding::encode_utf8(EXPR))</a></code>.]]></desc>
</keyword>
<keyword name="link" type="function">
<params>
<param name='oldfile'/>
<param name='newfile'/>
</params>
<desc><![CDATA[Creates a new filename linked to the old filename. Returns true for<br>
success, false otherwise.]]></desc>
</keyword>
<keyword name="listen" type="function">
<params>
<param name='socket'/>
<param name='queuesize'/>
</params>
<desc><![CDATA[Does the same thing that the listen system call does. Returns true if<br>
it succeeded, false otherwise. See the example in<br>
<a href="../perlipc.html#Sockets%3a-Client%2fServer-Communication">"Sockets: Client/Server Communication" in perlipc</a>.]]></desc>
</keyword>
<keyword name="local" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[You really probably want to be using <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code> instead, because <code class="inline"><a class="l_k" href="../functions/local.html">local</a></code> isn't<br>
what most people think of as "local". See<br>
<a href="../perlsub.html#Private-Variables-via-my()">"Private Variables via my()" in perlsub</a> for details.</p>
<p>A local modifies the listed variables to be local to the enclosing<br>
block, file, or eval. If more than one value is listed, the list must<br>
be placed in parentheses. See <a href="../perlsub.html#Temporary-Values-via-local()">"Temporary Values via local()" in perlsub</a>
for details, including issues with tied arrays and hashes.]]></desc>
</keyword>
<keyword name="localtime" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Converts a time as returned by the time function to a 9-element list<br>
with the time analyzed for the local time zone. Typically used as<br>
follows:</p>
<pre class="verbatim"><ol><li> <span class="c"># 0 1 2 3 4 5 6 7 8</span></li><li> <span class="s">(</span><span class="i">$sec</span><span class="cm">,</span><span class="i">$min</span><span class="cm">,</span><span class="i">$hour</span><span class="cm">,</span><span class="i">$mday</span><span class="cm">,</span><span class="i">$mon</span><span class="cm">,</span><span class="i">$year</span><span class="cm">,</span><span class="i">$wday</span><span class="cm">,</span><span class="i">$yday</span><span class="cm">,</span><span class="i">$isdst</span><span class="s">)</span> =</li><li> <a class="l_k" href="../functions/localtime.html">localtime</a><span class="s">(</span><a class="l_k" href="../functions/time.html">time</a><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>All list elements are numeric, and come straight out of the C `struct<br>
tm'. <code class="inline"><span class="i">$sec</span></code>
, <code class="inline"><span class="i">$min</span></code>
, and <code class="inline"><span class="i">$hour</span></code>
are the seconds, minutes, and hours<br>
of the specified time.</p>
<p><code class="inline"><span class="i">$mday</span></code>
is the day of the month, and <code class="inline"><span class="i">$mon</span></code>
is the month itself, in<br>
the range <code class="inline"><span class="n">0</span>..<span class="n">11</span></code>
with 0 indicating January and 11 indicating December.<br>
This makes it easy to get a month name from a list:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">@abbr</span> = <span class="q">qw( Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec )</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"$abbr[$mon] $mday"</span><span class="sc">;</span></li><li> <span class="c"># $mon=9, $mday=18 gives "Oct 18"</span></li></ol></pre><p><code class="inline"><span class="i">$year</span></code>
is the number of years since 1900, not just the last two digits<br>
of the year. That is, <code class="inline"><span class="i">$year</span></code>
is <code class="inline"><span class="n">123</span></code>
in year 2023. The proper way<br>
to get a complete 4-digit year is simply:</p>
<pre class="verbatim"><ol><li> <span class="i">$year</span> += <span class="n">1900</span><span class="sc">;</span></li></ol></pre><p>Otherwise you create non-Y2K-compliant programs--and you wouldn't want<br>
to do that, would you?</p>
<p>To get the last two digits of the year (e.g., '01' in 2001) do:</p>
<pre class="verbatim"><ol><li> <span class="i">$year</span> = <a class="l_k" href="../functions/sprintf.html">sprintf</a><span class="s">(</span><span class="q">"%02d"</span><span class="cm">,</span> <span class="i">$year</span> % <span class="n">100</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p><code class="inline"><span class="i">$wday</span></code>
is the day of the week, with 0 indicating Sunday and 3 indicating<br>
Wednesday. <code class="inline"><span class="i">$yday</span></code>
is the day of the year, in the range <code class="inline"><span class="n">0</span>..<span class="n">364</span></code>
<br>
(or <code class="inline"><span class="n">0</span>..<span class="n">365</span></code>
in leap years.)</p>
<p><code class="inline"><span class="i">$isdst</span></code>
is true if the specified time occurs during Daylight Saving<br>
Time, false otherwise.</p>
<p>If EXPR is omitted, <code class="inline"><a class="l_k" href="../functions/localtime.html">localtime()</a></code> uses the current time (as returned<br>
by time(3)).</p>
<p>In scalar context, <code class="inline"><a class="l_k" href="../functions/localtime.html">localtime()</a></code> returns the ctime(3) value:</p>
<pre class="verbatim"><ol><li> <span class="i">$now_string</span> = <a class="l_k" href="../functions/localtime.html">localtime</a><span class="sc">;</span> <span class="c"># e.g., "Thu Oct 13 04:54:34 1994"</span></li></ol></pre><p>This scalar value is <b>not</b> locale dependent but is a Perl builtin. For GMT<br>
instead of local time use the <a href="../functions/gmtime.html">"gmtime"</a> builtin. See also the<br>
<code class="inline"><span class="w">Time::Local</span></code>
module (to convert the second, minutes, hours, ... back to<br>
the integer value returned by time()), and the <a href="../POSIX.html">POSIX</a> module's strftime(3)<br>
and mktime(3) functions.</p>
<p>To get somewhat similar but locale dependent date strings, set up your<br>
locale environment variables appropriately (please see <a href="../perllocale.html">perllocale</a>) and<br>
try for example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">POSIX</span> <span class="q">qw(strftime)</span><span class="sc">;</span></li><li> <span class="i">$now_string</span> = <span class="w">strftime</span> <span class="q">"%a %b %e %H:%M:%S %Y"</span><span class="cm">,</span> <a class="l_k" href="../functions/localtime.html">localtime</a><span class="sc">;</span></li><li> <span class="c"># or for GMT formatted appropriately for your locale:</span></li><li> <span class="i">$now_string</span> = <span class="w">strftime</span> <span class="q">"%a %b %e %H:%M:%S %Y"</span><span class="cm">,</span> <a class="l_k" href="../functions/gmtime.html">gmtime</a><span class="sc">;</span></li></ol></pre><p>Note that the <code class="inline"><span class="i">%a</span></code>
and <code class="inline"><span class="i">%b</span></code>
, the short forms of the day of the week<br>
and the month of the year, may not necessarily be three characters wide.</p>
<p>See <a href="../perlport.html#localtime">"localtime" in perlport</a> for portability concerns.</p>
<p>The <a href="../Time/gmtime.html">Time::gmtime</a> and <a href="../Time/localtime.html">Time::localtime</a> modules provides a convenient,<br>
by-name access mechanism to the gmtime() and localtime() functions,<br>
respectively.</p>
<p>For a comprehensive date and time representation look at the<br>
<a href="http://search.cpan.org/perldoc/DateTime">DateTime</a> module on CPAN.]]></desc>
</keyword>
<keyword name="localtime" type="function">
<params>
</params>
<desc><![CDATA[Converts a time as returned by the time function to a 9-element list<br>
with the time analyzed for the local time zone. Typically used as<br>
follows:</p>
<pre class="verbatim"><ol><li> <span class="c"># 0 1 2 3 4 5 6 7 8</span></li><li> <span class="s">(</span><span class="i">$sec</span><span class="cm">,</span><span class="i">$min</span><span class="cm">,</span><span class="i">$hour</span><span class="cm">,</span><span class="i">$mday</span><span class="cm">,</span><span class="i">$mon</span><span class="cm">,</span><span class="i">$year</span><span class="cm">,</span><span class="i">$wday</span><span class="cm">,</span><span class="i">$yday</span><span class="cm">,</span><span class="i">$isdst</span><span class="s">)</span> =</li><li> <a class="l_k" href="../functions/localtime.html">localtime</a><span class="s">(</span><a class="l_k" href="../functions/time.html">time</a><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>All list elements are numeric, and come straight out of the C `struct<br>
tm'. <code class="inline"><span class="i">$sec</span></code>
, <code class="inline"><span class="i">$min</span></code>
, and <code class="inline"><span class="i">$hour</span></code>
are the seconds, minutes, and hours<br>
of the specified time.</p>
<p><code class="inline"><span class="i">$mday</span></code>
is the day of the month, and <code class="inline"><span class="i">$mon</span></code>
is the month itself, in<br>
the range <code class="inline"><span class="n">0</span>..<span class="n">11</span></code>
with 0 indicating January and 11 indicating December.<br>
This makes it easy to get a month name from a list:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">@abbr</span> = <span class="q">qw( Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec )</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"$abbr[$mon] $mday"</span><span class="sc">;</span></li><li> <span class="c"># $mon=9, $mday=18 gives "Oct 18"</span></li></ol></pre><p><code class="inline"><span class="i">$year</span></code>
is the number of years since 1900, not just the last two digits<br>
of the year. That is, <code class="inline"><span class="i">$year</span></code>
is <code class="inline"><span class="n">123</span></code>
in year 2023. The proper way<br>
to get a complete 4-digit year is simply:</p>
<pre class="verbatim"><ol><li> <span class="i">$year</span> += <span class="n">1900</span><span class="sc">;</span></li></ol></pre><p>Otherwise you create non-Y2K-compliant programs--and you wouldn't want<br>
to do that, would you?</p>
<p>To get the last two digits of the year (e.g., '01' in 2001) do:</p>
<pre class="verbatim"><ol><li> <span class="i">$year</span> = <a class="l_k" href="../functions/sprintf.html">sprintf</a><span class="s">(</span><span class="q">"%02d"</span><span class="cm">,</span> <span class="i">$year</span> % <span class="n">100</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p><code class="inline"><span class="i">$wday</span></code>
is the day of the week, with 0 indicating Sunday and 3 indicating<br>
Wednesday. <code class="inline"><span class="i">$yday</span></code>
is the day of the year, in the range <code class="inline"><span class="n">0</span>..<span class="n">364</span></code>
<br>
(or <code class="inline"><span class="n">0</span>..<span class="n">365</span></code>
in leap years.)</p>
<p><code class="inline"><span class="i">$isdst</span></code>
is true if the specified time occurs during Daylight Saving<br>
Time, false otherwise.</p>
<p>If EXPR is omitted, <code class="inline"><a class="l_k" href="../functions/localtime.html">localtime()</a></code> uses the current time (as returned<br>
by time(3)).</p>
<p>In scalar context, <code class="inline"><a class="l_k" href="../functions/localtime.html">localtime()</a></code> returns the ctime(3) value:</p>
<pre class="verbatim"><ol><li> <span class="i">$now_string</span> = <a class="l_k" href="../functions/localtime.html">localtime</a><span class="sc">;</span> <span class="c"># e.g., "Thu Oct 13 04:54:34 1994"</span></li></ol></pre><p>This scalar value is <b>not</b> locale dependent but is a Perl builtin. For GMT<br>
instead of local time use the <a href="../functions/gmtime.html">"gmtime"</a> builtin. See also the<br>
<code class="inline"><span class="w">Time::Local</span></code>
module (to convert the second, minutes, hours, ... back to<br>
the integer value returned by time()), and the <a href="../POSIX.html">POSIX</a> module's strftime(3)<br>
and mktime(3) functions.</p>
<p>To get somewhat similar but locale dependent date strings, set up your<br>
locale environment variables appropriately (please see <a href="../perllocale.html">perllocale</a>) and<br>
try for example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">POSIX</span> <span class="q">qw(strftime)</span><span class="sc">;</span></li><li> <span class="i">$now_string</span> = <span class="w">strftime</span> <span class="q">"%a %b %e %H:%M:%S %Y"</span><span class="cm">,</span> <a class="l_k" href="../functions/localtime.html">localtime</a><span class="sc">;</span></li><li> <span class="c"># or for GMT formatted appropriately for your locale:</span></li><li> <span class="i">$now_string</span> = <span class="w">strftime</span> <span class="q">"%a %b %e %H:%M:%S %Y"</span><span class="cm">,</span> <a class="l_k" href="../functions/gmtime.html">gmtime</a><span class="sc">;</span></li></ol></pre><p>Note that the <code class="inline"><span class="i">%a</span></code>
and <code class="inline"><span class="i">%b</span></code>
, the short forms of the day of the week<br>
and the month of the year, may not necessarily be three characters wide.</p>
<p>See <a href="../perlport.html#localtime">"localtime" in perlport</a> for portability concerns.</p>
<p>The <a href="../Time/gmtime.html">Time::gmtime</a> and <a href="../Time/localtime.html">Time::localtime</a> modules provides a convenient,<br>
by-name access mechanism to the gmtime() and localtime() functions,<br>
respectively.</p>
<p>For a comprehensive date and time representation look at the<br>
<a href="http://search.cpan.org/perldoc/DateTime">DateTime</a> module on CPAN.]]></desc>
</keyword>
<keyword name="lock" type="function">
<params>
<param name='thing'/>
</params>
<desc><![CDATA[This function places an advisory lock on a shared variable, or referenced<br>
object contained in <i>THING</i> until the lock goes out of scope.</p>
<p>lock() is a "weak keyword" : this means that if you've defined a function<br>
by this name (before any calls to it), that function will be called<br>
instead. (However, if you've said <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">threads</span></code>
, lock() is always a<br>
keyword.) See <a href="../threads.html">threads</a>.]]></desc>
</keyword>
<keyword name="log" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Returns the natural logarithm (base <i>e</i>) of EXPR. If EXPR is omitted,<br>
returns log of <code class="inline"><span class="i">$_</span></code>
. To get the log of another base, use basic algebra:<br>
The base-N log of a number is equal to the natural log of that number<br>
divided by the natural log of N. For example:</p>
<pre class="verbatim"><ol><li><a name="log10"></a> sub <span class="m">log10</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$n</span> = <a class="l_k" href="../functions/shift.html">shift</a><span class="sc">;</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <a class="l_k" href="../functions/log.html">log</a><span class="s">(</span><span class="i">$n</span><span class="s">)</span>/<a class="l_k" href="../functions/log.html">log</a><span class="s">(</span><span class="n">10</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>See also <a href="../functions/exp.html">"exp"</a> for the inverse operation.]]></desc>
</keyword>
<keyword name="log" type="function">
<params>
</params>
<desc><![CDATA[Returns the natural logarithm (base <i>e</i>) of EXPR. If EXPR is omitted,<br>
returns log of <code class="inline"><span class="i">$_</span></code>
. To get the log of another base, use basic algebra:<br>
The base-N log of a number is equal to the natural log of that number<br>
divided by the natural log of N. For example:</p>
<pre class="verbatim"><ol><li><a name="log10"></a> sub <span class="m">log10</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$n</span> = <a class="l_k" href="../functions/shift.html">shift</a><span class="sc">;</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <a class="l_k" href="../functions/log.html">log</a><span class="s">(</span><span class="i">$n</span><span class="s">)</span>/<a class="l_k" href="../functions/log.html">log</a><span class="s">(</span><span class="n">10</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>See also <a href="../functions/exp.html">"exp"</a> for the inverse operation.]]></desc>
</keyword>
<keyword name="lstat" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Does the same thing as the <code class="inline"><a class="l_k" href="../functions/stat.html">stat</a></code> function (including setting the<br>
special <code class="inline"><span class="w">_</span></code>
filehandle) but stats a symbolic link instead of the file<br>
the symbolic link points to. If symbolic links are unimplemented on<br>
your system, a normal <code class="inline"><a class="l_k" href="../functions/stat.html">stat</a></code> is done. For much more detailed<br>
information, please see the documentation for <code class="inline"><a class="l_k" href="../functions/stat.html">stat</a></code>.</p>
<p>If EXPR is omitted, stats <code class="inline"><span class="i">$_</span></code>
.]]></desc>
</keyword>
<keyword name="lstat" type="function">
<params>
</params>
<desc><![CDATA[Does the same thing as the <code class="inline"><a class="l_k" href="../functions/stat.html">stat</a></code> function (including setting the<br>
special <code class="inline"><span class="w">_</span></code>
filehandle) but stats a symbolic link instead of the file<br>
the symbolic link points to. If symbolic links are unimplemented on<br>
your system, a normal <code class="inline"><a class="l_k" href="../functions/stat.html">stat</a></code> is done. For much more detailed<br>
information, please see the documentation for <code class="inline"><a class="l_k" href="../functions/stat.html">stat</a></code>.</p>
<p>If EXPR is omitted, stats <code class="inline"><span class="i">$_</span></code>
.]]></desc>
</keyword>
<keyword name="m" type="function">
<params>
<param name='//'/>
</params>
<desc><![CDATA[The match operator. See <a href="../perlop.html#Regexp-Quote-Like-Operators">"Regexp Quote-Like Operators" in perlop</a>.]]></desc>
</keyword>
<keyword name="map" type="function">
<params>
<param name='block list'/>
</params>
<desc><![CDATA[Evaluates the BLOCK or EXPR for each element of LIST (locally setting<br>
<code class="inline"><span class="i">$_</span></code>
to each element) and returns the list value composed of the<br>
results of each such evaluation. In scalar context, returns the<br>
total number of elements so generated. Evaluates BLOCK or EXPR in<br>
list context, so each element of LIST may produce zero, one, or<br>
more elements in the returned value.</p>
<pre class="verbatim"><ol><li> <span class="i">@chars</span> = <a class="l_k" href="../functions/map.html">map</a><span class="s">(</span><a class="l_k" href="../functions/chr.html">chr</a><span class="cm">,</span> <span class="i">@nums</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>translates a list of numbers to the corresponding characters. And</p>
<pre class="verbatim"><ol><li> <span class="i">%hash</span> = <a class="l_k" href="../functions/map.html">map</a> <span class="s">{</span> <span class="i">get_a_key_for</span><span class="s">(</span><span class="i">$_</span><span class="s">)</span> <span class="cm">=></span> <span class="i">$_</span> <span class="s">}</span> <span class="i">@array</span><span class="sc">;</span></li></ol></pre><p>is just a funny way to write</p>
<pre class="verbatim"><ol><li> <span class="i">%hash</span> = <span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> foreach <span class="s">(</span><span class="i">@array</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$hash</span>{<span class="i">get_a_key_for</span><span class="s">(</span><span class="i">$_</span><span class="s">)</span>} = <span class="i">$_</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Note that <code class="inline"><span class="i">$_</span></code>
is an alias to the list value, so it can be used to<br>
modify the elements of the LIST. While this is useful and supported,<br>
it can cause bizarre results if the elements of LIST are not variables.<br>
Using a regular <code class="inline">foreach</code>
loop for this purpose would be clearer in<br>
most cases. See also <a href="../functions/grep.html">"grep"</a> for an array composed of those items of<br>
the original list for which the BLOCK or EXPR evaluates to true.</p>
<p>If <code class="inline"><span class="i">$_</span></code>
is lexical in the scope where the <code class="inline"><a class="l_k" href="../functions/map.html">map</a></code> appears (because it has<br>
been declared with <code class="inline"><a class="l_k" href="../functions/my.html">my</a> <span class="i">$_</span></code>
), then, in addition to being locally aliased to<br>
the list elements, <code class="inline"><span class="i">$_</span></code>
keeps being lexical inside the block; that is, it<br>
can't be seen from the outside, avoiding any potential side-effects.</p>
<p><code class="inline">{</code> starts both hash references and blocks, so <code class="inline">map { ...</code> could be either<br>
the start of map BLOCK LIST or map EXPR, LIST. Because perl doesn't look<br>
ahead for the closing <code class="inline">}</code> it has to take a guess at which its dealing with<br>
based what it finds just after the <code class="inline">{</code>. Usually it gets it right, but if it<br>
doesn't it won't realize something is wrong until it gets to the <code class="inline">}</code> and<br>
encounters the missing (or unexpected) comma. The syntax error will be<br>
reported close to the <code class="inline">}</code> but you'll need to change something near the <code class="inline">{</code>
such as using a unary <code class="inline">+</code>
to give perl some help:</p>
<pre class="verbatim"><ol><li> <span class="i">%hash</span> = <a class="l_k" href="../functions/map.html">map</a> <span class="s">{</span> <span class="q">"\L$_"</span><span class="cm">,</span> <span class="n">1</span> <span class="s">}</span> <span class="i">@array</span> <span class="c"># perl guesses EXPR. wrong</span></li><li> %<span class="w">hash</span> = <a class="l_k" href="../functions/map.html">map</a> <span class="s">{</span> +<span class="q">"\L$_"</span><span class="cm">,</span> <span class="n">1</span> <span class="s">}</span> <span class="i">@array</span> <span class="c"># perl guesses BLOCK. right</span></li><li> %<span class="w">hash</span> = <a class="l_k" href="../functions/map.html">map</a> <span class="s">{</span> <span class="s">(</span><span class="q">"\L$_"</span><span class="cm">,</span> <span class="n">1</span><span class="s">)</span> <span class="s">}</span> <span class="i">@array</span> <span class="c"># this also works</span></li><li> %<span class="w">hash</span> = <a class="l_k" href="../functions/map.html">map</a> <span class="s">{</span> <a class="l_k" href="../functions/lc.html">lc</a><span class="s">(</span><span class="i">$_</span><span class="s">)</span><span class="cm">,</span> <span class="n">1</span> <span class="s">}</span> <span class="i">@array</span> <span class="c"># as does this.</span></li><li> %<span class="w">hash</span> = <a class="l_k" href="../functions/map.html">map</a> +<span class="s">(</span> <a class="l_k" href="../functions/lc.html">lc</a><span class="s">(</span><span class="i">$_</span><span class="s">)</span><span class="cm">,</span> <span class="n">1</span> <span class="s">)</span><span class="cm">,</span> <span class="i">@array</span> <span class="c"># this is EXPR and works!</span></li><li></li><li> %<span class="w">hash</span> = <a class="l_k" href="../functions/map.html">map</a> <span class="s">(</span> <a class="l_k" href="../functions/lc.html">lc</a><span class="s">(</span><span class="i">$_</span><span class="s">)</span><span class="cm">,</span> <span class="n">1</span> <span class="s">)</span><span class="cm">,</span> <span class="i">@array</span> <span class="c"># evaluates to (1, @array)</span></li></ol></pre><p>or to force an anon hash constructor use <code class="inline">+{</code>:</p>
<pre class="verbatim"><ol><li> <span class="i">@hashes</span> = <a class="l_k" href="../functions/map.html">map</a> +<span class="s">{</span> <a class="l_k" href="../functions/lc.html">lc</a><span class="s">(</span><span class="i">$_</span><span class="s">)</span><span class="cm">,</span> <span class="n">1</span> <span class="s">}</span><span class="cm">,</span> <span class="i">@array</span> <span class="c"># EXPR, so needs , at end</span></li></ol></pre><p>and you get list of anonymous hashes each with only 1 entry.]]></desc>
</keyword>
<keyword name="map" type="function">
<params>
<param name='expr'/>
<param name='list'/>
</params>
<desc><![CDATA[Evaluates the BLOCK or EXPR for each element of LIST (locally setting<br>
<code class="inline"><span class="i">$_</span></code>
to each element) and returns the list value composed of the<br>
results of each such evaluation. In scalar context, returns the<br>
total number of elements so generated. Evaluates BLOCK or EXPR in<br>
list context, so each element of LIST may produce zero, one, or<br>
more elements in the returned value.</p>
<pre class="verbatim"><ol><li> <span class="i">@chars</span> = <a class="l_k" href="../functions/map.html">map</a><span class="s">(</span><a class="l_k" href="../functions/chr.html">chr</a><span class="cm">,</span> <span class="i">@nums</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>translates a list of numbers to the corresponding characters. And</p>
<pre class="verbatim"><ol><li> <span class="i">%hash</span> = <a class="l_k" href="../functions/map.html">map</a> <span class="s">{</span> <span class="i">get_a_key_for</span><span class="s">(</span><span class="i">$_</span><span class="s">)</span> <span class="cm">=></span> <span class="i">$_</span> <span class="s">}</span> <span class="i">@array</span><span class="sc">;</span></li></ol></pre><p>is just a funny way to write</p>
<pre class="verbatim"><ol><li> <span class="i">%hash</span> = <span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> foreach <span class="s">(</span><span class="i">@array</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$hash</span>{<span class="i">get_a_key_for</span><span class="s">(</span><span class="i">$_</span><span class="s">)</span>} = <span class="i">$_</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Note that <code class="inline"><span class="i">$_</span></code>
is an alias to the list value, so it can be used to<br>
modify the elements of the LIST. While this is useful and supported,<br>
it can cause bizarre results if the elements of LIST are not variables.<br>
Using a regular <code class="inline">foreach</code>
loop for this purpose would be clearer in<br>
most cases. See also <a href="../functions/grep.html">"grep"</a> for an array composed of those items of<br>
the original list for which the BLOCK or EXPR evaluates to true.</p>
<p>If <code class="inline"><span class="i">$_</span></code>
is lexical in the scope where the <code class="inline"><a class="l_k" href="../functions/map.html">map</a></code> appears (because it has<br>
been declared with <code class="inline"><a class="l_k" href="../functions/my.html">my</a> <span class="i">$_</span></code>
), then, in addition to being locally aliased to<br>
the list elements, <code class="inline"><span class="i">$_</span></code>
keeps being lexical inside the block; that is, it<br>
can't be seen from the outside, avoiding any potential side-effects.</p>
<p><code class="inline">{</code> starts both hash references and blocks, so <code class="inline">map { ...</code> could be either<br>
the start of map BLOCK LIST or map EXPR, LIST. Because perl doesn't look<br>
ahead for the closing <code class="inline">}</code> it has to take a guess at which its dealing with<br>
based what it finds just after the <code class="inline">{</code>. Usually it gets it right, but if it<br>
doesn't it won't realize something is wrong until it gets to the <code class="inline">}</code> and<br>
encounters the missing (or unexpected) comma. The syntax error will be<br>
reported close to the <code class="inline">}</code> but you'll need to change something near the <code class="inline">{</code>
such as using a unary <code class="inline">+</code>
to give perl some help:</p>
<pre class="verbatim"><ol><li> <span class="i">%hash</span> = <a class="l_k" href="../functions/map.html">map</a> <span class="s">{</span> <span class="q">"\L$_"</span><span class="cm">,</span> <span class="n">1</span> <span class="s">}</span> <span class="i">@array</span> <span class="c"># perl guesses EXPR. wrong</span></li><li> %<span class="w">hash</span> = <a class="l_k" href="../functions/map.html">map</a> <span class="s">{</span> +<span class="q">"\L$_"</span><span class="cm">,</span> <span class="n">1</span> <span class="s">}</span> <span class="i">@array</span> <span class="c"># perl guesses BLOCK. right</span></li><li> %<span class="w">hash</span> = <a class="l_k" href="../functions/map.html">map</a> <span class="s">{</span> <span class="s">(</span><span class="q">"\L$_"</span><span class="cm">,</span> <span class="n">1</span><span class="s">)</span> <span class="s">}</span> <span class="i">@array</span> <span class="c"># this also works</span></li><li> %<span class="w">hash</span> = <a class="l_k" href="../functions/map.html">map</a> <span class="s">{</span> <a class="l_k" href="../functions/lc.html">lc</a><span class="s">(</span><span class="i">$_</span><span class="s">)</span><span class="cm">,</span> <span class="n">1</span> <span class="s">}</span> <span class="i">@array</span> <span class="c"># as does this.</span></li><li> %<span class="w">hash</span> = <a class="l_k" href="../functions/map.html">map</a> +<span class="s">(</span> <a class="l_k" href="../functions/lc.html">lc</a><span class="s">(</span><span class="i">$_</span><span class="s">)</span><span class="cm">,</span> <span class="n">1</span> <span class="s">)</span><span class="cm">,</span> <span class="i">@array</span> <span class="c"># this is EXPR and works!</span></li><li></li><li> %<span class="w">hash</span> = <a class="l_k" href="../functions/map.html">map</a> <span class="s">(</span> <a class="l_k" href="../functions/lc.html">lc</a><span class="s">(</span><span class="i">$_</span><span class="s">)</span><span class="cm">,</span> <span class="n">1</span> <span class="s">)</span><span class="cm">,</span> <span class="i">@array</span> <span class="c"># evaluates to (1, @array)</span></li></ol></pre><p>or to force an anon hash constructor use <code class="inline">+{</code>:</p>
<pre class="verbatim"><ol><li> <span class="i">@hashes</span> = <a class="l_k" href="../functions/map.html">map</a> +<span class="s">{</span> <a class="l_k" href="../functions/lc.html">lc</a><span class="s">(</span><span class="i">$_</span><span class="s">)</span><span class="cm">,</span> <span class="n">1</span> <span class="s">}</span><span class="cm">,</span> <span class="i">@array</span> <span class="c"># EXPR, so needs , at end</span></li></ol></pre><p>and you get list of anonymous hashes each with only 1 entry.]]></desc>
</keyword>
<keyword name="mkdir" type="function">
<params>
<param name='filename'/>
<param name='mask'/>
</params>
<desc><![CDATA[Creates the directory specified by FILENAME, with permissions<br>
specified by MASK (as modified by <code class="inline"><a class="l_k" href="../functions/umask.html">umask</a></code>). If it succeeds it<br>
returns true, otherwise it returns false and sets <code class="inline"><span class="i">$!</span></code>
(errno).<br>
If omitted, MASK defaults to 0777. If omitted, FILENAME defaults<br>
to <code class="inline"><span class="i">$_</span></code>
.</p>
<p>In general, it is better to create directories with permissive MASK,<br>
and let the user modify that with their <code class="inline"><a class="l_k" href="../functions/umask.html">umask</a></code>, than it is to supply<br>
a restrictive MASK and give the user no way to be more permissive.<br>
The exceptions to this rule are when the file or directory should be<br>
kept private (mail files, for instance). The perlfunc(1) entry on<br>
<code class="inline"><a class="l_k" href="../functions/umask.html">umask</a></code> discusses the choice of MASK in more detail.</p>
<p>Note that according to the POSIX 1003.1-1996 the FILENAME may have any<br>
number of trailing slashes. Some operating and filesystems do not get<br>
this right, so Perl automatically removes all trailing slashes to keep<br>
everyone happy.</p>
<p>In order to recursively create a directory structure look at<br>
the <code class="inline"><span class="w">mkpath</span></code>
function of the <a href="../File/Path.html">File::Path</a> module.]]></desc>
</keyword>
<keyword name="mkdir" type="function">
<params>
<param name='filename'/>
</params>
<desc><![CDATA[Creates the directory specified by FILENAME, with permissions<br>
specified by MASK (as modified by <code class="inline"><a class="l_k" href="../functions/umask.html">umask</a></code>). If it succeeds it<br>
returns true, otherwise it returns false and sets <code class="inline"><span class="i">$!</span></code>
(errno).<br>
If omitted, MASK defaults to 0777. If omitted, FILENAME defaults<br>
to <code class="inline"><span class="i">$_</span></code>
.</p>
<p>In general, it is better to create directories with permissive MASK,<br>
and let the user modify that with their <code class="inline"><a class="l_k" href="../functions/umask.html">umask</a></code>, than it is to supply<br>
a restrictive MASK and give the user no way to be more permissive.<br>
The exceptions to this rule are when the file or directory should be<br>
kept private (mail files, for instance). The perlfunc(1) entry on<br>
<code class="inline"><a class="l_k" href="../functions/umask.html">umask</a></code> discusses the choice of MASK in more detail.</p>
<p>Note that according to the POSIX 1003.1-1996 the FILENAME may have any<br>
number of trailing slashes. Some operating and filesystems do not get<br>
this right, so Perl automatically removes all trailing slashes to keep<br>
everyone happy.</p>
<p>In order to recursively create a directory structure look at<br>
the <code class="inline"><span class="w">mkpath</span></code>
function of the <a href="../File/Path.html">File::Path</a> module.]]></desc>
</keyword>
<keyword name="mkdir" type="function">
<params>
</params>
<desc><![CDATA[Creates the directory specified by FILENAME, with permissions<br>
specified by MASK (as modified by <code class="inline"><a class="l_k" href="../functions/umask.html">umask</a></code>). If it succeeds it<br>
returns true, otherwise it returns false and sets <code class="inline"><span class="i">$!</span></code>
(errno).<br>
If omitted, MASK defaults to 0777. If omitted, FILENAME defaults<br>
to <code class="inline"><span class="i">$_</span></code>
.</p>
<p>In general, it is better to create directories with permissive MASK,<br>
and let the user modify that with their <code class="inline"><a class="l_k" href="../functions/umask.html">umask</a></code>, than it is to supply<br>
a restrictive MASK and give the user no way to be more permissive.<br>
The exceptions to this rule are when the file or directory should be<br>
kept private (mail files, for instance). The perlfunc(1) entry on<br>
<code class="inline"><a class="l_k" href="../functions/umask.html">umask</a></code> discusses the choice of MASK in more detail.</p>
<p>Note that according to the POSIX 1003.1-1996 the FILENAME may have any<br>
number of trailing slashes. Some operating and filesystems do not get<br>
this right, so Perl automatically removes all trailing slashes to keep<br>
everyone happy.</p>
<p>In order to recursively create a directory structure look at<br>
the <code class="inline"><span class="w">mkpath</span></code>
function of the <a href="../File/Path.html">File::Path</a> module.]]></desc>
</keyword>
<keyword name="msgctl" type="function">
<params>
<param name='id'/>
<param name='cmd'/>
<param name='arg'/>
</params>
<desc><![CDATA[Calls the System V IPC function msgctl(2). You'll probably have to say</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">IPC::SysV</span><span class="sc">;</span></li></ol></pre><p>first to get the correct constant definitions. If CMD is <code class="inline"><span class="w">IPC_STAT</span></code>
,<br>
then ARG must be a variable that will hold the returned <code class="inline"><span class="w">msqid_ds</span></code>
<br>
structure. Returns like <code class="inline"><a class="l_k" href="../functions/ioctl.html">ioctl</a></code>: the undefined value for error,<br>
<code class="inline"><span class="q">"0 but true"</span></code>
for zero, or the actual return value otherwise. See also<br>
<a href="../perlipc.html#SysV-IPC">"SysV IPC" in perlipc</a>, <code class="inline"><span class="w">IPC::SysV</span></code>
, and <code class="inline"><span class="w">IPC::Semaphore</span></code>
documentation.]]></desc>
</keyword>
<keyword name="msgget" type="function">
<params>
<param name='key'/>
<param name='flags'/>
</params>
<desc><![CDATA[Calls the System V IPC function msgget(2). Returns the message queue<br>
id, or the undefined value if there is an error. See also<br>
<a href="../perlipc.html#SysV-IPC">"SysV IPC" in perlipc</a> and <code class="inline"><span class="w">IPC::SysV</span></code>
and <code class="inline"><span class="w">IPC::Msg</span></code>
documentation.]]></desc>
</keyword>
<keyword name="msgrcv" type="function">
<params>
<param name='id'/>
<param name='var'/>
<param name='size'/>
<param name='type'/>
<param name='flags'/>
</params>
<desc><![CDATA[Calls the System V IPC function msgrcv to receive a message from<br>
message queue ID into variable VAR with a maximum message size of<br>
SIZE. Note that when a message is received, the message type as a<br>
native long integer will be the first thing in VAR, followed by the<br>
actual message. This packing may be opened with <code class="inline"><a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">"l! a*"</span><span class="s">)</span></code>
.<br>
Taints the variable. Returns true if successful, or false if there is<br>
an error. See also <a href="../perlipc.html#SysV-IPC">"SysV IPC" in perlipc</a>, <code class="inline"><span class="w">IPC::SysV</span></code>
, and<br>
<code class="inline"><span class="w">IPC::SysV::Msg</span></code>
documentation.]]></desc>
</keyword>
<keyword name="msgsnd" type="function">
<params>
<param name='id'/>
<param name='msg'/>
<param name='flags'/>
</params>
<desc><![CDATA[Calls the System V IPC function msgsnd to send the message MSG to the<br>
message queue ID. MSG must begin with the native long integer message<br>
type, and be followed by the length of the actual message, and finally<br>
the message itself. This kind of packing can be achieved with<br>
<code class="inline"><a class="l_k" href="../functions/pack.html">pack</a><span class="s">(</span><span class="q">"l! a*"</span><span class="cm">,</span> <span class="i">$type</span><span class="cm">,</span> <span class="i">$message</span><span class="s">)</span></code>
. Returns true if successful,<br>
or false if there is an error. See also <code class="inline"><span class="w">IPC::SysV</span></code>
<br>
and <code class="inline"><span class="w">IPC::SysV::Msg</span></code>
documentation.]]></desc>
</keyword>
<keyword name="my" type="function">
<params>
<param name='expr : attrs'/>
</params>
<desc><![CDATA[A <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code> declares the listed variables to be local (lexically) to the<br>
enclosing block, file, or <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a></code>. If more than one value is listed,<br>
the list must be placed in parentheses.</p>
<p>The exact semantics and interface of TYPE and ATTRS are still<br>
evolving. TYPE is currently bound to the use of <code class="inline"><span class="w">fields</span></code>
pragma,<br>
and attributes are handled using the <code class="inline"><span class="w">attributes</span></code>
pragma, or starting<br>
from Perl 5.8.0 also via the <code class="inline"><span class="w">Attribute::Handlers</span></code>
module. See<br>
<a href="../perlsub.html#Private-Variables-via-my()">"Private Variables via my()" in perlsub</a> for details, and <a href="../fields.html">fields</a>,<br>
<a href="../attributes.html">attributes</a>, and <a href="../Attribute/Handlers.html">Attribute::Handlers</a>.]]></desc>
</keyword>
<keyword name="my" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[A <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code> declares the listed variables to be local (lexically) to the<br>
enclosing block, file, or <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a></code>. If more than one value is listed,<br>
the list must be placed in parentheses.</p>
<p>The exact semantics and interface of TYPE and ATTRS are still<br>
evolving. TYPE is currently bound to the use of <code class="inline"><span class="w">fields</span></code>
pragma,<br>
and attributes are handled using the <code class="inline"><span class="w">attributes</span></code>
pragma, or starting<br>
from Perl 5.8.0 also via the <code class="inline"><span class="w">Attribute::Handlers</span></code>
module. See<br>
<a href="../perlsub.html#Private-Variables-via-my()">"Private Variables via my()" in perlsub</a> for details, and <a href="../fields.html">fields</a>,<br>
<a href="../attributes.html">attributes</a>, and <a href="../Attribute/Handlers.html">Attribute::Handlers</a>.]]></desc>
</keyword>
<keyword name="my" type="function">
<params>
<param name='type expr : attrs'/>
</params>
<desc><![CDATA[A <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code> declares the listed variables to be local (lexically) to the<br>
enclosing block, file, or <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a></code>. If more than one value is listed,<br>
the list must be placed in parentheses.</p>
<p>The exact semantics and interface of TYPE and ATTRS are still<br>
evolving. TYPE is currently bound to the use of <code class="inline"><span class="w">fields</span></code>
pragma,<br>
and attributes are handled using the <code class="inline"><span class="w">attributes</span></code>
pragma, or starting<br>
from Perl 5.8.0 also via the <code class="inline"><span class="w">Attribute::Handlers</span></code>
module. See<br>
<a href="../perlsub.html#Private-Variables-via-my()">"Private Variables via my()" in perlsub</a> for details, and <a href="../fields.html">fields</a>,<br>
<a href="../attributes.html">attributes</a>, and <a href="../Attribute/Handlers.html">Attribute::Handlers</a>.]]></desc>
</keyword>
<keyword name="my" type="function">
<params>
<param name='type expr'/>
</params>
<desc><![CDATA[A <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code> declares the listed variables to be local (lexically) to the<br>
enclosing block, file, or <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a></code>. If more than one value is listed,<br>
the list must be placed in parentheses.</p>
<p>The exact semantics and interface of TYPE and ATTRS are still<br>
evolving. TYPE is currently bound to the use of <code class="inline"><span class="w">fields</span></code>
pragma,<br>
and attributes are handled using the <code class="inline"><span class="w">attributes</span></code>
pragma, or starting<br>
from Perl 5.8.0 also via the <code class="inline"><span class="w">Attribute::Handlers</span></code>
module. See<br>
<a href="../perlsub.html#Private-Variables-via-my()">"Private Variables via my()" in perlsub</a> for details, and <a href="../fields.html">fields</a>,<br>
<a href="../attributes.html">attributes</a>, and <a href="../Attribute/Handlers.html">Attribute::Handlers</a>.]]></desc>
</keyword>
<keyword name="next" type="function">
<params>
<param name='label'/>
</params>
<desc><![CDATA[The <code class="inline"><a class="l_k" href="../functions/next.html">next</a></code> command is like the <code class="inline"><a class="l_k" href="../functions/continue.html">continue</a></code> statement in C; it starts<br>
the next iteration of the loop:</p>
<pre class="verbatim"><ol><li> <span class="j">LINE:</span> while <span class="s">(</span><span class="q"><STDIN></span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/next.html">next</a> <span class="j">LINE</span> if <span class="q">/^#/</span><span class="sc">;</span> <span class="c"># discard comments</span></li><li> <span class="c">#...</span></li><li> <span class="s">}</span></li></ol></pre><p>Note that if there were a <code class="inline"><a class="l_k" href="../functions/continue.html">continue</a></code> block on the above, it would get<br>
executed even on discarded lines. If the LABEL is omitted, the command<br>
refers to the innermost enclosing loop.</p>
<p><code class="inline"><a class="l_k" href="../functions/next.html">next</a></code> cannot be used to exit a block which returns a value such as<br>
<code class="inline"><a class="l_k" href="../functions/eval.html">eval</a> <span class="s">{</span><span class="s">}</span></code>
, <code class="inline"><a class="l_k" href="../functions/sub.html">sub</a> <span class="s">{</span><span class="s">}</span></code>
or <code class="inline"><a class="l_k" href="../functions/do.html">do</a> <span class="s">{</span><span class="s">}</span></code>
, and should not be used to exit<br>
a grep() or map() operation.</p>
<p>Note that a block by itself is semantically identical to a loop<br>
that executes once. Thus <code class="inline"><a class="l_k" href="../functions/next.html">next</a></code> will exit such a block early.</p>
<p>See also <a href="../functions/continue.html">"continue"</a> for an illustration of how <code class="inline"><a class="l_k" href="../functions/last.html">last</a></code>, <code class="inline"><a class="l_k" href="../functions/next.html">next</a></code>, and<br>
<code class="inline"><a class="l_k" href="../functions/redo.html">redo</a></code> work.]]></desc>
</keyword>
<keyword name="next" type="function">
<params>
</params>
<desc><![CDATA[The <code class="inline"><a class="l_k" href="../functions/next.html">next</a></code> command is like the <code class="inline"><a class="l_k" href="../functions/continue.html">continue</a></code> statement in C; it starts<br>
the next iteration of the loop:</p>
<pre class="verbatim"><ol><li> <span class="j">LINE:</span> while <span class="s">(</span><span class="q"><STDIN></span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/next.html">next</a> <span class="j">LINE</span> if <span class="q">/^#/</span><span class="sc">;</span> <span class="c"># discard comments</span></li><li> <span class="c">#...</span></li><li> <span class="s">}</span></li></ol></pre><p>Note that if there were a <code class="inline"><a class="l_k" href="../functions/continue.html">continue</a></code> block on the above, it would get<br>
executed even on discarded lines. If the LABEL is omitted, the command<br>
refers to the innermost enclosing loop.</p>
<p><code class="inline"><a class="l_k" href="../functions/next.html">next</a></code> cannot be used to exit a block which returns a value such as<br>
<code class="inline"><a class="l_k" href="../functions/eval.html">eval</a> <span class="s">{</span><span class="s">}</span></code>
, <code class="inline"><a class="l_k" href="../functions/sub.html">sub</a> <span class="s">{</span><span class="s">}</span></code>
or <code class="inline"><a class="l_k" href="../functions/do.html">do</a> <span class="s">{</span><span class="s">}</span></code>
, and should not be used to exit<br>
a grep() or map() operation.</p>
<p>Note that a block by itself is semantically identical to a loop<br>
that executes once. Thus <code class="inline"><a class="l_k" href="../functions/next.html">next</a></code> will exit such a block early.</p>
<p>See also <a href="../functions/continue.html">"continue"</a> for an illustration of how <code class="inline"><a class="l_k" href="../functions/last.html">last</a></code>, <code class="inline"><a class="l_k" href="../functions/next.html">next</a></code>, and<br>
<code class="inline"><a class="l_k" href="../functions/redo.html">redo</a></code> work.]]></desc>
</keyword>
<keyword name="no" type="function">
<params>
<param name='module list'/>
</params>
<desc><![CDATA[See the <code class="inline"><a class="l_k" href="../functions/use.html">use</a></code> function, of which <code class="inline"><a class="l_k" href="../functions/no.html">no</a></code> is the opposite.]]></desc>
</keyword>
<keyword name="no" type="function">
<params>
<param name='module version list'/>
</params>
<desc><![CDATA[See the <code class="inline"><a class="l_k" href="../functions/use.html">use</a></code> function, of which <code class="inline"><a class="l_k" href="../functions/no.html">no</a></code> is the opposite.]]></desc>
</keyword>
<keyword name="no" type="function">
<params>
<param name='module version'/>
</params>
<desc><![CDATA[See the <code class="inline"><a class="l_k" href="../functions/use.html">use</a></code> function, of which <code class="inline"><a class="l_k" href="../functions/no.html">no</a></code> is the opposite.]]></desc>
</keyword>
<keyword name="no" type="function">
<params>
<param name='module'/>
</params>
<desc><![CDATA[See the <code class="inline"><a class="l_k" href="../functions/use.html">use</a></code> function, of which <code class="inline"><a class="l_k" href="../functions/no.html">no</a></code> is the opposite.]]></desc>
</keyword>
<keyword name="no" type="function">
<params>
<param name='version'/>
</params>
<desc><![CDATA[See the <code class="inline"><a class="l_k" href="../functions/use.html">use</a></code> function, of which <code class="inline"><a class="l_k" href="../functions/no.html">no</a></code> is the opposite.]]></desc>
</keyword>
<keyword name="oct" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Interprets EXPR as an octal string and returns the corresponding<br>
value. (If EXPR happens to start off with <code class="inline"><span class="n">0</span>x</code>
, interprets it as a<br>
hex string. If EXPR starts off with <code class="inline">0b</code>, it is interpreted as a<br>
binary string. Leading whitespace is ignored in all three cases.)<br>
The following will handle decimal, binary, octal, and hex in the standard<br>
Perl or C notation:</p>
<pre class="verbatim"><ol><li> <span class="i">$val</span> = <a class="l_k" href="../functions/oct.html">oct</a><span class="s">(</span><span class="i">$val</span><span class="s">)</span> if <span class="i">$val</span> =~ <span class="q">/^0/</span><span class="sc">;</span></li></ol></pre><p>If EXPR is omitted, uses <code class="inline"><span class="i">$_</span></code>
. To go the other way (produce a number<br>
in octal), use sprintf() or printf():</p>
<pre class="verbatim"><ol><li> <span class="i">$perms</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="q">"filename"</span><span class="s">)</span><span class="s">)</span>[<span class="n">2</span>] & <span class="n">07777</span><span class="sc">;</span></li><li> <span class="i">$oct_perms</span> = <a class="l_k" href="../functions/sprintf.html">sprintf</a> <span class="q">"%lo"</span><span class="cm">,</span> <span class="i">$perms</span><span class="sc">;</span></li></ol></pre><p>The oct() function is commonly used when a string such as <code class="inline"><span class="n">644</span></code>
needs<br>
to be converted into a file mode, for example. (Although perl will<br>
automatically convert strings into numbers as needed, this automatic<br>
conversion assumes base 10.)]]></desc>
</keyword>
<keyword name="oct" type="function">
<params>
</params>
<desc><![CDATA[Interprets EXPR as an octal string and returns the corresponding<br>
value. (If EXPR happens to start off with <code class="inline"><span class="n">0</span>x</code>
, interprets it as a<br>
hex string. If EXPR starts off with <code class="inline">0b</code>, it is interpreted as a<br>
binary string. Leading whitespace is ignored in all three cases.)<br>
The following will handle decimal, binary, octal, and hex in the standard<br>
Perl or C notation:</p>
<pre class="verbatim"><ol><li> <span class="i">$val</span> = <a class="l_k" href="../functions/oct.html">oct</a><span class="s">(</span><span class="i">$val</span><span class="s">)</span> if <span class="i">$val</span> =~ <span class="q">/^0/</span><span class="sc">;</span></li></ol></pre><p>If EXPR is omitted, uses <code class="inline"><span class="i">$_</span></code>
. To go the other way (produce a number<br>
in octal), use sprintf() or printf():</p>
<pre class="verbatim"><ol><li> <span class="i">$perms</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="q">"filename"</span><span class="s">)</span><span class="s">)</span>[<span class="n">2</span>] & <span class="n">07777</span><span class="sc">;</span></li><li> <span class="i">$oct_perms</span> = <a class="l_k" href="../functions/sprintf.html">sprintf</a> <span class="q">"%lo"</span><span class="cm">,</span> <span class="i">$perms</span><span class="sc">;</span></li></ol></pre><p>The oct() function is commonly used when a string such as <code class="inline"><span class="n">644</span></code>
needs<br>
to be converted into a file mode, for example. (Although perl will<br>
automatically convert strings into numbers as needed, this automatic<br>
conversion assumes base 10.)]]></desc>
</keyword>
<keyword name="open" type="function">
<params>
<param name='filehandle'/>
<param name='expr'/>
</params>
<desc><![CDATA[Opens the file whose filename is given by EXPR, and associates it with<br>
FILEHANDLE.</p>
<p>Simple examples to open a file for reading:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$fh</span><span class="cm">,</span> <span class="q">'<'</span><span class="cm">,</span> <span class="q">"input.txt"</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="i">$!</span><span class="sc">;</span></li></ol></pre><p>and for writing:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$fh</span><span class="cm">,</span> <span class="q">'>'</span><span class="cm">,</span> <span class="q">"output.txt"</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="i">$!</span><span class="sc">;</span></li></ol></pre><p>(The following is a comprehensive reference to open(): for a gentler<br>
introduction you may consider <a href="../perlopentut.html">perlopentut</a>.)</p>
<p>If FILEHANDLE is an undefined scalar variable (or array or hash element)<br>
the variable is assigned a reference to a new anonymous filehandle,<br>
otherwise if FILEHANDLE is an expression, its value is used as the name of<br>
the real filehandle wanted. (This is considered a symbolic reference, so<br>
<code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">strict</span> <span class="q">'refs'</span></code>
should <i>not</i> be in effect.)</p>
<p>If EXPR is omitted, the scalar variable of the same name as the<br>
FILEHANDLE contains the filename. (Note that lexical variables--those<br>
declared with <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code>--will not work for this purpose; so if you're<br>
using <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code>, specify EXPR in your call to open.)</p>
<p>If three or more arguments are specified then the mode of opening and<br>
the file name are separate. If MODE is <code class="inline"><span class="q">'<'</span></code>
or nothing, the file<br>
is opened for input. If MODE is <code class="inline"><span class="q">'>'</span></code>
, the file is truncated and<br>
opened for output, being created if necessary. If MODE is <code class="inline"><span class="q">'>>'</span></code>
,<br>
the file is opened for appending, again being created if necessary.</p>
<p>You can put a <code class="inline"><span class="q">'+'</span></code>
in front of the <code class="inline"><span class="q">'>'</span></code>
or <code class="inline"><span class="q">'<'</span></code>
to<br>
indicate that you want both read and write access to the file; thus<br>
<code class="inline"><span class="q">'+<'</span></code>
is almost always preferred for read/write updates--the <code class="inline"><span class="q">'+>'</span></code>
mode would clobber the file first. You can't usually use<br>
either read-write mode for updating textfiles, since they have<br>
variable length records. See the <b>-i</b> switch in <a href="../perlrun.html">perlrun</a> for a<br>
better approach. The file is created with permissions of <code class="inline"><span class="n">0666</span></code>
<br>
modified by the process' <code class="inline"><a class="l_k" href="../functions/umask.html">umask</a></code> value.</p>
<p>These various prefixes correspond to the fopen(3) modes of <code class="inline"><span class="q">'r'</span></code>
,<br>
<code class="inline"><span class="q">'r+'</span></code>
, <code class="inline"><span class="q">'w'</span></code>
, <code class="inline"><span class="q">'w+'</span></code>
, <code class="inline"><span class="q">'a'</span></code>
, and <code class="inline"><span class="q">'a+'</span></code>
.</p>
<p>In the 2-arguments (and 1-argument) form of the call the mode and<br>
filename should be concatenated (in this order), possibly separated by<br>
spaces. It is possible to omit the mode in these forms if the mode is<br>
<code class="inline"><span class="q">'<'</span></code>
.</p>
<p>If the filename begins with <code class="inline"><span class="q">'|'</span></code>
, the filename is interpreted as a<br>
command to which output is to be piped, and if the filename ends with a<br>
<code class="inline"><span class="q">'|'</span></code>
, the filename is interpreted as a command which pipes output to<br>
us. See <a href="../perlipc.html#Using-open()-for-IPC">"Using open() for IPC" in perlipc</a>
for more examples of this. (You are not allowed to <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> to a command<br>
that pipes both in <i>and</i> out, but see <a href="../IPC/Open2.html">IPC::Open2</a>, <a href="../IPC/Open3.html">IPC::Open3</a>,<br>
and <a href="../perlipc.html#Bidirectional-Communication-with-Another-Process">"Bidirectional Communication with Another Process" in perlipc</a>
for alternatives.)</p>
<p>For three or more arguments if MODE is <code class="inline"><span class="q">'|-'</span></code>
, the filename is<br>
interpreted as a command to which output is to be piped, and if MODE<br>
is <code class="inline"><span class="q">'-|'</span></code>
, the filename is interpreted as a command which pipes<br>
output to us. In the 2-arguments (and 1-argument) form one should<br>
replace dash (<code class="inline"><span class="q">'-'</span></code>
) with the command.<br>
See <a href="../perlipc.html#Using-open()-for-IPC">"Using open() for IPC" in perlipc</a> for more examples of this.<br>
(You are not allowed to <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> to a command that pipes both in <i>and</i>
out, but see <a href="../IPC/Open2.html">IPC::Open2</a>, <a href="../IPC/Open3.html">IPC::Open3</a>, and<br>
<a href="../perlipc.html#Bidirectional-Communication">"Bidirectional Communication" in perlipc</a> for alternatives.)</p>
<p>In the three-or-more argument form of pipe opens, if LIST is specified<br>
(extra arguments after the command name) then LIST becomes arguments<br>
to the command invoked if the platform supports it. The meaning of<br>
<code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> with more than three arguments for non-pipe modes is not yet<br>
specified. Experimental "layers" may give extra LIST arguments<br>
meaning.</p>
<p>In the 2-arguments (and 1-argument) form opening <code class="inline"><span class="q">'-'</span></code>
opens STDIN<br>
and opening <code class="inline"><span class="q">'>-'</span></code>
opens STDOUT.</p>
<p>You may use the three-argument form of open to specify IO "layers"<br>
(sometimes also referred to as "disciplines") to be applied to the handle<br>
that affect how the input and output are processed (see <a href="../open.html">open</a> and<br>
<a href="../PerlIO.html">PerlIO</a> for more details). For example</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$fh</span><span class="cm">,</span> <span class="q">"<:encoding(UTF-8)"</span><span class="cm">,</span> <span class="q">"file"</span><span class="s">)</span></li></ol></pre><p>will open the UTF-8 encoded file containing Unicode characters,<br>
see <a href="../perluniintro.html">perluniintro</a>. Note that if layers are specified in the<br>
three-arg form then default layers stored in ${^OPEN} (see <a href="../perlvar.html">perlvar</a>;<br>
usually set by the <b>open</b> pragma or the switch <b>-CioD</b>) are ignored.</p>
<p>Open returns nonzero upon success, the undefined value otherwise. If<br>
the <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> involved a pipe, the return value happens to be the pid of<br>
the subprocess.</p>
<p>If you're running Perl on a system that distinguishes between text<br>
files and binary files, then you should check out <a href="../functions/binmode.html">"binmode"</a> for tips<br>
for dealing with this. The key distinction between systems that need<br>
<code class="inline"><a class="l_k" href="../functions/binmode.html">binmode</a></code> and those that don't is their text file formats. Systems<br>
like Unix, Mac OS, and Plan 9, which delimit lines with a single<br>
character, and which encode that character in C as <code class="inline"><span class="q">"\n"</span></code>
, do not<br>
need <code class="inline"><a class="l_k" href="../functions/binmode.html">binmode</a></code>. The rest need it.</p>
<p>When opening a file, it's usually a bad idea to continue normal execution<br>
if the request failed, so <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> is frequently used in connection with<br>
<code class="inline"><a class="l_k" href="../functions/die.html">die</a></code>. Even if <code class="inline"><a class="l_k" href="../functions/die.html">die</a></code> won't do what you want (say, in a CGI script,<br>
where you want to make a nicely formatted error message (but there are<br>
modules that can help with that problem)) you should always check<br>
the return value from opening a file. The infrequent exception is when<br>
working with an unopened filehandle is actually what you want to do.</p>
<p>As a special case the 3-arg form with a read/write mode and the third<br>
argument being <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code>:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$tmp</span><span class="cm">,</span> <span class="q">"+>"</span><span class="cm">,</span> <a class="l_k" href="../functions/undef.html">undef</a><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> ...</li></ol></pre><p>opens a filehandle to an anonymous temporary file. Also using "+<"<br>
works for symmetry, but you really should consider writing something<br>
to the temporary file first. You will need to seek() to do the<br>
reading.</p>
<p>Since v5.8.0, perl has built using PerlIO by default. Unless you've<br>
changed this (i.e. Configure -Uuseperlio), you can open file handles to<br>
"in memory" files held in Perl scalars via:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="i">$fh</span><span class="cm">,</span> <span class="q">'>'</span><span class="cm">,</span> \<span class="i">$variable</span><span class="s">)</span> || ..</li></ol></pre><p>Though if you try to re-open <code class="inline"><span class="w">STDOUT</span></code>
or <code class="inline"><span class="w">STDERR</span></code>
as an "in memory"<br>
file, you have to close it first:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/close.html">close</a> <span class="w">STDOUT</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDOUT</span><span class="cm">,</span> <span class="q">'>'</span><span class="cm">,</span> \<span class="i">$variable</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't open STDOUT: $!"</span><span class="sc">;</span></li></ol></pre><p>Examples:</p>
<pre class="verbatim"><ol><li> $ARTICLE = 100;</li><li> open ARTICLE or die "Can't find article $ARTICLE: $!\n";</li><li> while (<ARTICLE>) {...</li><li></li><li> open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved)</li><li> # if the open fails, output is discarded</li><li></li><li> open(my $dbase, '+<', 'dbase.mine') # open for update</li><li> or die "Can't open 'dbase.mine' for update: $!";</li><li></li><li> open(my $dbase, '+<dbase.mine') # ditto</li><li> or die "Can't open 'dbase.mine' for update: $!";</li><li></li><li> open(ARTICLE, '-|', "caesar <$article") # decrypt article</li><li> or die "Can't start caesar: $!";</li><li></li><li> open(ARTICLE, "caesar <$article |") # ditto</li><li> or die "Can't start caesar: $!";</li><li></li><li> open(EXTRACT, "|sort >Tmp$$") # $$ is our process id</li><li> or die "Can't start sort: $!";</li><li></li><li> # in memory files</li><li> open(MEMORY,'>', \$var)</li><li> or die "Can't open memory file: $!";</li><li> print MEMORY "foo!\n"; # output will end up in $var</li><li></li><li> # process argument list of files along with any includes</li><li></li><li> foreach $file (@ARGV) {</li><li> process($file, 'fh00');</li><li> }</li><li></li><li> sub process {</li><li> my($filename, $input) = @_;</li><li> $input++; # this is a string increment</li><li> unless (open($input, $filename)) {</li><li> print STDERR "Can't open $filename: $!\n";</li><li> return;</li><li> }</li><li></li><li> local $_;</li><li> while (<$input>) { # note use of indirection</li><li> if (/^#include "(.*)"/) {</li><li> process($1, $input);</li><li> next;</li><li> }</li><li> #... # whatever</li><li> }</li><li> }</li></ol></pre><p>See <a href="../perliol.html">perliol</a> for detailed info on PerlIO.</p>
<p>You may also, in the Bourne shell tradition, specify an EXPR beginning<br>
with <code class="inline"><span class="q">'>&'</span></code>
, in which case the rest of the string is interpreted<br>
as the name of a filehandle (or file descriptor, if numeric) to be<br>
duped (as <code class="inline"><span class="i">dup</span><span class="s">(</span><span class="n">2</span><span class="s">)</span></code>
) and opened. You may use <code class="inline"><span class="i">&</span></code>
after <code class="inline">></code>,<br>
<code class="inline">>></code>
, <code class="inline"><</code>
, <code class="inline">+></code>, <code class="inline">+>></code>
, and <code class="inline">+<</code>
.<br>
The mode you specify should match the mode of the original filehandle.<br>
(Duping a filehandle does not take into account any existing contents<br>
of IO buffers.) If you use the 3-arg form then you can pass either a<br>
number, the name of a filehandle or the normal "reference to a glob".</p>
<p>Here is a script that saves, redirects, and restores <code class="inline"><span class="w">STDOUT</span></code>
and<br>
<code class="inline"><span class="w">STDERR</span></code>
using various methods:</p>
<pre class="verbatim"><ol><li> <span class="c">#!/usr/bin/perl</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$oldout</span><span class="cm">,</span> <span class="q">">&STDOUT"</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup STDOUT: $!"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">OLDERR</span><span class="cm">,</span> <span class="q">">&"</span><span class="cm">,</span> \<span class="i">*STDERR</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup STDERR: $!"</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDOUT</span><span class="cm">,</span> <span class="q">'>'</span><span class="cm">,</span> <span class="q">"foo.out"</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't redirect STDOUT: $!"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDERR</span><span class="cm">,</span> <span class="q">">&STDOUT"</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup STDOUT: $!"</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/select.html">select</a> <span class="w">STDERR</span><span class="sc">;</span> <span class="i">$|</span> = <span class="n">1</span><span class="sc">;</span> <span class="c"># make unbuffered</span></li><li> <a class="l_k" href="../functions/select.html">select</a> <span class="w">STDOUT</span><span class="sc">;</span> <span class="i">$|</span> = <span class="n">1</span><span class="sc">;</span> <span class="c"># make unbuffered</span></li><li></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDOUT</span> <span class="q">"stdout 1\n"</span><span class="sc">;</span> <span class="c"># this works for</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDERR</span> <span class="q">"stderr 1\n"</span><span class="sc">;</span> <span class="c"># subprocesses too</span></li><li></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDOUT</span><span class="cm">,</span> <span class="q">">&"</span><span class="cm">,</span> <span class="i">$oldout</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup \$oldout: $!"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDERR</span><span class="cm">,</span> <span class="q">">&OLDERR"</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup OLDERR: $!"</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDOUT</span> <span class="q">"stdout 2\n"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDERR</span> <span class="q">"stderr 2\n"</span><span class="sc">;</span></li></ol></pre><p>If you specify <code class="inline"><span class="q">'<&=X'</span></code>
, where <code class="inline"><span class="w">X</span></code>
is a file descriptor number<br>
or a filehandle, then Perl will do an equivalent of C's <code class="inline"><span class="w">fdopen</span></code>
of<br>
that file descriptor (and not call <code class="inline"><span class="i">dup</span><span class="s">(</span><span class="n">2</span><span class="s">)</span></code>
); this is more<br>
parsimonious of file descriptors. For example:</p>
<pre class="verbatim"><ol><li> <span class="c"># open for input, reusing the fileno of $fd</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FILEHANDLE</span><span class="cm">,</span> <span class="q">"<&=$fd"</span><span class="s">)</span></li></ol></pre><p>or</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FILEHANDLE</span><span class="cm">,</span> <span class="q">"<&="</span><span class="cm">,</span> <span class="i">$fd</span><span class="s">)</span></li></ol></pre><p>or</p>
<pre class="verbatim"><ol><li> <span class="c"># open for append, using the fileno of OLDFH</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FH</span><span class="cm">,</span> <span class="q">">>&="</span><span class="cm">,</span> <span class="w">OLDFH</span><span class="s">)</span></li></ol></pre><p>or</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FH</span><span class="cm">,</span> <span class="q">">>&=OLDFH"</span><span class="s">)</span></li></ol></pre><p>Being parsimonious on filehandles is also useful (besides being<br>
parsimonious) for example when something is dependent on file<br>
descriptors, like for example locking using flock(). If you do just<br>
<code class="inline"><a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">A</span><span class="cm">,</span> <span class="q">'>>&B'</span><span class="s">)</span></code>
, the filehandle A will not have the same file<br>
descriptor as B, and therefore flock(A) will not flock(B), and vice<br>
versa. But with <code class="inline"><a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">A</span><span class="cm">,</span> <span class="q">'>>&=B'</span><span class="s">)</span></code>
the filehandles will share<br>
the same file descriptor.</p>
<p>Note that if you are using Perls older than 5.8.0, Perl will be using<br>
the standard C libraries' fdopen() to implement the "=" functionality.<br>
On many UNIX systems fdopen() fails when file descriptors exceed a<br>
certain value, typically 255. For Perls 5.8.0 and later, PerlIO is<br>
most often the default.</p>
<p>You can see whether Perl has been compiled with PerlIO or not by<br>
running <code class="inline"><span class="w">perl</span> -<span class="w">V</span></code>
and looking for <code class="inline"><span class="w">useperlio</span>=</code>
line. If <code class="inline"><span class="w">useperlio</span></code>
<br>
is <code class="inline"><span class="w">define</span></code>
, you have PerlIO, otherwise you don't.</p>
<p>If you open a pipe on the command <code class="inline"><span class="q">'-'</span></code>
, i.e., either <code class="inline"><span class="q">'|-'</span></code>
or <code class="inline"><span class="q">'-|'</span></code>
<br>
with 2-arguments (or 1-argument) form of open(), then<br>
there is an implicit fork done, and the return value of open is the pid<br>
of the child within the parent process, and <code class="inline"><span class="n">0</span></code>
within the child<br>
process. (Use <code class="inline"><a class="l_k" href="../functions/defined.html">defined($pid)</a></code> to determine whether the open was successful.)<br>
The filehandle behaves normally for the parent, but i/o to that<br>
filehandle is piped from/to the STDOUT/STDIN of the child process.<br>
In the child process the filehandle isn't opened--i/o happens from/to<br>
the new STDOUT or STDIN. Typically this is used like the normal<br>
piped open when you want to exercise more control over just how the<br>
pipe command gets executed, such as when you are running setuid, and<br>
don't want to have to scan shell commands for metacharacters.<br>
The following triples are more or less equivalent:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">"|tr '[a-z]' '[A-Z]'"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'|-'</span><span class="cm">,</span> <span class="q">"tr '[a-z]' '[A-Z]'"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'|-'</span><span class="s">)</span> || <a class="l_k" href="../functions/exec.html">exec</a> <span class="q">'tr'</span><span class="cm">,</span> <span class="q">'[a-z]'</span><span class="cm">,</span> <span class="q">'[A-Z]'</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'|-'</span><span class="cm">,</span> <span class="q">"tr"</span><span class="cm">,</span> <span class="q">'[a-z]'</span><span class="cm">,</span> <span class="q">'[A-Z]'</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">"cat -n '$file'|"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'-|'</span><span class="cm">,</span> <span class="q">"cat -n '$file'"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'-|'</span><span class="s">)</span> || <a class="l_k" href="../functions/exec.html">exec</a> <span class="q">'cat'</span><span class="cm">,</span> <span class="q">'-n'</span><span class="cm">,</span> <span class="i">$file</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'-|'</span><span class="cm">,</span> <span class="q">"cat"</span><span class="cm">,</span> <span class="q">'-n'</span><span class="cm">,</span> <span class="i">$file</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The last example in each block shows the pipe as "list form", which is<br>
not yet supported on all platforms. A good rule of thumb is that if<br>
your platform has true <code class="inline"><a class="l_k" href="../functions/fork.html">fork()</a></code> (in other words, if your platform is<br>
UNIX) you can use the list form.</p>
<p>See <a href="../perlipc.html#Safe-Pipe-Opens">"Safe Pipe Opens" in perlipc</a> for more examples of this.</p>
<p>Beginning with v5.6.0, Perl will attempt to flush all files opened for<br>
output before any operation that may do a fork, but this may not be<br>
supported on some platforms (see <a href="../perlport.html">perlport</a>). To be safe, you may need<br>
to set <code class="inline"><span class="i">$|</span></code>
($AUTOFLUSH in English) or call the <code class="inline"><span class="i">autoflush</span><span class="s">(</span><span class="s">)</span></code>
method<br>
of <code class="inline"><span class="w">IO::Handle</span></code>
on any open handles.</p>
<p>On systems that support a close-on-exec flag on files, the flag will<br>
be set for the newly opened file descriptor as determined by the value<br>
of $^F. See <a href="../perlvar.html#%24%5eF">"$^F" in perlvar</a>.</p>
<p>Closing any piped filehandle causes the parent process to wait for the<br>
child to finish, and returns the status value in <code class="inline"><span class="i">$?</span></code>
and<br>
<code class="inline"><span class="i">$</span>{<span class="w">^CHILD_ERROR_NATIVE</span>}</code>
.</p>
<p>The filename passed to 2-argument (or 1-argument) form of open() will<br>
have leading and trailing whitespace deleted, and the normal<br>
redirection characters honored. This property, known as "magic open",<br>
can often be used to good effect. A user could specify a filename of<br>
<i>"rsh cat file |"</i>, or you could change certain filenames as needed:</p>
<pre class="verbatim"><ol><li> <span class="i">$filename</span> =~ <span class="q">s/(.*\.gz)\s*$/gzip -dc < $1|/</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FH</span><span class="cm">,</span> <span class="i">$filename</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't open $filename: $!"</span><span class="sc">;</span></li></ol></pre><p>Use 3-argument form to open a file with arbitrary weird characters in it,</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'<'</span><span class="cm">,</span> <span class="i">$file</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>otherwise it's necessary to protect any leading and trailing whitespace:</p>
<pre class="verbatim"><ol><li> <span class="i">$file</span> =~ <span class="q">s#^(\s)#./$1#</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">"< $file\0"</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>(this may not work on some bizarre filesystems). One should<br>
conscientiously choose between the <i>magic</i> and 3-arguments form<br>
of open():</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">IN</span><span class="cm">,</span> <span class="i">$ARGV</span>[<span class="n">0</span>]<span class="sc">;</span></li></ol></pre><p>will allow the user to specify an argument of the form <code class="inline"><span class="q">"rsh cat file |"</span></code>
,<br>
but will not work on a filename which happens to have a trailing space, while</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">IN</span><span class="cm">,</span> <span class="q">'<'</span><span class="cm">,</span> <span class="i">$ARGV</span>[<span class="n">0</span>]<span class="sc">;</span></li></ol></pre><p>will have exactly the opposite restrictions.</p>
<p>If you want a "real" C <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> (see <code class="inline"><a class="l_k" href="../functions/open.html">open(2)</a></code> on your system), then you<br>
should use the <code class="inline"><a class="l_k" href="../functions/sysopen.html">sysopen</a></code> function, which involves no such magic (but<br>
may use subtly different filemodes than Perl open(), which is mapped<br>
to C fopen()). This is<br>
another way to protect your filenames from interpretation. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">IO::Handle</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/sysopen.html">sysopen</a><span class="s">(</span><span class="w">HANDLE</span><span class="cm">,</span> <span class="i">$path</span><span class="cm">,</span> <span class="w">O_RDWR</span>|<span class="w">O_CREAT</span>|<span class="w">O_EXCL</span><span class="s">)</span></li><li> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"sysopen $path: $!"</span><span class="sc">;</span></li><li> <span class="i">$oldfh</span> = <a class="l_k" href="../functions/select.html">select</a><span class="s">(</span><span class="w">HANDLE</span><span class="s">)</span><span class="sc">;</span> <span class="i">$|</span> = <span class="n">1</span><span class="sc">;</span> <a class="l_k" href="../functions/select.html">select</a><span class="s">(</span><span class="i">$oldfh</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">HANDLE</span> <span class="q">"stuff $$\n"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/seek.html">seek</a><span class="s">(</span><span class="w">HANDLE</span><span class="cm">,</span> <span class="n">0</span><span class="cm">,</span> <span class="n">0</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"File contains: "</span><span class="cm">,</span> <span class="q"><HANDLE></span><span class="sc">;</span></li></ol></pre><p>Using the constructor from the <code class="inline"><span class="w">IO::Handle</span></code>
package (or one of its<br>
subclasses, such as <code class="inline"><span class="w">IO::File</span></code>
or <code class="inline"><span class="w">IO::Socket</span></code>
), you can generate anonymous<br>
filehandles that have the scope of whatever variables hold references to<br>
them, and automatically close whenever and however you leave that scope:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">IO::File</span><span class="sc">;</span></li><li> <span class="c">#...</span></li><li><a name="read_myfile_munged"></a> sub <span class="m">read_myfile_munged</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$ALL</span> = <a class="l_k" href="../functions/shift.html">shift</a><span class="sc">;</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$handle</span> = <span class="w">IO::File</span><span class="w">->new</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="i">$handle</span><span class="cm">,</span> <span class="q">"myfile"</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"myfile: $!"</span><span class="sc">;</span></li><li> <span class="i">$first</span> = <span class="q"><$handle></span></li><li> or <a class="l_k" href="../functions/return.html">return</a> <span class="s">(</span><span class="s">)</span><span class="sc">;</span> <span class="c"># Automatically closed here.</span></li><li> <span class="w">mung</span> <span class="i">$first</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"mung failed"</span><span class="sc">;</span> <span class="c"># Or here.</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <span class="i">$first</span><span class="cm">,</span> <span class="q"><$handle></span> if <span class="i">$ALL</span><span class="sc">;</span> <span class="c"># Or here.</span></li><li> <span class="i">$first</span><span class="sc">;</span> <span class="c"># Or here.</span></li><li> <span class="s">}</span></li></ol></pre><p>See <a href="../functions/seek.html">"seek"</a> for some details about mixing reading and writing.]]></desc>
</keyword>
<keyword name="open" type="function">
<params>
<param name='filehandle'/>
<param name='mode'/>
<param name='expr'/>
<param name='list'/>
</params>
<desc><![CDATA[Opens the file whose filename is given by EXPR, and associates it with<br>
FILEHANDLE.</p>
<p>Simple examples to open a file for reading:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$fh</span><span class="cm">,</span> <span class="q">'<'</span><span class="cm">,</span> <span class="q">"input.txt"</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="i">$!</span><span class="sc">;</span></li></ol></pre><p>and for writing:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$fh</span><span class="cm">,</span> <span class="q">'>'</span><span class="cm">,</span> <span class="q">"output.txt"</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="i">$!</span><span class="sc">;</span></li></ol></pre><p>(The following is a comprehensive reference to open(): for a gentler<br>
introduction you may consider <a href="../perlopentut.html">perlopentut</a>.)</p>
<p>If FILEHANDLE is an undefined scalar variable (or array or hash element)<br>
the variable is assigned a reference to a new anonymous filehandle,<br>
otherwise if FILEHANDLE is an expression, its value is used as the name of<br>
the real filehandle wanted. (This is considered a symbolic reference, so<br>
<code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">strict</span> <span class="q">'refs'</span></code>
should <i>not</i> be in effect.)</p>
<p>If EXPR is omitted, the scalar variable of the same name as the<br>
FILEHANDLE contains the filename. (Note that lexical variables--those<br>
declared with <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code>--will not work for this purpose; so if you're<br>
using <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code>, specify EXPR in your call to open.)</p>
<p>If three or more arguments are specified then the mode of opening and<br>
the file name are separate. If MODE is <code class="inline"><span class="q">'<'</span></code>
or nothing, the file<br>
is opened for input. If MODE is <code class="inline"><span class="q">'>'</span></code>
, the file is truncated and<br>
opened for output, being created if necessary. If MODE is <code class="inline"><span class="q">'>>'</span></code>
,<br>
the file is opened for appending, again being created if necessary.</p>
<p>You can put a <code class="inline"><span class="q">'+'</span></code>
in front of the <code class="inline"><span class="q">'>'</span></code>
or <code class="inline"><span class="q">'<'</span></code>
to<br>
indicate that you want both read and write access to the file; thus<br>
<code class="inline"><span class="q">'+<'</span></code>
is almost always preferred for read/write updates--the <code class="inline"><span class="q">'+>'</span></code>
mode would clobber the file first. You can't usually use<br>
either read-write mode for updating textfiles, since they have<br>
variable length records. See the <b>-i</b> switch in <a href="../perlrun.html">perlrun</a> for a<br>
better approach. The file is created with permissions of <code class="inline"><span class="n">0666</span></code>
<br>
modified by the process' <code class="inline"><a class="l_k" href="../functions/umask.html">umask</a></code> value.</p>
<p>These various prefixes correspond to the fopen(3) modes of <code class="inline"><span class="q">'r'</span></code>
,<br>
<code class="inline"><span class="q">'r+'</span></code>
, <code class="inline"><span class="q">'w'</span></code>
, <code class="inline"><span class="q">'w+'</span></code>
, <code class="inline"><span class="q">'a'</span></code>
, and <code class="inline"><span class="q">'a+'</span></code>
.</p>
<p>In the 2-arguments (and 1-argument) form of the call the mode and<br>
filename should be concatenated (in this order), possibly separated by<br>
spaces. It is possible to omit the mode in these forms if the mode is<br>
<code class="inline"><span class="q">'<'</span></code>
.</p>
<p>If the filename begins with <code class="inline"><span class="q">'|'</span></code>
, the filename is interpreted as a<br>
command to which output is to be piped, and if the filename ends with a<br>
<code class="inline"><span class="q">'|'</span></code>
, the filename is interpreted as a command which pipes output to<br>
us. See <a href="../perlipc.html#Using-open()-for-IPC">"Using open() for IPC" in perlipc</a>
for more examples of this. (You are not allowed to <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> to a command<br>
that pipes both in <i>and</i> out, but see <a href="../IPC/Open2.html">IPC::Open2</a>, <a href="../IPC/Open3.html">IPC::Open3</a>,<br>
and <a href="../perlipc.html#Bidirectional-Communication-with-Another-Process">"Bidirectional Communication with Another Process" in perlipc</a>
for alternatives.)</p>
<p>For three or more arguments if MODE is <code class="inline"><span class="q">'|-'</span></code>
, the filename is<br>
interpreted as a command to which output is to be piped, and if MODE<br>
is <code class="inline"><span class="q">'-|'</span></code>
, the filename is interpreted as a command which pipes<br>
output to us. In the 2-arguments (and 1-argument) form one should<br>
replace dash (<code class="inline"><span class="q">'-'</span></code>
) with the command.<br>
See <a href="../perlipc.html#Using-open()-for-IPC">"Using open() for IPC" in perlipc</a> for more examples of this.<br>
(You are not allowed to <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> to a command that pipes both in <i>and</i>
out, but see <a href="../IPC/Open2.html">IPC::Open2</a>, <a href="../IPC/Open3.html">IPC::Open3</a>, and<br>
<a href="../perlipc.html#Bidirectional-Communication">"Bidirectional Communication" in perlipc</a> for alternatives.)</p>
<p>In the three-or-more argument form of pipe opens, if LIST is specified<br>
(extra arguments after the command name) then LIST becomes arguments<br>
to the command invoked if the platform supports it. The meaning of<br>
<code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> with more than three arguments for non-pipe modes is not yet<br>
specified. Experimental "layers" may give extra LIST arguments<br>
meaning.</p>
<p>In the 2-arguments (and 1-argument) form opening <code class="inline"><span class="q">'-'</span></code>
opens STDIN<br>
and opening <code class="inline"><span class="q">'>-'</span></code>
opens STDOUT.</p>
<p>You may use the three-argument form of open to specify IO "layers"<br>
(sometimes also referred to as "disciplines") to be applied to the handle<br>
that affect how the input and output are processed (see <a href="../open.html">open</a> and<br>
<a href="../PerlIO.html">PerlIO</a> for more details). For example</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$fh</span><span class="cm">,</span> <span class="q">"<:encoding(UTF-8)"</span><span class="cm">,</span> <span class="q">"file"</span><span class="s">)</span></li></ol></pre><p>will open the UTF-8 encoded file containing Unicode characters,<br>
see <a href="../perluniintro.html">perluniintro</a>. Note that if layers are specified in the<br>
three-arg form then default layers stored in ${^OPEN} (see <a href="../perlvar.html">perlvar</a>;<br>
usually set by the <b>open</b> pragma or the switch <b>-CioD</b>) are ignored.</p>
<p>Open returns nonzero upon success, the undefined value otherwise. If<br>
the <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> involved a pipe, the return value happens to be the pid of<br>
the subprocess.</p>
<p>If you're running Perl on a system that distinguishes between text<br>
files and binary files, then you should check out <a href="../functions/binmode.html">"binmode"</a> for tips<br>
for dealing with this. The key distinction between systems that need<br>
<code class="inline"><a class="l_k" href="../functions/binmode.html">binmode</a></code> and those that don't is their text file formats. Systems<br>
like Unix, Mac OS, and Plan 9, which delimit lines with a single<br>
character, and which encode that character in C as <code class="inline"><span class="q">"\n"</span></code>
, do not<br>
need <code class="inline"><a class="l_k" href="../functions/binmode.html">binmode</a></code>. The rest need it.</p>
<p>When opening a file, it's usually a bad idea to continue normal execution<br>
if the request failed, so <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> is frequently used in connection with<br>
<code class="inline"><a class="l_k" href="../functions/die.html">die</a></code>. Even if <code class="inline"><a class="l_k" href="../functions/die.html">die</a></code> won't do what you want (say, in a CGI script,<br>
where you want to make a nicely formatted error message (but there are<br>
modules that can help with that problem)) you should always check<br>
the return value from opening a file. The infrequent exception is when<br>
working with an unopened filehandle is actually what you want to do.</p>
<p>As a special case the 3-arg form with a read/write mode and the third<br>
argument being <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code>:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$tmp</span><span class="cm">,</span> <span class="q">"+>"</span><span class="cm">,</span> <a class="l_k" href="../functions/undef.html">undef</a><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> ...</li></ol></pre><p>opens a filehandle to an anonymous temporary file. Also using "+<"<br>
works for symmetry, but you really should consider writing something<br>
to the temporary file first. You will need to seek() to do the<br>
reading.</p>
<p>Since v5.8.0, perl has built using PerlIO by default. Unless you've<br>
changed this (i.e. Configure -Uuseperlio), you can open file handles to<br>
"in memory" files held in Perl scalars via:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="i">$fh</span><span class="cm">,</span> <span class="q">'>'</span><span class="cm">,</span> \<span class="i">$variable</span><span class="s">)</span> || ..</li></ol></pre><p>Though if you try to re-open <code class="inline"><span class="w">STDOUT</span></code>
or <code class="inline"><span class="w">STDERR</span></code>
as an "in memory"<br>
file, you have to close it first:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/close.html">close</a> <span class="w">STDOUT</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDOUT</span><span class="cm">,</span> <span class="q">'>'</span><span class="cm">,</span> \<span class="i">$variable</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't open STDOUT: $!"</span><span class="sc">;</span></li></ol></pre><p>Examples:</p>
<pre class="verbatim"><ol><li> $ARTICLE = 100;</li><li> open ARTICLE or die "Can't find article $ARTICLE: $!\n";</li><li> while (<ARTICLE>) {...</li><li></li><li> open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved)</li><li> # if the open fails, output is discarded</li><li></li><li> open(my $dbase, '+<', 'dbase.mine') # open for update</li><li> or die "Can't open 'dbase.mine' for update: $!";</li><li></li><li> open(my $dbase, '+<dbase.mine') # ditto</li><li> or die "Can't open 'dbase.mine' for update: $!";</li><li></li><li> open(ARTICLE, '-|', "caesar <$article") # decrypt article</li><li> or die "Can't start caesar: $!";</li><li></li><li> open(ARTICLE, "caesar <$article |") # ditto</li><li> or die "Can't start caesar: $!";</li><li></li><li> open(EXTRACT, "|sort >Tmp$$") # $$ is our process id</li><li> or die "Can't start sort: $!";</li><li></li><li> # in memory files</li><li> open(MEMORY,'>', \$var)</li><li> or die "Can't open memory file: $!";</li><li> print MEMORY "foo!\n"; # output will end up in $var</li><li></li><li> # process argument list of files along with any includes</li><li></li><li> foreach $file (@ARGV) {</li><li> process($file, 'fh00');</li><li> }</li><li></li><li> sub process {</li><li> my($filename, $input) = @_;</li><li> $input++; # this is a string increment</li><li> unless (open($input, $filename)) {</li><li> print STDERR "Can't open $filename: $!\n";</li><li> return;</li><li> }</li><li></li><li> local $_;</li><li> while (<$input>) { # note use of indirection</li><li> if (/^#include "(.*)"/) {</li><li> process($1, $input);</li><li> next;</li><li> }</li><li> #... # whatever</li><li> }</li><li> }</li></ol></pre><p>See <a href="../perliol.html">perliol</a> for detailed info on PerlIO.</p>
<p>You may also, in the Bourne shell tradition, specify an EXPR beginning<br>
with <code class="inline"><span class="q">'>&'</span></code>
, in which case the rest of the string is interpreted<br>
as the name of a filehandle (or file descriptor, if numeric) to be<br>
duped (as <code class="inline"><span class="i">dup</span><span class="s">(</span><span class="n">2</span><span class="s">)</span></code>
) and opened. You may use <code class="inline"><span class="i">&</span></code>
after <code class="inline">></code>,<br>
<code class="inline">>></code>
, <code class="inline"><</code>
, <code class="inline">+></code>, <code class="inline">+>></code>
, and <code class="inline">+<</code>
.<br>
The mode you specify should match the mode of the original filehandle.<br>
(Duping a filehandle does not take into account any existing contents<br>
of IO buffers.) If you use the 3-arg form then you can pass either a<br>
number, the name of a filehandle or the normal "reference to a glob".</p>
<p>Here is a script that saves, redirects, and restores <code class="inline"><span class="w">STDOUT</span></code>
and<br>
<code class="inline"><span class="w">STDERR</span></code>
using various methods:</p>
<pre class="verbatim"><ol><li> <span class="c">#!/usr/bin/perl</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$oldout</span><span class="cm">,</span> <span class="q">">&STDOUT"</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup STDOUT: $!"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">OLDERR</span><span class="cm">,</span> <span class="q">">&"</span><span class="cm">,</span> \<span class="i">*STDERR</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup STDERR: $!"</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDOUT</span><span class="cm">,</span> <span class="q">'>'</span><span class="cm">,</span> <span class="q">"foo.out"</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't redirect STDOUT: $!"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDERR</span><span class="cm">,</span> <span class="q">">&STDOUT"</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup STDOUT: $!"</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/select.html">select</a> <span class="w">STDERR</span><span class="sc">;</span> <span class="i">$|</span> = <span class="n">1</span><span class="sc">;</span> <span class="c"># make unbuffered</span></li><li> <a class="l_k" href="../functions/select.html">select</a> <span class="w">STDOUT</span><span class="sc">;</span> <span class="i">$|</span> = <span class="n">1</span><span class="sc">;</span> <span class="c"># make unbuffered</span></li><li></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDOUT</span> <span class="q">"stdout 1\n"</span><span class="sc">;</span> <span class="c"># this works for</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDERR</span> <span class="q">"stderr 1\n"</span><span class="sc">;</span> <span class="c"># subprocesses too</span></li><li></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDOUT</span><span class="cm">,</span> <span class="q">">&"</span><span class="cm">,</span> <span class="i">$oldout</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup \$oldout: $!"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDERR</span><span class="cm">,</span> <span class="q">">&OLDERR"</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup OLDERR: $!"</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDOUT</span> <span class="q">"stdout 2\n"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDERR</span> <span class="q">"stderr 2\n"</span><span class="sc">;</span></li></ol></pre><p>If you specify <code class="inline"><span class="q">'<&=X'</span></code>
, where <code class="inline"><span class="w">X</span></code>
is a file descriptor number<br>
or a filehandle, then Perl will do an equivalent of C's <code class="inline"><span class="w">fdopen</span></code>
of<br>
that file descriptor (and not call <code class="inline"><span class="i">dup</span><span class="s">(</span><span class="n">2</span><span class="s">)</span></code>
); this is more<br>
parsimonious of file descriptors. For example:</p>
<pre class="verbatim"><ol><li> <span class="c"># open for input, reusing the fileno of $fd</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FILEHANDLE</span><span class="cm">,</span> <span class="q">"<&=$fd"</span><span class="s">)</span></li></ol></pre><p>or</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FILEHANDLE</span><span class="cm">,</span> <span class="q">"<&="</span><span class="cm">,</span> <span class="i">$fd</span><span class="s">)</span></li></ol></pre><p>or</p>
<pre class="verbatim"><ol><li> <span class="c"># open for append, using the fileno of OLDFH</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FH</span><span class="cm">,</span> <span class="q">">>&="</span><span class="cm">,</span> <span class="w">OLDFH</span><span class="s">)</span></li></ol></pre><p>or</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FH</span><span class="cm">,</span> <span class="q">">>&=OLDFH"</span><span class="s">)</span></li></ol></pre><p>Being parsimonious on filehandles is also useful (besides being<br>
parsimonious) for example when something is dependent on file<br>
descriptors, like for example locking using flock(). If you do just<br>
<code class="inline"><a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">A</span><span class="cm">,</span> <span class="q">'>>&B'</span><span class="s">)</span></code>
, the filehandle A will not have the same file<br>
descriptor as B, and therefore flock(A) will not flock(B), and vice<br>
versa. But with <code class="inline"><a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">A</span><span class="cm">,</span> <span class="q">'>>&=B'</span><span class="s">)</span></code>
the filehandles will share<br>
the same file descriptor.</p>
<p>Note that if you are using Perls older than 5.8.0, Perl will be using<br>
the standard C libraries' fdopen() to implement the "=" functionality.<br>
On many UNIX systems fdopen() fails when file descriptors exceed a<br>
certain value, typically 255. For Perls 5.8.0 and later, PerlIO is<br>
most often the default.</p>
<p>You can see whether Perl has been compiled with PerlIO or not by<br>
running <code class="inline"><span class="w">perl</span> -<span class="w">V</span></code>
and looking for <code class="inline"><span class="w">useperlio</span>=</code>
line. If <code class="inline"><span class="w">useperlio</span></code>
<br>
is <code class="inline"><span class="w">define</span></code>
, you have PerlIO, otherwise you don't.</p>
<p>If you open a pipe on the command <code class="inline"><span class="q">'-'</span></code>
, i.e., either <code class="inline"><span class="q">'|-'</span></code>
or <code class="inline"><span class="q">'-|'</span></code>
<br>
with 2-arguments (or 1-argument) form of open(), then<br>
there is an implicit fork done, and the return value of open is the pid<br>
of the child within the parent process, and <code class="inline"><span class="n">0</span></code>
within the child<br>
process. (Use <code class="inline"><a class="l_k" href="../functions/defined.html">defined($pid)</a></code> to determine whether the open was successful.)<br>
The filehandle behaves normally for the parent, but i/o to that<br>
filehandle is piped from/to the STDOUT/STDIN of the child process.<br>
In the child process the filehandle isn't opened--i/o happens from/to<br>
the new STDOUT or STDIN. Typically this is used like the normal<br>
piped open when you want to exercise more control over just how the<br>
pipe command gets executed, such as when you are running setuid, and<br>
don't want to have to scan shell commands for metacharacters.<br>
The following triples are more or less equivalent:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">"|tr '[a-z]' '[A-Z]'"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'|-'</span><span class="cm">,</span> <span class="q">"tr '[a-z]' '[A-Z]'"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'|-'</span><span class="s">)</span> || <a class="l_k" href="../functions/exec.html">exec</a> <span class="q">'tr'</span><span class="cm">,</span> <span class="q">'[a-z]'</span><span class="cm">,</span> <span class="q">'[A-Z]'</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'|-'</span><span class="cm">,</span> <span class="q">"tr"</span><span class="cm">,</span> <span class="q">'[a-z]'</span><span class="cm">,</span> <span class="q">'[A-Z]'</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">"cat -n '$file'|"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'-|'</span><span class="cm">,</span> <span class="q">"cat -n '$file'"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'-|'</span><span class="s">)</span> || <a class="l_k" href="../functions/exec.html">exec</a> <span class="q">'cat'</span><span class="cm">,</span> <span class="q">'-n'</span><span class="cm">,</span> <span class="i">$file</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'-|'</span><span class="cm">,</span> <span class="q">"cat"</span><span class="cm">,</span> <span class="q">'-n'</span><span class="cm">,</span> <span class="i">$file</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The last example in each block shows the pipe as "list form", which is<br>
not yet supported on all platforms. A good rule of thumb is that if<br>
your platform has true <code class="inline"><a class="l_k" href="../functions/fork.html">fork()</a></code> (in other words, if your platform is<br>
UNIX) you can use the list form.</p>
<p>See <a href="../perlipc.html#Safe-Pipe-Opens">"Safe Pipe Opens" in perlipc</a> for more examples of this.</p>
<p>Beginning with v5.6.0, Perl will attempt to flush all files opened for<br>
output before any operation that may do a fork, but this may not be<br>
supported on some platforms (see <a href="../perlport.html">perlport</a>). To be safe, you may need<br>
to set <code class="inline"><span class="i">$|</span></code>
($AUTOFLUSH in English) or call the <code class="inline"><span class="i">autoflush</span><span class="s">(</span><span class="s">)</span></code>
method<br>
of <code class="inline"><span class="w">IO::Handle</span></code>
on any open handles.</p>
<p>On systems that support a close-on-exec flag on files, the flag will<br>
be set for the newly opened file descriptor as determined by the value<br>
of $^F. See <a href="../perlvar.html#%24%5eF">"$^F" in perlvar</a>.</p>
<p>Closing any piped filehandle causes the parent process to wait for the<br>
child to finish, and returns the status value in <code class="inline"><span class="i">$?</span></code>
and<br>
<code class="inline"><span class="i">$</span>{<span class="w">^CHILD_ERROR_NATIVE</span>}</code>
.</p>
<p>The filename passed to 2-argument (or 1-argument) form of open() will<br>
have leading and trailing whitespace deleted, and the normal<br>
redirection characters honored. This property, known as "magic open",<br>
can often be used to good effect. A user could specify a filename of<br>
<i>"rsh cat file |"</i>, or you could change certain filenames as needed:</p>
<pre class="verbatim"><ol><li> <span class="i">$filename</span> =~ <span class="q">s/(.*\.gz)\s*$/gzip -dc < $1|/</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FH</span><span class="cm">,</span> <span class="i">$filename</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't open $filename: $!"</span><span class="sc">;</span></li></ol></pre><p>Use 3-argument form to open a file with arbitrary weird characters in it,</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'<'</span><span class="cm">,</span> <span class="i">$file</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>otherwise it's necessary to protect any leading and trailing whitespace:</p>
<pre class="verbatim"><ol><li> <span class="i">$file</span> =~ <span class="q">s#^(\s)#./$1#</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">"< $file\0"</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>(this may not work on some bizarre filesystems). One should<br>
conscientiously choose between the <i>magic</i> and 3-arguments form<br>
of open():</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">IN</span><span class="cm">,</span> <span class="i">$ARGV</span>[<span class="n">0</span>]<span class="sc">;</span></li></ol></pre><p>will allow the user to specify an argument of the form <code class="inline"><span class="q">"rsh cat file |"</span></code>
,<br>
but will not work on a filename which happens to have a trailing space, while</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">IN</span><span class="cm">,</span> <span class="q">'<'</span><span class="cm">,</span> <span class="i">$ARGV</span>[<span class="n">0</span>]<span class="sc">;</span></li></ol></pre><p>will have exactly the opposite restrictions.</p>
<p>If you want a "real" C <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> (see <code class="inline"><a class="l_k" href="../functions/open.html">open(2)</a></code> on your system), then you<br>
should use the <code class="inline"><a class="l_k" href="../functions/sysopen.html">sysopen</a></code> function, which involves no such magic (but<br>
may use subtly different filemodes than Perl open(), which is mapped<br>
to C fopen()). This is<br>
another way to protect your filenames from interpretation. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">IO::Handle</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/sysopen.html">sysopen</a><span class="s">(</span><span class="w">HANDLE</span><span class="cm">,</span> <span class="i">$path</span><span class="cm">,</span> <span class="w">O_RDWR</span>|<span class="w">O_CREAT</span>|<span class="w">O_EXCL</span><span class="s">)</span></li><li> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"sysopen $path: $!"</span><span class="sc">;</span></li><li> <span class="i">$oldfh</span> = <a class="l_k" href="../functions/select.html">select</a><span class="s">(</span><span class="w">HANDLE</span><span class="s">)</span><span class="sc">;</span> <span class="i">$|</span> = <span class="n">1</span><span class="sc">;</span> <a class="l_k" href="../functions/select.html">select</a><span class="s">(</span><span class="i">$oldfh</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">HANDLE</span> <span class="q">"stuff $$\n"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/seek.html">seek</a><span class="s">(</span><span class="w">HANDLE</span><span class="cm">,</span> <span class="n">0</span><span class="cm">,</span> <span class="n">0</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"File contains: "</span><span class="cm">,</span> <span class="q"><HANDLE></span><span class="sc">;</span></li></ol></pre><p>Using the constructor from the <code class="inline"><span class="w">IO::Handle</span></code>
package (or one of its<br>
subclasses, such as <code class="inline"><span class="w">IO::File</span></code>
or <code class="inline"><span class="w">IO::Socket</span></code>
), you can generate anonymous<br>
filehandles that have the scope of whatever variables hold references to<br>
them, and automatically close whenever and however you leave that scope:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">IO::File</span><span class="sc">;</span></li><li> <span class="c">#...</span></li><li><a name="read_myfile_munged"></a> sub <span class="m">read_myfile_munged</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$ALL</span> = <a class="l_k" href="../functions/shift.html">shift</a><span class="sc">;</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$handle</span> = <span class="w">IO::File</span><span class="w">->new</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="i">$handle</span><span class="cm">,</span> <span class="q">"myfile"</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"myfile: $!"</span><span class="sc">;</span></li><li> <span class="i">$first</span> = <span class="q"><$handle></span></li><li> or <a class="l_k" href="../functions/return.html">return</a> <span class="s">(</span><span class="s">)</span><span class="sc">;</span> <span class="c"># Automatically closed here.</span></li><li> <span class="w">mung</span> <span class="i">$first</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"mung failed"</span><span class="sc">;</span> <span class="c"># Or here.</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <span class="i">$first</span><span class="cm">,</span> <span class="q"><$handle></span> if <span class="i">$ALL</span><span class="sc">;</span> <span class="c"># Or here.</span></li><li> <span class="i">$first</span><span class="sc">;</span> <span class="c"># Or here.</span></li><li> <span class="s">}</span></li></ol></pre><p>See <a href="../functions/seek.html">"seek"</a> for some details about mixing reading and writing.]]></desc>
</keyword>
<keyword name="open" type="function">
<params>
<param name='filehandle'/>
<param name='mode'/>
<param name='expr'/>
</params>
<desc><![CDATA[Opens the file whose filename is given by EXPR, and associates it with<br>
FILEHANDLE.</p>
<p>Simple examples to open a file for reading:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$fh</span><span class="cm">,</span> <span class="q">'<'</span><span class="cm">,</span> <span class="q">"input.txt"</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="i">$!</span><span class="sc">;</span></li></ol></pre><p>and for writing:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$fh</span><span class="cm">,</span> <span class="q">'>'</span><span class="cm">,</span> <span class="q">"output.txt"</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="i">$!</span><span class="sc">;</span></li></ol></pre><p>(The following is a comprehensive reference to open(): for a gentler<br>
introduction you may consider <a href="../perlopentut.html">perlopentut</a>.)</p>
<p>If FILEHANDLE is an undefined scalar variable (or array or hash element)<br>
the variable is assigned a reference to a new anonymous filehandle,<br>
otherwise if FILEHANDLE is an expression, its value is used as the name of<br>
the real filehandle wanted. (This is considered a symbolic reference, so<br>
<code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">strict</span> <span class="q">'refs'</span></code>
should <i>not</i> be in effect.)</p>
<p>If EXPR is omitted, the scalar variable of the same name as the<br>
FILEHANDLE contains the filename. (Note that lexical variables--those<br>
declared with <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code>--will not work for this purpose; so if you're<br>
using <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code>, specify EXPR in your call to open.)</p>
<p>If three or more arguments are specified then the mode of opening and<br>
the file name are separate. If MODE is <code class="inline"><span class="q">'<'</span></code>
or nothing, the file<br>
is opened for input. If MODE is <code class="inline"><span class="q">'>'</span></code>
, the file is truncated and<br>
opened for output, being created if necessary. If MODE is <code class="inline"><span class="q">'>>'</span></code>
,<br>
the file is opened for appending, again being created if necessary.</p>
<p>You can put a <code class="inline"><span class="q">'+'</span></code>
in front of the <code class="inline"><span class="q">'>'</span></code>
or <code class="inline"><span class="q">'<'</span></code>
to<br>
indicate that you want both read and write access to the file; thus<br>
<code class="inline"><span class="q">'+<'</span></code>
is almost always preferred for read/write updates--the <code class="inline"><span class="q">'+>'</span></code>
mode would clobber the file first. You can't usually use<br>
either read-write mode for updating textfiles, since they have<br>
variable length records. See the <b>-i</b> switch in <a href="../perlrun.html">perlrun</a> for a<br>
better approach. The file is created with permissions of <code class="inline"><span class="n">0666</span></code>
<br>
modified by the process' <code class="inline"><a class="l_k" href="../functions/umask.html">umask</a></code> value.</p>
<p>These various prefixes correspond to the fopen(3) modes of <code class="inline"><span class="q">'r'</span></code>
,<br>
<code class="inline"><span class="q">'r+'</span></code>
, <code class="inline"><span class="q">'w'</span></code>
, <code class="inline"><span class="q">'w+'</span></code>
, <code class="inline"><span class="q">'a'</span></code>
, and <code class="inline"><span class="q">'a+'</span></code>
.</p>
<p>In the 2-arguments (and 1-argument) form of the call the mode and<br>
filename should be concatenated (in this order), possibly separated by<br>
spaces. It is possible to omit the mode in these forms if the mode is<br>
<code class="inline"><span class="q">'<'</span></code>
.</p>
<p>If the filename begins with <code class="inline"><span class="q">'|'</span></code>
, the filename is interpreted as a<br>
command to which output is to be piped, and if the filename ends with a<br>
<code class="inline"><span class="q">'|'</span></code>
, the filename is interpreted as a command which pipes output to<br>
us. See <a href="../perlipc.html#Using-open()-for-IPC">"Using open() for IPC" in perlipc</a>
for more examples of this. (You are not allowed to <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> to a command<br>
that pipes both in <i>and</i> out, but see <a href="../IPC/Open2.html">IPC::Open2</a>, <a href="../IPC/Open3.html">IPC::Open3</a>,<br>
and <a href="../perlipc.html#Bidirectional-Communication-with-Another-Process">"Bidirectional Communication with Another Process" in perlipc</a>
for alternatives.)</p>
<p>For three or more arguments if MODE is <code class="inline"><span class="q">'|-'</span></code>
, the filename is<br>
interpreted as a command to which output is to be piped, and if MODE<br>
is <code class="inline"><span class="q">'-|'</span></code>
, the filename is interpreted as a command which pipes<br>
output to us. In the 2-arguments (and 1-argument) form one should<br>
replace dash (<code class="inline"><span class="q">'-'</span></code>
) with the command.<br>
See <a href="../perlipc.html#Using-open()-for-IPC">"Using open() for IPC" in perlipc</a> for more examples of this.<br>
(You are not allowed to <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> to a command that pipes both in <i>and</i>
out, but see <a href="../IPC/Open2.html">IPC::Open2</a>, <a href="../IPC/Open3.html">IPC::Open3</a>, and<br>
<a href="../perlipc.html#Bidirectional-Communication">"Bidirectional Communication" in perlipc</a> for alternatives.)</p>
<p>In the three-or-more argument form of pipe opens, if LIST is specified<br>
(extra arguments after the command name) then LIST becomes arguments<br>
to the command invoked if the platform supports it. The meaning of<br>
<code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> with more than three arguments for non-pipe modes is not yet<br>
specified. Experimental "layers" may give extra LIST arguments<br>
meaning.</p>
<p>In the 2-arguments (and 1-argument) form opening <code class="inline"><span class="q">'-'</span></code>
opens STDIN<br>
and opening <code class="inline"><span class="q">'>-'</span></code>
opens STDOUT.</p>
<p>You may use the three-argument form of open to specify IO "layers"<br>
(sometimes also referred to as "disciplines") to be applied to the handle<br>
that affect how the input and output are processed (see <a href="../open.html">open</a> and<br>
<a href="../PerlIO.html">PerlIO</a> for more details). For example</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$fh</span><span class="cm">,</span> <span class="q">"<:encoding(UTF-8)"</span><span class="cm">,</span> <span class="q">"file"</span><span class="s">)</span></li></ol></pre><p>will open the UTF-8 encoded file containing Unicode characters,<br>
see <a href="../perluniintro.html">perluniintro</a>. Note that if layers are specified in the<br>
three-arg form then default layers stored in ${^OPEN} (see <a href="../perlvar.html">perlvar</a>;<br>
usually set by the <b>open</b> pragma or the switch <b>-CioD</b>) are ignored.</p>
<p>Open returns nonzero upon success, the undefined value otherwise. If<br>
the <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> involved a pipe, the return value happens to be the pid of<br>
the subprocess.</p>
<p>If you're running Perl on a system that distinguishes between text<br>
files and binary files, then you should check out <a href="../functions/binmode.html">"binmode"</a> for tips<br>
for dealing with this. The key distinction between systems that need<br>
<code class="inline"><a class="l_k" href="../functions/binmode.html">binmode</a></code> and those that don't is their text file formats. Systems<br>
like Unix, Mac OS, and Plan 9, which delimit lines with a single<br>
character, and which encode that character in C as <code class="inline"><span class="q">"\n"</span></code>
, do not<br>
need <code class="inline"><a class="l_k" href="../functions/binmode.html">binmode</a></code>. The rest need it.</p>
<p>When opening a file, it's usually a bad idea to continue normal execution<br>
if the request failed, so <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> is frequently used in connection with<br>
<code class="inline"><a class="l_k" href="../functions/die.html">die</a></code>. Even if <code class="inline"><a class="l_k" href="../functions/die.html">die</a></code> won't do what you want (say, in a CGI script,<br>
where you want to make a nicely formatted error message (but there are<br>
modules that can help with that problem)) you should always check<br>
the return value from opening a file. The infrequent exception is when<br>
working with an unopened filehandle is actually what you want to do.</p>
<p>As a special case the 3-arg form with a read/write mode and the third<br>
argument being <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code>:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$tmp</span><span class="cm">,</span> <span class="q">"+>"</span><span class="cm">,</span> <a class="l_k" href="../functions/undef.html">undef</a><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> ...</li></ol></pre><p>opens a filehandle to an anonymous temporary file. Also using "+<"<br>
works for symmetry, but you really should consider writing something<br>
to the temporary file first. You will need to seek() to do the<br>
reading.</p>
<p>Since v5.8.0, perl has built using PerlIO by default. Unless you've<br>
changed this (i.e. Configure -Uuseperlio), you can open file handles to<br>
"in memory" files held in Perl scalars via:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="i">$fh</span><span class="cm">,</span> <span class="q">'>'</span><span class="cm">,</span> \<span class="i">$variable</span><span class="s">)</span> || ..</li></ol></pre><p>Though if you try to re-open <code class="inline"><span class="w">STDOUT</span></code>
or <code class="inline"><span class="w">STDERR</span></code>
as an "in memory"<br>
file, you have to close it first:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/close.html">close</a> <span class="w">STDOUT</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDOUT</span><span class="cm">,</span> <span class="q">'>'</span><span class="cm">,</span> \<span class="i">$variable</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't open STDOUT: $!"</span><span class="sc">;</span></li></ol></pre><p>Examples:</p>
<pre class="verbatim"><ol><li> $ARTICLE = 100;</li><li> open ARTICLE or die "Can't find article $ARTICLE: $!\n";</li><li> while (<ARTICLE>) {...</li><li></li><li> open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved)</li><li> # if the open fails, output is discarded</li><li></li><li> open(my $dbase, '+<', 'dbase.mine') # open for update</li><li> or die "Can't open 'dbase.mine' for update: $!";</li><li></li><li> open(my $dbase, '+<dbase.mine') # ditto</li><li> or die "Can't open 'dbase.mine' for update: $!";</li><li></li><li> open(ARTICLE, '-|', "caesar <$article") # decrypt article</li><li> or die "Can't start caesar: $!";</li><li></li><li> open(ARTICLE, "caesar <$article |") # ditto</li><li> or die "Can't start caesar: $!";</li><li></li><li> open(EXTRACT, "|sort >Tmp$$") # $$ is our process id</li><li> or die "Can't start sort: $!";</li><li></li><li> # in memory files</li><li> open(MEMORY,'>', \$var)</li><li> or die "Can't open memory file: $!";</li><li> print MEMORY "foo!\n"; # output will end up in $var</li><li></li><li> # process argument list of files along with any includes</li><li></li><li> foreach $file (@ARGV) {</li><li> process($file, 'fh00');</li><li> }</li><li></li><li> sub process {</li><li> my($filename, $input) = @_;</li><li> $input++; # this is a string increment</li><li> unless (open($input, $filename)) {</li><li> print STDERR "Can't open $filename: $!\n";</li><li> return;</li><li> }</li><li></li><li> local $_;</li><li> while (<$input>) { # note use of indirection</li><li> if (/^#include "(.*)"/) {</li><li> process($1, $input);</li><li> next;</li><li> }</li><li> #... # whatever</li><li> }</li><li> }</li></ol></pre><p>See <a href="../perliol.html">perliol</a> for detailed info on PerlIO.</p>
<p>You may also, in the Bourne shell tradition, specify an EXPR beginning<br>
with <code class="inline"><span class="q">'>&'</span></code>
, in which case the rest of the string is interpreted<br>
as the name of a filehandle (or file descriptor, if numeric) to be<br>
duped (as <code class="inline"><span class="i">dup</span><span class="s">(</span><span class="n">2</span><span class="s">)</span></code>
) and opened. You may use <code class="inline"><span class="i">&</span></code>
after <code class="inline">></code>,<br>
<code class="inline">>></code>
, <code class="inline"><</code>
, <code class="inline">+></code>, <code class="inline">+>></code>
, and <code class="inline">+<</code>
.<br>
The mode you specify should match the mode of the original filehandle.<br>
(Duping a filehandle does not take into account any existing contents<br>
of IO buffers.) If you use the 3-arg form then you can pass either a<br>
number, the name of a filehandle or the normal "reference to a glob".</p>
<p>Here is a script that saves, redirects, and restores <code class="inline"><span class="w">STDOUT</span></code>
and<br>
<code class="inline"><span class="w">STDERR</span></code>
using various methods:</p>
<pre class="verbatim"><ol><li> <span class="c">#!/usr/bin/perl</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$oldout</span><span class="cm">,</span> <span class="q">">&STDOUT"</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup STDOUT: $!"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">OLDERR</span><span class="cm">,</span> <span class="q">">&"</span><span class="cm">,</span> \<span class="i">*STDERR</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup STDERR: $!"</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDOUT</span><span class="cm">,</span> <span class="q">'>'</span><span class="cm">,</span> <span class="q">"foo.out"</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't redirect STDOUT: $!"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDERR</span><span class="cm">,</span> <span class="q">">&STDOUT"</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup STDOUT: $!"</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/select.html">select</a> <span class="w">STDERR</span><span class="sc">;</span> <span class="i">$|</span> = <span class="n">1</span><span class="sc">;</span> <span class="c"># make unbuffered</span></li><li> <a class="l_k" href="../functions/select.html">select</a> <span class="w">STDOUT</span><span class="sc">;</span> <span class="i">$|</span> = <span class="n">1</span><span class="sc">;</span> <span class="c"># make unbuffered</span></li><li></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDOUT</span> <span class="q">"stdout 1\n"</span><span class="sc">;</span> <span class="c"># this works for</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDERR</span> <span class="q">"stderr 1\n"</span><span class="sc">;</span> <span class="c"># subprocesses too</span></li><li></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDOUT</span><span class="cm">,</span> <span class="q">">&"</span><span class="cm">,</span> <span class="i">$oldout</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup \$oldout: $!"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDERR</span><span class="cm">,</span> <span class="q">">&OLDERR"</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup OLDERR: $!"</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDOUT</span> <span class="q">"stdout 2\n"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDERR</span> <span class="q">"stderr 2\n"</span><span class="sc">;</span></li></ol></pre><p>If you specify <code class="inline"><span class="q">'<&=X'</span></code>
, where <code class="inline"><span class="w">X</span></code>
is a file descriptor number<br>
or a filehandle, then Perl will do an equivalent of C's <code class="inline"><span class="w">fdopen</span></code>
of<br>
that file descriptor (and not call <code class="inline"><span class="i">dup</span><span class="s">(</span><span class="n">2</span><span class="s">)</span></code>
); this is more<br>
parsimonious of file descriptors. For example:</p>
<pre class="verbatim"><ol><li> <span class="c"># open for input, reusing the fileno of $fd</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FILEHANDLE</span><span class="cm">,</span> <span class="q">"<&=$fd"</span><span class="s">)</span></li></ol></pre><p>or</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FILEHANDLE</span><span class="cm">,</span> <span class="q">"<&="</span><span class="cm">,</span> <span class="i">$fd</span><span class="s">)</span></li></ol></pre><p>or</p>
<pre class="verbatim"><ol><li> <span class="c"># open for append, using the fileno of OLDFH</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FH</span><span class="cm">,</span> <span class="q">">>&="</span><span class="cm">,</span> <span class="w">OLDFH</span><span class="s">)</span></li></ol></pre><p>or</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FH</span><span class="cm">,</span> <span class="q">">>&=OLDFH"</span><span class="s">)</span></li></ol></pre><p>Being parsimonious on filehandles is also useful (besides being<br>
parsimonious) for example when something is dependent on file<br>
descriptors, like for example locking using flock(). If you do just<br>
<code class="inline"><a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">A</span><span class="cm">,</span> <span class="q">'>>&B'</span><span class="s">)</span></code>
, the filehandle A will not have the same file<br>
descriptor as B, and therefore flock(A) will not flock(B), and vice<br>
versa. But with <code class="inline"><a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">A</span><span class="cm">,</span> <span class="q">'>>&=B'</span><span class="s">)</span></code>
the filehandles will share<br>
the same file descriptor.</p>
<p>Note that if you are using Perls older than 5.8.0, Perl will be using<br>
the standard C libraries' fdopen() to implement the "=" functionality.<br>
On many UNIX systems fdopen() fails when file descriptors exceed a<br>
certain value, typically 255. For Perls 5.8.0 and later, PerlIO is<br>
most often the default.</p>
<p>You can see whether Perl has been compiled with PerlIO or not by<br>
running <code class="inline"><span class="w">perl</span> -<span class="w">V</span></code>
and looking for <code class="inline"><span class="w">useperlio</span>=</code>
line. If <code class="inline"><span class="w">useperlio</span></code>
<br>
is <code class="inline"><span class="w">define</span></code>
, you have PerlIO, otherwise you don't.</p>
<p>If you open a pipe on the command <code class="inline"><span class="q">'-'</span></code>
, i.e., either <code class="inline"><span class="q">'|-'</span></code>
or <code class="inline"><span class="q">'-|'</span></code>
<br>
with 2-arguments (or 1-argument) form of open(), then<br>
there is an implicit fork done, and the return value of open is the pid<br>
of the child within the parent process, and <code class="inline"><span class="n">0</span></code>
within the child<br>
process. (Use <code class="inline"><a class="l_k" href="../functions/defined.html">defined($pid)</a></code> to determine whether the open was successful.)<br>
The filehandle behaves normally for the parent, but i/o to that<br>
filehandle is piped from/to the STDOUT/STDIN of the child process.<br>
In the child process the filehandle isn't opened--i/o happens from/to<br>
the new STDOUT or STDIN. Typically this is used like the normal<br>
piped open when you want to exercise more control over just how the<br>
pipe command gets executed, such as when you are running setuid, and<br>
don't want to have to scan shell commands for metacharacters.<br>
The following triples are more or less equivalent:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">"|tr '[a-z]' '[A-Z]'"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'|-'</span><span class="cm">,</span> <span class="q">"tr '[a-z]' '[A-Z]'"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'|-'</span><span class="s">)</span> || <a class="l_k" href="../functions/exec.html">exec</a> <span class="q">'tr'</span><span class="cm">,</span> <span class="q">'[a-z]'</span><span class="cm">,</span> <span class="q">'[A-Z]'</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'|-'</span><span class="cm">,</span> <span class="q">"tr"</span><span class="cm">,</span> <span class="q">'[a-z]'</span><span class="cm">,</span> <span class="q">'[A-Z]'</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">"cat -n '$file'|"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'-|'</span><span class="cm">,</span> <span class="q">"cat -n '$file'"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'-|'</span><span class="s">)</span> || <a class="l_k" href="../functions/exec.html">exec</a> <span class="q">'cat'</span><span class="cm">,</span> <span class="q">'-n'</span><span class="cm">,</span> <span class="i">$file</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'-|'</span><span class="cm">,</span> <span class="q">"cat"</span><span class="cm">,</span> <span class="q">'-n'</span><span class="cm">,</span> <span class="i">$file</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The last example in each block shows the pipe as "list form", which is<br>
not yet supported on all platforms. A good rule of thumb is that if<br>
your platform has true <code class="inline"><a class="l_k" href="../functions/fork.html">fork()</a></code> (in other words, if your platform is<br>
UNIX) you can use the list form.</p>
<p>See <a href="../perlipc.html#Safe-Pipe-Opens">"Safe Pipe Opens" in perlipc</a> for more examples of this.</p>
<p>Beginning with v5.6.0, Perl will attempt to flush all files opened for<br>
output before any operation that may do a fork, but this may not be<br>
supported on some platforms (see <a href="../perlport.html">perlport</a>). To be safe, you may need<br>
to set <code class="inline"><span class="i">$|</span></code>
($AUTOFLUSH in English) or call the <code class="inline"><span class="i">autoflush</span><span class="s">(</span><span class="s">)</span></code>
method<br>
of <code class="inline"><span class="w">IO::Handle</span></code>
on any open handles.</p>
<p>On systems that support a close-on-exec flag on files, the flag will<br>
be set for the newly opened file descriptor as determined by the value<br>
of $^F. See <a href="../perlvar.html#%24%5eF">"$^F" in perlvar</a>.</p>
<p>Closing any piped filehandle causes the parent process to wait for the<br>
child to finish, and returns the status value in <code class="inline"><span class="i">$?</span></code>
and<br>
<code class="inline"><span class="i">$</span>{<span class="w">^CHILD_ERROR_NATIVE</span>}</code>
.</p>
<p>The filename passed to 2-argument (or 1-argument) form of open() will<br>
have leading and trailing whitespace deleted, and the normal<br>
redirection characters honored. This property, known as "magic open",<br>
can often be used to good effect. A user could specify a filename of<br>
<i>"rsh cat file |"</i>, or you could change certain filenames as needed:</p>
<pre class="verbatim"><ol><li> <span class="i">$filename</span> =~ <span class="q">s/(.*\.gz)\s*$/gzip -dc < $1|/</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FH</span><span class="cm">,</span> <span class="i">$filename</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't open $filename: $!"</span><span class="sc">;</span></li></ol></pre><p>Use 3-argument form to open a file with arbitrary weird characters in it,</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'<'</span><span class="cm">,</span> <span class="i">$file</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>otherwise it's necessary to protect any leading and trailing whitespace:</p>
<pre class="verbatim"><ol><li> <span class="i">$file</span> =~ <span class="q">s#^(\s)#./$1#</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">"< $file\0"</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>(this may not work on some bizarre filesystems). One should<br>
conscientiously choose between the <i>magic</i> and 3-arguments form<br>
of open():</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">IN</span><span class="cm">,</span> <span class="i">$ARGV</span>[<span class="n">0</span>]<span class="sc">;</span></li></ol></pre><p>will allow the user to specify an argument of the form <code class="inline"><span class="q">"rsh cat file |"</span></code>
,<br>
but will not work on a filename which happens to have a trailing space, while</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">IN</span><span class="cm">,</span> <span class="q">'<'</span><span class="cm">,</span> <span class="i">$ARGV</span>[<span class="n">0</span>]<span class="sc">;</span></li></ol></pre><p>will have exactly the opposite restrictions.</p>
<p>If you want a "real" C <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> (see <code class="inline"><a class="l_k" href="../functions/open.html">open(2)</a></code> on your system), then you<br>
should use the <code class="inline"><a class="l_k" href="../functions/sysopen.html">sysopen</a></code> function, which involves no such magic (but<br>
may use subtly different filemodes than Perl open(), which is mapped<br>
to C fopen()). This is<br>
another way to protect your filenames from interpretation. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">IO::Handle</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/sysopen.html">sysopen</a><span class="s">(</span><span class="w">HANDLE</span><span class="cm">,</span> <span class="i">$path</span><span class="cm">,</span> <span class="w">O_RDWR</span>|<span class="w">O_CREAT</span>|<span class="w">O_EXCL</span><span class="s">)</span></li><li> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"sysopen $path: $!"</span><span class="sc">;</span></li><li> <span class="i">$oldfh</span> = <a class="l_k" href="../functions/select.html">select</a><span class="s">(</span><span class="w">HANDLE</span><span class="s">)</span><span class="sc">;</span> <span class="i">$|</span> = <span class="n">1</span><span class="sc">;</span> <a class="l_k" href="../functions/select.html">select</a><span class="s">(</span><span class="i">$oldfh</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">HANDLE</span> <span class="q">"stuff $$\n"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/seek.html">seek</a><span class="s">(</span><span class="w">HANDLE</span><span class="cm">,</span> <span class="n">0</span><span class="cm">,</span> <span class="n">0</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"File contains: "</span><span class="cm">,</span> <span class="q"><HANDLE></span><span class="sc">;</span></li></ol></pre><p>Using the constructor from the <code class="inline"><span class="w">IO::Handle</span></code>
package (or one of its<br>
subclasses, such as <code class="inline"><span class="w">IO::File</span></code>
or <code class="inline"><span class="w">IO::Socket</span></code>
), you can generate anonymous<br>
filehandles that have the scope of whatever variables hold references to<br>
them, and automatically close whenever and however you leave that scope:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">IO::File</span><span class="sc">;</span></li><li> <span class="c">#...</span></li><li><a name="read_myfile_munged"></a> sub <span class="m">read_myfile_munged</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$ALL</span> = <a class="l_k" href="../functions/shift.html">shift</a><span class="sc">;</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$handle</span> = <span class="w">IO::File</span><span class="w">->new</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="i">$handle</span><span class="cm">,</span> <span class="q">"myfile"</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"myfile: $!"</span><span class="sc">;</span></li><li> <span class="i">$first</span> = <span class="q"><$handle></span></li><li> or <a class="l_k" href="../functions/return.html">return</a> <span class="s">(</span><span class="s">)</span><span class="sc">;</span> <span class="c"># Automatically closed here.</span></li><li> <span class="w">mung</span> <span class="i">$first</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"mung failed"</span><span class="sc">;</span> <span class="c"># Or here.</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <span class="i">$first</span><span class="cm">,</span> <span class="q"><$handle></span> if <span class="i">$ALL</span><span class="sc">;</span> <span class="c"># Or here.</span></li><li> <span class="i">$first</span><span class="sc">;</span> <span class="c"># Or here.</span></li><li> <span class="s">}</span></li></ol></pre><p>See <a href="../functions/seek.html">"seek"</a> for some details about mixing reading and writing.]]></desc>
</keyword>
<keyword name="open" type="function">
<params>
<param name='filehandle'/>
<param name='mode'/>
<param name='reference'/>
</params>
<desc><![CDATA[Opens the file whose filename is given by EXPR, and associates it with<br>
FILEHANDLE.</p>
<p>Simple examples to open a file for reading:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$fh</span><span class="cm">,</span> <span class="q">'<'</span><span class="cm">,</span> <span class="q">"input.txt"</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="i">$!</span><span class="sc">;</span></li></ol></pre><p>and for writing:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$fh</span><span class="cm">,</span> <span class="q">'>'</span><span class="cm">,</span> <span class="q">"output.txt"</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="i">$!</span><span class="sc">;</span></li></ol></pre><p>(The following is a comprehensive reference to open(): for a gentler<br>
introduction you may consider <a href="../perlopentut.html">perlopentut</a>.)</p>
<p>If FILEHANDLE is an undefined scalar variable (or array or hash element)<br>
the variable is assigned a reference to a new anonymous filehandle,<br>
otherwise if FILEHANDLE is an expression, its value is used as the name of<br>
the real filehandle wanted. (This is considered a symbolic reference, so<br>
<code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">strict</span> <span class="q">'refs'</span></code>
should <i>not</i> be in effect.)</p>
<p>If EXPR is omitted, the scalar variable of the same name as the<br>
FILEHANDLE contains the filename. (Note that lexical variables--those<br>
declared with <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code>--will not work for this purpose; so if you're<br>
using <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code>, specify EXPR in your call to open.)</p>
<p>If three or more arguments are specified then the mode of opening and<br>
the file name are separate. If MODE is <code class="inline"><span class="q">'<'</span></code>
or nothing, the file<br>
is opened for input. If MODE is <code class="inline"><span class="q">'>'</span></code>
, the file is truncated and<br>
opened for output, being created if necessary. If MODE is <code class="inline"><span class="q">'>>'</span></code>
,<br>
the file is opened for appending, again being created if necessary.</p>
<p>You can put a <code class="inline"><span class="q">'+'</span></code>
in front of the <code class="inline"><span class="q">'>'</span></code>
or <code class="inline"><span class="q">'<'</span></code>
to<br>
indicate that you want both read and write access to the file; thus<br>
<code class="inline"><span class="q">'+<'</span></code>
is almost always preferred for read/write updates--the <code class="inline"><span class="q">'+>'</span></code>
mode would clobber the file first. You can't usually use<br>
either read-write mode for updating textfiles, since they have<br>
variable length records. See the <b>-i</b> switch in <a href="../perlrun.html">perlrun</a> for a<br>
better approach. The file is created with permissions of <code class="inline"><span class="n">0666</span></code>
<br>
modified by the process' <code class="inline"><a class="l_k" href="../functions/umask.html">umask</a></code> value.</p>
<p>These various prefixes correspond to the fopen(3) modes of <code class="inline"><span class="q">'r'</span></code>
,<br>
<code class="inline"><span class="q">'r+'</span></code>
, <code class="inline"><span class="q">'w'</span></code>
, <code class="inline"><span class="q">'w+'</span></code>
, <code class="inline"><span class="q">'a'</span></code>
, and <code class="inline"><span class="q">'a+'</span></code>
.</p>
<p>In the 2-arguments (and 1-argument) form of the call the mode and<br>
filename should be concatenated (in this order), possibly separated by<br>
spaces. It is possible to omit the mode in these forms if the mode is<br>
<code class="inline"><span class="q">'<'</span></code>
.</p>
<p>If the filename begins with <code class="inline"><span class="q">'|'</span></code>
, the filename is interpreted as a<br>
command to which output is to be piped, and if the filename ends with a<br>
<code class="inline"><span class="q">'|'</span></code>
, the filename is interpreted as a command which pipes output to<br>
us. See <a href="../perlipc.html#Using-open()-for-IPC">"Using open() for IPC" in perlipc</a>
for more examples of this. (You are not allowed to <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> to a command<br>
that pipes both in <i>and</i> out, but see <a href="../IPC/Open2.html">IPC::Open2</a>, <a href="../IPC/Open3.html">IPC::Open3</a>,<br>
and <a href="../perlipc.html#Bidirectional-Communication-with-Another-Process">"Bidirectional Communication with Another Process" in perlipc</a>
for alternatives.)</p>
<p>For three or more arguments if MODE is <code class="inline"><span class="q">'|-'</span></code>
, the filename is<br>
interpreted as a command to which output is to be piped, and if MODE<br>
is <code class="inline"><span class="q">'-|'</span></code>
, the filename is interpreted as a command which pipes<br>
output to us. In the 2-arguments (and 1-argument) form one should<br>
replace dash (<code class="inline"><span class="q">'-'</span></code>
) with the command.<br>
See <a href="../perlipc.html#Using-open()-for-IPC">"Using open() for IPC" in perlipc</a> for more examples of this.<br>
(You are not allowed to <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> to a command that pipes both in <i>and</i>
out, but see <a href="../IPC/Open2.html">IPC::Open2</a>, <a href="../IPC/Open3.html">IPC::Open3</a>, and<br>
<a href="../perlipc.html#Bidirectional-Communication">"Bidirectional Communication" in perlipc</a> for alternatives.)</p>
<p>In the three-or-more argument form of pipe opens, if LIST is specified<br>
(extra arguments after the command name) then LIST becomes arguments<br>
to the command invoked if the platform supports it. The meaning of<br>
<code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> with more than three arguments for non-pipe modes is not yet<br>
specified. Experimental "layers" may give extra LIST arguments<br>
meaning.</p>
<p>In the 2-arguments (and 1-argument) form opening <code class="inline"><span class="q">'-'</span></code>
opens STDIN<br>
and opening <code class="inline"><span class="q">'>-'</span></code>
opens STDOUT.</p>
<p>You may use the three-argument form of open to specify IO "layers"<br>
(sometimes also referred to as "disciplines") to be applied to the handle<br>
that affect how the input and output are processed (see <a href="../open.html">open</a> and<br>
<a href="../PerlIO.html">PerlIO</a> for more details). For example</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$fh</span><span class="cm">,</span> <span class="q">"<:encoding(UTF-8)"</span><span class="cm">,</span> <span class="q">"file"</span><span class="s">)</span></li></ol></pre><p>will open the UTF-8 encoded file containing Unicode characters,<br>
see <a href="../perluniintro.html">perluniintro</a>. Note that if layers are specified in the<br>
three-arg form then default layers stored in ${^OPEN} (see <a href="../perlvar.html">perlvar</a>;<br>
usually set by the <b>open</b> pragma or the switch <b>-CioD</b>) are ignored.</p>
<p>Open returns nonzero upon success, the undefined value otherwise. If<br>
the <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> involved a pipe, the return value happens to be the pid of<br>
the subprocess.</p>
<p>If you're running Perl on a system that distinguishes between text<br>
files and binary files, then you should check out <a href="../functions/binmode.html">"binmode"</a> for tips<br>
for dealing with this. The key distinction between systems that need<br>
<code class="inline"><a class="l_k" href="../functions/binmode.html">binmode</a></code> and those that don't is their text file formats. Systems<br>
like Unix, Mac OS, and Plan 9, which delimit lines with a single<br>
character, and which encode that character in C as <code class="inline"><span class="q">"\n"</span></code>
, do not<br>
need <code class="inline"><a class="l_k" href="../functions/binmode.html">binmode</a></code>. The rest need it.</p>
<p>When opening a file, it's usually a bad idea to continue normal execution<br>
if the request failed, so <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> is frequently used in connection with<br>
<code class="inline"><a class="l_k" href="../functions/die.html">die</a></code>. Even if <code class="inline"><a class="l_k" href="../functions/die.html">die</a></code> won't do what you want (say, in a CGI script,<br>
where you want to make a nicely formatted error message (but there are<br>
modules that can help with that problem)) you should always check<br>
the return value from opening a file. The infrequent exception is when<br>
working with an unopened filehandle is actually what you want to do.</p>
<p>As a special case the 3-arg form with a read/write mode and the third<br>
argument being <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code>:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$tmp</span><span class="cm">,</span> <span class="q">"+>"</span><span class="cm">,</span> <a class="l_k" href="../functions/undef.html">undef</a><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> ...</li></ol></pre><p>opens a filehandle to an anonymous temporary file. Also using "+<"<br>
works for symmetry, but you really should consider writing something<br>
to the temporary file first. You will need to seek() to do the<br>
reading.</p>
<p>Since v5.8.0, perl has built using PerlIO by default. Unless you've<br>
changed this (i.e. Configure -Uuseperlio), you can open file handles to<br>
"in memory" files held in Perl scalars via:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="i">$fh</span><span class="cm">,</span> <span class="q">'>'</span><span class="cm">,</span> \<span class="i">$variable</span><span class="s">)</span> || ..</li></ol></pre><p>Though if you try to re-open <code class="inline"><span class="w">STDOUT</span></code>
or <code class="inline"><span class="w">STDERR</span></code>
as an "in memory"<br>
file, you have to close it first:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/close.html">close</a> <span class="w">STDOUT</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDOUT</span><span class="cm">,</span> <span class="q">'>'</span><span class="cm">,</span> \<span class="i">$variable</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't open STDOUT: $!"</span><span class="sc">;</span></li></ol></pre><p>Examples:</p>
<pre class="verbatim"><ol><li> $ARTICLE = 100;</li><li> open ARTICLE or die "Can't find article $ARTICLE: $!\n";</li><li> while (<ARTICLE>) {...</li><li></li><li> open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved)</li><li> # if the open fails, output is discarded</li><li></li><li> open(my $dbase, '+<', 'dbase.mine') # open for update</li><li> or die "Can't open 'dbase.mine' for update: $!";</li><li></li><li> open(my $dbase, '+<dbase.mine') # ditto</li><li> or die "Can't open 'dbase.mine' for update: $!";</li><li></li><li> open(ARTICLE, '-|', "caesar <$article") # decrypt article</li><li> or die "Can't start caesar: $!";</li><li></li><li> open(ARTICLE, "caesar <$article |") # ditto</li><li> or die "Can't start caesar: $!";</li><li></li><li> open(EXTRACT, "|sort >Tmp$$") # $$ is our process id</li><li> or die "Can't start sort: $!";</li><li></li><li> # in memory files</li><li> open(MEMORY,'>', \$var)</li><li> or die "Can't open memory file: $!";</li><li> print MEMORY "foo!\n"; # output will end up in $var</li><li></li><li> # process argument list of files along with any includes</li><li></li><li> foreach $file (@ARGV) {</li><li> process($file, 'fh00');</li><li> }</li><li></li><li> sub process {</li><li> my($filename, $input) = @_;</li><li> $input++; # this is a string increment</li><li> unless (open($input, $filename)) {</li><li> print STDERR "Can't open $filename: $!\n";</li><li> return;</li><li> }</li><li></li><li> local $_;</li><li> while (<$input>) { # note use of indirection</li><li> if (/^#include "(.*)"/) {</li><li> process($1, $input);</li><li> next;</li><li> }</li><li> #... # whatever</li><li> }</li><li> }</li></ol></pre><p>See <a href="../perliol.html">perliol</a> for detailed info on PerlIO.</p>
<p>You may also, in the Bourne shell tradition, specify an EXPR beginning<br>
with <code class="inline"><span class="q">'>&'</span></code>
, in which case the rest of the string is interpreted<br>
as the name of a filehandle (or file descriptor, if numeric) to be<br>
duped (as <code class="inline"><span class="i">dup</span><span class="s">(</span><span class="n">2</span><span class="s">)</span></code>
) and opened. You may use <code class="inline"><span class="i">&</span></code>
after <code class="inline">></code>,<br>
<code class="inline">>></code>
, <code class="inline"><</code>
, <code class="inline">+></code>, <code class="inline">+>></code>
, and <code class="inline">+<</code>
.<br>
The mode you specify should match the mode of the original filehandle.<br>
(Duping a filehandle does not take into account any existing contents<br>
of IO buffers.) If you use the 3-arg form then you can pass either a<br>
number, the name of a filehandle or the normal "reference to a glob".</p>
<p>Here is a script that saves, redirects, and restores <code class="inline"><span class="w">STDOUT</span></code>
and<br>
<code class="inline"><span class="w">STDERR</span></code>
using various methods:</p>
<pre class="verbatim"><ol><li> <span class="c">#!/usr/bin/perl</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$oldout</span><span class="cm">,</span> <span class="q">">&STDOUT"</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup STDOUT: $!"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">OLDERR</span><span class="cm">,</span> <span class="q">">&"</span><span class="cm">,</span> \<span class="i">*STDERR</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup STDERR: $!"</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDOUT</span><span class="cm">,</span> <span class="q">'>'</span><span class="cm">,</span> <span class="q">"foo.out"</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't redirect STDOUT: $!"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDERR</span><span class="cm">,</span> <span class="q">">&STDOUT"</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup STDOUT: $!"</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/select.html">select</a> <span class="w">STDERR</span><span class="sc">;</span> <span class="i">$|</span> = <span class="n">1</span><span class="sc">;</span> <span class="c"># make unbuffered</span></li><li> <a class="l_k" href="../functions/select.html">select</a> <span class="w">STDOUT</span><span class="sc">;</span> <span class="i">$|</span> = <span class="n">1</span><span class="sc">;</span> <span class="c"># make unbuffered</span></li><li></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDOUT</span> <span class="q">"stdout 1\n"</span><span class="sc">;</span> <span class="c"># this works for</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDERR</span> <span class="q">"stderr 1\n"</span><span class="sc">;</span> <span class="c"># subprocesses too</span></li><li></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDOUT</span><span class="cm">,</span> <span class="q">">&"</span><span class="cm">,</span> <span class="i">$oldout</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup \$oldout: $!"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDERR</span><span class="cm">,</span> <span class="q">">&OLDERR"</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup OLDERR: $!"</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDOUT</span> <span class="q">"stdout 2\n"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDERR</span> <span class="q">"stderr 2\n"</span><span class="sc">;</span></li></ol></pre><p>If you specify <code class="inline"><span class="q">'<&=X'</span></code>
, where <code class="inline"><span class="w">X</span></code>
is a file descriptor number<br>
or a filehandle, then Perl will do an equivalent of C's <code class="inline"><span class="w">fdopen</span></code>
of<br>
that file descriptor (and not call <code class="inline"><span class="i">dup</span><span class="s">(</span><span class="n">2</span><span class="s">)</span></code>
); this is more<br>
parsimonious of file descriptors. For example:</p>
<pre class="verbatim"><ol><li> <span class="c"># open for input, reusing the fileno of $fd</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FILEHANDLE</span><span class="cm">,</span> <span class="q">"<&=$fd"</span><span class="s">)</span></li></ol></pre><p>or</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FILEHANDLE</span><span class="cm">,</span> <span class="q">"<&="</span><span class="cm">,</span> <span class="i">$fd</span><span class="s">)</span></li></ol></pre><p>or</p>
<pre class="verbatim"><ol><li> <span class="c"># open for append, using the fileno of OLDFH</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FH</span><span class="cm">,</span> <span class="q">">>&="</span><span class="cm">,</span> <span class="w">OLDFH</span><span class="s">)</span></li></ol></pre><p>or</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FH</span><span class="cm">,</span> <span class="q">">>&=OLDFH"</span><span class="s">)</span></li></ol></pre><p>Being parsimonious on filehandles is also useful (besides being<br>
parsimonious) for example when something is dependent on file<br>
descriptors, like for example locking using flock(). If you do just<br>
<code class="inline"><a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">A</span><span class="cm">,</span> <span class="q">'>>&B'</span><span class="s">)</span></code>
, the filehandle A will not have the same file<br>
descriptor as B, and therefore flock(A) will not flock(B), and vice<br>
versa. But with <code class="inline"><a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">A</span><span class="cm">,</span> <span class="q">'>>&=B'</span><span class="s">)</span></code>
the filehandles will share<br>
the same file descriptor.</p>
<p>Note that if you are using Perls older than 5.8.0, Perl will be using<br>
the standard C libraries' fdopen() to implement the "=" functionality.<br>
On many UNIX systems fdopen() fails when file descriptors exceed a<br>
certain value, typically 255. For Perls 5.8.0 and later, PerlIO is<br>
most often the default.</p>
<p>You can see whether Perl has been compiled with PerlIO or not by<br>
running <code class="inline"><span class="w">perl</span> -<span class="w">V</span></code>
and looking for <code class="inline"><span class="w">useperlio</span>=</code>
line. If <code class="inline"><span class="w">useperlio</span></code>
<br>
is <code class="inline"><span class="w">define</span></code>
, you have PerlIO, otherwise you don't.</p>
<p>If you open a pipe on the command <code class="inline"><span class="q">'-'</span></code>
, i.e., either <code class="inline"><span class="q">'|-'</span></code>
or <code class="inline"><span class="q">'-|'</span></code>
<br>
with 2-arguments (or 1-argument) form of open(), then<br>
there is an implicit fork done, and the return value of open is the pid<br>
of the child within the parent process, and <code class="inline"><span class="n">0</span></code>
within the child<br>
process. (Use <code class="inline"><a class="l_k" href="../functions/defined.html">defined($pid)</a></code> to determine whether the open was successful.)<br>
The filehandle behaves normally for the parent, but i/o to that<br>
filehandle is piped from/to the STDOUT/STDIN of the child process.<br>
In the child process the filehandle isn't opened--i/o happens from/to<br>
the new STDOUT or STDIN. Typically this is used like the normal<br>
piped open when you want to exercise more control over just how the<br>
pipe command gets executed, such as when you are running setuid, and<br>
don't want to have to scan shell commands for metacharacters.<br>
The following triples are more or less equivalent:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">"|tr '[a-z]' '[A-Z]'"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'|-'</span><span class="cm">,</span> <span class="q">"tr '[a-z]' '[A-Z]'"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'|-'</span><span class="s">)</span> || <a class="l_k" href="../functions/exec.html">exec</a> <span class="q">'tr'</span><span class="cm">,</span> <span class="q">'[a-z]'</span><span class="cm">,</span> <span class="q">'[A-Z]'</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'|-'</span><span class="cm">,</span> <span class="q">"tr"</span><span class="cm">,</span> <span class="q">'[a-z]'</span><span class="cm">,</span> <span class="q">'[A-Z]'</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">"cat -n '$file'|"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'-|'</span><span class="cm">,</span> <span class="q">"cat -n '$file'"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'-|'</span><span class="s">)</span> || <a class="l_k" href="../functions/exec.html">exec</a> <span class="q">'cat'</span><span class="cm">,</span> <span class="q">'-n'</span><span class="cm">,</span> <span class="i">$file</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'-|'</span><span class="cm">,</span> <span class="q">"cat"</span><span class="cm">,</span> <span class="q">'-n'</span><span class="cm">,</span> <span class="i">$file</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The last example in each block shows the pipe as "list form", which is<br>
not yet supported on all platforms. A good rule of thumb is that if<br>
your platform has true <code class="inline"><a class="l_k" href="../functions/fork.html">fork()</a></code> (in other words, if your platform is<br>
UNIX) you can use the list form.</p>
<p>See <a href="../perlipc.html#Safe-Pipe-Opens">"Safe Pipe Opens" in perlipc</a> for more examples of this.</p>
<p>Beginning with v5.6.0, Perl will attempt to flush all files opened for<br>
output before any operation that may do a fork, but this may not be<br>
supported on some platforms (see <a href="../perlport.html">perlport</a>). To be safe, you may need<br>
to set <code class="inline"><span class="i">$|</span></code>
($AUTOFLUSH in English) or call the <code class="inline"><span class="i">autoflush</span><span class="s">(</span><span class="s">)</span></code>
method<br>
of <code class="inline"><span class="w">IO::Handle</span></code>
on any open handles.</p>
<p>On systems that support a close-on-exec flag on files, the flag will<br>
be set for the newly opened file descriptor as determined by the value<br>
of $^F. See <a href="../perlvar.html#%24%5eF">"$^F" in perlvar</a>.</p>
<p>Closing any piped filehandle causes the parent process to wait for the<br>
child to finish, and returns the status value in <code class="inline"><span class="i">$?</span></code>
and<br>
<code class="inline"><span class="i">$</span>{<span class="w">^CHILD_ERROR_NATIVE</span>}</code>
.</p>
<p>The filename passed to 2-argument (or 1-argument) form of open() will<br>
have leading and trailing whitespace deleted, and the normal<br>
redirection characters honored. This property, known as "magic open",<br>
can often be used to good effect. A user could specify a filename of<br>
<i>"rsh cat file |"</i>, or you could change certain filenames as needed:</p>
<pre class="verbatim"><ol><li> <span class="i">$filename</span> =~ <span class="q">s/(.*\.gz)\s*$/gzip -dc < $1|/</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FH</span><span class="cm">,</span> <span class="i">$filename</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't open $filename: $!"</span><span class="sc">;</span></li></ol></pre><p>Use 3-argument form to open a file with arbitrary weird characters in it,</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'<'</span><span class="cm">,</span> <span class="i">$file</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>otherwise it's necessary to protect any leading and trailing whitespace:</p>
<pre class="verbatim"><ol><li> <span class="i">$file</span> =~ <span class="q">s#^(\s)#./$1#</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">"< $file\0"</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>(this may not work on some bizarre filesystems). One should<br>
conscientiously choose between the <i>magic</i> and 3-arguments form<br>
of open():</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">IN</span><span class="cm">,</span> <span class="i">$ARGV</span>[<span class="n">0</span>]<span class="sc">;</span></li></ol></pre><p>will allow the user to specify an argument of the form <code class="inline"><span class="q">"rsh cat file |"</span></code>
,<br>
but will not work on a filename which happens to have a trailing space, while</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">IN</span><span class="cm">,</span> <span class="q">'<'</span><span class="cm">,</span> <span class="i">$ARGV</span>[<span class="n">0</span>]<span class="sc">;</span></li></ol></pre><p>will have exactly the opposite restrictions.</p>
<p>If you want a "real" C <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> (see <code class="inline"><a class="l_k" href="../functions/open.html">open(2)</a></code> on your system), then you<br>
should use the <code class="inline"><a class="l_k" href="../functions/sysopen.html">sysopen</a></code> function, which involves no such magic (but<br>
may use subtly different filemodes than Perl open(), which is mapped<br>
to C fopen()). This is<br>
another way to protect your filenames from interpretation. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">IO::Handle</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/sysopen.html">sysopen</a><span class="s">(</span><span class="w">HANDLE</span><span class="cm">,</span> <span class="i">$path</span><span class="cm">,</span> <span class="w">O_RDWR</span>|<span class="w">O_CREAT</span>|<span class="w">O_EXCL</span><span class="s">)</span></li><li> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"sysopen $path: $!"</span><span class="sc">;</span></li><li> <span class="i">$oldfh</span> = <a class="l_k" href="../functions/select.html">select</a><span class="s">(</span><span class="w">HANDLE</span><span class="s">)</span><span class="sc">;</span> <span class="i">$|</span> = <span class="n">1</span><span class="sc">;</span> <a class="l_k" href="../functions/select.html">select</a><span class="s">(</span><span class="i">$oldfh</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">HANDLE</span> <span class="q">"stuff $$\n"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/seek.html">seek</a><span class="s">(</span><span class="w">HANDLE</span><span class="cm">,</span> <span class="n">0</span><span class="cm">,</span> <span class="n">0</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"File contains: "</span><span class="cm">,</span> <span class="q"><HANDLE></span><span class="sc">;</span></li></ol></pre><p>Using the constructor from the <code class="inline"><span class="w">IO::Handle</span></code>
package (or one of its<br>
subclasses, such as <code class="inline"><span class="w">IO::File</span></code>
or <code class="inline"><span class="w">IO::Socket</span></code>
), you can generate anonymous<br>
filehandles that have the scope of whatever variables hold references to<br>
them, and automatically close whenever and however you leave that scope:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">IO::File</span><span class="sc">;</span></li><li> <span class="c">#...</span></li><li><a name="read_myfile_munged"></a> sub <span class="m">read_myfile_munged</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$ALL</span> = <a class="l_k" href="../functions/shift.html">shift</a><span class="sc">;</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$handle</span> = <span class="w">IO::File</span><span class="w">->new</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="i">$handle</span><span class="cm">,</span> <span class="q">"myfile"</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"myfile: $!"</span><span class="sc">;</span></li><li> <span class="i">$first</span> = <span class="q"><$handle></span></li><li> or <a class="l_k" href="../functions/return.html">return</a> <span class="s">(</span><span class="s">)</span><span class="sc">;</span> <span class="c"># Automatically closed here.</span></li><li> <span class="w">mung</span> <span class="i">$first</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"mung failed"</span><span class="sc">;</span> <span class="c"># Or here.</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <span class="i">$first</span><span class="cm">,</span> <span class="q"><$handle></span> if <span class="i">$ALL</span><span class="sc">;</span> <span class="c"># Or here.</span></li><li> <span class="i">$first</span><span class="sc">;</span> <span class="c"># Or here.</span></li><li> <span class="s">}</span></li></ol></pre><p>See <a href="../functions/seek.html">"seek"</a> for some details about mixing reading and writing.]]></desc>
</keyword>
<keyword name="open" type="function">
<params>
<param name='filehandle'/>
</params>
<desc><![CDATA[Opens the file whose filename is given by EXPR, and associates it with<br>
FILEHANDLE.</p>
<p>Simple examples to open a file for reading:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$fh</span><span class="cm">,</span> <span class="q">'<'</span><span class="cm">,</span> <span class="q">"input.txt"</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="i">$!</span><span class="sc">;</span></li></ol></pre><p>and for writing:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$fh</span><span class="cm">,</span> <span class="q">'>'</span><span class="cm">,</span> <span class="q">"output.txt"</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="i">$!</span><span class="sc">;</span></li></ol></pre><p>(The following is a comprehensive reference to open(): for a gentler<br>
introduction you may consider <a href="../perlopentut.html">perlopentut</a>.)</p>
<p>If FILEHANDLE is an undefined scalar variable (or array or hash element)<br>
the variable is assigned a reference to a new anonymous filehandle,<br>
otherwise if FILEHANDLE is an expression, its value is used as the name of<br>
the real filehandle wanted. (This is considered a symbolic reference, so<br>
<code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">strict</span> <span class="q">'refs'</span></code>
should <i>not</i> be in effect.)</p>
<p>If EXPR is omitted, the scalar variable of the same name as the<br>
FILEHANDLE contains the filename. (Note that lexical variables--those<br>
declared with <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code>--will not work for this purpose; so if you're<br>
using <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code>, specify EXPR in your call to open.)</p>
<p>If three or more arguments are specified then the mode of opening and<br>
the file name are separate. If MODE is <code class="inline"><span class="q">'<'</span></code>
or nothing, the file<br>
is opened for input. If MODE is <code class="inline"><span class="q">'>'</span></code>
, the file is truncated and<br>
opened for output, being created if necessary. If MODE is <code class="inline"><span class="q">'>>'</span></code>
,<br>
the file is opened for appending, again being created if necessary.</p>
<p>You can put a <code class="inline"><span class="q">'+'</span></code>
in front of the <code class="inline"><span class="q">'>'</span></code>
or <code class="inline"><span class="q">'<'</span></code>
to<br>
indicate that you want both read and write access to the file; thus<br>
<code class="inline"><span class="q">'+<'</span></code>
is almost always preferred for read/write updates--the <code class="inline"><span class="q">'+>'</span></code>
mode would clobber the file first. You can't usually use<br>
either read-write mode for updating textfiles, since they have<br>
variable length records. See the <b>-i</b> switch in <a href="../perlrun.html">perlrun</a> for a<br>
better approach. The file is created with permissions of <code class="inline"><span class="n">0666</span></code>
<br>
modified by the process' <code class="inline"><a class="l_k" href="../functions/umask.html">umask</a></code> value.</p>
<p>These various prefixes correspond to the fopen(3) modes of <code class="inline"><span class="q">'r'</span></code>
,<br>
<code class="inline"><span class="q">'r+'</span></code>
, <code class="inline"><span class="q">'w'</span></code>
, <code class="inline"><span class="q">'w+'</span></code>
, <code class="inline"><span class="q">'a'</span></code>
, and <code class="inline"><span class="q">'a+'</span></code>
.</p>
<p>In the 2-arguments (and 1-argument) form of the call the mode and<br>
filename should be concatenated (in this order), possibly separated by<br>
spaces. It is possible to omit the mode in these forms if the mode is<br>
<code class="inline"><span class="q">'<'</span></code>
.</p>
<p>If the filename begins with <code class="inline"><span class="q">'|'</span></code>
, the filename is interpreted as a<br>
command to which output is to be piped, and if the filename ends with a<br>
<code class="inline"><span class="q">'|'</span></code>
, the filename is interpreted as a command which pipes output to<br>
us. See <a href="../perlipc.html#Using-open()-for-IPC">"Using open() for IPC" in perlipc</a>
for more examples of this. (You are not allowed to <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> to a command<br>
that pipes both in <i>and</i> out, but see <a href="../IPC/Open2.html">IPC::Open2</a>, <a href="../IPC/Open3.html">IPC::Open3</a>,<br>
and <a href="../perlipc.html#Bidirectional-Communication-with-Another-Process">"Bidirectional Communication with Another Process" in perlipc</a>
for alternatives.)</p>
<p>For three or more arguments if MODE is <code class="inline"><span class="q">'|-'</span></code>
, the filename is<br>
interpreted as a command to which output is to be piped, and if MODE<br>
is <code class="inline"><span class="q">'-|'</span></code>
, the filename is interpreted as a command which pipes<br>
output to us. In the 2-arguments (and 1-argument) form one should<br>
replace dash (<code class="inline"><span class="q">'-'</span></code>
) with the command.<br>
See <a href="../perlipc.html#Using-open()-for-IPC">"Using open() for IPC" in perlipc</a> for more examples of this.<br>
(You are not allowed to <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> to a command that pipes both in <i>and</i>
out, but see <a href="../IPC/Open2.html">IPC::Open2</a>, <a href="../IPC/Open3.html">IPC::Open3</a>, and<br>
<a href="../perlipc.html#Bidirectional-Communication">"Bidirectional Communication" in perlipc</a> for alternatives.)</p>
<p>In the three-or-more argument form of pipe opens, if LIST is specified<br>
(extra arguments after the command name) then LIST becomes arguments<br>
to the command invoked if the platform supports it. The meaning of<br>
<code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> with more than three arguments for non-pipe modes is not yet<br>
specified. Experimental "layers" may give extra LIST arguments<br>
meaning.</p>
<p>In the 2-arguments (and 1-argument) form opening <code class="inline"><span class="q">'-'</span></code>
opens STDIN<br>
and opening <code class="inline"><span class="q">'>-'</span></code>
opens STDOUT.</p>
<p>You may use the three-argument form of open to specify IO "layers"<br>
(sometimes also referred to as "disciplines") to be applied to the handle<br>
that affect how the input and output are processed (see <a href="../open.html">open</a> and<br>
<a href="../PerlIO.html">PerlIO</a> for more details). For example</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$fh</span><span class="cm">,</span> <span class="q">"<:encoding(UTF-8)"</span><span class="cm">,</span> <span class="q">"file"</span><span class="s">)</span></li></ol></pre><p>will open the UTF-8 encoded file containing Unicode characters,<br>
see <a href="../perluniintro.html">perluniintro</a>. Note that if layers are specified in the<br>
three-arg form then default layers stored in ${^OPEN} (see <a href="../perlvar.html">perlvar</a>;<br>
usually set by the <b>open</b> pragma or the switch <b>-CioD</b>) are ignored.</p>
<p>Open returns nonzero upon success, the undefined value otherwise. If<br>
the <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> involved a pipe, the return value happens to be the pid of<br>
the subprocess.</p>
<p>If you're running Perl on a system that distinguishes between text<br>
files and binary files, then you should check out <a href="../functions/binmode.html">"binmode"</a> for tips<br>
for dealing with this. The key distinction between systems that need<br>
<code class="inline"><a class="l_k" href="../functions/binmode.html">binmode</a></code> and those that don't is their text file formats. Systems<br>
like Unix, Mac OS, and Plan 9, which delimit lines with a single<br>
character, and which encode that character in C as <code class="inline"><span class="q">"\n"</span></code>
, do not<br>
need <code class="inline"><a class="l_k" href="../functions/binmode.html">binmode</a></code>. The rest need it.</p>
<p>When opening a file, it's usually a bad idea to continue normal execution<br>
if the request failed, so <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> is frequently used in connection with<br>
<code class="inline"><a class="l_k" href="../functions/die.html">die</a></code>. Even if <code class="inline"><a class="l_k" href="../functions/die.html">die</a></code> won't do what you want (say, in a CGI script,<br>
where you want to make a nicely formatted error message (but there are<br>
modules that can help with that problem)) you should always check<br>
the return value from opening a file. The infrequent exception is when<br>
working with an unopened filehandle is actually what you want to do.</p>
<p>As a special case the 3-arg form with a read/write mode and the third<br>
argument being <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code>:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$tmp</span><span class="cm">,</span> <span class="q">"+>"</span><span class="cm">,</span> <a class="l_k" href="../functions/undef.html">undef</a><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> ...</li></ol></pre><p>opens a filehandle to an anonymous temporary file. Also using "+<"<br>
works for symmetry, but you really should consider writing something<br>
to the temporary file first. You will need to seek() to do the<br>
reading.</p>
<p>Since v5.8.0, perl has built using PerlIO by default. Unless you've<br>
changed this (i.e. Configure -Uuseperlio), you can open file handles to<br>
"in memory" files held in Perl scalars via:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="i">$fh</span><span class="cm">,</span> <span class="q">'>'</span><span class="cm">,</span> \<span class="i">$variable</span><span class="s">)</span> || ..</li></ol></pre><p>Though if you try to re-open <code class="inline"><span class="w">STDOUT</span></code>
or <code class="inline"><span class="w">STDERR</span></code>
as an "in memory"<br>
file, you have to close it first:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/close.html">close</a> <span class="w">STDOUT</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDOUT</span><span class="cm">,</span> <span class="q">'>'</span><span class="cm">,</span> \<span class="i">$variable</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't open STDOUT: $!"</span><span class="sc">;</span></li></ol></pre><p>Examples:</p>
<pre class="verbatim"><ol><li> $ARTICLE = 100;</li><li> open ARTICLE or die "Can't find article $ARTICLE: $!\n";</li><li> while (<ARTICLE>) {...</li><li></li><li> open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved)</li><li> # if the open fails, output is discarded</li><li></li><li> open(my $dbase, '+<', 'dbase.mine') # open for update</li><li> or die "Can't open 'dbase.mine' for update: $!";</li><li></li><li> open(my $dbase, '+<dbase.mine') # ditto</li><li> or die "Can't open 'dbase.mine' for update: $!";</li><li></li><li> open(ARTICLE, '-|', "caesar <$article") # decrypt article</li><li> or die "Can't start caesar: $!";</li><li></li><li> open(ARTICLE, "caesar <$article |") # ditto</li><li> or die "Can't start caesar: $!";</li><li></li><li> open(EXTRACT, "|sort >Tmp$$") # $$ is our process id</li><li> or die "Can't start sort: $!";</li><li></li><li> # in memory files</li><li> open(MEMORY,'>', \$var)</li><li> or die "Can't open memory file: $!";</li><li> print MEMORY "foo!\n"; # output will end up in $var</li><li></li><li> # process argument list of files along with any includes</li><li></li><li> foreach $file (@ARGV) {</li><li> process($file, 'fh00');</li><li> }</li><li></li><li> sub process {</li><li> my($filename, $input) = @_;</li><li> $input++; # this is a string increment</li><li> unless (open($input, $filename)) {</li><li> print STDERR "Can't open $filename: $!\n";</li><li> return;</li><li> }</li><li></li><li> local $_;</li><li> while (<$input>) { # note use of indirection</li><li> if (/^#include "(.*)"/) {</li><li> process($1, $input);</li><li> next;</li><li> }</li><li> #... # whatever</li><li> }</li><li> }</li></ol></pre><p>See <a href="../perliol.html">perliol</a> for detailed info on PerlIO.</p>
<p>You may also, in the Bourne shell tradition, specify an EXPR beginning<br>
with <code class="inline"><span class="q">'>&'</span></code>
, in which case the rest of the string is interpreted<br>
as the name of a filehandle (or file descriptor, if numeric) to be<br>
duped (as <code class="inline"><span class="i">dup</span><span class="s">(</span><span class="n">2</span><span class="s">)</span></code>
) and opened. You may use <code class="inline"><span class="i">&</span></code>
after <code class="inline">></code>,<br>
<code class="inline">>></code>
, <code class="inline"><</code>
, <code class="inline">+></code>, <code class="inline">+>></code>
, and <code class="inline">+<</code>
.<br>
The mode you specify should match the mode of the original filehandle.<br>
(Duping a filehandle does not take into account any existing contents<br>
of IO buffers.) If you use the 3-arg form then you can pass either a<br>
number, the name of a filehandle or the normal "reference to a glob".</p>
<p>Here is a script that saves, redirects, and restores <code class="inline"><span class="w">STDOUT</span></code>
and<br>
<code class="inline"><span class="w">STDERR</span></code>
using various methods:</p>
<pre class="verbatim"><ol><li> <span class="c">#!/usr/bin/perl</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$oldout</span><span class="cm">,</span> <span class="q">">&STDOUT"</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup STDOUT: $!"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">OLDERR</span><span class="cm">,</span> <span class="q">">&"</span><span class="cm">,</span> \<span class="i">*STDERR</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup STDERR: $!"</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDOUT</span><span class="cm">,</span> <span class="q">'>'</span><span class="cm">,</span> <span class="q">"foo.out"</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't redirect STDOUT: $!"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDERR</span><span class="cm">,</span> <span class="q">">&STDOUT"</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup STDOUT: $!"</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/select.html">select</a> <span class="w">STDERR</span><span class="sc">;</span> <span class="i">$|</span> = <span class="n">1</span><span class="sc">;</span> <span class="c"># make unbuffered</span></li><li> <a class="l_k" href="../functions/select.html">select</a> <span class="w">STDOUT</span><span class="sc">;</span> <span class="i">$|</span> = <span class="n">1</span><span class="sc">;</span> <span class="c"># make unbuffered</span></li><li></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDOUT</span> <span class="q">"stdout 1\n"</span><span class="sc">;</span> <span class="c"># this works for</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDERR</span> <span class="q">"stderr 1\n"</span><span class="sc">;</span> <span class="c"># subprocesses too</span></li><li></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDOUT</span><span class="cm">,</span> <span class="q">">&"</span><span class="cm">,</span> <span class="i">$oldout</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup \$oldout: $!"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDERR</span><span class="cm">,</span> <span class="q">">&OLDERR"</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup OLDERR: $!"</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDOUT</span> <span class="q">"stdout 2\n"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDERR</span> <span class="q">"stderr 2\n"</span><span class="sc">;</span></li></ol></pre><p>If you specify <code class="inline"><span class="q">'<&=X'</span></code>
, where <code class="inline"><span class="w">X</span></code>
is a file descriptor number<br>
or a filehandle, then Perl will do an equivalent of C's <code class="inline"><span class="w">fdopen</span></code>
of<br>
that file descriptor (and not call <code class="inline"><span class="i">dup</span><span class="s">(</span><span class="n">2</span><span class="s">)</span></code>
); this is more<br>
parsimonious of file descriptors. For example:</p>
<pre class="verbatim"><ol><li> <span class="c"># open for input, reusing the fileno of $fd</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FILEHANDLE</span><span class="cm">,</span> <span class="q">"<&=$fd"</span><span class="s">)</span></li></ol></pre><p>or</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FILEHANDLE</span><span class="cm">,</span> <span class="q">"<&="</span><span class="cm">,</span> <span class="i">$fd</span><span class="s">)</span></li></ol></pre><p>or</p>
<pre class="verbatim"><ol><li> <span class="c"># open for append, using the fileno of OLDFH</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FH</span><span class="cm">,</span> <span class="q">">>&="</span><span class="cm">,</span> <span class="w">OLDFH</span><span class="s">)</span></li></ol></pre><p>or</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FH</span><span class="cm">,</span> <span class="q">">>&=OLDFH"</span><span class="s">)</span></li></ol></pre><p>Being parsimonious on filehandles is also useful (besides being<br>
parsimonious) for example when something is dependent on file<br>
descriptors, like for example locking using flock(). If you do just<br>
<code class="inline"><a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">A</span><span class="cm">,</span> <span class="q">'>>&B'</span><span class="s">)</span></code>
, the filehandle A will not have the same file<br>
descriptor as B, and therefore flock(A) will not flock(B), and vice<br>
versa. But with <code class="inline"><a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">A</span><span class="cm">,</span> <span class="q">'>>&=B'</span><span class="s">)</span></code>
the filehandles will share<br>
the same file descriptor.</p>
<p>Note that if you are using Perls older than 5.8.0, Perl will be using<br>
the standard C libraries' fdopen() to implement the "=" functionality.<br>
On many UNIX systems fdopen() fails when file descriptors exceed a<br>
certain value, typically 255. For Perls 5.8.0 and later, PerlIO is<br>
most often the default.</p>
<p>You can see whether Perl has been compiled with PerlIO or not by<br>
running <code class="inline"><span class="w">perl</span> -<span class="w">V</span></code>
and looking for <code class="inline"><span class="w">useperlio</span>=</code>
line. If <code class="inline"><span class="w">useperlio</span></code>
<br>
is <code class="inline"><span class="w">define</span></code>
, you have PerlIO, otherwise you don't.</p>
<p>If you open a pipe on the command <code class="inline"><span class="q">'-'</span></code>
, i.e., either <code class="inline"><span class="q">'|-'</span></code>
or <code class="inline"><span class="q">'-|'</span></code>
<br>
with 2-arguments (or 1-argument) form of open(), then<br>
there is an implicit fork done, and the return value of open is the pid<br>
of the child within the parent process, and <code class="inline"><span class="n">0</span></code>
within the child<br>
process. (Use <code class="inline"><a class="l_k" href="../functions/defined.html">defined($pid)</a></code> to determine whether the open was successful.)<br>
The filehandle behaves normally for the parent, but i/o to that<br>
filehandle is piped from/to the STDOUT/STDIN of the child process.<br>
In the child process the filehandle isn't opened--i/o happens from/to<br>
the new STDOUT or STDIN. Typically this is used like the normal<br>
piped open when you want to exercise more control over just how the<br>
pipe command gets executed, such as when you are running setuid, and<br>
don't want to have to scan shell commands for metacharacters.<br>
The following triples are more or less equivalent:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">"|tr '[a-z]' '[A-Z]'"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'|-'</span><span class="cm">,</span> <span class="q">"tr '[a-z]' '[A-Z]'"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'|-'</span><span class="s">)</span> || <a class="l_k" href="../functions/exec.html">exec</a> <span class="q">'tr'</span><span class="cm">,</span> <span class="q">'[a-z]'</span><span class="cm">,</span> <span class="q">'[A-Z]'</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'|-'</span><span class="cm">,</span> <span class="q">"tr"</span><span class="cm">,</span> <span class="q">'[a-z]'</span><span class="cm">,</span> <span class="q">'[A-Z]'</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">"cat -n '$file'|"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'-|'</span><span class="cm">,</span> <span class="q">"cat -n '$file'"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'-|'</span><span class="s">)</span> || <a class="l_k" href="../functions/exec.html">exec</a> <span class="q">'cat'</span><span class="cm">,</span> <span class="q">'-n'</span><span class="cm">,</span> <span class="i">$file</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'-|'</span><span class="cm">,</span> <span class="q">"cat"</span><span class="cm">,</span> <span class="q">'-n'</span><span class="cm">,</span> <span class="i">$file</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The last example in each block shows the pipe as "list form", which is<br>
not yet supported on all platforms. A good rule of thumb is that if<br>
your platform has true <code class="inline"><a class="l_k" href="../functions/fork.html">fork()</a></code> (in other words, if your platform is<br>
UNIX) you can use the list form.</p>
<p>See <a href="../perlipc.html#Safe-Pipe-Opens">"Safe Pipe Opens" in perlipc</a> for more examples of this.</p>
<p>Beginning with v5.6.0, Perl will attempt to flush all files opened for<br>
output before any operation that may do a fork, but this may not be<br>
supported on some platforms (see <a href="../perlport.html">perlport</a>). To be safe, you may need<br>
to set <code class="inline"><span class="i">$|</span></code>
($AUTOFLUSH in English) or call the <code class="inline"><span class="i">autoflush</span><span class="s">(</span><span class="s">)</span></code>
method<br>
of <code class="inline"><span class="w">IO::Handle</span></code>
on any open handles.</p>
<p>On systems that support a close-on-exec flag on files, the flag will<br>
be set for the newly opened file descriptor as determined by the value<br>
of $^F. See <a href="../perlvar.html#%24%5eF">"$^F" in perlvar</a>.</p>
<p>Closing any piped filehandle causes the parent process to wait for the<br>
child to finish, and returns the status value in <code class="inline"><span class="i">$?</span></code>
and<br>
<code class="inline"><span class="i">$</span>{<span class="w">^CHILD_ERROR_NATIVE</span>}</code>
.</p>
<p>The filename passed to 2-argument (or 1-argument) form of open() will<br>
have leading and trailing whitespace deleted, and the normal<br>
redirection characters honored. This property, known as "magic open",<br>
can often be used to good effect. A user could specify a filename of<br>
<i>"rsh cat file |"</i>, or you could change certain filenames as needed:</p>
<pre class="verbatim"><ol><li> <span class="i">$filename</span> =~ <span class="q">s/(.*\.gz)\s*$/gzip -dc < $1|/</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FH</span><span class="cm">,</span> <span class="i">$filename</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't open $filename: $!"</span><span class="sc">;</span></li></ol></pre><p>Use 3-argument form to open a file with arbitrary weird characters in it,</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'<'</span><span class="cm">,</span> <span class="i">$file</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>otherwise it's necessary to protect any leading and trailing whitespace:</p>
<pre class="verbatim"><ol><li> <span class="i">$file</span> =~ <span class="q">s#^(\s)#./$1#</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">"< $file\0"</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>(this may not work on some bizarre filesystems). One should<br>
conscientiously choose between the <i>magic</i> and 3-arguments form<br>
of open():</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">IN</span><span class="cm">,</span> <span class="i">$ARGV</span>[<span class="n">0</span>]<span class="sc">;</span></li></ol></pre><p>will allow the user to specify an argument of the form <code class="inline"><span class="q">"rsh cat file |"</span></code>
,<br>
but will not work on a filename which happens to have a trailing space, while</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">IN</span><span class="cm">,</span> <span class="q">'<'</span><span class="cm">,</span> <span class="i">$ARGV</span>[<span class="n">0</span>]<span class="sc">;</span></li></ol></pre><p>will have exactly the opposite restrictions.</p>
<p>If you want a "real" C <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> (see <code class="inline"><a class="l_k" href="../functions/open.html">open(2)</a></code> on your system), then you<br>
should use the <code class="inline"><a class="l_k" href="../functions/sysopen.html">sysopen</a></code> function, which involves no such magic (but<br>
may use subtly different filemodes than Perl open(), which is mapped<br>
to C fopen()). This is<br>
another way to protect your filenames from interpretation. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">IO::Handle</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/sysopen.html">sysopen</a><span class="s">(</span><span class="w">HANDLE</span><span class="cm">,</span> <span class="i">$path</span><span class="cm">,</span> <span class="w">O_RDWR</span>|<span class="w">O_CREAT</span>|<span class="w">O_EXCL</span><span class="s">)</span></li><li> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"sysopen $path: $!"</span><span class="sc">;</span></li><li> <span class="i">$oldfh</span> = <a class="l_k" href="../functions/select.html">select</a><span class="s">(</span><span class="w">HANDLE</span><span class="s">)</span><span class="sc">;</span> <span class="i">$|</span> = <span class="n">1</span><span class="sc">;</span> <a class="l_k" href="../functions/select.html">select</a><span class="s">(</span><span class="i">$oldfh</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">HANDLE</span> <span class="q">"stuff $$\n"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/seek.html">seek</a><span class="s">(</span><span class="w">HANDLE</span><span class="cm">,</span> <span class="n">0</span><span class="cm">,</span> <span class="n">0</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"File contains: "</span><span class="cm">,</span> <span class="q"><HANDLE></span><span class="sc">;</span></li></ol></pre><p>Using the constructor from the <code class="inline"><span class="w">IO::Handle</span></code>
package (or one of its<br>
subclasses, such as <code class="inline"><span class="w">IO::File</span></code>
or <code class="inline"><span class="w">IO::Socket</span></code>
), you can generate anonymous<br>
filehandles that have the scope of whatever variables hold references to<br>
them, and automatically close whenever and however you leave that scope:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">IO::File</span><span class="sc">;</span></li><li> <span class="c">#...</span></li><li><a name="read_myfile_munged"></a> sub <span class="m">read_myfile_munged</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$ALL</span> = <a class="l_k" href="../functions/shift.html">shift</a><span class="sc">;</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$handle</span> = <span class="w">IO::File</span><span class="w">->new</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="i">$handle</span><span class="cm">,</span> <span class="q">"myfile"</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"myfile: $!"</span><span class="sc">;</span></li><li> <span class="i">$first</span> = <span class="q"><$handle></span></li><li> or <a class="l_k" href="../functions/return.html">return</a> <span class="s">(</span><span class="s">)</span><span class="sc">;</span> <span class="c"># Automatically closed here.</span></li><li> <span class="w">mung</span> <span class="i">$first</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"mung failed"</span><span class="sc">;</span> <span class="c"># Or here.</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <span class="i">$first</span><span class="cm">,</span> <span class="q"><$handle></span> if <span class="i">$ALL</span><span class="sc">;</span> <span class="c"># Or here.</span></li><li> <span class="i">$first</span><span class="sc">;</span> <span class="c"># Or here.</span></li><li> <span class="s">}</span></li></ol></pre><p>See <a href="../functions/seek.html">"seek"</a> for some details about mixing reading and writing.]]></desc>
</keyword>
<keyword name="opendir" type="function">
<params>
<param name='dirhandle'/>
<param name='expr'/>
</params>
<desc><![CDATA[Opens a directory named EXPR for processing by <code class="inline"><a class="l_k" href="../functions/readdir.html">readdir</a></code>, <code class="inline"><a class="l_k" href="../functions/telldir.html">telldir</a></code>,<br>
<code class="inline"><a class="l_k" href="../functions/seekdir.html">seekdir</a></code>, <code class="inline"><a class="l_k" href="../functions/rewinddir.html">rewinddir</a></code>, and <code class="inline"><a class="l_k" href="../functions/closedir.html">closedir</a></code>. Returns true if successful.<br>
DIRHANDLE may be an expression whose value can be used as an indirect<br>
dirhandle, usually the real dirhandle name. If DIRHANDLE is an undefined<br>
scalar variable (or array or hash element), the variable is assigned a<br>
reference to a new anonymous dirhandle.<br>
DIRHANDLEs have their own namespace separate from FILEHANDLEs.</p>
<p>See example at <code class="inline"><a class="l_k" href="../functions/readdir.html">readdir</a></code>.]]></desc>
</keyword>
<keyword name="ord" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Returns the numeric (the native 8-bit encoding, like ASCII or EBCDIC,<br>
or Unicode) value of the first character of EXPR. If EXPR is omitted,<br>
uses <code class="inline"><span class="i">$_</span></code>
.</p>
<p>For the reverse, see <a href="../functions/chr.html">"chr"</a>.<br>
See <a href="../perlunicode.html">perlunicode</a> for more about Unicode.]]></desc>
</keyword>
<keyword name="ord" type="function">
<params>
</params>
<desc><![CDATA[Returns the numeric (the native 8-bit encoding, like ASCII or EBCDIC,<br>
or Unicode) value of the first character of EXPR. If EXPR is omitted,<br>
uses <code class="inline"><span class="i">$_</span></code>
.</p>
<p>For the reverse, see <a href="../functions/chr.html">"chr"</a>.<br>
See <a href="../perlunicode.html">perlunicode</a> for more about Unicode.]]></desc>
</keyword>
<keyword name="our" type="function">
<params>
<param name='expr : attrs'/>
</params>
<desc><![CDATA[<code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> associates a simple name with a package variable in the current<br>
package for use within the current scope. When <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">strict</span> <span class="q">'vars'</span></code>
is in<br>
effect, <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> lets you use declared global variables without qualifying<br>
them with package names, within the lexical scope of the <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> declaration.<br>
In this way <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> differs from <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">vars</span></code>
, which is package scoped.</p>
<p>Unlike <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code>, which both allocates storage for a variable and associates<br>
a simple name with that storage for use within the current scope, <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code>
associates a simple name with a package variable in the current package,<br>
for use within the current scope. In other words, <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> has the same<br>
scoping rules as <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code>, but does not necessarily create a<br>
variable.</p>
<p>If more than one value is listed, the list must be placed<br>
in parentheses.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/our.html">our</a> <span class="i">$foo</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/our.html">our</a><span class="s">(</span><span class="i">$bar</span><span class="cm">,</span> <span class="i">$baz</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>An <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> declaration declares a global variable that will be visible<br>
across its entire lexical scope, even across package boundaries. The<br>
package in which the variable is entered is determined at the point<br>
of the declaration, not at the point of use. This means the following<br>
behavior holds:</p>
<pre class="verbatim"><ol><li><a name="package-Foo"></a> package <span class="i">Foo</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/our.html">our</a> <span class="i">$bar</span><span class="sc">;</span> <span class="c"># declares $Foo::bar for rest of lexical scope</span></li><li> <span class="i">$bar</span> = <span class="n">20</span><span class="sc">;</span></li><li></li><li><a name="package-Bar"></a> package <span class="i">Bar</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$bar</span><span class="sc">;</span> <span class="c"># prints 20, as it refers to $Foo::bar</span></li></ol></pre><p>Multiple <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> declarations with the same name in the same lexical<br>
scope are allowed if they are in different packages. If they happen<br>
to be in the same package, Perl will emit warnings if you have asked<br>
for them, just like multiple <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code> declarations. Unlike a second<br>
<code class="inline"><a class="l_k" href="../functions/my.html">my</a></code> declaration, which will bind the name to a fresh variable, a<br>
second <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> declaration in the same package, in the same scope, is<br>
merely redundant.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">warnings</span><span class="sc">;</span></li><li><a name="package-Foo"></a> package <span class="i">Foo</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/our.html">our</a> <span class="i">$bar</span><span class="sc">;</span> <span class="c"># declares $Foo::bar for rest of lexical scope</span></li><li> <span class="i">$bar</span> = <span class="n">20</span><span class="sc">;</span></li><li></li><li><a name="package-Bar"></a> package <span class="i">Bar</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/our.html">our</a> <span class="i">$bar</span> = <span class="n">30</span><span class="sc">;</span> <span class="c"># declares $Bar::bar for rest of lexical scope</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$bar</span><span class="sc">;</span> <span class="c"># prints 30</span></li><li></li><li> <a class="l_k" href="../functions/our.html">our</a> <span class="i">$bar</span><span class="sc">;</span> <span class="c"># emits warning but has no other effect</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$bar</span><span class="sc">;</span> <span class="c"># still prints 30</span></li></ol></pre><p>An <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> declaration may also have a list of attributes associated<br>
with it.</p>
<p>The exact semantics and interface of TYPE and ATTRS are still<br>
evolving. TYPE is currently bound to the use of <code class="inline"><span class="w">fields</span></code>
pragma,<br>
and attributes are handled using the <code class="inline"><span class="w">attributes</span></code>
pragma, or starting<br>
from Perl 5.8.0 also via the <code class="inline"><span class="w">Attribute::Handlers</span></code>
module. See<br>
<a href="../perlsub.html#Private-Variables-via-my()">"Private Variables via my()" in perlsub</a> for details, and <a href="../fields.html">fields</a>,<br>
<a href="../attributes.html">attributes</a>, and <a href="../Attribute/Handlers.html">Attribute::Handlers</a>.]]></desc>
</keyword>
<keyword name="our" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[<code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> associates a simple name with a package variable in the current<br>
package for use within the current scope. When <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">strict</span> <span class="q">'vars'</span></code>
is in<br>
effect, <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> lets you use declared global variables without qualifying<br>
them with package names, within the lexical scope of the <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> declaration.<br>
In this way <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> differs from <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">vars</span></code>
, which is package scoped.</p>
<p>Unlike <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code>, which both allocates storage for a variable and associates<br>
a simple name with that storage for use within the current scope, <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code>
associates a simple name with a package variable in the current package,<br>
for use within the current scope. In other words, <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> has the same<br>
scoping rules as <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code>, but does not necessarily create a<br>
variable.</p>
<p>If more than one value is listed, the list must be placed<br>
in parentheses.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/our.html">our</a> <span class="i">$foo</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/our.html">our</a><span class="s">(</span><span class="i">$bar</span><span class="cm">,</span> <span class="i">$baz</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>An <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> declaration declares a global variable that will be visible<br>
across its entire lexical scope, even across package boundaries. The<br>
package in which the variable is entered is determined at the point<br>
of the declaration, not at the point of use. This means the following<br>
behavior holds:</p>
<pre class="verbatim"><ol><li><a name="package-Foo"></a> package <span class="i">Foo</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/our.html">our</a> <span class="i">$bar</span><span class="sc">;</span> <span class="c"># declares $Foo::bar for rest of lexical scope</span></li><li> <span class="i">$bar</span> = <span class="n">20</span><span class="sc">;</span></li><li></li><li><a name="package-Bar"></a> package <span class="i">Bar</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$bar</span><span class="sc">;</span> <span class="c"># prints 20, as it refers to $Foo::bar</span></li></ol></pre><p>Multiple <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> declarations with the same name in the same lexical<br>
scope are allowed if they are in different packages. If they happen<br>
to be in the same package, Perl will emit warnings if you have asked<br>
for them, just like multiple <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code> declarations. Unlike a second<br>
<code class="inline"><a class="l_k" href="../functions/my.html">my</a></code> declaration, which will bind the name to a fresh variable, a<br>
second <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> declaration in the same package, in the same scope, is<br>
merely redundant.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">warnings</span><span class="sc">;</span></li><li><a name="package-Foo"></a> package <span class="i">Foo</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/our.html">our</a> <span class="i">$bar</span><span class="sc">;</span> <span class="c"># declares $Foo::bar for rest of lexical scope</span></li><li> <span class="i">$bar</span> = <span class="n">20</span><span class="sc">;</span></li><li></li><li><a name="package-Bar"></a> package <span class="i">Bar</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/our.html">our</a> <span class="i">$bar</span> = <span class="n">30</span><span class="sc">;</span> <span class="c"># declares $Bar::bar for rest of lexical scope</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$bar</span><span class="sc">;</span> <span class="c"># prints 30</span></li><li></li><li> <a class="l_k" href="../functions/our.html">our</a> <span class="i">$bar</span><span class="sc">;</span> <span class="c"># emits warning but has no other effect</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$bar</span><span class="sc">;</span> <span class="c"># still prints 30</span></li></ol></pre><p>An <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> declaration may also have a list of attributes associated<br>
with it.</p>
<p>The exact semantics and interface of TYPE and ATTRS are still<br>
evolving. TYPE is currently bound to the use of <code class="inline"><span class="w">fields</span></code>
pragma,<br>
and attributes are handled using the <code class="inline"><span class="w">attributes</span></code>
pragma, or starting<br>
from Perl 5.8.0 also via the <code class="inline"><span class="w">Attribute::Handlers</span></code>
module. See<br>
<a href="../perlsub.html#Private-Variables-via-my()">"Private Variables via my()" in perlsub</a> for details, and <a href="../fields.html">fields</a>,<br>
<a href="../attributes.html">attributes</a>, and <a href="../Attribute/Handlers.html">Attribute::Handlers</a>.]]></desc>
</keyword>
<keyword name="our" type="function">
<params>
<param name='type expr : attrs'/>
</params>
<desc><![CDATA[<code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> associates a simple name with a package variable in the current<br>
package for use within the current scope. When <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">strict</span> <span class="q">'vars'</span></code>
is in<br>
effect, <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> lets you use declared global variables without qualifying<br>
them with package names, within the lexical scope of the <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> declaration.<br>
In this way <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> differs from <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">vars</span></code>
, which is package scoped.</p>
<p>Unlike <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code>, which both allocates storage for a variable and associates<br>
a simple name with that storage for use within the current scope, <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code>
associates a simple name with a package variable in the current package,<br>
for use within the current scope. In other words, <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> has the same<br>
scoping rules as <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code>, but does not necessarily create a<br>
variable.</p>
<p>If more than one value is listed, the list must be placed<br>
in parentheses.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/our.html">our</a> <span class="i">$foo</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/our.html">our</a><span class="s">(</span><span class="i">$bar</span><span class="cm">,</span> <span class="i">$baz</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>An <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> declaration declares a global variable that will be visible<br>
across its entire lexical scope, even across package boundaries. The<br>
package in which the variable is entered is determined at the point<br>
of the declaration, not at the point of use. This means the following<br>
behavior holds:</p>
<pre class="verbatim"><ol><li><a name="package-Foo"></a> package <span class="i">Foo</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/our.html">our</a> <span class="i">$bar</span><span class="sc">;</span> <span class="c"># declares $Foo::bar for rest of lexical scope</span></li><li> <span class="i">$bar</span> = <span class="n">20</span><span class="sc">;</span></li><li></li><li><a name="package-Bar"></a> package <span class="i">Bar</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$bar</span><span class="sc">;</span> <span class="c"># prints 20, as it refers to $Foo::bar</span></li></ol></pre><p>Multiple <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> declarations with the same name in the same lexical<br>
scope are allowed if they are in different packages. If they happen<br>
to be in the same package, Perl will emit warnings if you have asked<br>
for them, just like multiple <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code> declarations. Unlike a second<br>
<code class="inline"><a class="l_k" href="../functions/my.html">my</a></code> declaration, which will bind the name to a fresh variable, a<br>
second <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> declaration in the same package, in the same scope, is<br>
merely redundant.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">warnings</span><span class="sc">;</span></li><li><a name="package-Foo"></a> package <span class="i">Foo</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/our.html">our</a> <span class="i">$bar</span><span class="sc">;</span> <span class="c"># declares $Foo::bar for rest of lexical scope</span></li><li> <span class="i">$bar</span> = <span class="n">20</span><span class="sc">;</span></li><li></li><li><a name="package-Bar"></a> package <span class="i">Bar</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/our.html">our</a> <span class="i">$bar</span> = <span class="n">30</span><span class="sc">;</span> <span class="c"># declares $Bar::bar for rest of lexical scope</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$bar</span><span class="sc">;</span> <span class="c"># prints 30</span></li><li></li><li> <a class="l_k" href="../functions/our.html">our</a> <span class="i">$bar</span><span class="sc">;</span> <span class="c"># emits warning but has no other effect</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$bar</span><span class="sc">;</span> <span class="c"># still prints 30</span></li></ol></pre><p>An <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> declaration may also have a list of attributes associated<br>
with it.</p>
<p>The exact semantics and interface of TYPE and ATTRS are still<br>
evolving. TYPE is currently bound to the use of <code class="inline"><span class="w">fields</span></code>
pragma,<br>
and attributes are handled using the <code class="inline"><span class="w">attributes</span></code>
pragma, or starting<br>
from Perl 5.8.0 also via the <code class="inline"><span class="w">Attribute::Handlers</span></code>
module. See<br>
<a href="../perlsub.html#Private-Variables-via-my()">"Private Variables via my()" in perlsub</a> for details, and <a href="../fields.html">fields</a>,<br>
<a href="../attributes.html">attributes</a>, and <a href="../Attribute/Handlers.html">Attribute::Handlers</a>.]]></desc>
</keyword>
<keyword name="our" type="function">
<params>
<param name='type expr'/>
</params>
<desc><![CDATA[<code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> associates a simple name with a package variable in the current<br>
package for use within the current scope. When <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">strict</span> <span class="q">'vars'</span></code>
is in<br>
effect, <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> lets you use declared global variables without qualifying<br>
them with package names, within the lexical scope of the <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> declaration.<br>
In this way <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> differs from <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">vars</span></code>
, which is package scoped.</p>
<p>Unlike <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code>, which both allocates storage for a variable and associates<br>
a simple name with that storage for use within the current scope, <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code>
associates a simple name with a package variable in the current package,<br>
for use within the current scope. In other words, <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> has the same<br>
scoping rules as <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code>, but does not necessarily create a<br>
variable.</p>
<p>If more than one value is listed, the list must be placed<br>
in parentheses.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/our.html">our</a> <span class="i">$foo</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/our.html">our</a><span class="s">(</span><span class="i">$bar</span><span class="cm">,</span> <span class="i">$baz</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>An <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> declaration declares a global variable that will be visible<br>
across its entire lexical scope, even across package boundaries. The<br>
package in which the variable is entered is determined at the point<br>
of the declaration, not at the point of use. This means the following<br>
behavior holds:</p>
<pre class="verbatim"><ol><li><a name="package-Foo"></a> package <span class="i">Foo</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/our.html">our</a> <span class="i">$bar</span><span class="sc">;</span> <span class="c"># declares $Foo::bar for rest of lexical scope</span></li><li> <span class="i">$bar</span> = <span class="n">20</span><span class="sc">;</span></li><li></li><li><a name="package-Bar"></a> package <span class="i">Bar</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$bar</span><span class="sc">;</span> <span class="c"># prints 20, as it refers to $Foo::bar</span></li></ol></pre><p>Multiple <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> declarations with the same name in the same lexical<br>
scope are allowed if they are in different packages. If they happen<br>
to be in the same package, Perl will emit warnings if you have asked<br>
for them, just like multiple <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code> declarations. Unlike a second<br>
<code class="inline"><a class="l_k" href="../functions/my.html">my</a></code> declaration, which will bind the name to a fresh variable, a<br>
second <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> declaration in the same package, in the same scope, is<br>
merely redundant.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">warnings</span><span class="sc">;</span></li><li><a name="package-Foo"></a> package <span class="i">Foo</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/our.html">our</a> <span class="i">$bar</span><span class="sc">;</span> <span class="c"># declares $Foo::bar for rest of lexical scope</span></li><li> <span class="i">$bar</span> = <span class="n">20</span><span class="sc">;</span></li><li></li><li><a name="package-Bar"></a> package <span class="i">Bar</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/our.html">our</a> <span class="i">$bar</span> = <span class="n">30</span><span class="sc">;</span> <span class="c"># declares $Bar::bar for rest of lexical scope</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$bar</span><span class="sc">;</span> <span class="c"># prints 30</span></li><li></li><li> <a class="l_k" href="../functions/our.html">our</a> <span class="i">$bar</span><span class="sc">;</span> <span class="c"># emits warning but has no other effect</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$bar</span><span class="sc">;</span> <span class="c"># still prints 30</span></li></ol></pre><p>An <code class="inline"><a class="l_k" href="../functions/our.html">our</a></code> declaration may also have a list of attributes associated<br>
with it.</p>
<p>The exact semantics and interface of TYPE and ATTRS are still<br>
evolving. TYPE is currently bound to the use of <code class="inline"><span class="w">fields</span></code>
pragma,<br>
and attributes are handled using the <code class="inline"><span class="w">attributes</span></code>
pragma, or starting<br>
from Perl 5.8.0 also via the <code class="inline"><span class="w">Attribute::Handlers</span></code>
module. See<br>
<a href="../perlsub.html#Private-Variables-via-my()">"Private Variables via my()" in perlsub</a> for details, and <a href="../fields.html">fields</a>,<br>
<a href="../attributes.html">attributes</a>, and <a href="../Attribute/Handlers.html">Attribute::Handlers</a>.]]></desc>
</keyword>
<keyword name="pack" type="function">
<params>
<param name='template'/>
<param name='list'/>
</params>
<desc><![CDATA[Takes a LIST of values and converts it into a string using the rules<br>
given by the TEMPLATE. The resulting string is the concatenation of<br>
the converted values. Typically, each converted value looks<br>
like its machine-level representation. For example, on 32-bit machines<br>
an integer may be represented by a sequence of 4 bytes that will be <br>
converted to a sequence of 4 characters.</p>
<p>The TEMPLATE is a sequence of characters that give the order and type<br>
of values, as follows:</p>
<pre class="verbatim"><ol><li> a A string with arbitrary binary data, will be null padded.</li><li> A A text (ASCII) string, will be space padded.</li><li> Z A null terminated (ASCIZ) string, will be null padded.</li><li></li><li> b A bit string (ascending bit order inside each byte, like vec()).</li><li> B A bit string (descending bit order inside each byte).</li><li> h A hex string (low nybble first).</li><li> H A hex string (high nybble first).</li><li></li><li> c A signed char (8-bit) value.</li><li> C An unsigned char (octet) value.</li><li> W An unsigned char value (can be greater than 255).</li><li></li><li> s A signed short (16-bit) value.</li><li> S An unsigned short value.</li><li></li><li> l A signed long (32-bit) value.</li><li> L An unsigned long value.</li><li></li><li> q A signed quad (64-bit) value.</li><li> Q An unsigned quad value.</li><li> (Quads are available only if your system supports 64-bit</li><li> integer values _and_ if Perl has been compiled to support those.</li><li> Causes a fatal error otherwise.)</li><li></li><li> i A signed integer value.</li><li> I A unsigned integer value.</li><li> (This 'integer' is _at_least_ 32 bits wide. Its exact</li><li> size depends on what a local C compiler calls 'int'.)</li><li></li><li> n An unsigned short (16-bit) in "network" (big-endian) order.</li><li> N An unsigned long (32-bit) in "network" (big-endian) order.</li><li> v An unsigned short (16-bit) in "VAX" (little-endian) order.</li><li> V An unsigned long (32-bit) in "VAX" (little-endian) order.</li><li></li><li> j A Perl internal signed integer value (IV).</li><li> J A Perl internal unsigned integer value (UV).</li><li></li><li> f A single-precision float in the native format.</li><li> d A double-precision float in the native format.</li><li></li><li> F A Perl internal floating point value (NV) in the native format</li><li> D A long double-precision float in the native format.</li><li> (Long doubles are available only if your system supports long</li><li> double values _and_ if Perl has been compiled to support those.</li><li> Causes a fatal error otherwise.)</li><li></li><li> p A pointer to a null-terminated string.</li><li> P A pointer to a structure (fixed-length string).</li><li></li><li> u A uuencoded string.</li><li> U A Unicode character number. Encodes to a character in character mode</li><li> and UTF-8 (or UTF-EBCDIC in EBCDIC platforms) in byte mode.</li><li></li><li> w A BER compressed integer (not an ASN.1 BER, see perlpacktut for</li><li> details). Its bytes represent an unsigned integer in base 128,</li><li> most significant digit first, with as few digits as possible. Bit</li><li> eight (the high bit) is set on each byte except the last.</li><li></li><li> x A null byte.</li><li> X Back up a byte.</li><li> @ Null fill or truncate to absolute position, counted from the</li><li> start of the innermost ()-group.</li><li> . Null fill or truncate to absolute position specified by value.</li><li> ( Start of a ()-group.</li></ol></pre><p>One or more of the modifiers below may optionally follow some letters in the<br>
TEMPLATE (the second column lists the letters for which the modifier is<br>
valid):</p>
<pre class="verbatim"><ol><li> ! sSlLiI Forces native (short, long, int) sizes instead</li><li> of fixed (16-/32-bit) sizes.</li><li></li><li> xX Make x and X act as alignment commands.</li><li></li><li> nNvV Treat integers as signed instead of unsigned.</li><li></li><li> @. Specify position as byte offset in the internal</li><li> representation of the packed string. Efficient but</li><li> dangerous.</li><li></li><li> > sSiIlLqQ Force big-endian byte-order on the type.</li><li> jJfFdDpP (The "big end" touches the construct.)</li><li></li><li> < sSiIlLqQ Force little-endian byte-order on the type.</li><li> jJfFdDpP (The "little end" touches the construct.)</li></ol></pre><p>The <code class="inline">></code> and <code class="inline"><</code>
modifiers can also be used on <code class="inline"><span class="s">(</span><span class="s">)</span></code>
-groups,<br>
in which case they force a certain byte-order on all components of<br>
that group, including subgroups.</p>
<p>The following rules apply:</p>
<ul>
<li>
<p>Each letter may optionally be followed by a number giving a repeat<br>
count. With all types except <code class="inline"><span class="w">a</span></code>
, <code class="inline"><span class="w">A</span></code>
, <code class="inline"><span class="w">Z</span></code>
, <code class="inline"><span class="w">b</span></code>
, <code class="inline"><span class="w">B</span></code>
, <code class="inline"><span class="w">h</span></code>
,<br>
<code class="inline"><span class="w">H</span></code>
, <code class="inline"><span class="i">@</span></code>
, <code class="inline">.</code>, <code class="inline"><span class="w">x</span></code>
, <code class="inline"><span class="w">X</span></code>
and <code class="inline"><span class="w">P</span></code>
the pack function will gobble up<br>
that many values from the LIST. A <code class="inline"><span class="i">*</span></code>
for the repeat count means to<br>
use however many items are left, except for <code class="inline"><span class="i">@</span></code>
, <code class="inline"><span class="w">x</span></code>
, <code class="inline"><span class="w">X</span></code>
, where it<br>
is equivalent to <code class="inline"><span class="n">0</span></code>
, for <.> where it means relative to string start<br>
and <code class="inline"><span class="w">u</span></code>
, where it is equivalent to 1 (or 45, which is the same).<br>
A numeric repeat count may optionally be enclosed in brackets, as in<br>
<code class="inline"><a class="l_k" href="../functions/pack.html">pack</a> <span class="q">'C[80]'</span><span class="cm">,</span> <span class="i">@arr</span></code>
.</p>
<p>One can replace the numeric repeat count by a template enclosed in brackets;<br>
then the packed length of this template in bytes is used as a count.<br>
For example, <code class="inline"><span class="w">x</span><span class="s">[</span><span class="w">L</span><span class="s">]</span></code>
skips a long (it skips the number of bytes in a long);<br>
the template <code class="inline">$t X[$t] $t</code> unpack()s twice what $t unpacks.<br>
If the template in brackets contains alignment commands (such as <code class="inline"><span class="w">x</span>!<span class="s">[</span><span class="w">d</span><span class="s">]</span></code>
),<br>
its packed length is calculated as if the start of the template has the maximal<br>
possible alignment.</p>
<p>When used with <code class="inline"><span class="w">Z</span></code>
, <code class="inline"><span class="i">*</span></code>
results in the addition of a trailing null<br>
byte (so the packed result will be one longer than the byte <code class="inline"><a class="l_k" href="../functions/length.html">length</a></code>
of the item).</p>
<p>When used with <code class="inline"><span class="i">@</span></code>
, the repeat count represents an offset from the start<br>
of the innermost () group.</p>
<p>When used with <code class="inline">.</code>, the repeat count is used to determine the starting<br>
position from where the value offset is calculated. If the repeat count<br>
is 0, it's relative to the current position. If the repeat count is <code class="inline"><span class="i">*</span></code>
,<br>
the offset is relative to the start of the packed string. And if its an<br>
integer <code class="inline"><span class="w">n</span></code>
the offset is relative to the start of the n-th innermost<br>
() group (or the start of the string if <code class="inline"><span class="w">n</span></code>
is bigger then the group<br>
level).</p>
<p>The repeat count for <code class="inline"><span class="w">u</span></code>
is interpreted as the maximal number of bytes<br>
to encode per line of output, with 0, 1 and 2 replaced by 45. The repeat <br>
count should not be more than 65.</p>
</li>
<li>
<p>The <code class="inline"><span class="w">a</span></code>
, <code class="inline"><span class="w">A</span></code>
, and <code class="inline"><span class="w">Z</span></code>
types gobble just one value, but pack it as a<br>
string of length count, padding with nulls or spaces as necessary. When<br>
unpacking, <code class="inline"><span class="w">A</span></code>
strips trailing whitespace and nulls, <code class="inline"><span class="w">Z</span></code>
strips everything<br>
after the first null, and <code class="inline"><span class="w">a</span></code>
returns data verbatim.</p>
<p>If the value-to-pack is too long, it is truncated. If too long and an<br>
explicit count is provided, <code class="inline"><span class="w">Z</span></code>
packs only <code class="inline"><span class="i">$count</span>-<span class="n">1</span></code>
bytes, followed<br>
by a null byte. Thus <code class="inline"><span class="w">Z</span></code>
always packs a trailing null (except when the<br>
count is 0).</p>
</li>
<li>
<p>Likewise, the <code class="inline"><span class="w">b</span></code>
and <code class="inline"><span class="w">B</span></code>
fields pack a string that many bits long.<br>
Each character of the input field of pack() generates 1 bit of the result.<br>
Each result bit is based on the least-significant bit of the corresponding<br>
input character, i.e., on <code class="inline"><a class="l_k" href="../functions/ord.html">ord($char)%2</a></code>. In particular, characters <code class="inline"><span class="q">"0"</span></code>
<br>
and <code class="inline"><span class="q">"1"</span></code>
generate bits 0 and 1, as do characters <code class="inline"><span class="q">"\0"</span></code>
and <code class="inline"><span class="q">"\1"</span></code>
.</p>
<p>Starting from the beginning of the input string of pack(), each 8-tuple<br>
of characters is converted to 1 character of output. With format <code class="inline"><span class="w">b</span></code>
<br>
the first character of the 8-tuple determines the least-significant bit of a<br>
character, and with format <code class="inline"><span class="w">B</span></code>
it determines the most-significant bit of<br>
a character.</p>
<p>If the length of the input string is not exactly divisible by 8, the<br>
remainder is packed as if the input string were padded by null characters<br>
at the end. Similarly, during unpack()ing the "extra" bits are ignored.</p>
<p>If the input string of pack() is longer than needed, extra characters are <br>
ignored. A <code class="inline"><span class="i">*</span></code>
for the repeat count of pack() means to use all the <br>
characters of the input field. On unpack()ing the bits are converted to a <br>
string of <code class="inline"><span class="q">"0"</span></code>
s and <code class="inline"><span class="q">"1"</span></code>
s.</p>
</li>
<li>
<p>The <code class="inline"><span class="w">h</span></code>
and <code class="inline"><span class="w">H</span></code>
fields pack a string that many nybbles (4-bit groups,<br>
representable as hexadecimal digits, 0-9a-f) long.</p>
<p>Each character of the input field of pack() generates 4 bits of the result.<br>
For non-alphabetical characters the result is based on the 4 least-significant<br>
bits of the input character, i.e., on <code class="inline"><a class="l_k" href="../functions/ord.html">ord($char)%16</a></code>. In particular,<br>
characters <code class="inline"><span class="q">"0"</span></code>
and <code class="inline"><span class="q">"1"</span></code>
generate nybbles 0 and 1, as do bytes<br>
<code class="inline"><span class="q">"\0"</span></code>
and <code class="inline"><span class="q">"\1"</span></code>
. For characters <code class="inline"><span class="q">"a"</span>..<span class="q">"f"</span></code>
and <code class="inline"><span class="q">"A"</span>..<span class="q">"F"</span></code>
the result<br>
is compatible with the usual hexadecimal digits, so that <code class="inline"><span class="q">"a"</span></code>
and<br>
<code class="inline"><span class="q">"A"</span></code>
both generate the nybble <code class="inline"><span class="n">0xa</span>==<span class="n">10</span></code>
. The result for characters<br>
<code class="inline"><span class="q">"g"</span>..<span class="q">"z"</span></code>
and <code class="inline"><span class="q">"G"</span>..<span class="q">"Z"</span></code>
is not well-defined.</p>
<p>Starting from the beginning of the input string of pack(), each pair<br>
of characters is converted to 1 character of output. With format <code class="inline"><span class="w">h</span></code>
the<br>
first character of the pair determines the least-significant nybble of the<br>
output character, and with format <code class="inline"><span class="w">H</span></code>
it determines the most-significant<br>
nybble.</p>
<p>If the length of the input string is not even, it behaves as if padded<br>
by a null character at the end. Similarly, during unpack()ing the "extra"<br>
nybbles are ignored.</p>
<p>If the input string of pack() is longer than needed, extra characters are<br>
ignored.<br>
A <code class="inline"><span class="i">*</span></code>
for the repeat count of pack() means to use all the characters of<br>
the input field. On unpack()ing the nybbles are converted to a string<br>
of hexadecimal digits.</p>
</li>
<li>
<p>The <code class="inline"><span class="w">p</span></code>
type packs a pointer to a null-terminated string. You are<br>
responsible for ensuring the string is not a temporary value (which can<br>
potentially get deallocated before you get around to using the packed result).<br>
The <code class="inline"><span class="w">P</span></code>
type packs a pointer to a structure of the size indicated by the<br>
length. A NULL pointer is created if the corresponding value for <code class="inline"><span class="w">p</span></code>
or<br>
<code class="inline"><span class="w">P</span></code>
is <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code>, similarly for unpack().</p>
<p>If your system has a strange pointer size (i.e. a pointer is neither as<br>
big as an int nor as big as a long), it may not be possible to pack or<br>
unpack pointers in big- or little-endian byte order. Attempting to do<br>
so will result in a fatal error.</p>
</li>
<li>
<p>The <code class="inline">/</code> template character allows packing and unpacking of a sequence of<br>
items where the packed structure contains a packed item count followed by <br>
the packed items themselves.</p>
<p>For <code class="inline"><a class="l_k" href="../functions/pack.html">pack</a></code> you write <i>length-item</i><code class="inline">/</code><i>sequence-item</i> and the<br>
<i>length-item</i> describes how the length value is packed. The ones likely<br>
to be of most use are integer-packing ones like <code class="inline"><span class="w">n</span></code>
(for Java strings),<br>
<code class="inline"><span class="w">w</span></code>
(for ASN.1 or SNMP) and <code class="inline"><span class="w">N</span></code>
(for Sun XDR).</p>
<p>For <code class="inline"><a class="l_k" href="../functions/pack.html">pack</a></code>, the <i>sequence-item</i> may have a repeat count, in which case<br>
the minimum of that and the number of available items is used as argument<br>
for the <i>length-item</i>. If it has no repeat count or uses a '*', the number<br>
of available items is used.</p>
<p>For <code class="inline"><a class="l_k" href="../functions/unpack.html">unpack</a></code> an internal stack of integer arguments unpacked so far is<br>
used. You write <code class="inline">/</code><i>sequence-item</i> and the repeat count is obtained by<br>
popping off the last element from the stack. The <i>sequence-item</i> must not<br>
have a repeat count.</p>
<p>If the <i>sequence-item</i> refers to a string type (<code class="inline"><span class="q">"A"</span></code>
, <code class="inline"><span class="q">"a"</span></code>
or <code class="inline"><span class="q">"Z"</span></code>
),<br>
the <i>length-item</i> is a string length, not a number of strings. If there is<br>
an explicit repeat count for pack, the packed string will be adjusted to that<br>
given length.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/unpack.html">unpack</a> <span class="q">'W/a'</span><span class="cm">,</span> <span class="q">"\04Gurusamy"</span><span class="sc">;</span> <span class="w">gives</span> <span class="s">(</span><span class="q">'Guru'</span><span class="s">)</span></li><li> <a class="l_k" href="../functions/unpack.html">unpack</a> <span class="q">'a3/A A*'</span><span class="cm">,</span> <span class="q">'007 Bond J '</span><span class="sc">;</span> <span class="w">gives</span> <span class="s">(</span><span class="q">' Bond'</span><span class="cm">,</span> <span class="q">'J'</span><span class="s">)</span></li><li> <a class="l_k" href="../functions/unpack.html">unpack</a> <span class="q">'a3 x2 /A A*'</span><span class="cm">,</span> <span class="q">'007: Bond, J.'</span><span class="sc">;</span> <span class="w">gives</span> <span class="s">(</span><span class="q">'Bond, J'</span><span class="cm">,</span> <span class="q">'.'</span><span class="s">)</span></li><li> <a class="l_k" href="../functions/pack.html">pack</a> <span class="q">'n/a* w/a'</span><span class="cm">,</span><span class="q">'hello,'</span><span class="cm">,</span><span class="q">'world'</span><span class="sc">;</span> <span class="w">gives</span> <span class="q">"\000\006hello,\005world"</span></li><li> <a class="l_k" href="../functions/pack.html">pack</a> <span class="q">'a/W2'</span><span class="cm">,</span> <a class="l_k" href="../functions/ord.html">ord</a><span class="s">(</span><span class="q">'a'</span><span class="s">)</span> .. <a class="l_k" href="../functions/ord.html">ord</a><span class="s">(</span><span class="q">'z'</span><span class="s">)</span><span class="sc">;</span> <span class="w">gives</span> <span class="q">'2ab'</span></li></ol></pre><p>The <i>length-item</i> is not returned explicitly from <code class="inline"><a class="l_k" href="../functions/unpack.html">unpack</a></code>.</p>
<p>Adding a count to the <i>length-item</i> letter is unlikely to do anything<br>
useful, unless that letter is <code class="inline"><span class="w">A</span></code>
, <code class="inline"><span class="w">a</span></code>
or <code class="inline"><span class="w">Z</span></code>
. Packing with a<br>
<i>length-item</i> of <code class="inline"><span class="w">a</span></code>
or <code class="inline"><span class="w">Z</span></code>
may introduce <code class="inline"><span class="q">"\000"</span></code>
characters,<br>
which Perl does not regard as legal in numeric strings.</p>
</li>
<li>
<p>The integer types <code class="inline"><a class="l_k" href="../functions/s.html">s</a></code>, <code class="inline"><span class="w">S</span></code>
, <code class="inline"><span class="w">l</span></code>
, and <code class="inline"><span class="w">L</span></code>
may be<br>
followed by a <code class="inline">!</code>
modifier to signify native shorts or<br>
longs--as you can see from above for example a bare <code class="inline"><span class="w">l</span></code>
does mean<br>
exactly 32 bits, the native <code class="inline"><span class="w">long</span></code>
(as seen by the local C compiler)<br>
may be larger. This is an issue mainly in 64-bit platforms. You can<br>
see whether using <code class="inline">!</code>
makes any difference by</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/length.html">length</a><span class="s">(</span><a class="l_k" href="../functions/pack.html">pack</a><span class="s">(</span><span class="q">"s"</span><span class="s">)</span><span class="s">)</span><span class="cm">,</span> <span class="q">" "</span><span class="cm">,</span> <a class="l_k" href="../functions/length.html">length</a><span class="s">(</span><a class="l_k" href="../functions/pack.html">pack</a><span class="s">(</span><span class="q">"s!"</span><span class="s">)</span><span class="s">)</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/length.html">length</a><span class="s">(</span><a class="l_k" href="../functions/pack.html">pack</a><span class="s">(</span><span class="q">"l"</span><span class="s">)</span><span class="s">)</span><span class="cm">,</span> <span class="q">" "</span><span class="cm">,</span> <a class="l_k" href="../functions/length.html">length</a><span class="s">(</span><a class="l_k" href="../functions/pack.html">pack</a><span class="s">(</span><span class="q">"l!"</span><span class="s">)</span><span class="s">)</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li></ol></pre><p><code class="inline"><span class="w">i</span>!</code>
and <code class="inline"><span class="w">I</span>!</code>
also work but only because of completeness;<br>
they are identical to <code class="inline"><span class="w">i</span></code>
and <code class="inline"><span class="w">I</span></code>
.</p>
<p>The actual sizes (in bytes) of native shorts, ints, longs, and long<br>
longs on the platform where Perl was built are also available via<br>
<a href="../Config.html">Config</a>:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Config</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$Config</span>{<span class="w">shortsize</span>}<span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$Config</span>{<span class="w">intsize</span>}<span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$Config</span>{<span class="w">longsize</span>}<span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$Config</span>{<span class="w">longlongsize</span>}<span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li></ol></pre><p>(The <code class="inline"><span class="i">$Config</span>{<span class="w">longlongsize</span>}</code>
will be undefined if your system does<br>
not support long longs.)</p>
</li>
<li>
<p>The integer formats <code class="inline"><a class="l_k" href="../functions/s.html">s</a></code>, <code class="inline"><span class="w">S</span></code>
, <code class="inline"><span class="w">i</span></code>
, <code class="inline"><span class="w">I</span></code>
, <code class="inline"><span class="w">l</span></code>
, <code class="inline"><span class="w">L</span></code>
, <code class="inline"><span class="w">j</span></code>
, and <code class="inline"><span class="w">J</span></code>
<br>
are inherently non-portable between processors and operating systems<br>
because they obey the native byteorder and endianness. For example a<br>
4-byte integer 0x12345678 (305419896 decimal) would be ordered natively<br>
(arranged in and handled by the CPU registers) into bytes as</p>
<pre class="verbatim"><ol><li> 0x12 0x34 0x56 0x78 # big-endian</li><li> 0x78 0x56 0x34 0x12 # little-endian</li></ol></pre><p>Basically, the Intel and VAX CPUs are little-endian, while everybody<br>
else, for example Motorola m68k/88k, PPC, Sparc, HP PA, Power, and<br>
Cray are big-endian. Alpha and MIPS can be either: Digital/Compaq<br>
used/uses them in little-endian mode; SGI/Cray uses them in big-endian<br>
mode.</p>
<p>The names `big-endian' and `little-endian' are comic references to<br>
the classic "Gulliver's Travels" (via the paper "On Holy Wars and a<br>
Plea for Peace" by Danny Cohen, USC/ISI IEN 137, April 1, 1980) and<br>
the egg-eating habits of the Lilliputians.</p>
<p>Some systems may have even weirder byte orders such as</p>
<pre class="verbatim"><ol><li> 0x56 0x78 0x12 0x34</li><li> 0x34 0x12 0x78 0x56</li></ol></pre><p>You can see your system's preference with</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/join.html">join</a><span class="s">(</span><span class="q">" "</span><span class="cm">,</span> <a class="l_k" href="../functions/map.html">map</a> <span class="s">{</span> <a class="l_k" href="../functions/sprintf.html">sprintf</a> <span class="q">"%#02x"</span><span class="cm">,</span> <span class="i">$_</span> <span class="s">}</span></li><li> <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">"W*"</span><span class="cm">,</span><a class="l_k" href="../functions/pack.html">pack</a><span class="s">(</span><span class="q">"L"</span><span class="cm">,</span><span class="n">0x12345678</span><span class="s">)</span><span class="s">)</span><span class="s">)</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li></ol></pre><p>The byteorder on the platform where Perl was built is also available<br>
via <a href="../Config.html">Config</a>:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Config</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$Config</span>{<span class="w">byteorder</span>}<span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li></ol></pre><p>Byteorders <code class="inline"><span class="q">'1234'</span></code>
and <code class="inline"><span class="q">'12345678'</span></code>
are little-endian, <code class="inline"><span class="q">'4321'</span></code>
<br>
and <code class="inline"><span class="q">'87654321'</span></code>
are big-endian.</p>
<p>If you want portable packed integers you can either use the formats<br>
<code class="inline"><span class="w">n</span></code>
, <code class="inline"><span class="w">N</span></code>
, <code class="inline"><span class="w">v</span></code>
, and <code class="inline"><span class="w">V</span></code>
, or you can use the <code class="inline">></code> and <code class="inline"><</code>
<br>
modifiers. These modifiers are only available as of perl 5.9.2.<br>
See also <a href="../perlport.html">perlport</a>.</p>
</li>
<li>
<p>All integer and floating point formats as well as <code class="inline"><span class="w">p</span></code>
and <code class="inline"><span class="w">P</span></code>
and<br>
<code class="inline"><span class="s">(</span><span class="s">)</span></code>
-groups may be followed by the <code class="inline">></code> or <code class="inline"><</code>
modifiers<br>
to force big- or little- endian byte-order, respectively.<br>
This is especially useful, since <code class="inline"><span class="w">n</span></code>
, <code class="inline"><span class="w">N</span></code>
, <code class="inline"><span class="w">v</span></code>
and <code class="inline"><span class="w">V</span></code>
don't cover<br>
signed integers, 64-bit integers and floating point values. However,<br>
there are some things to keep in mind.</p>
<p>Exchanging signed integers between different platforms only works<br>
if all platforms store them in the same format. Most platforms store<br>
signed integers in two's complement, so usually this is not an issue.</p>
<p>The <code class="inline">></code> or <code class="inline"><</code>
modifiers can only be used on floating point<br>
formats on big- or little-endian machines. Otherwise, attempting to<br>
do so will result in a fatal error.</p>
<p>Forcing big- or little-endian byte-order on floating point values for<br>
data exchange can only work if all platforms are using the same<br>
binary representation (e.g. IEEE floating point format). Even if all<br>
platforms are using IEEE, there may be subtle differences. Being able<br>
to use <code class="inline">></code> or <code class="inline"><</code>
on floating point values can be very useful,<br>
but also very dangerous if you don't know exactly what you're doing.<br>
It is definitely not a general way to portably store floating point<br>
values.</p>
<p>When using <code class="inline">></code> or <code class="inline"><</code>
on an <code class="inline"><span class="s">(</span><span class="s">)</span></code>
-group, this will affect<br>
all types inside the group that accept the byte-order modifiers,<br>
including all subgroups. It will silently be ignored for all other<br>
types. You are not allowed to override the byte-order within a group<br>
that already has a byte-order modifier suffix.</p>
</li>
<li>
<p>Real numbers (floats and doubles) are in the native machine format only;<br>
due to the multiplicity of floating formats around, and the lack of a<br>
standard "network" representation, no facility for interchange has been<br>
made. This means that packed floating point data written on one machine<br>
may not be readable on another - even if both use IEEE floating point<br>
arithmetic (as the endian-ness of the memory representation is not part<br>
of the IEEE spec). See also <a href="../perlport.html">perlport</a>.</p>
<p>If you know exactly what you're doing, you can use the <code class="inline">></code> or <code class="inline"><</code>
<br>
modifiers to force big- or little-endian byte-order on floating point values.</p>
<p>Note that Perl uses doubles (or long doubles, if configured) internally for<br>
all numeric calculation, and converting from double into float and thence back<br>
to double again will lose precision (i.e., <code class="inline">unpack("f", pack("f", $foo)</code>)<br>
will not in general equal $foo).</p>
</li>
<li>
<p>Pack and unpack can operate in two modes, character mode (<code class="inline"><span class="w">C0</span></code>
mode) where<br>
the packed string is processed per character and UTF-8 mode (<code class="inline"><span class="w">U0</span></code>
mode)<br>
where the packed string is processed in its UTF-8-encoded Unicode form on<br>
a byte by byte basis. Character mode is the default unless the format string <br>
starts with an <code class="inline"><span class="w">U</span></code>
. You can switch mode at any moment with an explicit <br>
<code class="inline"><span class="w">C0</span></code>
or <code class="inline"><span class="w">U0</span></code>
in the format. A mode is in effect until the next mode switch <br>
or until the end of the ()-group in which it was entered.</p>
</li>
<li>
<p>You must yourself do any alignment or padding by inserting for example<br>
enough <code class="inline"><span class="q">'x'</span></code>
es while packing. There is no way to pack() and unpack()<br>
could know where the characters are going to or coming from. Therefore<br>
<code class="inline"><a class="l_k" href="../functions/pack.html">pack</a></code> (and <code class="inline"><a class="l_k" href="../functions/unpack.html">unpack</a></code>) handle their output and input as flat<br>
sequences of characters.</p>
</li>
<li>
<p>A ()-group is a sub-TEMPLATE enclosed in parentheses. A group may<br>
take a repeat count, both as postfix, and for unpack() also via the <code class="inline">/</code>
template character. Within each repetition of a group, positioning with<br>
<code class="inline"><span class="i">@</span></code>
starts again at 0. Therefore, the result of</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/pack.html">pack</a><span class="s">(</span> <span class="q">'@1A((@2A)@3A)'</span><span class="cm">,</span> <span class="q">'a'</span><span class="cm">,</span> <span class="q">'b'</span><span class="cm">,</span> <span class="q">'c'</span> <span class="s">)</span></li></ol></pre><p>is the string "\0a\0\0bc".</p>
</li>
<li>
<p><code class="inline"><span class="w">x</span></code>
and <code class="inline"><span class="w">X</span></code>
accept <code class="inline">!</code>
modifier. In this case they act as<br>
alignment commands: they jump forward/back to the closest position<br>
aligned at a multiple of <code class="inline"><span class="w">count</span></code>
characters. For example, to pack() or<br>
unpack() C's <code class="inline"><span class="i">struct</span> <span class="s">{</span><span class="w">char</span> <span class="w">c</span><span class="sc">;</span> <span class="w">double</span> <span class="w">d</span><span class="sc">;</span> <span class="w">char</span> <span class="w">cc</span><span class="s">[</span><span class="n">2</span><span class="s">]</span><span class="s">}</span></code>
one may need to<br>
use the template <code class="inline"><span class="w">W</span> <span class="w">x</span>!<span class="s">[</span><span class="w">d</span><span class="s">]</span> <span class="w">d</span> <span class="w">W</span><span class="s">[</span><span class="n">2</span><span class="s">]</span></code>
; this assumes that doubles must be<br>
aligned on the double's size.</p>
<p>For alignment commands <code class="inline"><span class="w">count</span></code>
of 0 is equivalent to <code class="inline"><span class="w">count</span></code>
of 1;<br>
both result in no-ops.</p>
</li>
<li>
<p><code class="inline"><span class="w">n</span></code>
, <code class="inline"><span class="w">N</span></code>
, <code class="inline"><span class="w">v</span></code>
and <code class="inline"><span class="w">V</span></code>
accept the <code class="inline">!</code>
modifier. In this case they<br>
will represent signed 16-/32-bit integers in big-/little-endian order.<br>
This is only portable if all platforms sharing the packed data use the<br>
same binary representation for signed integers (e.g. all platforms are<br>
using two's complement representation).</p>
</li>
<li>
<p>A comment in a TEMPLATE starts with <code class="inline"><span class="c">#</span></code>
and goes to the end of line.<br>
White space may be used to separate pack codes from each other, but<br>
modifiers and a repeat count must follow immediately.</p>
</li>
<li>
<p>If TEMPLATE requires more arguments to pack() than actually given, pack()<br>
assumes additional <code class="inline"><span class="q">""</span></code>
arguments. If TEMPLATE requires fewer arguments<br>
to pack() than actually given, extra arguments are ignored.]]></desc>
</keyword>
<keyword name="package" type="function">
<params>
<param name='namespace'/>
</params>
<desc><![CDATA[Declares the compilation unit as being in the given namespace. The scope<br>
of the package declaration is from the declaration itself through the end<br>
of the enclosing block, file, or eval (the same as the <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code> operator).<br>
All further unqualified dynamic identifiers will be in this namespace.<br>
A package statement affects only dynamic variables--including those<br>
you've used <code class="inline"><a class="l_k" href="../functions/local.html">local</a></code> on--but <i>not</i> lexical variables, which are created<br>
with <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code>. Typically it would be the first declaration in a file to<br>
be included by the <code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> or <code class="inline"><a class="l_k" href="../functions/use.html">use</a></code> operator. You can switch into a<br>
package in more than one place; it merely influences which symbol table<br>
is used by the compiler for the rest of that block. You can refer to<br>
variables and filehandles in other packages by prefixing the identifier<br>
with the package name and a double colon: <code class="inline"><span class="i">$Package::Variable</span></code>
.<br>
If the package name is null, the <code class="inline"><span class="w">main</span></code>
package as assumed. That is,<br>
<code class="inline"><span class="i">$::sail</span></code>
is equivalent to <code class="inline"><span class="i">$main::sail</span></code>
(as well as to <code class="inline"><span class="i">$main'sail</span></code>
,<br>
still seen in older code).</p>
<p>See <a href="../perlmod.html#Packages">"Packages" in perlmod</a> for more information about packages, modules,<br>
and classes. See <a href="../perlsub.html">perlsub</a> for other scoping issues.]]></desc>
</keyword>
<keyword name="package" type="function">
<params>
</params>
<desc><![CDATA[Declares the compilation unit as being in the given namespace. The scope<br>
of the package declaration is from the declaration itself through the end<br>
of the enclosing block, file, or eval (the same as the <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code> operator).<br>
All further unqualified dynamic identifiers will be in this namespace.<br>
A package statement affects only dynamic variables--including those<br>
you've used <code class="inline"><a class="l_k" href="../functions/local.html">local</a></code> on--but <i>not</i> lexical variables, which are created<br>
with <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code>. Typically it would be the first declaration in a file to<br>
be included by the <code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> or <code class="inline"><a class="l_k" href="../functions/use.html">use</a></code> operator. You can switch into a<br>
package in more than one place; it merely influences which symbol table<br>
is used by the compiler for the rest of that block. You can refer to<br>
variables and filehandles in other packages by prefixing the identifier<br>
with the package name and a double colon: <code class="inline"><span class="i">$Package::Variable</span></code>
.<br>
If the package name is null, the <code class="inline"><span class="w">main</span></code>
package as assumed. That is,<br>
<code class="inline"><span class="i">$::sail</span></code>
is equivalent to <code class="inline"><span class="i">$main::sail</span></code>
(as well as to <code class="inline"><span class="i">$main'sail</span></code>
,<br>
still seen in older code).</p>
<p>See <a href="../perlmod.html#Packages">"Packages" in perlmod</a> for more information about packages, modules,<br>
and classes. See <a href="../perlsub.html">perlsub</a> for other scoping issues.]]></desc>
</keyword>
<keyword name="pipe" type="function">
<params>
<param name='readhandle'/>
<param name='writehandle'/>
</params>
<desc><![CDATA[Opens a pair of connected pipes like the corresponding system call.<br>
Note that if you set up a loop of piped processes, deadlock can occur<br>
unless you are very careful. In addition, note that Perl's pipes use<br>
IO buffering, so you may need to set <code class="inline"><span class="i">$|</span></code>
to flush your WRITEHANDLE<br>
after each command, depending on the application.</p>
<p>See <a href="../IPC/Open2.html">IPC::Open2</a>, <a href="../IPC/Open3.html">IPC::Open3</a>, and <a href="../perlipc.html#Bidirectional-Communication">"Bidirectional Communication" in perlipc</a>
for examples of such things.</p>
<p>On systems that support a close-on-exec flag on files, the flag will be set<br>
for the newly opened file descriptors as determined by the value of $^F.<br>
See <a href="../perlvar.html#%24%5eF">"$^F" in perlvar</a>.]]></desc>
</keyword>
<keyword name="pop" type="function">
<params>
<param name='array'/>
</params>
<desc><![CDATA[Pops and returns the last value of the array, shortening the array by<br>
one element.</p>
<p>If there are no elements in the array, returns the undefined value<br>
(although this may happen at other times as well). If ARRAY is<br>
omitted, pops the <code class="inline"><span class="i">@ARGV</span></code>
array in the main program, and the <code class="inline"><span class="i">@_</span></code>
<br>
array in subroutines, just like <code class="inline"><a class="l_k" href="../functions/shift.html">shift</a></code>.]]></desc>
</keyword>
<keyword name="pop" type="function">
<params>
</params>
<desc><![CDATA[Pops and returns the last value of the array, shortening the array by<br>
one element.</p>
<p>If there are no elements in the array, returns the undefined value<br>
(although this may happen at other times as well). If ARRAY is<br>
omitted, pops the <code class="inline"><span class="i">@ARGV</span></code>
array in the main program, and the <code class="inline"><span class="i">@_</span></code>
<br>
array in subroutines, just like <code class="inline"><a class="l_k" href="../functions/shift.html">shift</a></code>.]]></desc>
</keyword>
<keyword name="pos" type="function">
<params>
<param name='scalar'/>
</params>
<desc><![CDATA[Returns the offset of where the last <code class="inline"><a class="l_k" href="../functions/m.html">m//g</a></code> search left off for the variable<br>
in question (<code class="inline"><span class="i">$_</span></code>
is used when the variable is not specified). Note that<br>
0 is a valid match offset. <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> indicates that the search position<br>
is reset (usually due to match failure, but can also be because no match has<br>
yet been performed on the scalar). <code class="inline"><a class="l_k" href="../functions/pos.html">pos</a></code> directly accesses the location used<br>
by the regexp engine to store the offset, so assigning to <code class="inline"><a class="l_k" href="../functions/pos.html">pos</a></code> will change<br>
that offset, and so will also influence the <code class="inline">\<span class="w">G</span></code>
zero-width assertion in<br>
regular expressions. Because a failed <code class="inline"><a class="l_k" href="../functions/m.html">m//gc</a></code> match doesn't reset the offset,<br>
the return from <code class="inline"><a class="l_k" href="../functions/pos.html">pos</a></code> won't change either in this case. See <a href="../perlre.html">perlre</a> and<br>
<a href="../perlop.html">perlop</a>.]]></desc>
</keyword>
<keyword name="pos" type="function">
<params>
</params>
<desc><![CDATA[Returns the offset of where the last <code class="inline"><a class="l_k" href="../functions/m.html">m//g</a></code> search left off for the variable<br>
in question (<code class="inline"><span class="i">$_</span></code>
is used when the variable is not specified). Note that<br>
0 is a valid match offset. <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> indicates that the search position<br>
is reset (usually due to match failure, but can also be because no match has<br>
yet been performed on the scalar). <code class="inline"><a class="l_k" href="../functions/pos.html">pos</a></code> directly accesses the location used<br>
by the regexp engine to store the offset, so assigning to <code class="inline"><a class="l_k" href="../functions/pos.html">pos</a></code> will change<br>
that offset, and so will also influence the <code class="inline">\<span class="w">G</span></code>
zero-width assertion in<br>
regular expressions. Because a failed <code class="inline"><a class="l_k" href="../functions/m.html">m//gc</a></code> match doesn't reset the offset,<br>
the return from <code class="inline"><a class="l_k" href="../functions/pos.html">pos</a></code> won't change either in this case. See <a href="../perlre.html">perlre</a> and<br>
<a href="../perlop.html">perlop</a>.]]></desc>
</keyword>
<keyword name="print" type="function">
<params>
<param name='filehandle list'/>
</params>
<desc><![CDATA[Prints a string or a list of strings. Returns true if successful.<br>
FILEHANDLE may be a scalar variable name, in which case the variable<br>
contains the name of or a reference to the filehandle, thus introducing<br>
one level of indirection. (NOTE: If FILEHANDLE is a variable and<br>
the next token is a term, it may be misinterpreted as an operator<br>
unless you interpose a <code class="inline">+</code>
or put parentheses around the arguments.)<br>
If FILEHANDLE is omitted, prints by default to standard output (or<br>
to the last selected output channel--see <a href="../functions/select.html">"select"</a>). If LIST is<br>
also omitted, prints <code class="inline"><span class="i">$_</span></code>
to the currently selected output channel.<br>
To set the default output channel to something other than STDOUT<br>
use the select operation. The current value of <code class="inline"><span class="i">$,</span></code>
(if any) is<br>
printed between each LIST item. The current value of <code class="inline"><span class="i">$\</span></code>
(if<br>
any) is printed after the entire LIST has been printed. Because<br>
print takes a LIST, anything in the LIST is evaluated in list<br>
context, and any subroutine that you call will have one or more of<br>
its expressions evaluated in list context. Also be careful not to<br>
follow the print keyword with a left parenthesis unless you want<br>
the corresponding right parenthesis to terminate the arguments to<br>
the print--interpose a <code class="inline">+</code>
or put parentheses around all the<br>
arguments.</p>
<p>Note that if you're storing FILEHANDLEs in an array, or if you're using<br>
any other expression more complex than a scalar variable to retrieve it,<br>
you will have to use a block returning the filehandle value instead:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <span class="s">{</span> <span class="i">$files</span>[<span class="i">$i</span>] <span class="s">}</span> <span class="q">"stuff\n"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="s">{</span> <span class="i">$OK</span> ? <span class="w">STDOUT</span> <span class="co">:</span> <span class="w">STDERR</span> <span class="s">}</span> <span class="q">"stuff\n"</span><span class="sc">;</span></li></ol><]]></desc>
</keyword>
<keyword name="print" type="function">
<params>
<param name='list'/>
</params>
<desc><![CDATA[Prints a string or a list of strings. Returns true if successful.<br>
FILEHANDLE may be a scalar variable name, in which case the variable<br>
contains the name of or a reference to the filehandle, thus introducing<br>
one level of indirection. (NOTE: If FILEHANDLE is a variable and<br>
the next token is a term, it may be misinterpreted as an operator<br>
unless you interpose a <code class="inline">+</code>
or put parentheses around the arguments.)<br>
If FILEHANDLE is omitted, prints by default to standard output (or<br>
to the last selected output channel--see <a href="../functions/select.html">"select"</a>). If LIST is<br>
also omitted, prints <code class="inline"><span class="i">$_</span></code>
to the currently selected output channel.<br>
To set the default output channel to something other than STDOUT<br>
use the select operation. The current value of <code class="inline"><span class="i">$,</span></code>
(if any) is<br>
printed between each LIST item. The current value of <code class="inline"><span class="i">$\</span></code>
(if<br>
any) is printed after the entire LIST has been printed. Because<br>
print takes a LIST, anything in the LIST is evaluated in list<br>
context, and any subroutine that you call will have one or more of<br>
its expressions evaluated in list context. Also be careful not to<br>
follow the print keyword with a left parenthesis unless you want<br>
the corresponding right parenthesis to terminate the arguments to<br>
the print--interpose a <code class="inline">+</code>
or put parentheses around all the<br>
arguments.</p>
<p>Note that if you're storing FILEHANDLEs in an array, or if you're using<br>
any other expression more complex than a scalar variable to retrieve it,<br>
you will have to use a block returning the filehandle value instead:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <span class="s">{</span> <span class="i">$files</span>[<span class="i">$i</span>] <span class="s">}</span> <span class="q">"stuff\n"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="s">{</span> <span class="i">$OK</span> ? <span class="w">STDOUT</span> <span class="co">:</span> <span class="w">STDERR</span> <span class="s">}</span> <span class="q">"stuff\n"</span><span class="sc">;</span></li></ol><]]></desc>
</keyword>
<keyword name="print" type="function">
<params>
</params>
<desc><![CDATA[Prints a string or a list of strings. Returns true if successful.<br>
FILEHANDLE may be a scalar variable name, in which case the variable<br>
contains the name of or a reference to the filehandle, thus introducing<br>
one level of indirection. (NOTE: If FILEHANDLE is a variable and<br>
the next token is a term, it may be misinterpreted as an operator<br>
unless you interpose a <code class="inline">+</code>
or put parentheses around the arguments.)<br>
If FILEHANDLE is omitted, prints by default to standard output (or<br>
to the last selected output channel--see <a href="../functions/select.html">"select"</a>). If LIST is<br>
also omitted, prints <code class="inline"><span class="i">$_</span></code>
to the currently selected output channel.<br>
To set the default output channel to something other than STDOUT<br>
use the select operation. The current value of <code class="inline"><span class="i">$,</span></code>
(if any) is<br>
printed between each LIST item. The current value of <code class="inline"><span class="i">$\</span></code>
(if<br>
any) is printed after the entire LIST has been printed. Because<br>
print takes a LIST, anything in the LIST is evaluated in list<br>
context, and any subroutine that you call will have one or more of<br>
its expressions evaluated in list context. Also be careful not to<br>
follow the print keyword with a left parenthesis unless you want<br>
the corresponding right parenthesis to terminate the arguments to<br>
the print--interpose a <code class="inline">+</code>
or put parentheses around all the<br>
arguments.</p>
<p>Note that if you're storing FILEHANDLEs in an array, or if you're using<br>
any other expression more complex than a scalar variable to retrieve it,<br>
you will have to use a block returning the filehandle value instead:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <span class="s">{</span> <span class="i">$files</span>[<span class="i">$i</span>] <span class="s">}</span> <span class="q">"stuff\n"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="s">{</span> <span class="i">$OK</span> ? <span class="w">STDOUT</span> <span class="co">:</span> <span class="w">STDERR</span> <span class="s">}</span> <span class="q">"stuff\n"</span><span class="sc">;</span></li></ol><]]></desc>
</keyword>
<keyword name="printf" type="function">
<params>
<param name='filehandle format'/>
<param name='list'/>
</params>
<desc><![CDATA[Equivalent to <code class="inline"><a class="l_k" href="../functions/print.html">print</a> <span class="i">FILEHANDLE</span> <a class="l_k" href="../functions/sprintf.html">sprintf</a><span class="s">(</span><span class="w">FORMAT</span><span class="cm">,</span> <span class="w">LIST</span><span class="s">)</span></code>
, except that <code class="inline"><span class="i">$\</span></code>
<br>
(the output record separator) is not appended. The first argument<br>
of the list will be interpreted as the <code class="inline"><a class="l_k" href="../functions/printf.html">printf</a></code> format. See <code class="inline"><a class="l_k" href="../functions/sprintf.html">sprintf</a></code>
for an explanation of the format argument. If <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">locale</span></code>
is in effect,<br>
and POSIX::setlocale() has been called, the character used for the decimal<br>
separator in formatted floating point numbers is affected by the LC_NUMERIC<br>
locale. See <a href="../perllocale.html">perllocale</a> and <a href="../POSIX.html">POSIX</a>.</p>
<p>Don't fall into the trap of using a <code class="inline"><a class="l_k" href="../functions/printf.html">printf</a></code> when a simple<br>
<code class="inline"><a class="l_k" href="../functions/print.html">print</a></code> would do. The <code class="inline"><a class="l_k" href="../functions/print.html">print</a></code> is more efficient and less<br>
error prone.]]></desc>
</keyword>
<keyword name="printf" type="function">
<params>
<param name='format'/>
<param name='list'/>
</params>
<desc><![CDATA[Equivalent to <code class="inline"><a class="l_k" href="../functions/print.html">print</a> <span class="i">FILEHANDLE</span> <a class="l_k" href="../functions/sprintf.html">sprintf</a><span class="s">(</span><span class="w">FORMAT</span><span class="cm">,</span> <span class="w">LIST</span><span class="s">)</span></code>
, except that <code class="inline"><span class="i">$\</span></code>
<br>
(the output record separator) is not appended. The first argument<br>
of the list will be interpreted as the <code class="inline"><a class="l_k" href="../functions/printf.html">printf</a></code> format. See <code class="inline"><a class="l_k" href="../functions/sprintf.html">sprintf</a></code>
for an explanation of the format argument. If <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">locale</span></code>
is in effect,<br>
and POSIX::setlocale() has been called, the character used for the decimal<br>
separator in formatted floating point numbers is affected by the LC_NUMERIC<br>
locale. See <a href="../perllocale.html">perllocale</a> and <a href="../POSIX.html">POSIX</a>.</p>
<p>Don't fall into the trap of using a <code class="inline"><a class="l_k" href="../functions/printf.html">printf</a></code> when a simple<br>
<code class="inline"><a class="l_k" href="../functions/print.html">print</a></code> would do. The <code class="inline"><a class="l_k" href="../functions/print.html">print</a></code> is more efficient and less<br>
error prone.]]></desc>
</keyword>
<keyword name="prototype" type="function">
<params>
<param name='function'/>
</params>
<desc><![CDATA[Returns the prototype of a function as a string (or <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> if the<br>
function has no prototype). FUNCTION is a reference to, or the name of,<br>
the function whose prototype you want to retrieve.</p>
<p>If FUNCTION is a string starting with <code class="inline"><span class="w">CORE::</span></code>
, the rest is taken as a<br>
name for Perl builtin. If the builtin is not <i>overridable</i> (such as<br>
<code class="inline"><a class="l_k" href="../functions/qw.html">qw//</a></code>) or if its arguments cannot be adequately expressed by a prototype<br>
(such as <code class="inline"><a class="l_k" href="../functions/system.html">system</a></code>), prototype() returns <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code>, because the builtin<br>
does not really behave like a Perl function. Otherwise, the string<br>
describing the equivalent prototype is returned.]]></desc>
</keyword>
<keyword name="push" type="function">
<params>
<param name='array'/>
<param name='list'/>
</params>
<desc><![CDATA[Treats ARRAY as a stack, and pushes the values of LIST<br>
onto the end of ARRAY. The length of ARRAY increases by the length of<br>
LIST. Has the same effect as</p>
<pre class="verbatim"><ol><li> for <span class="i">$value</span> <span class="s">(</span><span class="w">LIST</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ARRAY</span>[++<span class="i">$#ARRAY</span>] = <span class="i">$value</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>but is more efficient. Returns the number of elements in the array following<br>
the completed <code class="inline"><a class="l_k" href="../functions/push.html">push</a></code>.]]></desc>
</keyword>
<keyword name="q" type="function">
<params>
<param name='/string/'/>
</params>
<desc><![CDATA[Generalized quotes. See <a href="../perlop.html#Quote-Like-Operators">"Quote-Like Operators" in perlop</a>.]]></desc>
</keyword>
<keyword name="q" type="function">
<params>
<param name='q/string/'/>
</params>
<desc><![CDATA[Generalized quotes. See <a href="../perlop.html#Quote-Like-Operators">"Quote-Like Operators" in perlop</a>.]]></desc>
</keyword>
<keyword name="q" type="function">
<params>
<param name='w/string/'/>
</params>
<desc><![CDATA[Generalized quotes. See <a href="../perlop.html#Quote-Like-Operators">"Quote-Like Operators" in perlop</a>.]]></desc>
</keyword>
<keyword name="q" type="function">
<params>
<param name='x/string/'/>
</params>
<desc><![CDATA[Generalized quotes. See <a href="../perlop.html#Quote-Like-Operators">"Quote-Like Operators" in perlop</a>.]]></desc>
</keyword>
<keyword name="qq" type="function">
<params>
<param name='/string/'/>
</params>
<desc><![CDATA[Generalized quotes. See <a href="../perlop.html#Quote-Like-Operators">"Quote-Like Operators" in perlop</a>.]]></desc>
</keyword>
<keyword name="qr" type="function">
<params>
<param name='/string/'/>
</params>
<desc><![CDATA[Regexp-like quote. See <a href="../perlop.html#Regexp-Quote-Like-Operators">"Regexp Quote-Like Operators" in perlop</a>.]]></desc>
</keyword>
<keyword name="quotemeta" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Returns the value of EXPR with all non-"word"<br>
characters backslashed. (That is, all characters not matching<br>
<code class="inline"><span class="q">/[A-Za-z_0-9]/</span></code>
will be preceded by a backslash in the<br>
returned string, regardless of any locale settings.)<br>
This is the internal function implementing<br>
the <code class="inline">\<span class="w">Q</span></code>
escape in double-quoted strings.</p>
<p>If EXPR is omitted, uses <code class="inline"><span class="i">$_</span></code>
.]]></desc>
</keyword>
<keyword name="quotemeta" type="function">
<params>
</params>
<desc><![CDATA[Returns the value of EXPR with all non-"word"<br>
characters backslashed. (That is, all characters not matching<br>
<code class="inline"><span class="q">/[A-Za-z_0-9]/</span></code>
will be preceded by a backslash in the<br>
returned string, regardless of any locale settings.)<br>
This is the internal function implementing<br>
the <code class="inline">\<span class="w">Q</span></code>
escape in double-quoted strings.</p>
<p>If EXPR is omitted, uses <code class="inline"><span class="i">$_</span></code>
.]]></desc>
</keyword>
<keyword name="qw" type="function">
<params>
<param name='/string/'/>
</params>
<desc><![CDATA[Generalized quotes. See <a href="../perlop.html#Quote-Like-Operators">"Quote-Like Operators" in perlop</a>.]]></desc>
</keyword>
<keyword name="qx" type="function">
<params>
<param name='/string/'/>
</params>
<desc><![CDATA[Generalized quotes. See <a href="../perlop.html#Quote-Like-Operators">"Quote-Like Operators" in perlop</a>.]]></desc>
</keyword>
<keyword name="rand" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Returns a random fractional number greater than or equal to <code class="inline"><span class="n">0</span></code>
and less<br>
than the value of EXPR. (EXPR should be positive.) If EXPR is<br>
omitted, the value <code class="inline"><span class="n">1</span></code>
is used. Currently EXPR with the value <code class="inline"><span class="n">0</span></code>
is<br>
also special-cased as <code class="inline"><span class="n">1</span></code>
- this has not been documented before perl 5.8.0<br>
and is subject to change in future versions of perl. Automatically calls<br>
<code class="inline"><a class="l_k" href="../functions/srand.html">srand</a></code> unless <code class="inline"><a class="l_k" href="../functions/srand.html">srand</a></code> has already been called. See also <code class="inline"><a class="l_k" href="../functions/srand.html">srand</a></code>.</p>
<p>Apply <code class="inline"><a class="l_k" href="../functions/int.html">int()</a></code> to the value returned by <code class="inline"><a class="l_k" href="../functions/rand.html">rand()</a></code> if you want random<br>
integers instead of random fractional numbers. For example,</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/int.html">int</a><span class="s">(</span><a class="l_k" href="../functions/rand.html">rand</a><span class="s">(</span><span class="n">10</span><span class="s">)</span><span class="s">)</span></li></ol></pre><p>returns a random integer between <code class="inline"><span class="n">0</span></code>
and <code class="inline"><span class="n">9</span></code>
, inclusive.</p>
<p>(Note: If your rand function consistently returns numbers that are too<br>
large or too small, then your version of Perl was probably compiled<br>
with the wrong number of RANDBITS.)]]></desc>
</keyword>
<keyword name="rand" type="function">
<params>
</params>
<desc><![CDATA[Returns a random fractional number greater than or equal to <code class="inline"><span class="n">0</span></code>
and less<br>
than the value of EXPR. (EXPR should be positive.) If EXPR is<br>
omitted, the value <code class="inline"><span class="n">1</span></code>
is used. Currently EXPR with the value <code class="inline"><span class="n">0</span></code>
is<br>
also special-cased as <code class="inline"><span class="n">1</span></code>
- this has not been documented before perl 5.8.0<br>
and is subject to change in future versions of perl. Automatically calls<br>
<code class="inline"><a class="l_k" href="../functions/srand.html">srand</a></code> unless <code class="inline"><a class="l_k" href="../functions/srand.html">srand</a></code> has already been called. See also <code class="inline"><a class="l_k" href="../functions/srand.html">srand</a></code>.</p>
<p>Apply <code class="inline"><a class="l_k" href="../functions/int.html">int()</a></code> to the value returned by <code class="inline"><a class="l_k" href="../functions/rand.html">rand()</a></code> if you want random<br>
integers instead of random fractional numbers. For example,</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/int.html">int</a><span class="s">(</span><a class="l_k" href="../functions/rand.html">rand</a><span class="s">(</span><span class="n">10</span><span class="s">)</span><span class="s">)</span></li></ol></pre><p>returns a random integer between <code class="inline"><span class="n">0</span></code>
and <code class="inline"><span class="n">9</span></code>
, inclusive.</p>
<p>(Note: If your rand function consistently returns numbers that are too<br>
large or too small, then your version of Perl was probably compiled<br>
with the wrong number of RANDBITS.)]]></desc>
</keyword>
<keyword name="read" type="function">
<params>
<param name='filehandle'/>
<param name='scalar'/>
<param name='length'/>
<param name='offset'/>
</params>
<desc><![CDATA[Attempts to read LENGTH <i>characters</i> of data into variable SCALAR<br>
from the specified FILEHANDLE. Returns the number of characters<br>
actually read, <code class="inline"><span class="n">0</span></code>
at end of file, or undef if there was an error (in<br>
the latter case <code class="inline"><span class="i">$!</span></code>
is also set). SCALAR will be grown or shrunk <br>
so that the last character actually read is the last character of the<br>
scalar after the read.</p>
<p>An OFFSET may be specified to place the read data at some place in the<br>
string other than the beginning. A negative OFFSET specifies<br>
placement at that many characters counting backwards from the end of<br>
the string. A positive OFFSET greater than the length of SCALAR<br>
results in the string being padded to the required size with <code class="inline"><span class="q">"\0"</span></code>
<br>
bytes before the result of the read is appended.</p>
<p>The call is actually implemented in terms of either Perl's or system's<br>
fread() call. To get a true read(2) system call, see <code class="inline"><a class="l_k" href="../functions/sysread.html">sysread</a></code>.</p>
<p>Note the <i>characters</i>: depending on the status of the filehandle,<br>
either (8-bit) bytes or characters are read. By default all<br>
filehandles operate on bytes, but for example if the filehandle has<br>
been opened with the <code class="inline"><span class="j">:</span><span class="w">utf8</span></code>
I/O layer (see <a href="../functions/open.html">"open"</a>, and the <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code>
pragma, <a href="../open.html">open</a>), the I/O will operate on UTF-8 encoded Unicode<br>
characters, not bytes. Similarly for the <code class="inline"><span class="j">:</span><span class="w">encoding</span></code>
pragma:<br>
in that case pretty much any characters can be read.]]></desc>
</keyword>
<keyword name="read" type="function">
<params>
<param name='filehandle'/>
<param name='scalar'/>
<param name='length'/>
</params>
<desc><![CDATA[Attempts to read LENGTH <i>characters</i> of data into variable SCALAR<br>
from the specified FILEHANDLE. Returns the number of characters<br>
actually read, <code class="inline"><span class="n">0</span></code>
at end of file, or undef if there was an error (in<br>
the latter case <code class="inline"><span class="i">$!</span></code>
is also set). SCALAR will be grown or shrunk <br>
so that the last character actually read is the last character of the<br>
scalar after the read.</p>
<p>An OFFSET may be specified to place the read data at some place in the<br>
string other than the beginning. A negative OFFSET specifies<br>
placement at that many characters counting backwards from the end of<br>
the string. A positive OFFSET greater than the length of SCALAR<br>
results in the string being padded to the required size with <code class="inline"><span class="q">"\0"</span></code>
<br>
bytes before the result of the read is appended.</p>
<p>The call is actually implemented in terms of either Perl's or system's<br>
fread() call. To get a true read(2) system call, see <code class="inline"><a class="l_k" href="../functions/sysread.html">sysread</a></code>.</p>
<p>Note the <i>characters</i>: depending on the status of the filehandle,<br>
either (8-bit) bytes or characters are read. By default all<br>
filehandles operate on bytes, but for example if the filehandle has<br>
been opened with the <code class="inline"><span class="j">:</span><span class="w">utf8</span></code>
I/O layer (see <a href="../functions/open.html">"open"</a>, and the <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code>
pragma, <a href="../open.html">open</a>), the I/O will operate on UTF-8 encoded Unicode<br>
characters, not bytes. Similarly for the <code class="inline"><span class="j">:</span><span class="w">encoding</span></code>
pragma:<br>
in that case pretty much any characters can be read.]]></desc>
</keyword>
<keyword name="readdir" type="function">
<params>
<param name='dirhandle'/>
</params>
<desc><![CDATA[Returns the next directory entry for a directory opened by <code class="inline"><a class="l_k" href="../functions/opendir.html">opendir</a></code>.<br>
If used in list context, returns all the rest of the entries in the<br>
directory. If there are no more entries, returns an undefined value in<br>
scalar context or a null list in list context.</p>
<p>If you're planning to filetest the return values out of a <code class="inline"><a class="l_k" href="../functions/readdir.html">readdir</a></code>, you'd<br>
better prepend the directory in question. Otherwise, because we didn't<br>
<code class="inline"><a class="l_k" href="../functions/chdir.html">chdir</a></code> there, it would have been testing the wrong file.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/opendir.html">opendir</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$dh</span><span class="cm">,</span> <span class="i">$some_dir</span><span class="s">)</span> || <a class="l_k" href="../functions/die.html">die</a> <span class="q">"can't opendir $some_dir: $!"</span><span class="sc">;</span></li><li> <span class="i">@dots</span> = <a class="l_k" href="../functions/grep.html">grep</a> <span class="s">{</span> <span class="q">/^\./</span> && -f <span class="q">"$some_dir/$_"</span> <span class="s">}</span> <a class="l_k" href="../functions/readdir.html">readdir</a><span class="s">(</span><span class="i">$dh</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/closedir.html">closedir</a> <span class="i">$dh</span><span class="sc">;</span></li></ol><]]></desc>
</keyword>
<keyword name="readline" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Reads from the filehandle whose typeglob is contained in EXPR (or from<br>
*ARGV if EXPR is not provided). In scalar context, each call reads and<br>
returns the next line, until end-of-file is reached, whereupon the<br>
subsequent call returns undef. In list context, reads until end-of-file<br>
is reached and returns a list of lines. Note that the notion of "line"<br>
used here is however you may have defined it with <code class="inline"><span class="i">$/</span></code>
or<br>
<code class="inline"><span class="i">$INPUT_RECORD_SEPARATOR</span></code>
). See <a href="../perlvar.html#%24%2f">"$/" in perlvar</a>.</p>
<p>When <code class="inline"><span class="i">$/</span></code>
is set to <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code>, when readline() is in scalar<br>
context (i.e. file slurp mode), and when an empty file is read, it<br>
returns <code class="inline"><span class="q">''</span></code>
the first time, followed by <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> subsequently.</p>
<p>This is the internal function implementing the <code class="inline"><span class="q"><EXPR></span></code>
<br>
operator, but you can use it directly. The <code class="inline"><span class="q"><EXPR></span></code>
<br>
operator is discussed in more detail in <a href="../perlop.html#I%2fO-Operators">"I/O Operators" in perlop</a>.</p>
<pre class="verbatim"><ol><li> <span class="i">$line</span> = <span class="q"><STDIN></span><span class="sc">;</span></li><li> <span class="i">$line</span> = <a class="l_k" href="../functions/readline.html">readline</a><span class="s">(</span><span class="i">*STDIN</span><span class="s">)</span><span class="sc">;</span> <span class="c"># same thing</span></li></ol></pre><p>If readline encounters an operating system error, <code class="inline"><span class="i">$!</span></code>
will be set with the<br>
corresponding error message. It can be helpful to check <code class="inline"><span class="i">$!</span></code>
when you are<br>
reading from filehandles you don't trust, such as a tty or a socket. The<br>
following example uses the operator form of <code class="inline"><a class="l_k" href="../functions/readline.html">readline</a></code>, and takes the necessary<br>
steps to ensure that <code class="inline"><a class="l_k" href="../functions/readline.html">readline</a></code> was successful.</p>
<pre class="verbatim"><ol><li> for <span class="s">(</span><span class="sc">;</span><span class="sc">;</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/undef.html">undef</a> <span class="i">$!</span><span class="sc">;</span></li><li> unless <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a><span class="s">(</span> <span class="i">$line</span> = <> <span class="s">)</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/last.html">last</a> if <a class="l_k" href="../functions/eof.html">eof</a><span class="sc">;</span></li><li> <a class="l_k" href="../functions/die.html">die</a> <span class="i">$!</span> if <span class="i">$!</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> <span class="c"># ...</span></li><li> <span class="s">}</span></li></ol><]]></desc>
</keyword>
<keyword name="readline" type="function">
<params>
</params>
<desc><![CDATA[Reads from the filehandle whose typeglob is contained in EXPR (or from<br>
*ARGV if EXPR is not provided). In scalar context, each call reads and<br>
returns the next line, until end-of-file is reached, whereupon the<br>
subsequent call returns undef. In list context, reads until end-of-file<br>
is reached and returns a list of lines. Note that the notion of "line"<br>
used here is however you may have defined it with <code class="inline"><span class="i">$/</span></code>
or<br>
<code class="inline"><span class="i">$INPUT_RECORD_SEPARATOR</span></code>
). See <a href="../perlvar.html#%24%2f">"$/" in perlvar</a>.</p>
<p>When <code class="inline"><span class="i">$/</span></code>
is set to <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code>, when readline() is in scalar<br>
context (i.e. file slurp mode), and when an empty file is read, it<br>
returns <code class="inline"><span class="q">''</span></code>
the first time, followed by <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> subsequently.</p>
<p>This is the internal function implementing the <code class="inline"><span class="q"><EXPR></span></code>
<br>
operator, but you can use it directly. The <code class="inline"><span class="q"><EXPR></span></code>
<br>
operator is discussed in more detail in <a href="../perlop.html#I%2fO-Operators">"I/O Operators" in perlop</a>.</p>
<pre class="verbatim"><ol><li> <span class="i">$line</span> = <span class="q"><STDIN></span><span class="sc">;</span></li><li> <span class="i">$line</span> = <a class="l_k" href="../functions/readline.html">readline</a><span class="s">(</span><span class="i">*STDIN</span><span class="s">)</span><span class="sc">;</span> <span class="c"># same thing</span></li></ol></pre><p>If readline encounters an operating system error, <code class="inline"><span class="i">$!</span></code>
will be set with the<br>
corresponding error message. It can be helpful to check <code class="inline"><span class="i">$!</span></code>
when you are<br>
reading from filehandles you don't trust, such as a tty or a socket. The<br>
following example uses the operator form of <code class="inline"><a class="l_k" href="../functions/readline.html">readline</a></code>, and takes the necessary<br>
steps to ensure that <code class="inline"><a class="l_k" href="../functions/readline.html">readline</a></code> was successful.</p>
<pre class="verbatim"><ol><li> for <span class="s">(</span><span class="sc">;</span><span class="sc">;</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/undef.html">undef</a> <span class="i">$!</span><span class="sc">;</span></li><li> unless <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a><span class="s">(</span> <span class="i">$line</span> = <> <span class="s">)</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/last.html">last</a> if <a class="l_k" href="../functions/eof.html">eof</a><span class="sc">;</span></li><li> <a class="l_k" href="../functions/die.html">die</a> <span class="i">$!</span> if <span class="i">$!</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> <span class="c"># ...</span></li><li> <span class="s">}</span></li></ol><]]></desc>
</keyword>
<keyword name="readlink" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Returns the value of a symbolic link, if symbolic links are<br>
implemented. If not, gives a fatal error. If there is some system<br>
error, returns the undefined value and sets <code class="inline"><span class="i">$!</span></code>
(errno). If EXPR is<br>
omitted, uses <code class="inline"><span class="i">$_</span></code>
.]]></desc>
</keyword>
<keyword name="readlink" type="function">
<params>
</params>
<desc><![CDATA[Returns the value of a symbolic link, if symbolic links are<br>
implemented. If not, gives a fatal error. If there is some system<br>
error, returns the undefined value and sets <code class="inline"><span class="i">$!</span></code>
(errno). If EXPR is<br>
omitted, uses <code class="inline"><span class="i">$_</span></code>
.]]></desc>
</keyword>
<keyword name="readpipe" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[EXPR is executed as a system command.<br>
The collected standard output of the command is returned.<br>
In scalar context, it comes back as a single (potentially<br>
multi-line) string. In list context, returns a list of lines<br>
(however you've defined lines with <code class="inline"><span class="i">$/</span></code>
or <code class="inline"><span class="i">$INPUT_RECORD_SEPARATOR</span></code>
).<br>
This is the internal function implementing the <code class="inline"><a class="l_k" href="../functions/qx.html">qx/EXPR/</a></code>
operator, but you can use it directly. The <code class="inline"><a class="l_k" href="../functions/qx.html">qx/EXPR/</a></code>
operator is discussed in more detail in <a href="../perlop.html#I%2fO-Operators">"I/O Operators" in perlop</a>.<br>
If EXPR is omitted, uses <code class="inline"><span class="i">$_</span></code>
.]]></desc>
</keyword>
<keyword name="readpipe" type="function">
<params>
</params>
<desc><![CDATA[EXPR is executed as a system command.<br>
The collected standard output of the command is returned.<br>
In scalar context, it comes back as a single (potentially<br>
multi-line) string. In list context, returns a list of lines<br>
(however you've defined lines with <code class="inline"><span class="i">$/</span></code>
or <code class="inline"><span class="i">$INPUT_RECORD_SEPARATOR</span></code>
).<br>
This is the internal function implementing the <code class="inline"><a class="l_k" href="../functions/qx.html">qx/EXPR/</a></code>
operator, but you can use it directly. The <code class="inline"><a class="l_k" href="../functions/qx.html">qx/EXPR/</a></code>
operator is discussed in more detail in <a href="../perlop.html#I%2fO-Operators">"I/O Operators" in perlop</a>.<br>
If EXPR is omitted, uses <code class="inline"><span class="i">$_</span></code>
.]]></desc>
</keyword>
<keyword name="recv" type="function">
<params>
<param name='socket'/>
<param name='scalar'/>
<param name='length'/>
<param name='flags'/>
</params>
<desc><![CDATA[Receives a message on a socket. Attempts to receive LENGTH characters<br>
of data into variable SCALAR from the specified SOCKET filehandle.<br>
SCALAR will be grown or shrunk to the length actually read. Takes the<br>
same flags as the system call of the same name. Returns the address<br>
of the sender if SOCKET's protocol supports this; returns an empty<br>
string otherwise. If there's an error, returns the undefined value.<br>
This call is actually implemented in terms of recvfrom(2) system call.<br>
See <a href="../perlipc.html#UDP%3a-Message-Passing">"UDP: Message Passing" in perlipc</a> for examples.</p>
<p>Note the <i>characters</i>: depending on the status of the socket, either<br>
(8-bit) bytes or characters are received. By default all sockets<br>
operate on bytes, but for example if the socket has been changed using<br>
binmode() to operate with the <code class="inline"><span class="j">:</span><span class="i">encoding</span><span class="s">(</span><span class="w">utf8</span><span class="s">)</span></code>
I/O layer (see the<br>
<code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> pragma, <a href="../open.html">open</a>), the I/O will operate on UTF-8 encoded Unicode<br>
characters, not bytes. Similarly for the <code class="inline"><span class="j">:</span><span class="w">encoding</span></code>
pragma: in that<br>
case pretty much any characters can be read.]]></desc>
</keyword>
<keyword name="redo" type="function">
<params>
<param name='label'/>
</params>
<desc><![CDATA[The <code class="inline"><a class="l_k" href="../functions/redo.html">redo</a></code> command restarts the loop block without evaluating the<br>
conditional again. The <code class="inline"><a class="l_k" href="../functions/continue.html">continue</a></code> block, if any, is not executed. If<br>
the LABEL is omitted, the command refers to the innermost enclosing<br>
loop. Programs that want to lie to themselves about what was just input <br>
normally use this command:</p>
<pre class="verbatim"><ol><li> <span class="c"># a simpleminded Pascal comment stripper</span></li><li> <span class="c"># (warning: assumes no { or } in strings)</span></li><li> <span class="j">LINE:</span> while <span class="s">(</span><span class="q"><STDIN></span><span class="s">)</span> <span class="s">{</span></li><li> while <span class="s">(</span><span class="q">s|({.*}.*){.*}|$1 |</span><span class="s">)</span> <span class="s">{</span><span class="s">}</span></li><li> <span class="q">s|{.*}| |</span><span class="sc">;</span></li><li> if <span class="s">(</span><span class="q">s|{.*| |</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$front</span> = <span class="i">$_</span><span class="sc">;</span></li><li> while <span class="s">(</span><span class="q"><STDIN></span><span class="s">)</span> <span class="s">{</span></li><li> if <span class="s">(</span><span class="q">/}/</span><span class="s">)</span> <span class="s">{</span> <span class="c"># end of comment?</span></li><li> <span class="q">s|^|$front\{|</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/redo.html">redo</a> <span class="j">LINE</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> <span class="s">}</span></li><li> <span class="s">}</span></li><li> <a class="l_k" href="../functions/print.html">print</a><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p><code class="inline"><a class="l_k" href="../functions/redo.html">redo</a></code> cannot be used to retry a block which returns a value such as<br>
<code class="inline"><a class="l_k" href="../functions/eval.html">eval</a> <span class="s">{</span><span class="s">}</span></code>
, <code class="inline"><a class="l_k" href="../functions/sub.html">sub</a> <span class="s">{</span><span class="s">}</span></code>
or <code class="inline"><a class="l_k" href="../functions/do.html">do</a> <span class="s">{</span><span class="s">}</span></code>
, and should not be used to exit<br>
a grep() or map() operation.</p>
<p>Note that a block by itself is semantically identical to a loop<br>
that executes once. Thus <code class="inline"><a class="l_k" href="../functions/redo.html">redo</a></code> inside such a block will effectively<br>
turn it into a looping construct.</p>
<p>See also <a href="../functions/continue.html">"continue"</a> for an illustration of how <code class="inline"><a class="l_k" href="../functions/last.html">last</a></code>, <code class="inline"><a class="l_k" href="../functions/next.html">next</a></code>, and<br>
<code class="inline"><a class="l_k" href="../functions/redo.html">redo</a></code> work.]]></desc>
</keyword>
<keyword name="redo" type="function">
<params>
</params>
<desc><![CDATA[The <code class="inline"><a class="l_k" href="../functions/redo.html">redo</a></code> command restarts the loop block without evaluating the<br>
conditional again. The <code class="inline"><a class="l_k" href="../functions/continue.html">continue</a></code> block, if any, is not executed. If<br>
the LABEL is omitted, the command refers to the innermost enclosing<br>
loop. Programs that want to lie to themselves about what was just input <br>
normally use this command:</p>
<pre class="verbatim"><ol><li> <span class="c"># a simpleminded Pascal comment stripper</span></li><li> <span class="c"># (warning: assumes no { or } in strings)</span></li><li> <span class="j">LINE:</span> while <span class="s">(</span><span class="q"><STDIN></span><span class="s">)</span> <span class="s">{</span></li><li> while <span class="s">(</span><span class="q">s|({.*}.*){.*}|$1 |</span><span class="s">)</span> <span class="s">{</span><span class="s">}</span></li><li> <span class="q">s|{.*}| |</span><span class="sc">;</span></li><li> if <span class="s">(</span><span class="q">s|{.*| |</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$front</span> = <span class="i">$_</span><span class="sc">;</span></li><li> while <span class="s">(</span><span class="q"><STDIN></span><span class="s">)</span> <span class="s">{</span></li><li> if <span class="s">(</span><span class="q">/}/</span><span class="s">)</span> <span class="s">{</span> <span class="c"># end of comment?</span></li><li> <span class="q">s|^|$front\{|</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/redo.html">redo</a> <span class="j">LINE</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> <span class="s">}</span></li><li> <span class="s">}</span></li><li> <a class="l_k" href="../functions/print.html">print</a><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p><code class="inline"><a class="l_k" href="../functions/redo.html">redo</a></code> cannot be used to retry a block which returns a value such as<br>
<code class="inline"><a class="l_k" href="../functions/eval.html">eval</a> <span class="s">{</span><span class="s">}</span></code>
, <code class="inline"><a class="l_k" href="../functions/sub.html">sub</a> <span class="s">{</span><span class="s">}</span></code>
or <code class="inline"><a class="l_k" href="../functions/do.html">do</a> <span class="s">{</span><span class="s">}</span></code>
, and should not be used to exit<br>
a grep() or map() operation.</p>
<p>Note that a block by itself is semantically identical to a loop<br>
that executes once. Thus <code class="inline"><a class="l_k" href="../functions/redo.html">redo</a></code> inside such a block will effectively<br>
turn it into a looping construct.</p>
<p>See also <a href="../functions/continue.html">"continue"</a> for an illustration of how <code class="inline"><a class="l_k" href="../functions/last.html">last</a></code>, <code class="inline"><a class="l_k" href="../functions/next.html">next</a></code>, and<br>
<code class="inline"><a class="l_k" href="../functions/redo.html">redo</a></code> work.]]></desc>
</keyword>
<keyword name="ref" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Returns a non-empty string if EXPR is a reference, the empty<br>
string otherwise. If EXPR<br>
is not specified, <code class="inline"><span class="i">$_</span></code>
will be used. The value returned depends on the<br>
type of thing the reference is a reference to.<br>
Builtin types include:</p>
<pre class="verbatim"><ol><li> <span class="w">SCALAR</span></li><li> <span class="w">ARRAY</span></li><li> <span class="w">HASH</span></li><li> <span class="w">CODE</span></li><li> <span class="w">REF</span></li><li> <span class="w">GLOB</span></li><li> <span class="w">LVALUE</span></li><li> <span class="w">FORMAT</span></li><li> <span class="w">IO</span></li><li> <span class="w">VSTRING</span></li><li> <span class="w">Regexp</span></li></ol></pre><p>If the referenced object has been blessed into a package, then that package<br>
name is returned instead. You can think of <code class="inline"><a class="l_k" href="../functions/ref.html">ref</a></code> as a <code class="inline"><span class="w">typeof</span></code>
operator.</p>
<pre class="verbatim"><ol><li> if <span class="s">(</span><a class="l_k" href="../functions/ref.html">ref</a><span class="s">(</span><span class="i">$r</span><span class="s">)</span> eq <span class="q">"HASH"</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"r is a reference to a hash.\n"</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> unless <span class="s">(</span><a class="l_k" href="../functions/ref.html">ref</a><span class="s">(</span><span class="i">$r</span><span class="s">)</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"r is not a reference at all.\n"</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>The return value <code class="inline"><span class="w">LVALUE</span></code>
indicates a reference to an lvalue that is not<br>
a variable. You get this from taking the reference of function calls like<br>
<code class="inline"><a class="l_k" href="../functions/pos.html">pos()</a></code> or <code class="inline"><a class="l_k" href="../functions/substr.html">substr()</a></code>. <code class="inline"><span class="w">VSTRING</span></code>
is returned if the reference points<br>
to a <a href="../perldata.html#Version-Strings">version string</a>.</p>
<p>The result <code class="inline"><span class="w">Regexp</span></code>
indicates that the argument is a regular expression<br>
resulting from <code class="inline"><a class="l_k" href="../functions/qr.html">qr//</a></code>.</p>
<p>See also <a href="../perlref.html">perlref</a>.]]></desc>
</keyword>
<keyword name="ref" type="function">
<params>
</params>
<desc><![CDATA[Returns a non-empty string if EXPR is a reference, the empty<br>
string otherwise. If EXPR<br>
is not specified, <code class="inline"><span class="i">$_</span></code>
will be used. The value returned depends on the<br>
type of thing the reference is a reference to.<br>
Builtin types include:</p>
<pre class="verbatim"><ol><li> <span class="w">SCALAR</span></li><li> <span class="w">ARRAY</span></li><li> <span class="w">HASH</span></li><li> <span class="w">CODE</span></li><li> <span class="w">REF</span></li><li> <span class="w">GLOB</span></li><li> <span class="w">LVALUE</span></li><li> <span class="w">FORMAT</span></li><li> <span class="w">IO</span></li><li> <span class="w">VSTRING</span></li><li> <span class="w">Regexp</span></li></ol></pre><p>If the referenced object has been blessed into a package, then that package<br>
name is returned instead. You can think of <code class="inline"><a class="l_k" href="../functions/ref.html">ref</a></code> as a <code class="inline"><span class="w">typeof</span></code>
operator.</p>
<pre class="verbatim"><ol><li> if <span class="s">(</span><a class="l_k" href="../functions/ref.html">ref</a><span class="s">(</span><span class="i">$r</span><span class="s">)</span> eq <span class="q">"HASH"</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"r is a reference to a hash.\n"</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> unless <span class="s">(</span><a class="l_k" href="../functions/ref.html">ref</a><span class="s">(</span><span class="i">$r</span><span class="s">)</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"r is not a reference at all.\n"</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>The return value <code class="inline"><span class="w">LVALUE</span></code>
indicates a reference to an lvalue that is not<br>
a variable. You get this from taking the reference of function calls like<br>
<code class="inline"><a class="l_k" href="../functions/pos.html">pos()</a></code> or <code class="inline"><a class="l_k" href="../functions/substr.html">substr()</a></code>. <code class="inline"><span class="w">VSTRING</span></code>
is returned if the reference points<br>
to a <a href="../perldata.html#Version-Strings">version string</a>.</p>
<p>The result <code class="inline"><span class="w">Regexp</span></code>
indicates that the argument is a regular expression<br>
resulting from <code class="inline"><a class="l_k" href="../functions/qr.html">qr//</a></code>.</p>
<p>See also <a href="../perlref.html">perlref</a>.]]></desc>
</keyword>
<keyword name="rename" type="function">
<params>
<param name='oldname'/>
<param name='newname'/>
</params>
<desc><![CDATA[Changes the name of a file; an existing file NEWNAME will be<br>
clobbered. Returns true for success, false otherwise.</p>
<p>Behavior of this function varies wildly depending on your system<br>
implementation. For example, it will usually not work across file system<br>
boundaries, even though the system <i>mv</i> command sometimes compensates<br>
for this. Other restrictions include whether it works on directories,<br>
open files, or pre-existing files. Check <a href="../perlport.html">perlport</a> and either the<br>
rename(2) manpage or equivalent system documentation for details.</p>
<p>For a platform independent <code class="inline"><span class="w">move</span></code>
function look at the <a href="../File/Copy.html">File::Copy</a>
module.]]></desc>
</keyword>
<keyword name="require" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Demands a version of Perl specified by VERSION, or demands some semantics<br>
specified by EXPR or by <code class="inline"><span class="i">$_</span></code>
if EXPR is not supplied.</p>
<p>VERSION may be either a numeric argument such as 5.006, which will be<br>
compared to <code class="inline"><span class="i">$]</span></code>
, or a literal of the form v5.6.1, which will be compared<br>
to <code class="inline"><span class="i">$^V</span></code>
(aka $PERL_VERSION). A fatal error is produced at run time if<br>
VERSION is greater than the version of the current Perl interpreter.<br>
Compare with <a href="../functions/use.html">"use"</a>, which can do a similar check at compile time.</p>
<p>Specifying VERSION as a literal of the form v5.6.1 should generally be<br>
avoided, because it leads to misleading error messages under earlier<br>
versions of Perl that do not support this syntax. The equivalent numeric<br>
version should be used instead.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/require.html">require</a> <span class="v">v5.6.1</span><span class="sc">;</span> <span class="c"># run time version check</span></li><li> <a class="l_k" href="../functions/require.html">require</a> <span class="v">5.6.1</span><span class="sc">;</span> <span class="c"># ditto</span></li><li> <a class="l_k" href="../functions/require.html">require</a> <span class="n">5.006_001</span><span class="sc">;</span> <span class="c"># ditto; preferred for backwards compatibility</span></li></ol></pre><p>Otherwise, <code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> demands that a library file be included if it<br>
hasn't already been included. The file is included via the do-FILE<br>
mechanism, which is essentially just a variety of <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a></code> with the<br>
caveat that lexical variables in the invoking script will be invisible<br>
to the included code. Has semantics similar to the following subroutine:</p>
<pre class="verbatim"><ol><li><a name="require"></a> sub <span class="m">require</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="s">(</span><span class="i">$filename</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/exists.html">exists</a> <span class="i">$INC</span>{<span class="i">$filename</span>}<span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <span class="n">1</span> if <span class="i">$INC</span>{<span class="i">$filename</span>}<span class="sc">;</span></li><li> <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Compilation failed in require"</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="s">(</span><span class="i">$realfilename</span><span class="cm">,</span><span class="i">$result</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="j">ITER:</span> <span class="s">{</span></li><li> foreach <span class="i">$prefix</span> <span class="s">(</span><span class="i">@INC</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$realfilename</span> = <span class="q">"$prefix/$filename"</span><span class="sc">;</span></li><li> if <span class="s">(</span>-f <span class="i">$realfilename</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$INC</span>{<span class="i">$filename</span>} = <span class="i">$realfilename</span><span class="sc">;</span></li><li> <span class="i">$result</span> = <a class="l_k" href="../functions/do.html">do</a> <span class="i">$realfilename</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/last.html">last</a> <span class="j">ITER</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> <span class="s">}</span></li><li> <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't find $filename in \@INC"</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> if <span class="s">(</span><span class="i">$@</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$INC</span>{<span class="i">$filename</span>} = <a class="l_k" href="../functions/undef.html">undef</a><span class="sc">;</span></li><li> <a class="l_k" href="../functions/die.html">die</a> <span class="i">$@</span><span class="sc">;</span></li><li> <span class="s">}</span> elsif <span class="s">(</span>!<span class="i">$result</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/delete.html">delete</a> <span class="i">$INC</span>{<span class="i">$filename</span>}<span class="sc">;</span></li><li> <a class="l_k" href="../functions/die.html">die</a> <span class="q">"$filename did not return true value"</span><span class="sc">;</span></li><li> <span class="s">}</span> else <span class="s">{</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <span class="i">$result</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> <span class="s">}</span></li></ol></pre><p>Note that the file will not be included twice under the same specified<br>
name.</p>
<p>The file must return true as the last statement to indicate<br>
successful execution of any initialization code, so it's customary to<br>
end such a file with <code class="inline"><span class="n">1</span><span class="sc">;</span></code>
unless you're sure it'll return true<br>
otherwise. But it's better just to put the <code class="inline"><span class="n">1</span><span class="sc">;</span></code>
, in case you add more<br>
statements.</p>
<p>If EXPR is a bareword, the require assumes a "<i>.pm</i>" extension and<br>
replaces "<i>::</i>" with "<i>/</i>" in the filename for you,<br>
to make it easy to load standard modules. This form of loading of<br>
modules does not risk altering your namespace.</p>
<p>In other words, if you try this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/require.html">require</a> <span class="w">Foo::Bar</span><span class="sc">;</span> <span class="c"># a splendid bareword</span></li></ol></pre><p>The require function will actually look for the "<i>Foo/Bar.pm</i>" file in the<br>
directories specified in the <code class="inline"><span class="i">@INC</span></code>
array.</p>
<p>But if you try this:</p>
<pre class="verbatim"><ol><li> <span class="i">$class</span> = <span class="q">'Foo::Bar'</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/require.html">require</a> <span class="i">$class</span><span class="sc">;</span> <span class="c"># $class is not a bareword</span></li><li> <span class="c">#or</span></li><li> <a class="l_k" href="../functions/require.html">require</a> <span class="q">"Foo::Bar"</span><span class="sc">;</span> <span class="c"># not a bareword because of the ""</span></li></ol></pre><p>The require function will look for the "<i>Foo::Bar</i>" file in the @INC array and<br>
will complain about not finding "<i>Foo::Bar</i>" there. In this case you can do:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/eval.html">eval</a> <span class="q">"require $class"</span><span class="sc">;</span></li></ol></pre><p>Now that you understand how <code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> looks for files in the case of a<br>
bareword argument, there is a little extra functionality going on behind<br>
the scenes. Before <code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> looks for a "<i>.pm</i>" extension, it will<br>
first look for a similar filename with a "<i>.pmc</i>" extension. If this file<br>
is found, it will be loaded in place of any file ending in a "<i>.pm</i>"<br>
extension.</p>
<p>You can also insert hooks into the import facility, by putting directly<br>
Perl code into the @INC array. There are three forms of hooks: subroutine<br>
references, array references and blessed objects.</p>
<p>Subroutine references are the simplest case. When the inclusion system<br>
walks through @INC and encounters a subroutine, this subroutine gets<br>
called with two parameters, the first being a reference to itself, and the<br>
second the name of the file to be included (e.g. "<i>Foo/Bar.pm</i>"). The<br>
subroutine should return nothing, or a list of up to three values in the<br>
following order:</p>
<ol>
<li>
<p>A filehandle, from which the file will be read.</p>
</li>
<li>
<p>A reference to a subroutine. If there is no filehandle (previous item),<br>
then this subroutine is expected to generate one line of source code per<br>
call, writing the line into <code class="inline"><span class="i">$_</span></code>
and returning 1, then returning 0 at<br>
"end of file". If there is a filehandle, then the subroutine will be<br>
called to act as a simple source filter, with the line as read in <code class="inline"><span class="i">$_</span></code>
.<br>
Again, return 1 for each valid line, and 0 after all lines have been<br>
returned.</p>
</li>
<li>
<p>Optional state for the subroutine. The state is passed in as <code class="inline"><span class="i">$_</span>[<span class="n">1</span>]</code>
. A<br>
reference to the subroutine itself is passed in as <code class="inline"><span class="i">$_</span>[<span class="n">0</span>]</code>
.</p>
</li>
</ol>
<p>If an empty list, <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code>, or nothing that matches the first 3 values above<br>
is returned then <code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> will look at the remaining elements of @INC.<br>
Note that this file handle must be a real file handle (strictly a typeglob,<br>
or reference to a typeglob, blessed or unblessed) - tied file handles will be<br>
ignored and return value processing will stop there.</p>
<p>If the hook is an array reference, its first element must be a subroutine<br>
reference. This subroutine is called as above, but the first parameter is<br>
the array reference. This enables to pass indirectly some arguments to<br>
the subroutine.</p>
<p>In other words, you can write:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/push.html">push</a> <span class="i">@INC</span><span class="cm">,</span> \<span class="i">&my_sub</span><span class="sc">;</span></li><li><a name="my_sub"></a> sub <span class="m">my_sub</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="s">(</span><span class="i">$coderef</span><span class="cm">,</span> <span class="i">$filename</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span> <span class="c"># $coderef is \&my_sub</span></li><li> ...</li><li> <span class="s">}</span></li></ol></pre><p>or:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/push.html">push</a> <span class="i">@INC</span><span class="cm">,</span> <span class="s">[</span> \<span class="i">&my_sub</span><span class="cm">,</span> <span class="i">$x</span><span class="cm">,</span> <span class="i">$y</span><span class="cm">,</span> ... <span class="s">]</span><span class="sc">;</span></li><li><a name="my_sub"></a> sub <span class="m">my_sub</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="s">(</span><span class="i">$arrayref</span><span class="cm">,</span> <span class="i">$filename</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li> <span class="c"># Retrieve $x, $y, ...</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">@parameters</span> = <span class="i">@$arrayref</span>[<span class="n">1</span>..<span class="i">$#$arrayref</span>]<span class="sc">;</span></li><li> ...</li><li> <span class="s">}</span></li></ol></pre><p>If the hook is an object, it must provide an INC method that will be<br>
called as above, the first parameter being the object itself. (Note that<br>
you must fully qualify the sub's name, as unqualified <code class="inline"><span class="w">INC</span></code>
is always forced<br>
into package <code class="inline"><span class="w">main</span></code>
.) Here is a typical code layout:</p>
<pre class="verbatim"><ol><li> <span class="c"># In Foo.pm</span></li><li><a name="package-Foo"></a> package <span class="i">Foo</span><span class="sc">;</span></li><li><a name="new"></a> sub <span class="m">new</span> <span class="s">{</span> ... <span class="s">}</span></li><li><a name="Foo::INC"></a> sub <span class="m">Foo::INC</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="s">(</span><span class="i">$self</span><span class="cm">,</span> <span class="i">$filename</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li> ...</li><li> <span class="s">}</span></li><li></li><li> <span class="c"># In the main program</span></li><li> <a class="l_k" href="../functions/push.html">push</a> <span class="i">@INC</span><span class="cm">,</span> <span class="w">Foo</span><span class="w">->new</span><span class="s">(</span>...<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Note that these hooks are also permitted to set the %INC entry<br>
corresponding to the files they have loaded. See <a href="../perlvar.html#%25INC">"%INC" in perlvar</a>.</p>
<p>For a yet-more-powerful import facility, see <a href="../functions/use.html">"use"</a> and <a href="../perlmod.html">perlmod</a>.]]></desc>
</keyword>
<keyword name="require" type="function">
<params>
<param name='version'/>
</params>
<desc><![CDATA[Demands a version of Perl specified by VERSION, or demands some semantics<br>
specified by EXPR or by <code class="inline"><span class="i">$_</span></code>
if EXPR is not supplied.</p>
<p>VERSION may be either a numeric argument such as 5.006, which will be<br>
compared to <code class="inline"><span class="i">$]</span></code>
, or a literal of the form v5.6.1, which will be compared<br>
to <code class="inline"><span class="i">$^V</span></code>
(aka $PERL_VERSION). A fatal error is produced at run time if<br>
VERSION is greater than the version of the current Perl interpreter.<br>
Compare with <a href="../functions/use.html">"use"</a>, which can do a similar check at compile time.</p>
<p>Specifying VERSION as a literal of the form v5.6.1 should generally be<br>
avoided, because it leads to misleading error messages under earlier<br>
versions of Perl that do not support this syntax. The equivalent numeric<br>
version should be used instead.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/require.html">require</a> <span class="v">v5.6.1</span><span class="sc">;</span> <span class="c"># run time version check</span></li><li> <a class="l_k" href="../functions/require.html">require</a> <span class="v">5.6.1</span><span class="sc">;</span> <span class="c"># ditto</span></li><li> <a class="l_k" href="../functions/require.html">require</a> <span class="n">5.006_001</span><span class="sc">;</span> <span class="c"># ditto; preferred for backwards compatibility</span></li></ol></pre><p>Otherwise, <code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> demands that a library file be included if it<br>
hasn't already been included. The file is included via the do-FILE<br>
mechanism, which is essentially just a variety of <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a></code> with the<br>
caveat that lexical variables in the invoking script will be invisible<br>
to the included code. Has semantics similar to the following subroutine:</p>
<pre class="verbatim"><ol><li><a name="require"></a> sub <span class="m">require</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="s">(</span><span class="i">$filename</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/exists.html">exists</a> <span class="i">$INC</span>{<span class="i">$filename</span>}<span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <span class="n">1</span> if <span class="i">$INC</span>{<span class="i">$filename</span>}<span class="sc">;</span></li><li> <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Compilation failed in require"</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="s">(</span><span class="i">$realfilename</span><span class="cm">,</span><span class="i">$result</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="j">ITER:</span> <span class="s">{</span></li><li> foreach <span class="i">$prefix</span> <span class="s">(</span><span class="i">@INC</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$realfilename</span> = <span class="q">"$prefix/$filename"</span><span class="sc">;</span></li><li> if <span class="s">(</span>-f <span class="i">$realfilename</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$INC</span>{<span class="i">$filename</span>} = <span class="i">$realfilename</span><span class="sc">;</span></li><li> <span class="i">$result</span> = <a class="l_k" href="../functions/do.html">do</a> <span class="i">$realfilename</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/last.html">last</a> <span class="j">ITER</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> <span class="s">}</span></li><li> <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't find $filename in \@INC"</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> if <span class="s">(</span><span class="i">$@</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$INC</span>{<span class="i">$filename</span>} = <a class="l_k" href="../functions/undef.html">undef</a><span class="sc">;</span></li><li> <a class="l_k" href="../functions/die.html">die</a> <span class="i">$@</span><span class="sc">;</span></li><li> <span class="s">}</span> elsif <span class="s">(</span>!<span class="i">$result</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/delete.html">delete</a> <span class="i">$INC</span>{<span class="i">$filename</span>}<span class="sc">;</span></li><li> <a class="l_k" href="../functions/die.html">die</a> <span class="q">"$filename did not return true value"</span><span class="sc">;</span></li><li> <span class="s">}</span> else <span class="s">{</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <span class="i">$result</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> <span class="s">}</span></li></ol></pre><p>Note that the file will not be included twice under the same specified<br>
name.</p>
<p>The file must return true as the last statement to indicate<br>
successful execution of any initialization code, so it's customary to<br>
end such a file with <code class="inline"><span class="n">1</span><span class="sc">;</span></code>
unless you're sure it'll return true<br>
otherwise. But it's better just to put the <code class="inline"><span class="n">1</span><span class="sc">;</span></code>
, in case you add more<br>
statements.</p>
<p>If EXPR is a bareword, the require assumes a "<i>.pm</i>" extension and<br>
replaces "<i>::</i>" with "<i>/</i>" in the filename for you,<br>
to make it easy to load standard modules. This form of loading of<br>
modules does not risk altering your namespace.</p>
<p>In other words, if you try this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/require.html">require</a> <span class="w">Foo::Bar</span><span class="sc">;</span> <span class="c"># a splendid bareword</span></li></ol></pre><p>The require function will actually look for the "<i>Foo/Bar.pm</i>" file in the<br>
directories specified in the <code class="inline"><span class="i">@INC</span></code>
array.</p>
<p>But if you try this:</p>
<pre class="verbatim"><ol><li> <span class="i">$class</span> = <span class="q">'Foo::Bar'</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/require.html">require</a> <span class="i">$class</span><span class="sc">;</span> <span class="c"># $class is not a bareword</span></li><li> <span class="c">#or</span></li><li> <a class="l_k" href="../functions/require.html">require</a> <span class="q">"Foo::Bar"</span><span class="sc">;</span> <span class="c"># not a bareword because of the ""</span></li></ol></pre><p>The require function will look for the "<i>Foo::Bar</i>" file in the @INC array and<br>
will complain about not finding "<i>Foo::Bar</i>" there. In this case you can do:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/eval.html">eval</a> <span class="q">"require $class"</span><span class="sc">;</span></li></ol></pre><p>Now that you understand how <code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> looks for files in the case of a<br>
bareword argument, there is a little extra functionality going on behind<br>
the scenes. Before <code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> looks for a "<i>.pm</i>" extension, it will<br>
first look for a similar filename with a "<i>.pmc</i>" extension. If this file<br>
is found, it will be loaded in place of any file ending in a "<i>.pm</i>"<br>
extension.</p>
<p>You can also insert hooks into the import facility, by putting directly<br>
Perl code into the @INC array. There are three forms of hooks: subroutine<br>
references, array references and blessed objects.</p>
<p>Subroutine references are the simplest case. When the inclusion system<br>
walks through @INC and encounters a subroutine, this subroutine gets<br>
called with two parameters, the first being a reference to itself, and the<br>
second the name of the file to be included (e.g. "<i>Foo/Bar.pm</i>"). The<br>
subroutine should return nothing, or a list of up to three values in the<br>
following order:</p>
<ol>
<li>
<p>A filehandle, from which the file will be read.</p>
</li>
<li>
<p>A reference to a subroutine. If there is no filehandle (previous item),<br>
then this subroutine is expected to generate one line of source code per<br>
call, writing the line into <code class="inline"><span class="i">$_</span></code>
and returning 1, then returning 0 at<br>
"end of file". If there is a filehandle, then the subroutine will be<br>
called to act as a simple source filter, with the line as read in <code class="inline"><span class="i">$_</span></code>
.<br>
Again, return 1 for each valid line, and 0 after all lines have been<br>
returned.</p>
</li>
<li>
<p>Optional state for the subroutine. The state is passed in as <code class="inline"><span class="i">$_</span>[<span class="n">1</span>]</code>
. A<br>
reference to the subroutine itself is passed in as <code class="inline"><span class="i">$_</span>[<span class="n">0</span>]</code>
.</p>
</li>
</ol>
<p>If an empty list, <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code>, or nothing that matches the first 3 values above<br>
is returned then <code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> will look at the remaining elements of @INC.<br>
Note that this file handle must be a real file handle (strictly a typeglob,<br>
or reference to a typeglob, blessed or unblessed) - tied file handles will be<br>
ignored and return value processing will stop there.</p>
<p>If the hook is an array reference, its first element must be a subroutine<br>
reference. This subroutine is called as above, but the first parameter is<br>
the array reference. This enables to pass indirectly some arguments to<br>
the subroutine.</p>
<p>In other words, you can write:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/push.html">push</a> <span class="i">@INC</span><span class="cm">,</span> \<span class="i">&my_sub</span><span class="sc">;</span></li><li><a name="my_sub"></a> sub <span class="m">my_sub</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="s">(</span><span class="i">$coderef</span><span class="cm">,</span> <span class="i">$filename</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span> <span class="c"># $coderef is \&my_sub</span></li><li> ...</li><li> <span class="s">}</span></li></ol></pre><p>or:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/push.html">push</a> <span class="i">@INC</span><span class="cm">,</span> <span class="s">[</span> \<span class="i">&my_sub</span><span class="cm">,</span> <span class="i">$x</span><span class="cm">,</span> <span class="i">$y</span><span class="cm">,</span> ... <span class="s">]</span><span class="sc">;</span></li><li><a name="my_sub"></a> sub <span class="m">my_sub</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="s">(</span><span class="i">$arrayref</span><span class="cm">,</span> <span class="i">$filename</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li> <span class="c"># Retrieve $x, $y, ...</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">@parameters</span> = <span class="i">@$arrayref</span>[<span class="n">1</span>..<span class="i">$#$arrayref</span>]<span class="sc">;</span></li><li> ...</li><li> <span class="s">}</span></li></ol></pre><p>If the hook is an object, it must provide an INC method that will be<br>
called as above, the first parameter being the object itself. (Note that<br>
you must fully qualify the sub's name, as unqualified <code class="inline"><span class="w">INC</span></code>
is always forced<br>
into package <code class="inline"><span class="w">main</span></code>
.) Here is a typical code layout:</p>
<pre class="verbatim"><ol><li> <span class="c"># In Foo.pm</span></li><li><a name="package-Foo"></a> package <span class="i">Foo</span><span class="sc">;</span></li><li><a name="new"></a> sub <span class="m">new</span> <span class="s">{</span> ... <span class="s">}</span></li><li><a name="Foo::INC"></a> sub <span class="m">Foo::INC</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="s">(</span><span class="i">$self</span><span class="cm">,</span> <span class="i">$filename</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li> ...</li><li> <span class="s">}</span></li><li></li><li> <span class="c"># In the main program</span></li><li> <a class="l_k" href="../functions/push.html">push</a> <span class="i">@INC</span><span class="cm">,</span> <span class="w">Foo</span><span class="w">->new</span><span class="s">(</span>...<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Note that these hooks are also permitted to set the %INC entry<br>
corresponding to the files they have loaded. See <a href="../perlvar.html#%25INC">"%INC" in perlvar</a>.</p>
<p>For a yet-more-powerful import facility, see <a href="../functions/use.html">"use"</a> and <a href="../perlmod.html">perlmod</a>.]]></desc>
</keyword>
<keyword name="require" type="function">
<params>
</params>
<desc><![CDATA[Demands a version of Perl specified by VERSION, or demands some semantics<br>
specified by EXPR or by <code class="inline"><span class="i">$_</span></code>
if EXPR is not supplied.</p>
<p>VERSION may be either a numeric argument such as 5.006, which will be<br>
compared to <code class="inline"><span class="i">$]</span></code>
, or a literal of the form v5.6.1, which will be compared<br>
to <code class="inline"><span class="i">$^V</span></code>
(aka $PERL_VERSION). A fatal error is produced at run time if<br>
VERSION is greater than the version of the current Perl interpreter.<br>
Compare with <a href="../functions/use.html">"use"</a>, which can do a similar check at compile time.</p>
<p>Specifying VERSION as a literal of the form v5.6.1 should generally be<br>
avoided, because it leads to misleading error messages under earlier<br>
versions of Perl that do not support this syntax. The equivalent numeric<br>
version should be used instead.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/require.html">require</a> <span class="v">v5.6.1</span><span class="sc">;</span> <span class="c"># run time version check</span></li><li> <a class="l_k" href="../functions/require.html">require</a> <span class="v">5.6.1</span><span class="sc">;</span> <span class="c"># ditto</span></li><li> <a class="l_k" href="../functions/require.html">require</a> <span class="n">5.006_001</span><span class="sc">;</span> <span class="c"># ditto; preferred for backwards compatibility</span></li></ol></pre><p>Otherwise, <code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> demands that a library file be included if it<br>
hasn't already been included. The file is included via the do-FILE<br>
mechanism, which is essentially just a variety of <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a></code> with the<br>
caveat that lexical variables in the invoking script will be invisible<br>
to the included code. Has semantics similar to the following subroutine:</p>
<pre class="verbatim"><ol><li><a name="require"></a> sub <span class="m">require</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="s">(</span><span class="i">$filename</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/exists.html">exists</a> <span class="i">$INC</span>{<span class="i">$filename</span>}<span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <span class="n">1</span> if <span class="i">$INC</span>{<span class="i">$filename</span>}<span class="sc">;</span></li><li> <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Compilation failed in require"</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="s">(</span><span class="i">$realfilename</span><span class="cm">,</span><span class="i">$result</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="j">ITER:</span> <span class="s">{</span></li><li> foreach <span class="i">$prefix</span> <span class="s">(</span><span class="i">@INC</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$realfilename</span> = <span class="q">"$prefix/$filename"</span><span class="sc">;</span></li><li> if <span class="s">(</span>-f <span class="i">$realfilename</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$INC</span>{<span class="i">$filename</span>} = <span class="i">$realfilename</span><span class="sc">;</span></li><li> <span class="i">$result</span> = <a class="l_k" href="../functions/do.html">do</a> <span class="i">$realfilename</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/last.html">last</a> <span class="j">ITER</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> <span class="s">}</span></li><li> <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't find $filename in \@INC"</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> if <span class="s">(</span><span class="i">$@</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$INC</span>{<span class="i">$filename</span>} = <a class="l_k" href="../functions/undef.html">undef</a><span class="sc">;</span></li><li> <a class="l_k" href="../functions/die.html">die</a> <span class="i">$@</span><span class="sc">;</span></li><li> <span class="s">}</span> elsif <span class="s">(</span>!<span class="i">$result</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/delete.html">delete</a> <span class="i">$INC</span>{<span class="i">$filename</span>}<span class="sc">;</span></li><li> <a class="l_k" href="../functions/die.html">die</a> <span class="q">"$filename did not return true value"</span><span class="sc">;</span></li><li> <span class="s">}</span> else <span class="s">{</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <span class="i">$result</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> <span class="s">}</span></li></ol></pre><p>Note that the file will not be included twice under the same specified<br>
name.</p>
<p>The file must return true as the last statement to indicate<br>
successful execution of any initialization code, so it's customary to<br>
end such a file with <code class="inline"><span class="n">1</span><span class="sc">;</span></code>
unless you're sure it'll return true<br>
otherwise. But it's better just to put the <code class="inline"><span class="n">1</span><span class="sc">;</span></code>
, in case you add more<br>
statements.</p>
<p>If EXPR is a bareword, the require assumes a "<i>.pm</i>" extension and<br>
replaces "<i>::</i>" with "<i>/</i>" in the filename for you,<br>
to make it easy to load standard modules. This form of loading of<br>
modules does not risk altering your namespace.</p>
<p>In other words, if you try this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/require.html">require</a> <span class="w">Foo::Bar</span><span class="sc">;</span> <span class="c"># a splendid bareword</span></li></ol></pre><p>The require function will actually look for the "<i>Foo/Bar.pm</i>" file in the<br>
directories specified in the <code class="inline"><span class="i">@INC</span></code>
array.</p>
<p>But if you try this:</p>
<pre class="verbatim"><ol><li> <span class="i">$class</span> = <span class="q">'Foo::Bar'</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/require.html">require</a> <span class="i">$class</span><span class="sc">;</span> <span class="c"># $class is not a bareword</span></li><li> <span class="c">#or</span></li><li> <a class="l_k" href="../functions/require.html">require</a> <span class="q">"Foo::Bar"</span><span class="sc">;</span> <span class="c"># not a bareword because of the ""</span></li></ol></pre><p>The require function will look for the "<i>Foo::Bar</i>" file in the @INC array and<br>
will complain about not finding "<i>Foo::Bar</i>" there. In this case you can do:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/eval.html">eval</a> <span class="q">"require $class"</span><span class="sc">;</span></li></ol></pre><p>Now that you understand how <code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> looks for files in the case of a<br>
bareword argument, there is a little extra functionality going on behind<br>
the scenes. Before <code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> looks for a "<i>.pm</i>" extension, it will<br>
first look for a similar filename with a "<i>.pmc</i>" extension. If this file<br>
is found, it will be loaded in place of any file ending in a "<i>.pm</i>"<br>
extension.</p>
<p>You can also insert hooks into the import facility, by putting directly<br>
Perl code into the @INC array. There are three forms of hooks: subroutine<br>
references, array references and blessed objects.</p>
<p>Subroutine references are the simplest case. When the inclusion system<br>
walks through @INC and encounters a subroutine, this subroutine gets<br>
called with two parameters, the first being a reference to itself, and the<br>
second the name of the file to be included (e.g. "<i>Foo/Bar.pm</i>"). The<br>
subroutine should return nothing, or a list of up to three values in the<br>
following order:</p>
<ol>
<li>
<p>A filehandle, from which the file will be read.</p>
</li>
<li>
<p>A reference to a subroutine. If there is no filehandle (previous item),<br>
then this subroutine is expected to generate one line of source code per<br>
call, writing the line into <code class="inline"><span class="i">$_</span></code>
and returning 1, then returning 0 at<br>
"end of file". If there is a filehandle, then the subroutine will be<br>
called to act as a simple source filter, with the line as read in <code class="inline"><span class="i">$_</span></code>
.<br>
Again, return 1 for each valid line, and 0 after all lines have been<br>
returned.</p>
</li>
<li>
<p>Optional state for the subroutine. The state is passed in as <code class="inline"><span class="i">$_</span>[<span class="n">1</span>]</code>
. A<br>
reference to the subroutine itself is passed in as <code class="inline"><span class="i">$_</span>[<span class="n">0</span>]</code>
.</p>
</li>
</ol>
<p>If an empty list, <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code>, or nothing that matches the first 3 values above<br>
is returned then <code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> will look at the remaining elements of @INC.<br>
Note that this file handle must be a real file handle (strictly a typeglob,<br>
or reference to a typeglob, blessed or unblessed) - tied file handles will be<br>
ignored and return value processing will stop there.</p>
<p>If the hook is an array reference, its first element must be a subroutine<br>
reference. This subroutine is called as above, but the first parameter is<br>
the array reference. This enables to pass indirectly some arguments to<br>
the subroutine.</p>
<p>In other words, you can write:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/push.html">push</a> <span class="i">@INC</span><span class="cm">,</span> \<span class="i">&my_sub</span><span class="sc">;</span></li><li><a name="my_sub"></a> sub <span class="m">my_sub</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="s">(</span><span class="i">$coderef</span><span class="cm">,</span> <span class="i">$filename</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span> <span class="c"># $coderef is \&my_sub</span></li><li> ...</li><li> <span class="s">}</span></li></ol></pre><p>or:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/push.html">push</a> <span class="i">@INC</span><span class="cm">,</span> <span class="s">[</span> \<span class="i">&my_sub</span><span class="cm">,</span> <span class="i">$x</span><span class="cm">,</span> <span class="i">$y</span><span class="cm">,</span> ... <span class="s">]</span><span class="sc">;</span></li><li><a name="my_sub"></a> sub <span class="m">my_sub</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="s">(</span><span class="i">$arrayref</span><span class="cm">,</span> <span class="i">$filename</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li> <span class="c"># Retrieve $x, $y, ...</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">@parameters</span> = <span class="i">@$arrayref</span>[<span class="n">1</span>..<span class="i">$#$arrayref</span>]<span class="sc">;</span></li><li> ...</li><li> <span class="s">}</span></li></ol></pre><p>If the hook is an object, it must provide an INC method that will be<br>
called as above, the first parameter being the object itself. (Note that<br>
you must fully qualify the sub's name, as unqualified <code class="inline"><span class="w">INC</span></code>
is always forced<br>
into package <code class="inline"><span class="w">main</span></code>
.) Here is a typical code layout:</p>
<pre class="verbatim"><ol><li> <span class="c"># In Foo.pm</span></li><li><a name="package-Foo"></a> package <span class="i">Foo</span><span class="sc">;</span></li><li><a name="new"></a> sub <span class="m">new</span> <span class="s">{</span> ... <span class="s">}</span></li><li><a name="Foo::INC"></a> sub <span class="m">Foo::INC</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="s">(</span><span class="i">$self</span><span class="cm">,</span> <span class="i">$filename</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li> ...</li><li> <span class="s">}</span></li><li></li><li> <span class="c"># In the main program</span></li><li> <a class="l_k" href="../functions/push.html">push</a> <span class="i">@INC</span><span class="cm">,</span> <span class="w">Foo</span><span class="w">->new</span><span class="s">(</span>...<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Note that these hooks are also permitted to set the %INC entry<br>
corresponding to the files they have loaded. See <a href="../perlvar.html#%25INC">"%INC" in perlvar</a>.</p>
<p>For a yet-more-powerful import facility, see <a href="../functions/use.html">"use"</a> and <a href="../perlmod.html">perlmod</a>.]]></desc>
</keyword>
<keyword name="reset" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Generally used in a <code class="inline"><a class="l_k" href="../functions/continue.html">continue</a></code> block at the end of a loop to clear<br>
variables and reset <code class="inline"><span class="q">??</span></code>
searches so that they work again. The<br>
expression is interpreted as a list of single characters (hyphens<br>
allowed for ranges). All variables and arrays beginning with one of<br>
those letters are reset to their pristine state. If the expression is<br>
omitted, one-match searches (<code class="inline"><span class="q">?pattern?</span></code>
) are reset to match again. Resets<br>
only variables or searches in the current package. Always returns<br>
1. Examples:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/reset.html">reset</a> <span class="q">'X'</span><span class="sc">;</span> <span class="c"># reset all X variables</span></li><li> <a class="l_k" href="../functions/reset.html">reset</a> <span class="q">'a-z'</span><span class="sc">;</span> <span class="c"># reset lower case variables</span></li><li> <a class="l_k" href="../functions/reset.html">reset</a><span class="sc">;</span> <span class="c"># just reset ?one-time? searches</span></li></ol></pre><p>Resetting <code class="inline"><span class="q">"A-Z"</span></code>
is not recommended because you'll wipe out your<br>
<code class="inline"><span class="i">@ARGV</span></code>
and <code class="inline"><span class="i">@INC</span></code>
arrays and your <code class="inline"><span class="i">%ENV</span></code>
hash. Resets only package<br>
variables--lexical variables are unaffected, but they clean themselves<br>
up on scope exit anyway, so you'll probably want to use them instead.<br>
See <a href="../functions/my.html">"my"</a>.]]></desc>
</keyword>
<keyword name="reset" type="function">
<params>
</params>
<desc><![CDATA[Generally used in a <code class="inline"><a class="l_k" href="../functions/continue.html">continue</a></code> block at the end of a loop to clear<br>
variables and reset <code class="inline"><span class="q">??</span></code>
searches so that they work again. The<br>
expression is interpreted as a list of single characters (hyphens<br>
allowed for ranges). All variables and arrays beginning with one of<br>
those letters are reset to their pristine state. If the expression is<br>
omitted, one-match searches (<code class="inline"><span class="q">?pattern?</span></code>
) are reset to match again. Resets<br>
only variables or searches in the current package. Always returns<br>
1. Examples:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/reset.html">reset</a> <span class="q">'X'</span><span class="sc">;</span> <span class="c"># reset all X variables</span></li><li> <a class="l_k" href="../functions/reset.html">reset</a> <span class="q">'a-z'</span><span class="sc">;</span> <span class="c"># reset lower case variables</span></li><li> <a class="l_k" href="../functions/reset.html">reset</a><span class="sc">;</span> <span class="c"># just reset ?one-time? searches</span></li></ol></pre><p>Resetting <code class="inline"><span class="q">"A-Z"</span></code>
is not recommended because you'll wipe out your<br>
<code class="inline"><span class="i">@ARGV</span></code>
and <code class="inline"><span class="i">@INC</span></code>
arrays and your <code class="inline"><span class="i">%ENV</span></code>
hash. Resets only package<br>
variables--lexical variables are unaffected, but they clean themselves<br>
up on scope exit anyway, so you'll probably want to use them instead.<br>
See <a href="../functions/my.html">"my"</a>.]]></desc>
</keyword>
<keyword name="return" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Returns from a subroutine, <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a></code>, or <code class="inline"><a class="l_k" href="../functions/do.html">do</a> <span class="w">FILE</span></code>
with the value<br>
given in EXPR. Evaluation of EXPR may be in list, scalar, or void<br>
context, depending on how the return value will be used, and the context<br>
may vary from one execution to the next (see <code class="inline"><a class="l_k" href="../functions/wantarray.html">wantarray</a></code>). If no EXPR<br>
is given, returns an empty list in list context, the undefined value in<br>
scalar context, and (of course) nothing at all in a void context.</p>
<p>(Note that in the absence of an explicit <code class="inline"><a class="l_k" href="../functions/return.html">return</a></code>, a subroutine, eval,<br>
or do FILE will automatically return the value of the last expression<br>
evaluated.)]]></desc>
</keyword>
<keyword name="return" type="function">
<params>
</params>
<desc><![CDATA[Returns from a subroutine, <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a></code>, or <code class="inline"><a class="l_k" href="../functions/do.html">do</a> <span class="w">FILE</span></code>
with the value<br>
given in EXPR. Evaluation of EXPR may be in list, scalar, or void<br>
context, depending on how the return value will be used, and the context<br>
may vary from one execution to the next (see <code class="inline"><a class="l_k" href="../functions/wantarray.html">wantarray</a></code>). If no EXPR<br>
is given, returns an empty list in list context, the undefined value in<br>
scalar context, and (of course) nothing at all in a void context.</p>
<p>(Note that in the absence of an explicit <code class="inline"><a class="l_k" href="../functions/return.html">return</a></code>, a subroutine, eval,<br>
or do FILE will automatically return the value of the last expression<br>
evaluated.)]]></desc>
</keyword>
<keyword name="reverse" type="function">
<params>
<param name='list'/>
</params>
<desc><![CDATA[In list context, returns a list value consisting of the elements<br>
of LIST in the opposite order. In scalar context, concatenates the<br>
elements of LIST and returns a string value with all characters<br>
in the opposite order.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/join.html">join</a><span class="s">(</span><span class="q">", "</span><span class="cm">,</span> <a class="l_k" href="../functions/reverse.html">reverse</a> <span class="q">"world"</span><span class="cm">,</span> <span class="q">"Hello"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># Hello, world</span></li><li></li><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/scalar.html">scalar</a> <a class="l_k" href="../functions/reverse.html">reverse</a> <span class="q">"dlrow ,"</span><span class="cm">,</span> <span class="q">"olleH"</span><span class="sc">;</span> <span class="c"># Hello, world</span></li></ol></pre><p>Used without arguments in scalar context, reverse() reverses <code class="inline"><span class="i">$_</span></code>
.</p>
<pre class="verbatim"><ol><li> <span class="i">$_</span> = <span class="q">"dlrow ,olleH"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/reverse.html">reverse</a><span class="sc">;</span> <span class="c"># No output, list context</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/scalar.html">scalar</a> <a class="l_k" href="../functions/reverse.html">reverse</a><span class="sc">;</span> <span class="c"># Hello, world</span></li></ol></pre><p>This operator is also handy for inverting a hash, although there are some<br>
caveats. If a value is duplicated in the original hash, only one of those<br>
can be represented as a key in the inverted hash. Also, this has to<br>
unwind one hash and build a whole new one, which may take some time<br>
on a large hash, such as from a DBM file.</p>
<pre class="verbatim"><ol><li> <span class="i">%by_name</span> = <a class="l_k" href="../functions/reverse.html">reverse</a> <span class="i">%by_address</span><span class="sc">;</span> <span class="c"># Invert the hash</span></li></ol><]]></desc>
</keyword>
<keyword name="rewinddir" type="function">
<params>
<param name='dirhandle'/>
</params>
<desc><![CDATA[Sets the current position to the beginning of the directory for the<br>
<code class="inline"><a class="l_k" href="../functions/readdir.html">readdir</a></code> routine on DIRHANDLE.]]></desc>
</keyword>
<keyword name="rindex" type="function">
<params>
<param name='str'/>
<param name='substr'/>
<param name='position'/>
</params>
<desc><![CDATA[Works just like index() except that it returns the position of the <i>last</i>
occurrence of SUBSTR in STR. If POSITION is specified, returns the<br>
last occurrence beginning at or before that position.]]></desc>
</keyword>
<keyword name="rindex" type="function">
<params>
<param name='str'/>
<param name='substr'/>
</params>
<desc><![CDATA[Works just like index() except that it returns the position of the <i>last</i>
occurrence of SUBSTR in STR. If POSITION is specified, returns the<br>
last occurrence beginning at or before that position.]]></desc>
</keyword>
<keyword name="rmdir" type="function">
<params>
<param name='filename'/>
</params>
<desc><![CDATA[Deletes the directory specified by FILENAME if that directory is<br>
empty. If it succeeds it returns true, otherwise it returns false and<br>
sets <code class="inline"><span class="i">$!</span></code>
(errno). If FILENAME is omitted, uses <code class="inline"><span class="i">$_</span></code>
.</p>
<p>To remove a directory tree recursively (<code class="inline"><span class="w">rm</span> -<span class="w">rf</span></code>
on unix) look at<br>
the <code class="inline"><span class="w">rmtree</span></code>
function of the <a href="../File/Path.html">File::Path</a> module.]]></desc>
</keyword>
<keyword name="rmdir" type="function">
<params>
</params>
<desc><![CDATA[Deletes the directory specified by FILENAME if that directory is<br>
empty. If it succeeds it returns true, otherwise it returns false and<br>
sets <code class="inline"><span class="i">$!</span></code>
(errno). If FILENAME is omitted, uses <code class="inline"><span class="i">$_</span></code>
.</p>
<p>To remove a directory tree recursively (<code class="inline"><span class="w">rm</span> -<span class="w">rf</span></code>
on unix) look at<br>
the <code class="inline"><span class="w">rmtree</span></code>
function of the <a href="../File/Path.html">File::Path</a> module.]]></desc>
</keyword>
<keyword name="s" type="function">
<params>
<param name='///'/>
</params>
<desc><![CDATA[The substitution operator. See <a href="../perlop.html#Regexp-Quote-Like-Operators">"Regexp Quote-Like Operators" in perlop</a>.]]></desc>
</keyword>
<keyword name="say" type="function">
<params>
<param name='filehandle list'/>
</params>
<desc><![CDATA[Just like <code class="inline"><a class="l_k" href="../functions/print.html">print</a></code>, but implicitly appends a newline.<br>
<code class="inline"><a class="l_k" href="../functions/say.html">say</a> <span class="i">LIST</span></code>
is simply an abbreviation for <code class="inline"><span class="s">{</span> <a class="l_k" href="../functions/local.html">local</a> <span class="i">$\</span> = <span class="q">"\n"</span><span class="sc">;</span> <a class="l_k" href="../functions/print.html">print</a>
<span class="i">LIST</span> <span class="s">}</span></code>
.</p>
<p>This keyword is only available when the "say" feature is<br>
enabled: see <a href="../feature.html">feature</a>.]]></desc>
</keyword>
<keyword name="say" type="function">
<params>
<param name='list'/>
</params>
<desc><![CDATA[Just like <code class="inline"><a class="l_k" href="../functions/print.html">print</a></code>, but implicitly appends a newline.<br>
<code class="inline"><a class="l_k" href="../functions/say.html">say</a> <span class="i">LIST</span></code>
is simply an abbreviation for <code class="inline"><span class="s">{</span> <a class="l_k" href="../functions/local.html">local</a> <span class="i">$\</span> = <span class="q">"\n"</span><span class="sc">;</span> <a class="l_k" href="../functions/print.html">print</a>
<span class="i">LIST</span> <span class="s">}</span></code>
.</p>
<p>This keyword is only available when the "say" feature is<br>
enabled: see <a href="../feature.html">feature</a>.]]></desc>
</keyword>
<keyword name="say" type="function">
<params>
</params>
<desc><![CDATA[Just like <code class="inline"><a class="l_k" href="../functions/print.html">print</a></code>, but implicitly appends a newline.<br>
<code class="inline"><a class="l_k" href="../functions/say.html">say</a> <span class="i">LIST</span></code>
is simply an abbreviation for <code class="inline"><span class="s">{</span> <a class="l_k" href="../functions/local.html">local</a> <span class="i">$\</span> = <span class="q">"\n"</span><span class="sc">;</span> <a class="l_k" href="../functions/print.html">print</a>
<span class="i">LIST</span> <span class="s">}</span></code>
.</p>
<p>This keyword is only available when the "say" feature is<br>
enabled: see <a href="../feature.html">feature</a>.]]></desc>
</keyword>
<keyword name="scalar" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Forces EXPR to be interpreted in scalar context and returns the value<br>
of EXPR.</p>
<pre class="verbatim"><ol><li> <span class="i">@counts</span> = <span class="s">(</span> <a class="l_k" href="../functions/scalar.html">scalar</a> <span class="i">@a</span><span class="cm">,</span> <a class="l_k" href="../functions/scalar.html">scalar</a> <span class="i">@b</span><span class="cm">,</span> <a class="l_k" href="../functions/scalar.html">scalar</a> <span class="i">@c</span> <span class="s">)</span><span class="sc">;</span></li></ol></pre><p>There is no equivalent operator to force an expression to<br>
be interpolated in list context because in practice, this is never<br>
needed. If you really wanted to do so, however, you could use<br>
the construction <code class="inline"><span class="i">@</span>{<span class="s">[</span> <span class="s">(</span><span class="w">some</span> <span class="w">expression</span><span class="s">)</span> <span class="s">]</span>}</code>
, but usually a simple<br>
<code class="inline"><span class="s">(</span><span class="w">some</span> <span class="w">expression</span><span class="s">)</span></code>
suffices.</p>
<p>Because <code class="inline"><a class="l_k" href="../functions/scalar.html">scalar</a></code> is unary operator, if you accidentally use for EXPR a<br>
parenthesized list, this behaves as a scalar comma expression, evaluating<br>
all but the last element in void context and returning the final element<br>
evaluated in scalar context. This is seldom what you want.</p>
<p>The following single statement:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/uc.html">uc</a><span class="s">(</span><a class="l_k" href="../functions/scalar.html">scalar</a><span class="s">(</span><span class="i">&foo</span><span class="cm">,</span><span class="i">$bar</span><span class="s">)</span><span class="s">)</span><span class="cm">,</span><span class="i">$baz</span><span class="sc">;</span></li></ol></pre><p>is the moral equivalent of these two:</p>
<pre class="verbatim"><ol><li> <span class="i">&foo</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a><span class="s">(</span><a class="l_k" href="../functions/uc.html">uc</a><span class="s">(</span><span class="i">$bar</span><span class="s">)</span><span class="cm">,</span><span class="i">$baz</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>See <a href="../perlop.html">perlop</a> for more details on unary operators and the comma operator.]]></desc>
</keyword>
<keyword name="seek" type="function">
<params>
<param name='filehandle'/>
<param name='position'/>
<param name='whence'/>
</params>
<desc><![CDATA[Sets FILEHANDLE's position, just like the <code class="inline"><span class="w">fseek</span></code>
call of <code class="inline"><span class="w">stdio</span></code>
.<br>
FILEHANDLE may be an expression whose value gives the name of the<br>
filehandle. The values for WHENCE are <code class="inline"><span class="n">0</span></code>
to set the new position<br>
<i>in bytes</i> to POSITION, <code class="inline"><span class="n">1</span></code>
to set it to the current position plus<br>
POSITION, and <code class="inline"><span class="n">2</span></code>
to set it to EOF plus POSITION (typically<br>
negative). For WHENCE you may use the constants <code class="inline"><span class="w">SEEK_SET</span></code>
,<br>
<code class="inline"><span class="w">SEEK_CUR</span></code>
, and <code class="inline"><span class="w">SEEK_END</span></code>
(start of the file, current position, end<br>
of the file) from the Fcntl module. Returns <code class="inline"><span class="n">1</span></code>
upon success, <code class="inline"><span class="n">0</span></code>
<br>
otherwise.</p>
<p>Note the <i>in bytes</i>: even if the filehandle has been set to<br>
operate on characters (for example by using the <code class="inline"><span class="j">:</span><span class="i">encoding</span><span class="s">(</span><span class="w">utf8</span><span class="s">)</span></code>
open<br>
layer), tell() will return byte offsets, not character offsets<br>
(because implementing that would render seek() and tell() rather slow).</p>
<p>If you want to position file for <code class="inline"><a class="l_k" href="../functions/sysread.html">sysread</a></code> or <code class="inline"><a class="l_k" href="../functions/syswrite.html">syswrite</a></code>, don't use<br>
<code class="inline"><a class="l_k" href="../functions/seek.html">seek</a></code>--buffering makes its effect on the file's system position<br>
unpredictable and non-portable. Use <code class="inline"><a class="l_k" href="../functions/sysseek.html">sysseek</a></code> instead.</p>
<p>Due to the rules and rigors of ANSI C, on some systems you have to do a<br>
seek whenever you switch between reading and writing. Amongst other<br>
things, this may have the effect of calling stdio's clearerr(3).<br>
A WHENCE of <code class="inline"><span class="n">1</span></code>
(<code class="inline"><span class="w">SEEK_CUR</span></code>
) is useful for not moving the file position:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/seek.html">seek</a><span class="s">(</span><span class="w">TEST</span><span class="cm">,</span><span class="n">0</span><span class="cm">,</span><span class="n">1</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>This is also useful for applications emulating <code class="inline"><span class="w">tail</span> -f</code>
. Once you hit<br>
EOF on your read, and then sleep for a while, you might have to stick in a<br>
seek() to reset things. The <code class="inline"><a class="l_k" href="../functions/seek.html">seek</a></code> doesn't change the current position,<br>
but it <i>does</i> clear the end-of-file condition on the handle, so that the<br>
next <code class="inline"><span class="q"><FILE></span></code>
makes Perl try again to read something. We hope.</p>
<p>If that doesn't work (some IO implementations are particularly<br>
cantankerous), then you may need something more like this:</p>
<pre class="verbatim"><ol><li> for <span class="s">(</span><span class="sc">;</span><span class="sc">;</span><span class="s">)</span> <span class="s">{</span></li><li> for <span class="s">(</span><span class="i">$curpos</span> = <a class="l_k" href="../functions/tell.html">tell</a><span class="s">(</span><span class="w">FILE</span><span class="s">)</span><span class="sc">;</span> <span class="i">$_</span> = <span class="q"><FILE></span><span class="sc">;</span></li><li> <span class="i">$curpos</span> = <a class="l_k" href="../functions/tell.html">tell</a><span class="s">(</span><span class="w">FILE</span><span class="s">)</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="c"># search for some stuff and put it into files</span></li><li> <span class="s">}</span></li><li> <a class="l_k" href="../functions/sleep.html">sleep</a><span class="s">(</span><span class="i">$for_a_while</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/seek.html">seek</a><span class="s">(</span><span class="w">FILE</span><span class="cm">,</span> <span class="i">$curpos</span><span class="cm">,</span> <span class="n">0</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol><]]></desc>
</keyword>
<keyword name="seekdir" type="function">
<params>
<param name='dirhandle'/>
<param name='pos'/>
</params>
<desc><![CDATA[Sets the current position for the <code class="inline"><a class="l_k" href="../functions/readdir.html">readdir</a></code> routine on DIRHANDLE. POS<br>
must be a value returned by <code class="inline"><a class="l_k" href="../functions/telldir.html">telldir</a></code>. <code class="inline"><a class="l_k" href="../functions/seekdir.html">seekdir</a></code> also has the same caveats<br>
about possible directory compaction as the corresponding system library<br>
routine.]]></desc>
</keyword>
<keyword name="select" type="function">
<params>
<param name='filehandle'/>
</params>
<desc><![CDATA[Returns the currently selected filehandle. If FILEHANDLE is supplied,<br>
sets the new current default filehandle for output. This has two<br>
effects: first, a <code class="inline"><a class="l_k" href="../functions/write.html">write</a></code> or a <code class="inline"><a class="l_k" href="../functions/print.html">print</a></code> without a filehandle will<br>
default to this FILEHANDLE. Second, references to variables related to<br>
output will refer to this output channel. For example, if you have to<br>
set the top of form format for more than one output channel, you might<br>
do the following:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/select.html">select</a><span class="s">(</span><span class="w">REPORT1</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$^</span> = <span class="q">'report1_top'</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/select.html">select</a><span class="s">(</span><span class="w">REPORT2</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$^</span> = <span class="q">'report2_top'</span><span class="sc">;</span></li></ol></pre><p>FILEHANDLE may be an expression whose value gives the name of the<br>
actual filehandle. Thus:</p>
<pre class="verbatim"><ol><li> <span class="i">$oldfh</span> = <a class="l_k" href="../functions/select.html">select</a><span class="s">(</span><span class="w">STDERR</span><span class="s">)</span><span class="sc">;</span> <span class="i">$|</span> = <span class="n">1</span><span class="sc">;</span> <a class="l_k" href="../functions/select.html">select</a><span class="s">(</span><span class="i">$oldfh</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Some programmers may prefer to think of filehandles as objects with<br>
methods, preferring to write the last example as:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">IO::Handle</span><span class="sc">;</span></li><li> <span class="w">STDERR</span><span class="w">->autoflush</span><span class="s">(</span><span class="n">1</span><span class="s">)</span><span class="sc">;</span></li></ol><]]></desc>
</keyword>
<keyword name="select" type="function">
<params>
</params>
<desc><![CDATA[Returns the currently selected filehandle. If FILEHANDLE is supplied,<br>
sets the new current default filehandle for output. This has two<br>
effects: first, a <code class="inline"><a class="l_k" href="../functions/write.html">write</a></code> or a <code class="inline"><a class="l_k" href="../functions/print.html">print</a></code> without a filehandle will<br>
default to this FILEHANDLE. Second, references to variables related to<br>
output will refer to this output channel. For example, if you have to<br>
set the top of form format for more than one output channel, you might<br>
do the following:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/select.html">select</a><span class="s">(</span><span class="w">REPORT1</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$^</span> = <span class="q">'report1_top'</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/select.html">select</a><span class="s">(</span><span class="w">REPORT2</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$^</span> = <span class="q">'report2_top'</span><span class="sc">;</span></li></ol></pre><p>FILEHANDLE may be an expression whose value gives the name of the<br>
actual filehandle. Thus:</p>
<pre class="verbatim"><ol><li> <span class="i">$oldfh</span> = <a class="l_k" href="../functions/select.html">select</a><span class="s">(</span><span class="w">STDERR</span><span class="s">)</span><span class="sc">;</span> <span class="i">$|</span> = <span class="n">1</span><span class="sc">;</span> <a class="l_k" href="../functions/select.html">select</a><span class="s">(</span><span class="i">$oldfh</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Some programmers may prefer to think of filehandles as objects with<br>
methods, preferring to write the last example as:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">IO::Handle</span><span class="sc">;</span></li><li> <span class="w">STDERR</span><span class="w">->autoflush</span><span class="s">(</span><span class="n">1</span><span class="s">)</span><span class="sc">;</span></li></ol><]]></desc>
</keyword>
<keyword name="semctl" type="function">
<params>
<param name='id'/>
<param name='semnum'/>
<param name='cmd'/>
<param name='arg'/>
</params>
<desc><![CDATA[Calls the System V IPC function <code class="inline"><a class="l_k" href="../functions/semctl.html">semctl</a></code>. You'll probably have to say</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">IPC::SysV</span><span class="sc">;</span></li></ol></pre><p>first to get the correct constant definitions. If CMD is IPC_STAT or<br>
GETALL, then ARG must be a variable that will hold the returned<br>
semid_ds structure or semaphore value array. Returns like <code class="inline"><a class="l_k" href="../functions/ioctl.html">ioctl</a></code>:<br>
the undefined value for error, "<code class="inline">0 but true</code>" for zero, or the actual<br>
return value otherwise. The ARG must consist of a vector of native<br>
short integers, which may be created with <code class="inline"><a class="l_k" href="../functions/pack.html">pack("s!",(0)x$nsem)</a></code>.<br>
See also <a href="../perlipc.html#SysV-IPC">"SysV IPC" in perlipc</a>, <code class="inline"><span class="w">IPC::SysV</span></code>
, <code class="inline"><span class="w">IPC::Semaphore</span></code>
<br>
documentation.]]></desc>
</keyword>
<keyword name="semget" type="function">
<params>
<param name='key'/>
<param name='nsems'/>
<param name='flags'/>
</params>
<desc><![CDATA[Calls the System V IPC function semget. Returns the semaphore id, or<br>
the undefined value if there is an error. See also<br>
<a href="../perlipc.html#SysV-IPC">"SysV IPC" in perlipc</a>, <code class="inline"><span class="w">IPC::SysV</span></code>
, <code class="inline"><span class="w">IPC::SysV::Semaphore</span></code>
<br>
documentation.]]></desc>
</keyword>
<keyword name="semop" type="function">
<params>
<param name='key'/>
<param name='opstring'/>
</params>
<desc><![CDATA[Calls the System V IPC function semop to perform semaphore operations<br>
such as signalling and waiting. OPSTRING must be a packed array of<br>
semop structures. Each semop structure can be generated with<br>
<code class="inline"><a class="l_k" href="../functions/pack.html">pack</a><span class="s">(</span><span class="q">"s!3"</span><span class="cm">,</span> <span class="i">$semnum</span><span class="cm">,</span> <span class="i">$semop</span><span class="cm">,</span> <span class="i">$semflag</span><span class="s">)</span></code>
. The length of OPSTRING <br>
implies the number of semaphore operations. Returns true if<br>
successful, or false if there is an error. As an example, the<br>
following code waits on semaphore $semnum of semaphore id $semid:</p>
<pre class="verbatim"><ol><li> <span class="i">$semop</span> = <a class="l_k" href="../functions/pack.html">pack</a><span class="s">(</span><span class="q">"s!3"</span><span class="cm">,</span> <span class="i">$semnum</span><span class="cm">,</span> <span class="n">-1</span><span class="cm">,</span> <span class="n">0</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Semaphore trouble: $!\n"</span> unless <a class="l_k" href="../functions/semop.html">semop</a><span class="s">(</span><span class="i">$semid</span><span class="cm">,</span> <span class="i">$semop</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>To signal the semaphore, replace <code class="inline"><span class="n">-1</span></code>
with <code class="inline"><span class="n">1</span></code>
. See also<br>
<a href="../perlipc.html#SysV-IPC">"SysV IPC" in perlipc</a>, <code class="inline"><span class="w">IPC::SysV</span></code>
, and <code class="inline"><span class="w">IPC::SysV::Semaphore</span></code>
<br>
documentation.]]></desc>
</keyword>
<keyword name="send" type="function">
<params>
<param name='socket'/>
<param name='msg'/>
<param name='flags'/>
<param name='to'/>
</params>
<desc><![CDATA[Sends a message on a socket. Attempts to send the scalar MSG to the<br>
SOCKET filehandle. Takes the same flags as the system call of the<br>
same name. On unconnected sockets you must specify a destination to<br>
send TO, in which case it does a C <code class="inline"><span class="w">sendto</span></code>
. Returns the number of<br>
characters sent, or the undefined value if there is an error. The C<br>
system call sendmsg(2) is currently unimplemented. See<br>
<a href="../perlipc.html#UDP%3a-Message-Passing">"UDP: Message Passing" in perlipc</a> for examples.</p>
<p>Note the <i>characters</i>: depending on the status of the socket, either<br>
(8-bit) bytes or characters are sent. By default all sockets operate<br>
on bytes, but for example if the socket has been changed using<br>
binmode() to operate with the <code class="inline"><span class="j">:</span><span class="i">encoding</span><span class="s">(</span><span class="w">utf8</span><span class="s">)</span></code>
I/O layer (see<br>
<a href="../functions/open.html">"open"</a>, or the <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> pragma, <a href="../open.html">open</a>), the I/O will operate on UTF-8<br>
encoded Unicode characters, not bytes. Similarly for the <code class="inline"><span class="j">:</span><span class="w">encoding</span></code>
<br>
pragma: in that case pretty much any characters can be sent.]]></desc>
</keyword>
<keyword name="send" type="function">
<params>
<param name='socket'/>
<param name='msg'/>
<param name='flags'/>
</params>
<desc><![CDATA[Sends a message on a socket. Attempts to send the scalar MSG to the<br>
SOCKET filehandle. Takes the same flags as the system call of the<br>
same name. On unconnected sockets you must specify a destination to<br>
send TO, in which case it does a C <code class="inline"><span class="w">sendto</span></code>
. Returns the number of<br>
characters sent, or the undefined value if there is an error. The C<br>
system call sendmsg(2) is currently unimplemented. See<br>
<a href="../perlipc.html#UDP%3a-Message-Passing">"UDP: Message Passing" in perlipc</a> for examples.</p>
<p>Note the <i>characters</i>: depending on the status of the socket, either<br>
(8-bit) bytes or characters are sent. By default all sockets operate<br>
on bytes, but for example if the socket has been changed using<br>
binmode() to operate with the <code class="inline"><span class="j">:</span><span class="i">encoding</span><span class="s">(</span><span class="w">utf8</span><span class="s">)</span></code>
I/O layer (see<br>
<a href="../functions/open.html">"open"</a>, or the <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> pragma, <a href="../open.html">open</a>), the I/O will operate on UTF-8<br>
encoded Unicode characters, not bytes. Similarly for the <code class="inline"><span class="j">:</span><span class="w">encoding</span></code>
<br>
pragma: in that case pretty much any characters can be sent.]]></desc>
</keyword>
<keyword name="setgrent" type="function">
<params>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="sethostent" type="function">
<params>
<param name='stayopen'/>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="setnetent" type="function">
<params>
<param name='stayopen'/>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="setpgrp" type="function">
<params>
<param name='pid'/>
<param name='pgrp'/>
</params>
<desc><![CDATA[Sets the current process group for the specified PID, <code class="inline"><span class="n">0</span></code>
for the current<br>
process. Will produce a fatal error if used on a machine that doesn't<br>
implement POSIX setpgid(2) or BSD setpgrp(2). If the arguments are omitted,<br>
it defaults to <code class="inline"><span class="n">0</span><span class="cm">,</span><span class="n">0</span></code>
. Note that the BSD 4.2 version of <code class="inline"><a class="l_k" href="../functions/setpgrp.html">setpgrp</a></code> does not<br>
accept any arguments, so only <code class="inline"><a class="l_k" href="../functions/setpgrp.html">setpgrp(0,0)</a></code> is portable. See also<br>
<code class="inline"><span class="i">POSIX::setsid</span><span class="s">(</span><span class="s">)</span></code>
.]]></desc>
</keyword>
<keyword name="setpriority" type="function">
<params>
<param name='which'/>
<param name='who'/>
<param name='priority'/>
</params>
<desc><![CDATA[Sets the current priority for a process, a process group, or a user.<br>
(See setpriority(2).) Will produce a fatal error if used on a machine<br>
that doesn't implement setpriority(2).]]></desc>
</keyword>
<keyword name="setprotoent" type="function">
<params>
<param name='stayopen'/>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="setpwent" type="function">
<params>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="setservent" type="function">
<params>
<param name='stayopen'/>
</params>
<desc><![CDATA[These routines perform the same functions as their counterparts in the<br>
system library. In list context, the return values from the<br>
various get routines are as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$quota</span><span class="cm">,</span><span class="i">$comment</span><span class="cm">,</span><span class="i">$gcos</span><span class="cm">,</span><span class="i">$dir</span><span class="cm">,</span><span class="i">$shell</span><span class="cm">,</span><span class="i">$expire</span><span class="s">)</span> = <span class="w">getpw</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$passwd</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$members</span><span class="s">)</span> = <span class="w">getgr</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$length</span><span class="cm">,</span><span class="i">@addrs</span><span class="s">)</span> = <span class="w">gethost</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$addrtype</span><span class="cm">,</span><span class="i">$net</span><span class="s">)</span> = <span class="w">getnet</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getproto</span>*</li><li> <span class="s">(</span><span class="i">$name</span><span class="cm">,</span><span class="i">$aliases</span><span class="cm">,</span><span class="i">$port</span><span class="cm">,</span><span class="i">$proto</span><span class="s">)</span> = <span class="w">getserv</span>*</li></ol></pre><p>(If the entry doesn't exist you get a null list.)</p>
<p>The exact meaning of the $gcos field varies but it usually contains<br>
the real name of the user (as opposed to the login name) and other<br>
information pertaining to the user. Beware, however, that in many<br>
system users are able to change this information and therefore it<br>
cannot be trusted and therefore the $gcos is tainted (see<br>
<a href="../perlsec.html">perlsec</a>). The $passwd and $shell, user's encrypted password and<br>
login shell, are also tainted, because of the same reason.</p>
<p>In scalar context, you get the name, unless the function was a<br>
lookup by name, in which case you get the other thing, whatever it is.<br>
(If the entry doesn't exist you get the undefined value.) For example:</p>
<pre class="verbatim"><ol><li> <span class="i">$uid</span> = <a class="l_k" href="../functions/getpwnam.html">getpwnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwuid.html">getpwuid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getpwent.html">getpwent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$gid</span> = <a class="l_k" href="../functions/getgrnam.html">getgrnam</a><span class="s">(</span><span class="i">$name</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrgid.html">getgrgid</a><span class="s">(</span><span class="i">$num</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/getgrent.html">getgrent</a><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#etc.</span></li></ol></pre><p>In <i>getpw*()</i> the fields $quota, $comment, and $expire are special<br>
cases in the sense that in many systems they are unsupported. If the<br>
$quota is unsupported, it is an empty scalar. If it is supported, it<br>
usually encodes the disk quota. If the $comment field is unsupported,<br>
it is an empty scalar. If it is supported it usually encodes some<br>
administrative comment about the user. In some systems the $quota<br>
field may be $change or $age, fields that have to do with password<br>
aging. In some systems the $comment field may be $class. The $expire<br>
field, if present, encodes the expiration period of the account or the<br>
password. For the availability and the exact meaning of these fields<br>
in your system, please consult your getpwnam(3) documentation and your<br>
<i>pwd.h</i> file. You can also find out from within Perl what your<br>
$quota and $comment fields mean and whether you have the $expire field<br>
by using the <code class="inline"><span class="w">Config</span></code>
module and the values <code class="inline"><span class="w">d_pwquota</span></code>
, <code class="inline"><span class="w">d_pwage</span></code>
,<br>
<code class="inline"><span class="w">d_pwchange</span></code>
, <code class="inline"><span class="w">d_pwcomment</span></code>
, and <code class="inline"><span class="w">d_pwexpire</span></code>
. Shadow password<br>
files are only supported if your vendor has implemented them in the<br>
intuitive fashion that calling the regular C library routines gets the<br>
shadow versions if you're running under privilege or if there exists<br>
the shadow(3) functions as found in System V (this includes Solaris<br>
and Linux.) Those systems that implement a proprietary shadow password<br>
facility are unlikely to be supported.</p>
<p>The $members value returned by <i>getgr*()</i> is a space separated list of<br>
the login names of the members of the group.</p>
<p>For the <i>gethost*()</i> functions, if the <code class="inline"><span class="w">h_errno</span></code>
variable is supported in<br>
C, it will be returned to you via <code class="inline"><span class="i">$?</span></code>
if the function call fails. The<br>
<code class="inline"><span class="i">@addrs</span></code>
value returned by a successful call is a list of the raw<br>
addresses returned by the corresponding system library call. In the<br>
Internet domain, each address is four bytes long and you can unpack it<br>
by saying something like:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="cm">,</span><span class="i">$c</span><span class="cm">,</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'W4'</span><span class="cm">,</span><span class="i">$addr</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The Socket library makes this slightly easier:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$iaddr</span> = <span class="i">inet_aton</span><span class="s">(</span><span class="q">"127.1"</span><span class="s">)</span><span class="sc">;</span> <span class="c"># or whatever address</span></li><li> <span class="i">$name</span> = <a class="l_k" href="../functions/gethostbyaddr.html">gethostbyaddr</a><span class="s">(</span><span class="i">$iaddr</span><span class="cm">,</span> <span class="w">AF_INET</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># or going the other way</span></li><li> <span class="i">$straddr</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$iaddr</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In the opposite way, to resolve a hostname to the IP address<br>
you can write this:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <span class="i">$packed_ip</span> = <a class="l_k" href="../functions/gethostbyname.html">gethostbyname</a><span class="s">(</span><span class="q">"www.perl.org"</span><span class="s">)</span><span class="sc">;</span></li><li> if <span class="s">(</span><a class="l_k" href="../functions/defined.html">defined</a> <span class="i">$packed_ip</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$ip_address</span> = <span class="i">inet_ntoa</span><span class="s">(</span><span class="i">$packed_ip</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Make sure <gethostbyname()> is called in SCALAR context and that<br>
its return value is checked for definedness.</p>
<p>If you get tired of remembering which element of the return list<br>
contains which return value, by-name interfaces are provided<br>
in standard modules: <code class="inline"><span class="w">File::stat</span></code>
, <code class="inline"><span class="w">Net::hostent</span></code>
, <code class="inline"><span class="w">Net::netent</span></code>
,<br>
<code class="inline"><span class="w">Net::protoent</span></code>
, <code class="inline"><span class="w">Net::servent</span></code>
, <code class="inline"><span class="w">Time::gmtime</span></code>
, <code class="inline"><span class="w">Time::localtime</span></code>
,<br>
and <code class="inline"><span class="w">User::grent</span></code>
. These override the normal built-ins, supplying<br>
versions that return objects with the appropriate names<br>
for each field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">User::pwent</span><span class="sc">;</span></li><li> <span class="i">$is_his</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="i">->uid</span> == <span class="i">pwent</span><span class="s">(</span><span class="i">$whoever</span><span class="s">)</span><span class="i">->uid</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Even though it looks like they're the same method calls (uid),<br>
they aren't, because a <code class="inline"><span class="w">File::stat</span></code>
object is different from<br>
a <code class="inline"><span class="w">User::pwent</span></code>
object.]]></desc>
</keyword>
<keyword name="setsockopt" type="function">
<params>
<param name='socket'/>
<param name='level'/>
<param name='optname'/>
<param name='optval'/>
</params>
<desc><![CDATA[Sets the socket option requested. Returns undefined if there is an<br>
error. Use integer constants provided by the <code class="inline"><span class="w">Socket</span></code>
module for<br>
LEVEL and OPNAME. Values for LEVEL can also be obtained from<br>
getprotobyname. OPTVAL might either be a packed string or an integer.<br>
An integer OPTVAL is shorthand for pack("i", OPTVAL).</p>
<p>An example disabling the Nagle's algorithm for a socket:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span> <span class="q">qw(IPPROTO_TCP TCP_NODELAY)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/setsockopt.html">setsockopt</a><span class="s">(</span><span class="i">$socket</span><span class="cm">,</span> <span class="w">IPPROTO_TCP</span><span class="cm">,</span> <span class="w">TCP_NODELAY</span><span class="cm">,</span> <span class="n">1</span><span class="s">)</span><span class="sc">;</span></li></ol><]]></desc>
</keyword>
<keyword name="shift" type="function">
<params>
<param name='array'/>
</params>
<desc><![CDATA[Shifts the first value of the array off and returns it, shortening the<br>
array by 1 and moving everything down. If there are no elements in the<br>
array, returns the undefined value. If ARRAY is omitted, shifts the<br>
<code class="inline"><span class="i">@_</span></code>
array within the lexical scope of subroutines and formats, and the<br>
<code class="inline"><span class="i">@ARGV</span></code>
array outside of a subroutine and also within the lexical scopes<br>
established by the <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a> <span class="w">STRING</span></code>
, <code class="inline">BEGIN <span class="s">{</span><span class="s">}</span></code>
, <code class="inline">INIT <span class="s">{</span><span class="s">}</span></code>
, <code class="inline">CHECK <span class="s">{</span><span class="s">}</span></code>
,<br>
<code class="inline">UNITCHECK <span class="s">{</span><span class="s">}</span></code>
and <code class="inline">END <span class="s">{</span><span class="s">}</span></code>
constructs.</p>
<p>See also <code class="inline"><a class="l_k" href="../functions/unshift.html">unshift</a></code>, <code class="inline"><a class="l_k" href="../functions/push.html">push</a></code>, and <code class="inline"><a class="l_k" href="../functions/pop.html">pop</a></code>. <code class="inline"><a class="l_k" href="../functions/shift.html">shift</a></code> and <code class="inline"><a class="l_k" href="../functions/unshift.html">unshift</a></code> do the<br>
same thing to the left end of an array that <code class="inline"><a class="l_k" href="../functions/pop.html">pop</a></code> and <code class="inline"><a class="l_k" href="../functions/push.html">push</a></code> do to the<br>
right end.]]></desc>
</keyword>
<keyword name="shift" type="function">
<params>
</params>
<desc><![CDATA[Shifts the first value of the array off and returns it, shortening the<br>
array by 1 and moving everything down. If there are no elements in the<br>
array, returns the undefined value. If ARRAY is omitted, shifts the<br>
<code class="inline"><span class="i">@_</span></code>
array within the lexical scope of subroutines and formats, and the<br>
<code class="inline"><span class="i">@ARGV</span></code>
array outside of a subroutine and also within the lexical scopes<br>
established by the <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a> <span class="w">STRING</span></code>
, <code class="inline">BEGIN <span class="s">{</span><span class="s">}</span></code>
, <code class="inline">INIT <span class="s">{</span><span class="s">}</span></code>
, <code class="inline">CHECK <span class="s">{</span><span class="s">}</span></code>
,<br>
<code class="inline">UNITCHECK <span class="s">{</span><span class="s">}</span></code>
and <code class="inline">END <span class="s">{</span><span class="s">}</span></code>
constructs.</p>
<p>See also <code class="inline"><a class="l_k" href="../functions/unshift.html">unshift</a></code>, <code class="inline"><a class="l_k" href="../functions/push.html">push</a></code>, and <code class="inline"><a class="l_k" href="../functions/pop.html">pop</a></code>. <code class="inline"><a class="l_k" href="../functions/shift.html">shift</a></code> and <code class="inline"><a class="l_k" href="../functions/unshift.html">unshift</a></code> do the<br>
same thing to the left end of an array that <code class="inline"><a class="l_k" href="../functions/pop.html">pop</a></code> and <code class="inline"><a class="l_k" href="../functions/push.html">push</a></code> do to the<br>
right end.]]></desc>
</keyword>
<keyword name="shmctl" type="function">
<params>
<param name='id'/>
<param name='cmd'/>
<param name='arg'/>
</params>
<desc><![CDATA[Calls the System V IPC function shmctl. You'll probably have to say</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">IPC::SysV</span><span class="sc">;</span></li></ol></pre><p>first to get the correct constant definitions. If CMD is <code class="inline"><span class="w">IPC_STAT</span></code>
,<br>
then ARG must be a variable that will hold the returned <code class="inline"><span class="w">shmid_ds</span></code>
<br>
structure. Returns like ioctl: the undefined value for error, "<code class="inline"><span class="n">0</span></code>
but<br>
true" for zero, or the actual return value otherwise.<br>
See also <a href="../perlipc.html#SysV-IPC">"SysV IPC" in perlipc</a> and <code class="inline"><span class="w">IPC::SysV</span></code>
documentation.]]></desc>
</keyword>
<keyword name="shmget" type="function">
<params>
<param name='key'/>
<param name='size'/>
<param name='flags'/>
</params>
<desc><![CDATA[Calls the System V IPC function shmget. Returns the shared memory<br>
segment id, or the undefined value if there is an error.<br>
See also <a href="../perlipc.html#SysV-IPC">"SysV IPC" in perlipc</a> and <code class="inline"><span class="w">IPC::SysV</span></code>
documentation.]]></desc>
</keyword>
<keyword name="shmread" type="function">
<params>
<param name='id'/>
<param name='var'/>
<param name='pos'/>
<param name='size'/>
</params>
<desc></desc>
</keyword>
<keyword name="shmwrite" type="function">
<params>
<param name='id'/>
<param name='string'/>
<param name='pos'/>
<param name='size'/>
</params>
<desc><![CDATA[Reads or writes the System V shared memory segment ID starting at<br>
position POS for size SIZE by attaching to it, copying in/out, and<br>
detaching from it. When reading, VAR must be a variable that will<br>
hold the data read. When writing, if STRING is too long, only SIZE<br>
bytes are used; if STRING is too short, nulls are written to fill out<br>
SIZE bytes. Return true if successful, or false if there is an error.<br>
shmread() taints the variable. See also <a href="../perlipc.html#SysV-IPC">"SysV IPC" in perlipc</a>,<br>
<code class="inline"><span class="w">IPC::SysV</span></code>
documentation, and the <code class="inline"><span class="w">IPC::Shareable</span></code>
module from CPAN.]]></desc>
</keyword>
<keyword name="shutdown" type="function">
<params>
<param name='socket'/>
<param name='how'/>
</params>
<desc><![CDATA[Shuts down a socket connection in the manner indicated by HOW, which<br>
has the same interpretation as in the system call of the same name.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/shutdown.html">shutdown</a><span class="s">(</span><span class="w">SOCKET</span><span class="cm">,</span> <span class="n">0</span><span class="s">)</span><span class="sc">;</span> <span class="c"># I/we have stopped reading data</span></li><li> <a class="l_k" href="../functions/shutdown.html">shutdown</a><span class="s">(</span><span class="w">SOCKET</span><span class="cm">,</span> <span class="n">1</span><span class="s">)</span><span class="sc">;</span> <span class="c"># I/we have stopped writing data</span></li><li> <a class="l_k" href="../functions/shutdown.html">shutdown</a><span class="s">(</span><span class="w">SOCKET</span><span class="cm">,</span> <span class="n">2</span><span class="s">)</span><span class="sc">;</span> <span class="c"># I/we have stopped using this socket</span></li></ol></pre><p>This is useful with sockets when you want to tell the other<br>
side you're done writing but not done reading, or vice versa.<br>
It's also a more insistent form of close because it also<br>
disables the file descriptor in any forked copies in other<br>
processes.</p>
<p>Returns <code class="inline"><span class="n">1</span></code>
for success. In the case of error, returns <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> if<br>
the first argument is not a valid filehandle, or returns <code class="inline"><span class="n">0</span></code>
and sets<br>
<code class="inline"><span class="i">$!</span></code>
for any other failure.]]></desc>
</keyword>
<keyword name="sin" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Returns the sine of EXPR (expressed in radians). If EXPR is omitted,<br>
returns sine of <code class="inline"><span class="i">$_</span></code>
.</p>
<p>For the inverse sine operation, you may use the <code class="inline"><span class="w">Math::Trig::asin</span></code>
<br>
function, or use this relation:</p>
<pre class="verbatim"><ol><li><a name="asin"></a> sub <span class="m">asin</span> <span class="s">{</span> <a class="l_k" href="../functions/atan2.html">atan2</a><span class="s">(</span><span class="i">$_</span>[<span class="n">0</span>]<span class="cm">,</span> <a class="l_k" href="../functions/sqrt.html">sqrt</a><span class="s">(</span><span class="n">1</span> - <span class="i">$_</span>[<span class="n">0</span>] * <span class="i">$_</span>[<span class="n">0</span>]<span class="s">)</span><span class="s">)</span> <span class="s">}</span></li></ol><]]></desc>
</keyword>
<keyword name="sin" type="function">
<params>
</params>
<desc><![CDATA[Returns the sine of EXPR (expressed in radians). If EXPR is omitted,<br>
returns sine of <code class="inline"><span class="i">$_</span></code>
.</p>
<p>For the inverse sine operation, you may use the <code class="inline"><span class="w">Math::Trig::asin</span></code>
<br>
function, or use this relation:</p>
<pre class="verbatim"><ol><li><a name="asin"></a> sub <span class="m">asin</span> <span class="s">{</span> <a class="l_k" href="../functions/atan2.html">atan2</a><span class="s">(</span><span class="i">$_</span>[<span class="n">0</span>]<span class="cm">,</span> <a class="l_k" href="../functions/sqrt.html">sqrt</a><span class="s">(</span><span class="n">1</span> - <span class="i">$_</span>[<span class="n">0</span>] * <span class="i">$_</span>[<span class="n">0</span>]<span class="s">)</span><span class="s">)</span> <span class="s">}</span></li></ol><]]></desc>
</keyword>
<keyword name="sleep" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Causes the script to sleep for EXPR seconds, or forever if no EXPR.<br>
Returns the number of seconds actually slept.</p>
<p>May be interrupted if the process receives a signal such as <code class="inline"><span class="w">SIGALRM</span></code>
.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/eval.html">eval</a> <span class="s">{</span></li><li> <a class="l_k" href="../functions/local.html">local</a> <span class="i">$SIG</span>{<span class="w">ALARM</span>} = <a class="l_k" href="../functions/sub.html">sub</a> <span class="s">{</span> <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Alarm!\n"</span> <span class="s">}</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/sleep.html">sleep</a><span class="sc">;</span></li><li> <span class="s">}</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/die.html">die</a> <span class="i">$@</span> unless <span class="i">$@</span> eq <span class="q">"Alarm!\n"</span><span class="sc">;</span></li></ol></pre><p>You probably cannot mix <code class="inline"><a class="l_k" href="../functions/alarm.html">alarm</a></code> and <code class="inline"><a class="l_k" href="../functions/sleep.html">sleep</a></code> calls, because <code class="inline"><a class="l_k" href="../functions/sleep.html">sleep</a></code>
is often implemented using <code class="inline"><a class="l_k" href="../functions/alarm.html">alarm</a></code>.</p>
<p>On some older systems, it may sleep up to a full second less than what<br>
you requested, depending on how it counts seconds. Most modern systems<br>
always sleep the full amount. They may appear to sleep longer than that,<br>
however, because your process might not be scheduled right away in a<br>
busy multitasking system.</p>
<p>For delays of finer granularity than one second, the Time::HiRes module<br>
(from CPAN, and starting from Perl 5.8 part of the standard<br>
distribution) provides usleep(). You may also use Perl's four-argument<br>
version of select() leaving the first three arguments undefined, or you<br>
might be able to use the <code class="inline"><a class="l_k" href="../functions/syscall.html">syscall</a></code> interface to access setitimer(2) if<br>
your system supports it. See <a href="../perlfaq8.html">perlfaq8</a> for details.</p>
<p>See also the POSIX module's <code class="inline"><span class="w">pause</span></code>
function.]]></desc>
</keyword>
<keyword name="sleep" type="function">
<params>
</params>
<desc><![CDATA[Causes the script to sleep for EXPR seconds, or forever if no EXPR.<br>
Returns the number of seconds actually slept.</p>
<p>May be interrupted if the process receives a signal such as <code class="inline"><span class="w">SIGALRM</span></code>
.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/eval.html">eval</a> <span class="s">{</span></li><li> <a class="l_k" href="../functions/local.html">local</a> <span class="i">$SIG</span>{<span class="w">ALARM</span>} = <a class="l_k" href="../functions/sub.html">sub</a> <span class="s">{</span> <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Alarm!\n"</span> <span class="s">}</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/sleep.html">sleep</a><span class="sc">;</span></li><li> <span class="s">}</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/die.html">die</a> <span class="i">$@</span> unless <span class="i">$@</span> eq <span class="q">"Alarm!\n"</span><span class="sc">;</span></li></ol></pre><p>You probably cannot mix <code class="inline"><a class="l_k" href="../functions/alarm.html">alarm</a></code> and <code class="inline"><a class="l_k" href="../functions/sleep.html">sleep</a></code> calls, because <code class="inline"><a class="l_k" href="../functions/sleep.html">sleep</a></code>
is often implemented using <code class="inline"><a class="l_k" href="../functions/alarm.html">alarm</a></code>.</p>
<p>On some older systems, it may sleep up to a full second less than what<br>
you requested, depending on how it counts seconds. Most modern systems<br>
always sleep the full amount. They may appear to sleep longer than that,<br>
however, because your process might not be scheduled right away in a<br>
busy multitasking system.</p>
<p>For delays of finer granularity than one second, the Time::HiRes module<br>
(from CPAN, and starting from Perl 5.8 part of the standard<br>
distribution) provides usleep(). You may also use Perl's four-argument<br>
version of select() leaving the first three arguments undefined, or you<br>
might be able to use the <code class="inline"><a class="l_k" href="../functions/syscall.html">syscall</a></code> interface to access setitimer(2) if<br>
your system supports it. See <a href="../perlfaq8.html">perlfaq8</a> for details.</p>
<p>See also the POSIX module's <code class="inline"><span class="w">pause</span></code>
function.]]></desc>
</keyword>
<keyword name="socket" type="function">
<params>
<param name='socket'/>
<param name='domain'/>
<param name='type'/>
<param name='protocol'/>
</params>
<desc><![CDATA[Opens a socket of the specified kind and attaches it to filehandle<br>
SOCKET. DOMAIN, TYPE, and PROTOCOL are specified the same as for<br>
the system call of the same name. You should <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span></code>
first<br>
to get the proper definitions imported. See the examples in<br>
<a href="../perlipc.html#Sockets%3a-Client%2fServer-Communication">"Sockets: Client/Server Communication" in perlipc</a>.</p>
<p>On systems that support a close-on-exec flag on files, the flag will<br>
be set for the newly opened file descriptor, as determined by the<br>
value of $^F. See <a href="../perlvar.html#%24%5eF">"$^F" in perlvar</a>.]]></desc>
</keyword>
<keyword name="socketpair" type="function">
<params>
<param name='socket1'/>
<param name='socket2'/>
<param name='domain'/>
<param name='type'/>
<param name='protocol'/>
</params>
<desc><![CDATA[Creates an unnamed pair of sockets in the specified domain, of the<br>
specified type. DOMAIN, TYPE, and PROTOCOL are specified the same as<br>
for the system call of the same name. If unimplemented, yields a fatal<br>
error. Returns true if successful.</p>
<p>On systems that support a close-on-exec flag on files, the flag will<br>
be set for the newly opened file descriptors, as determined by the value<br>
of $^F. See <a href="../perlvar.html#%24%5eF">"$^F" in perlvar</a>.</p>
<p>Some systems defined <code class="inline"><a class="l_k" href="../functions/pipe.html">pipe</a></code> in terms of <code class="inline"><a class="l_k" href="../functions/socketpair.html">socketpair</a></code>, in which a call<br>
to <code class="inline"><a class="l_k" href="../functions/pipe.html">pipe</a><span class="s">(</span><span class="w">Rdr</span><span class="cm">,</span> <span class="w">Wtr</span><span class="s">)</span></code>
is essentially:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Socket</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/socketpair.html">socketpair</a><span class="s">(</span><span class="w">Rdr</span><span class="cm">,</span> <span class="w">Wtr</span><span class="cm">,</span> <span class="w">AF_UNIX</span><span class="cm">,</span> <span class="w">SOCK_STREAM</span><span class="cm">,</span> <span class="w">PF_UNSPEC</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/shutdown.html">shutdown</a><span class="s">(</span><span class="w">Rdr</span><span class="cm">,</span> <span class="n">1</span><span class="s">)</span><span class="sc">;</span> <span class="c"># no more writing for reader</span></li><li> <a class="l_k" href="../functions/shutdown.html">shutdown</a><span class="s">(</span><span class="w">Wtr</span><span class="cm">,</span> <span class="n">0</span><span class="s">)</span><span class="sc">;</span> <span class="c"># no more reading for writer</span></li></ol></pre><p>See <a href="../perlipc.html">perlipc</a> for an example of socketpair use. Perl 5.8 and later will<br>
emulate socketpair using IP sockets to localhost if your system implements<br>
sockets but not socketpair.]]></desc>
</keyword>
<keyword name="sort" type="function">
<params>
<param name='block list'/>
</params>
<desc><![CDATA[In list context, this sorts the LIST and returns the sorted list value.<br>
In scalar context, the behaviour of <code class="inline"><a class="l_k" href="../functions/sort.html">sort()</a></code> is undefined.</p>
<p>If SUBNAME or BLOCK is omitted, <code class="inline"><a class="l_k" href="../functions/sort.html">sort</a></code>s in standard string comparison<br>
order. If SUBNAME is specified, it gives the name of a subroutine<br>
that returns an integer less than, equal to, or greater than <code class="inline"><span class="n">0</span></code>
,<br>
depending on how the elements of the list are to be ordered. (The <code class="inline"><=></code>
and <code class="inline">cmp</code>
operators are extremely useful in such routines.)<br>
SUBNAME may be a scalar variable name (unsubscripted), in which case<br>
the value provides the name of (or a reference to) the actual<br>
subroutine to use. In place of a SUBNAME, you can provide a BLOCK as<br>
an anonymous, in-line sort subroutine.</p>
<p>If the subroutine's prototype is <code class="inline"><span class="s">(</span><span class="i">$$</span><span class="s">)</span></code>
, the elements to be compared<br>
are passed by reference in <code class="inline"><span class="i">@_</span></code>
, as for a normal subroutine. This is<br>
slower than unprototyped subroutines, where the elements to be<br>
compared are passed into the subroutine<br>
as the package global variables $a and $b (see example below). Note that<br>
in the latter case, it is usually counter-productive to declare $a and<br>
$b as lexicals.</p>
<p>The values to be compared are always passed by reference and should not<br>
be modified.</p>
<p>You also cannot exit out of the sort block or subroutine using any of the<br>
loop control operators described in <a href="../perlsyn.html">perlsyn</a> or with <code class="inline"><a class="l_k" href="../functions/goto.html">goto</a></code>.</p>
<p>When <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">locale</span></code>
is in effect, <code class="inline"><a class="l_k" href="../functions/sort.html">sort</a> <span class="i">LIST</span></code>
sorts LIST according to the<br>
current collation locale. See <a href="../perllocale.html">perllocale</a>.</p>
<p>sort() returns aliases into the original list, much as a for loop's index<br>
variable aliases the list elements. That is, modifying an element of a<br>
list returned by sort() (for example, in a <code class="inline">foreach</code>
, <code class="inline"><a class="l_k" href="../functions/map.html">map</a></code> or <code class="inline"><a class="l_k" href="../functions/grep.html">grep</a></code>)<br>
actually modifies the element in the original list. This is usually<br>
something to be avoided when writing clear code.</p>
<p>Perl 5.6 and earlier used a quicksort algorithm to implement sort.<br>
That algorithm was not stable, and <i>could</i> go quadratic. (A <i>stable</i> sort<br>
preserves the input order of elements that compare equal. Although<br>
quicksort's run time is O(NlogN) when averaged over all arrays of<br>
length N, the time can be O(N**2), <i>quadratic</i> behavior, for some<br>
inputs.) In 5.7, the quicksort implementation was replaced with<br>
a stable mergesort algorithm whose worst-case behavior is O(NlogN).<br>
But benchmarks indicated that for some inputs, on some platforms,<br>
the original quicksort was faster. 5.8 has a sort pragma for<br>
limited control of the sort. Its rather blunt control of the<br>
underlying algorithm may not persist into future Perls, but the<br>
ability to characterize the input or output in implementation<br>
independent ways quite probably will. See <a href="../sort.html">the sort pragma</a>.</p>
<p>Examples:</p>
<pre class="verbatim"><ol><li> <span class="c"># sort lexically</span></li><li> <span class="i">@articles</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="i">@files</span><span class="sc">;</span></li><li></li><li> <span class="c"># same thing, but with explicit sort routine</span></li><li> <span class="i">@articles</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span><span class="i">$a</span> cmp <span class="i">$b</span><span class="s">}</span> <span class="i">@files</span><span class="sc">;</span></li><li></li><li> <span class="c"># now case-insensitively</span></li><li> <span class="i">@articles</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span><a class="l_k" href="../functions/uc.html">uc</a><span class="s">(</span><span class="i">$a</span><span class="s">)</span> cmp <a class="l_k" href="../functions/uc.html">uc</a><span class="s">(</span><span class="i">$b</span><span class="s">)</span><span class="s">}</span> <span class="i">@files</span><span class="sc">;</span></li><li></li><li> <span class="c"># same thing in reversed order</span></li><li> <span class="i">@articles</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span><span class="i">$b</span> cmp <span class="i">$a</span><span class="s">}</span> <span class="i">@files</span><span class="sc">;</span></li><li></li><li> <span class="c"># sort numerically ascending</span></li><li> <span class="i">@articles</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span><span class="i">$a</span> <=> <span class="i">$b</span><span class="s">}</span> <span class="i">@files</span><span class="sc">;</span></li><li></li><li> <span class="c"># sort numerically descending</span></li><li> <span class="i">@articles</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span><span class="i">$b</span> <=> <span class="i">$a</span><span class="s">}</span> <span class="i">@files</span><span class="sc">;</span></li><li></li><li> <span class="c"># this sorts the %age hash by value instead of key</span></li><li> <span class="c"># using an in-line function</span></li><li> <span class="i">@eldest</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span> <span class="i">$age</span>{<span class="i">$b</span>} <=> <span class="i">$age</span>{<span class="i">$a</span>} <span class="s">}</span> <a class="l_k" href="../functions/keys.html">keys</a> <span class="i">%age</span><span class="sc">;</span></li><li></li><li> <span class="c"># sort using explicit subroutine name</span></li><li><a name="byage"></a> sub <span class="m">byage</span> <span class="s">{</span></li><li> <span class="i">$age</span>{<span class="i">$a</span>} <=> <span class="i">$age</span>{<span class="i">$b</span>}<span class="sc">;</span> <span class="c"># presuming numeric</span></li><li> <span class="s">}</span></li><li> <span class="i">@sortedclass</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="i">byage</span> <span class="i">@class</span><span class="sc">;</span></li><li></li><li><a name="backwards"></a> sub <span class="m">backwards</span> <span class="s">{</span> <span class="i">$b</span> cmp <span class="i">$a</span> <span class="s">}</span></li><li> <span class="i">@harry</span> = <span class="q">qw(dog cat x Cain Abel)</span><span class="sc">;</span></li><li> <span class="i">@george</span> = <span class="q">qw(gone chased yz Punished Axed)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/sort.html">sort</a> <span class="i">@harry</span><span class="sc">;</span></li><li> <span class="c"># prints AbelCaincatdogx</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/sort.html">sort</a> <span class="i">backwards</span> <span class="i">@harry</span><span class="sc">;</span></li><li> <span class="c"># prints xdogcatCainAbel</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/sort.html">sort</a> <span class="i">@george</span><span class="cm">,</span> <span class="q">'to'</span><span class="cm">,</span> <span class="i">@harry</span><span class="sc">;</span></li><li> <span class="c"># prints AbelAxedCainPunishedcatchaseddoggonetoxyz</span></li><li></li><li> <span class="c"># inefficiently sort by descending numeric compare using</span></li><li> <span class="c"># the first integer after the first = sign, or the</span></li><li> <span class="c"># whole record case-insensitively otherwise</span></li><li></li><li> <span class="i">@new</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span></li><li> <span class="s">(</span><span class="i">$b</span> =~ <span class="q">/=(\d+)/</span><span class="s">)</span>[<span class="n">0</span>] <=> <span class="s">(</span><span class="i">$a</span> =~ <span class="q">/=(\d+)/</span><span class="s">)</span>[<span class="n">0</span>]</li><li> ||</li><li> <a class="l_k" href="../functions/uc.html">uc</a><span class="s">(</span><span class="i">$a</span><span class="s">)</span> cmp <a class="l_k" href="../functions/uc.html">uc</a><span class="s">(</span><span class="i">$b</span><span class="s">)</span></li><li> <span class="s">}</span> <span class="i">@old</span><span class="sc">;</span></li><li></li><li> <span class="c"># same thing, but much more efficiently;</span></li><li> <span class="c"># we'll build auxiliary indices instead</span></li><li> <span class="c"># for speed</span></li><li> <span class="i">@nums</span> = <span class="i">@caps</span> = <span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> for <span class="s">(</span><span class="i">@old</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/push.html">push</a> <span class="i">@nums</span><span class="cm">,</span> <span class="q">/=(\d+)/</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/push.html">push</a> <span class="i">@caps</span><span class="cm">,</span> <a class="l_k" href="../functions/uc.html">uc</a><span class="s">(</span><span class="i">$_</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li></li><li> <span class="i">@new</span> = <span class="i">@old</span>[ <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span></li><li> <span class="i">$nums</span>[<span class="i">$b</span>] <=> <span class="i">$nums</span>[<span class="i">$a</span>]</li><li> ||</li><li> <span class="i">$caps</span>[<span class="i">$a</span>] cmp <span class="i">$caps</span>[<span class="i">$b</span>]</li><li> <span class="s">}</span> <span class="n">0</span>..<span class="i">$#old</span></li><li> ]<span class="sc">;</span></li><li></li><li> <span class="c"># same thing, but without any temps</span></li><li> <span class="i">@new</span> = <a class="l_k" href="../functions/map.html">map</a> <span class="s">{</span> <span class="i">$_</span>->[<span class="n">0</span>] <span class="s">}</span></li><li> <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span> <span class="i">$b</span>->[<span class="n">1</span>] <=> <span class="i">$a</span>->[<span class="n">1</span>]</li><li> ||</li><li> <span class="i">$a</span>->[<span class="n">2</span>] cmp <span class="i">$b</span>->[<span class="n">2</span>]</li><li> <span class="s">}</span> <a class="l_k" href="../functions/map.html">map</a> <span class="s">{</span> <span class="s">[</span><span class="i">$_</span><span class="cm">,</span> <span class="q">/=(\d+)/</span><span class="cm">,</span> <a class="l_k" href="../functions/uc.html">uc</a><span class="s">(</span><span class="i">$_</span><span class="s">)</span><span class="s">]</span> <span class="s">}</span> <span class="i">@old</span><span class="sc">;</span></li><li></li><li> <span class="c"># using a prototype allows you to use any comparison subroutine</span></li><li> <span class="c"># as a sort subroutine (including other package's subroutines)</span></li><li><a name="package-other"></a> package <span class="i">other</span><span class="sc">;</span></li><li><a name="backwards-1"></a> sub <span class="m">backwards ($$)</span> <span class="s">{</span> <span class="i">$_</span>[<span class="n">1</span>] cmp <span class="i">$_</span>[<span class="n">0</span>]<span class="sc">;</span> <span class="s">}</span> <span class="c"># $a and $b are not set here</span></li><li></li><li><a name="package-main"></a> package <span class="i">main</span><span class="sc">;</span></li><li> <span class="i">@new</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="i">other::backwards</span> <span class="i">@old</span><span class="sc">;</span></li><li></li><li> <span class="c"># guarantee stability, regardless of algorithm</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <a class="l_k" href="../functions/sort.html">sort</a> <span class="q">'stable'</span><span class="sc">;</span></li><li> <span class="i">@new</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span> <a class="l_k" href="../functions/substr.html">substr</a><span class="s">(</span><span class="i">$a</span><span class="cm">,</span> <span class="n">3</span><span class="cm">,</span> <span class="n">5</span><span class="s">)</span> cmp <a class="l_k" href="../functions/substr.html">substr</a><span class="s">(</span><span class="i">$b</span><span class="cm">,</span> <span class="n">3</span><span class="cm">,</span> <span class="n">5</span><span class="s">)</span> <span class="s">}</span> <span class="i">@old</span><span class="sc">;</span></li><li></li><li> <span class="c"># force use of mergesort (not portable outside Perl 5.8)</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <a class="l_k" href="../functions/sort.html">sort</a> <span class="q">'_mergesort'</span><span class="sc">;</span> <span class="c"># note discouraging _</span></li><li> <span class="i">@new</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span> <a class="l_k" href="../functions/substr.html">substr</a><span class="s">(</span><span class="i">$a</span><span class="cm">,</span> <span class="n">3</span><span class="cm">,</span> <span class="n">5</span><span class="s">)</span> cmp <a class="l_k" href="../functions/substr.html">substr</a><span class="s">(</span><span class="i">$b</span><span class="cm">,</span> <span class="n">3</span><span class="cm">,</span> <span class="n">5</span><span class="s">)</span> <span class="s">}</span> <span class="i">@old</span><span class="sc">;</span></li></ol></pre><p>Warning: syntactical care is required when sorting the list returned from<br>
a function. If you want to sort the list returned by the function call<br>
<code class="inline"><span class="i">find_records</span><span class="s">(</span><span class="i">@key</span><span class="s">)</span></code>
, you can use:</p>
<pre class="verbatim"><ol><li> <span class="i">@contact</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span> <span class="i">$a</span> cmp <span class="i">$b</span> <span class="s">}</span> <span class="w">find_records</span> <span class="i">@key</span><span class="sc">;</span></li><li> <span class="i">@contact</span> = <a class="l_k" href="../functions/sort.html">sort</a> +<span class="i">find_records</span><span class="s">(</span><span class="i">@key</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">@contact</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="i">&find_records</span><span class="s">(</span><span class="i">@key</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">@contact</span> = <a class="l_k" href="../functions/sort.html">sort</a><span class="s">(</span><span class="i">find_records</span><span class="s">(</span><span class="i">@key</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>If instead you want to sort the array @key with the comparison routine<br>
<code class="inline"><span class="i">find_records</span><span class="s">(</span><span class="s">)</span></code>
then you can use:</p>
<pre class="verbatim"><ol><li> <span class="i">@contact</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span> <span class="i">find_records</span><span class="s">(</span><span class="s">)</span> <span class="s">}</span> <span class="i">@key</span><span class="sc">;</span></li><li> <span class="i">@contact</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="i">find_records</span><span class="s">(</span><span class="i">@key</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">@contact</span> = <a class="l_k" href="../functions/sort.html">sort</a><span class="s">(</span><span class="i">find_records</span> <span class="i">@key</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">@contact</span> = <a class="l_k" href="../functions/sort.html">sort</a><span class="s">(</span><span class="i">find_records</span> <span class="s">(</span><span class="i">@key</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>If you're using strict, you <i>must not</i> declare $a<br>
and $b as lexicals. They are package globals. That means<br>
that if you're in the <code class="inline"><span class="w">main</span></code>
package and type</p>
<pre class="verbatim"><ol><li> <span class="i">@articles</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span><span class="i">$b</span> <=> <span class="i">$a</span><span class="s">}</span> <span class="i">@files</span><span class="sc">;</span></li></ol></pre><p>then <code class="inline"><span class="i">$a</span></code>
and <code class="inline"><span class="i">$b</span></code>
are <code class="inline"><span class="i">$main::a</span></code>
and <code class="inline"><span class="i">$main::b</span></code>
(or <code class="inline"><span class="i">$::a</span></code>
and <code class="inline"><span class="i">$::b</span></code>
),<br>
but if you're in the <code class="inline"><span class="w">FooPack</span></code>
package, it's the same as typing</p>
<pre class="verbatim"><ol><li> <span class="i">@articles</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span><span class="i">$FooPack::b</span> <=> <span class="i">$FooPack::a</span><span class="s">}</span> <span class="i">@files</span><span class="sc">;</span></li></ol></pre><p>The comparison function is required to behave. If it returns<br>
inconsistent results (sometimes saying <code class="inline"><span class="i">$x</span>[<span class="n">1</span>]</code>
is less than <code class="inline"><span class="i">$x</span>[<span class="n">2</span>]</code>
and<br>
sometimes saying the opposite, for example) the results are not<br>
well-defined.</p>
<p>Because <code class="inline"><=></code>
returns <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> when either operand is <code class="inline"><span class="w">NaN</span></code>
<br>
(not-a-number), and because <code class="inline"><a class="l_k" href="../functions/sort.html">sort</a></code> will trigger a fatal error unless the<br>
result of a comparison is defined, when sorting with a comparison function<br>
like <code class="inline"><span class="i">$a</span> <=> <span class="i">$b</span></code>
, be careful about lists that might contain a <code class="inline"><span class="w">NaN</span></code>
.<br>
The following example takes advantage of the fact that <code class="inline"><span class="w">NaN</span> != <span class="w">NaN</span></code>
to<br>
eliminate any <code class="inline"><span class="w">NaN</span></code>
s from the input.</p>
<pre class="verbatim"><ol><li> <span class="i">@result</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span> <span class="i">$a</span> <=> <span class="i">$b</span> <span class="s">}</span> <a class="l_k" href="../functions/grep.html">grep</a> <span class="s">{</span> <span class="i">$_</span> == <span class="i">$_</span> <span class="s">}</span> <span class="i">@input</span><span class="sc">;</span></li></ol><]]></desc>
</keyword>
<keyword name="sort" type="function">
<params>
<param name='list'/>
</params>
<desc><![CDATA[In list context, this sorts the LIST and returns the sorted list value.<br>
In scalar context, the behaviour of <code class="inline"><a class="l_k" href="../functions/sort.html">sort()</a></code> is undefined.</p>
<p>If SUBNAME or BLOCK is omitted, <code class="inline"><a class="l_k" href="../functions/sort.html">sort</a></code>s in standard string comparison<br>
order. If SUBNAME is specified, it gives the name of a subroutine<br>
that returns an integer less than, equal to, or greater than <code class="inline"><span class="n">0</span></code>
,<br>
depending on how the elements of the list are to be ordered. (The <code class="inline"><=></code>
and <code class="inline">cmp</code>
operators are extremely useful in such routines.)<br>
SUBNAME may be a scalar variable name (unsubscripted), in which case<br>
the value provides the name of (or a reference to) the actual<br>
subroutine to use. In place of a SUBNAME, you can provide a BLOCK as<br>
an anonymous, in-line sort subroutine.</p>
<p>If the subroutine's prototype is <code class="inline"><span class="s">(</span><span class="i">$$</span><span class="s">)</span></code>
, the elements to be compared<br>
are passed by reference in <code class="inline"><span class="i">@_</span></code>
, as for a normal subroutine. This is<br>
slower than unprototyped subroutines, where the elements to be<br>
compared are passed into the subroutine<br>
as the package global variables $a and $b (see example below). Note that<br>
in the latter case, it is usually counter-productive to declare $a and<br>
$b as lexicals.</p>
<p>The values to be compared are always passed by reference and should not<br>
be modified.</p>
<p>You also cannot exit out of the sort block or subroutine using any of the<br>
loop control operators described in <a href="../perlsyn.html">perlsyn</a> or with <code class="inline"><a class="l_k" href="../functions/goto.html">goto</a></code>.</p>
<p>When <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">locale</span></code>
is in effect, <code class="inline"><a class="l_k" href="../functions/sort.html">sort</a> <span class="i">LIST</span></code>
sorts LIST according to the<br>
current collation locale. See <a href="../perllocale.html">perllocale</a>.</p>
<p>sort() returns aliases into the original list, much as a for loop's index<br>
variable aliases the list elements. That is, modifying an element of a<br>
list returned by sort() (for example, in a <code class="inline">foreach</code>
, <code class="inline"><a class="l_k" href="../functions/map.html">map</a></code> or <code class="inline"><a class="l_k" href="../functions/grep.html">grep</a></code>)<br>
actually modifies the element in the original list. This is usually<br>
something to be avoided when writing clear code.</p>
<p>Perl 5.6 and earlier used a quicksort algorithm to implement sort.<br>
That algorithm was not stable, and <i>could</i> go quadratic. (A <i>stable</i> sort<br>
preserves the input order of elements that compare equal. Although<br>
quicksort's run time is O(NlogN) when averaged over all arrays of<br>
length N, the time can be O(N**2), <i>quadratic</i> behavior, for some<br>
inputs.) In 5.7, the quicksort implementation was replaced with<br>
a stable mergesort algorithm whose worst-case behavior is O(NlogN).<br>
But benchmarks indicated that for some inputs, on some platforms,<br>
the original quicksort was faster. 5.8 has a sort pragma for<br>
limited control of the sort. Its rather blunt control of the<br>
underlying algorithm may not persist into future Perls, but the<br>
ability to characterize the input or output in implementation<br>
independent ways quite probably will. See <a href="../sort.html">the sort pragma</a>.</p>
<p>Examples:</p>
<pre class="verbatim"><ol><li> <span class="c"># sort lexically</span></li><li> <span class="i">@articles</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="i">@files</span><span class="sc">;</span></li><li></li><li> <span class="c"># same thing, but with explicit sort routine</span></li><li> <span class="i">@articles</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span><span class="i">$a</span> cmp <span class="i">$b</span><span class="s">}</span> <span class="i">@files</span><span class="sc">;</span></li><li></li><li> <span class="c"># now case-insensitively</span></li><li> <span class="i">@articles</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span><a class="l_k" href="../functions/uc.html">uc</a><span class="s">(</span><span class="i">$a</span><span class="s">)</span> cmp <a class="l_k" href="../functions/uc.html">uc</a><span class="s">(</span><span class="i">$b</span><span class="s">)</span><span class="s">}</span> <span class="i">@files</span><span class="sc">;</span></li><li></li><li> <span class="c"># same thing in reversed order</span></li><li> <span class="i">@articles</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span><span class="i">$b</span> cmp <span class="i">$a</span><span class="s">}</span> <span class="i">@files</span><span class="sc">;</span></li><li></li><li> <span class="c"># sort numerically ascending</span></li><li> <span class="i">@articles</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span><span class="i">$a</span> <=> <span class="i">$b</span><span class="s">}</span> <span class="i">@files</span><span class="sc">;</span></li><li></li><li> <span class="c"># sort numerically descending</span></li><li> <span class="i">@articles</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span><span class="i">$b</span> <=> <span class="i">$a</span><span class="s">}</span> <span class="i">@files</span><span class="sc">;</span></li><li></li><li> <span class="c"># this sorts the %age hash by value instead of key</span></li><li> <span class="c"># using an in-line function</span></li><li> <span class="i">@eldest</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span> <span class="i">$age</span>{<span class="i">$b</span>} <=> <span class="i">$age</span>{<span class="i">$a</span>} <span class="s">}</span> <a class="l_k" href="../functions/keys.html">keys</a> <span class="i">%age</span><span class="sc">;</span></li><li></li><li> <span class="c"># sort using explicit subroutine name</span></li><li><a name="byage"></a> sub <span class="m">byage</span> <span class="s">{</span></li><li> <span class="i">$age</span>{<span class="i">$a</span>} <=> <span class="i">$age</span>{<span class="i">$b</span>}<span class="sc">;</span> <span class="c"># presuming numeric</span></li><li> <span class="s">}</span></li><li> <span class="i">@sortedclass</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="i">byage</span> <span class="i">@class</span><span class="sc">;</span></li><li></li><li><a name="backwards"></a> sub <span class="m">backwards</span> <span class="s">{</span> <span class="i">$b</span> cmp <span class="i">$a</span> <span class="s">}</span></li><li> <span class="i">@harry</span> = <span class="q">qw(dog cat x Cain Abel)</span><span class="sc">;</span></li><li> <span class="i">@george</span> = <span class="q">qw(gone chased yz Punished Axed)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/sort.html">sort</a> <span class="i">@harry</span><span class="sc">;</span></li><li> <span class="c"># prints AbelCaincatdogx</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/sort.html">sort</a> <span class="i">backwards</span> <span class="i">@harry</span><span class="sc">;</span></li><li> <span class="c"># prints xdogcatCainAbel</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/sort.html">sort</a> <span class="i">@george</span><span class="cm">,</span> <span class="q">'to'</span><span class="cm">,</span> <span class="i">@harry</span><span class="sc">;</span></li><li> <span class="c"># prints AbelAxedCainPunishedcatchaseddoggonetoxyz</span></li><li></li><li> <span class="c"># inefficiently sort by descending numeric compare using</span></li><li> <span class="c"># the first integer after the first = sign, or the</span></li><li> <span class="c"># whole record case-insensitively otherwise</span></li><li></li><li> <span class="i">@new</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span></li><li> <span class="s">(</span><span class="i">$b</span> =~ <span class="q">/=(\d+)/</span><span class="s">)</span>[<span class="n">0</span>] <=> <span class="s">(</span><span class="i">$a</span> =~ <span class="q">/=(\d+)/</span><span class="s">)</span>[<span class="n">0</span>]</li><li> ||</li><li> <a class="l_k" href="../functions/uc.html">uc</a><span class="s">(</span><span class="i">$a</span><span class="s">)</span> cmp <a class="l_k" href="../functions/uc.html">uc</a><span class="s">(</span><span class="i">$b</span><span class="s">)</span></li><li> <span class="s">}</span> <span class="i">@old</span><span class="sc">;</span></li><li></li><li> <span class="c"># same thing, but much more efficiently;</span></li><li> <span class="c"># we'll build auxiliary indices instead</span></li><li> <span class="c"># for speed</span></li><li> <span class="i">@nums</span> = <span class="i">@caps</span> = <span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> for <span class="s">(</span><span class="i">@old</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/push.html">push</a> <span class="i">@nums</span><span class="cm">,</span> <span class="q">/=(\d+)/</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/push.html">push</a> <span class="i">@caps</span><span class="cm">,</span> <a class="l_k" href="../functions/uc.html">uc</a><span class="s">(</span><span class="i">$_</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li></li><li> <span class="i">@new</span> = <span class="i">@old</span>[ <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span></li><li> <span class="i">$nums</span>[<span class="i">$b</span>] <=> <span class="i">$nums</span>[<span class="i">$a</span>]</li><li> ||</li><li> <span class="i">$caps</span>[<span class="i">$a</span>] cmp <span class="i">$caps</span>[<span class="i">$b</span>]</li><li> <span class="s">}</span> <span class="n">0</span>..<span class="i">$#old</span></li><li> ]<span class="sc">;</span></li><li></li><li> <span class="c"># same thing, but without any temps</span></li><li> <span class="i">@new</span> = <a class="l_k" href="../functions/map.html">map</a> <span class="s">{</span> <span class="i">$_</span>->[<span class="n">0</span>] <span class="s">}</span></li><li> <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span> <span class="i">$b</span>->[<span class="n">1</span>] <=> <span class="i">$a</span>->[<span class="n">1</span>]</li><li> ||</li><li> <span class="i">$a</span>->[<span class="n">2</span>] cmp <span class="i">$b</span>->[<span class="n">2</span>]</li><li> <span class="s">}</span> <a class="l_k" href="../functions/map.html">map</a> <span class="s">{</span> <span class="s">[</span><span class="i">$_</span><span class="cm">,</span> <span class="q">/=(\d+)/</span><span class="cm">,</span> <a class="l_k" href="../functions/uc.html">uc</a><span class="s">(</span><span class="i">$_</span><span class="s">)</span><span class="s">]</span> <span class="s">}</span> <span class="i">@old</span><span class="sc">;</span></li><li></li><li> <span class="c"># using a prototype allows you to use any comparison subroutine</span></li><li> <span class="c"># as a sort subroutine (including other package's subroutines)</span></li><li><a name="package-other"></a> package <span class="i">other</span><span class="sc">;</span></li><li><a name="backwards-1"></a> sub <span class="m">backwards ($$)</span> <span class="s">{</span> <span class="i">$_</span>[<span class="n">1</span>] cmp <span class="i">$_</span>[<span class="n">0</span>]<span class="sc">;</span> <span class="s">}</span> <span class="c"># $a and $b are not set here</span></li><li></li><li><a name="package-main"></a> package <span class="i">main</span><span class="sc">;</span></li><li> <span class="i">@new</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="i">other::backwards</span> <span class="i">@old</span><span class="sc">;</span></li><li></li><li> <span class="c"># guarantee stability, regardless of algorithm</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <a class="l_k" href="../functions/sort.html">sort</a> <span class="q">'stable'</span><span class="sc">;</span></li><li> <span class="i">@new</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span> <a class="l_k" href="../functions/substr.html">substr</a><span class="s">(</span><span class="i">$a</span><span class="cm">,</span> <span class="n">3</span><span class="cm">,</span> <span class="n">5</span><span class="s">)</span> cmp <a class="l_k" href="../functions/substr.html">substr</a><span class="s">(</span><span class="i">$b</span><span class="cm">,</span> <span class="n">3</span><span class="cm">,</span> <span class="n">5</span><span class="s">)</span> <span class="s">}</span> <span class="i">@old</span><span class="sc">;</span></li><li></li><li> <span class="c"># force use of mergesort (not portable outside Perl 5.8)</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <a class="l_k" href="../functions/sort.html">sort</a> <span class="q">'_mergesort'</span><span class="sc">;</span> <span class="c"># note discouraging _</span></li><li> <span class="i">@new</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span> <a class="l_k" href="../functions/substr.html">substr</a><span class="s">(</span><span class="i">$a</span><span class="cm">,</span> <span class="n">3</span><span class="cm">,</span> <span class="n">5</span><span class="s">)</span> cmp <a class="l_k" href="../functions/substr.html">substr</a><span class="s">(</span><span class="i">$b</span><span class="cm">,</span> <span class="n">3</span><span class="cm">,</span> <span class="n">5</span><span class="s">)</span> <span class="s">}</span> <span class="i">@old</span><span class="sc">;</span></li></ol></pre><p>Warning: syntactical care is required when sorting the list returned from<br>
a function. If you want to sort the list returned by the function call<br>
<code class="inline"><span class="i">find_records</span><span class="s">(</span><span class="i">@key</span><span class="s">)</span></code>
, you can use:</p>
<pre class="verbatim"><ol><li> <span class="i">@contact</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span> <span class="i">$a</span> cmp <span class="i">$b</span> <span class="s">}</span> <span class="w">find_records</span> <span class="i">@key</span><span class="sc">;</span></li><li> <span class="i">@contact</span> = <a class="l_k" href="../functions/sort.html">sort</a> +<span class="i">find_records</span><span class="s">(</span><span class="i">@key</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">@contact</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="i">&find_records</span><span class="s">(</span><span class="i">@key</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">@contact</span> = <a class="l_k" href="../functions/sort.html">sort</a><span class="s">(</span><span class="i">find_records</span><span class="s">(</span><span class="i">@key</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>If instead you want to sort the array @key with the comparison routine<br>
<code class="inline"><span class="i">find_records</span><span class="s">(</span><span class="s">)</span></code>
then you can use:</p>
<pre class="verbatim"><ol><li> <span class="i">@contact</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span> <span class="i">find_records</span><span class="s">(</span><span class="s">)</span> <span class="s">}</span> <span class="i">@key</span><span class="sc">;</span></li><li> <span class="i">@contact</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="i">find_records</span><span class="s">(</span><span class="i">@key</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">@contact</span> = <a class="l_k" href="../functions/sort.html">sort</a><span class="s">(</span><span class="i">find_records</span> <span class="i">@key</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">@contact</span> = <a class="l_k" href="../functions/sort.html">sort</a><span class="s">(</span><span class="i">find_records</span> <span class="s">(</span><span class="i">@key</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>If you're using strict, you <i>must not</i> declare $a<br>
and $b as lexicals. They are package globals. That means<br>
that if you're in the <code class="inline"><span class="w">main</span></code>
package and type</p>
<pre class="verbatim"><ol><li> <span class="i">@articles</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span><span class="i">$b</span> <=> <span class="i">$a</span><span class="s">}</span> <span class="i">@files</span><span class="sc">;</span></li></ol></pre><p>then <code class="inline"><span class="i">$a</span></code>
and <code class="inline"><span class="i">$b</span></code>
are <code class="inline"><span class="i">$main::a</span></code>
and <code class="inline"><span class="i">$main::b</span></code>
(or <code class="inline"><span class="i">$::a</span></code>
and <code class="inline"><span class="i">$::b</span></code>
),<br>
but if you're in the <code class="inline"><span class="w">FooPack</span></code>
package, it's the same as typing</p>
<pre class="verbatim"><ol><li> <span class="i">@articles</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span><span class="i">$FooPack::b</span> <=> <span class="i">$FooPack::a</span><span class="s">}</span> <span class="i">@files</span><span class="sc">;</span></li></ol></pre><p>The comparison function is required to behave. If it returns<br>
inconsistent results (sometimes saying <code class="inline"><span class="i">$x</span>[<span class="n">1</span>]</code>
is less than <code class="inline"><span class="i">$x</span>[<span class="n">2</span>]</code>
and<br>
sometimes saying the opposite, for example) the results are not<br>
well-defined.</p>
<p>Because <code class="inline"><=></code>
returns <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> when either operand is <code class="inline"><span class="w">NaN</span></code>
<br>
(not-a-number), and because <code class="inline"><a class="l_k" href="../functions/sort.html">sort</a></code> will trigger a fatal error unless the<br>
result of a comparison is defined, when sorting with a comparison function<br>
like <code class="inline"><span class="i">$a</span> <=> <span class="i">$b</span></code>
, be careful about lists that might contain a <code class="inline"><span class="w">NaN</span></code>
.<br>
The following example takes advantage of the fact that <code class="inline"><span class="w">NaN</span> != <span class="w">NaN</span></code>
to<br>
eliminate any <code class="inline"><span class="w">NaN</span></code>
s from the input.</p>
<pre class="verbatim"><ol><li> <span class="i">@result</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span> <span class="i">$a</span> <=> <span class="i">$b</span> <span class="s">}</span> <a class="l_k" href="../functions/grep.html">grep</a> <span class="s">{</span> <span class="i">$_</span> == <span class="i">$_</span> <span class="s">}</span> <span class="i">@input</span><span class="sc">;</span></li></ol><]]></desc>
</keyword>
<keyword name="sort" type="function">
<params>
<param name='subname list'/>
</params>
<desc><![CDATA[In list context, this sorts the LIST and returns the sorted list value.<br>
In scalar context, the behaviour of <code class="inline"><a class="l_k" href="../functions/sort.html">sort()</a></code> is undefined.</p>
<p>If SUBNAME or BLOCK is omitted, <code class="inline"><a class="l_k" href="../functions/sort.html">sort</a></code>s in standard string comparison<br>
order. If SUBNAME is specified, it gives the name of a subroutine<br>
that returns an integer less than, equal to, or greater than <code class="inline"><span class="n">0</span></code>
,<br>
depending on how the elements of the list are to be ordered. (The <code class="inline"><=></code>
and <code class="inline">cmp</code>
operators are extremely useful in such routines.)<br>
SUBNAME may be a scalar variable name (unsubscripted), in which case<br>
the value provides the name of (or a reference to) the actual<br>
subroutine to use. In place of a SUBNAME, you can provide a BLOCK as<br>
an anonymous, in-line sort subroutine.</p>
<p>If the subroutine's prototype is <code class="inline"><span class="s">(</span><span class="i">$$</span><span class="s">)</span></code>
, the elements to be compared<br>
are passed by reference in <code class="inline"><span class="i">@_</span></code>
, as for a normal subroutine. This is<br>
slower than unprototyped subroutines, where the elements to be<br>
compared are passed into the subroutine<br>
as the package global variables $a and $b (see example below). Note that<br>
in the latter case, it is usually counter-productive to declare $a and<br>
$b as lexicals.</p>
<p>The values to be compared are always passed by reference and should not<br>
be modified.</p>
<p>You also cannot exit out of the sort block or subroutine using any of the<br>
loop control operators described in <a href="../perlsyn.html">perlsyn</a> or with <code class="inline"><a class="l_k" href="../functions/goto.html">goto</a></code>.</p>
<p>When <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">locale</span></code>
is in effect, <code class="inline"><a class="l_k" href="../functions/sort.html">sort</a> <span class="i">LIST</span></code>
sorts LIST according to the<br>
current collation locale. See <a href="../perllocale.html">perllocale</a>.</p>
<p>sort() returns aliases into the original list, much as a for loop's index<br>
variable aliases the list elements. That is, modifying an element of a<br>
list returned by sort() (for example, in a <code class="inline">foreach</code>
, <code class="inline"><a class="l_k" href="../functions/map.html">map</a></code> or <code class="inline"><a class="l_k" href="../functions/grep.html">grep</a></code>)<br>
actually modifies the element in the original list. This is usually<br>
something to be avoided when writing clear code.</p>
<p>Perl 5.6 and earlier used a quicksort algorithm to implement sort.<br>
That algorithm was not stable, and <i>could</i> go quadratic. (A <i>stable</i> sort<br>
preserves the input order of elements that compare equal. Although<br>
quicksort's run time is O(NlogN) when averaged over all arrays of<br>
length N, the time can be O(N**2), <i>quadratic</i> behavior, for some<br>
inputs.) In 5.7, the quicksort implementation was replaced with<br>
a stable mergesort algorithm whose worst-case behavior is O(NlogN).<br>
But benchmarks indicated that for some inputs, on some platforms,<br>
the original quicksort was faster. 5.8 has a sort pragma for<br>
limited control of the sort. Its rather blunt control of the<br>
underlying algorithm may not persist into future Perls, but the<br>
ability to characterize the input or output in implementation<br>
independent ways quite probably will. See <a href="../sort.html">the sort pragma</a>.</p>
<p>Examples:</p>
<pre class="verbatim"><ol><li> <span class="c"># sort lexically</span></li><li> <span class="i">@articles</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="i">@files</span><span class="sc">;</span></li><li></li><li> <span class="c"># same thing, but with explicit sort routine</span></li><li> <span class="i">@articles</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span><span class="i">$a</span> cmp <span class="i">$b</span><span class="s">}</span> <span class="i">@files</span><span class="sc">;</span></li><li></li><li> <span class="c"># now case-insensitively</span></li><li> <span class="i">@articles</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span><a class="l_k" href="../functions/uc.html">uc</a><span class="s">(</span><span class="i">$a</span><span class="s">)</span> cmp <a class="l_k" href="../functions/uc.html">uc</a><span class="s">(</span><span class="i">$b</span><span class="s">)</span><span class="s">}</span> <span class="i">@files</span><span class="sc">;</span></li><li></li><li> <span class="c"># same thing in reversed order</span></li><li> <span class="i">@articles</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span><span class="i">$b</span> cmp <span class="i">$a</span><span class="s">}</span> <span class="i">@files</span><span class="sc">;</span></li><li></li><li> <span class="c"># sort numerically ascending</span></li><li> <span class="i">@articles</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span><span class="i">$a</span> <=> <span class="i">$b</span><span class="s">}</span> <span class="i">@files</span><span class="sc">;</span></li><li></li><li> <span class="c"># sort numerically descending</span></li><li> <span class="i">@articles</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span><span class="i">$b</span> <=> <span class="i">$a</span><span class="s">}</span> <span class="i">@files</span><span class="sc">;</span></li><li></li><li> <span class="c"># this sorts the %age hash by value instead of key</span></li><li> <span class="c"># using an in-line function</span></li><li> <span class="i">@eldest</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span> <span class="i">$age</span>{<span class="i">$b</span>} <=> <span class="i">$age</span>{<span class="i">$a</span>} <span class="s">}</span> <a class="l_k" href="../functions/keys.html">keys</a> <span class="i">%age</span><span class="sc">;</span></li><li></li><li> <span class="c"># sort using explicit subroutine name</span></li><li><a name="byage"></a> sub <span class="m">byage</span> <span class="s">{</span></li><li> <span class="i">$age</span>{<span class="i">$a</span>} <=> <span class="i">$age</span>{<span class="i">$b</span>}<span class="sc">;</span> <span class="c"># presuming numeric</span></li><li> <span class="s">}</span></li><li> <span class="i">@sortedclass</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="i">byage</span> <span class="i">@class</span><span class="sc">;</span></li><li></li><li><a name="backwards"></a> sub <span class="m">backwards</span> <span class="s">{</span> <span class="i">$b</span> cmp <span class="i">$a</span> <span class="s">}</span></li><li> <span class="i">@harry</span> = <span class="q">qw(dog cat x Cain Abel)</span><span class="sc">;</span></li><li> <span class="i">@george</span> = <span class="q">qw(gone chased yz Punished Axed)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/sort.html">sort</a> <span class="i">@harry</span><span class="sc">;</span></li><li> <span class="c"># prints AbelCaincatdogx</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/sort.html">sort</a> <span class="i">backwards</span> <span class="i">@harry</span><span class="sc">;</span></li><li> <span class="c"># prints xdogcatCainAbel</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/sort.html">sort</a> <span class="i">@george</span><span class="cm">,</span> <span class="q">'to'</span><span class="cm">,</span> <span class="i">@harry</span><span class="sc">;</span></li><li> <span class="c"># prints AbelAxedCainPunishedcatchaseddoggonetoxyz</span></li><li></li><li> <span class="c"># inefficiently sort by descending numeric compare using</span></li><li> <span class="c"># the first integer after the first = sign, or the</span></li><li> <span class="c"># whole record case-insensitively otherwise</span></li><li></li><li> <span class="i">@new</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span></li><li> <span class="s">(</span><span class="i">$b</span> =~ <span class="q">/=(\d+)/</span><span class="s">)</span>[<span class="n">0</span>] <=> <span class="s">(</span><span class="i">$a</span> =~ <span class="q">/=(\d+)/</span><span class="s">)</span>[<span class="n">0</span>]</li><li> ||</li><li> <a class="l_k" href="../functions/uc.html">uc</a><span class="s">(</span><span class="i">$a</span><span class="s">)</span> cmp <a class="l_k" href="../functions/uc.html">uc</a><span class="s">(</span><span class="i">$b</span><span class="s">)</span></li><li> <span class="s">}</span> <span class="i">@old</span><span class="sc">;</span></li><li></li><li> <span class="c"># same thing, but much more efficiently;</span></li><li> <span class="c"># we'll build auxiliary indices instead</span></li><li> <span class="c"># for speed</span></li><li> <span class="i">@nums</span> = <span class="i">@caps</span> = <span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> for <span class="s">(</span><span class="i">@old</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/push.html">push</a> <span class="i">@nums</span><span class="cm">,</span> <span class="q">/=(\d+)/</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/push.html">push</a> <span class="i">@caps</span><span class="cm">,</span> <a class="l_k" href="../functions/uc.html">uc</a><span class="s">(</span><span class="i">$_</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li></li><li> <span class="i">@new</span> = <span class="i">@old</span>[ <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span></li><li> <span class="i">$nums</span>[<span class="i">$b</span>] <=> <span class="i">$nums</span>[<span class="i">$a</span>]</li><li> ||</li><li> <span class="i">$caps</span>[<span class="i">$a</span>] cmp <span class="i">$caps</span>[<span class="i">$b</span>]</li><li> <span class="s">}</span> <span class="n">0</span>..<span class="i">$#old</span></li><li> ]<span class="sc">;</span></li><li></li><li> <span class="c"># same thing, but without any temps</span></li><li> <span class="i">@new</span> = <a class="l_k" href="../functions/map.html">map</a> <span class="s">{</span> <span class="i">$_</span>->[<span class="n">0</span>] <span class="s">}</span></li><li> <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span> <span class="i">$b</span>->[<span class="n">1</span>] <=> <span class="i">$a</span>->[<span class="n">1</span>]</li><li> ||</li><li> <span class="i">$a</span>->[<span class="n">2</span>] cmp <span class="i">$b</span>->[<span class="n">2</span>]</li><li> <span class="s">}</span> <a class="l_k" href="../functions/map.html">map</a> <span class="s">{</span> <span class="s">[</span><span class="i">$_</span><span class="cm">,</span> <span class="q">/=(\d+)/</span><span class="cm">,</span> <a class="l_k" href="../functions/uc.html">uc</a><span class="s">(</span><span class="i">$_</span><span class="s">)</span><span class="s">]</span> <span class="s">}</span> <span class="i">@old</span><span class="sc">;</span></li><li></li><li> <span class="c"># using a prototype allows you to use any comparison subroutine</span></li><li> <span class="c"># as a sort subroutine (including other package's subroutines)</span></li><li><a name="package-other"></a> package <span class="i">other</span><span class="sc">;</span></li><li><a name="backwards-1"></a> sub <span class="m">backwards ($$)</span> <span class="s">{</span> <span class="i">$_</span>[<span class="n">1</span>] cmp <span class="i">$_</span>[<span class="n">0</span>]<span class="sc">;</span> <span class="s">}</span> <span class="c"># $a and $b are not set here</span></li><li></li><li><a name="package-main"></a> package <span class="i">main</span><span class="sc">;</span></li><li> <span class="i">@new</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="i">other::backwards</span> <span class="i">@old</span><span class="sc">;</span></li><li></li><li> <span class="c"># guarantee stability, regardless of algorithm</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <a class="l_k" href="../functions/sort.html">sort</a> <span class="q">'stable'</span><span class="sc">;</span></li><li> <span class="i">@new</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span> <a class="l_k" href="../functions/substr.html">substr</a><span class="s">(</span><span class="i">$a</span><span class="cm">,</span> <span class="n">3</span><span class="cm">,</span> <span class="n">5</span><span class="s">)</span> cmp <a class="l_k" href="../functions/substr.html">substr</a><span class="s">(</span><span class="i">$b</span><span class="cm">,</span> <span class="n">3</span><span class="cm">,</span> <span class="n">5</span><span class="s">)</span> <span class="s">}</span> <span class="i">@old</span><span class="sc">;</span></li><li></li><li> <span class="c"># force use of mergesort (not portable outside Perl 5.8)</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <a class="l_k" href="../functions/sort.html">sort</a> <span class="q">'_mergesort'</span><span class="sc">;</span> <span class="c"># note discouraging _</span></li><li> <span class="i">@new</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span> <a class="l_k" href="../functions/substr.html">substr</a><span class="s">(</span><span class="i">$a</span><span class="cm">,</span> <span class="n">3</span><span class="cm">,</span> <span class="n">5</span><span class="s">)</span> cmp <a class="l_k" href="../functions/substr.html">substr</a><span class="s">(</span><span class="i">$b</span><span class="cm">,</span> <span class="n">3</span><span class="cm">,</span> <span class="n">5</span><span class="s">)</span> <span class="s">}</span> <span class="i">@old</span><span class="sc">;</span></li></ol></pre><p>Warning: syntactical care is required when sorting the list returned from<br>
a function. If you want to sort the list returned by the function call<br>
<code class="inline"><span class="i">find_records</span><span class="s">(</span><span class="i">@key</span><span class="s">)</span></code>
, you can use:</p>
<pre class="verbatim"><ol><li> <span class="i">@contact</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span> <span class="i">$a</span> cmp <span class="i">$b</span> <span class="s">}</span> <span class="w">find_records</span> <span class="i">@key</span><span class="sc">;</span></li><li> <span class="i">@contact</span> = <a class="l_k" href="../functions/sort.html">sort</a> +<span class="i">find_records</span><span class="s">(</span><span class="i">@key</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">@contact</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="i">&find_records</span><span class="s">(</span><span class="i">@key</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">@contact</span> = <a class="l_k" href="../functions/sort.html">sort</a><span class="s">(</span><span class="i">find_records</span><span class="s">(</span><span class="i">@key</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>If instead you want to sort the array @key with the comparison routine<br>
<code class="inline"><span class="i">find_records</span><span class="s">(</span><span class="s">)</span></code>
then you can use:</p>
<pre class="verbatim"><ol><li> <span class="i">@contact</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span> <span class="i">find_records</span><span class="s">(</span><span class="s">)</span> <span class="s">}</span> <span class="i">@key</span><span class="sc">;</span></li><li> <span class="i">@contact</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="i">find_records</span><span class="s">(</span><span class="i">@key</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">@contact</span> = <a class="l_k" href="../functions/sort.html">sort</a><span class="s">(</span><span class="i">find_records</span> <span class="i">@key</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">@contact</span> = <a class="l_k" href="../functions/sort.html">sort</a><span class="s">(</span><span class="i">find_records</span> <span class="s">(</span><span class="i">@key</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>If you're using strict, you <i>must not</i> declare $a<br>
and $b as lexicals. They are package globals. That means<br>
that if you're in the <code class="inline"><span class="w">main</span></code>
package and type</p>
<pre class="verbatim"><ol><li> <span class="i">@articles</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span><span class="i">$b</span> <=> <span class="i">$a</span><span class="s">}</span> <span class="i">@files</span><span class="sc">;</span></li></ol></pre><p>then <code class="inline"><span class="i">$a</span></code>
and <code class="inline"><span class="i">$b</span></code>
are <code class="inline"><span class="i">$main::a</span></code>
and <code class="inline"><span class="i">$main::b</span></code>
(or <code class="inline"><span class="i">$::a</span></code>
and <code class="inline"><span class="i">$::b</span></code>
),<br>
but if you're in the <code class="inline"><span class="w">FooPack</span></code>
package, it's the same as typing</p>
<pre class="verbatim"><ol><li> <span class="i">@articles</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span><span class="i">$FooPack::b</span> <=> <span class="i">$FooPack::a</span><span class="s">}</span> <span class="i">@files</span><span class="sc">;</span></li></ol></pre><p>The comparison function is required to behave. If it returns<br>
inconsistent results (sometimes saying <code class="inline"><span class="i">$x</span>[<span class="n">1</span>]</code>
is less than <code class="inline"><span class="i">$x</span>[<span class="n">2</span>]</code>
and<br>
sometimes saying the opposite, for example) the results are not<br>
well-defined.</p>
<p>Because <code class="inline"><=></code>
returns <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> when either operand is <code class="inline"><span class="w">NaN</span></code>
<br>
(not-a-number), and because <code class="inline"><a class="l_k" href="../functions/sort.html">sort</a></code> will trigger a fatal error unless the<br>
result of a comparison is defined, when sorting with a comparison function<br>
like <code class="inline"><span class="i">$a</span> <=> <span class="i">$b</span></code>
, be careful about lists that might contain a <code class="inline"><span class="w">NaN</span></code>
.<br>
The following example takes advantage of the fact that <code class="inline"><span class="w">NaN</span> != <span class="w">NaN</span></code>
to<br>
eliminate any <code class="inline"><span class="w">NaN</span></code>
s from the input.</p>
<pre class="verbatim"><ol><li> <span class="i">@result</span> = <a class="l_k" href="../functions/sort.html">sort</a> <span class="s">{</span> <span class="i">$a</span> <=> <span class="i">$b</span> <span class="s">}</span> <a class="l_k" href="../functions/grep.html">grep</a> <span class="s">{</span> <span class="i">$_</span> == <span class="i">$_</span> <span class="s">}</span> <span class="i">@input</span><span class="sc">;</span></li></ol><]]></desc>
</keyword>
<keyword name="splice" type="function">
<params>
<param name='array'/>
<param name='offset'/>
<param name='length'/>
<param name='list'/>
</params>
<desc><![CDATA[Removes the elements designated by OFFSET and LENGTH from an array, and<br>
replaces them with the elements of LIST, if any. In list context,<br>
returns the elements removed from the array. In scalar context,<br>
returns the last element removed, or <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> if no elements are<br>
removed. The array grows or shrinks as necessary.<br>
If OFFSET is negative then it starts that far from the end of the array.<br>
If LENGTH is omitted, removes everything from OFFSET onward.<br>
If LENGTH is negative, removes the elements from OFFSET onward<br>
except for -LENGTH elements at the end of the array.<br>
If both OFFSET and LENGTH are omitted, removes everything. If OFFSET is<br>
past the end of the array, perl issues a warning, and splices at the<br>
end of the array.</p>
<p>The following equivalences hold (assuming <code class="inline"><span class="i">$[</span> == <span class="n">0</span> and <span class="i">$#a</span> >= <span class="i">$i</span></code>
)</p>
<pre class="verbatim"><ol><li> push(@a,$x,$y) splice(@a,@a,0,$x,$y)</li><li> pop(@a) splice(@a,-1)</li><li> shift(@a) splice(@a,0,1)</li><li> unshift(@a,$x,$y) splice(@a,0,0,$x,$y)</li><li> $a[$i] = $y splice(@a,$i,1,$y)</li></ol></pre><p>Example, assuming array lengths are passed before arrays:</p>
<pre class="verbatim"><ol><li><a name="aeq"></a> sub <span class="m">aeq</span> <span class="s">{</span> <span class="c"># compare two list values</span></li><li> <a class="l_k" href="../functions/my.html">my</a><span class="s">(</span><span class="i">@a</span><span class="s">)</span> = <a class="l_k" href="../functions/splice.html">splice</a><span class="s">(</span><span class="i">@_</span><span class="cm">,</span><span class="n">0</span><span class="cm">,</span><a class="l_k" href="../functions/shift.html">shift</a><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/my.html">my</a><span class="s">(</span><span class="i">@b</span><span class="s">)</span> = <a class="l_k" href="../functions/splice.html">splice</a><span class="s">(</span><span class="i">@_</span><span class="cm">,</span><span class="n">0</span><span class="cm">,</span><a class="l_k" href="../functions/shift.html">shift</a><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <span class="n">0</span> unless <span class="i">@a</span> == <span class="i">@b</span><span class="sc">;</span> <span class="c"># same len?</span></li><li> while <span class="s">(</span><span class="i">@a</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <span class="n">0</span> if <a class="l_k" href="../functions/pop.html">pop</a><span class="s">(</span><span class="i">@a</span><span class="s">)</span> ne <a class="l_k" href="../functions/pop.html">pop</a><span class="s">(</span><span class="i">@b</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <span class="n">1</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> if <span class="s">(</span><span class="i">&aeq</span><span class="s">(</span><span class="i">$len</span><span class="cm">,</span><span class="i">@foo</span>[<span class="n">1</span>..<span class="i">$len</span>]<span class="cm">,</span><span class="n">0</span>+<span class="i">@bar</span><span class="cm">,</span><span class="i">@bar</span><span class="s">)</span><span class="s">)</span> <span class="s">{</span> ... <span class="s">}</span></li></ol><]]></desc>
</keyword>
<keyword name="splice" type="function">
<params>
<param name='array'/>
<param name='offset'/>
<param name='length'/>
</params>
<desc><![CDATA[Removes the elements designated by OFFSET and LENGTH from an array, and<br>
replaces them with the elements of LIST, if any. In list context,<br>
returns the elements removed from the array. In scalar context,<br>
returns the last element removed, or <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> if no elements are<br>
removed. The array grows or shrinks as necessary.<br>
If OFFSET is negative then it starts that far from the end of the array.<br>
If LENGTH is omitted, removes everything from OFFSET onward.<br>
If LENGTH is negative, removes the elements from OFFSET onward<br>
except for -LENGTH elements at the end of the array.<br>
If both OFFSET and LENGTH are omitted, removes everything. If OFFSET is<br>
past the end of the array, perl issues a warning, and splices at the<br>
end of the array.</p>
<p>The following equivalences hold (assuming <code class="inline"><span class="i">$[</span> == <span class="n">0</span> and <span class="i">$#a</span> >= <span class="i">$i</span></code>
)</p>
<pre class="verbatim"><ol><li> push(@a,$x,$y) splice(@a,@a,0,$x,$y)</li><li> pop(@a) splice(@a,-1)</li><li> shift(@a) splice(@a,0,1)</li><li> unshift(@a,$x,$y) splice(@a,0,0,$x,$y)</li><li> $a[$i] = $y splice(@a,$i,1,$y)</li></ol></pre><p>Example, assuming array lengths are passed before arrays:</p>
<pre class="verbatim"><ol><li><a name="aeq"></a> sub <span class="m">aeq</span> <span class="s">{</span> <span class="c"># compare two list values</span></li><li> <a class="l_k" href="../functions/my.html">my</a><span class="s">(</span><span class="i">@a</span><span class="s">)</span> = <a class="l_k" href="../functions/splice.html">splice</a><span class="s">(</span><span class="i">@_</span><span class="cm">,</span><span class="n">0</span><span class="cm">,</span><a class="l_k" href="../functions/shift.html">shift</a><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/my.html">my</a><span class="s">(</span><span class="i">@b</span><span class="s">)</span> = <a class="l_k" href="../functions/splice.html">splice</a><span class="s">(</span><span class="i">@_</span><span class="cm">,</span><span class="n">0</span><span class="cm">,</span><a class="l_k" href="../functions/shift.html">shift</a><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <span class="n">0</span> unless <span class="i">@a</span> == <span class="i">@b</span><span class="sc">;</span> <span class="c"># same len?</span></li><li> while <span class="s">(</span><span class="i">@a</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <span class="n">0</span> if <a class="l_k" href="../functions/pop.html">pop</a><span class="s">(</span><span class="i">@a</span><span class="s">)</span> ne <a class="l_k" href="../functions/pop.html">pop</a><span class="s">(</span><span class="i">@b</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <span class="n">1</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> if <span class="s">(</span><span class="i">&aeq</span><span class="s">(</span><span class="i">$len</span><span class="cm">,</span><span class="i">@foo</span>[<span class="n">1</span>..<span class="i">$len</span>]<span class="cm">,</span><span class="n">0</span>+<span class="i">@bar</span><span class="cm">,</span><span class="i">@bar</span><span class="s">)</span><span class="s">)</span> <span class="s">{</span> ... <span class="s">}</span></li></ol><]]></desc>
</keyword>
<keyword name="splice" type="function">
<params>
<param name='array'/>
<param name='offset'/>
</params>
<desc><![CDATA[Removes the elements designated by OFFSET and LENGTH from an array, and<br>
replaces them with the elements of LIST, if any. In list context,<br>
returns the elements removed from the array. In scalar context,<br>
returns the last element removed, or <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> if no elements are<br>
removed. The array grows or shrinks as necessary.<br>
If OFFSET is negative then it starts that far from the end of the array.<br>
If LENGTH is omitted, removes everything from OFFSET onward.<br>
If LENGTH is negative, removes the elements from OFFSET onward<br>
except for -LENGTH elements at the end of the array.<br>
If both OFFSET and LENGTH are omitted, removes everything. If OFFSET is<br>
past the end of the array, perl issues a warning, and splices at the<br>
end of the array.</p>
<p>The following equivalences hold (assuming <code class="inline"><span class="i">$[</span> == <span class="n">0</span> and <span class="i">$#a</span> >= <span class="i">$i</span></code>
)</p>
<pre class="verbatim"><ol><li> push(@a,$x,$y) splice(@a,@a,0,$x,$y)</li><li> pop(@a) splice(@a,-1)</li><li> shift(@a) splice(@a,0,1)</li><li> unshift(@a,$x,$y) splice(@a,0,0,$x,$y)</li><li> $a[$i] = $y splice(@a,$i,1,$y)</li></ol></pre><p>Example, assuming array lengths are passed before arrays:</p>
<pre class="verbatim"><ol><li><a name="aeq"></a> sub <span class="m">aeq</span> <span class="s">{</span> <span class="c"># compare two list values</span></li><li> <a class="l_k" href="../functions/my.html">my</a><span class="s">(</span><span class="i">@a</span><span class="s">)</span> = <a class="l_k" href="../functions/splice.html">splice</a><span class="s">(</span><span class="i">@_</span><span class="cm">,</span><span class="n">0</span><span class="cm">,</span><a class="l_k" href="../functions/shift.html">shift</a><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/my.html">my</a><span class="s">(</span><span class="i">@b</span><span class="s">)</span> = <a class="l_k" href="../functions/splice.html">splice</a><span class="s">(</span><span class="i">@_</span><span class="cm">,</span><span class="n">0</span><span class="cm">,</span><a class="l_k" href="../functions/shift.html">shift</a><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <span class="n">0</span> unless <span class="i">@a</span> == <span class="i">@b</span><span class="sc">;</span> <span class="c"># same len?</span></li><li> while <span class="s">(</span><span class="i">@a</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <span class="n">0</span> if <a class="l_k" href="../functions/pop.html">pop</a><span class="s">(</span><span class="i">@a</span><span class="s">)</span> ne <a class="l_k" href="../functions/pop.html">pop</a><span class="s">(</span><span class="i">@b</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <span class="n">1</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> if <span class="s">(</span><span class="i">&aeq</span><span class="s">(</span><span class="i">$len</span><span class="cm">,</span><span class="i">@foo</span>[<span class="n">1</span>..<span class="i">$len</span>]<span class="cm">,</span><span class="n">0</span>+<span class="i">@bar</span><span class="cm">,</span><span class="i">@bar</span><span class="s">)</span><span class="s">)</span> <span class="s">{</span> ... <span class="s">}</span></li></ol><]]></desc>
</keyword>
<keyword name="splice" type="function">
<params>
<param name='array'/>
</params>
<desc><![CDATA[Removes the elements designated by OFFSET and LENGTH from an array, and<br>
replaces them with the elements of LIST, if any. In list context,<br>
returns the elements removed from the array. In scalar context,<br>
returns the last element removed, or <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> if no elements are<br>
removed. The array grows or shrinks as necessary.<br>
If OFFSET is negative then it starts that far from the end of the array.<br>
If LENGTH is omitted, removes everything from OFFSET onward.<br>
If LENGTH is negative, removes the elements from OFFSET onward<br>
except for -LENGTH elements at the end of the array.<br>
If both OFFSET and LENGTH are omitted, removes everything. If OFFSET is<br>
past the end of the array, perl issues a warning, and splices at the<br>
end of the array.</p>
<p>The following equivalences hold (assuming <code class="inline"><span class="i">$[</span> == <span class="n">0</span> and <span class="i">$#a</span> >= <span class="i">$i</span></code>
)</p>
<pre class="verbatim"><ol><li> push(@a,$x,$y) splice(@a,@a,0,$x,$y)</li><li> pop(@a) splice(@a,-1)</li><li> shift(@a) splice(@a,0,1)</li><li> unshift(@a,$x,$y) splice(@a,0,0,$x,$y)</li><li> $a[$i] = $y splice(@a,$i,1,$y)</li></ol></pre><p>Example, assuming array lengths are passed before arrays:</p>
<pre class="verbatim"><ol><li><a name="aeq"></a> sub <span class="m">aeq</span> <span class="s">{</span> <span class="c"># compare two list values</span></li><li> <a class="l_k" href="../functions/my.html">my</a><span class="s">(</span><span class="i">@a</span><span class="s">)</span> = <a class="l_k" href="../functions/splice.html">splice</a><span class="s">(</span><span class="i">@_</span><span class="cm">,</span><span class="n">0</span><span class="cm">,</span><a class="l_k" href="../functions/shift.html">shift</a><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/my.html">my</a><span class="s">(</span><span class="i">@b</span><span class="s">)</span> = <a class="l_k" href="../functions/splice.html">splice</a><span class="s">(</span><span class="i">@_</span><span class="cm">,</span><span class="n">0</span><span class="cm">,</span><a class="l_k" href="../functions/shift.html">shift</a><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <span class="n">0</span> unless <span class="i">@a</span> == <span class="i">@b</span><span class="sc">;</span> <span class="c"># same len?</span></li><li> while <span class="s">(</span><span class="i">@a</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <span class="n">0</span> if <a class="l_k" href="../functions/pop.html">pop</a><span class="s">(</span><span class="i">@a</span><span class="s">)</span> ne <a class="l_k" href="../functions/pop.html">pop</a><span class="s">(</span><span class="i">@b</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <span class="n">1</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> if <span class="s">(</span><span class="i">&aeq</span><span class="s">(</span><span class="i">$len</span><span class="cm">,</span><span class="i">@foo</span>[<span class="n">1</span>..<span class="i">$len</span>]<span class="cm">,</span><span class="n">0</span>+<span class="i">@bar</span><span class="cm">,</span><span class="i">@bar</span><span class="s">)</span><span class="s">)</span> <span class="s">{</span> ... <span class="s">}</span></li></ol><]]></desc>
</keyword>
<keyword name="split" type="function">
<params>
<param name='/pattern/'/>
<param name='expr'/>
<param name='limit'/>
</params>
<desc><![CDATA[Splits the string EXPR into a list of strings and returns that list. By<br>
default, empty leading fields are preserved, and empty trailing ones are<br>
deleted. (If all fields are empty, they are considered to be trailing.)</p>
<p>In scalar context, returns the number of fields found. In scalar and void<br>
context it splits into the <code class="inline"><span class="i">@_</span></code>
array. Use of split in scalar and void<br>
context is deprecated, however, because it clobbers your subroutine<br>
arguments.</p>
<p>If EXPR is omitted, splits the <code class="inline"><span class="i">$_</span></code>
string. If PATTERN is also omitted,<br>
splits on whitespace (after skipping any leading whitespace). Anything<br>
matching PATTERN is taken to be a delimiter separating the fields. (Note<br>
that the delimiter may be longer than one character.)</p>
<p>If LIMIT is specified and positive, it represents the maximum number<br>
of fields the EXPR will be split into, though the actual number of<br>
fields returned depends on the number of times PATTERN matches within<br>
EXPR. If LIMIT is unspecified or zero, trailing null fields are<br>
stripped (which potential users of <code class="inline"><a class="l_k" href="../functions/pop.html">pop</a></code> would do well to remember).<br>
If LIMIT is negative, it is treated as if an arbitrarily large LIMIT<br>
had been specified. Note that splitting an EXPR that evaluates to the<br>
empty string always returns the empty list, regardless of the LIMIT<br>
specified.</p>
<p>A pattern matching the null string (not to be confused with<br>
a null pattern <code class="inline"><span class="q">//</span></code>
, which is just one member of the set of patterns<br>
matching a null string) will split the value of EXPR into separate<br>
characters at each point it matches that way. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/join.html">join</a><span class="s">(</span><span class="q">':'</span><span class="cm">,</span> <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/ */</span><span class="cm">,</span> <span class="q">'hi there'</span><span class="s">)</span><span class="s">)</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li></ol></pre><p>produces the output 'h:i:t:h:e:r:e'.</p>
<p>As a special case for <code class="inline"><a class="l_k" href="../functions/split.html">split</a></code>, using the empty pattern <code class="inline"><span class="q">//</span></code>
specifically<br>
matches only the null string, and is not be confused with the regular use<br>
of <code class="inline"><span class="q">//</span></code>
to mean "the last successful pattern match". So, for <code class="inline"><a class="l_k" href="../functions/split.html">split</a></code>,<br>
the following:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/join.html">join</a><span class="s">(</span><span class="q">':'</span><span class="cm">,</span> <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">//</span><span class="cm">,</span> <span class="q">'hi there'</span><span class="s">)</span><span class="s">)</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li></ol></pre><p>produces the output 'h:i: :t:h:e:r:e'.</p>
<p>Empty leading fields are produced when there are positive-width matches at<br>
the beginning of the string; a zero-width match at the beginning of<br>
the string does not produce an empty field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/join.html">join</a><span class="s">(</span><span class="q">':'</span><span class="cm">,</span> <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/(?=\w)/</span><span class="cm">,</span> <span class="q">'hi there!'</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>produces the output 'h:i :t:h:e:r:e!'. Empty trailing fields, on the other<br>
hand, are produced when there is a match at the end of the string (and<br>
when LIMIT is given and is not 0), regardless of the length of the match.<br>
For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/join.html">join</a><span class="s">(</span><span class="q">':'</span><span class="cm">,</span> <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">//</span><span class="cm">,</span> <span class="q">'hi there!'</span><span class="cm">,</span> <span class="n">-1</span><span class="s">)</span><span class="s">)</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/join.html">join</a><span class="s">(</span><span class="q">':'</span><span class="cm">,</span> <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/\W/</span><span class="cm">,</span> <span class="q">'hi there!'</span><span class="cm">,</span> <span class="n">-1</span><span class="s">)</span><span class="s">)</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li></ol></pre><p>produce the output 'h:i: :t:h:e:r:e:!:' and 'hi:there:', respectively,<br>
both with an empty trailing field.</p>
<p>The LIMIT parameter can be used to split a line partially</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$login</span><span class="cm">,</span> <span class="i">$passwd</span><span class="cm">,</span> <span class="i">$remainder</span><span class="s">)</span> = <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/:/</span><span class="cm">,</span> <span class="i">$_</span><span class="cm">,</span> <span class="n">3</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>When assigning to a list, if LIMIT is omitted, or zero, Perl supplies<br>
a LIMIT one larger than the number of variables in the list, to avoid<br>
unnecessary work. For the list above LIMIT would have been 4 by<br>
default. In time critical applications it behooves you not to split<br>
into more fields than you really need.</p>
<p>If the PATTERN contains parentheses, additional list elements are<br>
created from each matching substring in the delimiter.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/([,-])/</span><span class="cm">,</span> <span class="q">"1-10,20"</span><span class="cm">,</span> <span class="n">3</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>produces the list value</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="n">1</span><span class="cm">,</span> <span class="q">'-'</span><span class="cm">,</span> <span class="n">10</span><span class="cm">,</span> <span class="q">','</span><span class="cm">,</span> <span class="n">20</span><span class="s">)</span></li></ol></pre><p>If you had the entire header of a normal Unix email message in $header,<br>
you could split it up into fields and their values this way:</p>
<pre class="verbatim"><ol><li> <span class="i">$header</span> =~ <span class="q">s/\n(?=\s)//g</span><span class="sc">;</span> <span class="c"># fix continuation lines</span></li><li> <span class="i">%hdrs</span> = <span class="s">(</span><span class="w">UNIX_FROM</span> <span class="cm">=></span> <a class="l_k" href="../functions/split.html">split</a> <span class="q">/^(\S*?):\s*/m</span><span class="cm">,</span> <span class="i">$header</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The pattern <code class="inline"><span class="q">/PATTERN/</span></code>
may be replaced with an expression to specify<br>
patterns that vary at runtime. (To do runtime compilation only once,<br>
use <code class="inline"><span class="q">/$variable/o</span></code>
.)</p>
<p>As a special case, specifying a PATTERN of space (<code class="inline"><span class="q">' '</span></code>
) will split on<br>
white space just as <code class="inline"><a class="l_k" href="../functions/split.html">split</a></code> with no arguments does. Thus, <code class="inline"><a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">' '</span><span class="s">)</span></code>
can<br>
be used to emulate <b>awk</b>'s default behavior, whereas <code class="inline"><a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/ /</span><span class="s">)</span></code>
<br>
will give you as many null initial fields as there are leading spaces.<br>
A <code class="inline"><a class="l_k" href="../functions/split.html">split</a></code> on <code class="inline"><span class="q">/\s+/</span></code>
is like a <code class="inline"><a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">' '</span><span class="s">)</span></code>
except that any leading<br>
whitespace produces a null first field. A <code class="inline"><a class="l_k" href="../functions/split.html">split</a></code> with no arguments<br>
really does a <code class="inline"><a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">' '</span><span class="cm">,</span> <span class="i">$_</span><span class="s">)</span></code>
internally.</p>
<p>A PATTERN of <code class="inline"><span class="q">/^/</span></code>
is treated as if it were <code class="inline"><span class="q">/^/m</span></code>
, since it isn't<br>
much use otherwise.</p>
<p>Example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">PASSWD</span><span class="cm">,</span> <span class="q">'/etc/passwd'</span><span class="s">)</span><span class="sc">;</span></li><li> while <span class="s">(</span><span class="q"><PASSWD></span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/chomp.html">chomp</a><span class="sc">;</span></li><li> <span class="s">(</span><span class="i">$login</span><span class="cm">,</span> <span class="i">$passwd</span><span class="cm">,</span> <span class="i">$uid</span><span class="cm">,</span> <span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$gcos</span><span class="cm">,</span> <span class="i">$home</span><span class="cm">,</span> <span class="i">$shell</span><span class="s">)</span> = <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/:/</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#...</span></li><li> <span class="s">}</span></li></ol></pre><p>As with regular pattern matching, any capturing parentheses that are not<br>
matched in a <code class="inline"><a class="l_k" href="../functions/split.html">split()</a></code> will be set to <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> when returned:</p>
<pre class="verbatim"><ol><li> <span class="i">@fields</span> = <a class="l_k" href="../functions/split.html">split</a> <span class="q">/(A)|B/</span><span class="cm">,</span> <span class="q">"1A2B3"</span><span class="sc">;</span></li><li> <span class="c"># @fields is (1, 'A', 2, undef, 3)</span></li></ol><]]></desc>
</keyword>
<keyword name="split" type="function">
<params>
<param name='/pattern/'/>
<param name='expr'/>
</params>
<desc><![CDATA[Splits the string EXPR into a list of strings and returns that list. By<br>
default, empty leading fields are preserved, and empty trailing ones are<br>
deleted. (If all fields are empty, they are considered to be trailing.)</p>
<p>In scalar context, returns the number of fields found. In scalar and void<br>
context it splits into the <code class="inline"><span class="i">@_</span></code>
array. Use of split in scalar and void<br>
context is deprecated, however, because it clobbers your subroutine<br>
arguments.</p>
<p>If EXPR is omitted, splits the <code class="inline"><span class="i">$_</span></code>
string. If PATTERN is also omitted,<br>
splits on whitespace (after skipping any leading whitespace). Anything<br>
matching PATTERN is taken to be a delimiter separating the fields. (Note<br>
that the delimiter may be longer than one character.)</p>
<p>If LIMIT is specified and positive, it represents the maximum number<br>
of fields the EXPR will be split into, though the actual number of<br>
fields returned depends on the number of times PATTERN matches within<br>
EXPR. If LIMIT is unspecified or zero, trailing null fields are<br>
stripped (which potential users of <code class="inline"><a class="l_k" href="../functions/pop.html">pop</a></code> would do well to remember).<br>
If LIMIT is negative, it is treated as if an arbitrarily large LIMIT<br>
had been specified. Note that splitting an EXPR that evaluates to the<br>
empty string always returns the empty list, regardless of the LIMIT<br>
specified.</p>
<p>A pattern matching the null string (not to be confused with<br>
a null pattern <code class="inline"><span class="q">//</span></code>
, which is just one member of the set of patterns<br>
matching a null string) will split the value of EXPR into separate<br>
characters at each point it matches that way. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/join.html">join</a><span class="s">(</span><span class="q">':'</span><span class="cm">,</span> <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/ */</span><span class="cm">,</span> <span class="q">'hi there'</span><span class="s">)</span><span class="s">)</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li></ol></pre><p>produces the output 'h:i:t:h:e:r:e'.</p>
<p>As a special case for <code class="inline"><a class="l_k" href="../functions/split.html">split</a></code>, using the empty pattern <code class="inline"><span class="q">//</span></code>
specifically<br>
matches only the null string, and is not be confused with the regular use<br>
of <code class="inline"><span class="q">//</span></code>
to mean "the last successful pattern match". So, for <code class="inline"><a class="l_k" href="../functions/split.html">split</a></code>,<br>
the following:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/join.html">join</a><span class="s">(</span><span class="q">':'</span><span class="cm">,</span> <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">//</span><span class="cm">,</span> <span class="q">'hi there'</span><span class="s">)</span><span class="s">)</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li></ol></pre><p>produces the output 'h:i: :t:h:e:r:e'.</p>
<p>Empty leading fields are produced when there are positive-width matches at<br>
the beginning of the string; a zero-width match at the beginning of<br>
the string does not produce an empty field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/join.html">join</a><span class="s">(</span><span class="q">':'</span><span class="cm">,</span> <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/(?=\w)/</span><span class="cm">,</span> <span class="q">'hi there!'</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>produces the output 'h:i :t:h:e:r:e!'. Empty trailing fields, on the other<br>
hand, are produced when there is a match at the end of the string (and<br>
when LIMIT is given and is not 0), regardless of the length of the match.<br>
For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/join.html">join</a><span class="s">(</span><span class="q">':'</span><span class="cm">,</span> <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">//</span><span class="cm">,</span> <span class="q">'hi there!'</span><span class="cm">,</span> <span class="n">-1</span><span class="s">)</span><span class="s">)</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/join.html">join</a><span class="s">(</span><span class="q">':'</span><span class="cm">,</span> <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/\W/</span><span class="cm">,</span> <span class="q">'hi there!'</span><span class="cm">,</span> <span class="n">-1</span><span class="s">)</span><span class="s">)</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li></ol></pre><p>produce the output 'h:i: :t:h:e:r:e:!:' and 'hi:there:', respectively,<br>
both with an empty trailing field.</p>
<p>The LIMIT parameter can be used to split a line partially</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$login</span><span class="cm">,</span> <span class="i">$passwd</span><span class="cm">,</span> <span class="i">$remainder</span><span class="s">)</span> = <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/:/</span><span class="cm">,</span> <span class="i">$_</span><span class="cm">,</span> <span class="n">3</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>When assigning to a list, if LIMIT is omitted, or zero, Perl supplies<br>
a LIMIT one larger than the number of variables in the list, to avoid<br>
unnecessary work. For the list above LIMIT would have been 4 by<br>
default. In time critical applications it behooves you not to split<br>
into more fields than you really need.</p>
<p>If the PATTERN contains parentheses, additional list elements are<br>
created from each matching substring in the delimiter.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/([,-])/</span><span class="cm">,</span> <span class="q">"1-10,20"</span><span class="cm">,</span> <span class="n">3</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>produces the list value</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="n">1</span><span class="cm">,</span> <span class="q">'-'</span><span class="cm">,</span> <span class="n">10</span><span class="cm">,</span> <span class="q">','</span><span class="cm">,</span> <span class="n">20</span><span class="s">)</span></li></ol></pre><p>If you had the entire header of a normal Unix email message in $header,<br>
you could split it up into fields and their values this way:</p>
<pre class="verbatim"><ol><li> <span class="i">$header</span> =~ <span class="q">s/\n(?=\s)//g</span><span class="sc">;</span> <span class="c"># fix continuation lines</span></li><li> <span class="i">%hdrs</span> = <span class="s">(</span><span class="w">UNIX_FROM</span> <span class="cm">=></span> <a class="l_k" href="../functions/split.html">split</a> <span class="q">/^(\S*?):\s*/m</span><span class="cm">,</span> <span class="i">$header</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The pattern <code class="inline"><span class="q">/PATTERN/</span></code>
may be replaced with an expression to specify<br>
patterns that vary at runtime. (To do runtime compilation only once,<br>
use <code class="inline"><span class="q">/$variable/o</span></code>
.)</p>
<p>As a special case, specifying a PATTERN of space (<code class="inline"><span class="q">' '</span></code>
) will split on<br>
white space just as <code class="inline"><a class="l_k" href="../functions/split.html">split</a></code> with no arguments does. Thus, <code class="inline"><a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">' '</span><span class="s">)</span></code>
can<br>
be used to emulate <b>awk</b>'s default behavior, whereas <code class="inline"><a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/ /</span><span class="s">)</span></code>
<br>
will give you as many null initial fields as there are leading spaces.<br>
A <code class="inline"><a class="l_k" href="../functions/split.html">split</a></code> on <code class="inline"><span class="q">/\s+/</span></code>
is like a <code class="inline"><a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">' '</span><span class="s">)</span></code>
except that any leading<br>
whitespace produces a null first field. A <code class="inline"><a class="l_k" href="../functions/split.html">split</a></code> with no arguments<br>
really does a <code class="inline"><a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">' '</span><span class="cm">,</span> <span class="i">$_</span><span class="s">)</span></code>
internally.</p>
<p>A PATTERN of <code class="inline"><span class="q">/^/</span></code>
is treated as if it were <code class="inline"><span class="q">/^/m</span></code>
, since it isn't<br>
much use otherwise.</p>
<p>Example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">PASSWD</span><span class="cm">,</span> <span class="q">'/etc/passwd'</span><span class="s">)</span><span class="sc">;</span></li><li> while <span class="s">(</span><span class="q"><PASSWD></span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/chomp.html">chomp</a><span class="sc">;</span></li><li> <span class="s">(</span><span class="i">$login</span><span class="cm">,</span> <span class="i">$passwd</span><span class="cm">,</span> <span class="i">$uid</span><span class="cm">,</span> <span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$gcos</span><span class="cm">,</span> <span class="i">$home</span><span class="cm">,</span> <span class="i">$shell</span><span class="s">)</span> = <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/:/</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#...</span></li><li> <span class="s">}</span></li></ol></pre><p>As with regular pattern matching, any capturing parentheses that are not<br>
matched in a <code class="inline"><a class="l_k" href="../functions/split.html">split()</a></code> will be set to <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> when returned:</p>
<pre class="verbatim"><ol><li> <span class="i">@fields</span> = <a class="l_k" href="../functions/split.html">split</a> <span class="q">/(A)|B/</span><span class="cm">,</span> <span class="q">"1A2B3"</span><span class="sc">;</span></li><li> <span class="c"># @fields is (1, 'A', 2, undef, 3)</span></li></ol><]]></desc>
</keyword>
<keyword name="split" type="function">
<params>
<param name='/pattern/'/>
</params>
<desc><![CDATA[Splits the string EXPR into a list of strings and returns that list. By<br>
default, empty leading fields are preserved, and empty trailing ones are<br>
deleted. (If all fields are empty, they are considered to be trailing.)</p>
<p>In scalar context, returns the number of fields found. In scalar and void<br>
context it splits into the <code class="inline"><span class="i">@_</span></code>
array. Use of split in scalar and void<br>
context is deprecated, however, because it clobbers your subroutine<br>
arguments.</p>
<p>If EXPR is omitted, splits the <code class="inline"><span class="i">$_</span></code>
string. If PATTERN is also omitted,<br>
splits on whitespace (after skipping any leading whitespace). Anything<br>
matching PATTERN is taken to be a delimiter separating the fields. (Note<br>
that the delimiter may be longer than one character.)</p>
<p>If LIMIT is specified and positive, it represents the maximum number<br>
of fields the EXPR will be split into, though the actual number of<br>
fields returned depends on the number of times PATTERN matches within<br>
EXPR. If LIMIT is unspecified or zero, trailing null fields are<br>
stripped (which potential users of <code class="inline"><a class="l_k" href="../functions/pop.html">pop</a></code> would do well to remember).<br>
If LIMIT is negative, it is treated as if an arbitrarily large LIMIT<br>
had been specified. Note that splitting an EXPR that evaluates to the<br>
empty string always returns the empty list, regardless of the LIMIT<br>
specified.</p>
<p>A pattern matching the null string (not to be confused with<br>
a null pattern <code class="inline"><span class="q">//</span></code>
, which is just one member of the set of patterns<br>
matching a null string) will split the value of EXPR into separate<br>
characters at each point it matches that way. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/join.html">join</a><span class="s">(</span><span class="q">':'</span><span class="cm">,</span> <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/ */</span><span class="cm">,</span> <span class="q">'hi there'</span><span class="s">)</span><span class="s">)</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li></ol></pre><p>produces the output 'h:i:t:h:e:r:e'.</p>
<p>As a special case for <code class="inline"><a class="l_k" href="../functions/split.html">split</a></code>, using the empty pattern <code class="inline"><span class="q">//</span></code>
specifically<br>
matches only the null string, and is not be confused with the regular use<br>
of <code class="inline"><span class="q">//</span></code>
to mean "the last successful pattern match". So, for <code class="inline"><a class="l_k" href="../functions/split.html">split</a></code>,<br>
the following:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/join.html">join</a><span class="s">(</span><span class="q">':'</span><span class="cm">,</span> <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">//</span><span class="cm">,</span> <span class="q">'hi there'</span><span class="s">)</span><span class="s">)</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li></ol></pre><p>produces the output 'h:i: :t:h:e:r:e'.</p>
<p>Empty leading fields are produced when there are positive-width matches at<br>
the beginning of the string; a zero-width match at the beginning of<br>
the string does not produce an empty field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/join.html">join</a><span class="s">(</span><span class="q">':'</span><span class="cm">,</span> <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/(?=\w)/</span><span class="cm">,</span> <span class="q">'hi there!'</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>produces the output 'h:i :t:h:e:r:e!'. Empty trailing fields, on the other<br>
hand, are produced when there is a match at the end of the string (and<br>
when LIMIT is given and is not 0), regardless of the length of the match.<br>
For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/join.html">join</a><span class="s">(</span><span class="q">':'</span><span class="cm">,</span> <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">//</span><span class="cm">,</span> <span class="q">'hi there!'</span><span class="cm">,</span> <span class="n">-1</span><span class="s">)</span><span class="s">)</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/join.html">join</a><span class="s">(</span><span class="q">':'</span><span class="cm">,</span> <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/\W/</span><span class="cm">,</span> <span class="q">'hi there!'</span><span class="cm">,</span> <span class="n">-1</span><span class="s">)</span><span class="s">)</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li></ol></pre><p>produce the output 'h:i: :t:h:e:r:e:!:' and 'hi:there:', respectively,<br>
both with an empty trailing field.</p>
<p>The LIMIT parameter can be used to split a line partially</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$login</span><span class="cm">,</span> <span class="i">$passwd</span><span class="cm">,</span> <span class="i">$remainder</span><span class="s">)</span> = <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/:/</span><span class="cm">,</span> <span class="i">$_</span><span class="cm">,</span> <span class="n">3</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>When assigning to a list, if LIMIT is omitted, or zero, Perl supplies<br>
a LIMIT one larger than the number of variables in the list, to avoid<br>
unnecessary work. For the list above LIMIT would have been 4 by<br>
default. In time critical applications it behooves you not to split<br>
into more fields than you really need.</p>
<p>If the PATTERN contains parentheses, additional list elements are<br>
created from each matching substring in the delimiter.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/([,-])/</span><span class="cm">,</span> <span class="q">"1-10,20"</span><span class="cm">,</span> <span class="n">3</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>produces the list value</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="n">1</span><span class="cm">,</span> <span class="q">'-'</span><span class="cm">,</span> <span class="n">10</span><span class="cm">,</span> <span class="q">','</span><span class="cm">,</span> <span class="n">20</span><span class="s">)</span></li></ol></pre><p>If you had the entire header of a normal Unix email message in $header,<br>
you could split it up into fields and their values this way:</p>
<pre class="verbatim"><ol><li> <span class="i">$header</span> =~ <span class="q">s/\n(?=\s)//g</span><span class="sc">;</span> <span class="c"># fix continuation lines</span></li><li> <span class="i">%hdrs</span> = <span class="s">(</span><span class="w">UNIX_FROM</span> <span class="cm">=></span> <a class="l_k" href="../functions/split.html">split</a> <span class="q">/^(\S*?):\s*/m</span><span class="cm">,</span> <span class="i">$header</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The pattern <code class="inline"><span class="q">/PATTERN/</span></code>
may be replaced with an expression to specify<br>
patterns that vary at runtime. (To do runtime compilation only once,<br>
use <code class="inline"><span class="q">/$variable/o</span></code>
.)</p>
<p>As a special case, specifying a PATTERN of space (<code class="inline"><span class="q">' '</span></code>
) will split on<br>
white space just as <code class="inline"><a class="l_k" href="../functions/split.html">split</a></code> with no arguments does. Thus, <code class="inline"><a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">' '</span><span class="s">)</span></code>
can<br>
be used to emulate <b>awk</b>'s default behavior, whereas <code class="inline"><a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/ /</span><span class="s">)</span></code>
<br>
will give you as many null initial fields as there are leading spaces.<br>
A <code class="inline"><a class="l_k" href="../functions/split.html">split</a></code> on <code class="inline"><span class="q">/\s+/</span></code>
is like a <code class="inline"><a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">' '</span><span class="s">)</span></code>
except that any leading<br>
whitespace produces a null first field. A <code class="inline"><a class="l_k" href="../functions/split.html">split</a></code> with no arguments<br>
really does a <code class="inline"><a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">' '</span><span class="cm">,</span> <span class="i">$_</span><span class="s">)</span></code>
internally.</p>
<p>A PATTERN of <code class="inline"><span class="q">/^/</span></code>
is treated as if it were <code class="inline"><span class="q">/^/m</span></code>
, since it isn't<br>
much use otherwise.</p>
<p>Example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">PASSWD</span><span class="cm">,</span> <span class="q">'/etc/passwd'</span><span class="s">)</span><span class="sc">;</span></li><li> while <span class="s">(</span><span class="q"><PASSWD></span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/chomp.html">chomp</a><span class="sc">;</span></li><li> <span class="s">(</span><span class="i">$login</span><span class="cm">,</span> <span class="i">$passwd</span><span class="cm">,</span> <span class="i">$uid</span><span class="cm">,</span> <span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$gcos</span><span class="cm">,</span> <span class="i">$home</span><span class="cm">,</span> <span class="i">$shell</span><span class="s">)</span> = <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/:/</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#...</span></li><li> <span class="s">}</span></li></ol></pre><p>As with regular pattern matching, any capturing parentheses that are not<br>
matched in a <code class="inline"><a class="l_k" href="../functions/split.html">split()</a></code> will be set to <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> when returned:</p>
<pre class="verbatim"><ol><li> <span class="i">@fields</span> = <a class="l_k" href="../functions/split.html">split</a> <span class="q">/(A)|B/</span><span class="cm">,</span> <span class="q">"1A2B3"</span><span class="sc">;</span></li><li> <span class="c"># @fields is (1, 'A', 2, undef, 3)</span></li></ol><]]></desc>
</keyword>
<keyword name="split" type="function">
<params>
</params>
<desc><![CDATA[Splits the string EXPR into a list of strings and returns that list. By<br>
default, empty leading fields are preserved, and empty trailing ones are<br>
deleted. (If all fields are empty, they are considered to be trailing.)</p>
<p>In scalar context, returns the number of fields found. In scalar and void<br>
context it splits into the <code class="inline"><span class="i">@_</span></code>
array. Use of split in scalar and void<br>
context is deprecated, however, because it clobbers your subroutine<br>
arguments.</p>
<p>If EXPR is omitted, splits the <code class="inline"><span class="i">$_</span></code>
string. If PATTERN is also omitted,<br>
splits on whitespace (after skipping any leading whitespace). Anything<br>
matching PATTERN is taken to be a delimiter separating the fields. (Note<br>
that the delimiter may be longer than one character.)</p>
<p>If LIMIT is specified and positive, it represents the maximum number<br>
of fields the EXPR will be split into, though the actual number of<br>
fields returned depends on the number of times PATTERN matches within<br>
EXPR. If LIMIT is unspecified or zero, trailing null fields are<br>
stripped (which potential users of <code class="inline"><a class="l_k" href="../functions/pop.html">pop</a></code> would do well to remember).<br>
If LIMIT is negative, it is treated as if an arbitrarily large LIMIT<br>
had been specified. Note that splitting an EXPR that evaluates to the<br>
empty string always returns the empty list, regardless of the LIMIT<br>
specified.</p>
<p>A pattern matching the null string (not to be confused with<br>
a null pattern <code class="inline"><span class="q">//</span></code>
, which is just one member of the set of patterns<br>
matching a null string) will split the value of EXPR into separate<br>
characters at each point it matches that way. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/join.html">join</a><span class="s">(</span><span class="q">':'</span><span class="cm">,</span> <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/ */</span><span class="cm">,</span> <span class="q">'hi there'</span><span class="s">)</span><span class="s">)</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li></ol></pre><p>produces the output 'h:i:t:h:e:r:e'.</p>
<p>As a special case for <code class="inline"><a class="l_k" href="../functions/split.html">split</a></code>, using the empty pattern <code class="inline"><span class="q">//</span></code>
specifically<br>
matches only the null string, and is not be confused with the regular use<br>
of <code class="inline"><span class="q">//</span></code>
to mean "the last successful pattern match". So, for <code class="inline"><a class="l_k" href="../functions/split.html">split</a></code>,<br>
the following:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/join.html">join</a><span class="s">(</span><span class="q">':'</span><span class="cm">,</span> <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">//</span><span class="cm">,</span> <span class="q">'hi there'</span><span class="s">)</span><span class="s">)</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li></ol></pre><p>produces the output 'h:i: :t:h:e:r:e'.</p>
<p>Empty leading fields are produced when there are positive-width matches at<br>
the beginning of the string; a zero-width match at the beginning of<br>
the string does not produce an empty field. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/join.html">join</a><span class="s">(</span><span class="q">':'</span><span class="cm">,</span> <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/(?=\w)/</span><span class="cm">,</span> <span class="q">'hi there!'</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>produces the output 'h:i :t:h:e:r:e!'. Empty trailing fields, on the other<br>
hand, are produced when there is a match at the end of the string (and<br>
when LIMIT is given and is not 0), regardless of the length of the match.<br>
For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/join.html">join</a><span class="s">(</span><span class="q">':'</span><span class="cm">,</span> <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">//</span><span class="cm">,</span> <span class="q">'hi there!'</span><span class="cm">,</span> <span class="n">-1</span><span class="s">)</span><span class="s">)</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/join.html">join</a><span class="s">(</span><span class="q">':'</span><span class="cm">,</span> <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/\W/</span><span class="cm">,</span> <span class="q">'hi there!'</span><span class="cm">,</span> <span class="n">-1</span><span class="s">)</span><span class="s">)</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li></ol></pre><p>produce the output 'h:i: :t:h:e:r:e:!:' and 'hi:there:', respectively,<br>
both with an empty trailing field.</p>
<p>The LIMIT parameter can be used to split a line partially</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$login</span><span class="cm">,</span> <span class="i">$passwd</span><span class="cm">,</span> <span class="i">$remainder</span><span class="s">)</span> = <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/:/</span><span class="cm">,</span> <span class="i">$_</span><span class="cm">,</span> <span class="n">3</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>When assigning to a list, if LIMIT is omitted, or zero, Perl supplies<br>
a LIMIT one larger than the number of variables in the list, to avoid<br>
unnecessary work. For the list above LIMIT would have been 4 by<br>
default. In time critical applications it behooves you not to split<br>
into more fields than you really need.</p>
<p>If the PATTERN contains parentheses, additional list elements are<br>
created from each matching substring in the delimiter.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/([,-])/</span><span class="cm">,</span> <span class="q">"1-10,20"</span><span class="cm">,</span> <span class="n">3</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>produces the list value</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="n">1</span><span class="cm">,</span> <span class="q">'-'</span><span class="cm">,</span> <span class="n">10</span><span class="cm">,</span> <span class="q">','</span><span class="cm">,</span> <span class="n">20</span><span class="s">)</span></li></ol></pre><p>If you had the entire header of a normal Unix email message in $header,<br>
you could split it up into fields and their values this way:</p>
<pre class="verbatim"><ol><li> <span class="i">$header</span> =~ <span class="q">s/\n(?=\s)//g</span><span class="sc">;</span> <span class="c"># fix continuation lines</span></li><li> <span class="i">%hdrs</span> = <span class="s">(</span><span class="w">UNIX_FROM</span> <span class="cm">=></span> <a class="l_k" href="../functions/split.html">split</a> <span class="q">/^(\S*?):\s*/m</span><span class="cm">,</span> <span class="i">$header</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The pattern <code class="inline"><span class="q">/PATTERN/</span></code>
may be replaced with an expression to specify<br>
patterns that vary at runtime. (To do runtime compilation only once,<br>
use <code class="inline"><span class="q">/$variable/o</span></code>
.)</p>
<p>As a special case, specifying a PATTERN of space (<code class="inline"><span class="q">' '</span></code>
) will split on<br>
white space just as <code class="inline"><a class="l_k" href="../functions/split.html">split</a></code> with no arguments does. Thus, <code class="inline"><a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">' '</span><span class="s">)</span></code>
can<br>
be used to emulate <b>awk</b>'s default behavior, whereas <code class="inline"><a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/ /</span><span class="s">)</span></code>
<br>
will give you as many null initial fields as there are leading spaces.<br>
A <code class="inline"><a class="l_k" href="../functions/split.html">split</a></code> on <code class="inline"><span class="q">/\s+/</span></code>
is like a <code class="inline"><a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">' '</span><span class="s">)</span></code>
except that any leading<br>
whitespace produces a null first field. A <code class="inline"><a class="l_k" href="../functions/split.html">split</a></code> with no arguments<br>
really does a <code class="inline"><a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">' '</span><span class="cm">,</span> <span class="i">$_</span><span class="s">)</span></code>
internally.</p>
<p>A PATTERN of <code class="inline"><span class="q">/^/</span></code>
is treated as if it were <code class="inline"><span class="q">/^/m</span></code>
, since it isn't<br>
much use otherwise.</p>
<p>Example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">PASSWD</span><span class="cm">,</span> <span class="q">'/etc/passwd'</span><span class="s">)</span><span class="sc">;</span></li><li> while <span class="s">(</span><span class="q"><PASSWD></span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/chomp.html">chomp</a><span class="sc">;</span></li><li> <span class="s">(</span><span class="i">$login</span><span class="cm">,</span> <span class="i">$passwd</span><span class="cm">,</span> <span class="i">$uid</span><span class="cm">,</span> <span class="i">$gid</span><span class="cm">,</span></li><li> <span class="i">$gcos</span><span class="cm">,</span> <span class="i">$home</span><span class="cm">,</span> <span class="i">$shell</span><span class="s">)</span> = <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">/:/</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="c">#...</span></li><li> <span class="s">}</span></li></ol></pre><p>As with regular pattern matching, any capturing parentheses that are not<br>
matched in a <code class="inline"><a class="l_k" href="../functions/split.html">split()</a></code> will be set to <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> when returned:</p>
<pre class="verbatim"><ol><li> <span class="i">@fields</span> = <a class="l_k" href="../functions/split.html">split</a> <span class="q">/(A)|B/</span><span class="cm">,</span> <span class="q">"1A2B3"</span><span class="sc">;</span></li><li> <span class="c"># @fields is (1, 'A', 2, undef, 3)</span></li></ol><]]></desc>
</keyword>
<keyword name="sprintf" type="function">
<params>
<param name='format'/>
<param name='list'/>
</params>
<desc><![CDATA[Returns a string formatted by the usual <code class="inline"><a class="l_k" href="../functions/printf.html">printf</a></code> conventions of the C<br>
library function <code class="inline"><a class="l_k" href="../functions/sprintf.html">sprintf</a></code>. See below for more details<br>
and see <code class="inline"><a class="l_k" href="../functions/sprintf.html">sprintf(3)</a></code> or <code class="inline"><a class="l_k" href="../functions/printf.html">printf(3)</a></code> on your system for an explanation of<br>
the general principles.</p>
<p>For example:</p>
<pre class="verbatim"><ol><li> <span class="c"># Format number with up to 8 leading zeroes</span></li><li> <span class="i">$result</span> = <a class="l_k" href="../functions/sprintf.html">sprintf</a><span class="s">(</span><span class="q">"%08d"</span><span class="cm">,</span> <span class="i">$number</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <span class="c"># Round number to 3 digits after decimal point</span></li><li> <span class="i">$rounded</span> = <a class="l_k" href="../functions/sprintf.html">sprintf</a><span class="s">(</span><span class="q">"%.3f"</span><span class="cm">,</span> <span class="i">$number</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Perl does its own <code class="inline"><a class="l_k" href="../functions/sprintf.html">sprintf</a></code> formatting--it emulates the C<br>
function <code class="inline"><a class="l_k" href="../functions/sprintf.html">sprintf</a></code>, but it doesn't use it (except for floating-point<br>
numbers, and even then only the standard modifiers are allowed). As a<br>
result, any non-standard extensions in your local <code class="inline"><a class="l_k" href="../functions/sprintf.html">sprintf</a></code> are not<br>
available from Perl.</p>
<p>Unlike <code class="inline"><a class="l_k" href="../functions/printf.html">printf</a></code>, <code class="inline"><a class="l_k" href="../functions/sprintf.html">sprintf</a></code> does not do what you probably mean when you<br>
pass it an array as your first argument. The array is given scalar context,<br>
and instead of using the 0th element of the array as the format, Perl will<br>
use the count of elements in the array as the format, which is almost never<br>
useful.</p>
<p>Perl's <code class="inline"><a class="l_k" href="../functions/sprintf.html">sprintf</a></code> permits the following universally-known conversions:</p>
<pre class="verbatim"><ol><li> %% a percent sign</li><li> %c a character with the given number</li><li> %s a string</li><li> %d a signed integer, in decimal</li><li> %u an unsigned integer, in decimal</li><li> %o an unsigned integer, in octal</li><li> %x an unsigned integer, in hexadecimal</li><li> %e a floating-point number, in scientific notation</li><li> %f a floating-point number, in fixed decimal notation</li><li> %g a floating-point number, in %e or %f notation</li></ol></pre><p>In addition, Perl permits the following widely-supported conversions:</p>
<pre class="verbatim"><ol><li> %X like %x, but using upper-case letters</li><li> %E like %e, but using an upper-case "E"</li><li> %G like %g, but with an upper-case "E" (if applicable)</li><li> %b an unsigned integer, in binary</li><li> %B like %b, but using an upper-case "B" with the # flag</li><li> %p a pointer (outputs the Perl value's address in hexadecimal)</li><li> %n special: *stores* the number of characters output so far</li><li> into the next variable in the parameter list</li></ol></pre><p>Finally, for backward (and we do mean "backward") compatibility, Perl<br>
permits these unnecessary but widely-supported conversions:</p>
<pre class="verbatim"><ol><li> %i a synonym for %d</li><li> %D a synonym for %ld</li><li> %U a synonym for %lu</li><li> %O a synonym for %lo</li><li> %F a synonym for %f</li></ol></pre><p>Note that the number of exponent digits in the scientific notation produced<br>
by <code class="inline"><span class="i">%e</span></code>
, <code class="inline"><span class="i">%E</span></code>
, <code class="inline"><span class="i">%g</span></code>
and <code class="inline"><span class="i">%G</span></code>
for numbers with the modulus of the<br>
exponent less than 100 is system-dependent: it may be three or less<br>
(zero-padded as necessary). In other words, 1.23 times ten to the<br>
99th may be either "1.23e99" or "1.23e099".</p>
<p>Between the <code class="inline"><span class="i">%</span></code>
and the format letter, you may specify a number of<br>
additional attributes controlling the interpretation of the format.<br>
In order, these are:</p>
<ul>
<li><a name="format-parameter-index"></a><b>format parameter index</b>
<p>An explicit format parameter index, such as <code class="inline">2$</code>. By default sprintf<br>
will format the next unused argument in the list, but this allows you<br>
to take the arguments out of order, e.g.:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'%2$d %1$d'</span><span class="cm">,</span> <span class="n">12</span><span class="cm">,</span> <span class="n">34</span><span class="sc">;</span> <span class="c"># prints "34 12"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'%3$d %d %1$d'</span><span class="cm">,</span> <span class="n">1</span><span class="cm">,</span> <span class="n">2</span><span class="cm">,</span> <span class="n">3</span><span class="sc">;</span> <span class="c"># prints "3 1 1"</span></li></ol></pre></li>
<li><a name="flags"></a><b>flags</b>
<p>one or more of:</p>
<pre class="verbatim"><ol><li> space prefix non-negative number with a space</li><li> + prefix non-negative number with a plus sign</li><li> - left-justify within the field</li><li> 0 use zeros, not spaces, to right-justify</li><li> # ensure the leading "0" for any octal,</li><li> prefix non-zero hexadecimal with "0x" or "0X",</li><li> prefix non-zero binary with "0b" or "0B"</li></ol></pre><p>For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<% d>'</span><span class="cm">,</span> <span class="n">12</span><span class="sc">;</span> <span class="c"># prints "< 12>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%+d>'</span><span class="cm">,</span> <span class="n">12</span><span class="sc">;</span> <span class="c"># prints "<+12>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%6s>'</span><span class="cm">,</span> <span class="n">12</span><span class="sc">;</span> <span class="c"># prints "< 12>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%-6s>'</span><span class="cm">,</span> <span class="n">12</span><span class="sc">;</span> <span class="c"># prints "<12 >"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%06s>'</span><span class="cm">,</span> <span class="n">12</span><span class="sc">;</span> <span class="c"># prints "<000012>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%#o>'</span><span class="cm">,</span> <span class="n">12</span><span class="sc">;</span> <span class="c"># prints "<014>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%#x>'</span><span class="cm">,</span> <span class="n">12</span><span class="sc">;</span> <span class="c"># prints "<0xc>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%#X>'</span><span class="cm">,</span> <span class="n">12</span><span class="sc">;</span> <span class="c"># prints "<0XC>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%#b>'</span><span class="cm">,</span> <span class="n">12</span><span class="sc">;</span> <span class="c"># prints "<0b1100>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%#B>'</span><span class="cm">,</span> <span class="n">12</span><span class="sc">;</span> <span class="c"># prints "<0B1100>"</span></li></ol></pre><p>When a space and a plus sign are given as the flags at once,<br>
a plus sign is used to prefix a positive number.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%+ d>'</span><span class="cm">,</span> <span class="n">12</span><span class="sc">;</span> <span class="c"># prints "<+12>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<% +d>'</span><span class="cm">,</span> <span class="n">12</span><span class="sc">;</span> <span class="c"># prints "<+12>"</span></li></ol></pre><p>When the # flag and a precision are given in the %o conversion,<br>
the precision is incremented if it's necessary for the leading "0".</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%#.5o>'</span><span class="cm">,</span> <span class="n">012</span><span class="sc">;</span> <span class="c"># prints "<00012>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%#.5o>'</span><span class="cm">,</span> <span class="n">012345</span><span class="sc">;</span> <span class="c"># prints "<012345>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%#.0o>'</span><span class="cm">,</span> <span class="n">0</span><span class="sc">;</span> <span class="c"># prints "<0>"</span></li></ol></pre></li>
<li><a name="vector-flag"></a><b>vector flag</b>
<p>This flag tells perl to interpret the supplied string as a vector of<br>
integers, one for each character in the string. Perl applies the format to<br>
each integer in turn, then joins the resulting strings with a separator (a<br>
dot <code class="inline">.</code> by default). This can be useful for displaying ordinal values of<br>
characters in arbitrary strings:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"%vd"</span><span class="cm">,</span> <span class="q">"AB\x{100}"</span><span class="sc">;</span> <span class="c"># prints "65.66.256"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"version is v%vd\n"</span><span class="cm">,</span> <span class="i">$^V</span><span class="sc">;</span> <span class="c"># Perl's version</span></li></ol></pre><p>Put an asterisk <code class="inline"><span class="i">*</span></code>
before the <code class="inline"><span class="w">v</span></code>
to override the string to<br>
use to separate the numbers:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"address is %*vX\n"</span><span class="cm">,</span> <span class="q">":"</span><span class="cm">,</span> <span class="i">$addr</span><span class="sc">;</span> <span class="c"># IPv6 address</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"bits are %0*v8b\n"</span><span class="cm">,</span> <span class="q">" "</span><span class="cm">,</span> <span class="i">$bits</span><span class="sc">;</span> <span class="c"># random bitstring</span></li></ol></pre><p>You can also explicitly specify the argument number to use for<br>
the join string using e.g. <code class="inline">*2$v</code>:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'%*4$vX %*4$vX %*4$vX'</span><span class="cm">,</span> <span class="i">@addr</span>[<span class="n">1</span>..<span class="n">3</span>]<span class="cm">,</span> <span class="q">":"</span><span class="sc">;</span> <span class="c"># 3 IPv6 addresses</span></li></ol></pre></li>
<li><a name="(minimum)-width"></a><b>(minimum) width</b>
<p>Arguments are usually formatted to be only as wide as required to<br>
display the given value. You can override the width by putting<br>
a number here, or get the width from the next argument (with <code class="inline"><span class="i">*</span></code>
)<br>
or from a specified argument (with e.g. <code class="inline">*2$</code>):</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%s>'</span><span class="cm">,</span> <span class="q">"a"</span><span class="sc">;</span> <span class="c"># prints "<a>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%6s>'</span><span class="cm">,</span> <span class="q">"a"</span><span class="sc">;</span> <span class="c"># prints "< a>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%*s>'</span><span class="cm">,</span> <span class="n">6</span><span class="cm">,</span> <span class="q">"a"</span><span class="sc">;</span> <span class="c"># prints "< a>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%*2$s>'</span><span class="cm">,</span> <span class="q">"a"</span><span class="cm">,</span> <span class="n">6</span><span class="sc">;</span> <span class="c"># prints "< a>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%2s>'</span><span class="cm">,</span> <span class="q">"long"</span><span class="sc">;</span> <span class="c"># prints "<long>" (does not truncate)</span></li></ol></pre><p>If a field width obtained through <code class="inline"><span class="i">*</span></code>
is negative, it has the same<br>
effect as the <code class="inline">-</code>
flag: left-justification.</p>
</li>
<li><a name="precision%2c-or-maximum-width"></a><b>precision, or maximum width<br>
</b>
<p>You can specify a precision (for numeric conversions) or a maximum<br>
width (for string conversions) by specifying a <code class="inline">.</code> followed by a number.<br>
For floating point formats, with the exception of 'g' and 'G', this specifies<br>
the number of decimal places to show (the default being 6), e.g.:</p>
<pre class="verbatim"><ol><li> <span class="c"># these examples are subject to system-specific variation</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%f>'</span><span class="cm">,</span> <span class="n">1</span><span class="sc">;</span> <span class="c"># prints "<1.000000>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%.1f>'</span><span class="cm">,</span> <span class="n">1</span><span class="sc">;</span> <span class="c"># prints "<1.0>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%.0f>'</span><span class="cm">,</span> <span class="n">1</span><span class="sc">;</span> <span class="c"># prints "<1>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%e>'</span><span class="cm">,</span> <span class="n">10</span><span class="sc">;</span> <span class="c"># prints "<1.000000e+01>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%.1e>'</span><span class="cm">,</span> <span class="n">10</span><span class="sc">;</span> <span class="c"># prints "<1.0e+01>"</span></li></ol></pre><p>For 'g' and 'G', this specifies the maximum number of digits to show,<br>
including prior to the decimal point as well as after it, e.g.:</p>
<pre class="verbatim"><ol><li> <span class="c"># these examples are subject to system-specific variation</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%g>'</span><span class="cm">,</span> <span class="n">1</span><span class="sc">;</span> <span class="c"># prints "<1>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%.10g>'</span><span class="cm">,</span> <span class="n">1</span><span class="sc">;</span> <span class="c"># prints "<1>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%g>'</span><span class="cm">,</span> <span class="n">100</span><span class="sc">;</span> <span class="c"># prints "<100>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%.1g>'</span><span class="cm">,</span> <span class="n">100</span><span class="sc">;</span> <span class="c"># prints "<1e+02>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%.2g>'</span><span class="cm">,</span> <span class="n">100.01</span><span class="sc">;</span> <span class="c"># prints "<1e+02>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%.5g>'</span><span class="cm">,</span> <span class="n">100.01</span><span class="sc">;</span> <span class="c"># prints "<100.01>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%.4g>'</span><span class="cm">,</span> <span class="n">100.01</span><span class="sc">;</span> <span class="c"># prints "<100>"</span></li></ol></pre><p>For integer conversions, specifying a precision implies that the<br>
output of the number itself should be zero-padded to this width,<br>
where the 0 flag is ignored:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%.6d>'</span><span class="cm">,</span> <span class="n">1</span><span class="sc">;</span> <span class="c"># prints "<000001>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%+.6d>'</span><span class="cm">,</span> <span class="n">1</span><span class="sc">;</span> <span class="c"># prints "<+000001>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%-10.6d>'</span><span class="cm">,</span> <span class="n">1</span><span class="sc">;</span> <span class="c"># prints "<000001 >"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%10.6d>'</span><span class="cm">,</span> <span class="n">1</span><span class="sc">;</span> <span class="c"># prints "< 000001>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%010.6d>'</span><span class="cm">,</span> <span class="n">1</span><span class="sc">;</span> <span class="c"># prints "< 000001>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%+10.6d>'</span><span class="cm">,</span> <span class="n">1</span><span class="sc">;</span> <span class="c"># prints "< +000001>"</span></li><li></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%.6x>'</span><span class="cm">,</span> <span class="n">1</span><span class="sc">;</span> <span class="c"># prints "<000001>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%#.6x>'</span><span class="cm">,</span> <span class="n">1</span><span class="sc">;</span> <span class="c"># prints "<0x000001>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%-10.6x>'</span><span class="cm">,</span> <span class="n">1</span><span class="sc">;</span> <span class="c"># prints "<000001 >"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%10.6x>'</span><span class="cm">,</span> <span class="n">1</span><span class="sc">;</span> <span class="c"># prints "< 000001>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%010.6x>'</span><span class="cm">,</span> <span class="n">1</span><span class="sc">;</span> <span class="c"># prints "< 000001>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%#10.6x>'</span><span class="cm">,</span> <span class="n">1</span><span class="sc">;</span> <span class="c"># prints "< 0x000001>"</span></li></ol></pre><p>For string conversions, specifying a precision truncates the string<br>
to fit in the specified width:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%.5s>'</span><span class="cm">,</span> <span class="q">"truncated"</span><span class="sc">;</span> <span class="c"># prints "<trunc>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%10.5s>'</span><span class="cm">,</span> <span class="q">"truncated"</span><span class="sc">;</span> <span class="c"># prints "< trunc>"</span></li></ol></pre><p>You can also get the precision from the next argument using <code class="inline">.*</code>:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%.6x>'</span><span class="cm">,</span> <span class="n">1</span><span class="sc">;</span> <span class="c"># prints "<000001>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%.*x>'</span><span class="cm">,</span> <span class="n">6</span><span class="cm">,</span> <span class="n">1</span><span class="sc">;</span> <span class="c"># prints "<000001>"</span></li></ol></pre><p>If a precision obtained through <code class="inline"><span class="i">*</span></code>
is negative, it has the same<br>
effect as no precision.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%.*s>'</span><span class="cm">,</span> <span class="n">7</span><span class="cm">,</span> <span class="q">"string"</span><span class="sc">;</span> <span class="c"># prints "<string>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%.*s>'</span><span class="cm">,</span> <span class="n">3</span><span class="cm">,</span> <span class="q">"string"</span><span class="sc">;</span> <span class="c"># prints "<str>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%.*s>'</span><span class="cm">,</span> <span class="n">0</span><span class="cm">,</span> <span class="q">"string"</span><span class="sc">;</span> <span class="c"># prints "<>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%.*s>'</span><span class="cm">,</span> <span class="n">-1</span><span class="cm">,</span> <span class="q">"string"</span><span class="sc">;</span> <span class="c"># prints "<string>"</span></li><li></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%.*d>'</span><span class="cm">,</span> <span class="n">1</span><span class="cm">,</span> <span class="n">0</span><span class="sc">;</span> <span class="c"># prints "<0>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%.*d>'</span><span class="cm">,</span> <span class="n">0</span><span class="cm">,</span> <span class="n">0</span><span class="sc">;</span> <span class="c"># prints "<>"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%.*d>'</span><span class="cm">,</span> <span class="n">-1</span><span class="cm">,</span> <span class="n">0</span><span class="sc">;</span> <span class="c"># prints "<0>"</span></li></ol></pre><p>You cannot currently get the precision from a specified number,<br>
but it is intended that this will be possible in the future using<br>
e.g. <code class="inline">.*2$</code>:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%.*2$x>'</span><span class="cm">,</span> <span class="n">1</span><span class="cm">,</span> <span class="n">6</span><span class="sc">;</span> <span class="c"># INVALID, but in future will print "<000001>"</span></li></ol></pre></li>
<li><a name="size"></a><b>size</b>
<p>For numeric conversions, you can specify the size to interpret the<br>
number as using <code class="inline"><span class="w">l</span></code>
, <code class="inline"><span class="w">h</span></code>
, <code class="inline"><span class="w">V</span></code>
, <code class="inline"><a class="l_k" href="../functions/q.html">q</a></code>, <code class="inline"><span class="w">L</span></code>
, or <code class="inline"><span class="w">ll</span></code>
. For integer<br>
conversions (<code class="inline"><span class="w">d</span> <span class="w">u</span> <span class="w">o</span> <span class="w">x</span> <span class="w">X</span> <span class="w">b</span> <span class="w">i</span> <span class="w">D</span> <span class="w">U</span> <span class="w">O</span></code>
), numbers are usually assumed to be<br>
whatever the default integer size is on your platform (usually 32 or 64<br>
bits), but you can override this to use instead one of the standard C types,<br>
as supported by the compiler used to build Perl:</p>
<pre class="verbatim"><ol><li> l interpret integer as C type "long" or "unsigned long"</li><li> h interpret integer as C type "short" or "unsigned short"</li><li> q, L or ll interpret integer as C type "long long", "unsigned long long".</li><li> or "quads" (typically 64-bit integers)</li></ol></pre><p>The last will produce errors if Perl does not understand "quads" in your<br>
installation. (This requires that either the platform natively supports quads<br>
or Perl was specifically compiled to support quads.) You can find out<br>
whether your Perl supports quads via <a href="../Config.html">Config</a>:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Config</span><span class="sc">;</span></li><li> <span class="s">(</span><span class="i">$Config</span>{<span class="w">use64bitint</span>} eq <span class="q">'define'</span> || <span class="i">$Config</span>{<span class="w">longsize</span>} >= <span class="n">8</span><span class="s">)</span> &&</li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"quads\n"</span><span class="sc">;</span></li></ol></pre><p>For floating point conversions (<code class="inline"><span class="w">e</span> <span class="w">f</span> <span class="w">g</span> <span class="w">E</span> <span class="w">F</span> <span class="w">G</span></code>
), numbers are usually assumed<br>
to be the default floating point size on your platform (double or long double),<br>
but you can force 'long double' with <code class="inline"><a class="l_k" href="../functions/q.html">q</a></code>, <code class="inline"><span class="w">L</span></code>
, or <code class="inline"><span class="w">ll</span></code>
if your<br>
platform supports them. You can find out whether your Perl supports long<br>
doubles via <a href="../Config.html">Config</a>:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Config</span><span class="sc">;</span></li><li> <span class="i">$Config</span>{<span class="w">d_longdbl</span>} eq <span class="q">'define'</span> && <a class="l_k" href="../functions/print.html">print</a> <span class="q">"long doubles\n"</span><span class="sc">;</span></li></ol></pre><p>You can find out whether Perl considers 'long double' to be the default<br>
floating point size to use on your platform via <a href="../Config.html">Config</a>:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Config</span><span class="sc">;</span></li><li> <span class="s">(</span><span class="i">$Config</span>{<span class="w">uselongdouble</span>} eq <span class="q">'define'</span><span class="s">)</span> &&</li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"long doubles by default\n"</span><span class="sc">;</span></li></ol></pre><p>It can also be the case that long doubles and doubles are the same thing:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Config</span><span class="sc">;</span></li><li> <span class="s">(</span><span class="i">$Config</span>{<span class="w">doublesize</span>} == <span class="i">$Config</span>{<span class="w">longdblsize</span>}<span class="s">)</span> &&</li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"doubles are long doubles\n"</span><span class="sc">;</span></li></ol></pre><p>The size specifier <code class="inline"><span class="w">V</span></code>
has no effect for Perl code, but it is supported<br>
for compatibility with XS code; it means 'use the standard size for<br>
a Perl integer (or floating-point number)', which is already the<br>
default for Perl code.</p>
</li>
<li><a name="order-of-arguments"></a><b>order of arguments</b>
<p>Normally, sprintf takes the next unused argument as the value to<br>
format for each format specification. If the format specification<br>
uses <code class="inline"><span class="i">*</span></code>
to require additional arguments, these are consumed from<br>
the argument list in the order in which they appear in the format<br>
specification <i>before</i> the value to format. Where an argument is<br>
specified using an explicit index, this does not affect the normal<br>
order for the arguments (even when the explicitly specified index<br>
would have been the next argument in any case).</p>
<p>So:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%*.*s>'</span><span class="cm">,</span> <span class="i">$a</span><span class="cm">,</span> <span class="i">$b</span><span class="cm">,</span> <span class="i">$c</span><span class="sc">;</span></li></ol></pre><p>would use <code class="inline"><span class="i">$a</span></code>
for the width, <code class="inline"><span class="i">$b</span></code>
for the precision and <code class="inline"><span class="i">$c</span></code>
<br>
as the value to format, while:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">'<%*1$.*s>'</span><span class="cm">,</span> <span class="i">$a</span><span class="cm">,</span> <span class="i">$b</span><span class="sc">;</span></li></ol></pre><p>would use <code class="inline"><span class="i">$a</span></code>
for the width and the precision, and <code class="inline"><span class="i">$b</span></code>
as the<br>
value to format.</p>
<p>Here are some more examples - beware that when using an explicit<br>
index, the <code class="inline"><span class="i">$</span></code>
may need to be escaped:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"%2\$d %d\n"</span><span class="cm">,</span> <span class="n">12</span><span class="cm">,</span> <span class="n">34</span><span class="sc">;</span> <span class="c"># will print "34 12\n"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"%2\$d %d %d\n"</span><span class="cm">,</span> <span class="n">12</span><span class="cm">,</span> <span class="n">34</span><span class="sc">;</span> <span class="c"># will print "34 12 34\n"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"%3\$d %d %d\n"</span><span class="cm">,</span> <span class="n">12</span><span class="cm">,</span> <span class="n">34</span><span class="cm">,</span> <span class="n">56</span><span class="sc">;</span> <span class="c"># will print "56 12 34\n"</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"%2\$*3\$d %d\n"</span><span class="cm">,</span> <span class="n">12</span><span class="cm">,</span> <span class="n">34</span><span class="cm">,</span> <span class="n">3</span><span class="sc">;</span> <span class="c"># will print " 34 12\n"</span></li></ol><]]></desc>
</keyword>
<keyword name="sqrt" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Return the square root of EXPR. If EXPR is omitted, returns square<br>
root of <code class="inline"><span class="i">$_</span></code>
. Only works on non-negative operands, unless you've<br>
loaded the standard Math::Complex module.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Math::Complex</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/sqrt.html">sqrt</a><span class="s">(</span><span class="n">-2</span><span class="s">)</span><span class="sc">;</span> <span class="c"># prints 1.4142135623731i</span></li></ol><]]></desc>
</keyword>
<keyword name="sqrt" type="function">
<params>
</params>
<desc><![CDATA[Return the square root of EXPR. If EXPR is omitted, returns square<br>
root of <code class="inline"><span class="i">$_</span></code>
. Only works on non-negative operands, unless you've<br>
loaded the standard Math::Complex module.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Math::Complex</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/sqrt.html">sqrt</a><span class="s">(</span><span class="n">-2</span><span class="s">)</span><span class="sc">;</span> <span class="c"># prints 1.4142135623731i</span></li></ol><]]></desc>
</keyword>
<keyword name="srand" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Sets the random number seed for the <code class="inline"><a class="l_k" href="../functions/rand.html">rand</a></code> operator.</p>
<p>The point of the function is to "seed" the <code class="inline"><a class="l_k" href="../functions/rand.html">rand</a></code> function so that<br>
<code class="inline"><a class="l_k" href="../functions/rand.html">rand</a></code> can produce a different sequence each time you run your<br>
program.</p>
<p>If srand() is not called explicitly, it is called implicitly at the<br>
first use of the <code class="inline"><a class="l_k" href="../functions/rand.html">rand</a></code> operator. However, this was not the case in<br>
versions of Perl before 5.004, so if your script will run under older<br>
Perl versions, it should call <code class="inline"><a class="l_k" href="../functions/srand.html">srand</a></code>.</p>
<p>Most programs won't even call srand() at all, except those that<br>
need a cryptographically-strong starting point rather than the<br>
generally acceptable default, which is based on time of day,<br>
process ID, and memory allocation, or the <i>/dev/urandom</i> device,<br>
if available.</p>
<p>You can call srand($seed) with the same $seed to reproduce the<br>
<i>same</i> sequence from rand(), but this is usually reserved for<br>
generating predictable results for testing or debugging.<br>
Otherwise, don't call srand() more than once in your program.</p>
<p>Do <b>not</b> call srand() (i.e. without an argument) more than once in<br>
a script. The internal state of the random number generator should<br>
contain more entropy than can be provided by any seed, so calling<br>
srand() again actually <i>loses</i> randomness.</p>
<p>Most implementations of <code class="inline"><a class="l_k" href="../functions/srand.html">srand</a></code> take an integer and will silently<br>
truncate decimal numbers. This means <code class="inline"><a class="l_k" href="../functions/srand.html">srand(42)</a></code> will usually<br>
produce the same results as <code class="inline"><a class="l_k" href="../functions/srand.html">srand(42.1)</a></code>. To be safe, always pass<br>
<code class="inline"><a class="l_k" href="../functions/srand.html">srand</a></code> an integer.</p>
<p>In versions of Perl prior to 5.004 the default seed was just the<br>
current <code class="inline"><a class="l_k" href="../functions/time.html">time</a></code>. This isn't a particularly good seed, so many old<br>
programs supply their own seed value (often <code class="inline"><a class="l_k" href="../functions/time.html">time</a> ^ <span class="i">$$</span></code>
or <code class="inline"><a class="l_k" href="../functions/time.html">time</a> ^<br>
<span class="s">(</span><span class="i">$$</span> + <span class="s">(</span><span class="i">$$</span> << <span class="n">15</span><span class="s">)</span><span class="s">)</span></code>
), but that isn't necessary any more.</p>
<p>For cryptographic purposes, however, you need something much more random <br>
than the default seed. Checksumming the compressed output of one or more<br>
rapidly changing operating system status programs is the usual method. For<br>
example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/srand.html">srand</a> <span class="s">(</span><a class="l_k" href="../functions/time.html">time</a> ^ <span class="i">$$</span> ^ <a class="l_k" href="../functions/unpack.html">unpack</a> <span class="q">"%L*"</span><span class="cm">,</span> <span class="q">`ps axww | gzip -f`</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>If you're particularly concerned with this, see the <code class="inline"><span class="w">Math::TrulyRandom</span></code>
<br>
module in CPAN.</p>
<p>Frequently called programs (like CGI scripts) that simply use</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/time.html">time</a> ^ <span class="i">$$</span></li></ol></pre><p>for a seed can fall prey to the mathematical property that</p>
<pre class="verbatim"><ol><li> <span class="w">a</span>^<span class="w">b</span> == <span class="s">(</span><span class="w">a</span>+<span class="n">1</span><span class="s">)</span>^<span class="s">(</span><span class="w">b</span>+<span class="n">1</span><span class="s">)</span></li></ol></pre><p>one-third of the time. So don't do that.]]></desc>
</keyword>
<keyword name="srand" type="function">
<params>
</params>
<desc><![CDATA[Sets the random number seed for the <code class="inline"><a class="l_k" href="../functions/rand.html">rand</a></code> operator.</p>
<p>The point of the function is to "seed" the <code class="inline"><a class="l_k" href="../functions/rand.html">rand</a></code> function so that<br>
<code class="inline"><a class="l_k" href="../functions/rand.html">rand</a></code> can produce a different sequence each time you run your<br>
program.</p>
<p>If srand() is not called explicitly, it is called implicitly at the<br>
first use of the <code class="inline"><a class="l_k" href="../functions/rand.html">rand</a></code> operator. However, this was not the case in<br>
versions of Perl before 5.004, so if your script will run under older<br>
Perl versions, it should call <code class="inline"><a class="l_k" href="../functions/srand.html">srand</a></code>.</p>
<p>Most programs won't even call srand() at all, except those that<br>
need a cryptographically-strong starting point rather than the<br>
generally acceptable default, which is based on time of day,<br>
process ID, and memory allocation, or the <i>/dev/urandom</i> device,<br>
if available.</p>
<p>You can call srand($seed) with the same $seed to reproduce the<br>
<i>same</i> sequence from rand(), but this is usually reserved for<br>
generating predictable results for testing or debugging.<br>
Otherwise, don't call srand() more than once in your program.</p>
<p>Do <b>not</b> call srand() (i.e. without an argument) more than once in<br>
a script. The internal state of the random number generator should<br>
contain more entropy than can be provided by any seed, so calling<br>
srand() again actually <i>loses</i> randomness.</p>
<p>Most implementations of <code class="inline"><a class="l_k" href="../functions/srand.html">srand</a></code> take an integer and will silently<br>
truncate decimal numbers. This means <code class="inline"><a class="l_k" href="../functions/srand.html">srand(42)</a></code> will usually<br>
produce the same results as <code class="inline"><a class="l_k" href="../functions/srand.html">srand(42.1)</a></code>. To be safe, always pass<br>
<code class="inline"><a class="l_k" href="../functions/srand.html">srand</a></code> an integer.</p>
<p>In versions of Perl prior to 5.004 the default seed was just the<br>
current <code class="inline"><a class="l_k" href="../functions/time.html">time</a></code>. This isn't a particularly good seed, so many old<br>
programs supply their own seed value (often <code class="inline"><a class="l_k" href="../functions/time.html">time</a> ^ <span class="i">$$</span></code>
or <code class="inline"><a class="l_k" href="../functions/time.html">time</a> ^<br>
<span class="s">(</span><span class="i">$$</span> + <span class="s">(</span><span class="i">$$</span> << <span class="n">15</span><span class="s">)</span><span class="s">)</span></code>
), but that isn't necessary any more.</p>
<p>For cryptographic purposes, however, you need something much more random <br>
than the default seed. Checksumming the compressed output of one or more<br>
rapidly changing operating system status programs is the usual method. For<br>
example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/srand.html">srand</a> <span class="s">(</span><a class="l_k" href="../functions/time.html">time</a> ^ <span class="i">$$</span> ^ <a class="l_k" href="../functions/unpack.html">unpack</a> <span class="q">"%L*"</span><span class="cm">,</span> <span class="q">`ps axww | gzip -f`</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>If you're particularly concerned with this, see the <code class="inline"><span class="w">Math::TrulyRandom</span></code>
<br>
module in CPAN.</p>
<p>Frequently called programs (like CGI scripts) that simply use</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/time.html">time</a> ^ <span class="i">$$</span></li></ol></pre><p>for a seed can fall prey to the mathematical property that</p>
<pre class="verbatim"><ol><li> <span class="w">a</span>^<span class="w">b</span> == <span class="s">(</span><span class="w">a</span>+<span class="n">1</span><span class="s">)</span>^<span class="s">(</span><span class="w">b</span>+<span class="n">1</span><span class="s">)</span></li></ol></pre><p>one-third of the time. So don't do that.]]></desc>
</keyword>
<keyword name="stat" type="function">
<params>
<param name='dirhandle'/>
</params>
<desc><![CDATA[Returns a 13-element list giving the status info for a file, either<br>
the file opened via FILEHANDLE or DIRHANDLE, or named by EXPR. If EXPR is <br>
omitted, it stats <code class="inline"><span class="i">$_</span></code>
. Returns a null list if the stat fails. Typically<br>
used as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$dev</span><span class="cm">,</span><span class="i">$ino</span><span class="cm">,</span><span class="i">$mode</span><span class="cm">,</span><span class="i">$nlink</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$rdev</span><span class="cm">,</span><span class="i">$size</span><span class="cm">,</span></li><li> <span class="i">$atime</span><span class="cm">,</span><span class="i">$mtime</span><span class="cm">,</span><span class="i">$ctime</span><span class="cm">,</span><span class="i">$blksize</span><span class="cm">,</span><span class="i">$blocks</span><span class="s">)</span></li><li> = <a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Not all fields are supported on all filesystem types. Here are the<br>
meanings of the fields:</p>
<pre class="verbatim"><ol><li> 0 dev device number of filesystem</li><li> 1 ino inode number</li><li> 2 mode file mode (type and permissions)</li><li> 3 nlink number of (hard) links to the file</li><li> 4 uid numeric user ID of file's owner</li><li> 5 gid numeric group ID of file's owner</li><li> 6 rdev the device identifier (special files only)</li><li> 7 size total size of file, in bytes</li><li> 8 atime last access time in seconds since the epoch</li><li> 9 mtime last modify time in seconds since the epoch</li><li> 10 ctime inode change time in seconds since the epoch (*)</li><li> 11 blksize preferred block size for file system I/O</li><li> 12 blocks actual number of blocks allocated</li></ol></pre><p>(The epoch was at 00:00 January 1, 1970 GMT.)</p>
<p>(*) Not all fields are supported on all filesystem types. Notably, the<br>
ctime field is non-portable. In particular, you cannot expect it to be a<br>
"creation time", see <a href="../perlport.html#Files-and-Filesystems">"Files and Filesystems" in perlport</a> for details.</p>
<p>If <code class="inline"><a class="l_k" href="../functions/stat.html">stat</a></code> is passed the special filehandle consisting of an underline, no<br>
stat is done, but the current contents of the stat structure from the<br>
last <code class="inline"><a class="l_k" href="../functions/stat.html">stat</a></code>, <code class="inline"><a class="l_k" href="../functions/lstat.html">lstat</a></code>, or filetest are returned. Example:</p>
<pre class="verbatim"><ol><li> if <span class="s">(</span>-x <span class="i">$file</span> && <span class="s">(</span><span class="s">(</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="w">_</span><span class="s">)</span><span class="s">)</span> && <span class="i">$d</span> < <span class="n">0</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"$file is executable NFS file\n"</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>(This works on machines only for which the device number is negative<br>
under NFS.)</p>
<p>Because the mode contains both the file type and its permissions, you<br>
should mask off the file type portion and (s)printf using a <code class="inline"><span class="q">"%o"</span></code>
<br>
if you want to see the real permissions.</p>
<pre class="verbatim"><ol><li> <span class="i">$mode</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="s">)</span>[<span class="n">2</span>]<span class="sc">;</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"Permissions are %04o\n"</span><span class="cm">,</span> <span class="i">$mode</span> & <span class="n">07777</span><span class="sc">;</span></li></ol></pre><p>In scalar context, <code class="inline"><a class="l_k" href="../functions/stat.html">stat</a></code> returns a boolean value indicating success<br>
or failure, and, if successful, sets the information associated with<br>
the special filehandle <code class="inline"><span class="w">_</span></code>
.</p>
<p>The <a href="../File/stat.html">File::stat</a> module provides a convenient, by-name access mechanism:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <span class="i">$sb</span> = <a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"File is %s, size is %s, perm %04o, mtime %s\n"</span><span class="cm">,</span></li><li> <span class="i">$filename</span><span class="cm">,</span> <span class="i">$sb</span><span class="i">->size</span><span class="cm">,</span> <span class="i">$sb</span><span class="i">->mode</span> & <span class="n">07777</span><span class="cm">,</span></li><li> <a class="l_k" href="../functions/scalar.html">scalar</a> <a class="l_k" href="../functions/localtime.html">localtime</a> <span class="i">$sb</span><span class="i">->mtime</span><span class="sc">;</span></li></ol></pre><p>You can import symbolic mode constants (<code class="inline"><span class="w">S_IF</span>*</code>
) and functions<br>
(<code class="inline"><span class="w">S_IS</span>*</code>
) from the Fcntl module:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Fcntl</span> <span class="q">':mode'</span><span class="sc">;</span></li><li></li><li> <span class="i">$mode</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="s">)</span>[<span class="n">2</span>]<span class="sc">;</span></li><li></li><li> <span class="i">$user_rwx</span> = <span class="s">(</span><span class="i">$mode</span> & <span class="w">S_IRWXU</span><span class="s">)</span> >> <span class="n">6</span><span class="sc">;</span></li><li> <span class="i">$group_read</span> = <span class="s">(</span><span class="i">$mode</span> & <span class="w">S_IRGRP</span><span class="s">)</span> >> <span class="n">3</span><span class="sc">;</span></li><li> <span class="i">$other_execute</span> = <span class="i">$mode</span> & <span class="w">S_IXOTH</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"Permissions are %04o\n"</span><span class="cm">,</span> <span class="i">S_IMODE</span><span class="s">(</span><span class="i">$mode</span><span class="s">)</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li><li></li><li> <span class="i">$is_setuid</span> = <span class="i">$mode</span> & <span class="w">S_ISUID</span><span class="sc">;</span></li><li> <span class="i">$is_directory</span> = <span class="i">S_ISDIR</span><span class="s">(</span><span class="i">$mode</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>You could write the last two using the <code class="inline">-u</code>
and <code class="inline">-d</code>
operators.<br>
The commonly available <code class="inline"><span class="w">S_IF</span>*</code>
constants are</p>
<pre class="verbatim"><ol><li> <span class="c"># Permissions: read, write, execute, for user, group, others.</span></li><li></li><li> <span class="w">S_IRWXU</span> <span class="w">S_IRUSR</span> <span class="w">S_IWUSR</span> <span class="w">S_IXUSR</span></li><li> <span class="w">S_IRWXG</span> <span class="w">S_IRGRP</span> <span class="w">S_IWGRP</span> <span class="w">S_IXGRP</span></li><li> <span class="w">S_IRWXO</span> <span class="w">S_IROTH</span> <span class="w">S_IWOTH</span> <span class="w">S_IXOTH</span></li><li></li><li> <span class="c"># Setuid/Setgid/Stickiness/SaveText.</span></li><li> <span class="c"># Note that the exact meaning of these is system dependent.</span></li><li></li><li> <span class="w">S_ISUID</span> <span class="w">S_ISGID</span> <span class="w">S_ISVTX</span> <span class="w">S_ISTXT</span></li><li></li><li> <span class="c"># File types. Not necessarily all are available on your system.</span></li><li></li><li> <span class="w">S_IFREG</span> <span class="w">S_IFDIR</span> <span class="w">S_IFLNK</span> <span class="w">S_IFBLK</span> <span class="w">S_IFCHR</span> <span class="w">S_IFIFO</span> <span class="w">S_IFSOCK</span> <span class="w">S_IFWHT</span> <span class="w">S_ENFMT</span></li><li></li><li> <span class="c"># The following are compatibility aliases for S_IRUSR, S_IWUSR, S_IXUSR.</span></li><li></li><li> <span class="w">S_IREAD</span> <span class="w">S_IWRITE</span> <span class="w">S_IEXEC</span></li></ol></pre><p>and the <code class="inline"><span class="w">S_IF</span>*</code>
functions are</p>
<pre class="verbatim"><ol><li> S_IMODE($mode) the part of $mode containing the permission bits</li><li> and the setuid/setgid/sticky bits</li><li></li><li> S_IFMT($mode) the part of $mode containing the file type</li><li> which can be bit-anded with e.g. S_IFREG</li><li> or with the following functions</li><li></li><li> # The operators -f, -d, -l, -b, -c, -p, and -S.</li><li></li><li> S_ISREG($mode) S_ISDIR($mode) S_ISLNK($mode)</li><li> S_ISBLK($mode) S_ISCHR($mode) S_ISFIFO($mode) S_ISSOCK($mode)</li><li></li><li> # No direct -X operator counterpart, but for the first one</li><li> # the -g operator is often equivalent. The ENFMT stands for</li><li> # record flocking enforcement, a platform-dependent feature.</li><li></li><li> S_ISENFMT($mode) S_ISWHT($mode)</li></ol></pre><p>See your native chmod(2) and stat(2) documentation for more details<br>
about the <code class="inline"><span class="w">S_</span>*</code>
constants. To get status info for a symbolic link<br>
instead of the target file behind the link, use the <code class="inline"><a class="l_k" href="../functions/lstat.html">lstat</a></code> function.]]></desc>
</keyword>
<keyword name="stat" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Returns a 13-element list giving the status info for a file, either<br>
the file opened via FILEHANDLE or DIRHANDLE, or named by EXPR. If EXPR is <br>
omitted, it stats <code class="inline"><span class="i">$_</span></code>
. Returns a null list if the stat fails. Typically<br>
used as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$dev</span><span class="cm">,</span><span class="i">$ino</span><span class="cm">,</span><span class="i">$mode</span><span class="cm">,</span><span class="i">$nlink</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$rdev</span><span class="cm">,</span><span class="i">$size</span><span class="cm">,</span></li><li> <span class="i">$atime</span><span class="cm">,</span><span class="i">$mtime</span><span class="cm">,</span><span class="i">$ctime</span><span class="cm">,</span><span class="i">$blksize</span><span class="cm">,</span><span class="i">$blocks</span><span class="s">)</span></li><li> = <a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Not all fields are supported on all filesystem types. Here are the<br>
meanings of the fields:</p>
<pre class="verbatim"><ol><li> 0 dev device number of filesystem</li><li> 1 ino inode number</li><li> 2 mode file mode (type and permissions)</li><li> 3 nlink number of (hard) links to the file</li><li> 4 uid numeric user ID of file's owner</li><li> 5 gid numeric group ID of file's owner</li><li> 6 rdev the device identifier (special files only)</li><li> 7 size total size of file, in bytes</li><li> 8 atime last access time in seconds since the epoch</li><li> 9 mtime last modify time in seconds since the epoch</li><li> 10 ctime inode change time in seconds since the epoch (*)</li><li> 11 blksize preferred block size for file system I/O</li><li> 12 blocks actual number of blocks allocated</li></ol></pre><p>(The epoch was at 00:00 January 1, 1970 GMT.)</p>
<p>(*) Not all fields are supported on all filesystem types. Notably, the<br>
ctime field is non-portable. In particular, you cannot expect it to be a<br>
"creation time", see <a href="../perlport.html#Files-and-Filesystems">"Files and Filesystems" in perlport</a> for details.</p>
<p>If <code class="inline"><a class="l_k" href="../functions/stat.html">stat</a></code> is passed the special filehandle consisting of an underline, no<br>
stat is done, but the current contents of the stat structure from the<br>
last <code class="inline"><a class="l_k" href="../functions/stat.html">stat</a></code>, <code class="inline"><a class="l_k" href="../functions/lstat.html">lstat</a></code>, or filetest are returned. Example:</p>
<pre class="verbatim"><ol><li> if <span class="s">(</span>-x <span class="i">$file</span> && <span class="s">(</span><span class="s">(</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="w">_</span><span class="s">)</span><span class="s">)</span> && <span class="i">$d</span> < <span class="n">0</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"$file is executable NFS file\n"</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>(This works on machines only for which the device number is negative<br>
under NFS.)</p>
<p>Because the mode contains both the file type and its permissions, you<br>
should mask off the file type portion and (s)printf using a <code class="inline"><span class="q">"%o"</span></code>
<br>
if you want to see the real permissions.</p>
<pre class="verbatim"><ol><li> <span class="i">$mode</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="s">)</span>[<span class="n">2</span>]<span class="sc">;</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"Permissions are %04o\n"</span><span class="cm">,</span> <span class="i">$mode</span> & <span class="n">07777</span><span class="sc">;</span></li></ol></pre><p>In scalar context, <code class="inline"><a class="l_k" href="../functions/stat.html">stat</a></code> returns a boolean value indicating success<br>
or failure, and, if successful, sets the information associated with<br>
the special filehandle <code class="inline"><span class="w">_</span></code>
.</p>
<p>The <a href="../File/stat.html">File::stat</a> module provides a convenient, by-name access mechanism:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <span class="i">$sb</span> = <a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"File is %s, size is %s, perm %04o, mtime %s\n"</span><span class="cm">,</span></li><li> <span class="i">$filename</span><span class="cm">,</span> <span class="i">$sb</span><span class="i">->size</span><span class="cm">,</span> <span class="i">$sb</span><span class="i">->mode</span> & <span class="n">07777</span><span class="cm">,</span></li><li> <a class="l_k" href="../functions/scalar.html">scalar</a> <a class="l_k" href="../functions/localtime.html">localtime</a> <span class="i">$sb</span><span class="i">->mtime</span><span class="sc">;</span></li></ol></pre><p>You can import symbolic mode constants (<code class="inline"><span class="w">S_IF</span>*</code>
) and functions<br>
(<code class="inline"><span class="w">S_IS</span>*</code>
) from the Fcntl module:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Fcntl</span> <span class="q">':mode'</span><span class="sc">;</span></li><li></li><li> <span class="i">$mode</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="s">)</span>[<span class="n">2</span>]<span class="sc">;</span></li><li></li><li> <span class="i">$user_rwx</span> = <span class="s">(</span><span class="i">$mode</span> & <span class="w">S_IRWXU</span><span class="s">)</span> >> <span class="n">6</span><span class="sc">;</span></li><li> <span class="i">$group_read</span> = <span class="s">(</span><span class="i">$mode</span> & <span class="w">S_IRGRP</span><span class="s">)</span> >> <span class="n">3</span><span class="sc">;</span></li><li> <span class="i">$other_execute</span> = <span class="i">$mode</span> & <span class="w">S_IXOTH</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"Permissions are %04o\n"</span><span class="cm">,</span> <span class="i">S_IMODE</span><span class="s">(</span><span class="i">$mode</span><span class="s">)</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li><li></li><li> <span class="i">$is_setuid</span> = <span class="i">$mode</span> & <span class="w">S_ISUID</span><span class="sc">;</span></li><li> <span class="i">$is_directory</span> = <span class="i">S_ISDIR</span><span class="s">(</span><span class="i">$mode</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>You could write the last two using the <code class="inline">-u</code>
and <code class="inline">-d</code>
operators.<br>
The commonly available <code class="inline"><span class="w">S_IF</span>*</code>
constants are</p>
<pre class="verbatim"><ol><li> <span class="c"># Permissions: read, write, execute, for user, group, others.</span></li><li></li><li> <span class="w">S_IRWXU</span> <span class="w">S_IRUSR</span> <span class="w">S_IWUSR</span> <span class="w">S_IXUSR</span></li><li> <span class="w">S_IRWXG</span> <span class="w">S_IRGRP</span> <span class="w">S_IWGRP</span> <span class="w">S_IXGRP</span></li><li> <span class="w">S_IRWXO</span> <span class="w">S_IROTH</span> <span class="w">S_IWOTH</span> <span class="w">S_IXOTH</span></li><li></li><li> <span class="c"># Setuid/Setgid/Stickiness/SaveText.</span></li><li> <span class="c"># Note that the exact meaning of these is system dependent.</span></li><li></li><li> <span class="w">S_ISUID</span> <span class="w">S_ISGID</span> <span class="w">S_ISVTX</span> <span class="w">S_ISTXT</span></li><li></li><li> <span class="c"># File types. Not necessarily all are available on your system.</span></li><li></li><li> <span class="w">S_IFREG</span> <span class="w">S_IFDIR</span> <span class="w">S_IFLNK</span> <span class="w">S_IFBLK</span> <span class="w">S_IFCHR</span> <span class="w">S_IFIFO</span> <span class="w">S_IFSOCK</span> <span class="w">S_IFWHT</span> <span class="w">S_ENFMT</span></li><li></li><li> <span class="c"># The following are compatibility aliases for S_IRUSR, S_IWUSR, S_IXUSR.</span></li><li></li><li> <span class="w">S_IREAD</span> <span class="w">S_IWRITE</span> <span class="w">S_IEXEC</span></li></ol></pre><p>and the <code class="inline"><span class="w">S_IF</span>*</code>
functions are</p>
<pre class="verbatim"><ol><li> S_IMODE($mode) the part of $mode containing the permission bits</li><li> and the setuid/setgid/sticky bits</li><li></li><li> S_IFMT($mode) the part of $mode containing the file type</li><li> which can be bit-anded with e.g. S_IFREG</li><li> or with the following functions</li><li></li><li> # The operators -f, -d, -l, -b, -c, -p, and -S.</li><li></li><li> S_ISREG($mode) S_ISDIR($mode) S_ISLNK($mode)</li><li> S_ISBLK($mode) S_ISCHR($mode) S_ISFIFO($mode) S_ISSOCK($mode)</li><li></li><li> # No direct -X operator counterpart, but for the first one</li><li> # the -g operator is often equivalent. The ENFMT stands for</li><li> # record flocking enforcement, a platform-dependent feature.</li><li></li><li> S_ISENFMT($mode) S_ISWHT($mode)</li></ol></pre><p>See your native chmod(2) and stat(2) documentation for more details<br>
about the <code class="inline"><span class="w">S_</span>*</code>
constants. To get status info for a symbolic link<br>
instead of the target file behind the link, use the <code class="inline"><a class="l_k" href="../functions/lstat.html">lstat</a></code> function.]]></desc>
</keyword>
<keyword name="stat" type="function">
<params>
<param name='filehandle'/>
</params>
<desc><![CDATA[Returns a 13-element list giving the status info for a file, either<br>
the file opened via FILEHANDLE or DIRHANDLE, or named by EXPR. If EXPR is <br>
omitted, it stats <code class="inline"><span class="i">$_</span></code>
. Returns a null list if the stat fails. Typically<br>
used as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$dev</span><span class="cm">,</span><span class="i">$ino</span><span class="cm">,</span><span class="i">$mode</span><span class="cm">,</span><span class="i">$nlink</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$rdev</span><span class="cm">,</span><span class="i">$size</span><span class="cm">,</span></li><li> <span class="i">$atime</span><span class="cm">,</span><span class="i">$mtime</span><span class="cm">,</span><span class="i">$ctime</span><span class="cm">,</span><span class="i">$blksize</span><span class="cm">,</span><span class="i">$blocks</span><span class="s">)</span></li><li> = <a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Not all fields are supported on all filesystem types. Here are the<br>
meanings of the fields:</p>
<pre class="verbatim"><ol><li> 0 dev device number of filesystem</li><li> 1 ino inode number</li><li> 2 mode file mode (type and permissions)</li><li> 3 nlink number of (hard) links to the file</li><li> 4 uid numeric user ID of file's owner</li><li> 5 gid numeric group ID of file's owner</li><li> 6 rdev the device identifier (special files only)</li><li> 7 size total size of file, in bytes</li><li> 8 atime last access time in seconds since the epoch</li><li> 9 mtime last modify time in seconds since the epoch</li><li> 10 ctime inode change time in seconds since the epoch (*)</li><li> 11 blksize preferred block size for file system I/O</li><li> 12 blocks actual number of blocks allocated</li></ol></pre><p>(The epoch was at 00:00 January 1, 1970 GMT.)</p>
<p>(*) Not all fields are supported on all filesystem types. Notably, the<br>
ctime field is non-portable. In particular, you cannot expect it to be a<br>
"creation time", see <a href="../perlport.html#Files-and-Filesystems">"Files and Filesystems" in perlport</a> for details.</p>
<p>If <code class="inline"><a class="l_k" href="../functions/stat.html">stat</a></code> is passed the special filehandle consisting of an underline, no<br>
stat is done, but the current contents of the stat structure from the<br>
last <code class="inline"><a class="l_k" href="../functions/stat.html">stat</a></code>, <code class="inline"><a class="l_k" href="../functions/lstat.html">lstat</a></code>, or filetest are returned. Example:</p>
<pre class="verbatim"><ol><li> if <span class="s">(</span>-x <span class="i">$file</span> && <span class="s">(</span><span class="s">(</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="w">_</span><span class="s">)</span><span class="s">)</span> && <span class="i">$d</span> < <span class="n">0</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"$file is executable NFS file\n"</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>(This works on machines only for which the device number is negative<br>
under NFS.)</p>
<p>Because the mode contains both the file type and its permissions, you<br>
should mask off the file type portion and (s)printf using a <code class="inline"><span class="q">"%o"</span></code>
<br>
if you want to see the real permissions.</p>
<pre class="verbatim"><ol><li> <span class="i">$mode</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="s">)</span>[<span class="n">2</span>]<span class="sc">;</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"Permissions are %04o\n"</span><span class="cm">,</span> <span class="i">$mode</span> & <span class="n">07777</span><span class="sc">;</span></li></ol></pre><p>In scalar context, <code class="inline"><a class="l_k" href="../functions/stat.html">stat</a></code> returns a boolean value indicating success<br>
or failure, and, if successful, sets the information associated with<br>
the special filehandle <code class="inline"><span class="w">_</span></code>
.</p>
<p>The <a href="../File/stat.html">File::stat</a> module provides a convenient, by-name access mechanism:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <span class="i">$sb</span> = <a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"File is %s, size is %s, perm %04o, mtime %s\n"</span><span class="cm">,</span></li><li> <span class="i">$filename</span><span class="cm">,</span> <span class="i">$sb</span><span class="i">->size</span><span class="cm">,</span> <span class="i">$sb</span><span class="i">->mode</span> & <span class="n">07777</span><span class="cm">,</span></li><li> <a class="l_k" href="../functions/scalar.html">scalar</a> <a class="l_k" href="../functions/localtime.html">localtime</a> <span class="i">$sb</span><span class="i">->mtime</span><span class="sc">;</span></li></ol></pre><p>You can import symbolic mode constants (<code class="inline"><span class="w">S_IF</span>*</code>
) and functions<br>
(<code class="inline"><span class="w">S_IS</span>*</code>
) from the Fcntl module:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Fcntl</span> <span class="q">':mode'</span><span class="sc">;</span></li><li></li><li> <span class="i">$mode</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="s">)</span>[<span class="n">2</span>]<span class="sc">;</span></li><li></li><li> <span class="i">$user_rwx</span> = <span class="s">(</span><span class="i">$mode</span> & <span class="w">S_IRWXU</span><span class="s">)</span> >> <span class="n">6</span><span class="sc">;</span></li><li> <span class="i">$group_read</span> = <span class="s">(</span><span class="i">$mode</span> & <span class="w">S_IRGRP</span><span class="s">)</span> >> <span class="n">3</span><span class="sc">;</span></li><li> <span class="i">$other_execute</span> = <span class="i">$mode</span> & <span class="w">S_IXOTH</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"Permissions are %04o\n"</span><span class="cm">,</span> <span class="i">S_IMODE</span><span class="s">(</span><span class="i">$mode</span><span class="s">)</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li><li></li><li> <span class="i">$is_setuid</span> = <span class="i">$mode</span> & <span class="w">S_ISUID</span><span class="sc">;</span></li><li> <span class="i">$is_directory</span> = <span class="i">S_ISDIR</span><span class="s">(</span><span class="i">$mode</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>You could write the last two using the <code class="inline">-u</code>
and <code class="inline">-d</code>
operators.<br>
The commonly available <code class="inline"><span class="w">S_IF</span>*</code>
constants are</p>
<pre class="verbatim"><ol><li> <span class="c"># Permissions: read, write, execute, for user, group, others.</span></li><li></li><li> <span class="w">S_IRWXU</span> <span class="w">S_IRUSR</span> <span class="w">S_IWUSR</span> <span class="w">S_IXUSR</span></li><li> <span class="w">S_IRWXG</span> <span class="w">S_IRGRP</span> <span class="w">S_IWGRP</span> <span class="w">S_IXGRP</span></li><li> <span class="w">S_IRWXO</span> <span class="w">S_IROTH</span> <span class="w">S_IWOTH</span> <span class="w">S_IXOTH</span></li><li></li><li> <span class="c"># Setuid/Setgid/Stickiness/SaveText.</span></li><li> <span class="c"># Note that the exact meaning of these is system dependent.</span></li><li></li><li> <span class="w">S_ISUID</span> <span class="w">S_ISGID</span> <span class="w">S_ISVTX</span> <span class="w">S_ISTXT</span></li><li></li><li> <span class="c"># File types. Not necessarily all are available on your system.</span></li><li></li><li> <span class="w">S_IFREG</span> <span class="w">S_IFDIR</span> <span class="w">S_IFLNK</span> <span class="w">S_IFBLK</span> <span class="w">S_IFCHR</span> <span class="w">S_IFIFO</span> <span class="w">S_IFSOCK</span> <span class="w">S_IFWHT</span> <span class="w">S_ENFMT</span></li><li></li><li> <span class="c"># The following are compatibility aliases for S_IRUSR, S_IWUSR, S_IXUSR.</span></li><li></li><li> <span class="w">S_IREAD</span> <span class="w">S_IWRITE</span> <span class="w">S_IEXEC</span></li></ol></pre><p>and the <code class="inline"><span class="w">S_IF</span>*</code>
functions are</p>
<pre class="verbatim"><ol><li> S_IMODE($mode) the part of $mode containing the permission bits</li><li> and the setuid/setgid/sticky bits</li><li></li><li> S_IFMT($mode) the part of $mode containing the file type</li><li> which can be bit-anded with e.g. S_IFREG</li><li> or with the following functions</li><li></li><li> # The operators -f, -d, -l, -b, -c, -p, and -S.</li><li></li><li> S_ISREG($mode) S_ISDIR($mode) S_ISLNK($mode)</li><li> S_ISBLK($mode) S_ISCHR($mode) S_ISFIFO($mode) S_ISSOCK($mode)</li><li></li><li> # No direct -X operator counterpart, but for the first one</li><li> # the -g operator is often equivalent. The ENFMT stands for</li><li> # record flocking enforcement, a platform-dependent feature.</li><li></li><li> S_ISENFMT($mode) S_ISWHT($mode)</li></ol></pre><p>See your native chmod(2) and stat(2) documentation for more details<br>
about the <code class="inline"><span class="w">S_</span>*</code>
constants. To get status info for a symbolic link<br>
instead of the target file behind the link, use the <code class="inline"><a class="l_k" href="../functions/lstat.html">lstat</a></code> function.]]></desc>
</keyword>
<keyword name="stat" type="function">
<params>
</params>
<desc><![CDATA[Returns a 13-element list giving the status info for a file, either<br>
the file opened via FILEHANDLE or DIRHANDLE, or named by EXPR. If EXPR is <br>
omitted, it stats <code class="inline"><span class="i">$_</span></code>
. Returns a null list if the stat fails. Typically<br>
used as follows:</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$dev</span><span class="cm">,</span><span class="i">$ino</span><span class="cm">,</span><span class="i">$mode</span><span class="cm">,</span><span class="i">$nlink</span><span class="cm">,</span><span class="i">$uid</span><span class="cm">,</span><span class="i">$gid</span><span class="cm">,</span><span class="i">$rdev</span><span class="cm">,</span><span class="i">$size</span><span class="cm">,</span></li><li> <span class="i">$atime</span><span class="cm">,</span><span class="i">$mtime</span><span class="cm">,</span><span class="i">$ctime</span><span class="cm">,</span><span class="i">$blksize</span><span class="cm">,</span><span class="i">$blocks</span><span class="s">)</span></li><li> = <a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Not all fields are supported on all filesystem types. Here are the<br>
meanings of the fields:</p>
<pre class="verbatim"><ol><li> 0 dev device number of filesystem</li><li> 1 ino inode number</li><li> 2 mode file mode (type and permissions)</li><li> 3 nlink number of (hard) links to the file</li><li> 4 uid numeric user ID of file's owner</li><li> 5 gid numeric group ID of file's owner</li><li> 6 rdev the device identifier (special files only)</li><li> 7 size total size of file, in bytes</li><li> 8 atime last access time in seconds since the epoch</li><li> 9 mtime last modify time in seconds since the epoch</li><li> 10 ctime inode change time in seconds since the epoch (*)</li><li> 11 blksize preferred block size for file system I/O</li><li> 12 blocks actual number of blocks allocated</li></ol></pre><p>(The epoch was at 00:00 January 1, 1970 GMT.)</p>
<p>(*) Not all fields are supported on all filesystem types. Notably, the<br>
ctime field is non-portable. In particular, you cannot expect it to be a<br>
"creation time", see <a href="../perlport.html#Files-and-Filesystems">"Files and Filesystems" in perlport</a> for details.</p>
<p>If <code class="inline"><a class="l_k" href="../functions/stat.html">stat</a></code> is passed the special filehandle consisting of an underline, no<br>
stat is done, but the current contents of the stat structure from the<br>
last <code class="inline"><a class="l_k" href="../functions/stat.html">stat</a></code>, <code class="inline"><a class="l_k" href="../functions/lstat.html">lstat</a></code>, or filetest are returned. Example:</p>
<pre class="verbatim"><ol><li> if <span class="s">(</span>-x <span class="i">$file</span> && <span class="s">(</span><span class="s">(</span><span class="i">$d</span><span class="s">)</span> = <a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="w">_</span><span class="s">)</span><span class="s">)</span> && <span class="i">$d</span> < <span class="n">0</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"$file is executable NFS file\n"</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>(This works on machines only for which the device number is negative<br>
under NFS.)</p>
<p>Because the mode contains both the file type and its permissions, you<br>
should mask off the file type portion and (s)printf using a <code class="inline"><span class="q">"%o"</span></code>
<br>
if you want to see the real permissions.</p>
<pre class="verbatim"><ol><li> <span class="i">$mode</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="s">)</span>[<span class="n">2</span>]<span class="sc">;</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"Permissions are %04o\n"</span><span class="cm">,</span> <span class="i">$mode</span> & <span class="n">07777</span><span class="sc">;</span></li></ol></pre><p>In scalar context, <code class="inline"><a class="l_k" href="../functions/stat.html">stat</a></code> returns a boolean value indicating success<br>
or failure, and, if successful, sets the information associated with<br>
the special filehandle <code class="inline"><span class="w">_</span></code>
.</p>
<p>The <a href="../File/stat.html">File::stat</a> module provides a convenient, by-name access mechanism:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">File::stat</span><span class="sc">;</span></li><li> <span class="i">$sb</span> = <a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"File is %s, size is %s, perm %04o, mtime %s\n"</span><span class="cm">,</span></li><li> <span class="i">$filename</span><span class="cm">,</span> <span class="i">$sb</span><span class="i">->size</span><span class="cm">,</span> <span class="i">$sb</span><span class="i">->mode</span> & <span class="n">07777</span><span class="cm">,</span></li><li> <a class="l_k" href="../functions/scalar.html">scalar</a> <a class="l_k" href="../functions/localtime.html">localtime</a> <span class="i">$sb</span><span class="i">->mtime</span><span class="sc">;</span></li></ol></pre><p>You can import symbolic mode constants (<code class="inline"><span class="w">S_IF</span>*</code>
) and functions<br>
(<code class="inline"><span class="w">S_IS</span>*</code>
) from the Fcntl module:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Fcntl</span> <span class="q">':mode'</span><span class="sc">;</span></li><li></li><li> <span class="i">$mode</span> = <span class="s">(</span><a class="l_k" href="../functions/stat.html">stat</a><span class="s">(</span><span class="i">$filename</span><span class="s">)</span><span class="s">)</span>[<span class="n">2</span>]<span class="sc">;</span></li><li></li><li> <span class="i">$user_rwx</span> = <span class="s">(</span><span class="i">$mode</span> & <span class="w">S_IRWXU</span><span class="s">)</span> >> <span class="n">6</span><span class="sc">;</span></li><li> <span class="i">$group_read</span> = <span class="s">(</span><span class="i">$mode</span> & <span class="w">S_IRGRP</span><span class="s">)</span> >> <span class="n">3</span><span class="sc">;</span></li><li> <span class="i">$other_execute</span> = <span class="i">$mode</span> & <span class="w">S_IXOTH</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"Permissions are %04o\n"</span><span class="cm">,</span> <span class="i">S_IMODE</span><span class="s">(</span><span class="i">$mode</span><span class="s">)</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li><li></li><li> <span class="i">$is_setuid</span> = <span class="i">$mode</span> & <span class="w">S_ISUID</span><span class="sc">;</span></li><li> <span class="i">$is_directory</span> = <span class="i">S_ISDIR</span><span class="s">(</span><span class="i">$mode</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>You could write the last two using the <code class="inline">-u</code>
and <code class="inline">-d</code>
operators.<br>
The commonly available <code class="inline"><span class="w">S_IF</span>*</code>
constants are</p>
<pre class="verbatim"><ol><li> <span class="c"># Permissions: read, write, execute, for user, group, others.</span></li><li></li><li> <span class="w">S_IRWXU</span> <span class="w">S_IRUSR</span> <span class="w">S_IWUSR</span> <span class="w">S_IXUSR</span></li><li> <span class="w">S_IRWXG</span> <span class="w">S_IRGRP</span> <span class="w">S_IWGRP</span> <span class="w">S_IXGRP</span></li><li> <span class="w">S_IRWXO</span> <span class="w">S_IROTH</span> <span class="w">S_IWOTH</span> <span class="w">S_IXOTH</span></li><li></li><li> <span class="c"># Setuid/Setgid/Stickiness/SaveText.</span></li><li> <span class="c"># Note that the exact meaning of these is system dependent.</span></li><li></li><li> <span class="w">S_ISUID</span> <span class="w">S_ISGID</span> <span class="w">S_ISVTX</span> <span class="w">S_ISTXT</span></li><li></li><li> <span class="c"># File types. Not necessarily all are available on your system.</span></li><li></li><li> <span class="w">S_IFREG</span> <span class="w">S_IFDIR</span> <span class="w">S_IFLNK</span> <span class="w">S_IFBLK</span> <span class="w">S_IFCHR</span> <span class="w">S_IFIFO</span> <span class="w">S_IFSOCK</span> <span class="w">S_IFWHT</span> <span class="w">S_ENFMT</span></li><li></li><li> <span class="c"># The following are compatibility aliases for S_IRUSR, S_IWUSR, S_IXUSR.</span></li><li></li><li> <span class="w">S_IREAD</span> <span class="w">S_IWRITE</span> <span class="w">S_IEXEC</span></li></ol></pre><p>and the <code class="inline"><span class="w">S_IF</span>*</code>
functions are</p>
<pre class="verbatim"><ol><li> S_IMODE($mode) the part of $mode containing the permission bits</li><li> and the setuid/setgid/sticky bits</li><li></li><li> S_IFMT($mode) the part of $mode containing the file type</li><li> which can be bit-anded with e.g. S_IFREG</li><li> or with the following functions</li><li></li><li> # The operators -f, -d, -l, -b, -c, -p, and -S.</li><li></li><li> S_ISREG($mode) S_ISDIR($mode) S_ISLNK($mode)</li><li> S_ISBLK($mode) S_ISCHR($mode) S_ISFIFO($mode) S_ISSOCK($mode)</li><li></li><li> # No direct -X operator counterpart, but for the first one</li><li> # the -g operator is often equivalent. The ENFMT stands for</li><li> # record flocking enforcement, a platform-dependent feature.</li><li></li><li> S_ISENFMT($mode) S_ISWHT($mode)</li></ol></pre><p>See your native chmod(2) and stat(2) documentation for more details<br>
about the <code class="inline"><span class="w">S_</span>*</code>
constants. To get status info for a symbolic link<br>
instead of the target file behind the link, use the <code class="inline"><a class="l_k" href="../functions/lstat.html">lstat</a></code> function.]]></desc>
</keyword>
<keyword name="state" type="function">
<params>
<param name='expr : attrs'/>
</params>
<desc><![CDATA[<code class="inline"><a class="l_k" href="../functions/state.html">state</a></code> declares a lexically scoped variable, just like <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code> does.<br>
However, those variables will never be reinitialized, contrary to<br>
lexical variables that are reinitialized each time their enclosing block<br>
is entered.</p>
<p><code class="inline"><a class="l_k" href="../functions/state.html">state</a></code> variables are only enabled when the <code class="inline"><span class="w">feature</span> <span class="q">'state'</span></code>
pragma is<br>
in effect. See <a href="../feature.html">feature</a>.]]></desc>
</keyword>
<keyword name="state" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[<code class="inline"><a class="l_k" href="../functions/state.html">state</a></code> declares a lexically scoped variable, just like <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code> does.<br>
However, those variables will never be reinitialized, contrary to<br>
lexical variables that are reinitialized each time their enclosing block<br>
is entered.</p>
<p><code class="inline"><a class="l_k" href="../functions/state.html">state</a></code> variables are only enabled when the <code class="inline"><span class="w">feature</span> <span class="q">'state'</span></code>
pragma is<br>
in effect. See <a href="../feature.html">feature</a>.]]></desc>
</keyword>
<keyword name="state" type="function">
<params>
<param name='type expr : attrs'/>
</params>
<desc><![CDATA[<code class="inline"><a class="l_k" href="../functions/state.html">state</a></code> declares a lexically scoped variable, just like <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code> does.<br>
However, those variables will never be reinitialized, contrary to<br>
lexical variables that are reinitialized each time their enclosing block<br>
is entered.</p>
<p><code class="inline"><a class="l_k" href="../functions/state.html">state</a></code> variables are only enabled when the <code class="inline"><span class="w">feature</span> <span class="q">'state'</span></code>
pragma is<br>
in effect. See <a href="../feature.html">feature</a>.]]></desc>
</keyword>
<keyword name="state" type="function">
<params>
<param name='type expr'/>
</params>
<desc><![CDATA[<code class="inline"><a class="l_k" href="../functions/state.html">state</a></code> declares a lexically scoped variable, just like <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code> does.<br>
However, those variables will never be reinitialized, contrary to<br>
lexical variables that are reinitialized each time their enclosing block<br>
is entered.</p>
<p><code class="inline"><a class="l_k" href="../functions/state.html">state</a></code> variables are only enabled when the <code class="inline"><span class="w">feature</span> <span class="q">'state'</span></code>
pragma is<br>
in effect. See <a href="../feature.html">feature</a>.]]></desc>
</keyword>
<keyword name="study" type="function">
<params>
<param name='scalar'/>
</params>
<desc><![CDATA[Takes extra time to study SCALAR (<code class="inline"><span class="i">$_</span></code>
if unspecified) in anticipation of<br>
doing many pattern matches on the string before it is next modified.<br>
This may or may not save time, depending on the nature and number of<br>
patterns you are searching on, and on the distribution of character<br>
frequencies in the string to be searched--you probably want to compare<br>
run times with and without it to see which runs faster. Those loops<br>
that scan for many short constant strings (including the constant<br>
parts of more complex patterns) will benefit most. You may have only<br>
one <code class="inline"><a class="l_k" href="../functions/study.html">study</a></code> active at a time--if you study a different scalar the first<br>
is "unstudied". (The way <code class="inline"><a class="l_k" href="../functions/study.html">study</a></code> works is this: a linked list of every<br>
character in the string to be searched is made, so we know, for<br>
example, where all the <code class="inline"><span class="q">'k'</span></code>
characters are. From each search string,<br>
the rarest character is selected, based on some static frequency tables<br>
constructed from some C programs and English text. Only those places<br>
that contain this "rarest" character are examined.)</p>
<p>For example, here is a loop that inserts index producing entries<br>
before any line containing a certain pattern:</p>
<pre class="verbatim"><ol><li> while <span class="s">(</span><><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/study.html">study</a><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">".IX foo\n"</span> if <span class="q">/\bfoo\b/</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">".IX bar\n"</span> if <span class="q">/\bbar\b/</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">".IX blurfl\n"</span> if <span class="q">/\bblurfl\b/</span><span class="sc">;</span></li><li> <span class="c"># ...</span></li><li> <a class="l_k" href="../functions/print.html">print</a><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>In searching for <code class="inline"><span class="q">/\bfoo\b/</span></code>
, only those locations in <code class="inline"><span class="i">$_</span></code>
that contain <code class="inline"><span class="w">f</span></code>
<br>
will be looked at, because <code class="inline"><span class="w">f</span></code>
is rarer than <code class="inline"><span class="w">o</span></code>
. In general, this is<br>
a big win except in pathological cases. The only question is whether<br>
it saves you more time than it took to build the linked list in the<br>
first place.</p>
<p>Note that if you have to look for strings that you don't know till<br>
runtime, you can build an entire loop as a string and <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a></code> that to<br>
avoid recompiling all your patterns all the time. Together with<br>
undefining <code class="inline"><span class="i">$/</span></code>
to input entire files as one record, this can be very<br>
fast, often faster than specialized programs like fgrep(1). The following<br>
scans a list of files (<code class="inline"><span class="i">@files</span></code>
) for a list of words (<code class="inline"><span class="i">@words</span></code>
), and prints<br>
out the names of those files that contain a match:</p>
<pre class="verbatim"><ol><li> <span class="i">$search</span> = <span class="q">'while (<>) { study;'</span><span class="sc">;</span></li><li> foreach <span class="i">$word</span> <span class="s">(</span><span class="i">@words</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$search</span> .= <span class="q">"++\$seen{\$ARGV} if /\\b$word\\b/;\n"</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> <span class="i">$search</span> .= <span class="q">"}"</span><span class="sc">;</span></li><li> <span class="i">@ARGV</span> = <span class="i">@files</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/undef.html">undef</a> <span class="i">$/</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/eval.html">eval</a> <span class="i">$search</span><span class="sc">;</span> <span class="c"># this screams</span></li><li> <span class="i">$/</span> = <span class="q">"\n"</span><span class="sc">;</span> <span class="c"># put back to normal input delimiter</span></li><li> foreach <span class="i">$file</span> <span class="s">(</span><a class="l_k" href="../functions/sort.html">sort</a> <a class="l_k" href="../functions/keys.html">keys</a><span class="s">(</span><span class="i">%seen</span><span class="s">)</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$file</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol><]]></desc>
</keyword>
<keyword name="study" type="function">
<params>
</params>
<desc><![CDATA[Takes extra time to study SCALAR (<code class="inline"><span class="i">$_</span></code>
if unspecified) in anticipation of<br>
doing many pattern matches on the string before it is next modified.<br>
This may or may not save time, depending on the nature and number of<br>
patterns you are searching on, and on the distribution of character<br>
frequencies in the string to be searched--you probably want to compare<br>
run times with and without it to see which runs faster. Those loops<br>
that scan for many short constant strings (including the constant<br>
parts of more complex patterns) will benefit most. You may have only<br>
one <code class="inline"><a class="l_k" href="../functions/study.html">study</a></code> active at a time--if you study a different scalar the first<br>
is "unstudied". (The way <code class="inline"><a class="l_k" href="../functions/study.html">study</a></code> works is this: a linked list of every<br>
character in the string to be searched is made, so we know, for<br>
example, where all the <code class="inline"><span class="q">'k'</span></code>
characters are. From each search string,<br>
the rarest character is selected, based on some static frequency tables<br>
constructed from some C programs and English text. Only those places<br>
that contain this "rarest" character are examined.)</p>
<p>For example, here is a loop that inserts index producing entries<br>
before any line containing a certain pattern:</p>
<pre class="verbatim"><ol><li> while <span class="s">(</span><><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/study.html">study</a><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">".IX foo\n"</span> if <span class="q">/\bfoo\b/</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">".IX bar\n"</span> if <span class="q">/\bbar\b/</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">".IX blurfl\n"</span> if <span class="q">/\bblurfl\b/</span><span class="sc">;</span></li><li> <span class="c"># ...</span></li><li> <a class="l_k" href="../functions/print.html">print</a><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>In searching for <code class="inline"><span class="q">/\bfoo\b/</span></code>
, only those locations in <code class="inline"><span class="i">$_</span></code>
that contain <code class="inline"><span class="w">f</span></code>
<br>
will be looked at, because <code class="inline"><span class="w">f</span></code>
is rarer than <code class="inline"><span class="w">o</span></code>
. In general, this is<br>
a big win except in pathological cases. The only question is whether<br>
it saves you more time than it took to build the linked list in the<br>
first place.</p>
<p>Note that if you have to look for strings that you don't know till<br>
runtime, you can build an entire loop as a string and <code class="inline"><a class="l_k" href="../functions/eval.html">eval</a></code> that to<br>
avoid recompiling all your patterns all the time. Together with<br>
undefining <code class="inline"><span class="i">$/</span></code>
to input entire files as one record, this can be very<br>
fast, often faster than specialized programs like fgrep(1). The following<br>
scans a list of files (<code class="inline"><span class="i">@files</span></code>
) for a list of words (<code class="inline"><span class="i">@words</span></code>
), and prints<br>
out the names of those files that contain a match:</p>
<pre class="verbatim"><ol><li> <span class="i">$search</span> = <span class="q">'while (<>) { study;'</span><span class="sc">;</span></li><li> foreach <span class="i">$word</span> <span class="s">(</span><span class="i">@words</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$search</span> .= <span class="q">"++\$seen{\$ARGV} if /\\b$word\\b/;\n"</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> <span class="i">$search</span> .= <span class="q">"}"</span><span class="sc">;</span></li><li> <span class="i">@ARGV</span> = <span class="i">@files</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/undef.html">undef</a> <span class="i">$/</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/eval.html">eval</a> <span class="i">$search</span><span class="sc">;</span> <span class="c"># this screams</span></li><li> <span class="i">$/</span> = <span class="q">"\n"</span><span class="sc">;</span> <span class="c"># put back to normal input delimiter</span></li><li> foreach <span class="i">$file</span> <span class="s">(</span><a class="l_k" href="../functions/sort.html">sort</a> <a class="l_k" href="../functions/keys.html">keys</a><span class="s">(</span><span class="i">%seen</span><span class="s">)</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$file</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol><]]></desc>
</keyword>
<keyword name="sub" type="function">
<params>
<param name='name (proto) : attrs block'/>
</params>
<desc><![CDATA[This is subroutine definition, not a real function <i>per se</i>.<br>
Without a BLOCK it's just a forward declaration. Without a NAME,<br>
it's an anonymous function declaration, and does actually return<br>
a value: the CODE ref of the closure you just created.</p>
<p>See <a href="../perlsub.html">perlsub</a> and <a href="../perlref.html">perlref</a> for details about subroutines and<br>
references, and <a href="../attributes.html">attributes</a> and <a href="../Attribute/Handlers.html">Attribute::Handlers</a> for more<br>
information about attributes.]]></desc>
</keyword>
<keyword name="sub" type="function">
<params>
<param name='name (proto) block'/>
</params>
<desc><![CDATA[This is subroutine definition, not a real function <i>per se</i>.<br>
Without a BLOCK it's just a forward declaration. Without a NAME,<br>
it's an anonymous function declaration, and does actually return<br>
a value: the CODE ref of the closure you just created.</p>
<p>See <a href="../perlsub.html">perlsub</a> and <a href="../perlref.html">perlref</a> for details about subroutines and<br>
references, and <a href="../attributes.html">attributes</a> and <a href="../Attribute/Handlers.html">Attribute::Handlers</a> for more<br>
information about attributes.]]></desc>
</keyword>
<keyword name="sub" type="function">
<params>
<param name='name : attrs block'/>
</params>
<desc><![CDATA[This is subroutine definition, not a real function <i>per se</i>.<br>
Without a BLOCK it's just a forward declaration. Without a NAME,<br>
it's an anonymous function declaration, and does actually return<br>
a value: the CODE ref of the closure you just created.</p>
<p>See <a href="../perlsub.html">perlsub</a> and <a href="../perlref.html">perlref</a> for details about subroutines and<br>
references, and <a href="../attributes.html">attributes</a> and <a href="../Attribute/Handlers.html">Attribute::Handlers</a> for more<br>
information about attributes.]]></desc>
</keyword>
<keyword name="sub" type="function">
<params>
<param name='name block'/>
</params>
<desc><![CDATA[This is subroutine definition, not a real function <i>per se</i>.<br>
Without a BLOCK it's just a forward declaration. Without a NAME,<br>
it's an anonymous function declaration, and does actually return<br>
a value: the CODE ref of the closure you just created.</p>
<p>See <a href="../perlsub.html">perlsub</a> and <a href="../perlref.html">perlref</a> for details about subroutines and<br>
references, and <a href="../attributes.html">attributes</a> and <a href="../Attribute/Handlers.html">Attribute::Handlers</a> for more<br>
information about attributes.]]></desc>
</keyword>
<keyword name="substr" type="function">
<params>
<param name='expr'/>
<param name='offset'/>
<param name='length'/>
<param name='replacement'/>
</params>
<desc><![CDATA[Extracts a substring out of EXPR and returns it. First character is at<br>
offset <code class="inline"><span class="n">0</span></code>
, or whatever you've set <code class="inline"><span class="i">$[</span></code>
to (but don't do that).<br>
If OFFSET is negative (or more precisely, less than <code class="inline"><span class="i">$[</span></code>
), starts<br>
that far from the end of the string. If LENGTH is omitted, returns<br>
everything to the end of the string. If LENGTH is negative, leaves that<br>
many characters off the end of the string.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$s</span> = <span class="q">"The black cat climbed the green tree"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$color</span> = <a class="l_k" href="../functions/substr.html">substr</a> <span class="i">$s</span><span class="cm">,</span> <span class="n">4</span><span class="cm">,</span> <span class="n">5</span><span class="sc">;</span> <span class="c"># black</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$middle</span> = <a class="l_k" href="../functions/substr.html">substr</a> <span class="i">$s</span><span class="cm">,</span> <span class="n">4</span><span class="cm">,</span> <span class="n">-11</span><span class="sc">;</span> <span class="c"># black cat climbed the</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$end</span> = <a class="l_k" href="../functions/substr.html">substr</a> <span class="i">$s</span><span class="cm">,</span> <span class="n">14</span><span class="sc">;</span> <span class="c"># climbed the green tree</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$tail</span> = <a class="l_k" href="../functions/substr.html">substr</a> <span class="i">$s</span><span class="cm">,</span> <span class="n">-4</span><span class="sc">;</span> <span class="c"># tree</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$z</span> = <a class="l_k" href="../functions/substr.html">substr</a> <span class="i">$s</span><span class="cm">,</span> <span class="n">-4</span><span class="cm">,</span> <span class="n">2</span><span class="sc">;</span> <span class="c"># tr</span></li></ol></pre><p>You can use the substr() function as an lvalue, in which case EXPR<br>
must itself be an lvalue. If you assign something shorter than LENGTH,<br>
the string will shrink, and if you assign something longer than LENGTH,<br>
the string will grow to accommodate it. To keep the string the same<br>
length you may need to pad or chop your value using <code class="inline"><a class="l_k" href="../functions/sprintf.html">sprintf</a></code>.</p>
<p>If OFFSET and LENGTH specify a substring that is partly outside the<br>
string, only the part within the string is returned. If the substring<br>
is beyond either end of the string, substr() returns the undefined<br>
value and produces a warning. When used as an lvalue, specifying a<br>
substring that is entirely outside the string is a fatal error.<br>
Here's an example showing the behavior for boundary cases:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$name</span> = <span class="q">'fred'</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/substr.html">substr</a><span class="s">(</span><span class="i">$name</span><span class="cm">,</span> <span class="n">4</span><span class="s">)</span> = <span class="q">'dy'</span><span class="sc">;</span> <span class="c"># $name is now 'freddy'</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$null</span> = <a class="l_k" href="../functions/substr.html">substr</a> <span class="i">$name</span><span class="cm">,</span> <span class="n">6</span><span class="cm">,</span> <span class="n">2</span><span class="sc">;</span> <span class="c"># returns '' (no warning)</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$oops</span> = <a class="l_k" href="../functions/substr.html">substr</a> <span class="i">$name</span><span class="cm">,</span> <span class="n">7</span><span class="sc">;</span> <span class="c"># returns undef, with warning</span></li><li> <a class="l_k" href="../functions/substr.html">substr</a><span class="s">(</span><span class="i">$name</span><span class="cm">,</span> <span class="n">7</span><span class="s">)</span> = <span class="q">'gap'</span><span class="sc">;</span> <span class="c"># fatal error</span></li></ol></pre><p>An alternative to using substr() as an lvalue is to specify the<br>
replacement string as the 4th argument. This allows you to replace<br>
parts of the EXPR and return what was there before in one operation,<br>
just as you can with splice().</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$s</span> = <span class="q">"The black cat climbed the green tree"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$z</span> = <a class="l_k" href="../functions/substr.html">substr</a> <span class="i">$s</span><span class="cm">,</span> <span class="n">14</span><span class="cm">,</span> <span class="n">7</span><span class="cm">,</span> <span class="q">"jumped from"</span><span class="sc">;</span> <span class="c"># climbed</span></li><li> <span class="c"># $s is now "The black cat jumped from the green tree"</span></li></ol></pre><p>Note that the lvalue returned by the 3-arg version of substr() acts as<br>
a 'magic bullet'; each time it is assigned to, it remembers which part<br>
of the original string is being modified; for example:</p>
<pre class="verbatim"><ol><li> <span class="i">$x</span> = <span class="q">'1234'</span><span class="sc">;</span></li><li> for <span class="s">(</span><a class="l_k" href="../functions/substr.html">substr</a><span class="s">(</span><span class="i">$x</span><span class="cm">,</span><span class="n">1</span><span class="cm">,</span><span class="n">2</span><span class="s">)</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$_</span> = <span class="q">'a'</span><span class="sc">;</span> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$x</span><span class="cm">,</span><span class="q">"\n"</span><span class="sc">;</span> <span class="c"># prints 1a4</span></li><li> <span class="i">$_</span> = <span class="q">'xyz'</span><span class="sc">;</span> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$x</span><span class="cm">,</span><span class="q">"\n"</span><span class="sc">;</span> <span class="c"># prints 1xyz4</span></li><li> <span class="i">$x</span> = <span class="q">'56789'</span><span class="sc">;</span></li><li> <span class="i">$_</span> = <span class="q">'pq'</span><span class="sc">;</span> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$x</span><span class="cm">,</span><span class="q">"\n"</span><span class="sc">;</span> <span class="c"># prints 5pq9</span></li><li> <span class="s">}</span></li></ol></pre><p>Prior to Perl version 5.9.1, the result of using an lvalue multiple times was<br>
unspecified.]]></desc>
</keyword>
<keyword name="substr" type="function">
<params>
<param name='expr'/>
<param name='offset'/>
<param name='length'/>
</params>
<desc><![CDATA[Extracts a substring out of EXPR and returns it. First character is at<br>
offset <code class="inline"><span class="n">0</span></code>
, or whatever you've set <code class="inline"><span class="i">$[</span></code>
to (but don't do that).<br>
If OFFSET is negative (or more precisely, less than <code class="inline"><span class="i">$[</span></code>
), starts<br>
that far from the end of the string. If LENGTH is omitted, returns<br>
everything to the end of the string. If LENGTH is negative, leaves that<br>
many characters off the end of the string.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$s</span> = <span class="q">"The black cat climbed the green tree"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$color</span> = <a class="l_k" href="../functions/substr.html">substr</a> <span class="i">$s</span><span class="cm">,</span> <span class="n">4</span><span class="cm">,</span> <span class="n">5</span><span class="sc">;</span> <span class="c"># black</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$middle</span> = <a class="l_k" href="../functions/substr.html">substr</a> <span class="i">$s</span><span class="cm">,</span> <span class="n">4</span><span class="cm">,</span> <span class="n">-11</span><span class="sc">;</span> <span class="c"># black cat climbed the</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$end</span> = <a class="l_k" href="../functions/substr.html">substr</a> <span class="i">$s</span><span class="cm">,</span> <span class="n">14</span><span class="sc">;</span> <span class="c"># climbed the green tree</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$tail</span> = <a class="l_k" href="../functions/substr.html">substr</a> <span class="i">$s</span><span class="cm">,</span> <span class="n">-4</span><span class="sc">;</span> <span class="c"># tree</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$z</span> = <a class="l_k" href="../functions/substr.html">substr</a> <span class="i">$s</span><span class="cm">,</span> <span class="n">-4</span><span class="cm">,</span> <span class="n">2</span><span class="sc">;</span> <span class="c"># tr</span></li></ol></pre><p>You can use the substr() function as an lvalue, in which case EXPR<br>
must itself be an lvalue. If you assign something shorter than LENGTH,<br>
the string will shrink, and if you assign something longer than LENGTH,<br>
the string will grow to accommodate it. To keep the string the same<br>
length you may need to pad or chop your value using <code class="inline"><a class="l_k" href="../functions/sprintf.html">sprintf</a></code>.</p>
<p>If OFFSET and LENGTH specify a substring that is partly outside the<br>
string, only the part within the string is returned. If the substring<br>
is beyond either end of the string, substr() returns the undefined<br>
value and produces a warning. When used as an lvalue, specifying a<br>
substring that is entirely outside the string is a fatal error.<br>
Here's an example showing the behavior for boundary cases:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$name</span> = <span class="q">'fred'</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/substr.html">substr</a><span class="s">(</span><span class="i">$name</span><span class="cm">,</span> <span class="n">4</span><span class="s">)</span> = <span class="q">'dy'</span><span class="sc">;</span> <span class="c"># $name is now 'freddy'</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$null</span> = <a class="l_k" href="../functions/substr.html">substr</a> <span class="i">$name</span><span class="cm">,</span> <span class="n">6</span><span class="cm">,</span> <span class="n">2</span><span class="sc">;</span> <span class="c"># returns '' (no warning)</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$oops</span> = <a class="l_k" href="../functions/substr.html">substr</a> <span class="i">$name</span><span class="cm">,</span> <span class="n">7</span><span class="sc">;</span> <span class="c"># returns undef, with warning</span></li><li> <a class="l_k" href="../functions/substr.html">substr</a><span class="s">(</span><span class="i">$name</span><span class="cm">,</span> <span class="n">7</span><span class="s">)</span> = <span class="q">'gap'</span><span class="sc">;</span> <span class="c"># fatal error</span></li></ol></pre><p>An alternative to using substr() as an lvalue is to specify the<br>
replacement string as the 4th argument. This allows you to replace<br>
parts of the EXPR and return what was there before in one operation,<br>
just as you can with splice().</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$s</span> = <span class="q">"The black cat climbed the green tree"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$z</span> = <a class="l_k" href="../functions/substr.html">substr</a> <span class="i">$s</span><span class="cm">,</span> <span class="n">14</span><span class="cm">,</span> <span class="n">7</span><span class="cm">,</span> <span class="q">"jumped from"</span><span class="sc">;</span> <span class="c"># climbed</span></li><li> <span class="c"># $s is now "The black cat jumped from the green tree"</span></li></ol></pre><p>Note that the lvalue returned by the 3-arg version of substr() acts as<br>
a 'magic bullet'; each time it is assigned to, it remembers which part<br>
of the original string is being modified; for example:</p>
<pre class="verbatim"><ol><li> <span class="i">$x</span> = <span class="q">'1234'</span><span class="sc">;</span></li><li> for <span class="s">(</span><a class="l_k" href="../functions/substr.html">substr</a><span class="s">(</span><span class="i">$x</span><span class="cm">,</span><span class="n">1</span><span class="cm">,</span><span class="n">2</span><span class="s">)</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$_</span> = <span class="q">'a'</span><span class="sc">;</span> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$x</span><span class="cm">,</span><span class="q">"\n"</span><span class="sc">;</span> <span class="c"># prints 1a4</span></li><li> <span class="i">$_</span> = <span class="q">'xyz'</span><span class="sc">;</span> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$x</span><span class="cm">,</span><span class="q">"\n"</span><span class="sc">;</span> <span class="c"># prints 1xyz4</span></li><li> <span class="i">$x</span> = <span class="q">'56789'</span><span class="sc">;</span></li><li> <span class="i">$_</span> = <span class="q">'pq'</span><span class="sc">;</span> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$x</span><span class="cm">,</span><span class="q">"\n"</span><span class="sc">;</span> <span class="c"># prints 5pq9</span></li><li> <span class="s">}</span></li></ol></pre><p>Prior to Perl version 5.9.1, the result of using an lvalue multiple times was<br>
unspecified.]]></desc>
</keyword>
<keyword name="substr" type="function">
<params>
<param name='expr'/>
<param name='offset'/>
</params>
<desc><![CDATA[Extracts a substring out of EXPR and returns it. First character is at<br>
offset <code class="inline"><span class="n">0</span></code>
, or whatever you've set <code class="inline"><span class="i">$[</span></code>
to (but don't do that).<br>
If OFFSET is negative (or more precisely, less than <code class="inline"><span class="i">$[</span></code>
), starts<br>
that far from the end of the string. If LENGTH is omitted, returns<br>
everything to the end of the string. If LENGTH is negative, leaves that<br>
many characters off the end of the string.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$s</span> = <span class="q">"The black cat climbed the green tree"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$color</span> = <a class="l_k" href="../functions/substr.html">substr</a> <span class="i">$s</span><span class="cm">,</span> <span class="n">4</span><span class="cm">,</span> <span class="n">5</span><span class="sc">;</span> <span class="c"># black</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$middle</span> = <a class="l_k" href="../functions/substr.html">substr</a> <span class="i">$s</span><span class="cm">,</span> <span class="n">4</span><span class="cm">,</span> <span class="n">-11</span><span class="sc">;</span> <span class="c"># black cat climbed the</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$end</span> = <a class="l_k" href="../functions/substr.html">substr</a> <span class="i">$s</span><span class="cm">,</span> <span class="n">14</span><span class="sc">;</span> <span class="c"># climbed the green tree</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$tail</span> = <a class="l_k" href="../functions/substr.html">substr</a> <span class="i">$s</span><span class="cm">,</span> <span class="n">-4</span><span class="sc">;</span> <span class="c"># tree</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$z</span> = <a class="l_k" href="../functions/substr.html">substr</a> <span class="i">$s</span><span class="cm">,</span> <span class="n">-4</span><span class="cm">,</span> <span class="n">2</span><span class="sc">;</span> <span class="c"># tr</span></li></ol></pre><p>You can use the substr() function as an lvalue, in which case EXPR<br>
must itself be an lvalue. If you assign something shorter than LENGTH,<br>
the string will shrink, and if you assign something longer than LENGTH,<br>
the string will grow to accommodate it. To keep the string the same<br>
length you may need to pad or chop your value using <code class="inline"><a class="l_k" href="../functions/sprintf.html">sprintf</a></code>.</p>
<p>If OFFSET and LENGTH specify a substring that is partly outside the<br>
string, only the part within the string is returned. If the substring<br>
is beyond either end of the string, substr() returns the undefined<br>
value and produces a warning. When used as an lvalue, specifying a<br>
substring that is entirely outside the string is a fatal error.<br>
Here's an example showing the behavior for boundary cases:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$name</span> = <span class="q">'fred'</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/substr.html">substr</a><span class="s">(</span><span class="i">$name</span><span class="cm">,</span> <span class="n">4</span><span class="s">)</span> = <span class="q">'dy'</span><span class="sc">;</span> <span class="c"># $name is now 'freddy'</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$null</span> = <a class="l_k" href="../functions/substr.html">substr</a> <span class="i">$name</span><span class="cm">,</span> <span class="n">6</span><span class="cm">,</span> <span class="n">2</span><span class="sc">;</span> <span class="c"># returns '' (no warning)</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$oops</span> = <a class="l_k" href="../functions/substr.html">substr</a> <span class="i">$name</span><span class="cm">,</span> <span class="n">7</span><span class="sc">;</span> <span class="c"># returns undef, with warning</span></li><li> <a class="l_k" href="../functions/substr.html">substr</a><span class="s">(</span><span class="i">$name</span><span class="cm">,</span> <span class="n">7</span><span class="s">)</span> = <span class="q">'gap'</span><span class="sc">;</span> <span class="c"># fatal error</span></li></ol></pre><p>An alternative to using substr() as an lvalue is to specify the<br>
replacement string as the 4th argument. This allows you to replace<br>
parts of the EXPR and return what was there before in one operation,<br>
just as you can with splice().</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$s</span> = <span class="q">"The black cat climbed the green tree"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$z</span> = <a class="l_k" href="../functions/substr.html">substr</a> <span class="i">$s</span><span class="cm">,</span> <span class="n">14</span><span class="cm">,</span> <span class="n">7</span><span class="cm">,</span> <span class="q">"jumped from"</span><span class="sc">;</span> <span class="c"># climbed</span></li><li> <span class="c"># $s is now "The black cat jumped from the green tree"</span></li></ol></pre><p>Note that the lvalue returned by the 3-arg version of substr() acts as<br>
a 'magic bullet'; each time it is assigned to, it remembers which part<br>
of the original string is being modified; for example:</p>
<pre class="verbatim"><ol><li> <span class="i">$x</span> = <span class="q">'1234'</span><span class="sc">;</span></li><li> for <span class="s">(</span><a class="l_k" href="../functions/substr.html">substr</a><span class="s">(</span><span class="i">$x</span><span class="cm">,</span><span class="n">1</span><span class="cm">,</span><span class="n">2</span><span class="s">)</span><span class="s">)</span> <span class="s">{</span></li><li> <span class="i">$_</span> = <span class="q">'a'</span><span class="sc">;</span> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$x</span><span class="cm">,</span><span class="q">"\n"</span><span class="sc">;</span> <span class="c"># prints 1a4</span></li><li> <span class="i">$_</span> = <span class="q">'xyz'</span><span class="sc">;</span> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$x</span><span class="cm">,</span><span class="q">"\n"</span><span class="sc">;</span> <span class="c"># prints 1xyz4</span></li><li> <span class="i">$x</span> = <span class="q">'56789'</span><span class="sc">;</span></li><li> <span class="i">$_</span> = <span class="q">'pq'</span><span class="sc">;</span> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$x</span><span class="cm">,</span><span class="q">"\n"</span><span class="sc">;</span> <span class="c"># prints 5pq9</span></li><li> <span class="s">}</span></li></ol></pre><p>Prior to Perl version 5.9.1, the result of using an lvalue multiple times was<br>
unspecified.]]></desc>
</keyword>
<keyword name="symlink" type="function">
<params>
<param name='oldfile'/>
<param name='newfile'/>
</params>
<desc><![CDATA[Creates a new filename symbolically linked to the old filename.<br>
Returns <code class="inline"><span class="n">1</span></code>
for success, <code class="inline"><span class="n">0</span></code>
otherwise. On systems that don't support<br>
symbolic links, produces a fatal error at run time. To check for that,<br>
use eval:</p>
<pre class="verbatim"><ol><li> <span class="i">$symlink_exists</span> = <a class="l_k" href="../functions/eval.html">eval</a> <span class="s">{</span> <a class="l_k" href="../functions/symlink.html">symlink</a><span class="s">(</span><span class="q">""</span><span class="cm">,</span><span class="q">""</span><span class="s">)</span><span class="sc">;</span> <span class="n">1</span> <span class="s">}</span><span class="sc">;</span></li></ol><]]></desc>
</keyword>
<keyword name="syscall" type="function">
<params>
<param name='number'/>
<param name='list'/>
</params>
<desc><![CDATA[Calls the system call specified as the first element of the list,<br>
passing the remaining elements as arguments to the system call. If<br>
unimplemented, produces a fatal error. The arguments are interpreted<br>
as follows: if a given argument is numeric, the argument is passed as<br>
an int. If not, the pointer to the string value is passed. You are<br>
responsible to make sure a string is pre-extended long enough to<br>
receive any result that might be written into a string. You can't use a<br>
string literal (or other read-only string) as an argument to <code class="inline"><a class="l_k" href="../functions/syscall.html">syscall</a></code>
because Perl has to assume that any string pointer might be written<br>
through. If your<br>
integer arguments are not literals and have never been interpreted in a<br>
numeric context, you may need to add <code class="inline"><span class="n">0</span></code>
to them to force them to look<br>
like numbers. This emulates the <code class="inline"><a class="l_k" href="../functions/syswrite.html">syswrite</a></code> function (or vice versa):</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/require.html">require</a> <span class="q">'syscall.ph'</span><span class="sc">;</span> <span class="c"># may need to run h2ph</span></li><li> <span class="i">$s</span> = <span class="q">"hi there\n"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/syscall.html">syscall</a><span class="s">(</span><span class="i">&SYS_write</span><span class="cm">,</span> <a class="l_k" href="../functions/fileno.html">fileno</a><span class="s">(</span><span class="w">STDOUT</span><span class="s">)</span><span class="cm">,</span> <span class="i">$s</span><span class="cm">,</span> <a class="l_k" href="../functions/length.html">length</a> <span class="i">$s</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Note that Perl supports passing of up to only 14 arguments to your system call,<br>
which in practice should usually suffice.</p>
<p>Syscall returns whatever value returned by the system call it calls.<br>
If the system call fails, <code class="inline"><a class="l_k" href="../functions/syscall.html">syscall</a></code> returns <code class="inline"><span class="n">-1</span></code>
and sets <code class="inline"><span class="i">$!</span></code>
(errno).<br>
Note that some system calls can legitimately return <code class="inline"><span class="n">-1</span></code>
. The proper<br>
way to handle such calls is to assign <code class="inline"><span class="i">$!</span>=<span class="n">0</span><span class="sc">;</span></code>
before the call and<br>
check the value of <code class="inline"><span class="i">$!</span></code>
if syscall returns <code class="inline"><span class="n">-1</span></code>
.</p>
<p>There's a problem with <code class="inline"><a class="l_k" href="../functions/syscall.html">syscall(&SYS_pipe)</a></code>: it returns the file<br>
number of the read end of the pipe it creates. There is no way<br>
to retrieve the file number of the other end. You can avoid this<br>
problem by using <code class="inline"><a class="l_k" href="../functions/pipe.html">pipe</a></code> instead.]]></desc>
</keyword>
<keyword name="sysopen" type="function">
<params>
<param name='filehandle'/>
<param name='filename'/>
<param name='mode'/>
<param name='perms'/>
</params>
<desc><![CDATA[Opens the file whose filename is given by FILENAME, and associates it<br>
with FILEHANDLE. If FILEHANDLE is an expression, its value is used as<br>
the name of the real filehandle wanted. This function calls the<br>
underlying operating system's <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> function with the parameters<br>
FILENAME, MODE, PERMS.</p>
<p>The possible values and flag bits of the MODE parameter are<br>
system-dependent; they are available via the standard module <code class="inline"><span class="w">Fcntl</span></code>
.<br>
See the documentation of your operating system's <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> to see which<br>
values and flag bits are available. You may combine several flags<br>
using the <code class="inline">|</code>-operator.</p>
<p>Some of the most common values are <code class="inline"><span class="w">O_RDONLY</span></code>
for opening the file in<br>
read-only mode, <code class="inline"><span class="w">O_WRONLY</span></code>
for opening the file in write-only mode,<br>
and <code class="inline"><span class="w">O_RDWR</span></code>
for opening the file in read-write mode.<br>
</p>
<p>For historical reasons, some values work on almost every system<br>
supported by perl: zero means read-only, one means write-only, and two<br>
means read/write. We know that these values do <i>not</i> work under<br>
OS/390 & VM/ESA Unix and on the Macintosh; you probably don't want to<br>
use them in new code.</p>
<p>If the file named by FILENAME does not exist and the <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> call creates<br>
it (typically because MODE includes the <code class="inline"><span class="w">O_CREAT</span></code>
flag), then the value of<br>
PERMS specifies the permissions of the newly created file. If you omit<br>
the PERMS argument to <code class="inline"><a class="l_k" href="../functions/sysopen.html">sysopen</a></code>, Perl uses the octal value <code class="inline"><span class="n">0666</span></code>
.<br>
These permission values need to be in octal, and are modified by your<br>
process's current <code class="inline"><a class="l_k" href="../functions/umask.html">umask</a></code>.<br>
</p>
<p>In many systems the <code class="inline"><span class="w">O_EXCL</span></code>
flag is available for opening files in<br>
exclusive mode. This is <b>not</b> locking: exclusiveness means here that<br>
if the file already exists, sysopen() fails. <code class="inline"><span class="w">O_EXCL</span></code>
may not work<br>
on network filesystems, and has no effect unless the <code class="inline"><span class="w">O_CREAT</span></code>
flag<br>
is set as well. Setting <code class="inline"><span class="w">O_CREAT</span>|<span class="w">O_EXCL</span></code>
prevents the file from<br>
being opened if it is a symbolic link. It does not protect against<br>
symbolic links in the file's path.<br>
</p>
<p>Sometimes you may want to truncate an already-existing file. This<br>
can be done using the <code class="inline"><span class="w">O_TRUNC</span></code>
flag. The behavior of<br>
<code class="inline"><span class="w">O_TRUNC</span></code>
with <code class="inline"><span class="w">O_RDONLY</span></code>
is undefined.<br>
</p>
<p>You should seldom if ever use <code class="inline"><span class="n">0644</span></code>
as argument to <code class="inline"><a class="l_k" href="../functions/sysopen.html">sysopen</a></code>, because<br>
that takes away the user's option to have a more permissive umask.<br>
Better to omit it. See the perlfunc(1) entry on <code class="inline"><a class="l_k" href="../functions/umask.html">umask</a></code> for more<br>
on this.</p>
<p>Note that <code class="inline"><a class="l_k" href="../functions/sysopen.html">sysopen</a></code> depends on the fdopen() C library function.<br>
On many UNIX systems, fdopen() is known to fail when file descriptors<br>
exceed a certain value, typically 255. If you need more file<br>
descriptors than that, consider rebuilding Perl to use the <code class="inline"><span class="w">sfio</span></code>
<br>
library, or perhaps using the POSIX::open() function.</p>
<p>See <a href="../perlopentut.html">perlopentut</a> for a kinder, gentler explanation of opening files.]]></desc>
</keyword>
<keyword name="sysopen" type="function">
<params>
<param name='filehandle'/>
<param name='filename'/>
<param name='mode'/>
</params>
<desc><![CDATA[Opens the file whose filename is given by FILENAME, and associates it<br>
with FILEHANDLE. If FILEHANDLE is an expression, its value is used as<br>
the name of the real filehandle wanted. This function calls the<br>
underlying operating system's <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> function with the parameters<br>
FILENAME, MODE, PERMS.</p>
<p>The possible values and flag bits of the MODE parameter are<br>
system-dependent; they are available via the standard module <code class="inline"><span class="w">Fcntl</span></code>
.<br>
See the documentation of your operating system's <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> to see which<br>
values and flag bits are available. You may combine several flags<br>
using the <code class="inline">|</code>-operator.</p>
<p>Some of the most common values are <code class="inline"><span class="w">O_RDONLY</span></code>
for opening the file in<br>
read-only mode, <code class="inline"><span class="w">O_WRONLY</span></code>
for opening the file in write-only mode,<br>
and <code class="inline"><span class="w">O_RDWR</span></code>
for opening the file in read-write mode.<br>
</p>
<p>For historical reasons, some values work on almost every system<br>
supported by perl: zero means read-only, one means write-only, and two<br>
means read/write. We know that these values do <i>not</i> work under<br>
OS/390 & VM/ESA Unix and on the Macintosh; you probably don't want to<br>
use them in new code.</p>
<p>If the file named by FILENAME does not exist and the <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> call creates<br>
it (typically because MODE includes the <code class="inline"><span class="w">O_CREAT</span></code>
flag), then the value of<br>
PERMS specifies the permissions of the newly created file. If you omit<br>
the PERMS argument to <code class="inline"><a class="l_k" href="../functions/sysopen.html">sysopen</a></code>, Perl uses the octal value <code class="inline"><span class="n">0666</span></code>
.<br>
These permission values need to be in octal, and are modified by your<br>
process's current <code class="inline"><a class="l_k" href="../functions/umask.html">umask</a></code>.<br>
</p>
<p>In many systems the <code class="inline"><span class="w">O_EXCL</span></code>
flag is available for opening files in<br>
exclusive mode. This is <b>not</b> locking: exclusiveness means here that<br>
if the file already exists, sysopen() fails. <code class="inline"><span class="w">O_EXCL</span></code>
may not work<br>
on network filesystems, and has no effect unless the <code class="inline"><span class="w">O_CREAT</span></code>
flag<br>
is set as well. Setting <code class="inline"><span class="w">O_CREAT</span>|<span class="w">O_EXCL</span></code>
prevents the file from<br>
being opened if it is a symbolic link. It does not protect against<br>
symbolic links in the file's path.<br>
</p>
<p>Sometimes you may want to truncate an already-existing file. This<br>
can be done using the <code class="inline"><span class="w">O_TRUNC</span></code>
flag. The behavior of<br>
<code class="inline"><span class="w">O_TRUNC</span></code>
with <code class="inline"><span class="w">O_RDONLY</span></code>
is undefined.<br>
</p>
<p>You should seldom if ever use <code class="inline"><span class="n">0644</span></code>
as argument to <code class="inline"><a class="l_k" href="../functions/sysopen.html">sysopen</a></code>, because<br>
that takes away the user's option to have a more permissive umask.<br>
Better to omit it. See the perlfunc(1) entry on <code class="inline"><a class="l_k" href="../functions/umask.html">umask</a></code> for more<br>
on this.</p>
<p>Note that <code class="inline"><a class="l_k" href="../functions/sysopen.html">sysopen</a></code> depends on the fdopen() C library function.<br>
On many UNIX systems, fdopen() is known to fail when file descriptors<br>
exceed a certain value, typically 255. If you need more file<br>
descriptors than that, consider rebuilding Perl to use the <code class="inline"><span class="w">sfio</span></code>
<br>
library, or perhaps using the POSIX::open() function.</p>
<p>See <a href="../perlopentut.html">perlopentut</a> for a kinder, gentler explanation of opening files.]]></desc>
</keyword>
<keyword name="sysread" type="function">
<params>
<param name='filehandle'/>
<param name='scalar'/>
<param name='length'/>
<param name='offset'/>
</params>
<desc><![CDATA[Attempts to read LENGTH bytes of data into variable SCALAR from the<br>
specified FILEHANDLE, using the system call read(2). It bypasses<br>
buffered IO, so mixing this with other kinds of reads, <code class="inline"><a class="l_k" href="../functions/print.html">print</a></code>,<br>
<code class="inline"><a class="l_k" href="../functions/write.html">write</a></code>, <code class="inline"><a class="l_k" href="../functions/seek.html">seek</a></code>, <code class="inline"><a class="l_k" href="../functions/tell.html">tell</a></code>, or <code class="inline"><a class="l_k" href="../functions/eof.html">eof</a></code> can cause confusion because the<br>
perlio or stdio layers usually buffers data. Returns the number of<br>
bytes actually read, <code class="inline"><span class="n">0</span></code>
at end of file, or undef if there was an<br>
error (in the latter case <code class="inline"><span class="i">$!</span></code>
is also set). SCALAR will be grown or<br>
shrunk so that the last byte actually read is the last byte of the<br>
scalar after the read.</p>
<p>An OFFSET may be specified to place the read data at some place in the<br>
string other than the beginning. A negative OFFSET specifies<br>
placement at that many characters counting backwards from the end of<br>
the string. A positive OFFSET greater than the length of SCALAR<br>
results in the string being padded to the required size with <code class="inline"><span class="q">"\0"</span></code>
<br>
bytes before the result of the read is appended.</p>
<p>There is no syseof() function, which is ok, since eof() doesn't work<br>
very well on device files (like ttys) anyway. Use sysread() and check<br>
for a return value for 0 to decide whether you're done.</p>
<p>Note that if the filehandle has been marked as <code class="inline"><span class="j">:</span><span class="w">utf8</span></code>
Unicode<br>
characters are read instead of bytes (the LENGTH, OFFSET, and the<br>
return value of sysread() are in Unicode characters).<br>
The <code class="inline"><span class="j">:</span><span class="i">encoding</span><span class="s">(</span>...<span class="s">)</span></code>
layer implicitly introduces the <code class="inline"><span class="j">:</span><span class="w">utf8</span></code>
layer.<br>
See <a href="../functions/binmode.html">"binmode"</a>, <a href="../functions/open.html">"open"</a>, and the <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> pragma, <a href="../open.html">open</a>.]]></desc>
</keyword>
<keyword name="sysread" type="function">
<params>
<param name='filehandle'/>
<param name='scalar'/>
<param name='length'/>
</params>
<desc><![CDATA[Attempts to read LENGTH bytes of data into variable SCALAR from the<br>
specified FILEHANDLE, using the system call read(2). It bypasses<br>
buffered IO, so mixing this with other kinds of reads, <code class="inline"><a class="l_k" href="../functions/print.html">print</a></code>,<br>
<code class="inline"><a class="l_k" href="../functions/write.html">write</a></code>, <code class="inline"><a class="l_k" href="../functions/seek.html">seek</a></code>, <code class="inline"><a class="l_k" href="../functions/tell.html">tell</a></code>, or <code class="inline"><a class="l_k" href="../functions/eof.html">eof</a></code> can cause confusion because the<br>
perlio or stdio layers usually buffers data. Returns the number of<br>
bytes actually read, <code class="inline"><span class="n">0</span></code>
at end of file, or undef if there was an<br>
error (in the latter case <code class="inline"><span class="i">$!</span></code>
is also set). SCALAR will be grown or<br>
shrunk so that the last byte actually read is the last byte of the<br>
scalar after the read.</p>
<p>An OFFSET may be specified to place the read data at some place in the<br>
string other than the beginning. A negative OFFSET specifies<br>
placement at that many characters counting backwards from the end of<br>
the string. A positive OFFSET greater than the length of SCALAR<br>
results in the string being padded to the required size with <code class="inline"><span class="q">"\0"</span></code>
<br>
bytes before the result of the read is appended.</p>
<p>There is no syseof() function, which is ok, since eof() doesn't work<br>
very well on device files (like ttys) anyway. Use sysread() and check<br>
for a return value for 0 to decide whether you're done.</p>
<p>Note that if the filehandle has been marked as <code class="inline"><span class="j">:</span><span class="w">utf8</span></code>
Unicode<br>
characters are read instead of bytes (the LENGTH, OFFSET, and the<br>
return value of sysread() are in Unicode characters).<br>
The <code class="inline"><span class="j">:</span><span class="i">encoding</span><span class="s">(</span>...<span class="s">)</span></code>
layer implicitly introduces the <code class="inline"><span class="j">:</span><span class="w">utf8</span></code>
layer.<br>
See <a href="../functions/binmode.html">"binmode"</a>, <a href="../functions/open.html">"open"</a>, and the <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> pragma, <a href="../open.html">open</a>.]]></desc>
</keyword>
<keyword name="sysseek" type="function">
<params>
<param name='filehandle'/>
<param name='position'/>
<param name='whence'/>
</params>
<desc><![CDATA[Sets FILEHANDLE's system position in bytes using the system call<br>
lseek(2). FILEHANDLE may be an expression whose value gives the name<br>
of the filehandle. The values for WHENCE are <code class="inline"><span class="n">0</span></code>
to set the new<br>
position to POSITION, <code class="inline"><span class="n">1</span></code>
to set the it to the current position plus<br>
POSITION, and <code class="inline"><span class="n">2</span></code>
to set it to EOF plus POSITION (typically<br>
negative).</p>
<p>Note the <i>in bytes</i>: even if the filehandle has been set to operate<br>
on characters (for example by using the <code class="inline"><span class="j">:</span><span class="i">encoding</span><span class="s">(</span><span class="w">utf8</span><span class="s">)</span></code>
I/O layer),<br>
tell() will return byte offsets, not character offsets (because<br>
implementing that would render sysseek() very slow).</p>
<p>sysseek() bypasses normal buffered IO, so mixing this with reads (other<br>
than <code class="inline"><a class="l_k" href="../functions/sysread.html">sysread</a></code>, for example <code class="inline"><></code>
or read()) <code class="inline"><a class="l_k" href="../functions/print.html">print</a></code>, <code class="inline"><a class="l_k" href="../functions/write.html">write</a></code>,<br>
<code class="inline"><a class="l_k" href="../functions/seek.html">seek</a></code>, <code class="inline"><a class="l_k" href="../functions/tell.html">tell</a></code>, or <code class="inline"><a class="l_k" href="../functions/eof.html">eof</a></code> may cause confusion.</p>
<p>For WHENCE, you may also use the constants <code class="inline"><span class="w">SEEK_SET</span></code>
, <code class="inline"><span class="w">SEEK_CUR</span></code>
,<br>
and <code class="inline"><span class="w">SEEK_END</span></code>
(start of the file, current position, end of the file)<br>
from the Fcntl module. Use of the constants is also more portable<br>
than relying on 0, 1, and 2. For example to define a "systell" function:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Fcntl</span> <span class="q">'SEEK_CUR'</span><span class="sc">;</span></li><li><a name="systell"></a> sub <span class="m">systell</span> <span class="s">{</span> <a class="l_k" href="../functions/sysseek.html">sysseek</a><span class="s">(</span><span class="i">$_</span>[<span class="n">0</span>]<span class="cm">,</span> <span class="n">0</span><span class="cm">,</span> <span class="w">SEEK_CUR</span><span class="s">)</span> <span class="s">}</span></li></ol></pre><p>Returns the new position, or the undefined value on failure. A position<br>
of zero is returned as the string <code class="inline"><span class="q">"0 but true"</span></code>
; thus <code class="inline"><a class="l_k" href="../functions/sysseek.html">sysseek</a></code> returns<br>
true on success and false on failure, yet you can still easily determine<br>
the new position.]]></desc>
</keyword>
<keyword name="system" type="function">
<params>
<param name='list'/>
</params>
<desc><![CDATA[Does exactly the same thing as <code class="inline"><a class="l_k" href="../functions/exec.html">exec</a> <span class="i">LIST</span></code>
, except that a fork is<br>
done first, and the parent process waits for the child process to<br>
complete. Note that argument processing varies depending on the<br>
number of arguments. If there is more than one argument in LIST,<br>
or if LIST is an array with more than one value, starts the program<br>
given by the first element of the list with arguments given by the<br>
rest of the list. If there is only one scalar argument, the argument<br>
is checked for shell metacharacters, and if there are any, the<br>
entire argument is passed to the system's command shell for parsing<br>
(this is <code class="inline">/bin/sh -c</code> on Unix platforms, but varies on other<br>
platforms). If there are no shell metacharacters in the argument,<br>
it is split into words and passed directly to <code class="inline"><span class="w">execvp</span></code>
, which is<br>
more efficient.</p>
<p>Beginning with v5.6.0, Perl will attempt to flush all files opened for<br>
output before any operation that may do a fork, but this may not be<br>
supported on some platforms (see <a href="../perlport.html">perlport</a>). To be safe, you may need<br>
to set <code class="inline"><span class="i">$|</span></code>
($AUTOFLUSH in English) or call the <code class="inline"><span class="i">autoflush</span><span class="s">(</span><span class="s">)</span></code>
method<br>
of <code class="inline"><span class="w">IO::Handle</span></code>
on any open handles.</p>
<p>The return value is the exit status of the program as returned by the<br>
<code class="inline"><a class="l_k" href="../functions/wait.html">wait</a></code> call. To get the actual exit value, shift right by eight (see<br>
below). See also <a href="../functions/exec.html">"exec"</a>. This is <i>not</i> what you want to use to capture<br>
the output from a command, for that you should use merely backticks or<br>
<code class="inline"><a class="l_k" href="../functions/qx.html">qx//</a></code>, as described in <a href="../perlop.html#%60STRING%60">"`STRING`" in perlop</a>. Return value of -1<br>
indicates a failure to start the program or an error of the wait(2) system<br>
call (inspect $! for the reason).</p>
<p>If you'd like to make <code class="inline"><a class="l_k" href="../functions/system.html">system</a></code> (and many other bits of Perl) die on error,<br>
have a look at the <a href="../autodie.html">autodie</a> pragma.</p>
<p>Like <code class="inline"><a class="l_k" href="../functions/exec.html">exec</a></code>, <code class="inline"><a class="l_k" href="../functions/system.html">system</a></code> allows you to lie to a program about its name if<br>
you use the <code class="inline"><a class="l_k" href="../functions/system.html">system</a> <span class="i">PROGRAM</span> <span class="w">LIST</span></code>
syntax. Again, see <a href="../functions/exec.html">"exec"</a>.</p>
<p>Since <code class="inline"><span class="w">SIGINT</span></code>
and <code class="inline"><span class="w">SIGQUIT</span></code>
are ignored during the execution of<br>
<code class="inline"><a class="l_k" href="../functions/system.html">system</a></code>, if you expect your program to terminate on receipt of these<br>
signals you will need to arrange to do so yourself based on the return<br>
value.</p>
<pre class="verbatim"><ol><li> <span class="i">@args</span> = <span class="s">(</span><span class="q">"command"</span><span class="cm">,</span> <span class="q">"arg1"</span><span class="cm">,</span> <span class="q">"arg2"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/system.html">system</a><span class="s">(</span><span class="i">@args</span><span class="s">)</span> == <span class="n">0</span></li><li> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"system @args failed: $?"</span></li></ol></pre><p>If you'd like to manually inspect <code class="inline"><a class="l_k" href="../functions/system.html">system</a></code>'s failure, you can check all<br>
possible failure modes by inspecting <code class="inline"><span class="i">$?</span></code>
like this:</p>
<pre class="verbatim"><ol><li> if <span class="s">(</span><span class="i">$?</span> == <span class="n">-1</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"failed to execute: $!\n"</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> elsif <span class="s">(</span><span class="i">$?</span> & <span class="n">127</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"child died with signal %d, %s coredump\n"</span><span class="cm">,</span></li><li> <span class="s">(</span><span class="i">$?</span> & <span class="n">127</span><span class="s">)</span><span class="cm">,</span> <span class="s">(</span><span class="i">$?</span> & <span class="n">128</span><span class="s">)</span> ? <span class="q">'with'</span> <span class="co">:</span> <span class="q">'without'</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> else <span class="s">{</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"child exited with value %d\n"</span><span class="cm">,</span> <span class="i">$?</span> >> <span class="n">8</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Alternatively you might inspect the value of <code class="inline"><span class="i">$</span>{<span class="w">^CHILD_ERROR_NATIVE</span>}</code>
<br>
with the W*() calls of the POSIX extension.</p>
<p>When the arguments get executed via the system shell, results<br>
and return codes will be subject to its quirks and capabilities.<br>
See <a href="../perlop.html#%60STRING%60">"`STRING`" in perlop</a> and <a href="../functions/exec.html">"exec"</a> for details.]]></desc>
</keyword>
<keyword name="system" type="function">
<params>
<param name='program list'/>
</params>
<desc><![CDATA[Does exactly the same thing as <code class="inline"><a class="l_k" href="../functions/exec.html">exec</a> <span class="i">LIST</span></code>
, except that a fork is<br>
done first, and the parent process waits for the child process to<br>
complete. Note that argument processing varies depending on the<br>
number of arguments. If there is more than one argument in LIST,<br>
or if LIST is an array with more than one value, starts the program<br>
given by the first element of the list with arguments given by the<br>
rest of the list. If there is only one scalar argument, the argument<br>
is checked for shell metacharacters, and if there are any, the<br>
entire argument is passed to the system's command shell for parsing<br>
(this is <code class="inline">/bin/sh -c</code> on Unix platforms, but varies on other<br>
platforms). If there are no shell metacharacters in the argument,<br>
it is split into words and passed directly to <code class="inline"><span class="w">execvp</span></code>
, which is<br>
more efficient.</p>
<p>Beginning with v5.6.0, Perl will attempt to flush all files opened for<br>
output before any operation that may do a fork, but this may not be<br>
supported on some platforms (see <a href="../perlport.html">perlport</a>). To be safe, you may need<br>
to set <code class="inline"><span class="i">$|</span></code>
($AUTOFLUSH in English) or call the <code class="inline"><span class="i">autoflush</span><span class="s">(</span><span class="s">)</span></code>
method<br>
of <code class="inline"><span class="w">IO::Handle</span></code>
on any open handles.</p>
<p>The return value is the exit status of the program as returned by the<br>
<code class="inline"><a class="l_k" href="../functions/wait.html">wait</a></code> call. To get the actual exit value, shift right by eight (see<br>
below). See also <a href="../functions/exec.html">"exec"</a>. This is <i>not</i> what you want to use to capture<br>
the output from a command, for that you should use merely backticks or<br>
<code class="inline"><a class="l_k" href="../functions/qx.html">qx//</a></code>, as described in <a href="../perlop.html#%60STRING%60">"`STRING`" in perlop</a>. Return value of -1<br>
indicates a failure to start the program or an error of the wait(2) system<br>
call (inspect $! for the reason).</p>
<p>If you'd like to make <code class="inline"><a class="l_k" href="../functions/system.html">system</a></code> (and many other bits of Perl) die on error,<br>
have a look at the <a href="../autodie.html">autodie</a> pragma.</p>
<p>Like <code class="inline"><a class="l_k" href="../functions/exec.html">exec</a></code>, <code class="inline"><a class="l_k" href="../functions/system.html">system</a></code> allows you to lie to a program about its name if<br>
you use the <code class="inline"><a class="l_k" href="../functions/system.html">system</a> <span class="i">PROGRAM</span> <span class="w">LIST</span></code>
syntax. Again, see <a href="../functions/exec.html">"exec"</a>.</p>
<p>Since <code class="inline"><span class="w">SIGINT</span></code>
and <code class="inline"><span class="w">SIGQUIT</span></code>
are ignored during the execution of<br>
<code class="inline"><a class="l_k" href="../functions/system.html">system</a></code>, if you expect your program to terminate on receipt of these<br>
signals you will need to arrange to do so yourself based on the return<br>
value.</p>
<pre class="verbatim"><ol><li> <span class="i">@args</span> = <span class="s">(</span><span class="q">"command"</span><span class="cm">,</span> <span class="q">"arg1"</span><span class="cm">,</span> <span class="q">"arg2"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/system.html">system</a><span class="s">(</span><span class="i">@args</span><span class="s">)</span> == <span class="n">0</span></li><li> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"system @args failed: $?"</span></li></ol></pre><p>If you'd like to manually inspect <code class="inline"><a class="l_k" href="../functions/system.html">system</a></code>'s failure, you can check all<br>
possible failure modes by inspecting <code class="inline"><span class="i">$?</span></code>
like this:</p>
<pre class="verbatim"><ol><li> if <span class="s">(</span><span class="i">$?</span> == <span class="n">-1</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"failed to execute: $!\n"</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> elsif <span class="s">(</span><span class="i">$?</span> & <span class="n">127</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"child died with signal %d, %s coredump\n"</span><span class="cm">,</span></li><li> <span class="s">(</span><span class="i">$?</span> & <span class="n">127</span><span class="s">)</span><span class="cm">,</span> <span class="s">(</span><span class="i">$?</span> & <span class="n">128</span><span class="s">)</span> ? <span class="q">'with'</span> <span class="co">:</span> <span class="q">'without'</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> else <span class="s">{</span></li><li> <a class="l_k" href="../functions/printf.html">printf</a> <span class="q">"child exited with value %d\n"</span><span class="cm">,</span> <span class="i">$?</span> >> <span class="n">8</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Alternatively you might inspect the value of <code class="inline"><span class="i">$</span>{<span class="w">^CHILD_ERROR_NATIVE</span>}</code>
<br>
with the W*() calls of the POSIX extension.</p>
<p>When the arguments get executed via the system shell, results<br>
and return codes will be subject to its quirks and capabilities.<br>
See <a href="../perlop.html#%60STRING%60">"`STRING`" in perlop</a> and <a href="../functions/exec.html">"exec"</a> for details.]]></desc>
</keyword>
<keyword name="syswrite" type="function">
<params>
<param name='filehandle'/>
<param name='scalar'/>
<param name='length'/>
<param name='offset'/>
</params>
<desc><![CDATA[Attempts to write LENGTH bytes of data from variable SCALAR to the<br>
specified FILEHANDLE, using the system call write(2). If LENGTH is<br>
not specified, writes whole SCALAR. It bypasses buffered IO, so<br>
mixing this with reads (other than <code class="inline"><a class="l_k" href="../functions/sysread.html">sysread())</a></code>, <code class="inline"><a class="l_k" href="../functions/print.html">print</a></code>, <code class="inline"><a class="l_k" href="../functions/write.html">write</a></code>,<br>
<code class="inline"><a class="l_k" href="../functions/seek.html">seek</a></code>, <code class="inline"><a class="l_k" href="../functions/tell.html">tell</a></code>, or <code class="inline"><a class="l_k" href="../functions/eof.html">eof</a></code> may cause confusion because the perlio and<br>
stdio layers usually buffers data. Returns the number of bytes<br>
actually written, or <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> if there was an error (in this case the<br>
errno variable <code class="inline"><span class="i">$!</span></code>
is also set). If the LENGTH is greater than the<br>
available data in the SCALAR after the OFFSET, only as much data as is<br>
available will be written.</p>
<p>An OFFSET may be specified to write the data from some part of the<br>
string other than the beginning. A negative OFFSET specifies writing<br>
that many characters counting backwards from the end of the string.<br>
In the case the SCALAR is empty you can use OFFSET but only zero offset.</p>
<p>Note that if the filehandle has been marked as <code class="inline"><span class="j">:</span><span class="w">utf8</span></code>
, Unicode<br>
characters are written instead of bytes (the LENGTH, OFFSET, and the<br>
return value of syswrite() are in UTF-8 encoded Unicode characters).<br>
The <code class="inline"><span class="j">:</span><span class="i">encoding</span><span class="s">(</span>...<span class="s">)</span></code>
layer implicitly introduces the <code class="inline"><span class="j">:</span><span class="w">utf8</span></code>
layer.<br>
See <a href="../functions/binmode.html">"binmode"</a>, <a href="../functions/open.html">"open"</a>, and the <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> pragma, <a href="../open.html">open</a>.]]></desc>
</keyword>
<keyword name="syswrite" type="function">
<params>
<param name='filehandle'/>
<param name='scalar'/>
<param name='length'/>
</params>
<desc><![CDATA[Attempts to write LENGTH bytes of data from variable SCALAR to the<br>
specified FILEHANDLE, using the system call write(2). If LENGTH is<br>
not specified, writes whole SCALAR. It bypasses buffered IO, so<br>
mixing this with reads (other than <code class="inline"><a class="l_k" href="../functions/sysread.html">sysread())</a></code>, <code class="inline"><a class="l_k" href="../functions/print.html">print</a></code>, <code class="inline"><a class="l_k" href="../functions/write.html">write</a></code>,<br>
<code class="inline"><a class="l_k" href="../functions/seek.html">seek</a></code>, <code class="inline"><a class="l_k" href="../functions/tell.html">tell</a></code>, or <code class="inline"><a class="l_k" href="../functions/eof.html">eof</a></code> may cause confusion because the perlio and<br>
stdio layers usually buffers data. Returns the number of bytes<br>
actually written, or <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> if there was an error (in this case the<br>
errno variable <code class="inline"><span class="i">$!</span></code>
is also set). If the LENGTH is greater than the<br>
available data in the SCALAR after the OFFSET, only as much data as is<br>
available will be written.</p>
<p>An OFFSET may be specified to write the data from some part of the<br>
string other than the beginning. A negative OFFSET specifies writing<br>
that many characters counting backwards from the end of the string.<br>
In the case the SCALAR is empty you can use OFFSET but only zero offset.</p>
<p>Note that if the filehandle has been marked as <code class="inline"><span class="j">:</span><span class="w">utf8</span></code>
, Unicode<br>
characters are written instead of bytes (the LENGTH, OFFSET, and the<br>
return value of syswrite() are in UTF-8 encoded Unicode characters).<br>
The <code class="inline"><span class="j">:</span><span class="i">encoding</span><span class="s">(</span>...<span class="s">)</span></code>
layer implicitly introduces the <code class="inline"><span class="j">:</span><span class="w">utf8</span></code>
layer.<br>
See <a href="../functions/binmode.html">"binmode"</a>, <a href="../functions/open.html">"open"</a>, and the <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> pragma, <a href="../open.html">open</a>.]]></desc>
</keyword>
<keyword name="syswrite" type="function">
<params>
<param name='filehandle'/>
<param name='scalar'/>
</params>
<desc><![CDATA[Attempts to write LENGTH bytes of data from variable SCALAR to the<br>
specified FILEHANDLE, using the system call write(2). If LENGTH is<br>
not specified, writes whole SCALAR. It bypasses buffered IO, so<br>
mixing this with reads (other than <code class="inline"><a class="l_k" href="../functions/sysread.html">sysread())</a></code>, <code class="inline"><a class="l_k" href="../functions/print.html">print</a></code>, <code class="inline"><a class="l_k" href="../functions/write.html">write</a></code>,<br>
<code class="inline"><a class="l_k" href="../functions/seek.html">seek</a></code>, <code class="inline"><a class="l_k" href="../functions/tell.html">tell</a></code>, or <code class="inline"><a class="l_k" href="../functions/eof.html">eof</a></code> may cause confusion because the perlio and<br>
stdio layers usually buffers data. Returns the number of bytes<br>
actually written, or <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> if there was an error (in this case the<br>
errno variable <code class="inline"><span class="i">$!</span></code>
is also set). If the LENGTH is greater than the<br>
available data in the SCALAR after the OFFSET, only as much data as is<br>
available will be written.</p>
<p>An OFFSET may be specified to write the data from some part of the<br>
string other than the beginning. A negative OFFSET specifies writing<br>
that many characters counting backwards from the end of the string.<br>
In the case the SCALAR is empty you can use OFFSET but only zero offset.</p>
<p>Note that if the filehandle has been marked as <code class="inline"><span class="j">:</span><span class="w">utf8</span></code>
, Unicode<br>
characters are written instead of bytes (the LENGTH, OFFSET, and the<br>
return value of syswrite() are in UTF-8 encoded Unicode characters).<br>
The <code class="inline"><span class="j">:</span><span class="i">encoding</span><span class="s">(</span>...<span class="s">)</span></code>
layer implicitly introduces the <code class="inline"><span class="j">:</span><span class="w">utf8</span></code>
layer.<br>
See <a href="../functions/binmode.html">"binmode"</a>, <a href="../functions/open.html">"open"</a>, and the <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> pragma, <a href="../open.html">open</a>.]]></desc>
</keyword>
<keyword name="tell" type="function">
<params>
<param name='filehandle'/>
</params>
<desc><![CDATA[Returns the current position <i>in bytes</i> for FILEHANDLE, or -1 on<br>
error. FILEHANDLE may be an expression whose value gives the name of<br>
the actual filehandle. If FILEHANDLE is omitted, assumes the file<br>
last read.</p>
<p>Note the <i>in bytes</i>: even if the filehandle has been set to<br>
operate on characters (for example by using the <code class="inline"><span class="j">:</span><span class="i">encoding</span><span class="s">(</span><span class="w">utf8</span><span class="s">)</span></code>
open<br>
layer), tell() will return byte offsets, not character offsets (because<br>
that would render seek() and tell() rather slow).</p>
<p>The return value of tell() for the standard streams like the STDIN<br>
depends on the operating system: it may return -1 or something else.<br>
tell() on pipes, fifos, and sockets usually returns -1.</p>
<p>There is no <code class="inline"><span class="w">systell</span></code>
function. Use <code class="inline"><a class="l_k" href="../functions/sysseek.html">sysseek</a><span class="s">(</span><span class="w">FH</span><span class="cm">,</span> <span class="n">0</span><span class="cm">,</span> <span class="n">1</span><span class="s">)</span></code>
for that.</p>
<p>Do not use tell() (or other buffered I/O operations) on a file handle<br>
that has been manipulated by sysread(), syswrite() or sysseek().<br>
Those functions ignore the buffering, while tell() does not.]]></desc>
</keyword>
<keyword name="tell" type="function">
<params>
</params>
<desc><![CDATA[Returns the current position <i>in bytes</i> for FILEHANDLE, or -1 on<br>
error. FILEHANDLE may be an expression whose value gives the name of<br>
the actual filehandle. If FILEHANDLE is omitted, assumes the file<br>
last read.</p>
<p>Note the <i>in bytes</i>: even if the filehandle has been set to<br>
operate on characters (for example by using the <code class="inline"><span class="j">:</span><span class="i">encoding</span><span class="s">(</span><span class="w">utf8</span><span class="s">)</span></code>
open<br>
layer), tell() will return byte offsets, not character offsets (because<br>
that would render seek() and tell() rather slow).</p>
<p>The return value of tell() for the standard streams like the STDIN<br>
depends on the operating system: it may return -1 or something else.<br>
tell() on pipes, fifos, and sockets usually returns -1.</p>
<p>There is no <code class="inline"><span class="w">systell</span></code>
function. Use <code class="inline"><a class="l_k" href="../functions/sysseek.html">sysseek</a><span class="s">(</span><span class="w">FH</span><span class="cm">,</span> <span class="n">0</span><span class="cm">,</span> <span class="n">1</span><span class="s">)</span></code>
for that.</p>
<p>Do not use tell() (or other buffered I/O operations) on a file handle<br>
that has been manipulated by sysread(), syswrite() or sysseek().<br>
Those functions ignore the buffering, while tell() does not.]]></desc>
</keyword>
<keyword name="telldir" type="function">
<params>
<param name='dirhandle'/>
</params>
<desc><![CDATA[Returns the current position of the <code class="inline"><a class="l_k" href="../functions/readdir.html">readdir</a></code> routines on DIRHANDLE.<br>
Value may be given to <code class="inline"><a class="l_k" href="../functions/seekdir.html">seekdir</a></code> to access a particular location in a<br>
directory. <code class="inline"><a class="l_k" href="../functions/telldir.html">telldir</a></code> has the same caveats about possible directory<br>
compaction as the corresponding system library routine.]]></desc>
</keyword>
<keyword name="tie" type="function">
<params>
<param name='variable'/>
<param name='classname'/>
<param name='list'/>
</params>
<desc><![CDATA[This function binds a variable to a package class that will provide the<br>
implementation for the variable. VARIABLE is the name of the variable<br>
to be enchanted. CLASSNAME is the name of a class implementing objects<br>
of correct type. Any additional arguments are passed to the <code class="inline"><span class="w">new</span></code>
<br>
method of the class (meaning <code class="inline"><span class="w">TIESCALAR</span></code>
, <code class="inline"><span class="w">TIEHANDLE</span></code>
, <code class="inline"><span class="w">TIEARRAY</span></code>
,<br>
or <code class="inline"><span class="w">TIEHASH</span></code>
). Typically these are arguments such as might be passed<br>
to the <code class="inline"><span class="i">dbm_open</span><span class="s">(</span><span class="s">)</span></code>
function of C. The object returned by the <code class="inline"><span class="w">new</span></code>
<br>
method is also returned by the <code class="inline"><a class="l_k" href="../functions/tie.html">tie</a></code> function, which would be useful<br>
if you want to access other methods in CLASSNAME.</p>
<p>Note that functions such as <code class="inline"><a class="l_k" href="../functions/keys.html">keys</a></code> and <code class="inline"><a class="l_k" href="../functions/values.html">values</a></code> may return huge lists<br>
when used on large objects, like DBM files. You may prefer to use the<br>
<code class="inline"><a class="l_k" href="../functions/each.html">each</a></code> function to iterate over such. Example:</p>
<pre class="verbatim"><ol><li> <span class="c"># print out history file offsets</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">NDBM_File</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/tie.html">tie</a><span class="s">(</span><span class="i">%HIST</span><span class="cm">,</span> <span class="q">'NDBM_File'</span><span class="cm">,</span> <span class="q">'/usr/lib/news/history'</span><span class="cm">,</span> <span class="n">1</span><span class="cm">,</span> <span class="n">0</span><span class="s">)</span><span class="sc">;</span></li><li> while <span class="s">(</span><span class="s">(</span><span class="i">$key</span><span class="cm">,</span><span class="i">$val</span><span class="s">)</span> = <a class="l_k" href="../functions/each.html">each</a> <span class="i">%HIST</span><span class="s">)</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">$key</span><span class="cm">,</span> <span class="q">' = '</span><span class="cm">,</span> <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">'L'</span><span class="cm">,</span><span class="i">$val</span><span class="s">)</span><span class="cm">,</span> <span class="q">"\n"</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> <a class="l_k" href="../functions/untie.html">untie</a><span class="s">(</span><span class="i">%HIST</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>A class implementing a hash should have the following methods:</p>
<pre class="verbatim"><ol><li> <span class="w">TIEHASH</span> <span class="w">classname</span><span class="cm">,</span> <span class="w">LIST</span></li><li> <span class="w">FETCH</span> <span class="w">this</span><span class="cm">,</span> <span class="w">key</span></li><li> <span class="w">STORE</span> <span class="w">this</span><span class="cm">,</span> <span class="w">key</span><span class="cm">,</span> <span class="w">value</span></li><li> <span class="w">DELETE</span> <span class="w">this</span><span class="cm">,</span> <span class="w">key</span></li><li> <span class="w">CLEAR</span> <span class="w">this</span></li><li> <span class="w">EXISTS</span> <span class="w">this</span><span class="cm">,</span> <span class="w">key</span></li><li> <span class="w">FIRSTKEY</span> <span class="w">this</span></li><li> <span class="w">NEXTKEY</span> <span class="w">this</span><span class="cm">,</span> <span class="w">lastkey</span></li><li> <span class="w">SCALAR</span> <span class="w">this</span></li><li> DESTROY <span class="w">this</span></li><li> <span class="w">UNTIE</span> <span class="w">this</span></li></ol></pre><p>A class implementing an ordinary array should have the following methods:</p>
<pre class="verbatim"><ol><li> <span class="w">TIEARRAY</span> <span class="w">classname</span><span class="cm">,</span> <span class="w">LIST</span></li><li> <span class="w">FETCH</span> <span class="w">this</span><span class="cm">,</span> <span class="w">key</span></li><li> <span class="w">STORE</span> <span class="w">this</span><span class="cm">,</span> <span class="w">key</span><span class="cm">,</span> <span class="w">value</span></li><li> <span class="w">FETCHSIZE</span> <span class="w">this</span></li><li> <span class="w">STORESIZE</span> <span class="w">this</span><span class="cm">,</span> <span class="w">count</span></li><li> <span class="w">CLEAR</span> <span class="w">this</span></li><li> <span class="w">PUSH</span> <span class="w">this</span><span class="cm">,</span> <span class="w">LIST</span></li><li> <span class="w">POP</span> <span class="w">this</span></li><li> <span class="w">SHIFT</span> <span class="w">this</span></li><li> <span class="w">UNSHIFT</span> <span class="w">this</span><span class="cm">,</span> <span class="w">LIST</span></li><li> <span class="w">SPLICE</span> <span class="w">this</span><span class="cm">,</span> <span class="w">offset</span><span class="cm">,</span> <a class="l_k" href="../functions/length.html">length</a><span class="cm">,</span> <span class="w">LIST</span></li><li> <span class="w">EXTEND</span> <span class="w">this</span><span class="cm">,</span> <span class="w">count</span></li><li> DESTROY <span class="w">this</span></li><li> <span class="w">UNTIE</span> <span class="w">this</span></li></ol></pre><p>A class implementing a file handle should have the following methods:</p>
<pre class="verbatim"><ol><li> TIEHANDLE classname, LIST</li><li> READ this, scalar, length, offset</li><li> READLINE this</li><li> GETC this</li><li> WRITE this, scalar, length, offset</li><li> PRINT this, LIST</li><li> PRINTF this, format, LIST</li><li> BINMODE this</li><li> EOF this</li><li> FILENO this</li><li> SEEK this, position, whence</li><li> TELL this</li><li> OPEN this, mode, LIST</li><li> CLOSE this</li><li> DESTROY this</li><li> UNTIE this</li></ol></pre><p>A class implementing a scalar should have the following methods:</p>
<pre class="verbatim"><ol><li> <span class="w">TIESCALAR</span> <span class="w">classname</span><span class="cm">,</span> <span class="w">LIST</span></li><li> <span class="w">FETCH</span> <span class="w">this</span><span class="cm">,</span></li><li> <span class="w">STORE</span> <span class="w">this</span><span class="cm">,</span> <span class="w">value</span></li><li> DESTROY <span class="w">this</span></li><li> <span class="w">UNTIE</span> <span class="w">this</span></li></ol></pre><p>Not all methods indicated above need be implemented. See <a href="../perltie.html">perltie</a>,<br>
<a href="../Tie/Hash.html">Tie::Hash</a>, <a href="../Tie/Array.html">Tie::Array</a>, <a href="../Tie/Scalar.html">Tie::Scalar</a>, and <a href="../Tie/Handle.html">Tie::Handle</a>.</p>
<p>Unlike <code class="inline"><a class="l_k" href="../functions/dbmopen.html">dbmopen</a></code>, the <code class="inline"><a class="l_k" href="../functions/tie.html">tie</a></code> function will not use or require a module<br>
for you--you need to do that explicitly yourself. See <a href="../DB_File.html">DB_File</a>
or the <i>Config</i> module for interesting <code class="inline"><a class="l_k" href="../functions/tie.html">tie</a></code> implementations.</p>
<p>For further details see <a href="../perltie.html">perltie</a>, <a href="#tied-VARIABLE">"tied VARIABLE"</a>.]]></desc>
</keyword>
<keyword name="tied" type="function">
<params>
<param name='variable'/>
</params>
<desc><![CDATA[Returns a reference to the object underlying VARIABLE (the same value<br>
that was originally returned by the <code class="inline"><a class="l_k" href="../functions/tie.html">tie</a></code> call that bound the variable<br>
to a package.) Returns the undefined value if VARIABLE isn't tied to a<br>
package.]]></desc>
</keyword>
<keyword name="time" type="function">
<params>
</params>
<desc><![CDATA[Returns the number of non-leap seconds since whatever time the system<br>
considers to be the epoch, suitable for feeding to <code class="inline"><a class="l_k" href="../functions/gmtime.html">gmtime</a></code> and<br>
<code class="inline"><a class="l_k" href="../functions/localtime.html">localtime</a></code>. On most systems the epoch is 00:00:00 UTC, January 1, 1970;<br>
a prominent exception being Mac OS Classic which uses 00:00:00, January 1,<br>
1904 in the current local time zone for its epoch.</p>
<p>For measuring time in better granularity than one second,<br>
you may use either the <a href="../Time/HiRes.html">Time::HiRes</a> module (from CPAN, and starting from<br>
Perl 5.8 part of the standard distribution), or if you have<br>
gettimeofday(2), you may be able to use the <code class="inline"><a class="l_k" href="../functions/syscall.html">syscall</a></code> interface of Perl.<br>
See <a href="../perlfaq8.html">perlfaq8</a> for details.</p>
<p>For date and time processing look at the many related modules on CPAN.<br>
For a comprehensive date and time representation look at the<br>
<a href="http://search.cpan.org/perldoc/DateTime">DateTime</a> module.]]></desc>
</keyword>
<keyword name="times" type="function">
<params>
</params>
<desc><![CDATA[Returns a four-element list giving the user and system times, in<br>
seconds, for this process and the children of this process.</p>
<pre class="verbatim"><ol><li> <span class="s">(</span><span class="i">$user</span><span class="cm">,</span><span class="i">$system</span><span class="cm">,</span><span class="i">$cuser</span><span class="cm">,</span><span class="i">$csystem</span><span class="s">)</span> = <a class="l_k" href="../functions/times.html">times</a><span class="sc">;</span></li></ol></pre><p>In scalar context, <code class="inline"><a class="l_k" href="../functions/times.html">times</a></code> returns <code class="inline"><span class="i">$user</span></code>
.</p>
<p>Note that times for children are included only after they terminate.]]></desc>
</keyword>
<keyword name="tr" type="function">
<params>
<param name='///'/>
</params>
<desc><![CDATA[The transliteration operator. Same as <code class="inline"><a class="l_k" href="../functions/y.html">y///</a></code>. See<br>
<a href="../perlop.html#Quote-and-Quote-like-Operators">"Quote and Quote-like Operators" in perlop</a>.]]></desc>
</keyword>
<keyword name="truncate" type="function">
<params>
<param name='expr'/>
<param name='length'/>
</params>
<desc><![CDATA[Truncates the file opened on FILEHANDLE, or named by EXPR, to the<br>
specified length. Produces a fatal error if truncate isn't implemented<br>
on your system. Returns true if successful, the undefined value<br>
otherwise.</p>
<p>The behavior is undefined if LENGTH is greater than the length of the<br>
file.</p>
<p>The position in the file of FILEHANDLE is left unchanged. You may want to<br>
call <a href="../functions/seek.html">seek</a> before writing to the file.]]></desc>
</keyword>
<keyword name="truncate" type="function">
<params>
<param name='filehandle'/>
<param name='length'/>
</params>
<desc><![CDATA[Truncates the file opened on FILEHANDLE, or named by EXPR, to the<br>
specified length. Produces a fatal error if truncate isn't implemented<br>
on your system. Returns true if successful, the undefined value<br>
otherwise.</p>
<p>The behavior is undefined if LENGTH is greater than the length of the<br>
file.</p>
<p>The position in the file of FILEHANDLE is left unchanged. You may want to<br>
call <a href="../functions/seek.html">seek</a> before writing to the file.]]></desc>
</keyword>
<keyword name="uc" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Returns an uppercased version of EXPR. This is the internal function<br>
implementing the <code class="inline">\<span class="w">U</span></code>
escape in double-quoted strings. Respects<br>
current LC_CTYPE locale if <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">locale</span></code>
in force. See <a href="../perllocale.html">perllocale</a>
and <a href="../perlunicode.html">perlunicode</a> for more details about locale and Unicode support.<br>
It does not attempt to do titlecase mapping on initial letters. See<br>
<code class="inline"><a class="l_k" href="../functions/ucfirst.html">ucfirst</a></code> for that.</p>
<p>If EXPR is omitted, uses <code class="inline"><span class="i">$_</span></code>
.]]></desc>
</keyword>
<keyword name="uc" type="function">
<params>
</params>
<desc><![CDATA[Returns an uppercased version of EXPR. This is the internal function<br>
implementing the <code class="inline">\<span class="w">U</span></code>
escape in double-quoted strings. Respects<br>
current LC_CTYPE locale if <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">locale</span></code>
in force. See <a href="../perllocale.html">perllocale</a>
and <a href="../perlunicode.html">perlunicode</a> for more details about locale and Unicode support.<br>
It does not attempt to do titlecase mapping on initial letters. See<br>
<code class="inline"><a class="l_k" href="../functions/ucfirst.html">ucfirst</a></code> for that.</p>
<p>If EXPR is omitted, uses <code class="inline"><span class="i">$_</span></code>
.]]></desc>
</keyword>
<keyword name="ucfirst" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Returns the value of EXPR with the first character in uppercase<br>
(titlecase in Unicode). This is the internal function implementing<br>
the <code class="inline">\<span class="w">u</span></code>
escape in double-quoted strings. Respects current LC_CTYPE<br>
locale if <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">locale</span></code>
in force. See <a href="../perllocale.html">perllocale</a> and <a href="../perlunicode.html">perlunicode</a>
for more details about locale and Unicode support.</p>
<p>If EXPR is omitted, uses <code class="inline"><span class="i">$_</span></code>
.]]></desc>
</keyword>
<keyword name="ucfirst" type="function">
<params>
</params>
<desc><![CDATA[Returns the value of EXPR with the first character in uppercase<br>
(titlecase in Unicode). This is the internal function implementing<br>
the <code class="inline">\<span class="w">u</span></code>
escape in double-quoted strings. Respects current LC_CTYPE<br>
locale if <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">locale</span></code>
in force. See <a href="../perllocale.html">perllocale</a> and <a href="../perlunicode.html">perlunicode</a>
for more details about locale and Unicode support.</p>
<p>If EXPR is omitted, uses <code class="inline"><span class="i">$_</span></code>
.]]></desc>
</keyword>
<keyword name="umask" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Sets the umask for the process to EXPR and returns the previous value.<br>
If EXPR is omitted, merely returns the current umask.</p>
<p>The Unix permission <code class="inline"><span class="w">rwxr</span>-x---</code>
is represented as three sets of three<br>
bits, or three octal digits: <code class="inline"><span class="n">0750</span></code>
(the leading 0 indicates octal<br>
and isn't one of the digits). The <code class="inline"><a class="l_k" href="../functions/umask.html">umask</a></code> value is such a number<br>
representing disabled permissions bits. The permission (or "mode")<br>
values you pass <code class="inline"><a class="l_k" href="../functions/mkdir.html">mkdir</a></code> or <code class="inline"><a class="l_k" href="../functions/sysopen.html">sysopen</a></code> are modified by your umask, so<br>
even if you tell <code class="inline"><a class="l_k" href="../functions/sysopen.html">sysopen</a></code> to create a file with permissions <code class="inline"><span class="n">0777</span></code>
,<br>
if your umask is <code class="inline"><span class="n">0022</span></code>
then the file will actually be created with<br>
permissions <code class="inline"><span class="n">0755</span></code>
. If your <code class="inline"><a class="l_k" href="../functions/umask.html">umask</a></code> were <code class="inline"><span class="n">0027</span></code>
(group can't<br>
write; others can't read, write, or execute), then passing<br>
<code class="inline"><a class="l_k" href="../functions/sysopen.html">sysopen</a></code> <code class="inline"><span class="n">0666</span></code>
would create a file with mode <code class="inline"><span class="n">0640</span></code>
(<code class="inline"><span class="n">0666</span> &~<br>
<span class="n">027</span></code>
is <code class="inline"><span class="n">0640</span></code>
).</p>
<p>Here's some advice: supply a creation mode of <code class="inline"><span class="n">0666</span></code>
for regular<br>
files (in <code class="inline"><a class="l_k" href="../functions/sysopen.html">sysopen</a></code>) and one of <code class="inline"><span class="n">0777</span></code>
for directories (in<br>
<code class="inline"><a class="l_k" href="../functions/mkdir.html">mkdir</a></code>) and executable files. This gives users the freedom of<br>
choice: if they want protected files, they might choose process umasks<br>
of <code class="inline"><span class="n">022</span></code>
, <code class="inline"><span class="n">027</span></code>
, or even the particularly antisocial mask of <code class="inline"><span class="n">077</span></code>
.<br>
Programs should rarely if ever make policy decisions better left to<br>
the user. The exception to this is when writing files that should be<br>
kept private: mail files, web browser cookies, <i>.rhosts</i> files, and<br>
so on.</p>
<p>If umask(2) is not implemented on your system and you are trying to<br>
restrict access for <i>yourself</i> (i.e., (EXPR & 0700) > 0), produces a<br>
fatal error at run time. If umask(2) is not implemented and you are<br>
not trying to restrict access for yourself, returns <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code>.</p>
<p>Remember that a umask is a number, usually given in octal; it is <i>not</i> a<br>
string of octal digits. See also <a href="../functions/oct.html">"oct"</a>, if all you have is a string.]]></desc>
</keyword>
<keyword name="umask" type="function">
<params>
</params>
<desc><![CDATA[Sets the umask for the process to EXPR and returns the previous value.<br>
If EXPR is omitted, merely returns the current umask.</p>
<p>The Unix permission <code class="inline"><span class="w">rwxr</span>-x---</code>
is represented as three sets of three<br>
bits, or three octal digits: <code class="inline"><span class="n">0750</span></code>
(the leading 0 indicates octal<br>
and isn't one of the digits). The <code class="inline"><a class="l_k" href="../functions/umask.html">umask</a></code> value is such a number<br>
representing disabled permissions bits. The permission (or "mode")<br>
values you pass <code class="inline"><a class="l_k" href="../functions/mkdir.html">mkdir</a></code> or <code class="inline"><a class="l_k" href="../functions/sysopen.html">sysopen</a></code> are modified by your umask, so<br>
even if you tell <code class="inline"><a class="l_k" href="../functions/sysopen.html">sysopen</a></code> to create a file with permissions <code class="inline"><span class="n">0777</span></code>
,<br>
if your umask is <code class="inline"><span class="n">0022</span></code>
then the file will actually be created with<br>
permissions <code class="inline"><span class="n">0755</span></code>
. If your <code class="inline"><a class="l_k" href="../functions/umask.html">umask</a></code> were <code class="inline"><span class="n">0027</span></code>
(group can't<br>
write; others can't read, write, or execute), then passing<br>
<code class="inline"><a class="l_k" href="../functions/sysopen.html">sysopen</a></code> <code class="inline"><span class="n">0666</span></code>
would create a file with mode <code class="inline"><span class="n">0640</span></code>
(<code class="inline"><span class="n">0666</span> &~<br>
<span class="n">027</span></code>
is <code class="inline"><span class="n">0640</span></code>
).</p>
<p>Here's some advice: supply a creation mode of <code class="inline"><span class="n">0666</span></code>
for regular<br>
files (in <code class="inline"><a class="l_k" href="../functions/sysopen.html">sysopen</a></code>) and one of <code class="inline"><span class="n">0777</span></code>
for directories (in<br>
<code class="inline"><a class="l_k" href="../functions/mkdir.html">mkdir</a></code>) and executable files. This gives users the freedom of<br>
choice: if they want protected files, they might choose process umasks<br>
of <code class="inline"><span class="n">022</span></code>
, <code class="inline"><span class="n">027</span></code>
, or even the particularly antisocial mask of <code class="inline"><span class="n">077</span></code>
.<br>
Programs should rarely if ever make policy decisions better left to<br>
the user. The exception to this is when writing files that should be<br>
kept private: mail files, web browser cookies, <i>.rhosts</i> files, and<br>
so on.</p>
<p>If umask(2) is not implemented on your system and you are trying to<br>
restrict access for <i>yourself</i> (i.e., (EXPR & 0700) > 0), produces a<br>
fatal error at run time. If umask(2) is not implemented and you are<br>
not trying to restrict access for yourself, returns <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code>.</p>
<p>Remember that a umask is a number, usually given in octal; it is <i>not</i> a<br>
string of octal digits. See also <a href="../functions/oct.html">"oct"</a>, if all you have is a string.]]></desc>
</keyword>
<keyword name="undef" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Undefines the value of EXPR, which must be an lvalue. Use only on a<br>
scalar value, an array (using <code class="inline"><span class="i">@</span></code>
), a hash (using <code class="inline"><span class="i">%</span></code>
), a subroutine<br>
(using <code class="inline"><span class="i">&</span></code>
), or a typeglob (using <code class="inline"><span class="i">*</span></code>
). (Saying <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a> <span class="i">$hash</span>{<span class="i">$key</span>}</code>
<br>
will probably not do what you expect on most predefined variables or<br>
DBM list values, so don't do that; see <a href="../functions/delete.html">delete</a>.) Always returns the<br>
undefined value. You can omit the EXPR, in which case nothing is<br>
undefined, but you still get an undefined value that you could, for<br>
instance, return from a subroutine, assign to a variable or pass as a<br>
parameter. Examples:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/undef.html">undef</a> <span class="i">$foo</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/undef.html">undef</a> <span class="i">$bar</span>{<span class="q">'blurfl'</span>}<span class="sc">;</span> <span class="c"># Compare to: delete $bar{'blurfl'};</span></li><li> <a class="l_k" href="../functions/undef.html">undef</a> <span class="i">@ary</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/undef.html">undef</a> <span class="i">%hash</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/undef.html">undef</a> <span class="i">&mysub</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/undef.html">undef</a> <span class="i">*xyz</span><span class="sc">;</span> <span class="c"># destroys $xyz, @xyz, %xyz, &xyz, etc.</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <span class="s">(</span><a class="l_k" href="../functions/wantarray.html">wantarray</a> ? <span class="s">(</span><a class="l_k" href="../functions/undef.html">undef</a><span class="cm">,</span> <span class="i">$errmsg</span><span class="s">)</span> <span class="co">:</span> <a class="l_k" href="../functions/undef.html">undef</a><span class="s">)</span> if <span class="i">$they_blew_it</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/select.html">select</a> <a class="l_k" href="../functions/undef.html">undef</a><span class="cm">,</span> <a class="l_k" href="../functions/undef.html">undef</a><span class="cm">,</span> <a class="l_k" href="../functions/undef.html">undef</a><span class="cm">,</span> <span class="n">0.25</span><span class="sc">;</span></li><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span> <span class="i">$b</span><span class="cm">,</span> <a class="l_k" href="../functions/undef.html">undef</a><span class="cm">,</span> <span class="i">$c</span><span class="s">)</span> = <span class="i">&foo</span><span class="sc">;</span> <span class="c"># Ignore third value returned</span></li></ol></pre><p>Note that this is a unary operator, not a list operator.]]></desc>
</keyword>
<keyword name="undef" type="function">
<params>
</params>
<desc><![CDATA[Undefines the value of EXPR, which must be an lvalue. Use only on a<br>
scalar value, an array (using <code class="inline"><span class="i">@</span></code>
), a hash (using <code class="inline"><span class="i">%</span></code>
), a subroutine<br>
(using <code class="inline"><span class="i">&</span></code>
), or a typeglob (using <code class="inline"><span class="i">*</span></code>
). (Saying <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a> <span class="i">$hash</span>{<span class="i">$key</span>}</code>
<br>
will probably not do what you expect on most predefined variables or<br>
DBM list values, so don't do that; see <a href="../functions/delete.html">delete</a>.) Always returns the<br>
undefined value. You can omit the EXPR, in which case nothing is<br>
undefined, but you still get an undefined value that you could, for<br>
instance, return from a subroutine, assign to a variable or pass as a<br>
parameter. Examples:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/undef.html">undef</a> <span class="i">$foo</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/undef.html">undef</a> <span class="i">$bar</span>{<span class="q">'blurfl'</span>}<span class="sc">;</span> <span class="c"># Compare to: delete $bar{'blurfl'};</span></li><li> <a class="l_k" href="../functions/undef.html">undef</a> <span class="i">@ary</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/undef.html">undef</a> <span class="i">%hash</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/undef.html">undef</a> <span class="i">&mysub</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/undef.html">undef</a> <span class="i">*xyz</span><span class="sc">;</span> <span class="c"># destroys $xyz, @xyz, %xyz, &xyz, etc.</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <span class="s">(</span><a class="l_k" href="../functions/wantarray.html">wantarray</a> ? <span class="s">(</span><a class="l_k" href="../functions/undef.html">undef</a><span class="cm">,</span> <span class="i">$errmsg</span><span class="s">)</span> <span class="co">:</span> <a class="l_k" href="../functions/undef.html">undef</a><span class="s">)</span> if <span class="i">$they_blew_it</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/select.html">select</a> <a class="l_k" href="../functions/undef.html">undef</a><span class="cm">,</span> <a class="l_k" href="../functions/undef.html">undef</a><span class="cm">,</span> <a class="l_k" href="../functions/undef.html">undef</a><span class="cm">,</span> <span class="n">0.25</span><span class="sc">;</span></li><li> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span> <span class="i">$b</span><span class="cm">,</span> <a class="l_k" href="../functions/undef.html">undef</a><span class="cm">,</span> <span class="i">$c</span><span class="s">)</span> = <span class="i">&foo</span><span class="sc">;</span> <span class="c"># Ignore third value returned</span></li></ol></pre><p>Note that this is a unary operator, not a list operator.]]></desc>
</keyword>
<keyword name="unlink" type="function">
<params>
<param name='list'/>
</params>
<desc><![CDATA[Deletes a list of files. Returns the number of files successfully<br>
deleted.</p>
<pre class="verbatim"><ol><li> <span class="i">$cnt</span> = <a class="l_k" href="../functions/unlink.html">unlink</a> <span class="q">'a'</span><span class="cm">,</span> <span class="q">'b'</span><span class="cm">,</span> <span class="q">'c'</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/unlink.html">unlink</a> <span class="i">@goners</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/unlink.html">unlink</a> <span class="q"><*.bak></span><span class="sc">;</span></li></ol></pre><p>Note: <code class="inline"><a class="l_k" href="../functions/unlink.html">unlink</a></code> will not attempt to delete directories unless you are superuser<br>
and the <b>-U</b> flag is supplied to Perl. Even if these conditions are<br>
met, be warned that unlinking a directory can inflict damage on your<br>
filesystem. Finally, using <code class="inline"><a class="l_k" href="../functions/unlink.html">unlink</a></code> on directories is not supported on <br>
many operating systems. Use <code class="inline"><a class="l_k" href="../functions/rmdir.html">rmdir</a></code> instead.</p>
<p>If LIST is omitted, uses <code class="inline"><span class="i">$_</span></code>
.]]></desc>
</keyword>
<keyword name="unlink" type="function">
<params>
</params>
<desc><![CDATA[Deletes a list of files. Returns the number of files successfully<br>
deleted.</p>
<pre class="verbatim"><ol><li> <span class="i">$cnt</span> = <a class="l_k" href="../functions/unlink.html">unlink</a> <span class="q">'a'</span><span class="cm">,</span> <span class="q">'b'</span><span class="cm">,</span> <span class="q">'c'</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/unlink.html">unlink</a> <span class="i">@goners</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/unlink.html">unlink</a> <span class="q"><*.bak></span><span class="sc">;</span></li></ol></pre><p>Note: <code class="inline"><a class="l_k" href="../functions/unlink.html">unlink</a></code> will not attempt to delete directories unless you are superuser<br>
and the <b>-U</b> flag is supplied to Perl. Even if these conditions are<br>
met, be warned that unlinking a directory can inflict damage on your<br>
filesystem. Finally, using <code class="inline"><a class="l_k" href="../functions/unlink.html">unlink</a></code> on directories is not supported on <br>
many operating systems. Use <code class="inline"><a class="l_k" href="../functions/rmdir.html">rmdir</a></code> instead.</p>
<p>If LIST is omitted, uses <code class="inline"><span class="i">$_</span></code>
.]]></desc>
</keyword>
<keyword name="unpack" type="function">
<params>
<param name='template'/>
<param name='expr'/>
</params>
<desc><![CDATA[<code class="inline"><a class="l_k" href="../functions/unpack.html">unpack</a></code> does the reverse of <code class="inline"><a class="l_k" href="../functions/pack.html">pack</a></code>: it takes a string<br>
and expands it out into a list of values.<br>
(In scalar context, it returns merely the first value produced.)</p>
<p>If EXPR is omitted, unpacks the <code class="inline"><span class="i">$_</span></code>
string.</p>
<p>The string is broken into chunks described by the TEMPLATE. Each chunk<br>
is converted separately to a value. Typically, either the string is a result<br>
of <code class="inline"><a class="l_k" href="../functions/pack.html">pack</a></code>, or the characters of the string represent a C structure of some<br>
kind.</p>
<p>The TEMPLATE has the same format as in the <code class="inline"><a class="l_k" href="../functions/pack.html">pack</a></code> function.<br>
Here's a subroutine that does substring:</p>
<pre class="verbatim"><ol><li><a name="substr"></a> sub <span class="m">substr</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/my.html">my</a><span class="s">(</span><span class="i">$what</span><span class="cm">,</span><span class="i">$where</span><span class="cm">,</span><span class="i">$howmuch</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">"x$where a$howmuch"</span><span class="cm">,</span> <span class="i">$what</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>and then there's</p>
<pre class="verbatim"><ol><li><a name="ordinal"></a> sub <span class="m">ordinal</span> <span class="s">{</span> <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">"W"</span><span class="cm">,</span><span class="i">$_</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span> <span class="s">}</span> <span class="c"># same as ord()</span></li></ol></pre><p>In addition to fields allowed in pack(), you may prefix a field with<br>
a %<number> to indicate that<br>
you want a <number>-bit checksum of the items instead of the items<br>
themselves. Default is a 16-bit checksum. Checksum is calculated by<br>
summing numeric values of expanded values (for string fields the sum of<br>
<code class="inline"><a class="l_k" href="../functions/ord.html">ord($char)</a></code> is taken, for bit fields the sum of zeroes and ones).</p>
<p>For example, the following<br>
computes the same number as the System V sum program:</p>
<pre class="verbatim"><ol><li> <span class="i">$checksum</span> = <a class="l_k" href="../functions/do.html">do</a> <span class="s">{</span></li><li> <a class="l_k" href="../functions/local.html">local</a> <span class="i">$/</span><span class="sc">;</span> <span class="c"># slurp!</span></li><li> <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">"%32W*"</span><span class="cm">,</span><><span class="s">)</span> % <span class="n">65535</span><span class="sc">;</span></li><li> <span class="s">}</span><span class="sc">;</span></li></ol></pre><p>The following efficiently counts the number of set bits in a bit vector:</p>
<pre class="verbatim"><ol><li> <span class="i">$setbits</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">"%32b*"</span><span class="cm">,</span> <span class="i">$selectmask</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The <code class="inline"><span class="w">p</span></code>
and <code class="inline"><span class="w">P</span></code>
formats should be used with care. Since Perl<br>
has no way of checking whether the value passed to <code class="inline"><a class="l_k" href="../functions/unpack.html">unpack()</a></code>
corresponds to a valid memory location, passing a pointer value that's<br>
not known to be valid is likely to have disastrous consequences.</p>
<p>If there are more pack codes or if the repeat count of a field or a group<br>
is larger than what the remainder of the input string allows, the result<br>
is not well defined: in some cases, the repeat count is decreased, or<br>
<code class="inline"><a class="l_k" href="../functions/unpack.html">unpack()</a></code> will produce null strings or zeroes, or terminate with an<br>
error. If the input string is longer than one described by the TEMPLATE,<br>
the rest is ignored.</p>
<p>See <a href="../functions/pack.html">"pack"</a> for more examples and notes.]]></desc>
</keyword>
<keyword name="unpack" type="function">
<params>
<param name='template'/>
</params>
<desc><![CDATA[<code class="inline"><a class="l_k" href="../functions/unpack.html">unpack</a></code> does the reverse of <code class="inline"><a class="l_k" href="../functions/pack.html">pack</a></code>: it takes a string<br>
and expands it out into a list of values.<br>
(In scalar context, it returns merely the first value produced.)</p>
<p>If EXPR is omitted, unpacks the <code class="inline"><span class="i">$_</span></code>
string.</p>
<p>The string is broken into chunks described by the TEMPLATE. Each chunk<br>
is converted separately to a value. Typically, either the string is a result<br>
of <code class="inline"><a class="l_k" href="../functions/pack.html">pack</a></code>, or the characters of the string represent a C structure of some<br>
kind.</p>
<p>The TEMPLATE has the same format as in the <code class="inline"><a class="l_k" href="../functions/pack.html">pack</a></code> function.<br>
Here's a subroutine that does substring:</p>
<pre class="verbatim"><ol><li><a name="substr"></a> sub <span class="m">substr</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/my.html">my</a><span class="s">(</span><span class="i">$what</span><span class="cm">,</span><span class="i">$where</span><span class="cm">,</span><span class="i">$howmuch</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">"x$where a$howmuch"</span><span class="cm">,</span> <span class="i">$what</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>and then there's</p>
<pre class="verbatim"><ol><li><a name="ordinal"></a> sub <span class="m">ordinal</span> <span class="s">{</span> <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">"W"</span><span class="cm">,</span><span class="i">$_</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span> <span class="s">}</span> <span class="c"># same as ord()</span></li></ol></pre><p>In addition to fields allowed in pack(), you may prefix a field with<br>
a %<number> to indicate that<br>
you want a <number>-bit checksum of the items instead of the items<br>
themselves. Default is a 16-bit checksum. Checksum is calculated by<br>
summing numeric values of expanded values (for string fields the sum of<br>
<code class="inline"><a class="l_k" href="../functions/ord.html">ord($char)</a></code> is taken, for bit fields the sum of zeroes and ones).</p>
<p>For example, the following<br>
computes the same number as the System V sum program:</p>
<pre class="verbatim"><ol><li> <span class="i">$checksum</span> = <a class="l_k" href="../functions/do.html">do</a> <span class="s">{</span></li><li> <a class="l_k" href="../functions/local.html">local</a> <span class="i">$/</span><span class="sc">;</span> <span class="c"># slurp!</span></li><li> <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">"%32W*"</span><span class="cm">,</span><><span class="s">)</span> % <span class="n">65535</span><span class="sc">;</span></li><li> <span class="s">}</span><span class="sc">;</span></li></ol></pre><p>The following efficiently counts the number of set bits in a bit vector:</p>
<pre class="verbatim"><ol><li> <span class="i">$setbits</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">"%32b*"</span><span class="cm">,</span> <span class="i">$selectmask</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The <code class="inline"><span class="w">p</span></code>
and <code class="inline"><span class="w">P</span></code>
formats should be used with care. Since Perl<br>
has no way of checking whether the value passed to <code class="inline"><a class="l_k" href="../functions/unpack.html">unpack()</a></code>
corresponds to a valid memory location, passing a pointer value that's<br>
not known to be valid is likely to have disastrous consequences.</p>
<p>If there are more pack codes or if the repeat count of a field or a group<br>
is larger than what the remainder of the input string allows, the result<br>
is not well defined: in some cases, the repeat count is decreased, or<br>
<code class="inline"><a class="l_k" href="../functions/unpack.html">unpack()</a></code> will produce null strings or zeroes, or terminate with an<br>
error. If the input string is longer than one described by the TEMPLATE,<br>
the rest is ignored.</p>
<p>See <a href="../functions/pack.html">"pack"</a> for more examples and notes.]]></desc>
</keyword>
<keyword name="unshift" type="function">
<params>
<param name='array'/>
<param name='list'/>
</params>
<desc><![CDATA[Does the opposite of a <code class="inline"><a class="l_k" href="../functions/shift.html">shift</a></code>. Or the opposite of a <code class="inline"><a class="l_k" href="../functions/push.html">push</a></code>,<br>
depending on how you look at it. Prepends list to the front of the<br>
array, and returns the new number of elements in the array.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/unshift.html">unshift</a><span class="s">(</span><span class="i">@ARGV</span><span class="cm">,</span> <span class="q">'-e'</span><span class="s">)</span> unless <span class="i">$ARGV</span>[<span class="n">0</span>] =~ <span class="q">/^-/</span><span class="sc">;</span></li></ol></pre><p>Note the LIST is prepended whole, not one element at a time, so the<br>
prepended elements stay in the same order. Use <code class="inline"><a class="l_k" href="../functions/reverse.html">reverse</a></code> to do the<br>
reverse.]]></desc>
</keyword>
<keyword name="untie" type="function">
<params>
<param name='variable'/>
</params>
<desc><![CDATA[Breaks the binding between a variable and a package. (See <code class="inline"><a class="l_k" href="../functions/tie.html">tie</a></code>.)<br>
Has no effect if the variable is not tied.]]></desc>
</keyword>
<keyword name="use" type="function">
<params>
<param name='module list'/>
</params>
<desc><![CDATA[Imports some semantics into the current package from the named module,<br>
generally by aliasing certain subroutine or variable names into your<br>
package. It is exactly equivalent to</p>
<pre class="verbatim"><ol><li> BEGIN <span class="s">{</span> <a class="l_k" href="../functions/require.html">require</a> <span class="w">Module</span><span class="sc">;</span> <span class="w">Module</span><span class="w">->import</span><span class="s">(</span> <span class="w">LIST</span> <span class="s">)</span><span class="sc">;</span> <span class="s">}</span></li></ol></pre><p>except that Module <i>must</i> be a bareword.</p>
<p>In the peculiar <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">VERSION</span></code>
form, VERSION may be either a numeric<br>
argument such as 5.006, which will be compared to <code class="inline"><span class="i">$]</span></code>
, or a literal of<br>
the form v5.6.1, which will be compared to <code class="inline"><span class="i">$^V</span></code>
(aka $PERL_VERSION). A<br>
fatal error is produced if VERSION is greater than the version of the<br>
current Perl interpreter; Perl will not attempt to parse the rest of the<br>
file. Compare with <a href="../functions/require.html">"require"</a>, which can do a similar check at run time.<br>
Symmetrically, <code class="inline"><a class="l_k" href="../functions/no.html">no</a> <span class="w">VERSION</span></code>
allows you to specify that you want a version<br>
of perl older than the specified one.</p>
<p>Specifying VERSION as a literal of the form v5.6.1 should generally be<br>
avoided, because it leads to misleading error messages under earlier<br>
versions of Perl (that is, prior to 5.6.0) that do not support this<br>
syntax. The equivalent numeric version should be used instead.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="v">v5.6.1</span><span class="sc">;</span> <span class="c"># compile time version check</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="v">5.6.1</span><span class="sc">;</span> <span class="c"># ditto</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="n">5.006_001</span><span class="sc">;</span> <span class="c"># ditto; preferred for backwards compatibility</span></li></ol></pre><p>This is often useful if you need to check the current Perl version before<br>
<code class="inline"><a class="l_k" href="../functions/use.html">use</a></code>ing library modules that won't work with older versions of Perl.<br>
(We try not to do this more than we have to.)</p>
<p>Also, if the specified perl version is greater than or equal to 5.9.5,<br>
<code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">VERSION</span></code>
will also load the <code class="inline"><span class="w">feature</span></code>
pragma and enable all<br>
features available in the requested version. See <a href="../feature.html">feature</a>.</p>
<p>The <code class="inline">BEGIN</code>
forces the <code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> and <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> to happen at compile time. The<br>
<code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> makes sure the module is loaded into memory if it hasn't been<br>
yet. The <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> is not a builtin--it's just an ordinary static method<br>
call into the <code class="inline"><span class="w">Module</span></code>
package to tell the module to import the list of<br>
features back into the current package. The module can implement its<br>
<code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> method any way it likes, though most modules just choose to<br>
derive their <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> method via inheritance from the <code class="inline"><span class="w">Exporter</span></code>
class that<br>
is defined in the <code class="inline"><span class="w">Exporter</span></code>
module. See <a href="../Exporter.html">Exporter</a>. If no <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code>
method can be found then the call is skipped, even if there is an AUTOLOAD<br>
method.</p>
<p>If you do not want to call the package's <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> method (for instance,<br>
to stop your namespace from being altered), explicitly supply the empty list:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Module</span> <span class="s">(</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>That is exactly equivalent to</p>
<pre class="verbatim"><ol><li> BEGIN <span class="s">{</span> <a class="l_k" href="../functions/require.html">require</a> <span class="w">Module</span> <span class="s">}</span></li></ol></pre><p>If the VERSION argument is present between Module and LIST, then the<br>
<code class="inline"><a class="l_k" href="../functions/use.html">use</a></code> will call the VERSION method in class Module with the given<br>
version as an argument. The default VERSION method, inherited from<br>
the UNIVERSAL class, croaks if the given version is larger than the<br>
value of the variable <code class="inline"><span class="i">$Module::VERSION</span></code>
.</p>
<p>Again, there is a distinction between omitting LIST (<code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> called<br>
with no arguments) and an explicit empty LIST <code class="inline"><span class="s">(</span><span class="s">)</span></code>
(<code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> not<br>
called). Note that there is no comma after VERSION!</p>
<p>Because this is a wide-open interface, pragmas (compiler directives)<br>
are also implemented this way. Currently implemented pragmas are:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">constant</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">diagnostics</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">integer</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">sigtrap</span> <span class="q">qw(SEGV BUS)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">strict</span> <span class="q">qw(subs vars refs)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">subs</span> <span class="q">qw(afunc blurfl)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">warnings</span> <span class="q">qw(all)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <a class="l_k" href="../functions/sort.html">sort</a> <span class="q">qw(stable _quicksort _mergesort)</span><span class="sc">;</span></li></ol></pre><p>Some of these pseudo-modules import semantics into the current<br>
block scope (like <code class="inline"><span class="w">strict</span></code>
or <code class="inline"><span class="w">integer</span></code>
, unlike ordinary modules,<br>
which import symbols into the current package (which are effective<br>
through the end of the file).</p>
<p>There's a corresponding <code class="inline"><a class="l_k" href="../functions/no.html">no</a></code> command that unimports meanings imported<br>
by <code class="inline"><a class="l_k" href="../functions/use.html">use</a></code>, i.e., it calls <code class="inline"><span class="w">unimport</span> <span class="w">Module</span> <span class="w">LIST</span></code>
instead of <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code>.<br>
It behaves exactly as <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> does with respect to VERSION, an<br>
omitted LIST, empty LIST, or no unimport method being found.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/no.html">no</a> <span class="w">integer</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/no.html">no</a> <span class="w">strict</span> <span class="q">'refs'</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/no.html">no</a> <span class="w">warnings</span><span class="sc">;</span></li></ol></pre><p>See <a href="../perlmodlib.html">perlmodlib</a> for a list of standard modules and pragmas. See <a href="../perlrun.html">perlrun</a>
for the <code class="inline">-M</code>
and <code class="inline">-m</code> command-line options to perl that give <code class="inline"><a class="l_k" href="../functions/use.html">use</a></code>
functionality from the command-line.]]></desc>
</keyword>
<keyword name="use" type="function">
<params>
<param name='module version list'/>
</params>
<desc><![CDATA[Imports some semantics into the current package from the named module,<br>
generally by aliasing certain subroutine or variable names into your<br>
package. It is exactly equivalent to</p>
<pre class="verbatim"><ol><li> BEGIN <span class="s">{</span> <a class="l_k" href="../functions/require.html">require</a> <span class="w">Module</span><span class="sc">;</span> <span class="w">Module</span><span class="w">->import</span><span class="s">(</span> <span class="w">LIST</span> <span class="s">)</span><span class="sc">;</span> <span class="s">}</span></li></ol></pre><p>except that Module <i>must</i> be a bareword.</p>
<p>In the peculiar <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">VERSION</span></code>
form, VERSION may be either a numeric<br>
argument such as 5.006, which will be compared to <code class="inline"><span class="i">$]</span></code>
, or a literal of<br>
the form v5.6.1, which will be compared to <code class="inline"><span class="i">$^V</span></code>
(aka $PERL_VERSION). A<br>
fatal error is produced if VERSION is greater than the version of the<br>
current Perl interpreter; Perl will not attempt to parse the rest of the<br>
file. Compare with <a href="../functions/require.html">"require"</a>, which can do a similar check at run time.<br>
Symmetrically, <code class="inline"><a class="l_k" href="../functions/no.html">no</a> <span class="w">VERSION</span></code>
allows you to specify that you want a version<br>
of perl older than the specified one.</p>
<p>Specifying VERSION as a literal of the form v5.6.1 should generally be<br>
avoided, because it leads to misleading error messages under earlier<br>
versions of Perl (that is, prior to 5.6.0) that do not support this<br>
syntax. The equivalent numeric version should be used instead.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="v">v5.6.1</span><span class="sc">;</span> <span class="c"># compile time version check</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="v">5.6.1</span><span class="sc">;</span> <span class="c"># ditto</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="n">5.006_001</span><span class="sc">;</span> <span class="c"># ditto; preferred for backwards compatibility</span></li></ol></pre><p>This is often useful if you need to check the current Perl version before<br>
<code class="inline"><a class="l_k" href="../functions/use.html">use</a></code>ing library modules that won't work with older versions of Perl.<br>
(We try not to do this more than we have to.)</p>
<p>Also, if the specified perl version is greater than or equal to 5.9.5,<br>
<code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">VERSION</span></code>
will also load the <code class="inline"><span class="w">feature</span></code>
pragma and enable all<br>
features available in the requested version. See <a href="../feature.html">feature</a>.</p>
<p>The <code class="inline">BEGIN</code>
forces the <code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> and <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> to happen at compile time. The<br>
<code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> makes sure the module is loaded into memory if it hasn't been<br>
yet. The <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> is not a builtin--it's just an ordinary static method<br>
call into the <code class="inline"><span class="w">Module</span></code>
package to tell the module to import the list of<br>
features back into the current package. The module can implement its<br>
<code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> method any way it likes, though most modules just choose to<br>
derive their <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> method via inheritance from the <code class="inline"><span class="w">Exporter</span></code>
class that<br>
is defined in the <code class="inline"><span class="w">Exporter</span></code>
module. See <a href="../Exporter.html">Exporter</a>. If no <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code>
method can be found then the call is skipped, even if there is an AUTOLOAD<br>
method.</p>
<p>If you do not want to call the package's <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> method (for instance,<br>
to stop your namespace from being altered), explicitly supply the empty list:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Module</span> <span class="s">(</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>That is exactly equivalent to</p>
<pre class="verbatim"><ol><li> BEGIN <span class="s">{</span> <a class="l_k" href="../functions/require.html">require</a> <span class="w">Module</span> <span class="s">}</span></li></ol></pre><p>If the VERSION argument is present between Module and LIST, then the<br>
<code class="inline"><a class="l_k" href="../functions/use.html">use</a></code> will call the VERSION method in class Module with the given<br>
version as an argument. The default VERSION method, inherited from<br>
the UNIVERSAL class, croaks if the given version is larger than the<br>
value of the variable <code class="inline"><span class="i">$Module::VERSION</span></code>
.</p>
<p>Again, there is a distinction between omitting LIST (<code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> called<br>
with no arguments) and an explicit empty LIST <code class="inline"><span class="s">(</span><span class="s">)</span></code>
(<code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> not<br>
called). Note that there is no comma after VERSION!</p>
<p>Because this is a wide-open interface, pragmas (compiler directives)<br>
are also implemented this way. Currently implemented pragmas are:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">constant</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">diagnostics</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">integer</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">sigtrap</span> <span class="q">qw(SEGV BUS)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">strict</span> <span class="q">qw(subs vars refs)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">subs</span> <span class="q">qw(afunc blurfl)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">warnings</span> <span class="q">qw(all)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <a class="l_k" href="../functions/sort.html">sort</a> <span class="q">qw(stable _quicksort _mergesort)</span><span class="sc">;</span></li></ol></pre><p>Some of these pseudo-modules import semantics into the current<br>
block scope (like <code class="inline"><span class="w">strict</span></code>
or <code class="inline"><span class="w">integer</span></code>
, unlike ordinary modules,<br>
which import symbols into the current package (which are effective<br>
through the end of the file).</p>
<p>There's a corresponding <code class="inline"><a class="l_k" href="../functions/no.html">no</a></code> command that unimports meanings imported<br>
by <code class="inline"><a class="l_k" href="../functions/use.html">use</a></code>, i.e., it calls <code class="inline"><span class="w">unimport</span> <span class="w">Module</span> <span class="w">LIST</span></code>
instead of <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code>.<br>
It behaves exactly as <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> does with respect to VERSION, an<br>
omitted LIST, empty LIST, or no unimport method being found.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/no.html">no</a> <span class="w">integer</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/no.html">no</a> <span class="w">strict</span> <span class="q">'refs'</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/no.html">no</a> <span class="w">warnings</span><span class="sc">;</span></li></ol></pre><p>See <a href="../perlmodlib.html">perlmodlib</a> for a list of standard modules and pragmas. See <a href="../perlrun.html">perlrun</a>
for the <code class="inline">-M</code>
and <code class="inline">-m</code> command-line options to perl that give <code class="inline"><a class="l_k" href="../functions/use.html">use</a></code>
functionality from the command-line.]]></desc>
</keyword>
<keyword name="use" type="function">
<params>
<param name='module version'/>
</params>
<desc><![CDATA[Imports some semantics into the current package from the named module,<br>
generally by aliasing certain subroutine or variable names into your<br>
package. It is exactly equivalent to</p>
<pre class="verbatim"><ol><li> BEGIN <span class="s">{</span> <a class="l_k" href="../functions/require.html">require</a> <span class="w">Module</span><span class="sc">;</span> <span class="w">Module</span><span class="w">->import</span><span class="s">(</span> <span class="w">LIST</span> <span class="s">)</span><span class="sc">;</span> <span class="s">}</span></li></ol></pre><p>except that Module <i>must</i> be a bareword.</p>
<p>In the peculiar <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">VERSION</span></code>
form, VERSION may be either a numeric<br>
argument such as 5.006, which will be compared to <code class="inline"><span class="i">$]</span></code>
, or a literal of<br>
the form v5.6.1, which will be compared to <code class="inline"><span class="i">$^V</span></code>
(aka $PERL_VERSION). A<br>
fatal error is produced if VERSION is greater than the version of the<br>
current Perl interpreter; Perl will not attempt to parse the rest of the<br>
file. Compare with <a href="../functions/require.html">"require"</a>, which can do a similar check at run time.<br>
Symmetrically, <code class="inline"><a class="l_k" href="../functions/no.html">no</a> <span class="w">VERSION</span></code>
allows you to specify that you want a version<br>
of perl older than the specified one.</p>
<p>Specifying VERSION as a literal of the form v5.6.1 should generally be<br>
avoided, because it leads to misleading error messages under earlier<br>
versions of Perl (that is, prior to 5.6.0) that do not support this<br>
syntax. The equivalent numeric version should be used instead.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="v">v5.6.1</span><span class="sc">;</span> <span class="c"># compile time version check</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="v">5.6.1</span><span class="sc">;</span> <span class="c"># ditto</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="n">5.006_001</span><span class="sc">;</span> <span class="c"># ditto; preferred for backwards compatibility</span></li></ol></pre><p>This is often useful if you need to check the current Perl version before<br>
<code class="inline"><a class="l_k" href="../functions/use.html">use</a></code>ing library modules that won't work with older versions of Perl.<br>
(We try not to do this more than we have to.)</p>
<p>Also, if the specified perl version is greater than or equal to 5.9.5,<br>
<code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">VERSION</span></code>
will also load the <code class="inline"><span class="w">feature</span></code>
pragma and enable all<br>
features available in the requested version. See <a href="../feature.html">feature</a>.</p>
<p>The <code class="inline">BEGIN</code>
forces the <code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> and <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> to happen at compile time. The<br>
<code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> makes sure the module is loaded into memory if it hasn't been<br>
yet. The <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> is not a builtin--it's just an ordinary static method<br>
call into the <code class="inline"><span class="w">Module</span></code>
package to tell the module to import the list of<br>
features back into the current package. The module can implement its<br>
<code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> method any way it likes, though most modules just choose to<br>
derive their <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> method via inheritance from the <code class="inline"><span class="w">Exporter</span></code>
class that<br>
is defined in the <code class="inline"><span class="w">Exporter</span></code>
module. See <a href="../Exporter.html">Exporter</a>. If no <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code>
method can be found then the call is skipped, even if there is an AUTOLOAD<br>
method.</p>
<p>If you do not want to call the package's <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> method (for instance,<br>
to stop your namespace from being altered), explicitly supply the empty list:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Module</span> <span class="s">(</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>That is exactly equivalent to</p>
<pre class="verbatim"><ol><li> BEGIN <span class="s">{</span> <a class="l_k" href="../functions/require.html">require</a> <span class="w">Module</span> <span class="s">}</span></li></ol></pre><p>If the VERSION argument is present between Module and LIST, then the<br>
<code class="inline"><a class="l_k" href="../functions/use.html">use</a></code> will call the VERSION method in class Module with the given<br>
version as an argument. The default VERSION method, inherited from<br>
the UNIVERSAL class, croaks if the given version is larger than the<br>
value of the variable <code class="inline"><span class="i">$Module::VERSION</span></code>
.</p>
<p>Again, there is a distinction between omitting LIST (<code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> called<br>
with no arguments) and an explicit empty LIST <code class="inline"><span class="s">(</span><span class="s">)</span></code>
(<code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> not<br>
called). Note that there is no comma after VERSION!</p>
<p>Because this is a wide-open interface, pragmas (compiler directives)<br>
are also implemented this way. Currently implemented pragmas are:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">constant</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">diagnostics</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">integer</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">sigtrap</span> <span class="q">qw(SEGV BUS)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">strict</span> <span class="q">qw(subs vars refs)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">subs</span> <span class="q">qw(afunc blurfl)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">warnings</span> <span class="q">qw(all)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <a class="l_k" href="../functions/sort.html">sort</a> <span class="q">qw(stable _quicksort _mergesort)</span><span class="sc">;</span></li></ol></pre><p>Some of these pseudo-modules import semantics into the current<br>
block scope (like <code class="inline"><span class="w">strict</span></code>
or <code class="inline"><span class="w">integer</span></code>
, unlike ordinary modules,<br>
which import symbols into the current package (which are effective<br>
through the end of the file).</p>
<p>There's a corresponding <code class="inline"><a class="l_k" href="../functions/no.html">no</a></code> command that unimports meanings imported<br>
by <code class="inline"><a class="l_k" href="../functions/use.html">use</a></code>, i.e., it calls <code class="inline"><span class="w">unimport</span> <span class="w">Module</span> <span class="w">LIST</span></code>
instead of <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code>.<br>
It behaves exactly as <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> does with respect to VERSION, an<br>
omitted LIST, empty LIST, or no unimport method being found.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/no.html">no</a> <span class="w">integer</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/no.html">no</a> <span class="w">strict</span> <span class="q">'refs'</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/no.html">no</a> <span class="w">warnings</span><span class="sc">;</span></li></ol></pre><p>See <a href="../perlmodlib.html">perlmodlib</a> for a list of standard modules and pragmas. See <a href="../perlrun.html">perlrun</a>
for the <code class="inline">-M</code>
and <code class="inline">-m</code> command-line options to perl that give <code class="inline"><a class="l_k" href="../functions/use.html">use</a></code>
functionality from the command-line.]]></desc>
</keyword>
<keyword name="use" type="function">
<params>
<param name='module'/>
</params>
<desc><![CDATA[Imports some semantics into the current package from the named module,<br>
generally by aliasing certain subroutine or variable names into your<br>
package. It is exactly equivalent to</p>
<pre class="verbatim"><ol><li> BEGIN <span class="s">{</span> <a class="l_k" href="../functions/require.html">require</a> <span class="w">Module</span><span class="sc">;</span> <span class="w">Module</span><span class="w">->import</span><span class="s">(</span> <span class="w">LIST</span> <span class="s">)</span><span class="sc">;</span> <span class="s">}</span></li></ol></pre><p>except that Module <i>must</i> be a bareword.</p>
<p>In the peculiar <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">VERSION</span></code>
form, VERSION may be either a numeric<br>
argument such as 5.006, which will be compared to <code class="inline"><span class="i">$]</span></code>
, or a literal of<br>
the form v5.6.1, which will be compared to <code class="inline"><span class="i">$^V</span></code>
(aka $PERL_VERSION). A<br>
fatal error is produced if VERSION is greater than the version of the<br>
current Perl interpreter; Perl will not attempt to parse the rest of the<br>
file. Compare with <a href="../functions/require.html">"require"</a>, which can do a similar check at run time.<br>
Symmetrically, <code class="inline"><a class="l_k" href="../functions/no.html">no</a> <span class="w">VERSION</span></code>
allows you to specify that you want a version<br>
of perl older than the specified one.</p>
<p>Specifying VERSION as a literal of the form v5.6.1 should generally be<br>
avoided, because it leads to misleading error messages under earlier<br>
versions of Perl (that is, prior to 5.6.0) that do not support this<br>
syntax. The equivalent numeric version should be used instead.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="v">v5.6.1</span><span class="sc">;</span> <span class="c"># compile time version check</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="v">5.6.1</span><span class="sc">;</span> <span class="c"># ditto</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="n">5.006_001</span><span class="sc">;</span> <span class="c"># ditto; preferred for backwards compatibility</span></li></ol></pre><p>This is often useful if you need to check the current Perl version before<br>
<code class="inline"><a class="l_k" href="../functions/use.html">use</a></code>ing library modules that won't work with older versions of Perl.<br>
(We try not to do this more than we have to.)</p>
<p>Also, if the specified perl version is greater than or equal to 5.9.5,<br>
<code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">VERSION</span></code>
will also load the <code class="inline"><span class="w">feature</span></code>
pragma and enable all<br>
features available in the requested version. See <a href="../feature.html">feature</a>.</p>
<p>The <code class="inline">BEGIN</code>
forces the <code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> and <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> to happen at compile time. The<br>
<code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> makes sure the module is loaded into memory if it hasn't been<br>
yet. The <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> is not a builtin--it's just an ordinary static method<br>
call into the <code class="inline"><span class="w">Module</span></code>
package to tell the module to import the list of<br>
features back into the current package. The module can implement its<br>
<code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> method any way it likes, though most modules just choose to<br>
derive their <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> method via inheritance from the <code class="inline"><span class="w">Exporter</span></code>
class that<br>
is defined in the <code class="inline"><span class="w">Exporter</span></code>
module. See <a href="../Exporter.html">Exporter</a>. If no <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code>
method can be found then the call is skipped, even if there is an AUTOLOAD<br>
method.</p>
<p>If you do not want to call the package's <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> method (for instance,<br>
to stop your namespace from being altered), explicitly supply the empty list:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Module</span> <span class="s">(</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>That is exactly equivalent to</p>
<pre class="verbatim"><ol><li> BEGIN <span class="s">{</span> <a class="l_k" href="../functions/require.html">require</a> <span class="w">Module</span> <span class="s">}</span></li></ol></pre><p>If the VERSION argument is present between Module and LIST, then the<br>
<code class="inline"><a class="l_k" href="../functions/use.html">use</a></code> will call the VERSION method in class Module with the given<br>
version as an argument. The default VERSION method, inherited from<br>
the UNIVERSAL class, croaks if the given version is larger than the<br>
value of the variable <code class="inline"><span class="i">$Module::VERSION</span></code>
.</p>
<p>Again, there is a distinction between omitting LIST (<code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> called<br>
with no arguments) and an explicit empty LIST <code class="inline"><span class="s">(</span><span class="s">)</span></code>
(<code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> not<br>
called). Note that there is no comma after VERSION!</p>
<p>Because this is a wide-open interface, pragmas (compiler directives)<br>
are also implemented this way. Currently implemented pragmas are:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">constant</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">diagnostics</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">integer</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">sigtrap</span> <span class="q">qw(SEGV BUS)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">strict</span> <span class="q">qw(subs vars refs)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">subs</span> <span class="q">qw(afunc blurfl)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">warnings</span> <span class="q">qw(all)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <a class="l_k" href="../functions/sort.html">sort</a> <span class="q">qw(stable _quicksort _mergesort)</span><span class="sc">;</span></li></ol></pre><p>Some of these pseudo-modules import semantics into the current<br>
block scope (like <code class="inline"><span class="w">strict</span></code>
or <code class="inline"><span class="w">integer</span></code>
, unlike ordinary modules,<br>
which import symbols into the current package (which are effective<br>
through the end of the file).</p>
<p>There's a corresponding <code class="inline"><a class="l_k" href="../functions/no.html">no</a></code> command that unimports meanings imported<br>
by <code class="inline"><a class="l_k" href="../functions/use.html">use</a></code>, i.e., it calls <code class="inline"><span class="w">unimport</span> <span class="w">Module</span> <span class="w">LIST</span></code>
instead of <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code>.<br>
It behaves exactly as <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> does with respect to VERSION, an<br>
omitted LIST, empty LIST, or no unimport method being found.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/no.html">no</a> <span class="w">integer</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/no.html">no</a> <span class="w">strict</span> <span class="q">'refs'</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/no.html">no</a> <span class="w">warnings</span><span class="sc">;</span></li></ol></pre><p>See <a href="../perlmodlib.html">perlmodlib</a> for a list of standard modules and pragmas. See <a href="../perlrun.html">perlrun</a>
for the <code class="inline">-M</code>
and <code class="inline">-m</code> command-line options to perl that give <code class="inline"><a class="l_k" href="../functions/use.html">use</a></code>
functionality from the command-line.]]></desc>
</keyword>
<keyword name="use" type="function">
<params>
<param name='version'/>
</params>
<desc><![CDATA[Imports some semantics into the current package from the named module,<br>
generally by aliasing certain subroutine or variable names into your<br>
package. It is exactly equivalent to</p>
<pre class="verbatim"><ol><li> BEGIN <span class="s">{</span> <a class="l_k" href="../functions/require.html">require</a> <span class="w">Module</span><span class="sc">;</span> <span class="w">Module</span><span class="w">->import</span><span class="s">(</span> <span class="w">LIST</span> <span class="s">)</span><span class="sc">;</span> <span class="s">}</span></li></ol></pre><p>except that Module <i>must</i> be a bareword.</p>
<p>In the peculiar <code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">VERSION</span></code>
form, VERSION may be either a numeric<br>
argument such as 5.006, which will be compared to <code class="inline"><span class="i">$]</span></code>
, or a literal of<br>
the form v5.6.1, which will be compared to <code class="inline"><span class="i">$^V</span></code>
(aka $PERL_VERSION). A<br>
fatal error is produced if VERSION is greater than the version of the<br>
current Perl interpreter; Perl will not attempt to parse the rest of the<br>
file. Compare with <a href="../functions/require.html">"require"</a>, which can do a similar check at run time.<br>
Symmetrically, <code class="inline"><a class="l_k" href="../functions/no.html">no</a> <span class="w">VERSION</span></code>
allows you to specify that you want a version<br>
of perl older than the specified one.</p>
<p>Specifying VERSION as a literal of the form v5.6.1 should generally be<br>
avoided, because it leads to misleading error messages under earlier<br>
versions of Perl (that is, prior to 5.6.0) that do not support this<br>
syntax. The equivalent numeric version should be used instead.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="v">v5.6.1</span><span class="sc">;</span> <span class="c"># compile time version check</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="v">5.6.1</span><span class="sc">;</span> <span class="c"># ditto</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="n">5.006_001</span><span class="sc">;</span> <span class="c"># ditto; preferred for backwards compatibility</span></li></ol></pre><p>This is often useful if you need to check the current Perl version before<br>
<code class="inline"><a class="l_k" href="../functions/use.html">use</a></code>ing library modules that won't work with older versions of Perl.<br>
(We try not to do this more than we have to.)</p>
<p>Also, if the specified perl version is greater than or equal to 5.9.5,<br>
<code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">VERSION</span></code>
will also load the <code class="inline"><span class="w">feature</span></code>
pragma and enable all<br>
features available in the requested version. See <a href="../feature.html">feature</a>.</p>
<p>The <code class="inline">BEGIN</code>
forces the <code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> and <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> to happen at compile time. The<br>
<code class="inline"><a class="l_k" href="../functions/require.html">require</a></code> makes sure the module is loaded into memory if it hasn't been<br>
yet. The <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> is not a builtin--it's just an ordinary static method<br>
call into the <code class="inline"><span class="w">Module</span></code>
package to tell the module to import the list of<br>
features back into the current package. The module can implement its<br>
<code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> method any way it likes, though most modules just choose to<br>
derive their <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> method via inheritance from the <code class="inline"><span class="w">Exporter</span></code>
class that<br>
is defined in the <code class="inline"><span class="w">Exporter</span></code>
module. See <a href="../Exporter.html">Exporter</a>. If no <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code>
method can be found then the call is skipped, even if there is an AUTOLOAD<br>
method.</p>
<p>If you do not want to call the package's <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> method (for instance,<br>
to stop your namespace from being altered), explicitly supply the empty list:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Module</span> <span class="s">(</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>That is exactly equivalent to</p>
<pre class="verbatim"><ol><li> BEGIN <span class="s">{</span> <a class="l_k" href="../functions/require.html">require</a> <span class="w">Module</span> <span class="s">}</span></li></ol></pre><p>If the VERSION argument is present between Module and LIST, then the<br>
<code class="inline"><a class="l_k" href="../functions/use.html">use</a></code> will call the VERSION method in class Module with the given<br>
version as an argument. The default VERSION method, inherited from<br>
the UNIVERSAL class, croaks if the given version is larger than the<br>
value of the variable <code class="inline"><span class="i">$Module::VERSION</span></code>
.</p>
<p>Again, there is a distinction between omitting LIST (<code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> called<br>
with no arguments) and an explicit empty LIST <code class="inline"><span class="s">(</span><span class="s">)</span></code>
(<code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> not<br>
called). Note that there is no comma after VERSION!</p>
<p>Because this is a wide-open interface, pragmas (compiler directives)<br>
are also implemented this way. Currently implemented pragmas are:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">constant</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">diagnostics</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">integer</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">sigtrap</span> <span class="q">qw(SEGV BUS)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">strict</span> <span class="q">qw(subs vars refs)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">subs</span> <span class="q">qw(afunc blurfl)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">warnings</span> <span class="q">qw(all)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/use.html">use</a> <a class="l_k" href="../functions/sort.html">sort</a> <span class="q">qw(stable _quicksort _mergesort)</span><span class="sc">;</span></li></ol></pre><p>Some of these pseudo-modules import semantics into the current<br>
block scope (like <code class="inline"><span class="w">strict</span></code>
or <code class="inline"><span class="w">integer</span></code>
, unlike ordinary modules,<br>
which import symbols into the current package (which are effective<br>
through the end of the file).</p>
<p>There's a corresponding <code class="inline"><a class="l_k" href="../functions/no.html">no</a></code> command that unimports meanings imported<br>
by <code class="inline"><a class="l_k" href="../functions/use.html">use</a></code>, i.e., it calls <code class="inline"><span class="w">unimport</span> <span class="w">Module</span> <span class="w">LIST</span></code>
instead of <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code>.<br>
It behaves exactly as <code class="inline"><a class="l_k" href="../functions/import.html">import</a></code> does with respect to VERSION, an<br>
omitted LIST, empty LIST, or no unimport method being found.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/no.html">no</a> <span class="w">integer</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/no.html">no</a> <span class="w">strict</span> <span class="q">'refs'</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/no.html">no</a> <span class="w">warnings</span><span class="sc">;</span></li></ol></pre><p>See <a href="../perlmodlib.html">perlmodlib</a> for a list of standard modules and pragmas. See <a href="../perlrun.html">perlrun</a>
for the <code class="inline">-M</code>
and <code class="inline">-m</code> command-line options to perl that give <code class="inline"><a class="l_k" href="../functions/use.html">use</a></code>
functionality from the command-line.]]></desc>
</keyword>
<keyword name="utime" type="function">
<params>
<param name='list'/>
</params>
<desc><![CDATA[Changes the access and modification times on each file of a list of<br>
files. The first two elements of the list must be the NUMERICAL access<br>
and modification times, in that order. Returns the number of files<br>
successfully changed. The inode change time of each file is set<br>
to the current time. For example, this code has the same effect as the<br>
Unix touch(1) command when the files <i>already exist</i> and belong to<br>
the user running the program:</p>
<pre class="verbatim"><ol><li> <span class="c">#!/usr/bin/perl</span></li><li> <span class="i">$atime</span> = <span class="i">$mtime</span> = <a class="l_k" href="../functions/time.html">time</a><span class="sc">;</span></li><li> <a class="l_k" href="../functions/utime.html">utime</a> <span class="i">$atime</span><span class="cm">,</span> <span class="i">$mtime</span><span class="cm">,</span> <span class="i">@ARGV</span><span class="sc">;</span></li></ol></pre><p>Since perl 5.7.2, if the first two elements of the list are <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code>, then<br>
the utime(2) function in the C library will be called with a null second<br>
argument. On most systems, this will set the file's access and<br>
modification times to the current time (i.e. equivalent to the example<br>
above) and will even work on other users' files where you have write<br>
permission:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/utime.html">utime</a> <a class="l_k" href="../functions/undef.html">undef</a><span class="cm">,</span> <a class="l_k" href="../functions/undef.html">undef</a><span class="cm">,</span> <span class="i">@ARGV</span><span class="sc">;</span></li></ol></pre><p>Under NFS this will use the time of the NFS server, not the time of<br>
the local machine. If there is a time synchronization problem, the<br>
NFS server and local machine will have different times. The Unix<br>
touch(1) command will in fact normally use this form instead of the<br>
one shown in the first example.</p>
<p>Note that only passing one of the first two elements as <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code> will<br>
be equivalent of passing it as 0 and will not have the same effect as<br>
described when they are both <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code>. This case will also trigger an<br>
uninitialized warning.</p>
<p>On systems that support futimes, you might pass file handles among the<br>
files. On systems that don't support futimes, passing file handles<br>
produces a fatal error at run time. The file handles must be passed<br>
as globs or references to be recognized. Barewords are considered<br>
file names.]]></desc>
</keyword>
<keyword name="values" type="function">
<params>
<param name='hash'/>
</params>
<desc><![CDATA[Returns a list consisting of all the values of the named hash.<br>
(In a scalar context, returns the number of values.)</p>
<p>The values are returned in an apparently random order. The actual<br>
random order is subject to change in future versions of perl, but it<br>
is guaranteed to be the same order as either the <code class="inline"><a class="l_k" href="../functions/keys.html">keys</a></code> or <code class="inline"><a class="l_k" href="../functions/each.html">each</a></code>
function would produce on the same (unmodified) hash. Since Perl<br>
5.8.1 the ordering is different even between different runs of Perl<br>
for security reasons (see <a href="../perlsec.html#Algorithmic-Complexity-Attacks">"Algorithmic Complexity Attacks" in perlsec</a>).</p>
<p>As a side effect, calling values() resets the HASH's internal iterator,<br>
see <a href="../functions/each.html">"each"</a>. (In particular, calling values() in void context resets<br>
the iterator with no other overhead.)</p>
<p>Note that the values are not copied, which means modifying them will<br>
modify the contents of the hash:</p>
<pre class="verbatim"><ol><li> for <span class="s">(</span><a class="l_k" href="../functions/values.html">values</a> <span class="i">%hash</span><span class="s">)</span> <span class="s">{</span> <span class="q">s/foo/bar/g</span> <span class="s">}</span> <span class="c"># modifies %hash values</span></li><li> for <span class="s">(</span><span class="i">@hash</span>{<a class="l_k" href="../functions/keys.html">keys</a> <span class="i">%hash</span>}<span class="s">)</span> <span class="s">{</span> <span class="q">s/foo/bar/g</span> <span class="s">}</span> <span class="c"># same</span></li></ol></pre><p>See also <code class="inline"><a class="l_k" href="../functions/keys.html">keys</a></code>, <code class="inline"><a class="l_k" href="../functions/each.html">each</a></code>, and <code class="inline"><a class="l_k" href="../functions/sort.html">sort</a></code>.]]></desc>
</keyword>
<keyword name="vec" type="function">
<params>
<param name='expr'/>
<param name='offset'/>
<param name='bits'/>
</params>
<desc><![CDATA[Treats the string in EXPR as a bit vector made up of elements of<br>
width BITS, and returns the value of the element specified by OFFSET<br>
as an unsigned integer. BITS therefore specifies the number of bits<br>
that are reserved for each element in the bit vector. This must<br>
be a power of two from 1 to 32 (or 64, if your platform supports<br>
that).</p>
<p>If BITS is 8, "elements" coincide with bytes of the input string.</p>
<p>If BITS is 16 or more, bytes of the input string are grouped into chunks<br>
of size BITS/8, and each group is converted to a number as with<br>
pack()/unpack() with big-endian formats <code class="inline"><span class="w">n</span></code>
/<code class="inline"><span class="w">N</span></code>
(and analogously<br>
for BITS==64). See <a href="http://search.cpan.org/perldoc/"pack"">pack</a> for details.</p>
<p>If bits is 4 or less, the string is broken into bytes, then the bits<br>
of each byte are broken into 8/BITS groups. Bits of a byte are<br>
numbered in a little-endian-ish way, as in <code class="inline"><span class="n">0x01</span></code>
, <code class="inline"><span class="n">0x02</span></code>
,<br>
<code class="inline"><span class="n">0x04</span></code>
, <code class="inline"><span class="n">0x08</span></code>
, <code class="inline"><span class="n">0x10</span></code>
, <code class="inline"><span class="n">0x20</span></code>
, <code class="inline"><span class="n">0x40</span></code>
, <code class="inline"><span class="n">0x80</span></code>
. For example,<br>
breaking the single input byte <code class="inline"><a class="l_k" href="../functions/chr.html">chr(0x36)</a></code> into two groups gives a list<br>
<code class="inline"><span class="s">(</span><span class="n">0x6</span><span class="cm">,</span> <span class="n">0x3</span><span class="s">)</span></code>
; breaking it into 4 groups gives <code class="inline"><span class="s">(</span><span class="n">0x2</span><span class="cm">,</span> <span class="n">0x1</span><span class="cm">,</span> <span class="n">0x3</span><span class="cm">,</span> <span class="n">0x0</span><span class="s">)</span></code>
.</p>
<p><code class="inline"><a class="l_k" href="../functions/vec.html">vec</a></code> may also be assigned to, in which case parentheses are needed<br>
to give the expression the correct precedence as in</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/vec.html">vec</a><span class="s">(</span><span class="i">$image</span><span class="cm">,</span> <span class="i">$max_x</span> * <span class="i">$x</span> + <span class="i">$y</span><span class="cm">,</span> <span class="n">8</span><span class="s">)</span> = <span class="n">3</span><span class="sc">;</span></li></ol></pre><p>If the selected element is outside the string, the value 0 is returned.<br>
If an element off the end of the string is written to, Perl will first<br>
extend the string with sufficiently many zero bytes. It is an error<br>
to try to write off the beginning of the string (i.e. negative OFFSET).</p>
<p>If the string happens to be encoded as UTF-8 internally (and thus has<br>
the UTF8 flag set), this is ignored by <code class="inline"><a class="l_k" href="../functions/vec.html">vec</a></code>, and it operates on the<br>
internal byte string, not the conceptual character string, even if you<br>
only have characters with values less than 256.</p>
<p>Strings created with <code class="inline"><a class="l_k" href="../functions/vec.html">vec</a></code> can also be manipulated with the logical<br>
operators <code class="inline">|</code>, <code class="inline"><span class="i">&</span></code>
, <code class="inline">^</code>, and <code class="inline">~</code>
. These operators will assume a bit<br>
vector operation is desired when both operands are strings.<br>
See <a href="../perlop.html#Bitwise-String-Operators">"Bitwise String Operators" in perlop</a>.</p>
<p>The following code will build up an ASCII string saying <code class="inline"><span class="q">'PerlPerlPerl'</span></code>
.<br>
The comments show the string after each step. Note that this code works<br>
in the same way on big-endian or little-endian machines.</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$foo</span> = <span class="q">''</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/vec.html">vec</a><span class="s">(</span><span class="i">$foo</span><span class="cm">,</span> <span class="n">0</span><span class="cm">,</span> <span class="n">32</span><span class="s">)</span> = <span class="n">0x5065726C</span><span class="sc">;</span> <span class="c"># 'Perl'</span></li><li></li><li> <span class="c"># $foo eq "Perl" eq "\x50\x65\x72\x6C", 32 bits</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <a class="l_k" href="../functions/vec.html">vec</a><span class="s">(</span><span class="i">$foo</span><span class="cm">,</span> <span class="n">0</span><span class="cm">,</span> <span class="n">8</span><span class="s">)</span><span class="sc">;</span> <span class="c"># prints 80 == 0x50 == ord('P')</span></li><li></li><li> <a class="l_k" href="../functions/vec.html">vec</a><span class="s">(</span><span class="i">$foo</span><span class="cm">,</span> <span class="n">2</span><span class="cm">,</span> <span class="n">16</span><span class="s">)</span> = <span class="n">0x5065</span><span class="sc">;</span> <span class="c"># 'PerlPe'</span></li><li> <a class="l_k" href="../functions/vec.html">vec</a><span class="s">(</span><span class="i">$foo</span><span class="cm">,</span> <span class="n">3</span><span class="cm">,</span> <span class="n">16</span><span class="s">)</span> = <span class="n">0x726C</span><span class="sc">;</span> <span class="c"># 'PerlPerl'</span></li><li> <a class="l_k" href="../functions/vec.html">vec</a><span class="s">(</span><span class="i">$foo</span><span class="cm">,</span> <span class="n">8</span><span class="cm">,</span> <span class="n">8</span><span class="s">)</span> = <span class="n">0x50</span><span class="sc">;</span> <span class="c"># 'PerlPerlP'</span></li><li> <a class="l_k" href="../functions/vec.html">vec</a><span class="s">(</span><span class="i">$foo</span><span class="cm">,</span> <span class="n">9</span><span class="cm">,</span> <span class="n">8</span><span class="s">)</span> = <span class="n">0x65</span><span class="sc">;</span> <span class="c"># 'PerlPerlPe'</span></li><li> <a class="l_k" href="../functions/vec.html">vec</a><span class="s">(</span><span class="i">$foo</span><span class="cm">,</span> <span class="n">20</span><span class="cm">,</span> <span class="n">4</span><span class="s">)</span> = <span class="n">2</span><span class="sc">;</span> <span class="c"># 'PerlPerlPe' . "\x02"</span></li><li> <a class="l_k" href="../functions/vec.html">vec</a><span class="s">(</span><span class="i">$foo</span><span class="cm">,</span> <span class="n">21</span><span class="cm">,</span> <span class="n">4</span><span class="s">)</span> = <span class="n">7</span><span class="sc">;</span> <span class="c"># 'PerlPerlPer'</span></li><li> <span class="c"># 'r' is "\x72"</span></li><li> <a class="l_k" href="../functions/vec.html">vec</a><span class="s">(</span><span class="i">$foo</span><span class="cm">,</span> <span class="n">45</span><span class="cm">,</span> <span class="n">2</span><span class="s">)</span> = <span class="n">3</span><span class="sc">;</span> <span class="c"># 'PerlPerlPer' . "\x0c"</span></li><li> <a class="l_k" href="../functions/vec.html">vec</a><span class="s">(</span><span class="i">$foo</span><span class="cm">,</span> <span class="n">93</span><span class="cm">,</span> <span class="n">1</span><span class="s">)</span> = <span class="n">1</span><span class="sc">;</span> <span class="c"># 'PerlPerlPer' . "\x2c"</span></li><li> <a class="l_k" href="../functions/vec.html">vec</a><span class="s">(</span><span class="i">$foo</span><span class="cm">,</span> <span class="n">94</span><span class="cm">,</span> <span class="n">1</span><span class="s">)</span> = <span class="n">1</span><span class="sc">;</span> <span class="c"># 'PerlPerlPerl'</span></li><li> <span class="c"># 'l' is "\x6c"</span></li></ol></pre><p>To transform a bit vector into a string or list of 0's and 1's, use these:</p>
<pre class="verbatim"><ol><li> <span class="i">$bits</span> = <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">"b*"</span><span class="cm">,</span> <span class="i">$vector</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">@bits</span> = <a class="l_k" href="../functions/split.html">split</a><span class="s">(</span><span class="q">//</span><span class="cm">,</span> <a class="l_k" href="../functions/unpack.html">unpack</a><span class="s">(</span><span class="q">"b*"</span><span class="cm">,</span> <span class="i">$vector</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>If you know the exact length in bits, it can be used in place of the <code class="inline"><span class="i">*</span></code>
.</p>
<p>Here is an example to illustrate how the bits actually fall in place:</p>
<pre class="verbatim"><ol><li> #!/usr/bin/perl -wl</li><li></li><li> print <<'EOT';</li><li> 0 1 2 3</li><li> unpack("V",$_) 01234567890123456789012345678901</li><li> ------------------------------------------------------------------</li><li> EOT</li><li></li><li> for $w (0..3) {</li><li> $width = 2**$w;</li><li> for ($shift=0; $shift < $width; ++$shift) {</li><li> for ($off=0; $off < 32/$width; ++$off) {</li><li> $str = pack("B*", "0"x32);</li><li> $bits = (1<<$shift);</li><li> vec($str, $off, $width) = $bits;</li><li> $res = unpack("b*",$str);</li><li> $val = unpack("V", $str);</li><li> write;</li><li> }</li><li> }</li><li> }</li><li></li><li> format STDOUT =</li><li> vec($_,@#,@#) = @<< == @######### @>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>></li><li> $off, $width, $bits, $val, $res</li><li> .</li><li> __END__</li></ol></pre><p>Regardless of the machine architecture on which it is run, the above<br>
example should print the following table:</p>
<pre class="verbatim"><ol><li> 0 1 2 3</li><li> unpack("V",$_) 01234567890123456789012345678901</li><li> ------------------------------------------------------------------</li><li> vec($_, 0, 1) = 1 == 1 10000000000000000000000000000000</li><li> vec($_, 1, 1) = 1 == 2 01000000000000000000000000000000</li><li> vec($_, 2, 1) = 1 == 4 00100000000000000000000000000000</li><li> vec($_, 3, 1) = 1 == 8 00010000000000000000000000000000</li><li> vec($_, 4, 1) = 1 == 16 00001000000000000000000000000000</li><li> vec($_, 5, 1) = 1 == 32 00000100000000000000000000000000</li><li> vec($_, 6, 1) = 1 == 64 00000010000000000000000000000000</li><li> vec($_, 7, 1) = 1 == 128 00000001000000000000000000000000</li><li> vec($_, 8, 1) = 1 == 256 00000000100000000000000000000000</li><li> vec($_, 9, 1) = 1 == 512 00000000010000000000000000000000</li><li> vec($_,10, 1) = 1 == 1024 00000000001000000000000000000000</li><li> vec($_,11, 1) = 1 == 2048 00000000000100000000000000000000</li><li> vec($_,12, 1) = 1 == 4096 00000000000010000000000000000000</li><li> vec($_,13, 1) = 1 == 8192 00000000000001000000000000000000</li><li> vec($_,14, 1) = 1 == 16384 00000000000000100000000000000000</li><li> vec($_,15, 1) = 1 == 32768 00000000000000010000000000000000</li><li> vec($_,16, 1) = 1 == 65536 00000000000000001000000000000000</li><li> vec($_,17, 1) = 1 == 131072 00000000000000000100000000000000</li><li> vec($_,18, 1) = 1 == 262144 00000000000000000010000000000000</li><li> vec($_,19, 1) = 1 == 524288 00000000000000000001000000000000</li><li> vec($_,20, 1) = 1 == 1048576 00000000000000000000100000000000</li><li> vec($_,21, 1) = 1 == 2097152 00000000000000000000010000000000</li><li> vec($_,22, 1) = 1 == 4194304 00000000000000000000001000000000</li><li> vec($_,23, 1) = 1 == 8388608 00000000000000000000000100000000</li><li> vec($_,24, 1) = 1 == 16777216 00000000000000000000000010000000</li><li> vec($_,25, 1) = 1 == 33554432 00000000000000000000000001000000</li><li> vec($_,26, 1) = 1 == 67108864 00000000000000000000000000100000</li><li> vec($_,27, 1) = 1 == 134217728 00000000000000000000000000010000</li><li> vec($_,28, 1) = 1 == 268435456 00000000000000000000000000001000</li><li> vec($_,29, 1) = 1 == 536870912 00000000000000000000000000000100</li><li> vec($_,30, 1) = 1 == 1073741824 00000000000000000000000000000010</li><li> vec($_,31, 1) = 1 == 2147483648 00000000000000000000000000000001</li><li> vec($_, 0, 2) = 1 == 1 10000000000000000000000000000000</li><li> vec($_, 1, 2) = 1 == 4 00100000000000000000000000000000</li><li> vec($_, 2, 2) = 1 == 16 00001000000000000000000000000000</li><li> vec($_, 3, 2) = 1 == 64 00000010000000000000000000000000</li><li> vec($_, 4, 2) = 1 == 256 00000000100000000000000000000000</li><li> vec($_, 5, 2) = 1 == 1024 00000000001000000000000000000000</li><li> vec($_, 6, 2) = 1 == 4096 00000000000010000000000000000000</li><li> vec($_, 7, 2) = 1 == 16384 00000000000000100000000000000000</li><li> vec($_, 8, 2) = 1 == 65536 00000000000000001000000000000000</li><li> vec($_, 9, 2) = 1 == 262144 00000000000000000010000000000000</li><li> vec($_,10, 2) = 1 == 1048576 00000000000000000000100000000000</li><li> vec($_,11, 2) = 1 == 4194304 00000000000000000000001000000000</li><li> vec($_,12, 2) = 1 == 16777216 00000000000000000000000010000000</li><li> vec($_,13, 2) = 1 == 67108864 00000000000000000000000000100000</li><li> vec($_,14, 2) = 1 == 268435456 00000000000000000000000000001000</li><li> vec($_,15, 2) = 1 == 1073741824 00000000000000000000000000000010</li><li> vec($_, 0, 2) = 2 == 2 01000000000000000000000000000000</li><li> vec($_, 1, 2) = 2 == 8 00010000000000000000000000000000</li><li> vec($_, 2, 2) = 2 == 32 00000100000000000000000000000000</li><li> vec($_, 3, 2) = 2 == 128 00000001000000000000000000000000</li><li> vec($_, 4, 2) = 2 == 512 00000000010000000000000000000000</li><li> vec($_, 5, 2) = 2 == 2048 00000000000100000000000000000000</li><li> vec($_, 6, 2) = 2 == 8192 00000000000001000000000000000000</li><li> vec($_, 7, 2) = 2 == 32768 00000000000000010000000000000000</li><li> vec($_, 8, 2) = 2 == 131072 00000000000000000100000000000000</li><li> vec($_, 9, 2) = 2 == 524288 00000000000000000001000000000000</li><li> vec($_,10, 2) = 2 == 2097152 00000000000000000000010000000000</li><li> vec($_,11, 2) = 2 == 8388608 00000000000000000000000100000000</li><li> vec($_,12, 2) = 2 == 33554432 00000000000000000000000001000000</li><li> vec($_,13, 2) = 2 == 134217728 00000000000000000000000000010000</li><li> vec($_,14, 2) = 2 == 536870912 00000000000000000000000000000100</li><li> vec($_,15, 2) = 2 == 2147483648 00000000000000000000000000000001</li><li> vec($_, 0, 4) = 1 == 1 10000000000000000000000000000000</li><li> vec($_, 1, 4) = 1 == 16 00001000000000000000000000000000</li><li> vec($_, 2, 4) = 1 == 256 00000000100000000000000000000000</li><li> vec($_, 3, 4) = 1 == 4096 00000000000010000000000000000000</li><li> vec($_, 4, 4) = 1 == 65536 00000000000000001000000000000000</li><li> vec($_, 5, 4) = 1 == 1048576 00000000000000000000100000000000</li><li> vec($_, 6, 4) = 1 == 16777216 00000000000000000000000010000000</li><li> vec($_, 7, 4) = 1 == 268435456 00000000000000000000000000001000</li><li> vec($_, 0, 4) = 2 == 2 01000000000000000000000000000000</li><li> vec($_, 1, 4) = 2 == 32 00000100000000000000000000000000</li><li> vec($_, 2, 4) = 2 == 512 00000000010000000000000000000000</li><li> vec($_, 3, 4) = 2 == 8192 00000000000001000000000000000000</li><li> vec($_, 4, 4) = 2 == 131072 00000000000000000100000000000000</li><li> vec($_, 5, 4) = 2 == 2097152 00000000000000000000010000000000</li><li> vec($_, 6, 4) = 2 == 33554432 00000000000000000000000001000000</li><li> vec($_, 7, 4) = 2 == 536870912 00000000000000000000000000000100</li><li> vec($_, 0, 4) = 4 == 4 00100000000000000000000000000000</li><li> vec($_, 1, 4) = 4 == 64 00000010000000000000000000000000</li><li> vec($_, 2, 4) = 4 == 1024 00000000001000000000000000000000</li><li> vec($_, 3, 4) = 4 == 16384 00000000000000100000000000000000</li><li> vec($_, 4, 4) = 4 == 262144 00000000000000000010000000000000</li><li> vec($_, 5, 4) = 4 == 4194304 00000000000000000000001000000000</li><li> vec($_, 6, 4) = 4 == 67108864 00000000000000000000000000100000</li><li> vec($_, 7, 4) = 4 == 1073741824 00000000000000000000000000000010</li><li> vec($_, 0, 4) = 8 == 8 00010000000000000000000000000000</li><li> vec($_, 1, 4) = 8 == 128 00000001000000000000000000000000</li><li> vec($_, 2, 4) = 8 == 2048 00000000000100000000000000000000</li><li> vec($_, 3, 4) = 8 == 32768 00000000000000010000000000000000</li><li> vec($_, 4, 4) = 8 == 524288 00000000000000000001000000000000</li><li> vec($_, 5, 4) = 8 == 8388608 00000000000000000000000100000000</li><li> vec($_, 6, 4) = 8 == 134217728 00000000000000000000000000010000</li><li> vec($_, 7, 4) = 8 == 2147483648 00000000000000000000000000000001</li><li> vec($_, 0, 8) = 1 == 1 10000000000000000000000000000000</li><li> vec($_, 1, 8) = 1 == 256 00000000100000000000000000000000</li><li> vec($_, 2, 8) = 1 == 65536 00000000000000001000000000000000</li><li> vec($_, 3, 8) = 1 == 16777216 00000000000000000000000010000000</li><li> vec($_, 0, 8) = 2 == 2 01000000000000000000000000000000</li><li> vec($_, 1, 8) = 2 == 512 00000000010000000000000000000000</li><li> vec($_, 2, 8) = 2 == 131072 00000000000000000100000000000000</li><li> vec($_, 3, 8) = 2 == 33554432 00000000000000000000000001000000</li><li> vec($_, 0, 8) = 4 == 4 00100000000000000000000000000000</li><li> vec($_, 1, 8) = 4 == 1024 00000000001000000000000000000000</li><li> vec($_, 2, 8) = 4 == 262144 00000000000000000010000000000000</li><li> vec($_, 3, 8) = 4 == 67108864 00000000000000000000000000100000</li><li> vec($_, 0, 8) = 8 == 8 00010000000000000000000000000000</li><li> vec($_, 1, 8) = 8 == 2048 00000000000100000000000000000000</li><li> vec($_, 2, 8) = 8 == 524288 00000000000000000001000000000000</li><li> vec($_, 3, 8) = 8 == 134217728 00000000000000000000000000010000</li><li> vec($_, 0, 8) = 16 == 16 00001000000000000000000000000000</li><li> vec($_, 1, 8) = 16 == 4096 00000000000010000000000000000000</li><li> vec($_, 2, 8) = 16 == 1048576 00000000000000000000100000000000</li><li> vec($_, 3, 8) = 16 == 268435456 00000000000000000000000000001000</li><li> vec($_, 0, 8) = 32 == 32 00000100000000000000000000000000</li><li> vec($_, 1, 8) = 32 == 8192 00000000000001000000000000000000</li><li> vec($_, 2, 8) = 32 == 2097152 00000000000000000000010000000000</li><li> vec($_, 3, 8) = 32 == 536870912 00000000000000000000000000000100</li><li> vec($_, 0, 8) = 64 == 64 00000010000000000000000000000000</li><li> vec($_, 1, 8) = 64 == 16384 00000000000000100000000000000000</li><li> vec($_, 2, 8) = 64 == 4194304 00000000000000000000001000000000</li><li> vec($_, 3, 8) = 64 == 1073741824 00000000000000000000000000000010</li><li> vec($_, 0, 8) = 128 == 128 00000001000000000000000000000000</li><li> vec($_, 1, 8) = 128 == 32768 00000000000000010000000000000000</li><li> vec($_, 2, 8) = 128 == 8388608 00000000000000000000000100000000</li><li> vec($_, 3, 8) = 128 == 2147483648 00000000000000000000000000000001</li></ol><]]></desc>
</keyword>
<keyword name="wait" type="function">
<params>
</params>
<desc><![CDATA[Behaves like the wait(2) system call on your system: it waits for a child<br>
process to terminate and returns the pid of the deceased process, or<br>
<code class="inline"><span class="n">-1</span></code>
if there are no child processes. The status is returned in <code class="inline"><span class="i">$?</span></code>
<br>
and <code class="inline"><span class="i">$</span>{<span class="w">^CHILD_ERROR_NATIVE</span>}</code>
.<br>
Note that a return value of <code class="inline"><span class="n">-1</span></code>
could mean that child processes are<br>
being automatically reaped, as described in <a href="../perlipc.html">perlipc</a>.]]></desc>
</keyword>
<keyword name="waitpid" type="function">
<params>
<param name='pid'/>
<param name='flags'/>
</params>
<desc><![CDATA[Waits for a particular child process to terminate and returns the pid of<br>
the deceased process, or <code class="inline"><span class="n">-1</span></code>
if there is no such child process. On some<br>
systems, a value of 0 indicates that there are processes still running.<br>
The status is returned in <code class="inline"><span class="i">$?</span></code>
and <code class="inline"><span class="i">$</span>{<span class="w">^CHILD_ERROR_NATIVE</span>}</code>
. If you say</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">POSIX</span> <span class="q">":sys_wait_h"</span><span class="sc">;</span></li><li> <span class="c">#...</span></li><li> <a class="l_k" href="../functions/do.html">do</a> <span class="s">{</span></li><li> <span class="i">$kid</span> = <a class="l_k" href="../functions/waitpid.html">waitpid</a><span class="s">(</span><span class="n">-1</span><span class="cm">,</span> <span class="w">WNOHANG</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span> while <span class="i">$kid</span> > <span class="n">0</span><span class="sc">;</span></li></ol></pre><p>then you can do a non-blocking wait for all pending zombie processes.<br>
Non-blocking wait is available on machines supporting either the<br>
waitpid(2) or wait4(2) system calls. However, waiting for a particular<br>
pid with FLAGS of <code class="inline"><span class="n">0</span></code>
is implemented everywhere. (Perl emulates the<br>
system call by remembering the status values of processes that have<br>
exited but have not been harvested by the Perl script yet.)</p>
<p>Note that on some systems, a return value of <code class="inline"><span class="n">-1</span></code>
could mean that child<br>
processes are being automatically reaped. See <a href="../perlipc.html">perlipc</a> for details,<br>
and for other examples.]]></desc>
</keyword>
<keyword name="wantarray" type="function">
<params>
</params>
<desc><![CDATA[Returns true if the context of the currently executing subroutine or<br>
<code class="inline"><a class="l_k" href="../functions/eval.html">eval</a></code> is looking for a list value. Returns false if the context is<br>
looking for a scalar. Returns the undefined value if the context is<br>
looking for no value (void context).</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/return.html">return</a> unless <a class="l_k" href="../functions/defined.html">defined</a> <a class="l_k" href="../functions/wantarray.html">wantarray</a><span class="sc">;</span> <span class="c"># don't bother doing more</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">@a</span> = <span class="i">complex_calculation</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <a class="l_k" href="../functions/wantarray.html">wantarray</a> ? <span class="i">@a</span> <span class="co">:</span> <span class="q">"@a"</span><span class="sc">;</span></li></ol></pre><p><code class="inline"><a class="l_k" href="../functions/wantarray.html">wantarray()</a></code>'s result is unspecified in the top level of a file,<br>
in a <code class="inline">BEGIN</code>
, <code class="inline">UNITCHECK</code>
, <code class="inline">CHECK</code>
, <code class="inline">INIT</code>
or <code class="inline">END</code>
block, or<br>
in a <code class="inline">DESTROY</code>
method.</p>
<p>This function should have been named wantlist() instead.]]></desc>
</keyword>
<keyword name="warn" type="function">
<params>
<param name='list'/>
</params>
<desc><![CDATA[Prints the value of LIST to STDERR. If the last element of LIST does<br>
not end in a newline, it appends the same file/line number text as <code class="inline"><a class="l_k" href="../functions/die.html">die</a></code>
does.</p>
<p>If LIST is empty and <code class="inline"><span class="i">$@</span></code>
already contains a value (typically from a<br>
previous eval) that value is used after appending <code class="inline"><span class="q">"\t...caught"</span></code>
<br>
to <code class="inline"><span class="i">$@</span></code>
. This is useful for staying almost, but not entirely similar to<br>
<code class="inline"><a class="l_k" href="../functions/die.html">die</a></code>.</p>
<p>If <code class="inline"><span class="i">$@</span></code>
is empty then the string <code class="inline"><span class="q">"Warning: Something's wrong"</span></code>
is used.</p>
<p>No message is printed if there is a <code class="inline"><span class="i">$SIG</span>{<span class="w">__WARN__</span>}</code>
handler<br>
installed. It is the handler's responsibility to deal with the message<br>
as it sees fit (like, for instance, converting it into a <code class="inline"><a class="l_k" href="../functions/die.html">die</a></code>). Most<br>
handlers must therefore make arrangements to actually display the<br>
warnings that they are not prepared to deal with, by calling <code class="inline"><a class="l_k" href="../functions/warn.html">warn</a></code>
again in the handler. Note that this is quite safe and will not<br>
produce an endless loop, since <code class="inline"><span class="w">__WARN__</span></code>
hooks are not called from<br>
inside one.</p>
<p>You will find this behavior is slightly different from that of<br>
<code class="inline"><span class="i">$SIG</span>{<span class="w">__DIE__</span>}</code>
handlers (which don't suppress the error text, but can<br>
instead call <code class="inline"><a class="l_k" href="../functions/die.html">die</a></code> again to change it).</p>
<p>Using a <code class="inline"><span class="w">__WARN__</span></code>
handler provides a powerful way to silence all<br>
warnings (even the so-called mandatory ones). An example:</p>
<pre class="verbatim"><ol><li> <span class="c"># wipe out *all* compile-time warnings</span></li><li> BEGIN <span class="s">{</span> <span class="i">$SIG</span>{<span class="q">'__WARN__'</span>} = <a class="l_k" href="../functions/sub.html">sub</a> <span class="s">{</span> <a class="l_k" href="../functions/warn.html">warn</a> <span class="i">$_</span>[<span class="n">0</span>] if <span class="i">$DOWARN</span> <span class="s">}</span> <span class="s">}</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$foo</span> = <span class="n">10</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$foo</span> = <span class="n">20</span><span class="sc">;</span> <span class="c"># no warning about duplicate my $foo,</span></li><li> <span class="c"># but hey, you asked for it!</span></li><li> <span class="c"># no compile-time or run-time warnings before here</span></li><li> <span class="i">$DOWARN</span> = <span class="n">1</span><span class="sc">;</span></li><li></li><li> <span class="c"># run-time warnings enabled after here</span></li><li> <a class="l_k" href="../functions/warn.html">warn</a> <span class="q">"\$foo is alive and $foo!"</span><span class="sc">;</span> <span class="c"># does show up</span></li></ol></pre><p>See <a href="../perlvar.html">perlvar</a> for details on setting <code class="inline"><span class="i">%SIG</span></code>
entries, and for more<br>
examples. See the Carp module for other kinds of warnings using its<br>
carp() and cluck() functions.]]></desc>
</keyword>
<keyword name="write" type="function">
<params>
<param name='expr'/>
</params>
<desc><![CDATA[Writes a formatted record (possibly multi-line) to the specified FILEHANDLE,<br>
using the format associated with that file. By default the format for<br>
a file is the one having the same name as the filehandle, but the<br>
format for the current output channel (see the <code class="inline"><a class="l_k" href="../functions/select.html">select</a></code> function) may be set<br>
explicitly by assigning the name of the format to the <code class="inline"><span class="i">$~</span></code>
variable.</p>
<p>Top of form processing is handled automatically: if there is<br>
insufficient room on the current page for the formatted record, the<br>
page is advanced by writing a form feed, a special top-of-page format<br>
is used to format the new page header, and then the record is written.<br>
By default the top-of-page format is the name of the filehandle with<br>
"_TOP" appended, but it may be dynamically set to the format of your<br>
choice by assigning the name to the <code class="inline"><span class="i">$^</span></code>
variable while the filehandle is<br>
selected. The number of lines remaining on the current page is in<br>
variable <code class="inline"><span class="i">$-</span></code>
, which can be set to <code class="inline"><span class="n">0</span></code>
to force a new page.</p>
<p>If FILEHANDLE is unspecified, output goes to the current default output<br>
channel, which starts out as STDOUT but may be changed by the<br>
<code class="inline"><a class="l_k" href="../functions/select.html">select</a></code> operator. If the FILEHANDLE is an EXPR, then the expression<br>
is evaluated and the resulting string is used to look up the name of<br>
the FILEHANDLE at run time. For more on formats, see <a href="../perlform.html">perlform</a>.</p>
<p>Note that write is <i>not</i> the opposite of <code class="inline"><a class="l_k" href="../functions/read.html">read</a></code>. Unfortunately.]]></desc>
</keyword>
<keyword name="write" type="function">
<params>
<param name='filehandle'/>
</params>
<desc><![CDATA[Writes a formatted record (possibly multi-line) to the specified FILEHANDLE,<br>
using the format associated with that file. By default the format for<br>
a file is the one having the same name as the filehandle, but the<br>
format for the current output channel (see the <code class="inline"><a class="l_k" href="../functions/select.html">select</a></code> function) may be set<br>
explicitly by assigning the name of the format to the <code class="inline"><span class="i">$~</span></code>
variable.</p>
<p>Top of form processing is handled automatically: if there is<br>
insufficient room on the current page for the formatted record, the<br>
page is advanced by writing a form feed, a special top-of-page format<br>
is used to format the new page header, and then the record is written.<br>
By default the top-of-page format is the name of the filehandle with<br>
"_TOP" appended, but it may be dynamically set to the format of your<br>
choice by assigning the name to the <code class="inline"><span class="i">$^</span></code>
variable while the filehandle is<br>
selected. The number of lines remaining on the current page is in<br>
variable <code class="inline"><span class="i">$-</span></code>
, which can be set to <code class="inline"><span class="n">0</span></code>
to force a new page.</p>
<p>If FILEHANDLE is unspecified, output goes to the current default output<br>
channel, which starts out as STDOUT but may be changed by the<br>
<code class="inline"><a class="l_k" href="../functions/select.html">select</a></code> operator. If the FILEHANDLE is an EXPR, then the expression<br>
is evaluated and the resulting string is used to look up the name of<br>
the FILEHANDLE at run time. For more on formats, see <a href="../perlform.html">perlform</a>.</p>
<p>Note that write is <i>not</i> the opposite of <code class="inline"><a class="l_k" href="../functions/read.html">read</a></code>. Unfortunately.]]></desc>
</keyword>
<keyword name="write" type="function">
<params>
</params>
<desc><![CDATA[Writes a formatted record (possibly multi-line) to the specified FILEHANDLE,<br>
using the format associated with that file. By default the format for<br>
a file is the one having the same name as the filehandle, but the<br>
format for the current output channel (see the <code class="inline"><a class="l_k" href="../functions/select.html">select</a></code> function) may be set<br>
explicitly by assigning the name of the format to the <code class="inline"><span class="i">$~</span></code>
variable.</p>
<p>Top of form processing is handled automatically: if there is<br>
insufficient room on the current page for the formatted record, the<br>
page is advanced by writing a form feed, a special top-of-page format<br>
is used to format the new page header, and then the record is written.<br>
By default the top-of-page format is the name of the filehandle with<br>
"_TOP" appended, but it may be dynamically set to the format of your<br>
choice by assigning the name to the <code class="inline"><span class="i">$^</span></code>
variable while the filehandle is<br>
selected. The number of lines remaining on the current page is in<br>
variable <code class="inline"><span class="i">$-</span></code>
, which can be set to <code class="inline"><span class="n">0</span></code>
to force a new page.</p>
<p>If FILEHANDLE is unspecified, output goes to the current default output<br>
channel, which starts out as STDOUT but may be changed by the<br>
<code class="inline"><a class="l_k" href="../functions/select.html">select</a></code> operator. If the FILEHANDLE is an EXPR, then the expression<br>
is evaluated and the resulting string is used to look up the name of<br>
the FILEHANDLE at run time. For more on formats, see <a href="../perlform.html">perlform</a>.</p>
<p>Note that write is <i>not</i> the opposite of <code class="inline"><a class="l_k" href="../functions/read.html">read</a></code>. Unfortunately.]]></desc>
</keyword>
<keyword name="y" type="function">
<params>
<param name='///'/>
</params>
<desc><![CDATA[The transliteration operator. Same as <code class="inline"><a class="l_k" href="../functions/tr.html">tr///</a></code>. See<br>
<a href="../perlop.html#Quote-and-Quote-like-Operators">"Quote and Quote-like Operators" in perlop</a>.]]></desc>
</keyword>
<keyword name="y" type="function">
<params>
<param name='///'/>
</params>
<desc><![CDATA[The transliteration operator. Same as <code class="inline"><a class="l_k" href="../functions/tr.html">tr///</a></code>. See<br>
<a href="../perlop.html#Quote-and-Quote-like-Operators">"Quote and Quote-like Operators" in perlop</a>.]]></desc>
</keyword>
</keywords>
</api>