DESCRIPTION

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.

This document gives a condensed list of the features available in the POSIX
module. Consult your operating system's manpages for general information on
most features. Consult perlfunc for functions which are noted as being
identical to Perl's builtin functions.

The first section describes POSIX functions from the 1003.1 specification.
The second section describes some classes for signal objects, TTY objects,
and other miscellaneous objects. The remaining sections list various
constants and macros in an organization which roughly follows IEEE Std
1003.1b-1993.

CAVEATS

Everything is exported by default (with a handful of exceptions).
This is an unfortunate backwards compatibility feature and its use is
strongly discouraged.
You should either prevent the exporting (by saying usePOSIX();
,
as usual) and then use fully qualified names (e.g. POSIX::SEEK_END
),
or give an explicit import list.
If you do neither and opt for the default (as in usePOSIX;
), you
will import hundreds and hundreds of symbols into your namespace.

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
aren't implemented, and suggest using the Perl equivalent, should one
exist. For example, trying to access the setjmp()
call will elicit the
message "setjmp()isC-specific:useeval{}instead
".

Furthermore, some evil vendors will claim 1003.1 compliance, but in fact
are not so: they will not pass the PCTS (POSIX Compliance Test Suites).
For example, one vendor may not define EDEADLK
, or the semantics of the
errno values set by open(2) might not be quite right. Perl does not
attempt to verify POSIX compliance. That means you can currently
successfully say "use POSIX", and then later in your program you find
that your vendor has been lax and there's no usable ICANON
macro after
all. This could be construed to be a bug.

FUNCTIONS

_exit

This is identical to the C function _exit()
. It exits the program
immediately which means among other things buffered I/O is not flushed.

Note that when using threads and in Linux this is 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.

abort

This is identical to the C function abort()
. It terminates the
process with a SIGABRT
signal unless caught by a signal handler or
if the handler does not return normally (it e.g. does a longjmp
).

telling the class of the argument [C99]. FP_INFINITE
is positive
or negative infinity, FP_NAN
is not-a-number. FP_SUBNORMAL
means subnormal numbers (also known as denormals), very small numbers
with low precision. FP_ZERO
is zero. FP_NORMAL
is all the rest.

This is identical to Perl's builtin getpwuid() function for
returning user entries by user identifiers, see getpwuid.

gets

Returns one line from STDIN
, similar to <>, also known
as the readline() function, see readline.

NOTE: if you have C programs that still use gets()
, be very
afraid. The gets()
function is a source of endless grief because
it has no buffer overrun checks. It should never be used. The
fgets()
function should be preferred instead.

This is identical to Perl's builtin kill() function for sending
signals to processes (often to terminate them), see kill.

labs

Not implemented. (For returning absolute values of long integers.)
labs()
is C-specific, see abs instead.

lchown

This is identical to the C function, except the order of arguments is
consistent with Perl's builtin chown() with the added restriction
of only one path, not a list of paths. Does the same thing as the
chown() function but changes the owner of a symbolic link instead
of the file the symbolic link points to.

POSIX::lchown($uid,$gid,$file_path);

ldexp

This is identical to the C function ldexp()
for multiplying floating point numbers with powers of two.

$x_quadrupled = POSIX::ldexp($x,2);

ldiv

Not implemented. (For computing dividends of long integers.)
ldiv()
is C-specific, use / and int() instead.

This is identical to Perl's builtin link() function
for creating hard links into files, see link.

localeconv

Get numeric formatting information. Returns a reference to a hash
containing the current underlying locale's formatting values. Users of this function
should also read perllocale, which provides a comprehensive
discussion of Perl locale handling, including
a section devoted to this function.

Here is how to query the database for the de (Deutsch or German) locale.

This is identical to Perl's builtin mkdir() function
for creating directories, see mkdir.

mkfifo

This is similar to the C function mkfifo()
for creating
FIFO special files.

