PerlBench

 view release on metacpan or  search on metacpan

benchmarks/app/perlfunc.pod  view on Meta::CPAN

C<fileno>, C<flock>, C<format>, C<getc>, C<print>, C<printf>, C<read>,
C<readdir>, C<rewinddir>, C<seek>, C<seekdir>, C<select>, C<syscall>,
C<sysread>, C<sysseek>, C<syswrite>, C<tell>, C<telldir>, C<truncate>,
C<warn>, C<write>

=item Functions for fixed length data or records

C<pack>, C<read>, C<syscall>, C<sysread>, C<syswrite>, C<unpack>, C<vec>

=item Functions for filehandles, files, or directories

C<-I<X>>, C<chdir>, C<chmod>, C<chown>, C<chroot>, C<fcntl>, C<glob>,
C<ioctl>, C<link>, C<lstat>, C<mkdir>, C<open>, C<opendir>,
C<readlink>, C<rename>, C<rmdir>, C<stat>, C<symlink>, C<sysopen>,
C<umask>, C<unlink>, C<utime>

=item Keywords related to the control flow of your Perl program

C<caller>, C<continue>, C<die>, C<do>, C<dump>, C<eval>, C<exit>,
C<goto>, C<last>, C<next>, C<redo>, C<return>, C<sub>, C<wantarray>

=item Keywords related to scoping

C<caller>, C<import>, C<local>, C<my>, C<our>, C<package>, C<use>

=item Miscellaneous functions

C<defined>, C<dump>, C<eval>, C<formline>, C<local>, C<my>, C<our>, C<reset>,
C<scalar>, C<undef>, C<wantarray>

=item Functions for processes and process groups

C<alarm>, C<exec>, C<fork>, C<getpgrp>, C<getppid>, C<getpriority>, C<kill>,
C<pipe>, C<qx/STRING/>, C<setpgrp>, C<setpriority>, C<sleep>, C<system>,
C<times>, C<wait>, C<waitpid>

=item Keywords related to perl modules

C<do>, C<import>, C<no>, C<package>, C<require>, C<use>

=item Keywords related to classes and object-orientedness

C<bless>, C<dbmclose>, C<dbmopen>, C<package>, C<ref>, C<tie>, C<tied>,
C<untie>, C<use>

=item Low-level socket functions

C<accept>, C<bind>, C<connect>, C<getpeername>, C<getsockname>,
C<getsockopt>, C<listen>, C<recv>, C<send>, C<setsockopt>, C<shutdown>,
C<socket>, C<socketpair>

=item System V interprocess communication functions

C<msgctl>, C<msgget>, C<msgrcv>, C<msgsnd>, C<semctl>, C<semget>, C<semop>,
C<shmctl>, C<shmget>, C<shmread>, C<shmwrite>

=item Fetching user and group info

C<endgrent>, C<endhostent>, C<endnetent>, C<endpwent>, C<getgrent>,
C<getgrgid>, C<getgrnam>, C<getlogin>, C<getpwent>, C<getpwnam>,
C<getpwuid>, C<setgrent>, C<setpwent>

=item Fetching network info

C<endprotoent>, C<endservent>, C<gethostbyaddr>, C<gethostbyname>,
C<gethostent>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>,
C<getprotobyname>, C<getprotobynumber>, C<getprotoent>,
C<getservbyname>, C<getservbyport>, C<getservent>, C<sethostent>,
C<setnetent>, C<setprotoent>, C<setservent>

=item Time-related functions

C<gmtime>, C<localtime>, C<time>, C<times>

=item Functions new in perl5

C<abs>, C<bless>, C<chomp>, C<chr>, C<exists>, C<formline>, C<glob>,
C<import>, C<lc>, C<lcfirst>, C<map>, C<my>, C<no>, C<our>, C<prototype>,
C<qx>, C<qw>, C<readline>, C<readpipe>, C<ref>, C<sub*>, C<sysopen>, C<tie>,
C<tied>, C<uc>, C<ucfirst>, C<untie>, C<use>

* - C<sub> was a keyword in perl4, but in perl5 it is an
operator, which can be used in expressions.

