=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 or almost 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.
The notation C indicates functions that were added in the ISO/IEC
9899:1999 version of the C language standard. Some may not be available
on your system if it adheres to an earlier standard. Attempts to use
any missing one will result in a fatal runtime error message.
=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 (except that C<:abs> must be provided
an explicit value (rather than relying on an implicit C):
$absolute_value = POSIX::abs(42); # good
$absolute_value = POSIX::abs(); # throws exception
=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>. Added in Perl v5.22.
=item C
This is identical to Perl's builtin C function, either for arming or
disarming the C timer, except that C<:alarm> must be provided
an explicit value (rather than relying on an implicit C):
POSIX::alarm(3) # good
POSIX::alarm() # throws exception
=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.
Note the result is always in English. Use C> instead to
get a result suitable for the current locale. That function's C
format yields the locale's preferred representation.
=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>. Added in Perl v5.22.
=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>. Added in Perl v5.22.
=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]. Added in Perl v5.22.
=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 -- with the
exception that C<:chdir> must be provided an explicit value (rather
than relying on an implicit C):
$rv = POSIX::chdir('path/to/dir'); # good
$rv = POSIX::chdir(); # throws exception
=item C
This is identical to Perl's builtin C function, allowing
one to change file and directory permissions -- see L -- with
the exception that C<:chmod> can only change one file at a time
(rather than a list of files):
$c = chmod 0664, $file1, $file2; # good
$c = POSIX::chmod 0664, $file1; # throws exception
$c = POSIX::chmod 0664, $file1, $file2; # throws exception
As with the built-in C, C may be a filename or a file
handle.
=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]. Added in Perl v5.22.
$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 [POSIX.1-1988]
Get the login name of the owner of the current process.
$name = POSIX::cuserid();
Note: this function has not been specified by POSIX since 1990 and is included
only for backwards compatibility. New code should use L|perlfunc/getlogin> instead.
=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]. Added in Perl v5.22.
=item C
The complementary error function [C99]. Added in Perl v5.22.
=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].
Added in Perl v5.22.
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].
Added in Perl v5.22.
=item C
Returns the current floating point rounding mode, one of
FE_TONEAREST FE_TOWARDZERO FE_UPWARD FE_DOWNWARD
C is like L, C is like L [C99].
Added in Perl v5.22.
=item C
Sets the floating point rounding mode, see L [C99]. Added in
Perl v5.22.
=item C
"Fused multiply-add", S>, possibly faster (and less lossy)
than the explicit two operations [C99]. Added in Perl v5.22.
my $fused = POSIX::fma($x, $y, $z);
=item C
Maximum of C and C, except when either is C, returns the other [C99].
Added in Perl v5.22.
my $min = POSIX::fmax($x, $y);
=item C
Minimum of C and C, except when either is C, returns the other [C99].
Added in Perl v5.22.
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.
Added in Perl v5.22.
=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