X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=80f1fe0cc821c3225994ecc6960bb55cb06e07d2;hb=f4dad39ef1a76c1f6bbf6733d7c2ee209381be78;hp=92dbc2a135ad25d191859205a4a7dd5a167c427d;hpb=20408e3ccf502b6ce4033d8203710405ec9ef8f6;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 92dbc2a..80f1fe0 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -657,7 +657,7 @@ Breaks the binding between a DBM file and a hash.
 
 [This function has been superseded by the tie() function.]
 
-This binds a dbm(3), ndbm(3), sdbm(3), gdbm(), or Berkeley DB file to a
+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 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
@@ -1083,6 +1083,15 @@ use system() instead of exec() if you want it to return. It fails and
 returns FALSE only if the command does not exist I<and> it is executed
 directly instead of via your system's command shell (see below).
 
+Since it's a common mistake to use system() instead of exec(), Perl
+warns you if there is a following statement which isn't die(), warn()
+or exit() (if C<-w> is set  -  but you always do that).   If you
+I<really> want to follow an exec() with some other statement, you
+can use one of these styles to avoid the warning:
+
+    exec ('foo') or print STDERR "couldn't exec foo";
+    { 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 execvp(3) with the arguments in LIST.  If
 there is only one scalar argument, the argument is checked for shell
@@ -1279,7 +1288,7 @@ you're done.  You should reopen those to /dev/null if it's any issue.
 
 =item format
 
-Declare a picture format with use by the write() function.  For
+Declare a picture format for use by the write() function.  For
 example:
 
     format Something =
@@ -1452,7 +1461,7 @@ system library.  Within a list context, the return values from the
 various get routines are as follows:
 
     ($name,$passwd,$uid,$gid,
-       $quota,$comment,$gcos,$dir,$shell) = getpw*
+       $quota,$comment,$gcos,$dir,$shell,$expire) = getpw*
     ($name,$passwd,$gid,$members) = getgr*
     ($name,$aliases,$addrtype,$length,@addrs) = gethost*
     ($name,$aliases,$addrtype,$net) = getnet*
@@ -1473,6 +1482,22 @@ lookup by name, in which case you get the other thing, whatever it is.
     $name = getgrent
     etc.
 
+In I<getpw*()> the fields $quota, $comment, and $expire are special
+cases in the sense that in many systems they are unsupported.  If the
+$quota is unsupported, it is an empty scalar.  If it is supported, it
+usually encodes the disk quota.  If the $comment field is unsupported,
+it is an empty scalar.  If it is supported it usually encodes some
+administrative comment about the user.  In some systems the $quota
+field may be $change or $age, fields that have to do with password
+aging.  In some systems the $comment field may be $class.  The $expire
+field, if present, encodes the expiration period of the account or the
+password.  For the availability and the exact meaning of these fields
+in your system, please consult your getpwnam(3) documentation and your
+<pwd.h> file.  You can also find out from within Perl which meaning
+your $quota and $comment fields have and whether you have the $expire
+field by using the Config module and the values d_pwquota, d_pwage,
+d_pwchange, d_pwcomment, and d_pwexpire.
+
 The $members value returned by I<getgr*()> is a space separated list of
 the login names of the members of the group.
 
@@ -1584,7 +1609,7 @@ 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.  Similarly, grep returns aliases into the original list,
-much like the way that L<Foreach Loops>'s index variable aliases the list
+much like the way that a for loops'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>)
 actually modifies the element in the original list.
@@ -1796,8 +1821,8 @@ subroutine, C<eval{}>, or C<do>.  If more than one value is listed, the
 list must be placed in parentheses.  See L<perlsub/"Temporary Values via
 local()"> for details, including issues with tied arrays and hashes.
 
-But you really probably want to be using my() instead, because local() isn't
-what most people think of as "local").  See L<perlsub/"Private Variables
+You really probably want to be using my() instead, because local() isn't
+what most people think of as "local".  See L<perlsub/"Private Variables
 via my()"> for details.
 
 =item localtime EXPR