=item Functions obsoleted in perl5

C<dbmclose>, C<dbmopen>

=back

=head2 Portability

Perl was born in Unix and can therefore access all common Unix
system calls.  In non-Unix environments, the functionality of some
Unix system calls may not be available, or details of the available
functionality may differ slightly.  The Perl functions affected
by this are:

C<-X>, C<binmode>, C<chmod>, C<chown>, C<chroot>, C<crypt>,
C<dbmclose>, C<dbmopen>, C<dump>, C<endgrent>, C<endhostent>,
C<endnetent>, C<endprotoent>, C<endpwent>, C<endservent>, C<exec>,
C<fcntl>, C<flock>, C<fork>, C<getgrent>, C<getgrgid>, C<gethostbyname>,
C<gethostent>, C<getlogin>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>,
C<getppid>, C<getpgrp>, C<getpriority>, C<getprotobynumber>,
C<getprotoent>, C<getpwent>, C<getpwnam>, C<getpwuid>,
C<getservbyport>, C<getservent>, C<getsockopt>, C<glob>, C<ioctl>,
C<kill>, C<link>, C<lstat>, C<msgctl>, C<msgget>, C<msgrcv>,
C<msgsnd>, C<open>, C<pipe>, C<readlink>, C<rename>, C<select>, C<semctl>,
C<semget>, C<semop>, C<setgrent>, C<sethostent>, C<setnetent>,
C<setpgrp>, C<setpriority>, C<setprotoent>, C<setpwent>,
C<setservent>, C<setsockopt>, C<shmctl>, C<shmget>, C<shmread>,
C<shmwrite>, C<socket>, C<socketpair>,
C<stat>, C<symlink>, C<syscall>, C<sysopen>, C<system>,
C<times>, C<truncate>, C<umask>, C<unlink>,
C<utime>, C<wait>, C<waitpid>

For more information about the portability of these functions, see
L<perlport> and other available platform-specific documentation.

=head2 Alphabetical Listing of Perl Functions

=over 8

=item -X FILEHANDLE

=item -X EXPR

=item -X

A file test, where X is one of the letters listed below.  This unary
operator takes one argument, either a filename or a filehandle, and
tests the associated file to see if something is true about it.  If the
argument is omitted, tests C<$_>, except for C<-t>, which tests STDIN.
Unless otherwise documented, it returns C<1> for true and C<''> for false, or
the undefined value if the file doesn't exist.  Despite the funny
names, precedence is the same as any other named unary operator, and
the argument may be parenthesized like any other unary operator.  The
operator may be any of:
X<-r>X<-w>X<-x>X<-o>X<-R>X<-W>X<-X>X<-O>X<-e>X<-z>X<-s>X<-f>X<-d>X<-l>X<-p>
X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C>

    -r	File is readable by effective uid/gid.
    -w	File is writable by effective uid/gid.
    -x	File is executable by effective uid/gid.
    -o	File is owned by effective uid.

    -R	File is readable by real uid/gid.
    -W	File is writable by real uid/gid.
    -X	File is executable by real uid/gid.
    -O	File is owned by real uid.

    -e	File exists.
    -z	File has zero size (is empty).
    -s	File has nonzero size (returns size in bytes).

    -f	File is a plain file.
    -d	File is a directory.
    -l	File is a symbolic link.
    -p	File is a named pipe (FIFO), or Filehandle is a pipe.
    -S	File is a socket.
    -b	File is a block special file.
    -c	File is a character special file.
    -t	Filehandle is opened to a tty.

    -u	File has setuid bit set.

benchmarks/app/perlfunc.pod  view on Meta::CPAN

=item cos

Returns the cosine of EXPR (expressed in radians).  If EXPR is omitted,
takes cosine of C<$_>.

For the inverse cosine operation, you may use the C<Math::Trig::acos()>
function, or use this relation:

    sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }

=item crypt PLAINTEXT,SALT

Creates a digest string exactly like the crypt(3) function in the C
library (assuming that you actually have a version there that has not
been extirpated as a potential munitions).

