argument, while a list operator may provide either scalar and list
contexts for its arguments. If it does both, the scalar arguments will
be first, and the list argument will follow. (Note that there can ever
-be only one list argument.) For instance, splice() has three scalar
+be only one such list argument.) For instance, splice() has three scalar
arguments followed by a list.
In the syntax descriptions that follow, list operators that expect a
=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
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 -x and -X may
+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
might be inherited by a derived class. See L<perltoot> and L<perlobj>
for more about the blessing (and blessings) of objects.
+Consider always blessing objects in CLASSNAMEs that are mixed case.
+Namespaces with all lowercase names are considered reserved for Perl
+pragmata. Builtin types have all uppercase names, so to prevent confusion,
+it is best to avoid such package names as well.
+
+See L<perlmod/"Perl Modules">.
+
=item caller EXPR
=item caller
=item dump LABEL
+=item dump
+
This causes an immediate core dump. Primarily this is so that you can
use the B<undump> program to turn your core dump into an executable binary
after having initialized all your variables at the beginning of the
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
print "$key=$value\n";
}
-See also C<keys()> and C<values()>.
+See also C<keys()>, C<values()> and C<sort()>.
=item eof FILEHANDLE
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<perlmod/CPAN>.
+details on CPAN can be found on L<perlmodlib/CPAN>.
=item getlogin
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:
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,
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
=item oct
Interprets EXPR as an octal string and returns the corresponding
-value. (If EXPR happens to start off with C<0x>, interprets it as
-a hex string instead.) The following will handle decimal, octal, and
+value. (If EXPR happens to start off with C<0x>, interprets it as a
+hex string. If EXPR starts off with C<0b>, it is interpreted as a
+binary string.) The following will handle decimal, binary, octal, and
hex in the standard Perl or C notation:
$val = oct($val) if $val =~ /^0/;
If the filename begins with C<'|'>, the filename is interpreted as a
command to which output is to be piped, and if the filename ends with a
-C<'|'>, the filename is interpreted See L<perlipc/"Using open() for IPC">
+C<'|'>, the filename is interpreted as a command which pipes output to
+us. See L<perlipc/"Using open() for IPC">
for more examples of this. (You are not allowed to C<open()> to a command
that pipes both in I<and> out, but see L<IPC::Open2>, L<IPC::Open3>,
and L<perlipc/"Bidirectional Communication"> for alternatives.)
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<$?>.
$first; # Or here.
}
-See L</seek()> for some details about mixing reading and writing.
+See L</seek> for some details about mixing reading and writing.
=item opendir DIRHANDLE,EXPR
sequence of characters that give the order and type of values, as
follows:
+ a A string with arbitrary binary data, will be null padded.
A An ascii string, will be space padded.
- a An ascii string, will be null padded.
+ Z A null terminated (asciz) string, will be null padded.
+
b A bit string (ascending bit order, like vec()).
B A bit string (descending bit order).
h A hex string (low nybble first).
(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.
X Back up a byte.
@ Null fill to absolute position.
+The following rules apply:
+
+=over 8
+
+=item *
+
Each letter may optionally be followed by a number giving a repeat
-count. With all types except C<"a">, C<"A">, C<"b">, C<"B">, C<"h">, C<"H">, and C<"P"> the
-pack function will gobble up that many values from the LIST. A C<*> for the
-repeat count means to use however many items are left. The C<"a"> and C<"A">
-types gobble just one value, but pack it as a string of length count,
-padding with nulls or spaces as necessary. (When unpacking, C<"A"> strips
-trailing spaces and nulls, but C<"a"> does not.) Likewise, the C<"b"> and C<"B">
-fields pack a string that many bits long. The C<"h"> and C<"H"> fields pack a
-string that many nybbles long. The C<"p"> type packs a pointer to a null-
-terminated string. You are responsible for ensuring the string is not a
-temporary value (which can potentially get deallocated before you get
-around to using the packed result). The C<"P"> packs a pointer to a structure
-of the size indicated by the length. A NULL pointer is created if the
-corresponding value for C<"p"> or C<"P"> is C<undef>.
-Real numbers (floats and doubles) are
-in the native machine format only; due to the multiplicity of floating
-formats around, and the lack of a standard "network" representation, no
-facility for interchange has been made. This means that packed floating
-point data written on one machine may not be readable on another - even if
-both use IEEE floating point arithmetic (as the endian-ness of the memory
-representation is not part of the IEEE spec). Note that Perl uses doubles
-internally for all numeric calculation, and converting from double into
-float and thence back to double again will lose precision (i.e.,
-C<unpack("f", pack("f", $foo)>) will not in general equal C<$foo>).
+count. With all types except C<"a">, C<"A">, C<"Z">, C<"b">, C<"B">, C<"h">,
+C<"H">, and C<"P"> the pack function will gobble up that many values from
+the LIST. A C<*> for the repeat count means to use however many items are
+left.
+
+=item *
+
+The C<"a">, C<"A"> and C<"Z"> types gobble just one value, but pack it as a
+string of length count, padding with nulls or spaces as necessary. When
+unpacking, C<"A"> strips trailing spaces and nulls, C<"Z"> strips everything
+after the first null, and C<"a"> returns data verbatim.
+
+=item *
+
+Likewise, the C<"b"> and C<"B"> fields pack a string that many bits long.
+
+=item *
+
+The C<"h"> and C<"H"> fields pack a string that many nybbles long.
+
+=item *
+
+The C<"p"> type packs a pointer to a null-terminated string. You are
+responsible for ensuring the string is not a temporary value (which can
+potentially get deallocated before you get around to using the packed result).
+The C<"P"> type packs a pointer to a structure of the size indicated by the
+length. A NULL pointer is created if the corresponding value for C<"p"> or
+C<"P"> is C<undef>.
+
+=item *
+
+Real numbers (floats and doubles) are in the native machine format only;
+due to the multiplicity of floating formats around, and the lack of a
+standard "network" representation, no facility for interchange has been
+made. This means that packed floating point data written on one machine
+may not be readable on another - even if both use IEEE floating point
+arithmetic (as the endian-ness of the memory representation is not part
+of the IEEE spec).
+
+Note that Perl uses doubles internally for all numeric calculation, and
+converting from double into float and thence back to double again will
+lose precision (i.e., C<unpack("f", pack("f", $foo)>) will not in general
+equal C<$foo>).
+
+=back
Examples:
$foo = pack("i9pl", gmtime);
# a real struct tm (on my system anyway)
+ $utmp_template = "Z8 Z8 Z16 L";
+ $utmp = pack($utmp_template, @utmp1);
+ # a struct utmp (BSDish)
+
+ @utmp2 = unpack($utmp_template, $utmp);
+ # "@utmp1" eq "@utmp2"
+
sub bintodec {
unpack("N", pack("B32", substr("0" x 32 . shift, -32)));
}
-The same template may generally also be used in the unpack function.
+The same template may generally also be used in unpack().
=item package
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
=item qw/STRING/
-Generalized quotes. See L<perlop>.
+Generalized quotes. See L<perlop/"Regexp Quote-Like Operators">.
=item quotemeta EXPR
=item readline EXPR
-Reads from the filehandle whose typeglob is contained in EXPR. In scalar context, a single line
-is read and returned. In list context, reads until end-of-file is
-reached and returns a list of lines (however you've defined lines
-with C<$/> or C<$INPUT_RECORD_SEPARATOR>).
+Reads from the filehandle whose typeglob is contained in EXPR. In scalar
+context, each call reads and returns the next line, until end-of-file is
+reached, whereupon the subsequent call returns undef. In list context,
+reads until end-of-file is reached and returns a list of lines. Note that
+the notion of "line" used here is however you may have defined it
+with C<$/> or C<$INPUT_RECORD_SEPARATOR>). See L<perlvar/"$/">.
+
+When C<$/> is set to C<undef> and when readline() is in a scalar
+context (i.e. file slurp mode), it returns C<''> the first time,
+followed by C<undef> subsequently.
+
This is the internal function implementing the C<E<lt>EXPRE<gt>>
operator, but you can use it directly. The C<E<lt>EXPRE<gt>>
operator is discussed in more detail in L<perlop/"I/O Operators">.
the construction C<@{[ (some expression) ]}>, but usually a simple
C<(some expression)> suffices.
+Though C<scalar> can be considered in general to be a unary operator,
+EXPR is also allowed to be a parenthesized list. The list in fact
+behaves as a scalar comma expression, evaluating all but the last
+element in void context and returning the final element evaluated in
+a scalar context.
+
+The following single statement:
+
+ print uc(scalar(&foo,$bar)),$baz;
+
+is the moral equivalent of these two:
+
+ &foo;
+ print(uc($bar),$baz);
+
+See L<perlop> for more details on unary operators and the comma operator.
+
=item seek FILEHANDLE,POSITION,WHENCE
Sets FILEHANDLE's position, just like the C<fseek()> call of C<stdio()>.
For delays of finer granularity than one second, you may use Perl's
C<syscall()> interface to access setitimer(2) if your system supports it,
-or else see L</select()> above.
+or else see L</select> above.
See also the POSIX module's C<sigpause()> function.
%X like %x, but using upper-case letters
%E like %e, but using an upper-case "E"
%G like %g, but with an upper-case "E" (if applicable)
+ %b an unsigned integer, in binary
%p a pointer (outputs the Perl value's address in hexadecimal)
%n special: *stores* the number of characters output so far
into the next variable in the parameter list
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 Unix and on the Macintosh; you probably don't want to use them
-in new code.
+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
it (typically because MODE includes the C<O_CREAT> flag), then the value of
=item sysread FILEHANDLE,SCALAR,LENGTH
Attempts to read LENGTH bytes of data into variable SCALAR from the
-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()>, 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
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
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
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.
+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>
or the F<Config> module for interesting C<tie()> implementations.
-For further details see L<perltie>, L<tied VARIABLE>.
+For further details see L<perltie>, L<"tied VARIABLE">.
=item tied VARIABLE
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
+and isn't one of 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>,
computes the same number as the System V sum program:
while (<>) {
- $checksum += unpack("%16C*", $_);
+ $checksum += unpack("%32C*", $_);
}
- $checksum %= 65536;
+ $checksum %= 65535;
The following efficiently counts the number of set bits in a bit vector:
$setbits = unpack("%32b*", $selectmask);
+See L</pack> for more examples.
+
=item untie VARIABLE
Breaks the binding between a variable and a package. (See C<tie()>.)
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()>.
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
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
projects / p5sagit/p5-mst-13.2.git / blobdiff