Refactoring to Sv*_set() macros - patch #5

[perl5.git] / ext / POSIX / POSIX.pod

diff --git a/ext/POSIX/POSIX.pod b/ext/POSIX/POSIX.pod
index d16bc32..1a09c69 100644 (file)
--- a/ext/POSIX/POSIX.pod
+++ b/ext/POSIX/POSIX.pod
@@ -19,10 +19,14 @@ POSIX - Perl interface to IEEE Std 1003.1
 
 The POSIX module permits you to access all (or nearly all) the standard
 POSIX 1003.1 identifiers.  Many of these identifiers have been given Perl-ish
-interfaces.  Things which are C<#defines> in C, like EINTR or O_NDELAY, are
-automatically exported into your namespace.  All functions are only exported
-if you ask for them explicitly.  Most likely people will prefer to use the
-fully-qualified function names.
+interfaces.
+
+I<Everything is exported by default> with the exception of any POSIX
+functions with the same name as a built-in Perl function, such as
+C<abs>, C<alarm>, C<rmdir>, C<write>, etc.., which will be exported
+only if you ask for them explicitly.  This is an unfortunate backwards
+compatibility feature.  You can stop the exporting by saying C<use
+POSIX ()> and then use the fully qualified names (ie. C<POSIX::SEEK_END>).
 
 This document gives a condensed list of the features available in the POSIX
 module.  Consult your operating system's manpages for general information on
@@ -413,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<POSIX::open>.
 
 The following will determine the maximum length of the longest allowable
-pathname on the filesystem which holds C</tmp/foo>.
+pathname on the filesystem which holds C</var/foo>.
 
-       $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<undef> on failure.
@@ -915,7 +919,7 @@ See also L<perlfunc/sysopen>.
 
 Open a directory for reading.
 
-       $dir = POSIX::opendir( "/tmp" );
+       $dir = POSIX::opendir( "/var" );
        @files = POSIX::readdir( $dir );
        POSIX::closedir( $dir );
 
@@ -926,9 +930,9 @@ Returns C<undef> 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</tmp>.
+pathname on the filesystem which holds C</var>.
 
-       $path_max = POSIX::pathconf( "/tmp", &POSIX::_PC_PATH_MAX );
+       $path_max = POSIX::pathconf( "/var", &POSIX::_PC_PATH_MAX );
 
 Returns C<undef> on failure.
 
@@ -951,9 +955,9 @@ variable instead, see L<perlfunc/warn> and L<perlvar/$ERRNO>.
 Create an interprocess channel.  This returns file descriptors like those
 returned by C<POSIX::open>.
 
-       ($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<perlfunc/pipe>.
 
@@ -1119,9 +1123,11 @@ manpage for details.
 
 Synopsis:
 
-       sigaction(sig, action, oldaction = 0)
+       sigaction(signal, action, oldaction = 0)
 
-Returns C<undef> on failure.
+Returns C<undef> on failure.  The C<signal> must be a number (like
+SIGHUP), not a string (like "SIGHUP"), though Perl does try hard
+to understand you.
 
 =item siglongjmp
 
@@ -1184,7 +1190,7 @@ See also L<Math::Trig>.
 
 This is functionally identical to Perl's builtin C<sleep()> function
 for suspending the execution of the current for process for certain
-number of seconds, see L<perlfunc/sleep>.  There is one signifanct 
+number of seconds, see L<perlfunc/sleep>.  There is one significant 
 difference, however: C<POSIX::sleep()> returns the number of
 B<unslept> seconds, while the C<CORE::sleep()> returns the
 number of slept seconds.
@@ -1336,8 +1342,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.
@@ -1635,9 +1641,9 @@ object, it defaults to the empty set.  The third parameter contains the
 C<sa_flags>, it defaults to 0.
 
        $sigset = POSIX::SigSet->new(SIGINT, SIGQUIT);
-       $sigaction = POSIX::SigAction->new( 'main::handler', $sigset, &POSIX::SA_NOCLDSTOP );
+       $sigaction = POSIX::SigAction->new( \&main::handler, $sigset, &POSIX::SA_NOCLDSTOP );
 
-This C<POSIX::SigAction> object should be used with the C<POSIX::sigaction()>
+This C<POSIX::SigAction> object is intended for use with the C<POSIX::sigaction()>
 function.
 
 =back
@@ -1655,6 +1661,23 @@ 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<perlipc> 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<POSIX::SigAction> 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<POSIX::sigaction()>:
+
+       sigaction(SIGINT, $new_action, $old_action);
+       if ($old_action->safe) {
+           # previous SIGINT handler used safe signals
+       }
+
 =back
 
 =head2 POSIX::SigSet