POSIX

📦 min

The POSIX (IEEE Std 1003.1) C standard library, exposed to Perl.

Reach for POSIX when you need something the Perl core does not give you directly: a strftime format, setlocale to switch numeric conventions, sigaction for signal handling, wait-status macros like WIFEXITED / WEXITSTATUS, mkfifo, or any of the hundreds of E* / O_* / F_* / S_* constants from <errno.h>, <fcntl.h>, and friends.

The module groups its surface into the categories below; each one becomes a section on the rendered POSIX page. Every category is backed by libc calls, so behaviour matches the host’s C library exactly (glibc / musl on Linux).

Functions

Math

abs

Integer absolute value of $n.

frexp

Split a floating-point number into mantissa and exponent.

modf

Split a number into integer and fractional parts, both as doubles.

ldexp

Compute $x * 2**$exp with a single rounding step.

Synopsis

my $y = POSIX::ldexp(1.5, 10);   # 1536

Differences from upstream

Fully compatible with upstream POSIX.

scalbn

Compute $x * FLT_RADIX**$n efficiently. On IEEE-754 systems scalbn is equivalent to ldexp.

Differences from upstream

Fully compatible with upstream POSIX.

fma

Fused multiply-add: $x * $y + $z with a single rounding.

nan

Build a quiet NaN, optionally with a payload string.

remquo

Floating-point remainder with partial quotient.

jn

Bessel function of the first kind, integer order $n.

yn

Bessel function of the second kind, integer order $n.

Float classification

fpclassify

Classify a floating-point number.

ilogb

Exponent of $x as an integer, trunc(log2(|$x|)).

Edge cases

• ilogb(0) returns FP_ILOGB0 (typically INT_MIN).

• ilogb(NaN) returns FP_ILOGBNAN.

• ilogb(inf) returns INT_MAX.

Differences from upstream

Fully compatible with upstream POSIX.

lrint

Round $x to the nearest integer, respecting the current rounding mode, and return it as an integer.

Differences from upstream

Fully compatible with upstream POSIX.

See also

• lround — always rounds half-away-from-zero regardless of mode.

• fegetround / fesetround — query or change the rounding mode.

lround

Round $x half-away-from-zero to the nearest integer.

Differences from upstream

Fully compatible with upstream POSIX.

See also

• lrint — rounds according to the current FP rounding mode.

fegetround

Current floating-point rounding direction.

What you get back

An integer matching one of the FE_TONEAREST, FE_DOWNWARD, FE_UPWARD, FE_TOWARDZERO constants.

Differences from upstream

Fully compatible with upstream POSIX.

See also

• fesetround — change the mode.

fesetround

Change the floating-point rounding direction.

Wait status

wexitstatus

Exit code of a child that terminated normally.

wifexited

True if the child terminated normally (via exit or return from main).

Differences from upstream

Fully compatible with upstream POSIX.

wifsignaled

True if the child was killed by a signal.

Differences from upstream

Fully compatible with upstream POSIX.

See also

• WTERMSIG — the signal number, when this is true.

wifstopped

True if the child is stopped (usable with waitpid(..., WUNTRACED)).

Differences from upstream

Fully compatible with upstream POSIX.

wstopsig

Signal number that stopped the child, meaningful only when WIFSTOPPED($status) is true.

Differences from upstream

Fully compatible with upstream POSIX.

wtermsig

Signal number that killed the child, meaningful only when WIFSIGNALED($status) is true.

Differences from upstream

Fully compatible with upstream POSIX.

Strings and printing

strtod

Parse a double from the start of a string, locale-aware.

strtol

Parse a signed integer from the start of a string, in a given base.

strtoul

Parse an unsigned integer from the start of a string, in a given base.

strcoll

Compare two strings using the current LC_COLLATE ordering.

What you get back

A negative, zero, or positive integer, suitable for use as a cmp-like sort return. The ordering depends on the locale set via setlocale(LC_COLLATE, ...).

Differences from upstream

Fully compatible with upstream POSIX.

strerror

Message string for an errno value.

strstr

Byte offset of the first occurrence of $needle in $haystack, or -1 if not found.

Edge cases

• Empty $needle: returns 0 (matches the empty substring at the start), matching C strstr.

Differences from upstream

Fully compatible with upstream POSIX.

See also

• Built-in index — the Perl-native way to do this.

sprintf

Format a string POSIX-style, identical to built-in sprintf.

System and process

getpid

Process ID of the current process.

Differences from upstream

Fully compatible with upstream POSIX.

getppid

Process ID of the parent process.

Differences from upstream

Fully compatible with upstream POSIX.

getuid

Real user ID of the current process.

Differences from upstream

Fully compatible with upstream POSIX.

geteuid

Effective user ID of the current process.

Differences from upstream

Fully compatible with upstream POSIX.

getgid

Real group ID of the current process.

Differences from upstream

Fully compatible with upstream POSIX.

getegid

Effective group ID of the current process.

Differences from upstream

Fully compatible with upstream POSIX.

setuid

Change the real user ID of the current process.

What you get back

1 on success, 0 on failure (and $! is set). Permission is required; only privileged processes can switch to arbitrary UIDs.

