X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=ext%2FPOSIX%2FPOSIX.pod;h=7263d0a62a090af23befb0133824b3d772ec23a1;hb=e27b5b51275a893e82bce85334679ee38d3d6bf8;hp=1ba494552ee568d10a7f939ac2ba35754ad14318;hpb=90b1bb76ac33d378b485f66b5eb18e95143363c9;p=p5sagit%2Fp5-mst-13.2.git diff --git a/ext/POSIX/POSIX.pod b/ext/POSIX/POSIX.pod index 1ba4945..7263d0a 100644 --- a/ext/POSIX/POSIX.pod +++ b/ext/POSIX/POSIX.pod @@ -25,7 +25,7 @@ I with the exception of any POSIX functions with the same name as a built-in Perl function, such as C, C, C, C, etc.., which will be exported only if you ask for them explicitly. This is an unfortunate backwards -compatiblity feature. You can stop the exporting by saying C and then use the fully qualified names (ie. C). This document gives a condensed list of the features available in the POSIX @@ -46,7 +46,7 @@ the standard distribution. It incorporates autoloading, namespace games, and dynamic loading of code that's in Perl, C, or both. It's a great source of wisdom. -=head1 CAVEATS +=head1 CAVEATS A few functions are not implemented because they are C specific. If you attempt to call these, they will print a message telling you that they @@ -125,8 +125,8 @@ and it is called thusly $wday, $yday, $isdst); The C<$mon> is zero-based: January equals C<0>. The C<$year> is -1900-based: 2001 equals C<101>. The C<$wday>, C<$yday>, and C<$isdst> -default to zero (and the first two are usually ignored anyway). +1900-based: 2001 equals C<101>. C<$wday> and C<$yday> default to zero +(and are usually ignored anyway), and C<$isdst> defaults to -1. =item asin @@ -417,9 +417,9 @@ Retrieves the value of a configurable limit on a file or directory. This uses file descriptors such as those obtained by calling C. The following will determine the maximum length of the longest allowable -pathname on the filesystem which holds C. +pathname on the filesystem which holds C. - $fd = POSIX::open( "/tmp/foo", &POSIX::O_RDONLY ); + $fd = POSIX::open( "/var/foo", &POSIX::O_RDONLY ); $path_max = POSIX::fpathconf( $fd, &POSIX::_PC_PATH_MAX ); Returns C on failure. @@ -509,7 +509,7 @@ variable C<$(>, see L. =item getenv -Returns the value of the specified enironment variable. +Returns the value of the specified environment variable. The same information is available through the C<%ENV> array. =item geteuid @@ -547,7 +547,7 @@ L. =item getpgrp This is identical to Perl's builtin C function for -returning the prcess group identifier of the current process, see +returning the process group identifier of the current process, see L. =item getpid @@ -770,7 +770,7 @@ You can also use or - sub log10 { log($_[0]) / 2.30258509299405 } + sub log10 { log($_[0]) / 2.30258509299405 } or @@ -798,21 +798,21 @@ malloc() is C-specific. Perl does memory management transparently. This is identical to the C function C. Perl does not have any support for the wide and multibyte -characters of the C standards, so this might be a rather +characters of the C standards, so this might be a rather useless function. =item mbstowcs This is identical to the C function C. Perl does not have any support for the wide and multibyte -characters of the C standards, so this might be a rather +characters of the C standards, so this might be a rather useless function. =item mbtowc This is identical to the C function C. Perl does not have any support for the wide and multibyte -characters of the C standards, so this might be a rather +characters of the C standards, so this might be a rather useless function. =item memchr @@ -848,7 +848,8 @@ FIFO special files. if (mkfifo($path, $mode)) { .... Returns C on failure. The C<$mode> is similar to the -mode of C, see L. +mode of C, see L, though for C +you B specify the C<$mode>. =item mktime @@ -856,7 +857,7 @@ Convert date/time info to a calendar time. Synopsis: - mktime(sec, min, hour, mday, mon, year, wday = 0, yday = 0, isdst = 0) + mktime(sec, min, hour, mday, mon, year, wday = 0, yday = 0, isdst = -1) The month (C), weekday (C), and yearday (C) begin at zero. I.e. January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1. The @@ -919,7 +920,7 @@ See also L. Open a directory for reading. - $dir = POSIX::opendir( "/tmp" ); + $dir = POSIX::opendir( "/var" ); @files = POSIX::readdir( $dir ); POSIX::closedir( $dir ); @@ -930,9 +931,9 @@ Returns C on failure. Retrieves the value of a configurable limit on a file or directory. The following will determine the maximum length of the longest allowable -pathname on the filesystem which holds C. +pathname on the filesystem which holds C. - $path_max = POSIX::pathconf( "/tmp", &POSIX::_PC_PATH_MAX ); + $path_max = POSIX::pathconf( "/var", &POSIX::_PC_PATH_MAX ); Returns C on failure. @@ -955,9 +956,9 @@ variable instead, see L and L. Create an interprocess channel. This returns file descriptors like those returned by C. - ($fd0, $fd1) = POSIX::pipe(); - POSIX::write( $fd0, "hello", 5 ); - POSIX::read( $fd1, $buf, 5 ); + my ($read, $write) = POSIX::pipe(); + POSIX::write( $write, "hello", 5 ); + POSIX::read( $read, $buf, 5 ); See also L. @@ -1054,7 +1055,7 @@ see L. Sets the real group identifier and the effective group identifier for this process. Similar to assigning a value to the Perl's builtin -C<$)> variable, see L, except that the latter +C<$)> variable, see L, except that the latter will change only the real user identifier, and that the setgid() uses only a single numeric argument, as opposed to a space-separated list of numbers. @@ -1117,15 +1118,47 @@ will change only the real user identifier. =item sigaction -Detailed signal management. This uses C objects for the -C and C arguments. Consult your system's C -manpage for details. +Detailed signal management. This uses C objects for +the C and C arguments (the oldaction can also be +just a hash reference). Consult your system's C manpage +for details, see also C. Synopsis: - sigaction(sig, action, oldaction = 0) + sigaction(signal, action, oldaction = 0) -Returns C on failure. +Returns C on failure. The C must be a number (like +SIGHUP), not a string (like "SIGHUP"), though Perl does try hard +to understand you. + +If you use the SA_SIGINFO flag, the signal handler will in addition to +the first argument, the signal name, also receive a second argument, a +hash reference, inside which are the following keys with the following +semantics, as defined by POSIX/SUSv3: + + signo the signal number + errno the error number + code if this is zero or less, the signal was sent by + a user process and the uid and pid make sense, + otherwise the signal was sent by the kernel + +The following are also defined by POSIX/SUSv3, but unfortunately +not very widely implemented: + + pid the process id generating the signal + uid the uid of the process id generating the signal + status exit value or signal for SIGCHLD + band band event for SIGPOLL + +A third argument is also passed to the handler, which contains a copy +of the raw binary contents of the siginfo structure: if a system has +some non-POSIX fields, this third argument is where to unpack() them +from. + +Note that not all siginfo values make sense simultaneously (some are +valid only for certain signals, for example), and not all values make +sense from Perl perspective, you should to consult your system's +C and possibly also C documentation. =item siglongjmp @@ -1188,7 +1221,7 @@ See also L. This is functionally identical to Perl's builtin C function for suspending the execution of the current for process for certain -number of seconds, see L. There is one signifanct +number of seconds, see L. There is one significant difference, however: C returns the number of B seconds, while the C returns the number of slept seconds. @@ -1217,7 +1250,7 @@ see L. =item stat This is identical to Perl's builtin C function -for retutning information about files and directories. +for returning information about files and directories. =item strcat @@ -1340,8 +1373,8 @@ To parse a string $str as a floating point number use The second returned item and $! can be used to check for valid input: - if (($str eq '') || ($n_unparsed != 0) || !$!) { - die "Non-numeric input $str" . $! ? ": $!\n" : "\n"; + if (($str eq '') || ($n_unparsed != 0) || $!) { + die "Non-numeric input $str" . ($! ? ": $!\n" : "\n"); } When called in a scalar context strtod returns the parsed number. @@ -1598,14 +1631,14 @@ builtin C function, see L. This is identical to the C function C. Perl does not have any support for the wide and multibyte -characters of the C standards, so this might be a rather +characters of the C standards, so this might be a rather useless function. =item wctomb This is identical to the C function C. Perl does not have any support for the wide and multibyte -characters of the C standards, so this might be a rather +characters of the C standards, so this might be a rather useless function. =item write @@ -1615,7 +1648,7 @@ calling C. $fd = POSIX::open( "foo", &POSIX::O_WRONLY ); $buf = "hello"; - $bytes = POSIX::write( $b, $buf, 5 ); + $bytes = POSIX::write( $fd, $buf, 5 ); Returns C on failure. @@ -1632,16 +1665,16 @@ See also L. =item new Creates a new C object which corresponds to the C -C. This object will be destroyed automatically when it is -no longer needed. The first parameter is the fully-qualified name of a sub -which is a signal-handler. The second parameter is a C -object, it defaults to the empty set. The third parameter contains the +C. This object will be destroyed automatically when +it is no longer needed. The first parameter is the handler, a sub +reference. The second parameter is a C object, it +defaults to the empty set. The third parameter contains the C, it defaults to 0. $sigset = POSIX::SigSet->new(SIGINT, SIGQUIT); - $sigaction = POSIX::SigAction->new( 'main::handler', $sigset, &POSIX::SA_NOCLDSTOP ); + $sigaction = POSIX::SigAction->new( \&handler, $sigset, &POSIX::SA_NOCLDSTOP ); -This C object should be used with the C +This C object is intended for use with the C function. =back @@ -1659,6 +1692,74 @@ accessor functions to get/set the values of a SigAction object. $sigset = $sigaction->mask; $sigaction->flags(&POSIX::SA_RESTART); +=item safe + +accessor function for the "safe signals" flag of a SigAction object; see +L for general information on safe (a.k.a. "deferred") signals. If +you wish to handle a signal safely, use this accessor to set the "safe" flag +in the C object: + + $sigaction->safe(1); + +You may also examine the "safe" flag on the output action object which is +filled in when given as the third parameter to C: + + sigaction(SIGINT, $new_action, $old_action); + if ($old_action->safe) { + # previous SIGINT handler used safe signals + } + +=back + +=head2 POSIX::SigRt + +=over 8 + +=item %SIGRT + +A hash of the POSIX realtime signal handlers. It is an extension of +the standard %SIG, the $POSIX::SIGRT{SIGRTMIN} is roughly equivalent +to $SIG{SIGRTMIN}, but the right POSIX moves (see below) are made with +the POSIX::SigSet and POSIX::sigaction instead of accessing the %SIG. + +You can set the %POSIX::SIGRT elements to set the POSIX realtime +signal handlers, use C and C on the elements, and use +C on the C<%POSIX::SIGRT> to find out how many POSIX realtime +signals there are available (SIGRTMAX - SIGRTMIN + 1, the SIGRTMAX is +a valid POSIX realtime signal). + +Setting the %SIGRT elements is equivalent to calling this: + + sub new { + my ($rtsig, $handler, $flags) = @_; + my $sigset = POSIX::SigSet($rtsig); + my $sigact = POSIX::SigAction->new($handler, $sigset, $flags); + sigaction($rtsig, $sigact); + } + +The flags default to zero, if you want something different you can +either use C on $POSIX::SigRt::SIGACTION_FLAGS, or you can +derive from POSIX::SigRt and define your own C (the tied hash +STORE method of the %SIGRT calls C, +where the $rtsig ranges from zero to SIGRTMAX - SIGRTMIN + 1). + +Just as with any signal, you can use sigaction($rtsig, undef, $oa) to +retrieve the installed signal handler (or, rather, the signal action). + +B whether POSIX realtime signals really work in your system, or +whether Perl has been compiled so that it works with them, is outside +of this discussion. + +=item SIGRTMIN + +Return the minimum POSIX realtime signal number available, or C +if no POSIX realtime signals are available. + +=item SIGRTMAX + +Return the maximum POSIX realtime signal number available, or C +if no POSIX realtime signals are available. + =back =head2 POSIX::SigSet @@ -1740,6 +1841,7 @@ Get terminal control attributes. Obtain the attributes for stdin. + $termios->getattr( 0 ) # Recommended for clarity. $termios->getattr() Obtain the attributes for stdout.