dbmclose, dbmopen
-
=back
=head2 Alphabetical Listing of Perl Functions
-
=over 8
=item -X FILEHANDLE
and sleep() calls.
If you want to use alarm() to time out a system call you need to use an
-eval/die pair. You can't rely on the alarm causing the system call to
+eval/die pair. You can't rely on the alarm causing the system call to
fail with $! set to EINTR because Perl sets up signal handlers to
restart system calls on some systems. Using eval/die always works.
$hasargs, $wantarray, $evaltext, $is_require) = caller($i);
Here $subroutine may be C<"(eval)"> if the frame is not a subroutine
-call, but C<L<eval>>. In such a case additional elements $evaltext and
+call, but C<L<eval>>. In such a case additional elements $evaltext and
$is_require are set: $is_require is true if the frame is created by
C<L<require>> or C<L<use>> statement, $evaltext contains the text of
-C<L<eval EXPR>> statement. In particular, for C<L<eval BLOCK>>
+C<L<eval EXPR>> statement. In particular, for C<L<eval BLOCK>>
statement $filename is C<"(eval)">, but $evaltext is undefined. (Note
also that C<L<use>> statement creates a C<L<require>> frame inside
an C<L<eval EXPR>>) frame.
Changes the permissions of a list of files. The first element of the
list must be the numerical mode, which should probably be an octal
-number. Returns the number of files successfully changed.
+number, and which definitely should I<not> a string of octal digits:
+C<0644> is okay, C<'0644'> is not. Returns the number of files
+successfully changed. See also L<oct>, if all you have is a string.
$cnt = chmod 0755, 'foo', 'bar';
chmod 0755, @executables;
+ $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
=item chomp VARIABLE
=item chr
Returns the character represented by that NUMBER in the character set.
-For example, C<chr(65)> is "A" in ASCII.
+For example, C<chr(65)> is "A" in ASCII. For the reverse, use L<ord>.
If NUMBER is omitted, uses $_.
the password file for lousy passwords, amongst other things. Only the
guys wearing white hats should do this.
+Note that crypt is intended to be a one-way function, much like breaking
+eggs to make an omelette. There is no (known) corresponding decrypt
+function. As a result, this function isn't all that useful for
+cryptography. (For that, see your nearby CPAN mirror.)
+
Here's an example that makes sure that whoever runs this program knows
their own password:
Of course, typing in your own password to whomever asks you
for it is unwise.
-=item dbmclose ASSOC_ARRAY
+=item dbmclose HASH
[This function has been superseded by the untie() function.]
-Breaks the binding between a DBM file and an associative array.
+Breaks the binding between a DBM file and a hash.
-=item dbmopen ASSOC,DBNAME,MODE
+=item dbmopen HASH,DBNAME,MODE
[This function has been superseded by the tie() function.]
-This binds a dbm(3), ndbm(3), sdbm(3), gdbm(), or Berkeley DB file to an
-associative array. ASSOC is the name of the associative array. (Unlike
-normal open, the first argument is I<NOT> a filehandle, even though it
-looks like one). DBNAME is the name of the database (without the F<.dir>
-or F<.pag> extension if any). If the database does not exist, it is
-created with protection specified by MODE (as modified by the umask()).
-If your system supports only the older DBM functions, you may perform only
-one dbmopen() in your program. In older versions of Perl, if your system
-had neither DBM nor ndbm, calling dbmopen() produced a fatal error; it now
-falls back to sdbm(3).
-
-If you don't have write access to the DBM file, you can only read
-associative array variables, not set them. If you want to test whether
-you can write, either use file tests or try setting a dummy array entry
-inside an eval(), which will trap the error.
+This binds a dbm(3), ndbm(3), sdbm(3), gdbm(), or Berkeley DB file to a
+hash. HASH is the name of the hash. (Unlike normal open, the first
+argument is I<NOT> a filehandle, even though it looks like one). DBNAME
+is the name of the database (without the F<.dir> or F<.pag> extension if
+any). If the database does not exist, it is created with protection
+specified by MODE (as modified by the umask()). If your system supports
+only the older DBM functions, you may perform only one dbmopen() in your
+program. In older versions of Perl, if your system had neither DBM nor
+ndbm, calling dbmopen() produced a fatal error; it now falls back to
+sdbm(3).
+
+If you don't have write access to the DBM file, you can only read hash
+variables, not set them. If you want to test whether you can write,
+either use file tests or try setting a dummy hash entry inside an eval(),
+which will trap the error.
Note that functions such as keys() and values() may return huge array
values when used on large DBM files. You may prefer to use the each()
=item defined
-Returns a boolean value saying whether EXPR has a real value
-or not. If EXPR is not present, $_ will be checked. Many operations
-return the undefined value under exceptional conditions, such as end of
-file, uninitialized variable, system error and such. This function
-allows you to distinguish between an undefined
-null scalar and a defined null scalar with operations that might return
-a real null string, such as referencing elements of an array. You may
-also check to see if arrays or subroutines exist. Use of defined on
-predefined variables is not guaranteed to produce intuitive results.
-
-When used on a hash array element, it tells you whether the value
-is defined, not whether the key exists in the hash. Use exists() for that.
+Returns a Boolean value telling whether EXPR has a value other than
+the undefined value C<undef>. If EXPR is not present, C<$_> will be
+checked.
+
+Many operations return C<undef> to indicate failure, end of file,
+system error, uninitialized variable, and other exceptional
+conditions. This function allows you to distinguish C<undef> from
+other values. (A simple Boolean test will not distinguish among
+C<undef>, zero, the empty string, and "0", which are all equally
+false.) Note that since C<undef> is a valid scalar, its presence
+doesn't I<necessarily> indicate an exceptional condition: pop()
+returns C<undef> when its argument is an empty array, I<or> when the
+element to return happens to be C<undef>.
+
+You may also use defined() to check whether a subroutine exists. On
+the other hand, use of defined() upon aggregates (hashes and arrays)
+is not guaranteed to produce intuitive results, and should probably be
+avoided.
+
+When used on a hash element, it tells you whether the value is defined,
+not whether the key exists in the hash. Use L<exists> for the latter
+purpose.
Examples:
print "$val\n" while defined($val = pop(@ary));
die "Can't readlink $sym: $!"
unless defined($value = readlink $sym);
- eval '@foo = ()' if defined(@foo);
- die "No XYZ package defined" unless defined %_XYZ;
sub foo { defined &$bar ? &$bar(@_) : die "No bar"; }
+ $debugging = 0 unless defined $debugging;
-See also undef().
-
-Note: many folks tend to overuse defined(), and then are surprised to
-discover that the number 0 and the null string are, in fact, defined
-concepts. For example, if you say
+Note: Many folks tend to overuse defined(), and then are surprised to
+discover that the number 0 and "" (the zero-length string) are, in fact,
+defined values. For example, if you say
"ab" =~ /a(.*)b/;
matched "nothing". But it didn't really match nothing--rather, it
matched something that happened to be 0 characters long. This is all
very above-board and honest. When a function returns an undefined value,
-it's an admission that it couldn't give you an honest answer. So
-you should use defined() only when you're questioning the integrity
-of what you're trying to do. At other times, a simple comparison to
-0 or "" is what you want.
-
-Another surprise is that using defined() on an entire array or
-hash reports whether memory for that aggregate has ever been
-allocated. So an array you set to the empty list appears undefined
-initially, and one that once was full and that you then set to
-the empty list still appears defined. You should instead use a
-simple test for size:
+it's an admission that it couldn't give you an honest answer. So you
+should use defined() only when you're questioning the integrity of what
+you're trying to do. At other times, a simple comparison to 0 or "" is
+what you want.
+
+Currently, using defined() on an entire array or hash reports whether
+memory for that aggregate has ever been allocated. So an array you set
+to the empty list appears undefined initially, and one that once was full
+and that you then set to the empty list still appears defined. You
+should instead use a simple test for size:
if (@an_array) { print "has array elements\n" }
if (%a_hash) { print "has hash members\n" }
This counter-intuitive behaviour of defined() on aggregates may be
changed, fixed, or broken in a future release of Perl.
+See also L<undef>, L<exists>, L<ref>.
+
=item delete EXPR
-Deletes the specified key(s) and their associated values from a hash
-array. For each key, returns the deleted value associated with that key,
-or the undefined value if there was no such key. Deleting from C<$ENV{}>
-modifies the environment. Deleting from an array tied to a DBM file
+Deletes the specified key(s) and their associated values from a hash.
+For each key, returns the deleted value associated with that key, or
+the undefined value if there was no such key. Deleting from C<$ENV{}>
+modifies the environment. Deleting from a hash tied to a DBM file
deletes the entry from the DBM file. (But deleting from a tie()d hash
doesn't necessarily return anything.)
-The following deletes all the values of an associative array:
+The following deletes all the values of a hash:
foreach $key (keys %HASH) {
delete $HASH{$key};
QUICKSTART:
Getopt('f');
-=item each ASSOC_ARRAY
+=item each HASH
+
+When called in a list context, returns a 2-element array consisting of the
+key and value for the next element of a hash, so that you can iterate over
+it. When called in a scalar context, returns the key for only the next
+element in the hash. (Note: Keys may be "0" or "", which are logically
+false; you may wish to avoid constructs like C<while ($k = each %foo) {}>
+for this reason.)
-When called in a list context, returns a 2-element array consisting
-of the key and value for the next element of an associative array,
-so that you can iterate over it. When called in a scalar context,
-returns the key for only the next element in the associative array.
-Entries are returned in an apparently random order. When the array is
+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 (0) value), and C<undef> is returned in a
-scalar context. The next call to each() after that will start
-iterating again. The iterator can be reset only by reading all the
-elements from the array. You should not add elements to an array while
-you're iterating over it. There is a single iterator for each
-associative array, shared by all each(), keys(), and values() function
-calls in the program. The following prints out your environment like
-the printenv(1) program, only in a different order:
+scalar context. The next call to each() after that will start iterating
+again. There is a single iterator for each hash, shared by all each(),
+keys(), and values() function calls in the program; it can be reset by
+reading all the elements from the hash, or by evaluating C<keys HASH> or
+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 printenv(1) program,
+only in a different order:
while (($key,$value) = each %ENV) {
print "$key=$value\n";
as terminals may lose the end-of-file condition if you do.
An C<eof> without an argument uses the last file read as argument.
-Empty parentheses () may be used to indicate
-the pseudo file formed of the files listed on the command line, i.e.,
-C<eof()> is reasonable to use inside a while (E<lt>E<gt>) loop to detect the end
-of only the last file. Use C<eof(ARGV)> or eof without the parentheses to
-test I<EACH> file in a while (E<lt>E<gt>) loop. Examples:
+Empty parentheses () may be used to indicate the pseudo file formed of
+the files listed on the command line, i.e., C<eof()> is reasonable to
+use inside a C<while (E<lt>E<gt>)> loop to detect the end of only the
+last file. Use C<eof(ARGV)> or eof without the parentheses to test
+I<EACH> file in a while (E<lt>E<gt>) loop. Examples:
# reset line numbering on each input file
while (<>) {
eval "\$$x++" # CASE 5
$$x++; # CASE 6
-Cases 1 and 2 above behave identically: they run the code contained in the
-variable $x. (Although case 2 has misleading double quotes making the
-reader wonder what else might be happening (nothing is).) Cases 3 and 4
-likewise behave in the same way: they run the code E<lt>$xE<gt>, which does
-nothing at all. (Case 4 is preferred for purely visual reasons.) Case 5
-is a place where normally you I<WOULD> like to use double quotes, except
-that in that particular situation, you can just use symbolic references
-instead, as in case 6.
+Cases 1 and 2 above behave identically: they run the code contained in
+the variable $x. (Although case 2 has misleading double quotes making
+the reader wonder what else might be happening (nothing is).) Cases 3
+and 4 likewise behave in the same way: they run the code '$x', which
+does nothing but return the value of C<$x>. (Case 4 is preferred for
+purely visual reasons, but it also has the advantage of compiling at
+compile-time instead of at run-time.) Case 5 is a place where
+normally you I<WOULD> like to use double quotes, except that in that
+particular situation, you can just use symbolic references instead, as
+in case 6.
=item exec LIST
$ans = <STDIN>;
exit 0 if $ans =~ /^[Xx]/;
-See also die(). If EXPR is omitted, exits with 0 status.
+See also die(). If EXPR is omitted, exits with 0 status. The only
+univerally portable values for EXPR are 0 for success and 1 for error;
+all other values are subject to unpredictable interpretation depending
+on the environment in which the Perl program is running.
You shouldn't use exit() to abort a subroutine if there's any chance that
someone might want to trap whatever error happened. Use die() instead,
}
print "\n";
-Determination of whether to whether $BSD_STYLE should be set
+Determination of whether $BSD_STYLE should be set
is left as an exercise to the reader.
The POSIX::getattr() function can do this more portably on systems
Returns the current login from F</etc/utmp>, if any. If null, use
getpwuid().
- $login = getlogin || (getpwuid($<))[0] || "Kilroy";
+ $login = getlogin || getpwuid($<) || "Kilroy";
Do not consider getlogin() for authentication: it is not as
secure as getpwuid().
=item glob EXPR
+=item glob
+
Returns the value of EXPR with filename expansions such as a shell
-would do. This is the internal function implementing the E<lt>*.*E<gt>
-operator, except it's easier to use.
+would do. This is the internal function implementing the <*.c>
+operator, except it's easier to use. If EXPR is omitted, $_ is used.
=item gmtime EXPR
All array elements are numeric, and come straight out of a struct tm.
In particular this means that $mon has the range 0..11 and $wday has
-the range 0..6. If EXPR is omitted, does C<gmtime(time())>.
+the range 0..6. Also, $year is the number of years since 1900, I<not>
+simply the last two digits of the year.
+
+If EXPR is omitted, does C<gmtime(time())>.
+
+In a scalar context, prints out the ctime(3) value:
+
+ $now_string = gmtime; # e.g., "Thu Oct 13 04:54:34 1994"
+
+Also see the F<timegm.pl> library, and the strftime(3) function available
+via the POSIX module.
=item goto LABEL
The goto-LABEL form finds the statement labeled with LABEL and resumes
execution there. It may not be used to go into any construct that
requires initialization, such as a subroutine or a foreach loop. It
-also can't be used to go into a construct that is optimized away. It
-can be used to go almost anywhere else within the dynamic scope,
+also can't be used to go into a construct that is optimized away,
+or to get out of a block or subroutine given to 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 last or die. The author of Perl has never felt the
need to use this form of goto (in Perl, that is--C is another matter).
=item grep EXPR,LIST
+This is similar in spirit to, but not the same as, L<grep(1)>
+and its relatives. In particular, it is not limited to using
+regular expressions.
+
Evaluates the BLOCK or EXPR for each element of LIST (locally setting
$_ to each element) and returns the list value consisting of those
elements for which the expression evaluated to TRUE. In a scalar
Note that, because $_ is a reference into the list value, it can be used
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.
+array. Similarly, grep returns aliases into the original list,
+much like the way that L<Foreach Loops>'s index variable aliases the list
+elements. That is, modifying an element of a list returned by grep
+actually modifies the element in the original list.
=item hex EXPR
=item hex
-Interprets EXPR as a hex string and returns the corresponding decimal
-value. (To convert strings that might start with 0 or 0x see
-oct().) If EXPR is omitted, uses $_.
+Interprets EXPR as a hex string and returns the corresponding
+value. (To convert strings that might start with either 0 or 0x
+see L<oct>.) If EXPR is omitted, uses $_.
+
+ print hex '0xAf'; # prints '175'
+ print hex 'aF'; # same
=item import
See L<perlfunc/split>.
-=item keys ASSOC_ARRAY
+=item keys HASH
+
+Returns a normal array 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
+values() or each() function produces (given that the hash has not been
+modified). As a side effect, it resets HASH's iterator.
-Returns a normal array consisting of all the keys of the named
-associative array. (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 values() or each() function produces (given that
-the associative array has not been modified). Here is yet another way
-to print your environment:
+Here is yet another way to print your environment:
@keys = keys %ENV;
@values = values %ENV;
print $key, '=', $ENV{$key}, "\n";
}
-To sort an array by value, you'll need to use a C<sort{}>
-function. Here's a descending numeric sort of a hash by its values:
+To sort an array 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
-allocated for the given associative array. 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
+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;
All array elements are numeric, and come straight out of a struct tm.
In particular this means that $mon has the range 0..11 and $wday has
-the range 0..6. If EXPR is omitted, does localtime(time).
+the range 0..6 and $year is year-1900, that is, $year is 123 in year
+2023. If EXPR is omitted, uses the current time ("localtime(time)").
-In a scalar context, prints out the ctime(3) value:
+In a scalar context, returns the ctime(3) value:
$now_string = localtime; # e.g., "Thu Oct 13 04:54:34 1994"
-Also see the F<timelocal.pl> library, and the strftime(3) function available
+Also see the Time::Local module, and the strftime(3) function available
via the POSIX module.
=item log EXPR
=item oct
Interprets EXPR as an octal string and returns the corresponding
-decimal value. (If EXPR happens to start off with 0x, interprets it as
+value. (If EXPR happens to start off with 0x, interprets it as
a hex string instead.) The following will handle decimal, octal, and
hex in the standard Perl or C notation:
$val = oct($val) if $val =~ /^0/;
-If EXPR is omitted, uses $_.
+If EXPR is omitted, uses $_. This function is commonly used when
+a string such as "644" needs to be converted into a file mode, for
+example. (Although perl will automatically convert strings into
+numbers as needed, this automatic conversion assumes base 10.)
=item open FILEHANDLE,EXPR
=item ord
Returns the numeric ascii value of the first character of EXPR. If
-EXPR is omitted, uses $_.
+EXPR is omitted, uses $_. For the reverse, see L<chr>.
=item pack TEMPLATE,LIST
u A uuencoded string.
- w A BER compressed integer. Bytes give an unsigned integer base
+ w A BER compressed integer. Bytes give an unsigned integer base
128, most significant digit first, with as few digits as
possible, and with the bit 8 of each byte except the last set
to "1."
=item pos
Returns the offset of where the last C<m//g> search left off for the variable
-is in question ($_ is used when the variable is not specified). May be
+is in question ($_ is used when the variable is not specified). May be
modified to change that offset. Such modification will also influence
the C<\G> zero-width assertion in regular expressions. See L<perlre> and
L<perlop>.
Returns a random fractional number between 0 and the value of EXPR.
(EXPR should be positive.) If EXPR is omitted, returns a value between
-0 and 1. This function produces repeatable sequences unless srand()
-is invoked. See also srand().
+0 and 1. Automatically calls srand() unless srand() has already been
+called. See also srand().
-(Note: if your rand function consistently returns numbers that are too
+(Note: If your rand function consistently returns numbers that are too
large or too small, then your version of Perl was probably compiled
-with the wrong number of RANDBITS. As a workaround, you can usually
-multiply EXPR by the correct power of 2 to get the range you want.
-This will make your script unportable, however. It's better to recompile
-if you can.)
+with the wrong number of RANDBITS.)
=item read FILEHANDLE,SCALAR,LENGTH,OFFSET
=item ref
-Returns a TRUE value if EXPR is a reference, FALSE otherwise. If EXPR
-is not specified, $_ will be used. The value returned depends on the
+Returns a TRUE value if EXPR is a reference, FALSE otherwise. If EXPR
+is not specified, $_ will be used. The value returned depends on the
type of thing the reference is a reference to.
Builtin types include:
name is returned instead. You can think of ref() as a typeof() operator.
if (ref($r) eq "HASH") {
- print "r is a reference to an associative array.\n";
+ print "r is a reference to a hash.\n";
}
if (!ref ($r) {
print "r is not a reference at all.\n";
=item reverse LIST
In a list context, returns a list value consisting of the elements
-of LIST in the opposite order. In a scalar context, returns a string
-value consisting of the bytes of the first element of LIST in the
-opposite order.
+of LIST in the opposite order. In a scalar context, concatenates the
+elements of LIST, and returns a string value consisting of those bytes,
+but in the opposite order.
- print reverse <>; # line tac
+ print reverse <>; # line tac, last line first
- undef $/;
- print scalar reverse scalar <>; # byte tac
+ undef $/; # for efficiency of <>
+ print scalar reverse <>; # byte 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
+can be represented as a key in the inverted hash. Also, this has to
+unwind one hash and build a whole new one, which may take some time
+on a large hash.
+
+ %by_name = reverse %by_address; # Invert the hash
=item rewinddir DIRHANDLE
@ARGV array in the main program, and the @_ array in subroutines.
(This is determined lexically.) See also unshift(), push(), and pop().
Shift() and unshift() do the same thing to the left end of an array
-that push() and pop() do to the right end.
+that pop() and push() do to the right end.
=item shmctl ID,CMD,ARG
=item sort LIST
-Sorts the LIST and returns the sorted list value. Nonexistent values
-of arrays are stripped out. If SUBNAME or BLOCK is omitted, sorts
-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 0, depending on how the elements of the array are
-to be ordered. (The E<lt>=E<gt> and cmp operators are extremely useful in such
-routines.) SUBNAME may be a scalar variable name, in which case the
-value provides the name of the subroutine to use. In place of a
-SUBNAME, you can provide a BLOCK as an anonymous, in-line sort
-subroutine.
+Sorts the LIST and returns the sorted list value. If SUBNAME or BLOCK
+is omitted, sorts 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 0, depending on how the elements
+of the array are to be ordered. (The C<E<lt>=E<gt>> and C<cmp>
+operators are extremely useful in such routines.) SUBNAME may be a
+scalar variable name, in which case the value provides the name of the
+subroutine to use. In place of a SUBNAME, you can provide a BLOCK as
+an anonymous, in-line sort subroutine.
In the interests of efficiency the normal calling code for subroutines is
bypassed, with the following effects: the subroutine may not be a
$b (see example below). They are passed by reference, so don't
modify $a and $b. And don't try to declare them as lexicals either.
+You also cannot exit out of the sort block or subroutine using any of the
+loop control operators described in L<perlsyn> or with goto().
+
When C<use locale> is in effect, C<sort LIST> sorts LIST according to the
current collation locale. See L<perllocale>.
# sort using explicit subroutine name
sub byage {
- $age{$a} <=> $age{$b}; # presuming integers
+ $age{$a} <=> $age{$b}; # presuming numeric
}
@sortedclass = sort byage @class;
- # this sorts the %age associative arrays by value
- # instead of key using an in-line function
+ # this sorts the %age hash by value instead of key
+ # using an in-line function
@eldest = sort { $age{$b} <=> $age{$a} } keys %age;
sub backwards { $b cmp $a; }
=item srand EXPR
-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 ID, among
-other things. In versions of Perl prior to 5.004 the default seed was
-just the current time(). This isn't a particularly good seed, so many
-old programs supply their own seed value (often C<time ^ $$> or C<time ^
-($$ + ($$ << 15))>), but that isn't necessary any more.
+=item srand
-You need something much more random than the default seed for
-cryptographic purposes, though. Checksumming the compressed output of
-one or more rapidly changing operating system status programs is the
-usual method. For example:
+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
+ID, among other things. In versions of Perl prior to 5.004 the default
+seed was just the current time(). This isn't a particularly good seed,
+so many old programs supply their own seed value (often C<time ^ $$> or
+C<time ^ ($$ + ($$ << 15))>), but that isn't necessary any more.
+
+In fact, it's usually not necessary to call 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
+before 5.004, so if your script will run under older Perl versions, it
+should call srand().
+
+Note that you need something much more random than the default seed for
+cryptographic purposes. Checksumming the compressed output of one or more
+rapidly changing operating system status programs is the usual method. For
+example:
srand (time ^ $$ ^ unpack "%L*", `ps axww | gzip`);
a^b == (a+1)^(b+1)
one-third of the time. So don't do that.
-
+
=item stat FILEHANDLE
=item stat EXPR
=item stat
Returns a 13-element array giving the status info for a file, either the
-file opened via FILEHANDLE, or named by EXPR. If EXPR is omitted, it
+file opened via FILEHANDLE, or named by EXPR. If EXPR is omitted, it
stats $_. Returns a null list if the stat fails. Typically used as
follows:
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
+value: the CODE ref of the closure you just created. See L<perlsub> and
L<perlref> for details.
=item substr EXPR,OFFSET,LEN
=item substr EXPR,OFFSET
Extracts a substring out of EXPR and returns it. First character is at
-offset 0, or whatever you've set $[ to. If OFFSET is negative, starts
+offset 0, or whatever you've set C<$[> to (but don't do that).
+If OFFSET is negative, 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
many characters off the end of the string.
print "signal $rc\n"
}
$ok = ($rc != 0);
-
+
=item syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
=item syswrite FILEHANDLE,SCALAR,LENGTH
}
untie(%HIST);
-A class implementing an associative array should have the following
-methods:
+A class implementing a hash should have the following methods:
TIEHASH classname, LIST
DESTROY this
=item umask
-Sets the umask for the process and returns the old one. If EXPR is
-omitted, returns merely the current umask.
+Sets the umask for the process to EXPR and returns the previous value.
+If EXPR is omitted, merely returns the current umask. 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
=item undef
Undefines the value of EXPR, which must be an lvalue. Use on only a
-scalar value, an entire array, or a subroutine name (using "&"). (Using undef()
-will probably not do what you expect on most predefined variables or
-DBM list values, so don't do that.) Always returns the undefined value. You can omit
-the EXPR, in which case nothing is undefined, but you still get an
-undefined value that you could, for instance, return from a
-subroutine. Examples:
+scalar value, an entire array or hash, or a subroutine name (using
+"&"). (Using undef() will probably not do what you expect on most
+predefined variables or DBM list values, so don't do that.) Always
+returns the undefined value. You can omit the EXPR, in which case
+nothing is undefined, but you still get an undefined value that you
+could, for instance, return from a subroutine, assign to a variable or
+pass as a parameter. Examples:
undef $foo;
- undef $bar{'blurfl'};
+ undef $bar{'blurfl'}; # Compare to: delete $bar{'blurfl'};
undef @ary;
- undef %assoc;
+ undef %hash;
undef &mysub;
return (wantarray ? () : undef) if $they_blew_it;
+ select undef, undef, undef, 0.25;
+ ($a, $b, undef, $c) = &foo; # Ignore third value returned
=item unlink LIST
features back into the current package. The module can implement its
import method any way it likes, though most modules just choose to
derive their import method via inheritance from the Exporter class that
-is defined in the Exporter module. See L<Exporter>. If no import
-method can be found then the error is currently silently ignored. This
+is defined in the Exporter module. See L<Exporter>. If no import
+method can be found then the error is currently silently ignored. This
may change to a fatal error in a future version.
If you don't want your namespace altered, explicitly supply an empty list:
$now = time;
utime $now, $now, @ARGV;
-=item values ASSOC_ARRAY
+=item values HASH
-Returns a normal array consisting of all the values of the named
-associative array. (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 keys() or each() function would produce
-on the same array. See also keys(), each(), and sort().
+Returns a normal array 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 keys() or each() function would produce on the same hash. As a side
+effect, it resets HASH's iterator. See also keys(), each(), and sort().
=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. vec() may also be
+vector. This must be a power of two from 1 to 32. vec() may also be
assigned to, in which case parentheses are needed to give the expression
the correct precedence as in
projects / p5sagit/p5-mst-13.2.git / blobdiff