was never a list to start with.
In general, functions in Perl that serve as wrappers for system calls
-of the same name (like C<chown(2)>, C<fork(2)>, C<closedir(2)>, etc.) all return
+of the same name (like chown(2), fork(2), closedir(2), etc.) all return
true when they succeed and C<undef> otherwise, as is usually mentioned
in the descriptions below. This is different from the C interfaces,
which return C<-1> on failure. Exceptions to this rule are C<wait()>,
=item Functions for SCALARs or strings
C<chomp>, C<chop>, C<chr>, C<crypt>, C<hex>, C<index>, C<lc>, C<lcfirst>,
-C<length>, C<oct>, C<ord>, C<pack>, C<q>/STRING/, C<qq>/STRING/, C<reverse>,
-C<rindex>, C<sprintf>, C<substr>, C<tr///>, C<uc>, C<ucfirst>, C<y>///
+C<length>, C<oct>, C<ord>, C<pack>, C<q/STRING/>, C<qq/STRING/>, C<reverse>,
+C<rindex>, C<sprintf>, C<substr>, C<tr///>, C<uc>, C<ucfirst>, C<y///>
=item Regular expressions and pattern matching
-C<m>//, C<pos>, C<quotemeta>, C<s>///, C<split>, C<study>
+C<m//>, C<pos>, C<quotemeta>, C<s///>, C<split>, C<study>, C<qr//>
=item Numeric functions
=item Functions for list data
-C<grep>, C<join>, C<map>, C<qw>/STRING/, C<reverse>, C<sort>, C<unpack>
+C<grep>, C<join>, C<map>, C<qw/STRING/>, C<reverse>, C<sort>, C<unpack>
=item Functions for real %HASHes
=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<umask>, C<unlink>, C<utime>
+C<ioctl>, C<link>, C<lstat>, C<mkdir>, C<open>, C<opendir>,
+C<readlink>, C<rename>, C<rmdir>, C<stat>, C<symlink>, 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>
+C<caller>, C<continue>, C<die>, C<do>, C<dump>, C<else>, C<elsif>,
+C<eval>, C<exit>, C<for>, C<foreach>, C<goto>, C<if>, C<last>,
+C<next>, C<redo>, C<return>, C<sub>, C<unless>, C<wantarray>,
+C<while>, C<until>
=item Keywords related to scoping
=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<pipe>, C<qx/STRING/>, C<setpgrp>, C<setpriority>, C<sleep>, C<system>,
C<times>, C<wait>, C<waitpid>
=item Keywords related to perl modules
=back
+=head2 Portability
+
+Perl was born in UNIX and therefore it can access all the common UNIX
+system calls. In non-UNIX environments the functionality of many
+UNIX system calls may not be available or the details of the available
+functionality may be slightly different. 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<gethostent>,
+C<getlogin>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>,
+C<getppid>, C<getprgp>, 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<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<socketpair>, C<stat>, C<symlink>, C<syscall>,
+C<sysopen>, C<system>, C<times>, C<truncate>, C<umask>, 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
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.
-f File is a plain file.
-d File is a directory.
-l File is a symbolic link.
- -p File is a named pipe (FIFO).
+ -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.
-A Same for access time.
-C Same for inode change time.
-The interpretation of the file permission operators C<-r>, C<-R>, C<-w>,
-C<-W>, C<-x>, and C<-X> is based solely on the mode of the file and the
-uids and gids of the user. There may be other reasons you can't actually
-read, write, or execute the file, such as AFS access control lists. Also note that, for the superuser,
-C<-r>, C<-R>, C<-w>, and C<-W> always return C<1>, and C<-x> and C<-X> return
-C<1> if any execute bit is set in the mode. Scripts run by the superuser may
-thus need to do a C<stat()> to determine the actual mode of the
-file, or temporarily set the uid to something else.
-
Example:
while (<>) {
#...
}
+The interpretation of the file permission operators C<-r>, C<-R>,
+C<-w>, C<-W>, C<-x>, and C<-X> is by default based solely on the mode
+of the file and the uids and gids of the user. There may be other
+reasons you can't actually read, write, or execute the file. Such
+reasons may be for example network filesystem access controls, ACLs
+(access control lists), read-only filesystems, and unrecognized
+executable formats.
+
+Also note that, for the superuser on the local filesystems, C<-r>,
+C<-R>, C<-w>, and C<-W> always return 1, and C<-x> and C<-X> return 1
+if any execute bit is set in the mode. Scripts run by the superuser
+may thus need to do a stat() to determine the actual mode of the file,
+or temporarily set the uid to something else.
+
+If you are using ACLs, there is a pragma called C<filetest> that may
+produce more accurate results than the bare stat() mode bits.
+
+When under the C<use filetest 'access'> the above-mentioned filetests
+will test whether the permission can (not) be granted using the
+access() family of system calls. Also note that the C<-x> and C<-X> may
+under this pragma return true even if there are no execute permission
+bits set (nor any extra execute permission ACLs). This strangeness is
+due to the underlying system calls' definitions. Read the
+documentation for the C<filetest> pragma for more information.
+
Note that C<-s/a/b/> does not do a negated substitution. Saying
C<-exp($foo)> still works as expected, however--only single letters
following a minus are interpreted as file tests.
=item accept NEWSOCKET,GENERICSOCKET
-Accepts an incoming socket connect, just as the C<accept(2)> system call
+Accepts an incoming socket connect, just as the accept(2) system call
does. Returns the packed address if it succeeded, FALSE otherwise.
See example in L<perlipc/"Sockets: Client/Server Communication">.
on the previous timer.
For delays of finer granularity than one second, you may use Perl's
-C<syscall()> interface to access C<setitimer(2)> if your system supports it,
+C<syscall()> interface to access setitimer(2) if your system supports it,
or else see L</select()>. It is usually a mistake to intermix C<alarm()>
and C<sleep()> calls.
If you want to use C<alarm()> to time out a system call you need to use an
-C<eval>/C<die> pair. You can't rely on the alarm causing the system call to
-fail with C<$!> set to EINTR because Perl sets up signal handlers to
-restart system calls on some systems. Using C<eval>/C<die> always works,
+C<eval()>/C<die()> pair. You can't rely on the alarm causing the system call to
+fail with C<$!> set to C<EINTR> because Perl sets up signal handlers to
+restart system calls on some systems. Using C<eval()>/C<die()> always works,
modulo the caveats given in L<perlipc/"Signals">.
eval {
- local $SIG{ALRM} = sub { die "alarm\n" }; # NB: \n required
+ local $SIG{ALRM} = sub { die "alarm\n" }; # NB: \n required
alarm $timeout;
$nread = sysread SOCKET, $buffer, $size;
alarm 0;
};
if ($@) {
- die unless $@ eq "alarm\n"; # propagate unexpected errors
+ die unless $@ eq "alarm\n"; # propagate unexpected errors
# timed out
}
else {
translated to CR LF on output. Binmode has no effect under Unix; in MS-DOS
and similarly archaic systems, it may be imperative--otherwise your
MS-DOS-damaged C library may mangle your file. The key distinction between
-systems that need C<binmode> and those that don't is their text file
+systems that need C<binmode()> and those that don't is their text file
formats. Systems like Unix, MacOS, and Plan9 that delimit lines with a single
character, and that encode that character in C as C<"\n">, do not need
-C<binmode>. The rest need it. If FILEHANDLE is an expression, the value
+C<binmode()>. The rest need it. If FILEHANDLE is an expression, the value
is taken as the name of the filehandle.
=item bless REF,CLASSNAME
might be inherited by a derived class. See L<perltoot> and L<perlobj>
for more about the blessing (and blessings) of objects.
+Creating objects in lowercased CLASSNAMEs should be avoided. Such
+namespaces should be considered reserved for Perl pragmata and objects
+that may be created to implement internal operations.
+
+See L<perlmod/"Perl Modules">.
+
=item caller EXPR
=item caller
$hasargs, $wantarray, $evaltext, $is_require) = caller($i);
Here C<$subroutine> may be C<"(eval)"> if the frame is not a subroutine
-call, but an C<eval>. In such a case additional elements C<$evaltext> and
+call, but an C<eval()>. In such a case additional elements C<$evaltext> and
C<$is_require> are set: C<$is_require> is true if the frame is created by a
C<require> or C<use> statement, C<$evaltext> contains the text of the
C<eval EXPR> statement. In particular, for a C<eval BLOCK> statement,
arguments with which the subroutine was invoked.
Be aware that the optimizer might have optimized call frames away before
-C<caller> had a chance to get the information. That means that C<caller(N)>
+C<caller()> had a chance to get the information. That means that C<caller(N)>
might not return information about the call frame you expect it do, for
C<N E<gt> 1>. In particular, C<@DB::args> might have information from the
previous time C<caller()> was called.
$cnt = chmod 0755, 'foo', 'bar';
chmod 0755, @executables;
- $mode = '0644'; chmod $mode, 'foo'; # !!! sets mode to --w----r-T
+ $mode = '0644'; chmod $mode, 'foo'; # !!! sets mode to
+ # --w----r-T
$mode = '0644'; chmod oct($mode), 'foo'; # this is better
$mode = 0644; chmod $mode, 'foo'; # this is best
chop($answer = <STDIN>);
If you chop a list, each element is chopped. Only the value of the
-last C<chop> is returned.
+last C<chop()> is returned.
-Note that C<chop> returns the last character. To return all but the last
+Note that C<chop()> returns the last character. To return all but the last
character, use C<substr($string, 0, -1)>.
=item chown LIST
=item chr
Returns the character represented by that NUMBER in the character set.
-For example, C<chr(65)> is C<"A"> in ASCII. For the reverse, use L</ord>.
+For example, C<chr(65)> is C<"A"> in either ASCII or Unicode, and
+chr(0x263a) is a Unicode smiley face (but only within the scope of a
+C<use utf8>). For the reverse, use L</ord>.
If NUMBER is omitted, uses C<$_>.
begin with a C<"/"> by your process and all its children. (It doesn't
change your current working directory, which is unaffected.) For security
reasons, this call is restricted to the superuser. If FILENAME is
-omitted, does a C<chroot> to C<$_>.
+omitted, does a C<chroot()> to C<$_>.
=item close FILEHANDLE
You don't have to close FILEHANDLE if you are immediately going to do
another C<open()> on it, because C<open()> will close it for you. (See
-C<open()>.) However, an explicit C<close> on an input file resets the line
+C<open()>.) However, an explicit C<close()> on an input file resets the line
counter (C<$.>), while the implicit close done by C<open()> does not.
-If the file handle came from a piped open C<close> will additionally
+If the file handle came from a piped open C<close()> will additionally
return FALSE if one of the other system calls involved fails or if the
program exits with non-zero status. (If the only problem was that the
program exited non-zero C<$!> will be set to C<0>.) Also, closing a pipe
=item continue BLOCK
Actually a flow control statement rather than a function. If there is a
-C<continue> BLOCK attached to a BLOCK (typically in a C<while> or
-C<foreach>), it is always executed just before the conditional is about to
-be evaluated again, just like the third part of a C<for> loop in C. Thus
+C<continue> BLOCK attached to a BLOCK (typically in a L</while> or
+L</foreach>), it is always executed just before the conditional is about to
+be evaluated again, just like the third part of a L</for> loop in C. Thus
it can be used to increment a loop variable, even when the loop has been
continued via the C<next> statement (which is similar to the C C<continue>
statement).
-C<last>, C<next>, or C<redo> may appear within a C<continue>
+L</last>, L</next>, or L</redo> may appear within a C<continue>
block. C<last> and C<redo> will behave as if they had been executed within
the main block. So will C<next>, but since it will execute a C<continue>
block, it may be more entertaining.
empty one, logically enough. In that case, C<next> goes directly back
to check the condition at the top of the loop.
+See also L<perlsyn>.
+
=item cos EXPR
Returns the cosine of EXPR (expressed in radians). If EXPR is omitted,
=item crypt PLAINTEXT,SALT
-Encrypts a string exactly like the C<crypt(3)> function in the C library
+Encrypts a 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 munition). This can prove useful for checking
the password file for lousy passwords, amongst other things. Only the
function. As a result, this function isn't all that useful for
cryptography. (For that, see your nearby CPAN mirror.)
+When verifying an existing encrypted string you should use the encrypted
+text as the salt (like C<crypt($plain, $crypted) eq $crypted>). This
+allows your code to work with the standard C<crypt()> and with more
+exotic implementations. 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]>).
+
Here's an example that makes sure that whoever runs this program knows
their own password:
$pwd = (getpwuid($<))[1];
- $salt = substr($pwd, 0, 2);
system "stty -echo";
print "Password: ";
- chop($word = <STDIN>);
+ chomp($word = <STDIN>);
print "\n";
system "stty echo";
- if (crypt($word, $salt) ne $pwd) {
+ if (crypt($word, $pwd) ne $pwd) {
die "Sorry...\n";
} else {
print "ok\n";
[This function has been 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
+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
Not really a function. Returns the value of the last command in the
sequence of commands indicated by BLOCK. When modified by a loop
-modifier, executes the BLOCK once before testing the loop condition.
-(On other statements the loop modifiers test the conditional first.)
+modifier such as L</while> or L</until>, executes the BLOCK once
+before testing the loop condition. (On other statements the loop
+modifiers test the conditional first.)
+
+C<do BLOCK> does I<not> count as a loop, so the loop control statements
+L</next>, L</last> or L</redo> cannot be used to leave or restart the block.
=item do SUBROUTINE(LIST)
reparse the file every time you call it, so you probably don't want to
do this inside a loop.
+If C<do> cannot read the file, it returns undef and sets C<$!> to the
+error. If C<do> can read the file but cannot compile it, it
+returns undef and sets an error message in C<$@>. If the file is
+successfully compiled, C<do> returns the value of the last expression
+evaluated.
+
Note that inclusion of library modules is better done with the
C<use()> and C<require()> operators, which also do automatic error checking
and raise an exception if there's a problem.
file. Manual error checking can be done this way:
# read in config files: system first, then user
- for $file ('/share/prog/defaults.rc", "$ENV{HOME}/.someprogrc") {
+ for $file ("/share/prog/defaults.rc",
+ "$ENV{HOME}/.someprogrc") {
unless ($return = do $file) {
- warn "couldn't parse $file: $@" if $@;
- warn "couldn't do $file: $!" unless defined $return;
- warn "couldn't run $file" unless $return;
+ warn "couldn't parse $file: $@" if $@;
+ warn "couldn't do $file: $!" unless defined $return;
+ warn "couldn't run $file" unless $return;
}
}
after having initialized all your variables at the beginning of the
program. When the new binary is executed it will begin by executing a
C<goto LABEL> (with all the restrictions that C<goto> suffers). Think of
-it as a goto with an intervening core dump and reincarnation. If LABEL
+it as a goto with an intervening core dump and reincarnation. If C<LABEL>
is omitted, restarts the program from the top. WARNING: Any files
opened at the time of the dump will NOT be open any more when the
program is reincarnated, with possible resulting confusion on the part
false; you may wish to avoid constructs like C<while ($k = each %foo) {}>
for this reason.)
-Entries are returned in an apparently random order. When the hash is
-entirely read, a null array is returned in list context (which when
-assigned produces a FALSE (C<0>) value), and C<undef> in
+Entries are returned in an apparently random order. The actual random
+order is subject to change in future versions of perl, but it is guaranteed
+to be in the same order as either the C<keys()> or C<values()> function
+would produce on the same (unmodified) hash.
+
+When the hash is entirely read, a null array is returned in list context
+(which when assigned produces a FALSE (C<0>) value), and C<undef> in
scalar context. The next call to C<each()> after that will start iterating
again. There is a single iterator for each hash, shared by all C<each()>,
C<keys()>, and C<values()> function calls in the program; it can be reset by
C<values HASH>. If you add or delete elements of a hash while you're
iterating over it, you may get entries skipped or duplicated, so don't.
-The following prints out your environment like the C<printenv(1)> program,
+The following prints out your environment like the printenv(1) program,
only in a different order:
while (($key,$value) = each %ENV) {
print "$key=$value\n";
}
-See also C<keys()> and C<values()>.
+See also C<keys()>, C<values()> and C<sort()>.
+
+=item else BLOCK
+
+=item elsif (EXPR) BLOCK
+
+See L</if>.
=item eof FILEHANDLE
purpose, as shown in this example:
# a very private exception trap for divide-by-zero
- eval { local $SIG{'__DIE__'}; $answer = $a / $b; }; warn $@ if $@;
+ eval { local $SIG{'__DIE__'}; $answer = $a / $b; };
+ warn $@ if $@;
This is especially significant, given that C<__DIE__> hooks can call
C<die()> again, which has the effect of changing their error messages:
# __DIE__ hooks may modify error messages
{
- local $SIG{'__DIE__'} = sub { (my $x = $_[0]) =~ s/foo/bar/g; die $x };
+ local $SIG{'__DIE__'} =
+ sub { (my $x = $_[0]) =~ s/foo/bar/g; die $x };
eval { die "foo lives here" };
print $@ if $@; # prints "bar lives here"
}
particular situation, you can just use symbolic references instead, as
in case 6.
+C<eval BLOCK> does I<not> count as a loop, so the loop control statements
+C<next>, C<last> or C<redo> cannot be used to leave or restart the block.
+
+
=item exec LIST
=item exec PROGRAM LIST
{ exec ('foo') }; print STDERR "couldn't exec foo: $!";
If there is more than one argument in LIST, or if LIST is an array
-with more than one value, calls C<execvp(3)> with the arguments in LIST.
+with more than one value, calls execvp(3) with the arguments in LIST.
If there is only one scalar argument or an array with one element in it,
the argument is checked for shell metacharacters, and if there are any,
the entire argument is passed to the system's command shell for parsing
be subject to its quirks and capabilities. See L<perlop/"`STRING`">
for details.
-Using an indirect object with C<exec> or C<system> is also more secure.
+Using an indirect object with C<exec()> or C<system()> is also more secure.
This usage forces interpretation of the arguments as a multivalued list,
even if the list had just one argument. That way you're safe from the
shell expanding wildcards or splitting up words with whitespace in them.
@args = ( "echo surprise" );
- system @args; # subject to shell escapes if @args == 1
+ system @args; # subject to shell escapes
+ # if @args == 1
system { $args[0] } @args; # safe even with one-arg list
The first version, the one without the indirect object, ran the I<echo>
didn't--it tried to run a program literally called I<"echo surprise">,
didn't find it, and set C<$?> to a non-zero value indicating failure.
-Note that C<exec> will not call your C<END> blocks, nor will it call
+Note that C<exec()> will not call your C<END> blocks, nor will it call
any C<DESTROY> methods in your objects.
=item exists EXPR
=item fcntl FILEHANDLE,FUNCTION,SCALAR
-Implements the C<fcntl(2)> function. You'll probably have to say
+Implements the fcntl(2) function. You'll probably have to say
use Fcntl;
fcntl($filehandle, F_GETFL, $packed_return_buffer)
or die "can't fcntl F_GETFL: $!";
-You don't have to check for C<defined> on the return from
-C<fnctl>. Like C<ioctl>, it maps a C<0> return from the system
+You don't have to check for C<defined()> on the return from
+C<fnctl()>. Like C<ioctl()>, it maps a C<0> return from the system
call into "C<0> but true" in Perl. This string is true in
boolean context and C<0> in numeric context. It is also
exempt from the normal B<-w> warnings on improper numeric
conversions.
Note that C<fcntl()> will produce a fatal error if used on a machine that
-doesn't implement C<fcntl(2)>.
+doesn't implement fcntl(2).
=item fileno FILEHANDLE
=item flock FILEHANDLE,OPERATION
-Calls C<flock(2)>, or an emulation of it, on FILEHANDLE. Returns TRUE for
+Calls flock(2), or an emulation of it, on FILEHANDLE. Returns TRUE for
success, FALSE on failure. Produces a fatal error if used on a machine
-that doesn't implement C<flock(2)>, C<fcntl(2)> locking, or C<lockf(3)>. C<flock()>
+that doesn't implement flock(2), fcntl(2) locking, or lockf(3). C<flock()>
is Perl's portable file locking interface, although it locks only entire
files, not records.
To avoid the possibility of mis-coordination, Perl flushes FILEHANDLE
before (un)locking it.
-Note that the emulation built with C<lockf(3)> doesn't provide shared
+Note that the emulation built with lockf(3) doesn't provide shared
locks, and it requires that FILEHANDLE be open with write intent. These
-are the semantics that C<lockf(3)> implements. Most (all?) systems
-implement C<lockf(3)> in terms of C<fcntl(2)> locking, though, so the
+are the semantics that lockf(3) implements. Most (all?) systems
+implement lockf(3) in terms of fcntl(2) locking, though, so the
differing semantics shouldn't bite too many people.
Note also that some versions of C<flock()> cannot lock things over the
network; you would need to use the more system-specific C<fcntl()> for
-that. If you like you can force Perl to ignore your system's C<flock(2)>
-function, and so provide its own C<fcntl(2)>-based emulation, by passing
+that. If you like you can force Perl to ignore your system's flock(2)
+function, and so provide its own fcntl(2)-based emulation, by passing
the switch C<-Ud_flock> to the F<Configure> program when you configure
perl.
See also L<DB_File> for other flock() examples.
+=item for (INITIAL; WHILE; EACH) BLOCK
+
+Do INITIAL, enter BLOCK while EXPR is true, at the end of each round
+do EACH. For example:
+
+ for ($i = 0, $j = 0; $i < 10; $i++) {
+ if ($i % 3 == 0) { $j++ }
+ print "i = $i, j = $j\n";
+ }
+
+See L<perlsyn> for more details. See also L</foreach>, a twin of
+C<for>, L</while> and L</until>, close cousins of L<for>, and
+L</last>, L</next>, and L</redo> for additional control flow.
+
+=item foreach LOOPVAR (LIST) BLOCK
+
+Enter BLOCK as LOOPVAR set in turn to each element of LIST.
+For example:
+
+ foreach $rolling (@stones) { print "rolling $stone\n" }
+
+ foreach my $file (@files) { print "file $file\n" }
+
+The LOOPVAR is optional and defaults to C<$_>. If the elements are
+modifiable (as opposed to constants or tied variables) you can modify them.
+
+ foreach (@words) { tr/abc/xyz/ }
+
+See L<perlsyn> for more details. See also L</for>, a twin of
+C<foreach>, L</while> and L</until>, close cousins of L<for>, and
+L</last>, L</next>, and L</redo> for additional control flow.
+
=item fork
-Does a C<fork(2)> system call. Returns the child pid to the parent process,
+Does a fork(2) system call. Returns the child pid to the parent process,
C<0> to the child process, or C<undef> if the fork is unsuccessful.
Note: unflushed buffers remain unflushed in both processes, which means
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 C<getpgrp(2)>. If PID is omitted, returns process
+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.
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 C<getpriority(2)>.
+machine that doesn't implement getpriority(2).
=item getpwnam NAME
aging. In some systems the C<$comment> field may be C<$class>. The C<$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 C<getpwnam(3)> documentation and your
+in your system, please consult your getpwnam(3) documentation and your
F<pwd.h> file. You can also find out from within Perl which meaning
your C<$quota> and C<$comment> fields have and whether you have the C<$expire>
field by using the C<Config> module and the values C<d_pwquota>, C<d_pwage>,
If EXPR is omitted, does C<gmtime(time())>.
-In scalar context, returns the C<ctime(3)> value:
+In scalar context, returns the ctime(3) value:
$now_string = gmtime; # e.g., "Thu Oct 13 04:54:34 1994"
Also see the C<timegm()> function provided by the C<Time::Local> module,
-and the C<strftime(3)> function available via the POSIX module.
+and the strftime(3) function available via the POSIX module.
This scalar value is B<not> locale dependent, see L<perllocale>, but
instead a Perl builtin. Also see the C<Time::Local> module, and the
-C<strftime(3)> and C<mktime(3)> function available via the POSIX module. To
+strftime(3) and mktime(3) function available via the POSIX module. To
get somewhat similar but locale dependent date strings, set up your
locale environment variables appropriately (please see L<perllocale>)
and try for example:
or to get out of a block or subroutine given to C<sort()>.
It can be used to go almost anywhere else within the dynamic scope,
including out of subroutines, but it's usually better to use some other
-construct such as C<last> or C<die>. The author of Perl has never felt the
+construct such as C<last> or C<die()>. The author of Perl has never felt the
need to use this form of C<goto> (in Perl, that is--C is another matter).
The C<goto-EXPR> form expects a label name, whose scope will be resolved
=item grep EXPR,LIST
-This is similar in spirit to, but not the same as, C<grep(1)>
+This is similar in spirit to, but not the same as, grep(1)
and its relatives. In particular, it is not limited to using
regular expressions.
to modify the elements of the array. While this is useful and
supported, it can cause bizarre results if the LIST is not a named
array. Similarly, grep returns aliases into the original list,
-much like the way that a for loops's index variable aliases the list
+much like the way that a for loop's index variable aliases the list
elements. That is, modifying an element of a list returned by grep
-(for example, in a C<foreach>, C<map> or another C<grep>)
+(for example, in a C<foreach>, C<map()> or another C<grep()>)
actually modifies the element in the original list.
See also L</map> for an array composed of the results of the BLOCK or EXPR.
print hex '0xAf'; # prints '175'
print hex 'aF'; # same
+=item if (EXPR) BLOCK
+
+=item if (EXPR) BLOCK else BLOCK2
+
+=item if (EXPR) BLOCK elsif (EXPR2) BLOCK2
+
+Enter BLOCKs conditionally. The first EXPR to return true
+causes the corresponding BLOCK to be entered, or, in the case
+of C<else>, the fall-through default BLOCK.
+
+Take notice: Perl wants BLOCKS, expressions (like e.g. in C, C++, or
+Pascal) won't do.
+
+See L<perlsyn> for more details. See also C<unless>.
+
=item import
There is no builtin C<import()> function. It is just an ordinary
=item ioctl FILEHANDLE,FUNCTION,SCALAR
-Implements the C<ioctl(2)> function. You'll probably have to say
+Implements the ioctl(2) function. You'll probably have to say
require "ioctl.ph"; # probably in /usr/local/lib/perl/ioctl.ph
(There is a Perl script called B<h2ph> that comes with the Perl kit that
may help you in this, but it's nontrivial.) SCALAR will be read and/or
written depending on the FUNCTION--a pointer to the string value of SCALAR
-will be passed as the third argument of the actual C<ioctl> call. (If SCALAR
+will be passed as the third argument of the actual C<ioctl()> call. (If SCALAR
has no string value but does have a numeric value, that value will be
passed rather than a pointer to the string value. To guarantee this to be
TRUE, add a C<0> to the scalar before using it.) The C<pack()> and C<unpack()>
|| die "Can't ioctl: $!";
}
-The return value of C<ioctl> (and C<fcntl>) is as follows:
+The return value of C<ioctl()> (and C<fcntl()>) is as follows:
if OS returns: then Perl returns:
-1 undefined value
Returns a list consisting of all the keys of the named hash. (In a
scalar context, returns the number of keys.) The keys are returned in
-an apparently random order, but it is the same order as either the
-C<values()> or C<each()> function produces (given that the hash has not been
-modified). As a side effect, it resets HASH's iterator.
+an apparently random order. The actual random order is subject to
+change in future versions of perl, but it is guaranteed to be the same
+order as either the C<values()> or C<each()> function produces (given
+that the hash has not been modified). As a side effect, it resets
+HASH's iterator.
Here is yet another way to print your environment:
print $key, '=', $ENV{$key}, "\n";
}
-To sort an array by value, you'll need to use a C<sort> function.
+To sort a hash by value, you'll need to use a C<sort()> function.
Here's a descending numeric sort of a hash by its values:
foreach $key (sort { $hash{$b} <=> $hash{$a} } keys %hash) {
printf "%4d %s\n", $hash{$key}, $key;
}
-As an lvalue C<keys> allows you to increase the number of hash buckets
+As an lvalue C<keys()> allows you to increase the number of hash buckets
allocated for the given hash. This can gain you a measure of efficiency if
you know the hash is going to get big. (This is similar to pre-extending
an array by assigning a larger number to $#array.) If you say
keys %hash = 200;
-then C<%hash> will have at least 200 buckets allocated for it--256 of them, in fact, since
-it rounds up to the next power of two. These
+then C<%hash> will have at least 200 buckets allocated for it--256 of them,
+in fact, since it rounds up to the next power of two. These
buckets will be retained even if you do C<%hash = ()>, use C<undef
%hash> if you want to free the storage while C<%hash> is still in scope.
You can't shrink the number of buckets allocated for the hash using
-C<keys> in this way (but you needn't worry about doing this by accident,
+C<keys()> in this way (but you needn't worry about doing this by accident,
as trying has no effect).
+See also C<each()>, C<values()> and C<sort()>.
+
=item kill LIST
Sends a signal to a list of processes. The first element of
#...
}
-See also L</continue> for an illustration of how C<last>, C<next>, and
-C<redo> work.
+C<last> cannot be used to exit a block which returns a value such as
+C<eval {}>, C<sub {}> or C<do {}>.
+
+See also L</continue> for an illustration of how C<last>, L</next>, and
+L</redo> work.
+
+See also L<perlsyn>.
=item lc EXPR
Returns an lowercased version of EXPR. This is the internal function
implementing the C<\L> escape in double-quoted strings.
-Respects current
C<LC_CTYPE> locale if C<use locale> in force. See L<perllocale>.
+Respects current
LC_CTYPE locale if C<use locale> in force. See L<perllocale>.
If EXPR is omitted, uses C<$_>.
Returns the value of EXPR with the first character lowercased. This is
the internal function implementing the C<\l> escape in double-quoted strings.
-Respects current
C<LC_CTYPE> locale if C<use locale> in force. See L<perllocale>.
+Respects current
LC_CTYPE locale if C<use locale> in force. See L<perllocale>.
If EXPR is omitted, uses C<$_>.
=item length
-Returns the length in bytes of the value of EXPR. If EXPR is
+Returns the length in characters of the value of EXPR. If EXPR is
omitted, returns length of C<$_>.
=item link OLDFILE,NEWFILE
If EXPR is omitted, uses the current time (C<localtime(time)>).
-In scalar context, returns the C<ctime(3)> value:
+In scalar context, returns the ctime(3) value:
$now_string = localtime; # e.g., "Thu Oct 13 04:54:34 1994"
This scalar value is B<not> locale dependent, see L<perllocale>, but
instead a Perl builtin. Also see the C<Time::Local> module, and the
-C<strftime(3)> and C<mktime(3)> function available via the POSIX module. To
+strftime(3) and mktime(3) function available via the POSIX module. To
get somewhat similar but locale dependent date strings, set up your
locale environment variables appropriately (please see L<perllocale>)
and try for example:
=item mkdir FILENAME,MODE
-Creates the directory specified by FILENAME, with permissions specified
-by MODE (as modified by umask). If it succeeds it returns TRUE, otherwise
-it returns FALSE and sets C<$!> (errno).
+Creates the directory specified by FILENAME, with permissions
+specified by MODE (as modified by C<umask>). If it succeeds it
+returns TRUE, otherwise it returns FALSE and sets C<$!> (errno).
+
+In general, it is better to create directories with permissive MODEs,
+and let the user modify that with their C<umask>, than it is to supply
+a restrictive MODE and give the user no way to be more permissive.
+The exceptions to this rule are when the file or directory should be
+kept private (mail files, for instance). The perlfunc(1) entry on
+C<umask> discusses the choice of MODE in more detail.
=item msgctl ID,CMD,ARG
-Calls the System V IPC function C<msgctl(2)>. You'll probably have to say
+Calls the System V IPC function msgctl(2). You'll probably have to say
use IPC::SysV;
first to get the correct constant definitions. If CMD is C<IPC_STAT>,
then ARG must be a variable which will hold the returned C<msqid_ds>
-structure. Returns like C<ioctl>: the undefined value for error, "C<0> but
+structure. Returns like C<ioctl()>: the undefined value for error, "C<0> but
true" for zero, or the actual return value otherwise. See also
C<IPC::SysV> and C<IPC::Semaphore::Msg> documentation.
=item msgget KEY,FLAGS
-Calls the System V IPC function C<msgget(2)>. Returns the message queue
+Calls the System V IPC function msgget(2). Returns the message queue
id, or the undefined value if there is an error. See also C<IPC::SysV>
and C<IPC::SysV::Msg> documentation.
=item my EXPR
-A C<my> declares the listed variables to be local (lexically) to the
-enclosing block, file, or C<eval>. If
+A C<my()> declares the listed variables to be local (lexically) to the
+enclosing block, file, or C<eval()>. If
more than one value is listed, the list must be placed in parentheses. See
L<perlsub/"Private Variables via my()"> for details.
executed even on discarded lines. If the LABEL is omitted, the command
refers to the innermost enclosing loop.
-See also L</continue> for an illustration of how C<last>, C<next>, and
-C<redo> work.
+C<next> cannot be used to exit a block which returns a value such as
+C<eval {}>, C<sub {}> or C<do {}>.
+
+See also L</continue> for an illustration of how L</last>, C<next>, and
+L</redo> work.
+
+See also L<perlsyn>.
=item no Module LIST
FILEHANDLE. If FILEHANDLE is an expression, its value is used as the
name of the real filehandle wanted. If EXPR is omitted, the scalar
variable of the same name as the FILEHANDLE contains the filename.
-(Note that lexical variables--those declared with C<my>--will not work
-for this purpose; so if you're using C<my>, specify EXPR in your call
+(Note that lexical variables--those declared with C<my()>--will not work
+for this purpose; so if you're using C<my()>, specify EXPR in your call
to open.)
If the filename begins with C<'E<lt>'> or nothing, the file is opened for input.
always preferred for read/write updates--the C<'+E<gt>'> mode would clobber the
file first. You can't usually use either read-write mode for updating
textfiles, since they have variable length records. See the B<-i>
-switch in L<perlrun> for a better approach.
+switch in L<perlrun> for a better approach. The file is created with
+permissions of C<0666> modified by the process' C<umask> value.
The prefix and the filename may be separated with spaces.
-These various prefixes correspond to the C<fopen(3)> modes of C<'r'>, C<'r+'>, C<'w'>,
+These various prefixes correspond to the fopen(3) modes of C<'r'>, C<'r+'>, C<'w'>,
C<'w+'>, C<'a'>, and C<'a+'>.
If the filename begins with C<'|'>, the filename is interpreted as a
and L<perlipc/"Bidirectional Communication"> for alternatives.)
Opening C<'-'> opens STDIN and opening C<'E<gt>-'> opens STDOUT. Open returns
-nonzero upon success, the undefined value otherwise. If the C<open>
+nonzero upon success, the undefined value otherwise. If the C<open()>
involved a pipe, the return value happens to be the pid of the
subprocess.
If you're unfortunate enough to be running Perl on a system that
distinguishes between text files and binary files (modern operating
systems don't care), then you should check out L</binmode> for tips for
-dealing with this. The key distinction between systems that need C<binmode>
+dealing with this. The key distinction between systems that need C<binmode()>
and those that don't is their text file formats. Systems like Unix, MacOS, and
Plan9, which delimit lines with a single character, and which encode that
-character in C as C<"\n">, do not need C<binmode>. The rest need it.
+character in C as C<"\n">, do not need C<binmode()>. The rest need it.
When opening a file, it's usually a bad idea to continue normal execution
-if the request failed, so C<open> is frequently used in connection with
-C<die>. Even if C<die> won't do what you want (say, in a CGI script,
+if the request failed, so C<open()> is frequently used in connection with
+C<die()>. Even if C<die()> won't do what you want (say, in a CGI script,
where you want to make a nicely formatted error message (but there are
modules that can help with that problem)) you should always check
the return value from opening a file. The infrequent exception is when
NOTE: On any operation that may do a fork, any unflushed buffers remain
unflushed in both processes, which means you may need to set C<$|> to
-avoid duplicate output.
+avoid duplicate output. On systems that support a close-on-exec flag on
+files, the flag will be set for the newly opened file descriptor as
+determined by the value of $^F. See L<perlvar/$^F>.
Closing any piped filehandle causes the parent process to wait for the
child to finish, and returns the status value in C<$?>.
The filename passed to open will have leading and trailing
-whitespace deleted, and the normal redirection chararacters
+whitespace deleted, and the normal redirection characters
honored. This property, known as "magic open",
can often be used to good effect. A user could specify a filename of
F<"rsh cat file |">, or you could change certain filenames as needed:
=item ord
-Returns the numeric ascii value of the first character of EXPR. If
+Returns the numeric (ASCII or Unicode) value of the first character of EXPR. If
EXPR is omitted, uses C<$_>. For the reverse, see L</chr>.
=item pack TEMPLATE,LIST
H A hex string (high nybble first).
c A signed char value.
- C An unsigned char value.
+ C An unsigned char value. Only does bytes. See U for Unicode.
s A signed short value.
S An unsigned short value.
i A signed integer value.
I An unsigned integer value.
- (This 'integer' is _at_least_ 32 bits wide. Its exact size
- depends on what a local C compiler calls 'int', and may
- even be larger than the 'long' described in the next item.)
+ (This 'integer' is _at_least_ 32 bits wide. Its exact
+ size depends on what a local C compiler calls 'int',
+ and may even be larger than the 'long' described in
+ the next item.)
l A signed long value.
L An unsigned long value.
(These 'shorts' and 'longs' are _exactly_ 16 bits and
_exactly_ 32 bits, respectively.)
+ q A signed quad (64-bit) value.
+ Q An unsigned quad value.
+ (Available only if your system supports 64-bit integer values
+ _and_ if Perl has been compiled to support those.
+ Causes a fatal error otherwise.)
+
f A single-precision float in the native format.
d A double-precision float in the native format.
P A pointer to a structure (fixed-length string).
u A uuencoded string.
+ U A Unicode character number. Encodes to UTF-8 internally.
+ Works even if C<use utf8> is not in effect.
w A BER compressed integer. Its bytes represent an unsigned
- integer in base 128, most significant digit first, with as few
- digits as possible. Bit eight (the high bit) is set on each
- byte except the last.
+ integer in base 128, most significant digit first, with as
+ few digits as possible. Bit eight (the high bit) is set
+ on each byte except the last.
x A null byte.
X Back up a byte.
Examples:
- $foo = pack("cccc",65,66,67,68);
+ $foo = pack("CCCC",65,66,67,68);
# foo eq "ABCD"
- $foo = pack("c4",65,66,67,68);
+ $foo = pack("C4",65,66,67,68);
# same thing
+ $foo = pack("U4",0x24b6,0x24b7,0x24b8,0x24b9);
+ # same thing with Unicode circled letters
$foo = pack("ccxxcc",65,66,67,68);
# foo eq "AB\0\0CD"
See L<IPC::Open2>, L<IPC::Open3>, and L<perlipc/"Bidirectional Communication">
for examples of such things.
+On systems that support a close-on-exec flag on files, the flag will be set
+for the newly opened file descriptors as determined by the value of $^F.
+See L<perlvar/$^F>.
+
=item pop ARRAY
=item pop
Equivalent to C<print FILEHANDLE sprintf(FORMAT, LIST)>, except that C<$\>
(the output record separator) is not appended. The first argument
-of the list will be interpreted as the C<printf> format. If C<use locale> is
+of the list will be interpreted as the C<printf()> format. If C<use locale> is
in effect, the character used for the decimal point in formatted real numbers
is affected by the LC_NUMERIC locale. See L<perllocale>.
If FUNCTION is a string starting with C<CORE::>, the rest is taken as
a name for Perl builtin. If builtin is not I<overridable> (such as
-C<qw>) or its arguments cannot be expressed by a prototype (such as
-C<system>) - in other words, the builtin does not behave like a Perl
+C<qw//>) or its arguments cannot be expressed by a prototype (such as
+C<system()>) - in other words, the builtin does not behave like a Perl
function - returns C<undef>. Otherwise, the string describing the
equivalent prototype is returned.
=item qq/STRING/
+=item qr/STRING/
+
=item qx/STRING/
=item qw/STRING/
-Generalized quotes. See L<perlop>.
+Generalized quotes. See L<perlop/"Regexp Quote-Like Operators">.
=item quotemeta EXPR
C<0> at end of file, or undef if there was an error. SCALAR will be grown
or shrunk to the length actually read. An OFFSET may be specified to
place the read data at some other place than the beginning of the
-string. This call is actually implemented in terms of stdio's C<fread(3)>
-call. To get a true C<read(2)> system call, see C<sysread()>.
+string. This call is actually implemented in terms of stdio's fread(3)
+call. To get a true read(2) system call, see C<sysread()>.
=item readdir DIRHANDLE
=item redo
The C<redo> command restarts the loop block without evaluating the
-conditional again. The C<continue> block, if any, is not executed. If
+conditional again. The L</continue> block, if any, is not executed. If
the LABEL is omitted, the command refers to the innermost enclosing
loop. This command is normally used by programs that want to lie to
themselves about what was just input:
print;
}
-See also L</continue> for an illustration of how C<last>, C<next>, and
+C<redo> cannot be used to retry a block which returns a value such as
+C<eval {}>, C<sub {}> or C<do {}>.
+
+See also L</continue> for an illustration of how L</last>, L</next>, and
C<redo> work.
+See also L<perlsyn>.
+
=item ref EXPR
=item ref
In other words, if you try this:
- require Foo::Bar; # a splendid bareword
+ require Foo::Bar; # a splendid bareword
The require function will actually look for the "F<Foo/Bar.pm>" file in the
directories specified in the C<@INC> array.
But if you try this:
$class = 'Foo::Bar';
- require $class; # $class is not a bareword
+ require $class; # $class is not a bareword
#or
- require "Foo::Bar"; # not a bareword because of the ""
+ require "Foo::Bar"; # not a bareword because of the ""
The require function will look for the "F<Foo::Bar>" file in the @INC array and
will complain about not finding "F<Foo::Bar>" there. In this case you can do:
In list context, returns a list value consisting of the elements
of LIST in the opposite order. In scalar context, concatenates the
-elements of LIST, and returns a string value consisting of those bytes,
-but in the opposite order.
+elements of LIST, and returns a string value with all the characters
+in the opposite order.
print reverse <>; # line tac, last line first
undef $/; # for efficiency of <>
- print scalar reverse <>; # byte tac, last line tsrif
+ print scalar reverse <>; # character tac, last line tsrif
This operator is also handy for inverting a hash, although there are some
caveats. If a value is duplicated in the original hash, only one of those
=item seek FILEHANDLE,POSITION,WHENCE
-Sets FILEHANDLE's position, just like the C<fseek()> call of C<stdio>.
+Sets FILEHANDLE's position, just like the C<fseek()> call of C<stdio()>.
FILEHANDLE may be an expression whose value gives the name of the
filehandle. The values for WHENCE are C<0> to set the new position to
POSITION, C<1> to set it to the current position plus POSITION, and C<2> to
On some systems you have to do a seek whenever you switch between reading
and writing. Amongst other things, this may have the effect of calling
-stdio's C<clearerr(3)>. A WHENCE of C<1> (C<SEEK_CUR>) is useful for not moving
+stdio's clearerr(3). A WHENCE of C<1> (C<SEEK_CUR>) is useful for not moving
the file position:
seek(TEST,0,1);
you may need something more like this:
for (;;) {
- for ($curpos = tell(FILE); $_ = <FILE>; $curpos = tell(FILE)) {
+ for ($curpos = tell(FILE); $_ = <FILE>;
+ $curpos = tell(FILE)) {
# search for some stuff and put it into files
}
sleep($for_a_while);
Returns the currently selected filehandle. Sets the current default
filehandle for output, if FILEHANDLE is supplied. This has two
-effects: first, a C<write> or a C<print> without a filehandle will
+effects: first, a C<write()> or a C<print()> without a filehandle will
default to this FILEHANDLE. Second, references to variables related to
output will refer to this output channel. For example, if you have to
set the top of form format for more than one output channel, you might
=item select RBITS,WBITS,EBITS,TIMEOUT
-This calls the C<select(2)> system call with the bit masks specified, which
+This calls the select(2) system call with the bit masks specified, which
can be constructed using C<fileno()> and C<vec()>, along these lines:
$rin = $win = $ein = '';
=item semctl ID,SEMNUM,CMD,ARG
-Calls the System V IPC function C<semctl>. You'll probably have to say
+Calls the System V IPC function C<semctl()>. You'll probably have to say
use IPC::SysV;
first to get the correct constant definitions. If CMD is IPC_STAT or
GETALL, then ARG must be a variable which will hold the returned
-semid_ds structure or semaphore value array. Returns like C<ioctl>: the
+semid_ds structure or semaphore value array. Returns like C<ioctl()>: the
undefined value for error, "C<0> but true" for zero, or the actual return
value otherwise. See also C<IPC::SysV> and C<IPC::Semaphore> documentation.
Sets the current process group for the specified PID, C<0> for the current
process. Will produce a fatal error if used on a machine that doesn't
-implement C<setpgrp(2)>. If the arguments are omitted, it defaults to
+implement setpgrp(2). If the arguments are omitted, it defaults to
C<0,0>. Note that the POSIX version of C<setpgrp()> does not accept any
arguments, so only setpgrp C<0,0> is portable.
=item setpriority WHICH,WHO,PRIORITY
Sets the current priority for a process, a process group, or a user.
-(See C<setpriority(2)>.) Will produce a fatal error if used on a machine
-that doesn't implement C<setpriority(2)>.
+(See setpriority(2).) Will produce a fatal error if used on a machine
+that doesn't implement setpriority(2).
=item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
Shuts down a socket connection in the manner indicated by HOW, which
has the same interpretation as in the system call of the same name.
- shutdown(SOCKET, 0); # I/we have stopped reading data
- shutdown(SOCKET, 1); # I/we have stopped writing data
- shutdown(SOCKET, 2); # I/we have stopped using this socket
+ shutdown(SOCKET, 0); # I/we have stopped reading data
+ shutdown(SOCKET, 1); # I/we have stopped writing data
+ shutdown(SOCKET, 2); # I/we have stopped using this socket
This is useful with sockets when you want to tell the other
side you're done writing but not done reading, or vice versa.
busy multitasking system.
For delays of finer granularity than one second, you may use Perl's
-C<syscall()> interface to access C<setitimer(2)> if your system supports it,
+C<syscall()> interface to access setitimer(2) if your system supports it,
or else see L</select()> above.
See also the POSIX module's C<sigpause()> function.
for the system call of the same name. If unimplemented, yields a fatal
error. Returns TRUE if successful.
-Some systems defined C<pipe()> in terms of C<socketpair>, in which a call
+Some systems defined C<pipe()> in terms of C<socketpair()>, in which a call
to C<pipe(Rdr, Wtr)> is essentially:
use Socket;
=item sort LIST
Sorts the LIST and returns the sorted list value. If SUBNAME or BLOCK
-is omitted, C<sort>s in standard string comparison order. If SUBNAME is
+is omitted, C<sort()>s in standard string comparison order. If SUBNAME is
specified, it gives the name of a subroutine that returns an integer
less than, equal to, or greater than C<0>, depending on how the elements
of the array are to be ordered. (The C<E<lt>=E<gt>> and C<cmp>
use C</$variable/o>.)
As a special case, specifying a PATTERN of space (C<' '>) will split on
-white space just as C<split> with no arguments does. Thus, C<split(' ')> can
+white space just as C<split()> with no arguments does. Thus, C<split(' ')> can
be used to emulate B<awk>'s default behavior, whereas C<split(/ /)>
will give you as many null initial fields as there are leading spaces.
-A C<split> on C</\s+/> is like a C<split(' ')> except that any leading
-whitespace produces a null first field. A C<split> with no arguments
+A C<split()> on C</\s+/> is like a C<split(' ')> except that any leading
+whitespace produces a null first field. A C<split()> with no arguments
really does a C<split(' ', $_)> internally.
Example:
open(PASSWD, '/etc/passwd');
while (<PASSWD>) {
- ($login, $passwd, $uid, $gid, $gcos,$home, $shell) = split(/:/);
+ ($login, $passwd, $uid, $gid,
+ $gcos, $home, $shell) = split(/:/);
#...
}
=item sprintf FORMAT, LIST
-Returns a string formatted by the usual C<printf> conventions of the
+Returns a string formatted by the usual C<printf()> conventions of the
C library function C<sprintf()>. See L<sprintf(3)> or L<printf(3)>
on your system for an explanation of the general principles.
0 use zeros, not spaces, to right-justify
# prefix non-zero octal with "0", non-zero hex with "0x"
number minimum field width
- .number "precision": digits after decimal point for floating-point,
- max length for string, minimum length for integer
+ .number "precision": digits after decimal point for
+ floating-point, max length for string, minimum length
+ for integer
l interpret integer as C type "long" or "unsigned long"
h interpret integer as C type "short" or "unsigned short"
=item srand
-Sets the random number seed for the C<rand> operator. If EXPR is
-omitted, uses a semi-random value based on the current time and process
+Sets the random number seed for the C<rand()> operator. If EXPR is
+omitted, uses a semi-random value supplied by the kernel (if it supports
+the F</dev/urandom> device) or based on the current time and process
ID, among other things. In versions of Perl prior to 5.004 the default
seed was just the current C<time()>. This isn't a particularly good seed,
so many old programs supply their own seed value (often C<time ^ $$> or
In fact, it's usually not necessary to call C<srand()> at all, because if
it is not called explicitly, it is called implicitly at the first use of
-the C<rand> operator. However, this was not the case in version of Perl
+the C<rand()> operator. However, this was not the case in version of Perl
before 5.004, so if your script will run under older Perl versions, it
should call C<srand()>.
(This works on machines only for which the device number is negative under NFS.)
-In scalar context, C<stat> returns a boolean value indicating success
+In scalar context, C<stat()> returns a boolean value indicating success
or failure, and, if successful, sets the information associated with
the special filehandle C<_>.
run times with and without it to see which runs faster. Those loops
which scan for many short constant strings (including the constant
parts of more complex patterns) will benefit most. You may have only
-one C<study> active at a time -- if you study a different scalar the first
-is "unstudied". (The way C<study> works is this: a linked list of every
+one C<study()> active at a time -- if you study a different scalar the first
+is "unstudied". (The way C<study()> works is this: a linked list of every
character in the string to be searched is made, so we know, for
example, where all the C<'k'> characters are. From each search string,
the rarest character is selected, based on some static frequency tables
first place.
Note that if you have to look for strings that you don't know till
-runtime, you can build an entire loop as a string and C<eval> that to
+runtime, you can build an entire loop as a string and C<eval()> that to
avoid recompiling all your patterns all the time. Together with
undefining C<$/> to input entire files as one record, this can be very
-fast, often faster than specialized programs like C<fgrep(1)>. The following
+fast, often faster than specialized programs like fgrep(1). The following
scans a list of files (C<@files>) for a list of words (C<@words>), and prints
out the names of those files that contain a match:
which in practice should usually suffice.
Syscall returns whatever value returned by the system call it calls.
-If the system call fails, C<syscall> returns C<-1> and sets C<$!> (errno).
+If the system call fails, C<syscall()> returns C<-1> and sets C<$!> (errno).
Note that some system calls can legitimately return C<-1>. The proper
way to handle such calls is to assign C<$!=0;> before the call and
check the value of C<$!> if syscall returns C<-1>.
There's a problem with C<syscall(&SYS_pipe)>: it returns the file
number of the read end of the pipe it creates. There is no way
to retrieve the file number of the other end. You can avoid this
-problem by using C<pipe> instead.
+problem by using C<pipe()> instead.
=item sysopen FILEHANDLE,FILENAME,MODE
Opens the file whose filename is given by FILENAME, and associates it
with FILEHANDLE. If FILEHANDLE is an expression, its value is used as
the name of the real filehandle wanted. This function calls the
-underlying operating system's C<open> function with the parameters
+underlying operating system's C<open()> function with the parameters
FILENAME, MODE, PERMS.
The possible values and flag bits of the MODE parameter are
system-dependent; they are available via the standard module C<Fcntl>.
-However, for historical reasons, some values are universal: zero means
-read-only, one means write-only, and two means read/write.
+For historical reasons, some values work on almost every system
+supported by perl: zero means read-only, one means write-only, and two
+means read/write. We know that these values do I<not> work under
+OS/390 & VM/ESA Unix and on the Macintosh; you probably don't want to
+use them in new code.
-If the file named by FILENAME does not exist and the C<open> call creates
+If the file named by FILENAME does not exist and the C<open()> call creates
it (typically because MODE includes the C<O_CREAT> flag), then the value of
PERMS specifies the permissions of the newly created file. If you omit
-the PERMS argument to C<sysopen>, Perl uses the octal value C<0666>.
+the PERMS argument to C<sysopen()>, Perl uses the octal value C<0666>.
These permission values need to be in octal, and are modified by your
-process's current C<umask>. The C<umask> value is a number representing
-disabled permissions bits--if your C<umask> were C<027> (group can't write;
-others can't read, write, or execute), then passing C<sysopen> C<0666> would
-create a file with mode C<0640> (C<0666 &~ 027> is C<0640>).
-
-If you find this C<umask> talk confusing, here's some advice: supply a
-creation mode of C<0666> for regular files and one of C<0777> for directories
-(in C<mkdir>) and executable files. This gives users the freedom of
-choice: if they want protected files, they might choose process umasks
-of C<022>, C<027>, or even the particularly antisocial mask of C<077>. Programs
-should rarely if ever make policy decisions better left to the user.
-The exception to this is when writing files that should be kept private:
-mail files, web browser cookies, I<.rhosts> files, and so on. In short,
-seldom if ever use C<0644> as argument to C<sysopen> because that takes
-away the user's option to have a more permissive umask. Better to omit it.
+process's current C<umask>.
+
+Seldom if ever use C<0644> as argument to C<sysopen()> because that
+takes away the user's option to have a more permissive umask. Better
+to omit it. See the perlfunc(1) entry on C<umask> for more on this.
The C<IO::File> module provides a more object-oriented approach, if you're
into that kind of thing.
=item sysread FILEHANDLE,SCALAR,LENGTH
Attempts to read LENGTH bytes of data into variable SCALAR from the
-specified FILEHANDLE, using the system call C<read(2)>. It bypasses
-stdio, so mixing this with other kinds of reads, C<print()>, C<write()>,
-C<seek()>, or C<tell()> can cause confusion because stdio usually buffers
-data. Returns the number of bytes actually read, C<0> at end of file,
-or undef if there was an error. SCALAR will be grown or shrunk so that
-the last byte actually read is the last byte of the scalar after the read.
+specified FILEHANDLE, using the system call read(2). It bypasses stdio,
+so mixing this with other kinds of reads, C<print()>, C<write()>,
+C<seek()>, C<tell()>, or C<eof()> can cause confusion because stdio
+usually buffers data. Returns the number of bytes actually read, C<0>
+at end of file, or undef if there was an error. SCALAR will be grown or
+shrunk so that the last byte actually read is the last byte of the
+scalar after the read.
An OFFSET may be specified to place the read data at some place in the
string other than the beginning. A negative OFFSET specifies
=item sysseek FILEHANDLE,POSITION,WHENCE
-Sets FILEHANDLE's system position using the system call C<lseek(2)>. It
+Sets FILEHANDLE's system position using the system call lseek(2). It
bypasses stdio, so mixing this with reads (other than C<sysread()>),
-C<print()>, C<write()>, C<seek()>, or C<tell()> may cause confusion. FILEHANDLE may
-be an expression whose value gives the name of the filehandle. The
-values for WHENCE are C<0> to set the new position to POSITION, C<1> to set
-the it to the current position plus POSITION, and C<2> to set it to EOF
-plus POSITION (typically negative). For WHENCE, you may use the
-constants C<SEEK_SET>, C<SEEK_CUR>, and C<SEEK_END> from either the C<IO::Seekable>
-or the POSIX module.
+C<print()>, C<write()>, C<seek()>, C<tell()>, or C<eof()> may cause
+confusion. FILEHANDLE may be an expression whose value gives the name
+of the filehandle. The values for WHENCE are C<0> to set the new
+position to POSITION, C<1> to set the it to the current position plus
+POSITION, and C<2> to set it to EOF plus POSITION (typically negative).
+For WHENCE, you may use the constants C<SEEK_SET>, C<SEEK_CUR>, and
+C<SEEK_END> from either the C<IO::Seekable> or the POSIX module.
Returns the new position, or the undefined value on failure. A position
of zero is returned as the string "C<0> but true"; thus C<sysseek()> returns
=item syswrite FILEHANDLE,SCALAR,LENGTH
+=item syswrite FILEHANDLE,SCALAR
+
Attempts to write LENGTH bytes of data from variable SCALAR to the
-specified FILEHANDLE, using the system call C<write(2)>. It bypasses
+specified FILEHANDLE, using the system call write(2). If LENGTH is
+not specified, writes whole SCALAR. It bypasses
stdio, so mixing this with reads (other than C<sysread())>, C<print()>,
-C<write()>, C<seek()>, or C<tell()> may cause confusion because stdio usually
-buffers data. Returns the number of bytes actually written, or C<undef>
-if there was an error. If the LENGTH is greater than the available
-data in the SCALAR after the OFFSET, only as much data as is available
-will be written.
+C<write()>, C<seek()>, C<tell()>, or C<eof()> may cause confusion
+because stdio usually buffers data. Returns the number of bytes
+actually written, or C<undef> if there was an error. If the LENGTH is
+greater than the available data in the SCALAR after the OFFSET, only as
+much data as is available will be written.
An OFFSET may be specified to write the data from some part of the
string other than the beginning. A negative OFFSET specifies writing
This function binds a variable to a package class that will provide the
implementation for the variable. VARIABLE is the name of the variable
to be enchanted. CLASSNAME is the name of a class implementing objects
-of correct type. Any additional arguments are passed to the "C<new>"
-method of the class (meaning C<TIESCALAR>, C<TIEARRAY>, or C<TIEHASH>).
-Typically these are arguments such as might be passed to the C<dbm_open()>
-function of C. The object returned by the "C<new>" method is also
-returned by the C<tie()> function, which would be useful if you want to
-access other methods in CLASSNAME.
+of correct type. Any additional arguments are passed to the "C<new()>"
+method of the class (meaning C<TIESCALAR>, C<TIEHANDLE>, C<TIEARRAY>,
+or C<TIEHASH>). Typically these are arguments such as might be passed
+to the C<dbm_open()> function of C. The object returned by the "C<new()>"
+method is also returned by the C<tie()> function, which would be useful
+if you want to access other methods in CLASSNAME.
Note that functions such as C<keys()> and C<values()> may return huge lists
when used on large objects, like DBM files. You may prefer to use the
A class implementing a hash should have the following methods:
TIEHASH classname, LIST
- DESTROY this
FETCH this, key
STORE this, key, value
DELETE this, key
+ CLEAR this
EXISTS this, key
FIRSTKEY this
NEXTKEY this, lastkey
+ DESTROY this
A class implementing an ordinary array should have the following methods:
TIEARRAY classname, LIST
- DESTROY this
FETCH this, key
STORE this, key, value
- [others TBD]
+ FETCHSIZE this
+ STORESIZE this, count
+ CLEAR this
+ PUSH this, LIST
+ POP this
+ SHIFT this
+ UNSHIFT this, LIST
+ SPLICE this, offset, length, LIST
+ EXTEND this, count
+ DESTROY this
+
+A class implementing a file handle should have the following methods:
+
+ TIEHANDLE classname, LIST
+ READ this, scalar, length, offset
+ READLINE this
+ GETC this
+ WRITE this, scalar, length, offset
+ PRINT this, LIST
+ PRINTF this, format, LIST
+ CLOSE this
+ DESTROY this
A class implementing a scalar should have the following methods:
TIESCALAR classname, LIST
- DESTROY this
FETCH this,
STORE this, value
+ DESTROY this
+
+Not all methods indicated above need be implemented. See L<perltie>,
+L<Tie::Hash>, L<Tie::Array>, L<Tie::Scalar> and L<Tie::Handle>.
Unlike C<dbmopen()>, the C<tie()> function will not use or require a module
for you--you need to do that explicitly yourself. See L<DB_File>
Returns an uppercased version of EXPR. This is the internal function
implementing the C<\U> escape in double-quoted strings.
Respects current LC_CTYPE locale if C<use locale> in force. See L<perllocale>.
+Under Unicode (C<use utf8>) it uses the standard Unicode uppercase mappings. (It
+does not attempt to do titlecase mapping on initial letters. See C<ucfirst()> for that.)
If EXPR is omitted, uses C<$_>.
=item ucfirst
-Returns the value of EXPR with the first character uppercased. This is
+Returns the value of EXPR with the first character
+in uppercase (titlecase in Unicode). This is
the internal function implementing the C<\u> escape in double-quoted strings.
Respects current LC_CTYPE locale if C<use locale> in force. See L<perllocale>.
=item umask
Sets the umask for the process to EXPR and returns the previous value.
-If EXPR is omitted, merely returns the current umask. If C<umask(2)> is
-not implemented on your system, returns C<undef>. Remember that a
-umask is a number, usually given in octal; it is I<not> a string of octal
-digits. See also L</oct>, if all you have is a string.
+If EXPR is omitted, merely returns the current umask.
+
+The Unix permission C<rwxr-x---> is represented as three sets of three
+bits, or three octal digits: C<0750> (the leading 0 indicates octal
+and isn't one of the the digits). The C<umask> value is such a number
+representing disabled permissions bits. The permission (or "mode")
+values you pass C<mkdir> or C<sysopen> are modified by your umask, so
+even if you tell C<sysopen> to create a file with permissions C<0777>,
+if your umask is C<0022> then the file will actually be created with
+permissions C<0755>. If your C<umask> were C<0027> (group can't
+write; others can't read, write, or execute), then passing
+C<sysopen()> C<0666> would create a file with mode C<0640> (C<0666 &~
+027> is C<0640>).
+
+Here's some advice: supply a creation mode of C<0666> for regular
+files (in C<sysopen()>) and one of C<0777> for directories (in
+C<mkdir()>) and executable files. This gives users the freedom of
+choice: if they want protected files, they might choose process umasks
+of C<022>, C<027>, or even the particularly antisocial mask of C<077>.
+Programs should rarely if ever make policy decisions better left to
+the user. The exception to this is when writing files that should be
+kept private: mail files, web browser cookies, I<.rhosts> files, and
+so on.
+
+If umask(2) is not implemented on your system and you are trying to
+restrict access for I<yourself> (i.e., (EXPR & 0700) > 0), produces a
+fatal error at run time. If umask(2) is not implemented and you are
+not trying to restrict access for yourself, returns C<undef>.
+
+Remember that a umask is a number, usually given in octal; it is I<not> a
+string of octal digits. See also L</oct>, if all you have is a string.
=item undef EXPR
parameter. Examples:
undef $foo;
- undef $bar{'blurfl'}; # Compare to: delete $bar{'blurfl'};
+ undef $bar{'blurfl'}; # Compare to: delete $bar{'blurfl'};
undef @ary;
undef %hash;
undef &mysub;
Note that this is a unary operator, not a list operator.
+=item unless (EXPR) BLOCK
+
+The negative counterpart of L</if>. If the EXPR returns false the
+BLOCK is entered.
+
+See also L<perlsyn>.
+
=item unlink LIST
=item unlink
unlink @goners;
unlink <*.bak>;
-Note: C<unlink> will not delete directories unless you are superuser and
+Note: C<unlink()> will not delete directories unless you are superuser and
the B<-U> flag is supplied to Perl. Even if these conditions are
met, be warned that unlinking a directory can inflict damage on your
-filesystem. Use C<rmdir> instead.
+filesystem. Use C<rmdir()> instead.
If LIST is omitted, uses C<$_>.
=item unpack TEMPLATE,EXPR
-C<Unpack> does the reverse of C<pack>: it takes a string representing a
+C<Unpack()> does the reverse of C<pack()>: it takes a string representing a
structure and expands it out into a list value, returning the array
value. (In scalar context, it returns merely the first value
-produced.) The TEMPLATE has the same format as in the C<pack> function.
+produced.) The TEMPLATE has the same format as in the C<pack()> function.
Here's a subroutine that does substring:
sub substr {
$setbits = unpack("%32b*", $selectmask);
-=item untie VARIABLE
-
-Breaks the binding between a variable and a package. (See C<tie()>.)
-
=item unshift ARRAY,LIST
-Does the opposite of a C<shift>. Or the opposite of a C<push>,
+Does the opposite of a C<shift()>. Or the opposite of a C<push()>,
depending on how you look at it. Prepends list to the front of the
array, and returns the new number of elements in the array.
unshift(ARGV, '-e') unless $ARGV[0] =~ /^-/;
Note the LIST is prepended whole, not one element at a time, so the
-prepended elements stay in the same order. Use C<reverse> to do the
+prepended elements stay in the same order. Use C<reverse()> to do the
reverse.
+=item until (EXPR) BLOCK
+
+=item do BLOCK until (EXPR)
+
+Enter BLOCK until EXPR returns false. The first form may avoid entering
+the BLOCK, the second form enters the BLOCK at least once.
+
+See L</do>, L</while>, and L</for>.
+
+See also L<perlsyn>.
+
+=item untie VARIABLE
+
+Breaks the binding between a variable and a package. (See C<tie()>.)
+
=item use Module LIST
=item use Module
incompatible ways from older versions of Perl. (We try not to do
this more than we have to.)
-The C<BEGIN> forces the C<require> and C<import> to happen at compile time. The
+The C<BEGIN> forces the C<require> and C<import()> to happen at compile time. The
C<require> makes sure the module is loaded into memory if it hasn't been
-yet. The C<import> is not a builtin--it's just an ordinary static method
+yet. The C<import()> is not a builtin--it's just an ordinary static method
call into the "C<Module>" package to tell the module to import the list of
features back into the current package. The module can implement its
-C<import> method any way it likes, though most modules just choose to
-derive their C<import> method via inheritance from the C<Exporter> class that
-is defined in the C<Exporter> module. See L<Exporter>. If no C<import>
+C<import()> method any way it likes, though most modules just choose to
+derive their C<import()> method via inheritance from the C<Exporter> class that
+is defined in the C<Exporter> module. See L<Exporter>. If no C<import()>
method can be found then the error is currently silently ignored. This
may change to a fatal error in a future version.
through the end of the file).
There's a corresponding "C<no>" command that unimports meanings imported
-by C<use>, i.e., it calls C<unimport Module LIST> instead of C<import>.
+by C<use>, i.e., it calls C<unimport Module LIST> instead of C<import()>.
no integer;
no strict 'refs';
-If no C<unimport> method can be found the call fails with a fatal error.
+If no C<unimport()> method can be found the call fails with a fatal error.
See L<perlmod> for a list of standard modules and pragmas.
Returns a list consisting of all the values of the named hash. (In a
scalar context, returns the number of values.) The values are
-returned in an apparently random order, but it is the same order as
-either the C<keys()> or C<each()> function would produce on the same hash.
+returned in an apparently random order. The actual random order is
+subject to change in future versions of perl, but it is guaranteed to
+be the same order as either the C<keys()> or C<each()> function would
+produce on the same (unmodified) hash.
+
As a side effect, it resets HASH's iterator. See also C<keys()>, C<each()>,
and C<sort()>.
vec($foo, 8, 8) = 0x50; # 'PerlPerlP'
vec($foo, 9, 8) = 0x65; # 'PerlPerlPe'
vec($foo, 20, 4) = 2; # 'PerlPerlPe' . "\x02"
- vec($foo, 21, 4) = 7; # 'PerlPerlPer' # 'r' is "\x72"
+ vec($foo, 21, 4) = 7; # 'PerlPerlPer'
+ # 'r' is "\x72"
vec($foo, 45, 2) = 3; # 'PerlPerlPer' . "\x0c"
vec($foo, 93, 1) = 1; # 'PerlPerlPer' . "\x2c"
- vec($foo, 94, 1) = 1; # 'PerlPerlPerl' # 'l' is "\x6c"
+ vec($foo, 94, 1) = 1; # 'PerlPerlPerl'
+ # 'l' is "\x6c"
To transform a bit vector into a string or array of 0's and 1's, use these:
Waits for a child process to terminate and returns the pid of the
deceased process, or C<-1> if there are no child processes. The status is
-returned in C<$?>.
+returned in C<$?>. Note that a return value of C<-1> could mean that
+child processes are being automatically reaped, as described in L<perlipc>.
=item waitpid PID,FLAGS
waitpid(-1,&WNOHANG);
then you can do a non-blocking wait for any process. Non-blocking wait
-is available on machines supporting either the C<waitpid(2)> or
-C<wait4(2)> system calls. However, waiting for a particular pid with
+is available on machines supporting either the waitpid(2) or
+wait4(2) system calls. However, waiting for a particular pid with
FLAGS of C<0> is implemented everywhere. (Perl emulates the system call
by remembering the status values of processes that have exited but have
not been harvested by the Perl script yet.)
-See L<perlipc> for other examples.
+Note that a return value of C<-1> could mean that child processes are being
+automatically reaped. See L<perlipc> for details, and for other examples.
=item wantarray
See L<perlvar> for details on setting C<%SIG> entries, and for more
examples.
+=item while (EXPR) BLOCK
+
+=item do BLOCK while (EXPR)
+
+Enter BLOCK while EXPR is true. The first form may avoid entering the
+BLOCK, the second form enters the BLOCK at least once.
+
+See also L<perlsyn>, L</for>, L</until>, and L</continue>.
+
=item write FILEHANDLE
=item write EXPR
If FILEHANDLE is unspecified, output goes to the current default output
channel, which starts out as STDOUT but may be changed by the
-C<select> operator. If the FILEHANDLE is an EXPR, then the expression
+C<select()> operator. If the FILEHANDLE is an EXPR, then the expression
is evaluated and the resulting string is used to look up the name of
the FILEHANDLE at run time. For more on formats, see L<perlform>.
-Note that write is I<NOT> the opposite of C<read>. Unfortunately.
+Note that write is I<NOT> the opposite of C<read()>. Unfortunately.
=item y///
https://perl5.git.perl.org / perl5.git / blobdiff