X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=d38424904b6fdde664366f0657d6f32acea637a8;hb=e1f775196788199aa205bfd047e37a8e188e06b2;hp=c1bc4c5743a39a4fb56eba3fab69e486793872b5;hpb=820475bd7227fcbc2178bb45a4d501c4ccc2133b;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index c1bc4c5..d384249 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -376,6 +376,10 @@ Accepts an incoming socket connect, just as the accept(2) system call does. Returns the packed address if it succeeded, false otherwise. See the example in L. +On systems that support a close-on-exec flag on files, the flag will +be set for the newly opened file descriptor, as determined by the +value of $^F. See L. + =item alarm SECONDS =item alarm @@ -423,7 +427,7 @@ modulo the caveats given in L. Returns the arctangent of Y/X in the range -PI to PI. -For the tangent operation, you may use the C +For the tangent operation, you may use the C function, or use the familiar relation: sub tan { sin($_[0]) / cos($_[0]) } @@ -523,8 +527,8 @@ C statement. In particular, for a C statement, $filename is C<(eval)>, but $evaltext is undefined. (Note also that each C statement creates a C frame inside an C) frame. C<$hints> contains pragmatic hints that the caller was -compiled with. It currently only reflects the hint corresponding to -C. +compiled with. The C<$hints> value is subject to change between versions +of Perl, and is not meant for external use. Furthermore, when called from within the DB package, caller returns more detailed information: it sets the list variable C<@DB::args> to be the @@ -539,8 +543,10 @@ previous time C was called. =item chdir EXPR Changes the working directory to EXPR, if possible. If EXPR is omitted, -changes to the user's home directory. Returns true upon success, -false otherwise. See the example under C. +changes to the directory specified by C<$ENV{HOME}>, if set; if not, +changes to the directory specified by C<$ENV{LOGDIR}>. If neither is +set, C does nothing. It returns true upon success, false +otherwise. See the example under C. =item chmod LIST @@ -557,6 +563,14 @@ successfully changed. See also L, if all you have is a string. $mode = '0644'; chmod oct($mode), 'foo'; # this is better $mode = 0644; chmod $mode, 'foo'; # this is best +You can also import the symbolic C constants from the Fcntl +module: + + use Fcntl ':mode'; + + chmod S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH|S_IXOTH, @executables; + # This is identical to the chmod 0755 of the above example. + =item chomp VARIABLE =item chomp LIST @@ -764,7 +778,7 @@ to check the condition at the top of the loop. Returns the cosine of EXPR (expressed in radians). If EXPR is omitted, takes cosine of C<$_>. -For the inverse cosine operation, you may use the C +For the inverse cosine operation, you may use the C function, or use this relation: sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) } @@ -925,35 +939,58 @@ See also L, L, L. =item delete EXPR -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 Cd hash -doesn't necessarily return anything.) +Given an expression that specifies a hash element, array element, hash slice, +or array slice, deletes the specified element(s) from the hash or array. +In the case of an array, if the array elements happen to be at the end, +the size of the array will shrink to the highest element that tests +true for exists() (or 0 if no such element exists). -The following deletes all the values of a hash: +Returns each element so deleted or the undefined value if there was no such +element. Deleting from C<$ENV{}> modifies the environment. Deleting from +a hash tied to a DBM file deletes the entry from the DBM file. Deleting +from a Cd hash or array may not necessarily return anything. + +Deleting an array element effectively returns that position of the array +to its initial, uninitialized state. Subsequently testing for the same +element with exists() will return false. Note that deleting array +elements in the middle of an array will not shift the index of the ones +after them down--use splice() for that. See L. + +The following (inefficiently) deletes all the values of %HASH and @ARRAY: foreach $key (keys %HASH) { delete $HASH{$key}; } -And so does this: + foreach $index (0 .. $#ARRAY) { + delete $ARRAY[$index]; + } + +And so do these: - delete @HASH{keys %HASH} + delete @HASH{keys %HASH}; + + delete @ARRAY[0 .. $#ARRAY]; But both of these are slower than just assigning the empty list -or undefining it: +or undefining %HASH or @ARRAY: + + %HASH = (); # completely empty %HASH + undef %HASH; # forget %HASH ever existed - %hash = (); # completely empty %hash - undef %hash; # forget %hash every existed + @ARRAY = (); # completely empty @ARRAY + undef @ARRAY; # forget @ARRAY ever existed Note that the EXPR can be arbitrarily complicated as long as the final -operation is a hash element lookup or hash slice: +operation is a hash element, array element, hash slice, or array slice +lookup: delete $ref->[$x][$y]{$key}; delete @{$ref->[$x][$y]}{$key1, $key2, @morekeys}; + delete $ref->[$x][$y][$index]; + delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices]; + =item die LIST Outside an C, prints the value of LIST to C and @@ -1386,27 +1423,46 @@ any C methods in your objects. =item exists EXPR -Returns true if the specified hash key exists in its hash, even -if the corresponding value is undefined. +Given an expression that specifies a hash element or array element, +returns true if the specified element in the hash or array has ever +been initialized, even if the corresponding value is undefined. The +element is not autovivified if it doesn't exist. + + print "Exists\n" if exists $hash{$key}; + print "Defined\n" if defined $hash{$key}; + print "True\n" if $hash{$key}; - print "Exists\n" if exists $array{$key}; - print "Defined\n" if defined $array{$key}; - print "True\n" if $array{$key}; + print "Exists\n" if exists $array[$index]; + print "Defined\n" if defined $array[$index]; + print "True\n" if $array[$index]; -A hash element can be true only if it's defined, and defined if +A hash or array element can be true only if it's defined, and defined if it exists, but the reverse doesn't necessarily hold true. +Given an expression that specifies the name of a subroutine, +returns true if the specified subroutine has ever been declared, even +if it is undefined. Mentioning a subroutine name for exists or defined +does not count as declaring it. + + print "Exists\n" if exists &subroutine; + print "Defined\n" if defined &subroutine; + Note that the EXPR can be arbitrarily complicated as long as the final -operation is a hash key lookup: +operation is a hash or array key lookup or subroutine name: if (exists $ref->{A}->{B}->{$key}) { } if (exists $hash{A}{B}{$key}) { } -Although the last element will not spring into existence just because -its existence was tested, intervening ones will. Thus C<$ref-E{"A"}> -and C<$ref-E{"A"}-E{"B"}> will spring into existence due to the -existence test for a $key element. This happens anywhere the arrow -operator is used, including even + if (exists $ref->{A}->{B}->[$ix]) { } + if (exists $hash{A}{B}[$ix]) { } + + if (exists &{$ref->{A}{B}{$key}}) { } + +Although the deepest nested array or hash will not spring into existence +just because its existence was tested, any intervening ones will. +Thus C<$ref-E{"A"}> and C<$ref-E{"A"}-E{"B"}> will spring +into existence due to the existence test for the $key element above. +This happens anywhere the arrow operator is used, including even: undef $ref; if (exists $ref->{"Some key"}) { } @@ -1419,6 +1475,12 @@ release. See L for specifics on how exists() acts when used on a pseudo-hash. +Use of a subroutine call, rather than a subroutine name, as an argument +to exists() is an error. + + exists ⊂ # OK + exists &sub(); # Error + =item exit EXPR Evaluates EXPR and exits immediately with that value. Example: @@ -1512,11 +1574,11 @@ in the way of your getting your job done.) 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, +you can use the symbolic names if you import them from the Fcntl module, either individually, or as a group using the ':flock' tag. LOCK_SH requests a shared lock, LOCK_EX requests an exclusive lock, and LOCK_UN -releases a previously requested lock. If LOCK_NB is added to LOCK_SH or -LOCK_EX then C will return immediately rather than blocking +releases a previously requested lock. If LOCK_NB is bitwise-or'ed with +LOCK_SH or LOCK_EX then C will return immediately rather than blocking waiting for the lock (check the return status to see if you got it). To avoid the possibility of miscoordination, Perl now flushes FILEHANDLE @@ -2269,7 +2331,7 @@ This scalar value is B locale dependent, see L, but instead a Perl builtin. Also see the C 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 +time()), and the strftime(3) and mktime(3) functions 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: @@ -2759,6 +2821,34 @@ declared global variable without qualifying it with a package name. (But only within the lexical scope of the C declaration. In this it differs from "use vars", which is package scoped.) +An C declaration declares a global variable that will be visible +across its entire lexical scope, even across package boundaries. The +package in which the variable is entered is determined at the point +of the declaration, not at the point of use. This means the following +behavior holds: + + package Foo; + our $bar; # declares $Foo::bar for rest of lexical scope + $bar = 20; + + package Bar; + print $bar; # prints 20 + +Multiple C declarations in the same lexical scope are allowed +if they are in different packages. If they happened to be in the same +package, Perl will emit warnings if you have asked for them. + + use warnings; + package Foo; + our $bar; # declares $Foo::bar for rest of lexical scope + $bar = 20; + + package Bar; + our $bar = 30; # declares $Bar::bar for rest of lexical scope + print $bar; # prints 30 + + our $bar; # emits warning + =item pack TEMPLATE,LIST Takes a LIST of values and converts it into a string using the rules @@ -3451,13 +3541,16 @@ for this. Other restrictions include whether it works on directories, open files, or pre-existing files. Check L and either the rename(2) manpage or equivalent system documentation for details. +=item require VERSION + =item require EXPR =item require Demands some semantics specified by EXPR, or by C<$_> if EXPR is not -supplied. If EXPR is numeric, demands that the current version of Perl -(C<$]> or $PERL_VERSION) be equal or greater than EXPR. +supplied. If a version number or tuple is specified, or if EXPR is +numeric, demands that the current version of Perl +(C<$^V> or C<$]> or $PERL_VERSION) be equal or greater than EXPR. Otherwise, demands that a library file be included if it hasn't already been included. The file is included via the do-FILE mechanism, which is @@ -3638,9 +3731,8 @@ 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, C, and C -(start of the file, current position, end of the file) from any of the -modules Fcntl, C, or POSIX. Returns C<1> upon success, -C<0> otherwise. +(start of the file, current position, end of the file) from the Fcntl +module. Returns C<1> upon success, C<0> otherwise. If you want to position file for C or C, don't use C--buffering makes its effect on the file's system position @@ -3829,7 +3921,7 @@ array by 1 and moving everything down. If there are no elements in the array, returns the undefined value. If ARRAY is omitted, shifts the C<@_> array within the lexical scope of subroutines and formats, and the C<@ARGV> array at file scopes or within the lexical scopes established by -the C, C, C, C, and C +the C, C, C, C, and C constructs. See also C, C, and C. C and C do the @@ -3889,7 +3981,7 @@ processes. Returns the sine of EXPR (expressed in radians). If EXPR is omitted, returns sine of C<$_>. -For the inverse sine operation, you may use the C +For the inverse sine operation, you may use the C function, or use this relation: sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) } @@ -3925,6 +4017,10 @@ the system call of the same name. You should C first to get the proper definitions imported. See the examples in L. +On systems that support a close-on-exec flag on files, the flag will +be set for the newly opened file descriptor, as determined by the +value of $^F. See L. + =item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL Creates an unnamed pair of sockets in the specified domain, of the @@ -3932,6 +4028,10 @@ specified type. DOMAIN, TYPE, and PROTOCOL are specified the same as for the system call of the same name. If unimplemented, yields a fatal error. Returns true if successful. +On systems that support a close-on-exec flag on files, the flag will +be set for the newly opened file descriptors, as determined by the value +of $^F. See L. + Some systems defined C in terms of C, in which a call to C is essentially: @@ -4232,6 +4332,10 @@ In addition, Perl permits the following widely-supported conversions: %n special: *stores* the number of characters output so far into the next variable in the parameter list +And the following Perl-specific conversion: + + %v a string, output as a tuple of integers ("Perl" is 80.101.114.108) + Finally, for backward (and we do mean "backward") compatibility, Perl permits these unnecessary but widely-supported conversions: @@ -4272,8 +4376,8 @@ point in formatted real numbers is affected by the LC_NUMERIC locale. See L. 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 +either that the platform natively support quads or that Perl +be specifically compiled to support quads), the characters d u o x X b i D U O @@ -4292,7 +4396,7 @@ You can find out whether your Perl supports quads via L: print "quads\n"; If Perl understands "long doubles" (this requires that the platform -supports long doubles), the flags +support long doubles), the flags e f g E F G @@ -4390,9 +4494,9 @@ meaning of the fields: 5 gid numeric group ID of file's owner 6 rdev the device identifier (special files only) 7 size total size of file, in bytes - 8 atime last access time since the epoch - 9 mtime last modify time since the epoch - 10 ctime inode change time (NOT creation time!) since the epoch + 8 atime last access time in seconds since the epoch + 9 mtime last modify time in seconds since the epoch + 10 ctime inode change time (NOT creation time!) in seconds since the epoch 11 blksize preferred block size for file system I/O 12 blocks actual number of blocks allocated @@ -4406,7 +4510,8 @@ last stat or filetest are returned. Example: print "$file is executable NFS file\n"; } -(This works on machines only for which the device number is negative under NFS.) +(This works on machines only for which the device number is negative +under NFS.) Because the mode contains both the file type and its permissions, you should mask off the file type portion and (s)printf using a C<"%o"> @@ -4427,6 +4532,66 @@ The File::stat module provides a convenient, by-name access mechanism: $filename, $sb->size, $sb->mode & 07777, scalar localtime $sb->mtime; +You can import symbolic mode constants (C) and functions +(C) from the Fcntl module: + + use Fcntl ':mode'; + + $mode = (stat($filename))[2]; + + $user_rwx = ($mode & S_IRWXU) >> 6; + $group_read = ($mode & S_IRGRP) >> 3; + $other_execute = $mode & S_IXOTH; + + printf "Permissions are %04o\n", S_ISMODE($mode), "\n"; + + $is_setuid = $mode & S_ISUID; + $is_setgid = S_ISDIR($mode); + +You could write the last two using the C<-u> and C<-d> operators. +The commonly available S_IF* constants are + + # Permissions: read, write, execute, for user, group, others. + + S_IRWXU S_IRUSR S_IWUSR S_IXUSR + S_IRWXG S_IRGRP S_IWGRP S_IXGRP + S_IRWXO S_IROTH S_IWOTH S_IXOTH + + # Setuid/Setgid/Stickiness. + + S_ISUID S_ISGID S_ISVTX S_ISTXT + + # File types. Not necessarily all are available on your system. + + S_IFREG S_IFDIR S_IFLNK S_IFBLK S_ISCHR S_IFIFO S_IFSOCK S_IFWHT S_ENFMT + + # The following are compatibility aliases for S_IRUSR, S_IWUSR, S_IXUSR. + + S_IREAD S_IWRITE S_IEXEC + +and the S_IF* functions are + + S_IFMODE($mode) the part of $mode containg the permission bits + and the setuid/setgid/sticky bits + + S_IFMT($mode) the part of $mode containing the file type + which can be bit-anded with e.g. S_IFREG + or with the following functions + + # The operators -f, -d, -l, -b, -c, -p, and -s. + + S_ISREG($mode) S_ISDIR($mode) S_ISLNK($mode) + S_ISBLK($mode) S_ISCHR($mode) S_ISFIFO($mode) S_ISSOCK($mode) + + # No direct -X operator counterpart, but for the first one + # the -g operator is often equivalent. The ENFMT stands for + # record flocking enforcement, a platform-dependent feature. + + S_ISENFMT($mode) S_ISWHT($mode) + +See your native chmod(2) and stat(2) documentation for more details +about the S_* constants. + =item study SCALAR =item study @@ -4666,7 +4831,7 @@ 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, C, and C (start of the file, current position, end of the file) -from any of the modules Fcntl, C, or POSIX. +from the Fcntl module. 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 returns @@ -5068,13 +5233,17 @@ package. It is exactly equivalent to except that Module I be a bareword. -If the first argument to C is a number, it is treated as a version -number instead of a module name. If the version of the Perl interpreter -is less than VERSION, then an error message is printed and Perl exits -immediately. This is often useful if you need to check the current -Perl version before Cing library modules that have changed in -incompatible ways from older versions of Perl. (We try not to do -this more than we have to.) +If the first argument to C is a number or a version tuple, it is +treated as a version instead of a module name. If the version +of the Perl interpreter is less than VERSION, then an error message +is printed and Perl exits immediately. + + use 5.005_03; # version number + use v5.6.0; # version tuple + +This is often useful if you need to check the current Perl version before +Cing library modules that have changed in incompatible ways from +older versions of Perl. (We try not to do this more than we have to.) The C forces the C and C to happen at compile time. The C makes sure the module is loaded into memory if it hasn't been @@ -5084,8 +5253,7 @@ features back into the current package. The module can implement its C method any way it likes, though most modules just choose to derive their C method via inheritance from the C class that is defined in the C module. See L. If no C -method can be found then the error is currently silently ignored. This -may change to a fatal error in a future version. +method can be found then the call is skipped. If you don't want your namespace altered, explicitly supply an empty list: @@ -5188,9 +5356,13 @@ to give the expression the correct precedence as in vec($image, $max_x * $x + $y, 8) = 3; -Vectors created with C 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. +If the selected element is off the end of the string, the value 0 is +returned. If an element off the end of the string is written to, +Perl will first extend the string with sufficiently many zero bytes. + +Strings created with C can also be manipulated with the logical +operators C<|>, C<&>, C<^>, and C<~>. These operators will assume a bit +vector operation is desired when both operands are strings. See L. The following code will build up an ASCII string saying C<'PerlPerlPerl'>.