ch05_02.htm

by Randal L. Schwartz and Tom Phoenix ISBN 0-596-00132-0 Third Edition, published July 2001. (See

<em class="emphasis">numerical</em> <em class="replaceable"><tt>uid</tt></em> and
<em class="replaceable"><tt>gid</tt></em>, in that order. The function returns
the number of files successfully changed.
</p><p>On most systems, you are not allowed to change the ownership of the
file unless you're the superuser, although you
should be able to change the group to any of your secondary groups.
On insecure systems, these restrictions may be relaxed, but this is
not a portable assumption.
</p></div>

<a name="INDEX-916" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><a name="chr"><b>chr</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><table width="515" border="0" cellpadding="5"><tr><td align="left"><pre>
chr <em class="emphasis">number</em>
</pre></td><td align="right" /></tr></table><a name="INDEX-916" />Returns
the character represented by <em class="replaceable"><tt>number</tt></em> in the
character set. For example, <tt class="literal">chr(65)</tt> is
"A" in ASCII.
</p></div>

<a name="INDEX-917" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><a name="chroot"><b>chroot</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><table width="515" border="0" cellpadding="5"><tr><td align="left"><pre>
chroot <em class="emphasis">dirname</em>
</pre></td><td align="right" /></tr></table><a name="INDEX-917" />Changes the root
directory for the current process to
<em class="replaceable"><tt>dirname</tt></em>&#x2014;the starting point for
pathnames beginning with <tt class="literal">/</tt>. This directory is
inherited across <tt class="literal">exec</tt> calls and by all
subprocesses. There is no way to undo a <tt class="literal">chroot</tt>.
Only the superuser can use this function.
</p></div>

<a name="INDEX-918" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><a name="close"><b>close</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><table width="515" border="0" cellpadding="5"><tr><td align="left"><pre>
close <em class="emphasis">filehandle</em>
</pre></td><td align="right" /></tr></table><a name="INDEX-918" />Closes the file, socket,
or pipe associated with the given filehandle. You
don't have to close
<em class="replaceable"><tt>filehandle</tt></em> if you are immediately going to
do another <tt class="literal">open</tt> on it, since the next
<tt class="literal">open</tt> will close it for you. However, an explicit
<tt class="literal">close</tt> on an input file resets the line counter
(<tt class="literal">$.</tt>), while the implicit <tt class="literal">close</tt>
done by <tt class="literal">open</tt> does not. Closing a pipe will wait
for the process executing on the pipe to complete and will prevent
the script from exiting before the pipeline is finished. Also,
closing a pipe explicitly puts the status value of the command
executing on the pipe into <tt class="literal">$?</tt>.
</p><p><em class="replaceable"><tt>filehandle</tt></em> may be an expression with a
value that gives a real filehandle name. It may also be a reference
to a filehandle object returned by some of the object-oriented I/O
packages.
</p></div>

<a name="INDEX-919" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><a name="closedir"><b>closedir</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><table width="515" border="0" cellpadding="5"><tr><td align="left"><pre>
closedir <em class="emphasis">dirhandle</em>
</pre></td><td align="right" /></tr></table><a name="INDEX-919" />Closes a
directory associated with the given directory handle opened by
<tt class="literal">opendir</tt>.
</p></div>

<a name="INDEX-920" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><a name="connect"><b>connect</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><table width="515" border="0" cellpadding="5"><tr><td align="left"><pre>
connect <em class="emphasis">socket</em>, <em class="emphasis">address</em>
</pre></td><td align="right" /></tr></table><a name="INDEX-920" />Initiates a
connection with another process that is waiting at an
<tt class="literal">accept</tt> on the filehandle
<em class="replaceable"><tt>socket</tt></em>. The function returns true for
success, false otherwise (and puts the error code into
<tt class="literal">$!</tt>). <em class="replaceable"><tt>address</tt></em> is a
packed network address of the proper type for
<em class="replaceable"><tt>socket</tt></em>.
</p><p>To disconnect a socket, use either <tt class="literal">close</tt> or
<tt class="literal">shutdown</tt>.
</p></div>

<a name="INDEX-921" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><a name="cos"><b>cos</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><table width="515" border="0" cellpadding="5"><tr><td align="left"><pre>
cos <em class="emphasis">num</em>
</pre></td><td align="right" /></tr></table><a name="INDEX-921" />Returns the cosine of
<em class="replaceable"><tt>num</tt></em> (expressed in radians). For the
inverse cosine operation, you may use the <tt class="literal">POSIX::acos(
)</tt> function, or use this relation:
</p><blockquote><pre class="code">sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }</pre></blockquote></div>

<a name="INDEX-922" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><a name="crypt"><b>crypt</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><table width="515" border="0" cellpadding="5"><tr><td align="left"><pre>
crypt <em class="emphasis">string</em>, <em class="emphasis">salt</em>
</pre></td><td align="right" /></tr></table><a name="INDEX-922" />Used by the
<tt class="literal">passwd</tt> function on Unix systems to produce a
unique 13-character string (stored in the system's
password file) from the first 8 characters of the given
<em class="replaceable"><tt>string</tt></em> and the 2-character
<em class="replaceable"><tt>salt</tt></em>. The Perl function operates the same
way and returns a 13-character string with the first 2 characters as
the <em class="replaceable"><tt>salt</tt></em>. <tt class="literal">crypt</tt> uses a
modified version of the Data Encryption Standard, which produces a
one-way encryption; the resulting string cannot be decrypted to
determine the original string. <tt class="literal">crypt</tt> can be used
to check that a password is correct by comparing the string from the
function to the string found in <em class="emphasis">/etc/passwd</em> (if
you have permission to do this):
</p><blockquote><pre class="code">if (crypt ($guess, $pass) eq $pass) {
       # guess is correct
   }</pre></blockquote><p>The variable <tt class="literal">$pass</tt> is the password string from the
