=head1 NAME
POSIX - Perl interface to IEEE Std 1003.1
=head1 SYNOPSIS
use POSIX ();
use POSIX qw(setsid);
use POSIX qw(:errno_h :fcntl_h);
printf "EINTR is %d\n", EINTR;
$sess_id = POSIX::setsid();
$fd = POSIX::open($path, O_CREAT|O_EXCL|O_WRONLY, 0644);
# note: that's a filedescriptor, *NOT* a filehandle
=head1 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 L 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.
=head1 CAVEATS
I (with a handful of exceptions).
This is an unfortunate backwards compatibility feature and its use is
B>.
You should either prevent the exporting (by saying S>,
as usual) and then use fully qualified names (e.g. C<:seek_end>),
or give an explicit import list.
If you do neither and opt for the default (as in S>), you
will import I 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 C call will elicit the
message "C".
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 C, or the semantics of the
errno values set by C 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 C macro after
all. This could be construed to be a bug.
=head1 FUNCTIONS
=over 8
=item C<_exit>
This is identical to the C function C<_exit>. It exits the program
immediately which means among other things buffered I/O is B flushed.
Note that when using threads and in Linux this is B 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 C
This is identical to the C function C. It terminates the
process with a C signal unless caught by a signal handler or
if the handler does not return normally (it e.g. does a C).
=item C
This is identical to Perl's builtin C function, returning
the absolute value of its numerical argument.
=item C
Determines the accessibility of a file.
if( POSIX::access( "/", &POSIX::R_OK ) ){
print "have read permission\n";
}
Returns C on failure. Note: do not use C for
security purposes. Between the C call and the operation
you are preparing for the permissions might change: a classic
I.
=item C
This is identical to the C function C, returning
the arcus cosine of its numerical argument. See also L<:trig>.
=item C
This is identical to the C function C, returning the
hyperbolic arcus cosine of its numerical argument [C99]. See also
L<:trig>.
=item C
This is identical to Perl's builtin C function,
either for arming or disarming the C timer.
=item C
This is identical to the C function C. It returns
a string of the form
"Fri Jun 2 18:22:13 2000\n\0"
and it is called thusly
$asctime = asctime($sec, $min, $hour, $mday, $mon,
$year, $wday, $yday, $isdst);
The C is zero-based: January equals C. The C is
1900-based: 2001 equals C. C and C default to zero
(and are usually ignored anyway), and C defaults to -1.
=item C
This is identical to the C function C, returning
the arcus sine of its numerical argument. See also L<:trig>.
=item C
This is identical to the C function C, returning the
hyperbolic arcus sine of its numerical argument [C99]. See also
L<:trig>.
=item C
Unimplemented, but you can use L and the L module
to achieve similar things.
=item C
This is identical to the C function C, returning the
arcus tangent of its numerical argument. See also L<:trig>.
=item C
This is identical to the C function C, returning the
hyperbolic arcus tangent of its numerical argument [C99]. See also
L<:trig>.
=item C
This is identical to Perl's builtin C function, returning
the arcus tangent defined by its two numerical arguments, the I
coordinate and the I coordinate. See also L<:trig>.
=item C
Not implemented. C is C-specific: use C instead, see L.
=item C
Not implemented. C is C-specific. Perl converts strings to numbers transparently.
If you need to force a scalar to a number, add a zero to it.
=item C
Not implemented. C is C-specific. Perl converts strings to numbers transparently.
If you need to force a scalar to a number, add a zero to it.
If you need to have just the integer part, see L.
=item C
Not implemented. C is C-specific. Perl converts strings to numbers transparently.
If you need to force a scalar to a number, add a zero to it.
If you need to have just the integer part, see L.
=item C
C not supplied. For doing binary search on wordlists,
see L<:dict>.
=item C
Not implemented. C is C-specific. Perl does memory management transparently.
=item C
The cube root [C99].
=item C
This is identical to the C function C, returning the smallest
integer value greater than or equal to the given numerical argument.
=item C
This is identical to Perl's builtin C function, allowing
one to change the working (default) directory, see L.
=item C
This is identical to Perl's builtin C function, allowing
one to change file and directory permissions, see L.
=item C
This is identical to Perl's builtin C function, allowing one
to change file and directory owners and groups, see L.
=item C
Not implemented. Use the method C<:handle::clearerr> instead, to reset the error
state (if any) and EOF state (if any) of the given stream.
=item C
This is identical to the C function C, returning the
amount of spent processor time in microseconds.
=item C
Close the file. This uses file descriptors such as those obtained by calling
C<:open>.
$fd = POSIX::open( "foo", &POSIX::O_RDONLY );
POSIX::close( $fd );
Returns C on failure.
See also L.
=item C
This is identical to Perl's builtin C function for closing
a directory handle, see L.
=item C
This is identical to Perl's builtin C function, for returning
the cosine of its numerical argument, see L.
See also L<:trig>.
=item C
This is identical to the C function C, for returning
the hyperbolic cosine of its numeric argument. See also L<:trig>.
=item C
Returns C but with the sign of C [C99].
$x_with_sign_of_y = POSIX::copysign($x, $y);
See also L.
=item C
Create a new file. This returns a file descriptor like the ones returned by
C<:open>. Use C<:close> to close the file.
$fd = POSIX::creat( "foo", 0611 );
POSIX::close( $fd );
See also L and its C flag.
=item C
Generates the path name for the controlling terminal.
$path = POSIX::ctermid();
=item C
This is identical to the C function C and equivalent
to C, see L and L.
=item C
Get the login name of the owner of the current process.
$name = POSIX::cuserid();
=item C
This is identical to the C function C, for returning
the time difference (in seconds) between two times (as returned
by C.
=item C
Not implemented. C
is C-specific, use L on the usual C> division and
the modulus C.
=item C
This is similar to the C function C, for duplicating a file
descriptor.
This uses file descriptors such as those obtained by calling
C<:open>.
Returns C on failure.
=item C
This is similar to the C function C, for duplicating a file
descriptor to an another known file descriptor.
This uses file descriptors such as those obtained by calling
C<:open>.
Returns C on failure.
=item C
The error function [C99].
=item C
The complementary error function [C99].
=item C
Returns the value of errno.
$errno = POSIX::errno();
This identical to the numerical values of the C, see L.
=item C
Not implemented. C is C-specific, see L.
=item C
Not implemented. C is C-specific, see L.
=item C
Not implemented. C is C-specific, see L.
=item C
Not implemented. C is C-specific, see L.
=item C
Not implemented. C is C-specific, see L.
=item C
Not implemented. C is C-specific, see L.
=item C
This is identical to Perl's builtin C function for exiting the
program, see L.
=item C
This is identical to Perl's builtin C function for
returning the exponent (I-based) of the numerical argument,
see L.
=item C
Equivalent to C, but more precise for small argument values [C99].
See also L.
=item C
This is identical to Perl's builtin C function for returning
the absolute value of the numerical argument, see L.
=item C
Not implemented. Use method C<:handle::close> instead, or see L.
=item C
This is identical to Perl's builtin C function,
see L.
=item C
Not implemented. Use method C<:handle::new_from_fd> instead, or see L.
=item C
Not implemented. Use method C<:handle::eof> instead, or see L.
=item C
Not implemented. Use method C<:handle::error> instead.
=item C
Not implemented. Use method C<:handle::flush> instead.
See also C>.
=item C
Not implemented. Use method C<:handle::getc> instead, or see L.
=item C
Not implemented. Use method C<:seekable::getpos> instead, or see L.
=item C
Not implemented. Use method C<:handle::gets> instead. Similar to EE, also known
as L.
=item C
Not implemented. Use method C<:handle::fileno> instead, or see L.
=item C
This is identical to the C function C, returning the largest
integer value less than or equal to the numerical argument.
=item C
"Positive difference", S> if S y>>, zero otherwise [C99].
=item C
Returns the current floating point rounding mode, one of
FE_TONEAREST FE_TOWARDZERO FE_UPWARD FE_UPWARD
C is like L, C is like L [C99].
=item C
Sets the floating point rounding mode, see L [C99].
=item C
"Fused multiply-add", S>, possibly faster (and less lossy)
than the explicit two operations [C99].
my $fused = POSIX::fma($x, $y, $z);
=item C
Maximum of C and C, except when either is C, returns the other [C99].
my $min = POSIX::fmax($x, $y);
=item C
Minimum of C and C, except when either is C, returns the other [C99].
my $min = POSIX::fmin($x, $y);
=item C
This is identical to the C function C.
$r = fmod($x, $y);
It returns the remainder S>, where S>.
The C has the same sign as C and magnitude (absolute value)
less than the magnitude of C.
=item C
Not implemented. Use method C<:file::open> instead, or see L.
=item C
This is identical to Perl's builtin C function
for duplicating the current process, see L
and L if you are in Windows.
=item C
Retrieves the value of a configurable limit on a file or directory. This
uses file descriptors such as those obtained by calling C<:open>.
The following will determine the maximum length of the longest allowable
pathname on the filesystem which holds F.
$fd = POSIX::open( "/var/foo", &POSIX::O_RDONLY );
$path_max = POSIX::fpathconf($fd, &POSIX::_PC_PATH_MAX);
Returns C on failure.
=item C
Returns one of
FP_NORMAL FP_ZERO FP_SUBNORMAL FP_INFINITE FP_NAN
telling the class of the argument [C99]. C is positive
or negative infinity, C is not-a-number. C
means subnormal numbers (also known as denormals), very small numbers
with low precision. C is zero. C is all the rest.
=item C
Not implemented. C is C-specific, see L instead.
=item C
Not implemented. C is C-specific, see L instead.
=item C
Not implemented. C is C-specific, see L instead.
=item C
Not implemented. C is C-specific, see L instead.
=item C
Not implemented. C is C-specific. Perl does memory management transparently.
=item C
Not implemented. C is C-specific, see L instead.
=item C
Return the mantissa and exponent of a floating-point number.
($mantissa, $exponent) = POSIX::frexp( 1.234e56 );
=item C
Not implemented. C is C-specific, use EE and regular expressions instead.
=item C
Not implemented. Use method C<:seekable::seek> instead, or see L