if (mkfifo($path, $mode)) { ....

Returns undef on failure. The $mode
is similar to the
mode of mkdir(), see mkdir, though for mkfifo
you must specify the $mode
.

mktime

Convert date/time info to a calendar time.

Synopsis:

mktime(sec,min,hour,mday,mon,year,wday = 0,

yday = 0,isdst = -1)

The month (mon
), weekday (wday
), and yearday (yday
) begin at zero,
i.e., January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1. The
year (year
) is given in years since 1900; i.e., the year 1995 is 95; the
year 2001 is 101. Consult your system's mktime()
manpage for details
about these and the other arguments.

With an argument, can be used to generate a NaN with payload.
The argument is first interpreted as a floating point number,
but then any fractional parts are truncated (towards zero),
and the value is interpreted as an unsigned integer.
The bits of this integer are stored in the unused bits of the NaN.

The result has a dual nature: it is a NaN, but it also carries
the integer inside it. The integer can be retrieved with getpayload.
Note, though, that the payload is not propagated, not even on copies,
and definitely not in arithmetic operations.

How many bits fit in the NaN depends on what kind of floating points
are being used, but on the most common platforms (64-bit IEEE 754,
or the x86 80-bit long doubles) there are 51 and 61 bits available,
respectively. (There would be 52 and 62, but the quiet/signaling
bit of NaNs takes away one.) However, because of the floating-point-to-
integer-and-back conversions, please test carefully whether you get back
what you put in. If your integers are only 32 bits wide, you probably
should not rely on more than 32 bits of payload.

Whether a "signaling" NaN is in any way different from a "quiet" NaN,
depends on the platform. Also note that the payload of the default
NaN (no argument to nan()) is not necessarily zero, use setpayload
to explicitly set the payload. On some platforms like the 32-bit x86,
(unless using the 80-bit long doubles) the signaling bit is not supported
at all.

This is similar to the C function nice()
, for changing
the scheduling preference of the current process. Positive
arguments mean a more polite process, negative values a more
needy process. Normal (non-root) user processes can only change towards
being more polite.

This is identical to the C function perror()
, which outputs to the
standard error stream the specified message followed by ": "
and the
current error string. Use the warn() function and the $!
variable instead, see warn and $ERRNO in perlvar.

Not implemented. scanf()
is C-specific, use <> and regular expressions instead,
see perlre.

setgid

Sets the real group identifier and the effective group identifier for
this process. Similar to assigning a value to the Perl's builtin
$)
variable, see $EGID in perlvar, 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.

setjmp

Not implemented. setjmp()
is C-specific: use eval{}
instead,
see eval.

setlocale

WARNING! Do NOT use this function in a thread. The locale
will change in all other threads at the same time, and should your
thread get paused by the operating system, and another started, that
thread will not have the locale it is expecting. On some platforms,
there can be a race leading to segfaults if two threads call this
function nearly simultaneously.

Modifies and queries the program's underlying locale. Users of this
function should read perllocale, whch provides a comprehensive
discussion of Perl locale handling, knowledge of which is necessary to
properly use this function. It contains
a section devoted to this function.
The discussion here is merely a summary reference for setlocale()
.
Note that Perl itself is almost entirely unaffected by the locale
except within the scope of "use locale"
. (Exceptions are listed
in Not within the scope of use locale in perllocale.)

The following will set the traditional UNIX system locale behavior
(the second argument "C"
).

$loc = setlocale(LC_ALL,"C");

The following will query the current LC_CTYPE
category. (No second
argument means 'query'.)

$loc = setlocale(LC_CTYPE);

The following will set the LC_CTYPE
behaviour according to the locale
environment variables (the second argument ""
).
Please see your system's setlocale(3)
documentation for the locale
environment variables' meaning or consult perllocale.

$loc = setlocale(LC_CTYPE,"");

The following will set the LC_COLLATE
behaviour to Argentinian
Spanish. NOTE: The naming and availability of locales depends on
your operating system. Please consult perllocale for how to find
out which locales are available in your system.

This is identical to the C function setsid()
for
setting the session identifier of the current process.

setuid

Sets the real user identifier and the effective user identifier for
this process. Similar to assigning a value to the Perl's builtin
$<
variable, see $UID in perlvar, except that the latter
will change only the real user identifier.

sigaction

Detailed signal management. This uses POSIX::SigAction
objects for
the action
and oldaction
arguments (the oldaction can also be
just a hash reference). Consult your system's sigaction
manpage
for details, see also POSIX::SigRt
.

Synopsis:

sigaction(signal,action,oldaction = 0)

Returns undef on failure. The 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:

signothesignalnumber

errnotheerrornumber

code if thisiszero or less,thesignalwassentby

auserprocess and theuid and pidmakesense,

otherwisethesignalwassentbythekernel

The constants for specific code
values can be imported individually
or using the :signal_h_si_code
tag.

The following are also defined by POSIX/SUSv3, but unfortunately
not very widely implemented:

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
sigaction
and possibly also siginfo
documentation.

This is functionally identical to Perl's builtin sleep() function
for suspending the execution of the current for process for certain
number of seconds, see sleep. There is one significant
difference, however: POSIX::sleep()
returns the number of
unslept seconds, while the CORE::sleep()
returns the
number of slept seconds.

Not implemented. strcspn()
is C-specific, use regular expressions instead,
see perlre.

strerror

Returns the error string for the specified errno.
Identical to the string form of $!
, see $ERRNO in perlvar.

strftime

Convert date and time information to string. Returns the string.

Synopsis:

strftime(fmt,sec,min,hour,mday,mon,year,

wday = -1,yday = -1,isdst = -1)

The month (mon
), weekday (wday
), and yearday (yday
) begin at zero,
i.e., January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1. The
year (year
) is given in years since 1900, i.e., the year 1995 is 95; the
year 2001 is 101. Consult your system's strftime()
manpage for details
about these and the other arguments.

