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
This is identical to the C function C<_exit()>. It exits the program
immediately which means among other things buffered I/O is B<not> flushed.
+Note that when using threads and in Linux this is B<not> a good way to
+exit a thread because in Linux processes and threads are kind of the
+same thing (Note: while this is the situation in early 2003 there are
+projects under way to have threads with more POSIXly semantics in Linux).
+If you want not to return from a thread, detach the thread.
+
=item abort
This is identical to the C function C<abort()>. It terminates the
=item acos
This is identical to the C function C<acos()>, returning
-the arcus cosine of its numerical argument.
+the arcus cosine of its numerical argument. See also L<Math::Trig>.
=item alarm
$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
This is identical to the C function C<asin()>, returning
-the arcus sine of its numerical argument.
+the arcus sine of its numerical argument. See also L<Math::Trig>.
=item assert
=item atan
This is identical to the C function C<atan()>, returning the
-arcus tangent of its numerical argument.
+arcus tangent of its numerical argument. See also L<Math::Trig>.
=item atan2
This is identical to Perl's builtin C<atan2()> function, returning
the arcus tangent defined by its two numerical arguments, the I<y>
-coordinate and the I<x> coordinate.
+coordinate and the I<x> coordinate. See also L<Math::Trig>.
=item atexit
=item clearerr
-Use the method L<IO::Handle::clearerr()> instead, to reset the error
+Use the method C<IO::Handle::clearerr()> instead, to reset the error
state (if any) and EOF state (if any) of the given stream.
=item clock
This is identical to Perl's builtin C<cos()> function, for returning
the cosine of its numerical argument, see L<perlfunc/cos>.
+See also L<Math::Trig>.
=item cosh
This is identical to the C function C<cosh()>, for returning
-the hyperbolic cosine of its numeric argument.
+the hyperbolic cosine of its numeric argument. See also L<Math::Trig>.
=item creat
=item ctime
-This is identical to the C function C<ctime()>.
+This is identical to the C function C<ctime()> and equivalent
+to C<asctime(localtime(...))>, see L</asctime> and L</localtime>.
=item cuserid
-Get the character login name of the user.
+Get the login name of the owner of the current process.
$name = POSIX::cuserid();
=item difftime
-This is identical to the C function C<difftime()>.
+This is identical to the C function C<difftime()>, for returning
+the time difference (in seconds) between two times (as returned
+by C<time()>), see L</time>.
=item div
=item dup
-This is similar to the C function C<dup()>.
+This is similar to the C function C<dup()>, for duplicating a file
+descriptor.
This uses file descriptors such as those obtained by calling
C<POSIX::open>.
=item dup2
-This is similar to the C function C<dup2()>.
+This is similar to the C function C<dup2()>, for duplicating a file
+descriptor to an another known file descriptor.
This uses file descriptors such as those obtained by calling
C<POSIX::open>.
$errno = POSIX::errno();
-This identical to the numerical values of the C<$!>, see L<perlvar>.
+This identical to the numerical values of the C<$!>, see L<perlvar/$ERRNO>.
=item execl
=item fclose
-Use method C<IO::Handle::close()> instead.
+Use method C<IO::Handle::close()> instead, or see L<perlfunc/close>.
=item fcntl
=item fdopen
-Use method C<IO::Handle::new_from_fd()> instead.
+Use method C<IO::Handle::new_from_fd()> instead, or see L<perlfunc/open>.
=item feof
-Use method C<IO::Handle::eof()> instead.
+Use method C<IO::Handle::eof()> instead, or see L<perlfunc/eof>.
=item ferror
=item fflush
Use method C<IO::Handle::flush()> instead.
+See also L<perlvar/$OUTPUT_AUTOFLUSH>.
=item fgetc
-Use method C<IO::Handle::getc()> instead.
+Use method C<IO::Handle::getc()> instead, or see L<perlfunc/read>.
=item fgetpos
-Use method C<IO::Seekable::getpos()> instead.
+Use method C<IO::Seekable::getpos()> instead, or see L<L/seek>.
=item fgets
-Use method C<IO::Handle::gets()> instead. Similar to <>, also known
+Use method C<IO::Handle::gets()> instead. Similar to E<lt>E<gt>, also known
as L<perlfunc/readline>.
=item fileno
-Use method C<IO::Handle::fileno()> instead.
+Use method C<IO::Handle::fileno()> instead, or see L<perlfunc/fileno>.
=item floor
This is identical to the C function C<fmod()>.
- $r = modf($x, $y);
+ $r = fmod($x, $y);
It returns the remainder C<$r = $x - $n*$y>, where C<$n = trunc($x/$y)>.
The C<$r> has the same sign as C<$x> and magnitude (absolute value)
=item fopen
-Use method C<IO::File::open()> instead.
+Use method C<IO::File::open()> instead, or see L<perlfunc/open>.
=item fork
-This is identical to Perl's builtin C<fork()> function.
+This is identical to Perl's builtin C<fork()> function
+for duplicating the current process, see L<perlfunc/fork>
+and L<perlfork> if you are in Windows.
=item fpathconf
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.
Return the mantissa and exponent of a floating-point number.
- ($mantissa, $exponent) = POSIX::frexp( 3.14 );
+ ($mantissa, $exponent) = POSIX::frexp( 1.234e56 );
=item fscanf
-fscanf() is C-specific--use <> and regular expressions instead.
+fscanf() is C-specific, use E<lt>E<gt> and regular expressions instead.
=item fseek
-Use method C<IO::Seekable::seek()> instead.
+Use method C<IO::Seekable::seek()> instead, or see L<perlfunc/seek>.
=item fsetpos
-Use method C<IO::Seekable::setpos()> instead.
+Use method C<IO::Seekable::setpos()> instead, or seek L<perlfunc/seek>.
=item fstat
$fd = POSIX::open( "foo", &POSIX::O_RDONLY );
@stats = POSIX::fstat( $fd );
+=item fsync
+
+Use method C<IO::Handle::sync()> instead.
+
=item ftell
-Use method C<IO::Seekable::tell()> instead.
+Use method C<IO::Seekable::tell()> instead, or see L<perlfunc/tell>.
=item fwrite
=item getchar
-Returns one character from STDIN.
+Returns one character from STDIN. Identical to Perl's C<getc()>,
+see L<perlfunc/getc>.
=item getcwd
Returns the name of the current working directory.
+See also L<Cwd>.
=item getegid
-Returns the effective group id.
+Returns the effective group identifier. Similar to Perl' s builtin
+variable C<$(>, see L<perlvar/$EGID>.
=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
-Returns the effective user id.
+Returns the effective user identifier. Identical to Perl's builtin C<$E<gt>>
+variable, see L<perlvar/$EUID>.
=item getgid
-Returns the user's real group id.
+Returns the user's real group identifier. Similar to Perl's builtin
+variable C<$)>, see L<perlvar/$GID>.
=item getgrgid
-This is identical to Perl's builtin C<getgrgid()> function,
-see L<perlfunc/getgrgid>.
+This is identical to Perl's builtin C<getgrgid()> function for
+returning group entries by group identifiers, see
+L<perlfunc/getgrgid>.
=item getgrnam
-This is identical to Perl's builtin C<getgrnam()> function,
-see L<perlfunc/getgrnam>.
+This is identical to Perl's builtin C<getgrnam()> function for
+returning group entries by group names, see L<perlfunc/getgrnam>.
=item getgroups
-Returns the ids of the user's supplementary groups.
+Returns the ids of the user's supplementary groups. Similar to Perl's
+builtin variable C<$)>, see L<perlvar/$GID>.
=item getlogin
-This is identical to Perl's builtin C<getlogin()> function,
-see L<perlfunc/getlogin>.
+This is identical to Perl's builtin C<getlogin()> function for
+returning the user name associated with the current session, see
+L<perlfunc/getlogin>.
=item getpgrp
-This is identical to Perl's builtin C<getpgrp()> function,
-see L<perlfunc/getpgrp>.
+This is identical to Perl's builtin C<getpgrp()> function for
+returning the process group identifier of the current process, see
+L<perlfunc/getpgrp>.
=item getpid
-Returns the process's id.
+Returns the process identifier. Identical to Perl's builtin
+variable C<$$>, see L<perlvar/$PID>.
=item getppid
-This is identical to Perl's builtin C<getppid()> function,
-see L<perlfunc/getppid>.
+This is identical to Perl's builtin C<getppid()> function for
+returning the process identifier of the parent process of the current
+process , see L<perlfunc/getppid>.
=item getpwnam
-This is identical to Perl's builtin C<getpwnam()> function,
-see L<perlfunc/getpwnam>.
+This is identical to Perl's builtin C<getpwnam()> function for
+returning user entries by user names, see L<perlfunc/getpwnam>.
=item getpwuid
-This is identical to Perl's builtin C<getpwuid()> function,
-see L<perlfunc/getpwuid>.
+This is identical to Perl's builtin C<getpwuid()> function for
+returning user entries by user identifiers, see L<perlfunc/getpwuid>.
=item gets
-Returns one line from C<STDIN>, similar to <>, also known
-as the C<readline()> functions, see L<perlfunc/readline>.
+Returns one line from C<STDIN>, similar to E<lt>E<gt>, also known
+as the C<readline()> function, see L<perlfunc/readline>.
+
+B<NOTE>: if you have C programs that still use C<gets()>, be very
+afraid. The C<gets()> function is a source of endless grief because
+it has no buffer overrun checks. It should B<never> be used. The
+C<fgets()> function should be preferred instead.
=item getuid
-Returns the user's id.
+Returns the user's identifier. Identical to Perl's builtin C<$E<lt>> variable,
+see L<perlvar/$UID>.
=item gmtime
-This is identical to Perl's builtin C<gmtime()> function,
+This is identical to Perl's builtin C<gmtime()> function for
+converting seconds since the epoch to a date in Greenwich Mean Time,
see L<perlfunc/gmtime>.
=item isalnum
-This is identical to the C function, except that it can apply to a single
-character or to a whole string. Consider using regular expressions and the
-C</[[:isalnum:]]/> construct instead.
+This is identical to the C function, except that it can apply to a
+single character or to a whole string. Note that locale settings may
+affect what characters are considered C<isalnum>. Does not work on
+Unicode characters code point 256 or higher. Consider using regular
+expressions and the C</[[:alnum:]]/> construct instead, or possibly
+the C</\w/> construct.
=item isalpha
-This is identical to the C function, except that it can apply to a single
-character or to a whole string. Consider using regular expressions and the
-C</[[:isalpha:]]/> construct instead.
+This is identical to the C function, except that it can apply to
+a single character or to a whole string. Note that locale settings
+may affect what characters are considered C<isalpha>. Does not work
+on Unicode characters code point 256 or higher. Consider using regular
+expressions and the C</[[:alpha:]]/> construct instead.
=item isatty
=item iscntrl
-This is identical to the C function, except that it can apply to a single
-character or to a whole string. Consider using regular expressions and the
-C</[[:iscntrl:]]/> construct instead.
+This is identical to the C function, except that it can apply to
+a single character or to a whole string. Note that locale settings
+may affect what characters are considered C<iscntrl>. Does not work
+on Unicode characters code point 256 or higher. Consider using regular
+expressions and the C</[[:cntrl:]]/> construct instead.
=item isdigit
-This is identical to the C function, except that it can apply to a single
-character or to a whole string. Consider using regular expressions and the
-C</[[:isdigit:]]/> construct instead.
+This is identical to the C function, except that it can apply to
+a single character or to a whole string. Note that locale settings
+may affect what characters are considered C<isdigit> (unlikely, but
+still possible). Does not work on Unicode characters code point 256
+or higher. Consider using regular expressions and the C</[[:digit:]]/>
+construct instead, or the C</\d/> construct.
=item isgraph
-This is identical to the C function, except that it can apply to a single
-character or to a whole string. Consider using regular expressions and the
-C</[[:isgraph:]]/> construct instead.
+This is identical to the C function, except that it can apply to
+a single character or to a whole string. Note that locale settings
+may affect what characters are considered C<isgraph>. Does not work
+on Unicode characters code point 256 or higher. Consider using regular
+expressions and the C</[[:graph:]]/> construct instead.
=item islower
-This is identical to the C function, except that it can apply to a single
-character or to a whole string. Consider using regular expressions and the
-C</[[:islower:]]/> construct instead.
+This is identical to the C function, except that it can apply to
+a single character or to a whole string. Note that locale settings
+may affect what characters are considered C<islower>. Does not work
+on Unicode characters code point 256 or higher. Consider using regular
+expressions and the C</[[:lower:]]/> construct instead. Do B<not> use
+C</[a-z]/>.
=item isprint
-This is identical to the C function, except that it can apply to a single
-character or to a whole string. Consider using regular expressions and the
-C</[[:isprint:]]/> construct instead.
+This is identical to the C function, except that it can apply to
+a single character or to a whole string. Note that locale settings
+may affect what characters are considered C<isprint>. Does not work
+on Unicode characters code point 256 or higher. Consider using regular
+expressions and the C</[[:print:]]/> construct instead.
=item ispunct
-This is identical to the C function, except that it can apply to a single
-character or to a whole string. Consider using regular expressions and the
-C</[[:ispunct:]]/> construct instead.
+This is identical to the C function, except that it can apply to
+a single character or to a whole string. Note that locale settings
+may affect what characters are considered C<ispunct>. Does not work
+on Unicode characters code point 256 or higher. Consider using regular
+expressions and the C</[[:punct:]]/> construct instead.
=item isspace
-This is identical to the C function, except that it can apply to a single
-character or to a whole string. Consider using regular expressions and the
-C</[[:isspace:]]/> construct instead.
+This is identical to the C function, except that it can apply to
+a single character or to a whole string. Note that locale settings
+may affect what characters are considered C<isspace>. Does not work
+on Unicode characters code point 256 or higher. Consider using regular
+expressions and the C</[[:space:]]/> construct instead, or the C</\s/>
+construct. (Note that C</\s/> and C</[[:space:]]/> are slightly
+different in that C</[[:space:]]/> can normally match a vertical tab,
+while C</\s/> does not.)
=item isupper
-This is identical to the C function, except that it can apply to a single
-character or to a whole string. Consider using regular expressions and the
-C</[[:isupper:]]/> construct instead.
+This is identical to the C function, except that it can apply to
+a single character or to a whole string. Note that locale settings
+may affect what characters are considered C<isupper>. Does not work
+on Unicode characters code point 256 or higher. Consider using regular
+expressions and the C</[[:upper:]]/> construct instead. Do B<not> use
+C</[A-Z]/>.
=item isxdigit
This is identical to the C function, except that it can apply to a single
-character or to a whole string. Consider using regular expressions and the
-C</[[:isxdigit:]]/> construct instead.
+character or to a whole string. Note that locale settings may affect what
+characters are considered C<isxdigit> (unlikely, but still possible).
+Does not work on Unicode characters code point 256 or higher.
+Consider using regular expressions and the C</[[:xdigit:]]/>
+construct instead, or simply C</[0-9a-f]/i>.
=item kill
-This is identical to Perl's builtin C<kill()> function.
+This is identical to Perl's builtin C<kill()> function for sending
+signals to processes (often to terminate them), see L<perlfunc/kill>.
=item labs
+(For returning absolute values of long integers.)
labs() is C-specific, see L<perlfunc/abs> instead.
=item ldexp
-This is identical to the C function C<ldexp()>.
+This is identical to the C function C<ldexp()>
+for multiplying floating point numbers with powers of two.
+
+ $x_quadrupled = POSIX::ldexp($x, 2);
=item ldiv
+(For computing dividends of long integers.)
ldiv() is C-specific, use C</> and C<int()> instead.
=item link
-This is identical to Perl's builtin C<link()> function.
+This is identical to Perl's builtin C<link()> function
+for creating hard links into files, see L<perlfunc/link>.
=item localeconv
=item localtime
-This is identical to Perl's builtin C<localtime()> function.
+This is identical to Perl's builtin C<localtime()> function for
+converting seconds since the epoch to a date see L<perlfunc/localtime>.
=item log
or
- sub log10 { log($_[0]) / 2.30258509299405 }
+ sub log10 { log($_[0]) / 2.30258509299405 }
or
=item mblen
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
+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
+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
+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.
This is identical to the C function C<perror()>, which outputs to the
standard error stream the specified message followed by ": " and the
current error string. Use the C<warn()> function and the C<$!>
-variable instead, see L<perlfunc/warn> and L<perlvar>.
+variable instead, see L<perlfunc/warn> and L<perlvar/$ERRNO>.
=item pipe
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>.
=item raise
Sends the specified signal to the current process.
-See also L<perlfunc/kill> and the C<$$> in L<perlvar>.
+See also L<perlfunc/kill> and the C<$$> in L<perlvar/$PID>.
=item rand
-rand() is non-portable, see L<perlfunc/rand> instead.
+C<rand()> is non-portable, see L<perlfunc/rand> instead.
=item read
=item scanf
-scanf() is C-specific--use <> and regular expressions instead,
+scanf() is C-specific, use E<lt>E<gt> and regular expressions instead,
see L<perlre>.
=item setgid
-Sets the real group id for this process.
+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/$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 setjmp
The following will set the LC_CTYPE behaviour according to the locale
environment variables (the second argument C<"">).
-Please see your systems L<setlocale(3)> documentation for the locale
+Please see your systems C<setlocale(3)> documentation for the locale
environment variables' meaning or consult L<perllocale>.
$loc = setlocale( LC_CTYPE, "" );
=item setpgid
-This is similar to the C function C<setpgid()>.
+This is similar to the C function C<setpgid()> for
+setting the process group identifier of the current process.
Returns C<undef> on failure.
=item setsid
-This is identical to the C function C<setsid()>.
+This is identical to the C function C<setsid()> for
+setting the session identifier of the current process.
=item setuid
-Sets the real user id for this process.
+Sets the real user identifier and the effective user identifier for
+this process. Similar to assigning a value to the Perl's builtin
+C<$E<lt>> variable, see L<perlvar/$UID>, except that the latter
+will change only the real user identifier.
=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 identical to Perl's builtin C<sin()> function
for returning the sine of the numerical argument,
-see L<perlfunc/sin>.
+see L<perlfunc/sin>. See also L<Math::Trig>.
=item sinh
This is identical to the C function C<sinh()>
for returning the hyperbolic sine of the numerical argument.
+See also L<Math::Trig>.
=item sleep
-This is 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>.
+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 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 sprintf
=item stat
-This is identical to Perl's builtin C<stat()> function.
+This is identical to Perl's builtin C<stat()> function
+for returning information about files and directories.
=item strcat
=item strcmp
-strcmp() is C-specific, use C<eq> instead, see L<perlop>.
+strcmp() is C-specific, use C<eq> or C<cmp> instead, see L<perlop>.
=item strcoll
=item strcspn
-strcspn() is C-specific, use regular expressions instead.
+strcspn() is C-specific, use regular expressions instead,
+see L<perlre>.
=item strerror
Returns the error string for the specified errno.
-Identical to the string form of the C<$!>, see L<perlvar>.
+Identical to the string form of the C<$!>, see L<perlvar/$ERRNO>.
=item strftime
year (C<year>) is given in years since 1900. I.e., the year 1995 is 95; the
year 2001 is 101. Consult your system's C<strftime()> manpage for details
about these and the other arguments.
+
If you want your code to be portable, your format (C<fmt>) argument
should use only the conversion specifiers defined by the ANSI C
-standard. These are C<aAbBcdHIjmMpSUwWxXyYZ%>.
-The given arguments are made consistent
-as though by calling C<mktime()> before calling your system's
-C<strftime()> function, except that the C<isdst> value is not affected.
+standard (C89, to play safe). These are C<aAbBcdHIjmMpSUwWxXyYZ%>.
+But even then, the B<results> of some of the conversion specifiers are
+non-portable. For example, the specifiers C<aAbBcpZ> change according
+to the locale settings of the user, and both how to set locales (the
+locale names) and what output to expect are non-standard.
+The specifier C<c> changes according to the timezone settings of the
+user and the timezone computation rules of the operating system.
+The C<Z> specifier is notoriously unportable since the names of
+timezones are non-standard. Sticking to the numeric specifiers is the
+safest route.
+
+The given arguments are made consistent as though by calling
+C<mktime()> before calling your system's C<strftime()> function,
+except that the C<isdst> value is not affected.
The string for Tuesday, December 12, 1995.
=item strpbrk
-strpbrk() is C-specific, use regular expressions instead, see L<perlre>.
+strpbrk() is C-specific, use regular expressions instead,
+see L<perlre>.
=item strrchr
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.
=item tan
This is identical to the C function C<tan()>, returning the
-tangent of the numerical argument.
+tangent of the numerical argument. See also L<Math::Trig>.
=item tanh
This is identical to the C function C<tanh()>, returning the
-hyperbolic tangent of the numerical argument.
+hyperbolic tangent of the numerical argument. See also L<Math::Trig>.
=item tcdrain
=item tcflush
This is similar to the C function C<tcflush()> for flushing
-the I/O buffers of its argumeny stream.
+the I/O buffers of its argument stream.
Returns C<undef> on failure.
=item tcgetpgrp
This is identical to the C function C<tcgetpgrp()> for returning the
-process group id of the foreground process group of the controlling
+process group identifier of the foreground process group of the controlling
terminal.
=item tcsendbreak
=item tcsetpgrp
This is similar to the C function C<tcsetpgrp()> for setting the
-process group id of the foreground process group of the controlling
+process group identifier of the foreground process group of the controlling
terminal.
Returns C<undef> on failure.
=item tmpfile
-Use method C<IO::File::new_tmpfile()> instead.
+Use method C<IO::File::new_tmpfile()> instead, or see L<File::Temp>.
=item tmpnam
$tmpfile = POSIX::tmpnam();
-See also the L<File::Temp> module.
+For security reasons, which are probably detailed in your system's
+documentation for the C library tmpnam() function, this interface
+should not be used; instead see L<File::Temp>.
=item tolower
Get name of current operating system.
- ($sysname, $nodename, $release, $version, $machine ) = POSIX::uname();
+ ($sysname, $nodename, $release, $version, $machine) = POSIX::uname();
+
+Note that the actual meanings of the various fields are not
+that well standardized, do not expect any great portability.
+The C<$sysname> might be the name of the operating system,
+the C<$nodename> might be the name of the host, the C<$release>
+might be the (major) release number of the operating system,
+the C<$version> might be the (minor) release number of the
+operating system, and the C<$machine> might be a hardware identifier.
+Maybe.
=item ungetc
Wait for a child process to change state. This is identical to Perl's
builtin C<waitpid()> function, see L<perlfunc/waitpid>.
- $pid = POSIX::waitpid( -1, &POSIX::WNOHANG );
+ $pid = POSIX::waitpid( -1, POSIX::WNOHANG );
print "status = ", ($? / 256), "\n";
=item wcstombs
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
+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
+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
+=over 8
+
+=item handler
+
+=item mask
+
+=item flags
+
+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::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
=over 8
Obtain the attributes for stdin.
+ $termios->getattr( 0 ) # Recommended for clarity.
$termios->getattr()
Obtain the attributes for stdout.
=item Constants
-_SC_ARG_MAX _SC_CHILD_MAX _SC_CLK_TCK _SC_JOB_CONTROL _SC_NGROUPS_MAX _SC_OPEN_MAX _SC_SAVED_IDS _SC_STREAM_MAX _SC_TZNAME_MAX _SC_VERSION
+_SC_ARG_MAX _SC_CHILD_MAX _SC_CLK_TCK _SC_JOB_CONTROL _SC_NGROUPS_MAX _SC_OPEN_MAX _SC_PAGESIZE _SC_SAVED_IDS _SC_STREAM_MAX _SC_TZNAME_MAX _SC_VERSION
=back
WNOHANG WUNTRACED
+=over 16
+
+=item WNOHANG
+
+Do not suspend the calling process until a child process
+changes state but instead return immediately.
+
+=item WUNTRACED
+
+Catch stopped child processes.
+
+=back
+
=item Macros
WIFEXITED WEXITSTATUS WIFSIGNALED WTERMSIG WIFSTOPPED WSTOPSIG
-=back
+=over 16
+
+=item WIFEXITED
+
+WIFEXITED($?) returns true if the child process exited normally
+(C<exit()> or by falling off the end of C<main()>)
+
+=item WEXITSTATUS
+
+WEXITSTATUS($?) returns the normal exit status of the child process
+(only meaningful if WIFEXITED($?) is true)
-=head1 CREATION
+=item WIFSIGNALED
-This document generated by ./mkposixman.PL version 19960129.
+WIFSIGNALED($?) returns true if the child process terminated because
+of a signal
+
+=item WTERMSIG
+
+WTERMSIG($?) returns the signal the child process terminated for
+(only meaningful if WIFSIGNALED($?) is true)
+
+=item WIFSTOPPED
+
+WIFSTOPPED($?) returns true if the child process is currently stopped
+(can happen only if you specified the WUNTRACED flag to waitpid())
+
+=item WSTOPSIG
+
+WSTOPSIG($?) returns the signal the child process was stopped for
+(only meaningful if WIFSTOPPED($?) is true)
+
+=back
+
+=back
projects / p5sagit/p5-mst-13.2.git / blobdiff