password file. <tt class="literal">crypt</tt> merely uses the first two
characters from this string for the <em class="replaceable"><tt>salt</tt></em>argument.
</p></div>

<a name="INDEX-923" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><a name="dbmclose"><b>dbmclose</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><table width="515" border="0" cellpadding="5"><tr><td align="left"><pre>
dbmclose %<em class="emphasis">hash</em>
</pre></td><td align="right" /></tr></table><a name="INDEX-923" />Breaks the
binding between a DBM file and a hash.
</p><p>This function is actually just a call to <tt class="literal">untie</tt>
with the proper arguments, but is provided for backward compatibility
with older versions of Perl.
</p></div>

<a name="INDEX-924" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><a name="dbmopen"><b>dbmopen</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><table width="515" border="0" cellpadding="5"><tr><td align="left"><pre>
dbmopen %<em class="emphasis">hash</em>, <em class="emphasis">dbname</em>, <em class="emphasis">mode</em>
</pre></td><td align="right" /></tr></table><a name="INDEX-924" />Binds a DBM file
(<em class="replaceable"><tt>dbname</tt></em>) to a hash
(%<em class="replaceable"><tt>hash</em>). <em class="replaceable">dbname</em>is the name of the database without the <em class="emphasis">.dir</tt></em> or
<em class="emphasis">.pag</em> extension. Note that while not deprecated,
<tt class="literal">dbmopen</tt> has basically been superseded by
<tt class="literal">tie( )</tt>. If the database does not exist, and a
valid mode is specified, the database is created with the permissions
specified by <em class="replaceable"><tt>mode</tt></em> (as modified by the
umask). To prevent creation of the database if it
doesn't exist, you may specify a
<em class="replaceable"><tt>mode</tt></em> of <tt class="literal">undef</tt>, and the
function will return a false value if it can't find
an existing database. If your system supports only the older DBM
functions, you may have only one <tt class="literal">dbmopen</tt> in your
program.
</p><p>Values assigned to the hash prior to the <tt class="literal">dbmopen</tt>
are not accessible. If you don't have write access
to the DBM file, you can only read the hash variables, not set them.
</p><p>This function is actually just a call to <tt class="literal">tie</tt> with
the proper arguments, but is provided for backward compatibility with
older versions of Perl.
</p></div>

<a name="INDEX-925" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><a name="defined"><b>defined</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><table width="515" border="0" cellpadding="5"><tr><td align="left"><pre>
defined <em class="emphasis">expr</em>
</pre></td><td align="right" /></tr></table><a name="INDEX-925" />Returns a Boolean
value saying whether the scalar value resulting from
<em class="replaceable"><tt>expr</tt></em> has a real value. If no argument is
given, <tt class="literal">defined</tt> checks <tt class="literal">$_</tt>.
</p><p>A scalar that contains no valid string, numeric, or reference value
is known as the undefined value, or <tt class="literal">undef</tt>. Many
operations return the undefined value under exceptional conditions,
such as end-of-file, uninitialized variable, system error, and so on.
This function allows you to distinguish between an undefined null
string and a defined null string when you're using
operators that might return a real null string.
</p><p>You can use <tt class="literal">defined</tt> to see if a subroutine exists,
that is, if the subroutine definition has been successfully parsed.
However, using <tt class="literal">defined</tt> on an array or a hash is
not guaranteed to produce intuitive results and should be avoided.
</p></div>

<a name="INDEX-926" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><a name="delete"><b>delete</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><table width="515" border="0" cellpadding="5"><tr><td align="left"><pre>
delete $<em class="emphasis">hash</em>{<em class="emphasis">key</em>}
delete @<em class="replaceable"><tt>hash</em>{@<em class="replaceable">keys</tt></em>}
</pre></td><td align="right" /></tr></table><a name="INDEX-926" />Deletes the specified
<em class="replaceable"><tt>key</em> or <em class="replaceable">keys</tt></em> and
associated values from the specified <em class="replaceable"><tt>hash</tt></em>.
(It doesn't delete a file. See <a href="ch05_02.htm#">unlink</a> for that.) Deleting from
<tt class="literal">$ENV{}</tt> modifies the environment. Deleting from a
hash that is bound to a (writable) DBM file deletes the entry from
the DBM file.
</p><p>For normal hashes, the <tt class="literal">delete</tt> function returns the
value (not the key) that was deleted, but this behavior is not
guaranteed for tied hashes, such as those bound to DBM files. To test
whether a hash element has been deleted, use
<tt class="literal">exists</tt>.
</p></div>

<a name="INDEX-927" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><a name="die"><b>die</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><table width="515" border="0" cellpadding="5"><tr><td align="left"><pre>
die <em class="emphasis">message</em>
</pre></td><td align="right" /></tr></table><a name="INDEX-927" />Prints
<em class="replaceable"><tt>message</tt></em> to the standard error output and
exits the Perl program with a nonzero exit status.
<em class="replaceable"><tt>message</tt></em> can be a list value, like the
arguments to <tt class="literal">print</tt>, from which the elements are