X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=d38424904b6fdde664366f0657d6f32acea637a8;hb=e1f775196788199aa205bfd047e37a8e188e06b2;hp=88cbb0a6e5fcd91ee83ac562bc89084254856163;hpb=fac7034317257ca372dae1fbecbc49d69a7c7d66;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 88cbb0a..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]) } @@ -559,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 @@ -766,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] ) } @@ -929,8 +941,9 @@ See also L, L, L. 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. -If the array elements happen to be at the end of the array, the size -of the array will shrink by that number of elements. +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). Returns each element so deleted or the undefined value if there was no such element. Deleting from C<$ENV{}> modifies the environment. Deleting from @@ -939,7 +952,9 @@ 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. See L. +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: @@ -2316,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: @@ -3716,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 @@ -3967,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])) } @@ -4003,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 @@ -4010,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: @@ -4354,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 @@ -4374,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 @@ -4488,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"> @@ -4509,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 @@ -4748,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