If you want your code to be portable, your format (fmt
) argument
should use only the conversion specifiers defined by the ANSI C
standard (C89, to play safe). These are aAbBcdHIjmMpSUwWxXyYZ%
.
But even then, the results of some of the conversion specifiers are
non-portable. For example, the specifiers 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
changes according to the timezone settings of the
user and the timezone computation rules of the operating system.
The 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
mktime()
before calling your system's strftime()
function,
except that the isdst
value is not affected.

String to double translation. Returns the parsed number and the number
of characters in the unparsed portion of the string. Truly
POSIX-compliant systems set $!
($ERRNO
) to indicate a translation
error, so clear $!
before calling strtod
. However, non-POSIX systems
may not check for overflow, and therefore will never set $!
.

strtod
respects any POSIX setlocale()LC_TIME
settings,
regardless of whether or not it is called from Perl code that is within
the scope of uselocale
.

Not implemented. strtok()
is C-specific, use regular expressions instead, see
perlre, or split.

strtol

String to (long) integer translation. Returns the parsed number and
the number of characters in the unparsed portion of the string. Truly
POSIX-compliant systems set $!
($ERRNO
) to indicate a translation
error, so clear $!
before calling strtol
. However, non-POSIX systems
may not check for overflow, and therefore will never set $!
.

strtol
should respect any POSIX setlocale() settings.

To parse a string $str
as a number in some base $base
use

$! = 0;

($num,$n_unparsed) = POSIX::strtol($str,$base);

The base should be zero or between 2 and 36, inclusive. When the base
is zero or omitted strtol
will use the string itself to determine the
base: a leading "0x" or "0X" means hexadecimal; a leading "0" means
octal; any other leading characters mean decimal. Thus, "1234" is
parsed as a decimal number, "01234" as an octal number, and "0x1234"
as a hexadecimal number.

The times() function returns elapsed realtime since some point in the past
(such as system startup), user and system times for this process, and user
and system times used by child processes. All times are returned in clock
ticks.

Not implemented. Use method IO::File::new_tmpfile()
instead, or see File::Temp.

tmpnam

Returns a name for a temporary file.

$tmpfile = POSIX::tmpnam();

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 File::Temp.

tolower

This is identical to the C function, except that it can apply to a single
character or to a whole string, and currently operates as if the locale
always is "C". Consider using the lc() function, see lc,
see lc, or the equivalent \L
operator inside doublequotish
strings.

toupper

This is similar to the C function, except that it can apply to a single
character or to a whole string, and currently operates as if the locale
always is "C". Consider using the uc() function, see uc,
or the equivalent \U
operator inside doublequotish strings.

This is identical to Perl's builtin umask() function
for setting (and querying) the file creation permission mask,
see umask.

uname

Get name of current operating system.

($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 $sysname
might be the name of the operating system,
the $nodename
might be the name of the host, the $release
might be the (major) release number of the operating system,
the $version
might be the (minor) release number of the
operating system, and the $machine
might be a hardware identifier.
Maybe.

CLASSES

POSIX::SigAction

new

Creates a new POSIX::SigAction
object which corresponds to the C
structsigaction
. 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 POSIX::SigSet
object, it
defaults to the empty set. The third parameter contains the
sa_flags
, it defaults to 0.

$sigset = POSIX::SigSet->new(SIGINT,SIGQUIT);

$sigaction = POSIX::SigAction->new(

\&handler,$sigset,&POSIX::SA_NOCLDSTOP

);

This POSIX::SigAction
object is intended for use with the POSIX::sigaction()
function.

handler

mask

flags

accessor functions to get/set the values of a SigAction object.

$sigset = $sigaction->mask;

$sigaction->flags(&POSIX::SA_RESTART);

safe

accessor function for the "safe signals" flag of a SigAction object; see
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 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 POSIX::sigaction()
:

sigaction(SIGINT,$new_action,$old_action);

if ($old_action->safe){

# previous SIGINT handler used safe signals

}

POSIX::SigRt

%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 delete and exists on the elements, and use
scalar on the %POSIX::SIGRT
to find out how many POSIX realtime
signals there are available (SIGRTMAX - SIGRTMIN + 1
, the SIGRTMAX
is
a valid POSIX realtime signal).

The flags default to zero, if you want something different you can
either use local on $POSIX::SigRt::SIGACTION_FLAGS
, or you can
derive from POSIX::SigRt and define your own new()
(the tied hash
STORE method of the %SIGRT
calls 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).

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.

SIGRTMIN

Return the minimum POSIX realtime signal number available, or undef
if no POSIX realtime signals are available.

SIGRTMAX

Return the maximum POSIX realtime signal number available, or undef
if no POSIX realtime signals are available.

POSIX::SigSet

new

Create a new SigSet object. This object will be destroyed automatically
when it is no longer needed. Arguments may be supplied to initialize the
set.

POSIX::Termios

new

Create a new Termios object. This object will be destroyed automatically
when it is no longer needed. A Termios object corresponds to the termios
C struct. new()
mallocs a new one, getattr()
fills it from a file descriptor,
and setattr()
sets a file descriptor's parameters to match Termios' contents.