Differences from upstream

Fully compatible with upstream POSIX.

setgid

Change the real group ID of the current process.

What you get back

1 on success, 0 on failure.

Differences from upstream

Fully compatible with upstream POSIX.

setpgid

Put process $pid into process group $pgid.

setsid

Create a new session and become its leader.

What you get back

The new session ID on success, -1 on failure. The caller must not already be a process group leader.

Differences from upstream

Fully compatible with upstream POSIX.

uname

Kernel and machine identification as a five-element list.

sysconf

Runtime system configuration value for the given _SC_* name.

getpgrp

Process group ID of the current process.

Differences from upstream

Fully compatible with upstream POSIX.

getlogin

Login name of the user running the process, or undef if not available (e.g. no controlling terminal).

Differences from upstream

Fully compatible with upstream POSIX.

getenv

Value of environment variable $name, or undef if it is unset.

Synopsis

my $path = POSIX::getenv("PATH");

Differences from upstream

Fully compatible with upstream POSIX. Prefer $ENV{$name} in ordinary Perl code.

exit

Terminate the process immediately with the given status, skipping END blocks, destructors, and stdio flushing.

Synopsis

POSIX::_exit(0);

Differences from upstream

Fully compatible with upstream POSIX. Note: exported as _exit, not exit, to avoid colliding with the core built-in.

abort

Abort the process abnormally (typically producing a core dump).

Differences from upstream

Fully compatible with upstream POSIX.

nice

Adjust the current process’s scheduling niceness by $incr.

pause

Suspend the process until any signal is delivered.

What you get back

Always -1 (with $! set to EINTR) once a signal handler returns — pause has no “success” exit path.

Differences from upstream

Fully compatible with upstream POSIX.

sleep

Suspend the process for $secs seconds, or until a signal arrives.

What you get back

The number of seconds left unslept — 0 for a full sleep, or a positive remainder when a signal cut the sleep short.

Differences from upstream

Fully compatible with upstream POSIX.

File and I/O

isatty

True if $fd refers to a terminal.

Differences from upstream

Fully compatible with upstream POSIX.

See also

• ttyname — the device path for a terminal fd.

ttyname

Device path of the terminal attached to $fd, or undef if none.

Differences from upstream

Fully compatible with upstream POSIX.

ctermid

Path of the controlling terminal.

What you get back

On most systems, the string "/dev/tty".

Differences from upstream

Fully compatible with upstream POSIX.

getcwd

Current working directory as an absolute path.

What you get back

The path as a byte string, or undef if the call fails (for example, if the process has no read permission on some ancestor directory).

Differences from upstream

Fully compatible with upstream POSIX.

See also

• Cwd::getcwd — the recommended Perl-level interface.

access

Check the caller’s permissions on a path.

lchown

Change the owner/group of a symlink itself (without following it).

Synopsis

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

What you get back

1 on success, 0 on failure.

Differences from upstream

Fully compatible with upstream POSIX.

mkfifo

Create a FIFO (named pipe) at $path with permission bits $mode.

What you get back

1 on success, 0 on failure.

Differences from upstream

Fully compatible with upstream POSIX.

remove

Delete a file or empty directory at $path.

What you get back

1 on success, 0 on failure. Works on both files and empty directories (dispatching to unlink / rmdir internally).

Differences from upstream

Fully compatible with upstream POSIX.

rename

Rename a file from $old to $new, atomically when on the same filesystem.

What you get back

1 on success, 0 on failure.

Differences from upstream

Fully compatible with upstream POSIX.

open

Open a file by path, returning a raw file descriptor.

close

Close a raw file descriptor.

What you get back

"0 but true" on success, undef on failure. A negative $fd is rejected with $! set to EBADF.

Differences from upstream

Fully compatible with upstream POSIX.

See also

• open, dup, dup2 — where fds come from.

dup

Duplicate a file descriptor, returning the lowest-numbered unused fd.

What you get back

The new fd as an integer on success, undef on failure. A negative $fd is rejected with $! set to EBADF.

Differences from upstream

Fully compatible with upstream POSIX.

dup2

Duplicate $fd1 onto $fd2, closing $fd2 first if necessary.

lseek

Reposition the read/write offset of an open fd.

pipe

Create an anonymous pipe and return its two fds.

read

Read up to $nbytes bytes from $fd into $buffer.

write

Write bytes from $buffer to $fd.

Time

strftime

Format a broken-down time as a string using a format template.

mktime

Convert a broken-down local time into epoch seconds.

difftime

Difference between two epoch times, $t1 - $t2, as a double.

Differences from upstream

Fully compatible with upstream POSIX.

tzset

Refresh the process’s timezone information from the TZ environment variable.

Differences from upstream

Fully compatible with upstream POSIX.

tzname

Short names of the current standard and daylight timezones.

clock

Approximate processor time used by the program, in CLOCKS_PER_SEC units.

What you get back

An integer count of clock ticks. Divide by POSIX::CLOCKS_PER_SEC for seconds. On Linux this counts user+system CPU time of the whole process.

Differences from upstream

Fully compatible with upstream POSIX.

times

