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
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
$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
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.
=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
=item getpgrp
This is identical to Perl's builtin C<getpgrp()> function for
-returning the prcess group identifier of the current process, see
+returning the process group identifier of the current process, see
L<perlfunc/getpgrp>.
=item getpid
or
- sub log10 { log($_[0]) / 2.30258509299405 }
+ sub log10 { log($_[0]) / 2.30258509299405 }
or
This is identical to the C function C<mblen()>.
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<mbstowcs()>.
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<mbtowc()>.
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
if (mkfifo($path, $mode)) { ....
Returns C<undef> on failure. The C<$mode> is similar to the
-mode of C<mkdir()>, see L<perlfunc/mkdir>.
+mode of C<mkdir()>, see L<perlfunc/mkdir>, though for C<mkfifo>
+you B<must> specify the C<$mode>.
=item mktime
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<mon>), weekday (C<wday>), and yearday (C<yday>) begin at zero.
I.e. January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1. The
Open a directory for reading.
- $dir = POSIX::opendir( "/tmp" );
+ $dir = POSIX::opendir( "/var" );
@files = POSIX::readdir( $dir );
POSIX::closedir( $dir );
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.
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>.
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<perlvar/$GID>, except that the latter
+C<$)> variable, see L<perlvar/$EGID>, 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.
=item sigaction
-Detailed signal management. This uses C<POSIX::SigAction> objects for the
-C<action> and C<oldaction> arguments. Consult your system's C<sigaction>
-manpage for details.
+Detailed signal management. This uses C<POSIX::SigAction> objects for
+the C<action> and C<oldaction> arguments (the oldaction can also be
+just a hash reference). Consult your system's C<sigaction> manpage
+for details, see also C<POSIX::SigRt>.
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.
+
+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<sigaction> and possibly also C<siginfo> documentation.
=item siglongjmp
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.
=item stat
This is identical to Perl's builtin C<stat()> function
-for retutning information about files and directories.
+for returning information about files and directories.
=item strcat
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.
This is identical to the C function C<wcstombs()>.
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<wctomb()>.
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
$fd = POSIX::open( "foo", &POSIX::O_WRONLY );
$buf = "hello";
- $bytes = POSIX::write( $b, $buf, 5 );
+ $bytes = POSIX::write( $fd, $buf, 5 );
Returns C<undef> on failure.
=item new
Creates a new C<POSIX::SigAction> object which corresponds to the C
-C<struct sigaction>. 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<POSIX::SigSet>
-object, it defaults to the empty set. The third parameter contains the
+C<struct sigaction>. 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<POSIX::SigSet> 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( \&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
$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::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<delete> and C<exists> on the elements, and use
+C<scalar> 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<local> on $POSIX::SigRt::SIGACTION_FLAGS, or you can
+derive from POSIX::SigRt and define your own C<new()> (the tied hash
+STORE method of the %SIGRT calls C<new($rtsig, $handler, $SIGACTION_FLAGS)>,
+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<NOTE:> 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<undef>
+if no POSIX realtime signals are available.
+
+=item SIGRTMAX
+
+Return the maximum POSIX realtime signal number available, or C<undef>
+if no POSIX realtime signals are available.
+
=back
=head2 POSIX::SigSet
Obtain the attributes for stdin.
+ $termios->getattr( 0 ) # Recommended for clarity.
$termios->getattr()
Obtain the attributes for stdout.