crypt() is a one-way hash function.  The PLAINTEXT and SALT is turned
into a short string, called a digest, which is returned.  The same
PLAINTEXT and SALT will always return the same string, but there is no
(known) way to get the original PLAINTEXT from the hash.  Small
changes in the PLAINTEXT or SALT will result in large changes in the
digest.

There is no decrypt function.  This function isn't all that useful for
cryptography (for that, look for F<Crypt> modules on your nearby CPAN
mirror) and the name "crypt" is a bit of a misnomer.  Instead it is
primarily used to check if two pieces of text are the same without
having to transmit or store the text itself.  An example is checking
if a correct password is given.  The digest of the password is stored,
not the password itself.  The user types in a password that is
crypt()'d with the same salt as the stored digest.  If the two digests
match the password is correct.

When verifying an existing digest string you should use the digest as
the salt (like C<crypt($plain, $digest) eq $digest>).  The SALT used
to create the digest is visible as part of the digest.  This ensures
crypt() will hash the new string with the same salt as the digest.
This allows your code to work with the standard L<crypt|/crypt> and
with more exotic implementations.  In other words, do not assume
anything about the returned string itself, or how many bytes in the
digest matter.

Traditionally the result is a string of 13 bytes: two first bytes of
the salt, followed by 11 bytes from the set C<[./0-9A-Za-z]>, and only
the first eight bytes of the digest string mattered, but alternative
hashing schemes (like MD5), higher level security schemes (like C2),
and implementations on non-UNIX platforms may produce different
strings.

