POSIX::isXXX(undef) segfaulted. (bug #24554.)

[p5sagit/p5-mst-13.2.git] / ext / POSIX / POSIX.pod

diff --git a/ext/POSIX/POSIX.pod b/ext/POSIX/POSIX.pod
index d16bc32..598464d 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
@@ -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
 
@@ -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