<!-- GENERATED by docs/sphinx/bin/02-reference from POSIX.rs. Do not edit. -->

```{index} single: POSIX; Perl module
```

# POSIX

```{pperl-module-badges} POSIX
```

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`](POSIX/abs)

Integer absolute value of `$n`.

#### [`frexp`](POSIX/frexp)

Split a floating-point number into mantissa and exponent.

#### [`modf`](POSIX/modf)

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

#### `ldexp`

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

**Synopsis**

```perl
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`](POSIX/fma)

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

#### [`nan`](POSIX/nan)

Build a quiet NaN, optionally with a payload string.

#### [`remquo`](POSIX/remquo)

Floating-point remainder with partial quotient.

#### [`jn`](POSIX/jn)

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

#### [`yn`](POSIX/yn)

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

### Float classification

#### [`fpclassify`](POSIX/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`](POSIX/fesetround)

Change the floating-point rounding direction.

### Wait status

#### [`wexitstatus`](POSIX/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`](POSIX/strtod)

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

#### [`strtol`](POSIX/strtol)

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

#### [`strtoul`](POSIX/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`](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`](POSIX/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`](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`](POSIX/uname)

Kernel and machine identification as a five-element list.

#### [`sysconf`](POSIX/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**

```perl
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**

```perl
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`](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`](POSIX/access)

Check the caller's permissions on a path.

#### `lchown`

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

**Synopsis**

```perl
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`](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`](POSIX/dup2)

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

#### [`lseek`](POSIX/lseek)

Reposition the read/write offset of an open fd.

#### [`pipe`](POSIX/pipe)

Create an anonymous pipe and return its two fds.

#### [`read`](POSIX/read)

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

#### [`write`](POSIX/write)

Write bytes from `$buffer` to `$fd`.

### Time

#### [`strftime`](POSIX/strftime)

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

#### [`mktime`](POSIX/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`](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`](POSIX/times)

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

#### [`asctime`](POSIX/asctime)

Canonical English timestamp string from a broken-down time.

#### [`ctime`](POSIX/ctime)

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

### Locale

#### [`setlocale`](POSIX/setlocale)

Query or change the program's locale setting.

#### [`localeconv`](POSIX/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`](POSIX/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`](POSIX/tcflow)

Suspend or resume transmission or reception on terminal `$fd`.

#### [`tcflush`](POSIX/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`](POSIX/termios_new)

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

#### [`termios_getattr`](POSIX/termios_getattr)

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

#### [`termios_setattr`](POSIX/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`](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`](POSIX/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`](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`](POSIX/sigaction)

Install or inspect a signal handler for signal `$sig`.

### Constants

#### [`constant`](POSIX/constant)

Look up a POSIX constant by name.

```{toctree}
:hidden:
:maxdepth: 1

POSIX/abs
POSIX/frexp
POSIX/modf
POSIX/fma
POSIX/nan
POSIX/remquo
POSIX/jn
POSIX/yn
POSIX/fpclassify
POSIX/fesetround
POSIX/wexitstatus
POSIX/strtod
POSIX/strtol
POSIX/strtoul
POSIX/strerror
POSIX/sprintf
POSIX/setpgid
POSIX/uname
POSIX/sysconf
POSIX/access
POSIX/open
POSIX/dup2
POSIX/lseek
POSIX/pipe
POSIX/read
POSIX/write
POSIX/strftime
POSIX/mktime
POSIX/tzname
POSIX/times
POSIX/asctime
POSIX/ctime
POSIX/nice
POSIX/setlocale
POSIX/localeconv
POSIX/fpathconf
POSIX/constant
POSIX/tcflow
POSIX/tcflush
POSIX/termios_new
POSIX/termios_getattr
POSIX/termios_setattr
POSIX/termios_getcc
POSIX/sigset_new
POSIX/sigprocmask
POSIX/sigaction
```