access setitimer(2) if your system supports it. The Time::HiRes module
from CPAN may also prove useful.
-It is usually a mistake to intermix C<alarm>
-and C<sleep> calls.
+It is usually a mistake to intermix C<alarm> and C<sleep> calls.
+(C<sleep> may be internally implemented in your system with C<alarm>)
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
second--glance appear to be an lvalue context may be fixed in a future
release.
+See L<perlref/"Pseudo-hashes"> for specifics on how exists() acts when
+used on a pseudo-hash.
+
=item exit EXPR
Evaluates EXPR and exits immediately with that value. Example:
themselves abort the exit. Likewise any object destructors that need to
be called are called before the real exit. If this is a problem, you
can call C<POSIX:_exit($status)> to avoid END and destructor processing.
-See L<perlsub> for details.
+See L<perlmod> for details.
=item exp EXPR
$rec = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell);
-See L</split>.
+Beware that unlike C<split>, C<join> doesn't take a pattern as its
+first argument. Compare L</split>.
=item keys HASH
Sends a signal to a list of processes. The first element of
the list must be the signal to send. Returns the number of
-processes successfully signaled.
+processes successfully signaled (which is not necessarily the
+same as the number actually killed).
$cnt = kill 1, $child1, $child2;
kill 9, @goners;
C<eval {}>, C<sub {}> or C<do {}>, and should not be used to exit
a grep() or map() operation.
+Note that a block by itself is semantically identical to a loop
+that executes once. Thus C<last> can be used to effect an early
+exit out of such a block.
+
See also L</continue> for an illustration of how C<last>, C<next>, and
C<redo> work.
$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
-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:
+instead a Perl builtin. Also see the C<Time::Local> module
+(to convert the second, minutes, hours, ... back to seconds since the
+stroke of midnight the 1st of January 1970, the value returned by
+time()), and the 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:
use POSIX qw(strftime);
$now_string = strftime "%a %b %e %H:%M:%S %Y", localtime;
=item my EXPR
+=item my EXPR : ATTRIBUTES
+
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
C<eval {}>, C<sub {}> or C<do {}>, and should not be used to exit
a grep() or map() operation.
+Note that a block by itself is semantically identical to a loop
+that executes once. Thus C<next> will exit such a block early.
+
See also L</continue> for an illustration of how C<last>, C<next>, and
C<redo> work.
automatically convert strings into numbers as needed, this automatic
conversion assumes base 10.)
+=item open FILEHANDLE,MODE,EXPR
+
=item open FILEHANDLE,EXPR
=item open FILEHANDLE
to open.) See L<perlopentut> for a kinder, gentler explanation of opening
files.
-If the filename begins with C<'E<lt>'> or nothing, the file is opened for input.
-If the filename begins with C<'E<gt>'>, the file is truncated and opened for
-output, being created if necessary. If the filename begins with C<'E<gt>E<gt>'>,
+If MODE is C<'E<lt>'> or nothing, the file is opened for input.
+If MODE is C<'E<gt>'>, the file is truncated and opened for
+output, being created if necessary. If MODE is C<'E<gt>E<gt>'>,
the file is opened for appending, again being created if necessary.
You can put a C<'+'> in front of the C<'E<gt>'> or C<'E<lt>'> to indicate that
you want both read and write access to the file; thus C<'+E<lt>'> is almost
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 fopen(3) modes of C<'r'>, C<'r+'>, C<'w'>,
C<'w+'>, C<'a'>, and C<'a+'>.
+In the 2-arguments (and 1-argument) form of the call the mode and
+filename should be concatenated (in this order), possibly separated by
+spaces. It is possible to omit the mode if the mode is C<'E<lt>'>.
+
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 as a command which pipes output to
that pipes both in I<and> out, but see L<IPC::Open2>, L<IPC::Open3>,
and L<perlipc/"Bidirectional Communication"> for alternatives.)
-Opening C<'-'> opens STDIN and opening C<'E<gt>-'> opens STDOUT. Open returns
+If MODE is C<'|-'>, the filename is interpreted as a
+command to which output is to be piped, and if MODE is
+C<'-|'>, the filename is interpreted as a command which pipes output to
+us. In the 2-arguments (and 1-argument) form one should replace dash
+(C<'-'>) with the command. 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.)
+
+In the 2-arguments (and 1-argument) form opening C<'-'> opens STDIN
+and opening C<'E<gt>-'> opens STDOUT.
+
+Open returns
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.
open ARTICLE or die "Can't find article $ARTICLE: $!\n";
while (<ARTICLE>) {...
- open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved)
+ open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved)
# if the open fails, output is discarded
- open(DBASE, '+<dbase.mine') # open for update
+ open(DBASE, '+<', 'dbase.mine') # open for update
+ or die "Can't open 'dbase.mine' for update: $!";
+
+ open(DBASE, '+<dbase.mine') # ditto
or die "Can't open 'dbase.mine' for update: $!";
- open(ARTICLE, "caesar <$article |") # decrypt article
+ open(ARTICLE, '-|', "caesar <$article") # decrypt article
+ or die "Can't start caesar: $!";
+
+ open(ARTICLE, "caesar <$article |") # ditto
or die "Can't start caesar: $!";
- open(EXTRACT, "|sort >/tmp/Tmp$$") # $$ is our process id
+ open(EXTRACT, "|sort >/tmp/Tmp$$") # $$ is our process id
or die "Can't start sort: $!";
# process argument list of files along with any includes
You may also, in the Bourne shell tradition, specify an EXPR beginning
with C<'E<gt>&'>, in which case the rest of the string is interpreted as the
name of a filehandle (or file descriptor, if numeric) to be
-duped and opened. You may use C<&> after C<E<gt>>, C<E<gt>E<gt>>, C<E<lt>>, C<+E<gt>>,
-C<+E<gt>E<gt>>, and C<+E<lt>>. The
+duped and opened. You may use C<&> after C<E<gt>>, C<E<gt>E<gt>>,
+C<E<lt>>, C<+E<gt>>, C<+E<gt>E<gt>>, and C<+E<lt>>. The
mode you specify should match the mode of the original filehandle.
(Duping a filehandle does not take into account any existing contents of
-stdio buffers.)
+stdio buffers.) Duping file handles is not yet supported for 3-argument
+open().
+
Here is a script that saves, redirects, and restores STDOUT and
STDERR:
open(OLDOUT, ">&STDOUT");
open(OLDERR, ">&STDERR");
- open(STDOUT, ">foo.out") || die "Can't redirect stdout";
- open(STDERR, ">&STDOUT") || die "Can't dup stdout";
+ open(STDOUT, '>', "foo.out") || die "Can't redirect stdout";
+ open(STDERR, ">&STDOUT") || die "Can't dup stdout";
select(STDERR); $| = 1; # make unbuffered
select(STDOUT); $| = 1; # make unbuffered
open(FILEHANDLE, "<&=$fd")
-If you open a pipe on the command C<'-'>, i.e., either C<'|-'> or C<'-|'>, then
+If you open a pipe on the command C<'-'>, i.e., either C<'|-'> or C<'-|'>
+with 2-arguments (or 1-argument) form of open(), then
there is an implicit fork done, and the return value of open is the pid
of the child within the parent process, and C<0> within the child
process. (Use C<defined($pid)> to determine whether the open was successful.)
piped open when you want to exercise more control over just how the
pipe command gets executed, such as when you are running setuid, and
don't want to have to scan shell commands for metacharacters.
-The following pairs are more or less equivalent:
+The following triples are more or less equivalent:
open(FOO, "|tr '[a-z]' '[A-Z]'");
- open(FOO, "|-") || exec 'tr', '[a-z]', '[A-Z]';
+ open(FOO, '|-', "tr '[a-z]' '[A-Z]'");
+ open(FOO, '|-') || exec 'tr', '[a-z]', '[A-Z]';
open(FOO, "cat -n '$file'|");
- open(FOO, "-|") || exec 'cat', '-n', $file;
+ open(FOO, '-|', "cat -n '$file'");
+ open(FOO, '-|') || exec 'cat', '-n', $file;
See L<perlipc/"Safe Pipe Opens"> for more examples of this.
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
+The filename passed to 2-argument (or 1-argument) form of open()
+will have leading and trailing
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
$filename =~ s/(.*\.gz)\s*$/gzip -dc < $1|/;
open(FH, $filename) or die "Can't open $filename: $!";
-However, to open a file with arbitrary weird characters in it, it's
-necessary to protect any leading and trailing whitespace:
+Use 3-argument form to open a file with arbitrary weird characters in it,
+
+ open(FOO, '<', $file);
+
+otherwise it's necessary to protect any leading and trailing whitespace:
$file =~ s#^(\s)#./$1#;
open(FOO, "< $file\0");
+(this may not work on some bizzare filesystems). One should
+conscientiously choose between the the I<magic> and 3-arguments form
+of open():
+
+ open IN, $ARGV[0];
+
+will allow the user to specify an argument of the form C<"rsh cat file |">,
+but will not work on a filename which happens to have a trailing space, while
+
+ open IN, '<', $ARGV[0];
+
+will have exactly the opposite restrictions.
+
If you want a "real" C C<open> (see L<open(2)> on your system), then you
-should use the C<sysopen> function, which involves no such magic. This is
+should use the C<sysopen> function, which involves no such magic (but
+may use subtly different filemodes than Perl open(), which is mapped
+to C fopen()). This is
another way to protect your filenames from interpretation. For example:
use IO::Handle;
EXPR is omitted, uses C<$_>. For the reverse, see L</chr>.
See L<utf8> for more about Unicode.
+=item our EXPR
+
+An C<our> declares the listed variables to be valid globals within
+the enclosing block, file, or C<eval>. That is, it has the same
+scoping rules as a "my" declaration, but does not create a local
+variable. If more than one value is listed, the list must be placed
+in parentheses. The C<our> declaration has no semantic effect unless
+"use strict vars" is in effect, in which case it lets you use the
+declared global variable without qualifying it with a package name.
+(But only within the lexical scope of the C<our> declaration. In this
+it differs from "use vars", which is package scoped.)
+
=item pack TEMPLATE,LIST
Takes a list of values and packs it into a binary structure,
s A signed short value.
S An unsigned short value.
(This 'short' is _exactly_ 16 bits, which may differ from
- what a local C compiler calls 'short'.)
+ what a local C compiler calls 'short'. If you want
+ native-length shorts, use the '!' suffix.)
i A signed integer value.
I An unsigned integer value.
l A signed long value.
L An unsigned long value.
(This 'long' is _exactly_ 32 bits, which may differ from
- what a local C compiler calls 'long'.)
+ what a local C compiler calls 'long'. If you want
+ native-length longs, use the '!' suffix.)
n A short in "network" (big-endian) order.
N A long in "network" (big-endian) order.
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.
+ (Quads are 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.
=item *
-The C<"h"> and C<"H"> fields pack a string that many nybbles long.
+The C<"h"> and C<"H"> fields pack a string that many nybbles (4-bit groups,
+representable as hexadecimal digits, 0-9a-f) long.
=item *
=item *
+The C<"/"> character allows packing and unpacking of strings where the
+packed structure contains a byte count followed by the string itself.
+You write I<length-item>C</>I<string-item>.
+
+The I<length-item> can be any C<pack> template letter,
+and describes how the length value is packed.
+The ones likely to be of most use are integer-packing ones like
+C<"n"> (for Java strings), C<"w"> (for ASN.1 or SNMP)
+and C<"N"> (for Sun XDR).
+
+The I<string-item> must, at present, be C<"A*">, C<"a*"> or C<"Z*">.
+For C<unpack> the length of the string is obtained from the I<length-item>,
+but if you put in the '*' it will be ignored.
+
+ unpack 'C/a', "\04Gurusamy"; gives 'Guru'
+ unpack 'a3/A* A*', '007 Bond J '; gives (' Bond','J')
+ pack 'n/a* w/a*','hello,','world'; gives "\000\006hello,\005world"
+
+The I<length-item> is not returned explicitly from C<unpack>.
+
+Adding a count to the I<length-item> letter
+is unlikely to do anything useful,
+unless that letter is C<"A">, C<"a"> or C<"Z">.
+Packing with a I<length-item> of C<"a"> or C<"Z">
+may introduce C<"\000"> characters,
+which Perl does not regard as legal in numeric strings.
+
+=item *
+
The integer types C<"s">, C<"S">, C<"l">, and C<"L"> may be
-immediately followed by a C<"!"> to signify native shorts or longs--as
-you can see from above for example a bare C<"l"> does mean exactly 32
-bits, the native C<long> (as seen by the local C compiler) may be
-larger. This is an issue mainly in 64-bit platforms. You can see
-whether using C<"!"> makes any difference by
+immediately followed by a C<"!"> suffix to signify native shorts or
+longs--as you can see from above for example a bare C<"l"> does mean
+exactly 32 bits, the native C<long> (as seen by the local C compiler)
+may be larger. This is an issue mainly in 64-bit platforms. You can
+see whether using C<"!"> makes any difference by
print length(pack("s")), " ", length(pack("s!")), "\n";
print length(pack("l")), " ", length(pack("l!")), "\n";
C<"i!"> and C<"I!"> also work but only because of completeness;
they are identical to C<"i"> and C<"I">.
-The actual sizes (in bytes) of native shorts, ints, and longs on
-the platform where Perl was built are also available via L<Config>:
-
The actual sizes (in bytes) of native shorts, ints, longs, and long
longs on the platform where Perl was built are also available via
L<Config>:
print $Config{longsize}, "\n";
print $Config{longlongsize}, "\n";
+(The C<$Config{longlongsize}> will be undefine if your system does
+not support long longs.)
+
=item *
The integer formats C<"s">, C<"S">, C<"i">, C<"I">, C<"l">, and C<"L">
are inherently non-portable between processors and operating systems
because they obey the native byteorder and endianness. For example a
-4-byte integer 0x87654321 (2271560481 decimal) be ordered natively
+4-byte integer 0x12345678 (305419896 decimal) be ordered natively
(arranged in and handled by the CPU registers) into bytes as
0x12 0x34 0x56 0x78 # little-endian
Plea for Peace" by Danny Cohen, USC/ISI IEN 137, April 1, 1980) and
the egg-eating habits of the Lilliputians.
-Some systems may even have weird byte orders such as
+Some systems may have even weirder byte orders such as
0x56 0x78 0x12 0x34
0x34 0x12 0x78 0x56
If you want portable packed integers use the formats C<"n">, C<"N">,
C<"v">, and C<"V">, their byte endianness and size is known.
+See also L<perlport>.
=item *
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).
+of the IEEE spec). See also L<perlport>.
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 $foo).
+=item *
+
+You must yourself do any alignment or padding by inserting for example
+enough C<'x'>es while packing. There is no way to pack() and unpack()
+could know where the bytes are going to or coming from. Therefore
+C<pack> (and C<unpack>) handle their output and input as flat
+sequences of bytes.
+
+=item *
+
+A comment in a TEMPLATE starts with C<#> and goes to the end of line.
+
=back
Examples:
$foo = pack("ccxxcc",65,66,67,68);
# foo eq "AB\0\0CD"
+ # note: the above examples featuring "C" and "c" are true
+ # only on ASCII and ASCII-derived systems such as ISO Latin 1
+ # and UTF-8. In EBCDIC the first example would be
+ # $foo = pack("CCCC",193,194,195,196);
+
$foo = pack("s2",1,2);
# "\1\0\2\0" on little-endian
# "\0\1\0\2" on big-endian
unpack("N", pack("B32", substr("0" x 32 . shift, -32)));
}
+ $foo = pack('sx2l', 12, 34);
+ # short 12, two zero bytes padding, long 34
+ $bar = pack('s@4l', 12, 34);
+ # short 12, zero fill to position 4, long 34
+ # $foo eq $bar
+
The same template may generally also be used in unpack().
=item package
C<eval {}>, C<sub {}> or C<do {}>, and should not be used to exit
a grep() or map() operation.
+Note that a block by itself is semantically identical to a loop
+that executes once. Thus C<redo> inside such a block will effectively
+turn it into a looping construct.
+
See also L</continue> for an illustration of how C<last>, C<next>, and
C<redo> work.
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
-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 C<1> upon success, C<0> otherwise.
+POSITION, C<1> to set 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>
+(start of the file, current position, end of the file) from any of the
+modules Fcntl, C<IO::Seekable>, or POSIX. Returns C<1> upon success,
+C<0> otherwise.
If you want to position file for C<sysread> or C<syswrite>, don't use
C<seek>--buffering makes its effect on the file's system position
busy multitasking system.
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.
+C<syscall> interface to access setitimer(2) if your system supports
+it, or else see L</select> above. The Time::HiRes module from CPAN
+may also help.
See also the POSIX module's C<sigpause> function.
for integer
l interpret integer as C type "long" or "unsigned long"
h interpret integer as C type "short" or "unsigned short"
+ If no flags, interpret integer as C type "int" or "unsigned"
There is also one Perl-specific flag:
point in formatted real numbers is affected by the LC_NUMERIC locale.
See L<perllocale>.
+To cope with broken systems that allow the standard locales to be
+overridden by malicious users, the return value may be tainted
+if any of the floating point formats are used and the conversion
+yields something that doesn't look like a normal C-locale floating
+point number. This happens regardless of whether C<use locale> is
+in effect or not.
+
+If Perl understands "quads" (64-bit integers) (this requires
+either that the platform natively supports quads or that Perl
+has been specifically compiled to support quads), the characters
+
+ d u o x X b i D U O
+
+print quads, and they may optionally be preceded by
+
+ ll L q
+
+For example
+
+ %lld %16LX %qo
+
+You can find out whether your Perl supports quads via L<Config>:
+
+ use Config;
+ ($Config{use64bits} eq 'define' || $Config{longsize} == 8) &&
+ print "quads\n";
+
+If Perl understands "long doubles" (this requires that the platform
+supports long doubles), the flags
+
+ e f g E F G
+
+may optionally be preceded by
+
+ ll L
+
+For example
+
+ %llf %Lg
+
+You can find out whether your Perl supports long doubles via L<Config>:
+
+ use Config;
+ $Config{d_longdbl} eq 'define' && print "long doubles\n";
+
=item sqrt EXPR
=item sqrt
=item sub NAME BLOCK
This is subroutine definition, not a real function I<per se>. With just a
-NAME (and possibly prototypes), it's just a forward declaration. Without
-a NAME, it's an anonymous function declaration, and does actually return a
-value: the CODE ref of the closure you just created. See L<perlsub> and
-L<perlref> for details.
+NAME (and possibly prototypes or attributes), it's just a forward declaration.
+Without a NAME, it's an anonymous function declaration, and does actually
+return a value: the CODE ref of the closure you just created. See L<perlsub>
+and L<perlref> for details.
-=item substr EXPR,OFFSET,LEN,REPLACEMENT
+=item substr EXPR,OFFSET,LENGTH,REPLACEMENT
-=item substr EXPR,OFFSET,LEN
+=item substr EXPR,OFFSET,LENGTH
=item substr EXPR,OFFSET
Extracts a substring out of EXPR and returns it. First character is at
offset C<0>, or whatever you've set C<$[> to (but don't do that).
If OFFSET is negative (or more precisely, less than C<$[>), starts
-that far from the end of the string. If LEN is omitted, returns
-everything to the end of the string. If LEN is negative, leaves that
+that far from the end of the string. If LENGTH is omitted, returns
+everything to the end of the string. If LENGTH is negative, leaves that
many characters off the end of the string.
-If you specify a substring that is partly outside the string, the part
-within the string is returned. If the substring is totally outside
-the string a warning is produced.
-
You can use the substr() function as an lvalue, in which case EXPR
-must itself be an lvalue. If you assign something shorter than LEN,
-the string will shrink, and if you assign something longer than LEN,
+must itself be an lvalue. If you assign something shorter than LENGTH,
+the string will shrink, and if you assign something longer than LENGTH,
the string will grow to accommodate it. To keep the string the same
length you may need to pad or chop your value using C<sprintf>.
+If OFFSET and LENGTH specify a substring that is partly outside the
+string, only the part within the string is returned. If the substring
+is beyond either end of the string, substr() returns the undefined
+value and produces a warning. When used as an lvalue, specifying a
+substring that is entirely outside the string is a fatal error.
+Here's an example showing the behavior for boundary cases:
+
+ my $name = 'fred';
+ substr($name, 4) = 'dy'; # $name is now 'freddy'
+ my $null = substr $name, 6, 2; # returns '' (no warning)
+ my $oops = substr $name, 7; # returns undef, with warning
+ substr($name, 7) = 'gap'; # fatal error
+
An alternative to using substr() as an lvalue is to specify the
replacement string as the 4th argument. This allows you to replace
parts of the EXPR and return what was there before in one operation,
The possible values and flag bits of the MODE parameter are
system-dependent; they are available via the standard module C<Fcntl>.
+See the documentation of your operating system's C<open> to see which
+values and flag bits are available. You may combine several flags
+using the C<|>-operator.
+
+Some of the most common values are C<O_RDONLY> for opening the file in
+read-only mode, C<O_WRONLY> for opening the file in write-only mode,
+and C<O_RDWR> for opening the file in read-write mode, and.
+
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.
+se them in new code, use thhe constants discussed in the preceding
+paragraph.
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
These permission values need to be in octal, and are modified by your
process's current C<umask>.
+In many systems the C<O_EXCL> flag is available for opening files in
+exclusive mode. This is B<not> locking: exclusiveness means here that
+if the file already exists, sysopen() fails. The C<O_EXCL> wins
+C<O_TRUNC>.
+
+Sometimes you may want to truncate an already-existing file: C<O_TRUNC>.
+
You should 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
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>, 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.
+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 also use the constants C<SEEK_SET>, C<SEEK_CUR>, and
+C<SEEK_END> (start of the file, current position, end of the file)
+from any of the modules Fcntl, C<IO::Seekable>, or POSIX.
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
returned by the C<wait> call. To get the actual exit value divide by
256. See also L</exec>. This is I<not> what you want to use to capture
the output from a command, for that you should use merely backticks or
-C<qx//>, as described in L<perlop/"`STRING`">.
+C<qx//>, as described in L<perlop/"`STRING`">. Return value of -1
+indicates a failure to start the program (inspect $! for the reason).
Like C<exec>, C<system> allows you to lie to a program about its name if
you use the C<system PROGRAM LIST> syntax. Again, see L</exec>.
and 00:00:00 UTC, January 1, 1970 for most other systems).
Suitable for feeding to C<gmtime> and C<localtime>.
+For measuring time in better granularity than one second,
+you may use either the Time::HiRes module from CPAN, or
+if you have gettimeofday(2), you may be able to use the
+C<syscall> interface of Perl, see L<perlfaq8> for details.
+
=item times
Returns a four-element list giving the user and system times, in
corresponds to a valid memory location, passing a pointer value that's
not known to be valid is likely to have disastrous consequences.
-See L</pack> for more examples.
+See L</pack> for more examples and notes.
=item untie VARIABLE
use integer;
use diagnostics;
- use sigtrap qw(SEGV BUS);
- use strict qw(subs vars refs);
- use subs qw(afunc blurfl);
+ use sigtrap qw(SEGV BUS);
+ use strict qw(subs vars refs);
+ use subs qw(afunc blurfl);
+ use warnings qw(all);
Some of these pseudo-modules import semantics into the current
block scope (like C<strict> or C<integer>, unlike ordinary modules,
no integer;
no strict 'refs';
+ no warnings;
If no C<unimport> method can be found the call fails with a fatal error.
Changes the access and modification times on each file of a list of
files. The first two elements of the list must be the NUMERICAL access
and modification times, in that order. Returns the number of files
-successfully changed. The inode modification time of each file is set
+successfully changed. The inode change time of each file is set
to the current time. This code has the same effect as the C<touch>
command if the files already exist:
=item vec EXPR,OFFSET,BITS
Treats the string in EXPR as a vector of unsigned integers, and
-returns the value of the bit field specified by OFFSET. BITS specifies
-the number of bits that are reserved for each entry in the bit
-vector. This must be a power of two from 1 to 32. C<vec> may also be
-assigned to, in which case parentheses are needed to give the expression
-the correct precedence as in
+returns the value of the bit field specified by OFFSET. BITS
+specifies the number of bits that are reserved for each entry in the
+bit vector. This must be a power of two from 1 to 32 (or 64, if your
+platform supports that).
+
+C<vec> may also be assigned to, in which case parentheses are needed
+to give the expression the correct precedence as in
vec($image, $max_x * $x + $y, 8) = 3;
Vectors created with C<vec> can also be manipulated with the logical
-operators C<|>, C<&>, and C<^>, which will assume a bit vector operation is
-desired when both operands are strings. See L<perlop/"Bitwise String Operators">.
+operators C<|>, C<&>, and C<^>, which will assume a bit vector
+operation is desired when both operands are strings.
+See L<perlop/"Bitwise String Operators">.
The following code will build up an ASCII string saying C<'PerlPerlPerl'>.
The comments show the string after each step. Note that this code works
projects / p5sagit/p5-mst-13.2.git / blobdiff