NAME

POSIX - Perl interface to IEEE Std 1003.1

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

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. Things which are #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.

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.

NOTE

The POSIX module is probably the most complex Perl module supplied with the standard distribution. It incorporates autoloading, namespace games, and dynamic loading of code that's in Perl, C, or both. It's a great source of wisdom.

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 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() is C-specific: use eval {} 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().

abort

This is identical to the C function abort().

abs

This is identical to Perl's builtin abs() function.

access

Determines the accessibility of a file.

if( POSIX::access( "/", &POSIX::R_OK ) ){
	print "have read permission\n";
}

Returns undef on failure.

acos

This is identical to the C function acos().

alarm

This is identical to Perl's builtin alarm() function.

asctime

This is identical to the C function asctime().

asin

This is identical to the C function asin().

assert

Unimplemented.

atan

This is identical to the C function atan().

atan2

This is identical to Perl's builtin atan2() function.

atexit

atexit() is C-specific: use END {} instead.

atof

atof() is C-specific.

atoi

atoi() is C-specific.

atol

atol() is C-specific.

bsearch

bsearch() not supplied.

calloc

calloc() is C-specific.

ceil

This is identical to the C function ceil().

chdir

This is identical to Perl's builtin chdir() function.

chmod

This is identical to Perl's builtin chmod() function.

chown

This is identical to Perl's builtin chown() function.

clearerr

Use method IO::Handle::clearerr() instead.

clock

This is identical to the C function clock().

close

Close the file. This uses file descriptors such as those obtained by calling POSIX::open.

$fd = POSIX::open( "foo", &POSIX::O_RDONLY );
POSIX::close( $fd );

Returns undef on failure.

closedir

This is identical to Perl's builtin closedir() function.

cos

This is identical to Perl's builtin cos() function.

cosh

This is identical to the C function cosh().

creat

Create a new file. This returns a file descriptor like the ones returned by POSIX::open. Use POSIX::close to close the file.

$fd = POSIX::creat( "foo", 0611 );
POSIX::close( $fd );

ctermid

Generates the path name for the controlling terminal.

$path = POSIX::ctermid();

ctime

This is identical to the C function ctime().

cuserid

Get the character login name of the user.

$name = POSIX::cuserid();

difftime

This is identical to the C function difftime().

div

div() is C-specific.

dup

This is similar to the C function dup().

This uses file descriptors such as those obtained by calling POSIX::open.

Returns undef on failure.

dup2

This is similar to the C function dup2().

This uses file descriptors such as those obtained by calling POSIX::open.

Returns undef on failure.

errno

Returns the value of errno.

$errno = POSIX::errno();

execl

execl() is C-specific.

execle

execle() is C-specific.

execlp

execlp() is C-specific.

execv

execv() is C-specific.

execve

execve() is C-specific.

execvp

execvp() is C-specific.

exit

This is identical to Perl's builtin exit() function.

exp

This is identical to Perl's builtin exp() function.

fabs

This is identical to Perl's builtin abs() function.

fclose

Use method IO::Handle::close() instead.

fcntl

This is identical to Perl's builtin fcntl() function.

fdopen

Use method IO::Handle::new_from_fd() instead.

feof

Use method IO::Handle::eof() instead.

ferror

Use method IO::Handle::error() instead.

fflush

Use method IO::Handle::flush() instead.

fgetc

Use method IO::Handle::getc() instead.

fgetpos

Use method IO::Seekable::getpos() instead.

fgets

Use method IO::Handle::gets() instead.

fileno

Use method IO::Handle::fileno() instead.

floor

This is identical to the C function floor().

fmod

This is identical to the C function fmod().

fopen

Use method IO::File::open() instead.

fork

This is identical to Perl's builtin fork() function.

fpathconf

Retrieves the value of a configurable limit on a file or directory. This uses file descriptors such as those obtained by calling POSIX::open.

The following will determine the maximum length of the longest allowable pathname on the filesystem which holds /tmp/foo.

$fd = POSIX::open( "/tmp/foo", &POSIX::O_RDONLY );
$path_max = POSIX::fpathconf( $fd, &POSIX::_PC_PATH_MAX );

Returns undef on failure.

fprintf

fprintf() is C-specific--use printf instead.

fputc

fputc() is C-specific--use print instead.

fputs

fputs() is C-specific--use print instead.

fread

fread() is C-specific--use read instead.

free

free() is C-specific.

freopen

freopen() is C-specific--use open instead.

frexp

Return the mantissa and exponent of a floating-point number.

($mantissa, $exponent) = POSIX::frexp( 3.14 );

fscanf

fscanf() is C-specific--use <> and regular expressions instead.

fseek

Use method IO::Seekable::seek() instead.

fsetpos

Use method IO::Seekable::setpos() instead.

fstat

Get file status. This uses file descriptors such as those obtained by calling POSIX::open. The data returned is identical to the data from Perl's builtin stat function.

$fd = POSIX::open( "foo", &POSIX::O_RDONLY );
@stats = POSIX::fstat( $fd );

ftell

Use method IO::Seekable::tell() instead.

fwrite

fwrite() is C-specific--use print instead.

getc

This is identical to Perl's builtin getc() function.

getchar

Returns one character from STDIN.

getcwd

Returns the name of the current working directory.

getegid

Returns the effective group id.

getenv

Returns the value of the specified enironment variable.

geteuid

Returns the effective user id.

getgid

Returns the user's real group id.

getgrgid

This is identical to Perl's builtin getgrgid() function.

getgrnam

This is identical to Perl's builtin getgrnam() function.

getgroups

Returns the ids of the user's supplementary groups.

getlogin

This is identical to Perl's builtin getlogin() function.

getpgrp

This is identical to Perl's builtin getpgrp() function.

getpid

Returns the process's id.

getppid

This is identical to Perl's builtin getppid() function.

getpwnam

This is identical to Perl's builtin getpwnam() function.

getpwuid

This is identical to Perl's builtin getpwuid() function.

gets

Returns one line from STDIN.

getuid

Returns the user's id.

gmtime

This is identical to Perl's builtin gmtime() function.

isalnum