X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=92dbc2a135ad25d191859205a4a7dd5a167c427d;hb=20408e3ccf502b6ce4033d8203710405ec9ef8f6;hp=f509f6155366ea92d6042c604c755b1341306e95;hpb=2c268ad5f2bec64cb74406f2e1af30ddc0dc3b9f;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index f509f61..92dbc2a 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -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,6 +1076,8 @@ 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 @@ -1182,6 +1186,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, @@ -1811,10 +1821,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 @@ -2359,7 +2377,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. @@ -2490,7 +2509,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. @@ -3094,10 +3113,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) @@ -3252,7 +3273,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 @@ -3478,13 +3499,17 @@ unimplemented, produces a fatal error. The arguments are interpreted as follows: if a given argument is numeric, the argument is passed as an int. If not, the pointer to the string value is passed. You are responsible to make sure a string is pre-extended long enough to -receive any result that might be written into a string. If your +receive any result that might be written into a string. You can't use a +string literal (or other read-only string) as an argument to syscall() +because Perl has to assume that any string pointer might be written +through. If your integer arguments are not literals and have never been interpreted in a numeric context, you may need to add 0 to them to force them to look like numbers. require 'syscall.ph'; # may need to run h2ph - syscall(&SYS_write, fileno(STDOUT), "hi there\n", 9); + $s = "hi there\n"; + syscall(&SYS_write, fileno(STDOUT), $s, length $s); Note that Perl supports passing of up to only 14 arguments to your system call, which in practice should usually suffice. @@ -3562,6 +3587,8 @@ the new position. =item system LIST +=item system PROGRAM LIST + Does exactly the same thing as "exec LIST" except that a fork is done first, and the parent process waits for the child process to complete. Note that argument processing varies depending on the number of @@ -3571,6 +3598,9 @@ returned by the wait() call. To get the actual exit value divide by the output from a command, for that you should use merely backticks or qx//, as described in L. +Like exec(), system() allows you to lie to a program about its name if +you use the "system PROGRAM LIST" syntax. Again, see L. + Because system() and backticks block SIGINT and SIGQUIT, killing the program they're running doesn't actually interrupt your program. @@ -3728,7 +3758,8 @@ The transliteration operator. Same as y///. See L. Truncates the file opened on FILEHANDLE, or named by EXPR, to the specified length. Produces a fatal error if truncate isn't implemented -on your system. +on your system. Returns TRUE if successful, the undefined value +otherwise. =item uc EXPR @@ -3764,19 +3795,21 @@ digits. See also L, if all you have is a string. =item undef Undefines the value of EXPR, which must be an lvalue. Use only on a -scalar value, an entire array, an entire 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: +scalar value, an array (using "@"), a hash (using "%"), a subroutine +(using "&"), or a typeglob (using "*"). (Saying C +will probably not do what you expect on most predefined variables or +DBM list values, so don't do that; see L.) 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'}; # Compare to: delete $bar{'blurfl'}; undef @ary; undef %hash; undef &mysub; + undef *xyz; # destroys $xyz, @xyz, %xyz, &xyz, etc. return (wantarray ? (undef, $errmsg) : undef) if $they_blew_it; select undef, undef, undef, 0.25; ($a, $b, undef, $c) = &foo; # Ignore third value returned @@ -3925,7 +3958,8 @@ 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 -to the current time. Example of a "touch" command: +to the current time. This code has the same effect as the "touch" +command if the files already exist: #!/usr/bin/perl $now = time; @@ -4000,6 +4034,13 @@ for no value (void context). Produces a message on STDERR just like die(), but doesn't exit or throw an exception. +If LIST is empty and $@ already contains a value (typically from a +previous eval) that value is used after appending "\t...caught" +to $@. This is useful for staying almost, but not entirely similar to +die(). + +If $@ is empty then the string "Warning: Something's wrong" is used. + No message is printed if there is a C<$SIG{__WARN__}> handler installed. It is the handler's responsibility to deal with the message as it sees fit (like, for instance, converting it into a die()). Most