@@ -2620,8 +2645,26 @@ replaces "F<::>" with "F</>" in the filename for you,
 to make it easy to load standard modules.  This form of loading of
 modules does not risk altering your namespace.
 
-For a yet-more-powerful import facility, see L</use> and
-L<perlmod>.
+In other words, if you try this:
+
+        require Foo::Bar ; # a splendid bareword 
+
+The require function will actually look for the "Foo/Bar.pm" file in the 
+directories specified in the @INC array.
+
+But if you try this :
+
+        $class = 'Foo::Bar';
+        require $class ; # $class is not a bareword
+or
+        require "Foo::Bar" ; # not a bareword because of the ""
+
+The require function will look for the "Foo::Bar" file in the @INC array and 
+will complain about not finding "Foo::Bar" there. In this case you can do :
+
+        eval "require $class";
+
+For a yet-more-powerful import facility, see L</use> and L<perlmod>.
 
 =item reset EXPR
 
@@ -2965,7 +3008,7 @@ always sleep the full amount.
 
 For delays of finer granularity than one second, you may use Perl's
 syscall() interface to access setitimer(2) if your system supports it,
-or else see L</select()> below.
+or else see L</select()> above.
 
 See also the POSIX module's sigpause() function.
 
@@ -3159,9 +3202,9 @@ splits on whitespace (after skipping any leading whitespace).  Anything
 matching PATTERN is taken to be a delimiter separating the fields.  (Note
 that the delimiter may be longer than one character.)
 
-If LIMIT is specified and is not negative, splits into no more than
-that many fields (though it may split into fewer).  If LIMIT is
-unspecified, trailing null fields are stripped (which potential users
+If LIMIT is specified and is positive, splits into no more than that
+many fields (though it may split into fewer).  If LIMIT is unspecified
+or zero, trailing null fields are stripped (which potential users
 of pop() would do well to remember).  If LIMIT is negative, it is
 treated as if an arbitrarily large LIMIT had been specified.
 
@@ -3310,7 +3353,7 @@ 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.
+C<time ^ ($$ + ($$ E<lt>E<lt> 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
@@ -3460,6 +3503,8 @@ 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,LEN
 
 =item substr EXPR,OFFSET
@@ -3482,6 +3527,12 @@ something longer than LEN, the string will grow to accommodate it.  To
 keep the string the same length you may need to pad or chop your value
 using sprintf().
 
+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.
+In this case LEN can be C<undef> if you want to affect everything to
+the end of the string.
+
 =item symlink OLDFILE,NEWFILE
 
 Creates a new filename symbolically linked to the old filename.
@@ -3518,7 +3569,7 @@ Syscall returns whatever value returned by the system call it calls.
 If the system call fails, syscall returns -1 and sets C<$!> (errno).
 Note that some system calls can legitimately return -1.  The proper
 way to handle such calls is to assign C<$!=0;> before the call and
-check the value of <$!> if syscall returns -1.
+check the value of C<$!> if syscall returns -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
@@ -3612,15 +3663,20 @@ Here's a more elaborate example of analysing the return value from
 system() on a Unix system to check for all possibilities, including for
 signals and core dumps.
 
-    $rc = 0xffff & system @args;
+    $! = 0;
+    $rc = system @args;
     printf "system(%s) returned %#04x: ", "@args", $rc;
     if ($rc == 0) {
 	print "ran with normal exit\n";
     }
     elsif ($rc == 0xff00) {
-	print "command failed: $!\n";
+	# Note that $! can be an empty string if the command that
+	# system() tried to execute was not found, not executable, etc.
+	# These errors occur in the child process after system() has
+	# forked, so the errno value is not visible in the parent.
+	printf "command failed: %s\n", ($! || "Unknown system() error");
     }
-    elsif ($rc > 0x80) {
+    elsif (($rc & 0xff) == 0) {
 	$rc >>= 8;
 	print "ran with non-zero exit status $rc\n";
     }
@@ -3786,7 +3842,8 @@ If EXPR is omitted, uses $_.
 =item 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
+If EXPR is omitted, merely returns the current umask.  If 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.