Raw wall + CPU times of the process and its children, as a five-element list.

asctime

Canonical English timestamp string from a broken-down time.

ctime

Canonical English timestamp string for an epoch time, in local time.

Locale

setlocale

Query or change the program’s locale setting.

localeconv

Numeric and monetary formatting rules for the active locale.

Character classification

toupper

Locale-aware uppercase of one byte value.

What you get back

The uppercased byte as an integer, or the input unchanged if it has no uppercase form in the current LC_CTYPE locale.

Differences from upstream

Fully compatible with upstream POSIX.

See also

• Core uc — uppercase a whole string, Unicode-aware by default.

tolower

Locale-aware lowercase of one byte value.

Differences from upstream

Fully compatible with upstream POSIX.

See also

• Core lc — lowercase a whole string.

Errno and path limits

errno

Current value of the C errno variable, as an integer.

What you get back

The integer value. Compare against symbolic constants like ENOENT, EINVAL, etc., which this module also exports.

Differences from upstream

Fully compatible with upstream POSIX. In ordinary Perl code prefer $! (which also stringifies to strerror(errno)).

See also

• strerror — message string for an errno number.

fpathconf

Runtime limit for a configuration variable on an open fd.

pathconf

Runtime limit for a configuration variable on a pathname.

What you get back

The limit value, or -1 if unsupported/unlimited.

Differences from upstream

Fully compatible with upstream POSIX.

See also

• fpathconf — same query on an already-open fd.

Terminal control

tcdrain

Block until all queued output on $fd has been transmitted.

What you get back

"0 but true" on success, undef on failure. A negative $fd sets $! to EBADF.

Differences from upstream

Fully compatible with upstream POSIX.

tcflow

Suspend or resume transmission or reception on terminal $fd.

tcflush

Discard buffered input, output, or both on terminal $fd.

tcsendbreak

Send a continuous break condition on terminal $fd for roughly $duration tenths of a second (0 means the implementation default).

What you get back

"0 but true" on success, undef on failure. Negative $duration sets $! to EINVAL.

Differences from upstream

Fully compatible with upstream POSIX.

tcgetpgrp

Process group ID of the foreground process group for terminal $fd.

What you get back

The pgid as an integer, or -1 on error (with $! set).

Differences from upstream

Fully compatible with upstream POSIX.

tcsetpgrp

Make $pgrp the foreground process group of terminal $fd.

What you get back

"0 but true" on success, undef on failure.

Differences from upstream

Fully compatible with upstream POSIX.

termios_new

Create a fresh POSIX::Termios object, all fields zeroed.

termios_getattr

Fill the POSIX::Termios object with the current settings of $fd.

termios_setattr

Apply the POSIX::Termios settings to $fd.

termios_getispeed

Input baud rate encoded in the termios structure.

What you get back

The encoded speed as an integer (compare against B9600, B115200, etc., which this module also exports).

Differences from upstream

Fully compatible with upstream POSIX.

termios_getospeed

Output baud rate encoded in the termios structure.

Differences from upstream

Fully compatible with upstream POSIX.

termios_setispeed

Encode an input baud rate into the termios structure.

What you get back

"0 but true" on success, undef on failure. The change is not applied to the terminal until you call setattr.

Differences from upstream

Fully compatible with upstream POSIX.

termios_setospeed

Encode an output baud rate into the termios structure.

Differences from upstream

Fully compatible with upstream POSIX.

termios_getcc

Value of a special control character in the termios structure.

termios_setcc

Set a special control character in the termios structure.

Edge cases

• Indices beyond NCCS croak with Bad setcc subscript.

• The change is not applied until you call setattr.

Differences from upstream

Fully compatible with upstream POSIX.

Signals

sigset_new

Create a POSIX::SigSet object, optionally pre-populated with the given signal numbers.

sigset_addset

Add signal $sig to the set.

What you get back

"0 but true" on success, undef on failure.

Differences from upstream

Fully compatible with upstream POSIX.

sigset_delset

Remove signal $sig from the set.

What you get back

"0 but true" on success, undef on failure.

Differences from upstream

Fully compatible with upstream POSIX.

sigset_emptyset

Remove every signal from the set.

Differences from upstream

Fully compatible with upstream POSIX.

sigset_fillset

Add every signal to the set.

Differences from upstream

Fully compatible with upstream POSIX.

sigset_ismember

Test whether signal $sig is in the set.

What you get back

1 if the signal is a member, 0 if it is not, -1 on error.

Differences from upstream

Fully compatible with upstream POSIX.

sigprocmask

Change, query, or both the set of signals blocked for this process.

sigpending

Fill $sigset with the signals currently pending for delivery.

What you get back

"0 but true" on success, undef on failure.

Differences from upstream

Fully compatible with upstream POSIX.

sigsuspend

Temporarily replace the signal mask with $sigset and suspend the process until any non-blocked signal arrives.

What you get back

Always undef (with $! set to EINTR) once a signal handler has run — there is no success exit path.

Differences from upstream

Fully compatible with upstream POSIX.

sigaction

Install or inspect a signal handler for signal $sig.

Constants

constant

Look up a POSIX constant by name.