X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=80f1fe0cc821c3225994ecc6960bb55cb06e07d2;hb=f4dad39ef1a76c1f6bbf6733d7c2ee209381be78;hp=a89ee99e06ea0c9e0f9539032023ccd28a02fff0;hpb=22fae026e9f4859841088a1c5609be12b0b1d4f3;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index a89ee99..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 a filehandle, even though it looks like one). DBNAME is the name of the database (without the F<.dir> or F<.pag> extension if @@ -863,7 +863,9 @@ is just like except that it's more efficient, more concise, keeps track of the current filename for error messages, and searches all the B<-I> libraries if the file isn't in the current directory (see also the @INC -array in L). It's the same, however, in that it does +array in L). It is also different in how +code evaluated with C doesn't see lexicals in the enclosing +scope like C does. It's the same, however, in that it does reparse the file every time you call it, so you probably don't want to do this inside a loop. @@ -1074,11 +1076,22 @@ in case 6. =item exec LIST +=item exec PROGRAM LIST + The exec() function executes a system command I - use system() instead of exec() if you want it to return. It fails and returns FALSE only if the command does not exist I 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 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 @@ -1182,6 +1195,12 @@ that doesn't implement flock(2), fcntl(2) locking, or lockf(3). flock() is Perl's portable file locking interface, although it locks only entire files, not records. +On many platforms (including most versions or clones of Unix), locks +established by flock() are B. This means that files +locked with flock() may be modified by programs which do not also use +flock(). Windows NT and OS/2, however, are among the platforms which +supply mandatory locking. See your local documentation for details. + OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN, possibly combined with LOCK_NB. These constants are traditionally valued 1, 2, 8 and 4, but you can use the symbolic names if import them from the Fcntl module, @@ -1269,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 = @@ -1442,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* @@ -1463,6 +1482,22 @@ lookup by name, in which case you get the other thing, whatever it is. $name = getgrent etc. +In I 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 + 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 is a space separated list of the login names of the members of the group. @@ -1574,12 +1609,13 @@ 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'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, C or another C) actually modifies the element in the original list. See also L for an array composed of the results of the BLOCK or EXPR. + =item hex EXPR =item hex @@ -1785,8 +1821,8 @@ subroutine, C, or C. If more than one value is listed, the list must be placed in parentheses. See L 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 for details. =item localtime EXPR @@ -1810,10 +1846,18 @@ In a scalar context, returns the ctime(3) value: $now_string = localtime; # e.g., "Thu Oct 13 04:54:34 1994" -This scalar value is B locale dependent, see L, -but instead a Perl builtin. -Also see the Time::Local module, and the strftime(3) and mktime(3) -function available via the POSIX module. +This scalar value is B locale dependent, see L, but +instead a Perl builtin. Also see the 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) +and try for example + + use POSIX qw(strftime) + $now_string = strftime "%a %b %e %H:%M:%S %Y", localtime; + +Note that the C<%a> and C<%b>, the short forms of the day of the week +and the month of the year, may not necessarily be three characters wide. =item log EXPR @@ -2358,7 +2402,8 @@ you will have to use a block returning its value instead: =item printf FORMAT, LIST -Equivalent to C. The first argument +Equivalent to C, except that $\ +(the output record separator) is not appended. The first argument of the list will be interpreted as the printf format. If C is in effect, the character used for the decimal point in formatted real numbers is affected by the LC_NUMERIC locale. See L. @@ -2373,6 +2418,13 @@ Returns the prototype of a function as a string (or C if the function has no prototype). FUNCTION is a reference to, or the name of, the function whose prototype you want to retrieve. +If FUNCTION is a string starting with C, the rest is taken as +a name for Perl builtin. If builtin is not I (such as +C) or its arguments cannot be expressed by a prototype (such as +C) - in other words, the builtin does not behave like a Perl +function - returns C. Otherwise, the string describing the +equivalent prototype is returned. + =item push ARRAY,LIST Treats ARRAY as a stack, and pushes the values of LIST @@ -2482,7 +2534,7 @@ operator is discussed in more detail in L. Receives a message on a socket. Attempts to receive LENGTH bytes of data into variable SCALAR from the specified SOCKET filehandle. -Actually does a C recvfrom(), so that it can returns the address of the +Actually does a C recvfrom(), so that it can return the address of the sender. Returns the undefined value if there's an error. SCALAR will be grown or shrunk to the length actually read. Takes the same flags as the system call of the same name. @@ -2593,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 and -L. +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 and L. =item reset EXPR @@ -2938,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 below. +or else see L above. See also the POSIX module's sigpause() function. @@ -3086,10 +3156,12 @@ sanity checks in the interest of speed. =item splice ARRAY,OFFSET Removes the elements designated by OFFSET and LENGTH from an array, and -replaces them with the elements of LIST, if any. Returns the elements -removed from the array. The array grows or shrinks as necessary. If -LENGTH is omitted, removes everything from OFFSET onward. The -following equivalences hold (assuming C<$[ == 0>): +replaces them with the elements of LIST, if any. In a list context, +returns the elements removed from the array. In a scalar context, +returns the last element removed, or C if no elements are +removed. The array grows or shrinks as necessary. If LENGTH is +omitted, removes everything from OFFSET onward. The following +equivalences hold (assuming C<$[ == 0>): push(@a,$x,$y) splice(@a,$#a+1,0,$x,$y) pop(@a) splice(@a,-1) @@ -3130,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. @@ -3244,7 +3316,7 @@ and the conversion letter: + prefix positive number with a plus sign - left-justify within the field 0 use zeros, not spaces, to right-justify - # prefix octal with "0", hex with "0x" + # prefix non-zero octal with "0", non-zero hex with "0x" number minimum field width .number "precision": digits after decimal point for floating-point, max length for string, minimum length for integer @@ -3281,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