When choosing a new salt create a random two character string whose
characters come from the set C<[./0-9A-Za-z]> (like C<join '', ('.',
'/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]>).  This set of
characters is just a recommendation; the characters allowed in
the salt depend solely on your system's crypt library, and Perl can't
restrict what salts C<crypt()> accepts.

Here's an example that makes sure that whoever runs this program knows
their password:

    $pwd = (getpwuid($<))[1];

    system "stty -echo";
    print "Password: ";
    chomp($word = <STDIN>);
    print "\n";
    system "stty echo";

    if (crypt($word, $pwd) ne $pwd) {
	die "Sorry...\n";
    } else {
	print "ok\n";
    }

Of course, typing in your own password to whoever asks you
for it is unwise.

The L<crypt|/crypt> function is unsuitable for hashing large quantities
of data, not least of all because you can't get the information
back.  Look at the L<Digest> module for more robust algorithms.

If using crypt() on a Unicode string (which I<potentially> has
characters with codepoints above 255), Perl tries to make sense
of the situation by trying to downgrade (a copy of the string)
the string back to an eight-bit byte string before calling crypt()
(on that copy).  If that works, good.  If not, crypt() dies with
C<Wide character in crypt>.

=item dbmclose HASH

[This function has been largely superseded by the C<untie> function.]

Breaks the binding between a DBM file and a hash.

=item dbmopen HASH,DBNAME,MASK

[This function has been largely superseded by the C<tie> function.]

This binds a dbm(3), ndbm(3), sdbm(3), gdbm(3), or Berkeley DB file to a
hash.  HASH is the name of the hash.  (Unlike normal C<open>, the first
argument is I<not> a filehandle, even though it looks like one).  DBNAME
is the name of the database (without the F<.dir> or F<.pag> extension if
any).  If the database does not exist, it is created with protection
specified by MASK (as modified by the C<umask>).  If your system supports
only the older DBM functions, you may perform only one C<dbmopen> in your
program.  In older versions of Perl, if your system had neither DBM nor
ndbm, calling C<dbmopen> produced a fatal error; it now falls back to
sdbm(3).

If you don't have write access to the DBM file, you can only read hash
variables, not set them.  If you want to test whether you can write,
either use file tests or try setting a dummy hash entry inside an C<eval>,
which will trap the error.

Note that functions such as C<keys> and C<values> may return huge lists
when used on large DBM files.  You may prefer to use the C<each>
function to iterate over large DBM files.  Example:

    # print out history file offsets
    dbmopen(%HIST,'/usr/lib/news/history',0666);
    while (($key,$val) = each %HIST) {

benchmarks/app/perlfunc.pod  view on Meta::CPAN

=item formline PICTURE,LIST

This is an internal function used by C<format>s, though you may call it,
too.  It formats (see L<perlform>) a list of values according to the
contents of PICTURE, placing the output into the format output
accumulator, C<$^A> (or C<$ACCUMULATOR> in English).
Eventually, when a C<write> is done, the contents of
C<$^A> are written to some filehandle.  You could also read C<$^A>
and then set C<$^A> back to C<"">.  Note that a format typically
does one C<formline> per line of form, but the C<formline> function itself
doesn't care how many newlines are embedded in the PICTURE.  This means
that the C<~> and C<~~> tokens will treat the entire PICTURE as a single line.
You may therefore need to use multiple formlines to implement a single
record format, just like the format compiler.

Be careful if you put double quotes around the picture, because an C<@>
character may be taken to mean the beginning of an array name.
C<formline> always returns true.  See L<perlform> for other examples.

=item getc FILEHANDLE

=item getc

Returns the next character from the input file attached to FILEHANDLE,
or the undefined value at end of file, or if there was an error (in
the latter case C<$!> is set).  If FILEHANDLE is omitted, reads from
STDIN.  This is not particularly efficient.  However, it cannot be
used by itself to fetch single characters without waiting for the user
to hit enter.  For that, try something more like:

    if ($BSD_STYLE) {
	system "stty cbreak </dev/tty >/dev/tty 2>&1";
    }
    else {
	system "stty", '-icanon', 'eol', "\001";
    }

    $key = getc(STDIN);

    if ($BSD_STYLE) {
	system "stty -cbreak </dev/tty >/dev/tty 2>&1";
    }
    else {
	system "stty", 'icanon', 'eol', '^@'; # ASCII null
    }
    print "\n";

Determination of whether $BSD_STYLE should be set
is left as an exercise to the reader.

The C<POSIX::getattr> function can do this more portably on
systems purporting POSIX compliance.  See also the C<Term::ReadKey>
module from your nearest CPAN site; details on CPAN can be found on
L<perlmodlib/CPAN>.

=item getlogin

This implements the C library function of the same name, which on most
systems returns the current login from F</etc/utmp>, if any.  If null,
use C<getpwuid>.

    $login = getlogin || getpwuid($<) || "Kilroy";

Do not consider C<getlogin> for authentication: it is not as
secure as C<getpwuid>.

=item getpeername SOCKET

Returns the packed sockaddr address of other end of the SOCKET connection.

    use Socket;
    $hersockaddr    = getpeername(SOCK);
    ($port, $iaddr) = sockaddr_in($hersockaddr);
    $herhostname    = gethostbyaddr($iaddr, AF_INET);
    $herstraddr     = inet_ntoa($iaddr);

=item getpgrp PID

Returns the current process group for the specified PID.  Use
a PID of C<0> to get the current process group for the
current process.  Will raise an exception if used on a machine that
doesn't implement getpgrp(2).  If PID is omitted, returns process
group of current process.  Note that the POSIX version of C<getpgrp>
does not accept a PID argument, so only C<PID==0> is truly portable.

=item getppid

Returns the process id of the parent process.

Note for Linux users: on Linux, the C functions C<getpid()> and
C<getppid()> return different values from different threads. In order to
be portable, this behavior is not reflected by the perl-level function
C<getppid()>, that returns a consistent value across threads. If you want
to call the underlying C<getppid()>, you may use the CPAN module
C<Linux::Pid>.

=item getpriority WHICH,WHO

Returns the current priority for a process, a process group, or a user.
(See L<getpriority(2)>.)  Will raise a fatal exception if used on a
machine that doesn't implement getpriority(2).

=item getpwnam NAME

=item getgrnam NAME

=item gethostbyname NAME

=item getnetbyname NAME

=item getprotobyname NAME

=item getpwuid UID

=item getgrgid GID

=item getservbyname NAME,PROTO

=item gethostbyaddr ADDR,ADDRTYPE

=item getnetbyaddr ADDR,ADDRTYPE

=item getprotobynumber NUMBER

=item getservbyport PORT,PROTO

=item getpwent

=item getgrent

=item gethostent

=item getnetent

=item getprotoent

=item getservent

=item setpwent

=item setgrent

=item sethostent STAYOPEN

=item setnetent STAYOPEN

=item setprotoent STAYOPEN

=item setservent STAYOPEN

=item endpwent

=item endgrent

=item endhostent

=item endnetent

=item endprotoent

=item endservent

These routines perform the same functions as their counterparts in the
system library.  In list context, the return values from the
various get routines are as follows:

    ($name,$passwd,$uid,$gid,
       $quota,$comment,$gcos,$dir,$shell,$expire) = getpw*
    ($name,$passwd,$gid,$members) = getgr*
    ($name,$aliases,$addrtype,$length,@addrs) = gethost*
    ($name,$aliases,$addrtype,$net) = getnet*
    ($name,$aliases,$proto) = getproto*
    ($name,$aliases,$port,$proto) = getserv*

(If the entry doesn't exist you get a null list.)

The exact meaning of the $gcos field varies but it usually contains
the real name of the user (as opposed to the login name) and other
information pertaining to the user.  Beware, however, that in many
system users are able to change this information and therefore it
cannot be trusted and therefore the $gcos is tainted (see
L<perlsec>).  The $passwd and $shell, user's encrypted password and
login shell, are also tainted, because of the same reason.

In scalar context, you get the name, unless the function was a
lookup by name, in which case you get the other thing, whatever it is.
(If the entry doesn't exist you get the undefined value.)  For example:

    $uid   = getpwnam($name);
    $name  = getpwuid($num);
    $name  = getpwent();
    $gid   = getgrnam($name);
    $name  = getgrgid($num);
    $name  = getgrent();
    #etc.

In I<getpw*()> the fields $quota, $comment, and $expire are special
cases in the sense that in many systems they are unsupported.  If the
$quota is unsupported, it is an empty scalar.  If it is supported, it
usually encodes the disk quota.  If the $comment field is unsupported,
it is an empty scalar.  If it is supported it usually encodes some
administrative comment about the user.  In some systems the $quota
field may be $change or $age, fields that have to do with password
aging.  In some systems the $comment field may be $class.  The $expire
field, if present, encodes the expiration period of the account or the
password.  For the availability and the exact meaning of these fields
in your system, please consult your getpwnam(3) documentation and your
F<pwd.h> file.  You can also find out from within Perl what your
$quota and $comment fields mean and whether you have the $expire field
by using the C<Config> module and the values C<d_pwquota>, C<d_pwage>,
C<d_pwchange>, C<d_pwcomment>, and C<d_pwexpire>.  Shadow password
files are only supported if your vendor has implemented them in the
intuitive fashion that calling the regular C library routines gets the
shadow versions if you're running under privilege or if there exists
the shadow(3) functions as found in System V (this includes Solaris
and Linux.)  Those systems that implement a proprietary shadow password
facility are unlikely to be supported.

The $members value returned by I<getgr*()> is a space separated list of
the login names of the members of the group.

For the I<gethost*()> functions, if the C<h_errno> variable is supported in
C, it will be returned to you via C<$?> if the function call fails.  The
C<@addrs> value returned by a successful call is a list of the raw
addresses returned by the corresponding system library call.  In the
Internet domain, each address is four bytes long and you can unpack it
by saying something like:

    ($a,$b,$c,$d) = unpack('C4',$addr[0]);

The Socket library makes this slightly easier:

    use Socket;
    $iaddr = inet_aton("127.1"); # or whatever address
    $name  = gethostbyaddr($iaddr, AF_INET);

    # or going the other way
    $straddr = inet_ntoa($iaddr);

If you get tired of remembering which element of the return list
contains which return value, by-name interfaces are provided
in standard modules: C<File::stat>, C<Net::hostent>, C<Net::netent>,
C<Net::protoent>, C<Net::servent>, C<Time::gmtime>, C<Time::localtime>,
and C<User::grent>.  These override the normal built-ins, supplying
versions that return objects with the appropriate names
for each field.  For example:

   use File::stat;
   use User::pwent;
   $is_his = (stat($filename)->uid == pwent($whoever)->uid);