Download the PHP package microscrap/posix without Composer

microscrap/posix — POSIX bindings for ScrapyardIO

PHP library that wraps the posi extension with global helpers and enums. Every helper delegates to Posi\System.

This project provides bindings to the UNIX Portable Operating System Interface (POSIX).

Highlights

• Retrieve file descriptors to replace fopen
• Read and write to file descriptors beyond streams, replacing fread and fwrite
• Direct access to fcntl
• Direct access to ioctl

Requirements

• PHP 8.3+
• ext-posi ^0.4.0 — install from php-io-extensions/posi (see that repo for build and enable instructions)

Installation

Confirm ext-posi is loaded before using this library:

Composer autoloads src/Helpers/posix-system.php, registering the global helpers when the package is installed.

Usage

POSIX I/O is invoked through global helper functions (for example posix_open, posix_read). Helpers are only defined if the name is not already taken (function_exists guard).

Optional enums live under Microscrap\Bindings\POSIX\Enums (FileControlFlag, FcntlCommand).

posix_open(), fcntl(), and ioctl() take the same flag and command constants as C (O_RDONLY, F_GETFL, and so on). Define them in PHP or load them from your platform headers; values differ by OS.

Global Helper API

posix_open(string $filepath, int $flags = 2, int $mode = 0644): int

Opens a path and returns a file descriptor (non-negative integer), or -1 on failure (same semantics as C open(2)).

• $filepath — device node, pipe, socket path, or regular file path.
• $flags — O_* access mode and creation flags (e.g. O_RDWR, O_CREAT | O_TRUNC). Default 2 (O_RDWR on Linux/glibc).
• $mode — permission bits when O_CREAT is set (default 0644).

Example — open an existing file for reading

Example — create and truncate a file for read/write

posix_close(int $fd): int

Closes a file descriptor. Returns 0 on success and -1 on failure (same semantics as C close(2)).

Example

posix_chmod(string $path, int $mode): int

Sets permission bits on a path. Returns 0 on success and -1 on failure (same semantics as C chmod(2)).

• $path — file or directory path.
• $mode — permission bits (e.g. 0644). Combine with S_ISUID, S_ISGID, and S_ISVTX where your platform supports them.

Changing modes on paths you do not own, or setting set-user-ID bits, typically requires appropriate privileges.

Example

posix_chown(string $path, int $owner, int $group): int

Sets owner and group for a path. Returns 0 on success and -1 on failure (same semantics as C chown(2)).

• $owner — numeric user ID (uid_t).
• $group — numeric group ID (gid_t).

This call usually requires superuser privileges or capability CAP_CHOWN on Linux.

Example

posix_fchmod(int $fd, int $mode): int

Like posix_chmod, but applies to an open file descriptor. Returns 0 on success and -1 on failure (same semantics as C fchmod(2)).

Example

posix_fchown(int $fd, int $owner, int $group): int

Like posix_chown, but applies to the file referred to by an open descriptor. Returns 0 on success and -1 on failure (same semantics as C fchown(2)).

Example

posix_write(int $fd, string $data, int $bytes_to_write): int

Writes up to $bytes_to_write bytes from $data to the descriptor. Returns the number of bytes written, or -1 on failure (same semantics as C write(2)).

Example — write a line to a file descriptor

Example — write to /dev/null

posix_read(int $fd, int $bytes_to_read): string|false

Reads up to $bytes_to_read bytes from the descriptor. Returns a binary string of the bytes read (length may be less than requested). Returns false if the underlying read(2) fails.

Example — read the first 512 bytes of a file

Example — read from a pipe in a loop

posix_getuid(): int

Returns the real user ID of the calling process (same semantics as C getuid(2)).

This helper is registered only when posix_getuid() is not already defined (for example by PHP’s built-in posix extension). When the built-in exists, PHP’s version is used instead.

Example

posix_setuid(int $uid): int

Sets the real user ID of the calling process. Returns 0 on success and -1 on failure (same semantics as C setuid(2)). Changing UID typically requires appropriate privileges.

Registered only when posix_setuid() is not already defined.

Example

posix_umask(int $mask): int

Sets the file mode creation mask. Returns the previous umask value (same semantics as C umask(2)). Values are numeric (for example octal 022 is the integer 18 on typical platforms).

Example

posix_lseek(int $fd, int $offset, int $whence): int

Repositions the offset of the open descriptor. Returns the new offset measured in bytes from the beginning of the file, or -1 on failure (same semantics as C lseek(2)). Use SEEK_SET, SEEK_CUR, and SEEK_END from your platform.

Example

posix_recv(int $fd, int $len, int $flags = 0): string|false

Receives up to $len bytes from a socket descriptor (same semantics as C recv(2)). Returns a binary string (possibly shorter than $len), or false on failure. Optional $flags are the usual MSG_* constants for your platform (0 to block until data is available).

Example

posix_readv(int $fd, array $iovecs): array|false

Scatter-read into several buffers in one syscall (readv(2)). Each element of $iovecs is an associative array:

On success, returns:

Returns false if the syscall fails or if $iovecs is invalid.

Example — two segments from a regular file

fcntl(int $fd, int $command, mixed $arg, mixed &$value): int

Invokes fcntl(2) on the descriptor. Returns the syscall status (0 or non-negative on success, -1 on failure). Command-specific output is written to $value by reference (flag integer for getters like F_GETFL, flock array for lock commands, or echo of the argument for setters).

$arg may be an integer, a boolean, or (for F_GETLK / F_SETLK / F_SETLKW) an array with keys: type, whence, start, len, pid.

Example — read open-file status flags (F_GETFL)

Example — enable non-blocking I/O (F_SETFL)

Example — advisory lock (F_SETLK)

ioctl(int $fd, int $command, mixed $arg, mixed &$value): int

Invokes ioctl(2) on the descriptor. Returns the syscall status. Output is written to $value by reference: integer, string buffer, or argument echo depending on command and $arg.

$arg may be an integer pointer value, a string buffer, or an array:

• ['value' => int] — read/write a single integer through the ioctl (value updated in $value).
• ['bytes' => string] or ['data' => string] — binary buffer in/out.

Example — ioctl with no argument (device-specific command)

Example — pass an integer argument

Example — integer in/out via array

Example — binary buffer in/out

posix_wait(?int &$status = null): int

Blocks until any child process exits (implemented with waitpid(-1, …, 0), same idea as wait(2)). Returns the child PID on success, or -1 on error (for example ECHILD when there are no children). If you pass $status by reference, it receives the raw wait status integer for use with pcntl_wifexited(), pcntl_wexitstatus(), and related helpers (or your own bit tests). If the call fails, $status is not updated.

Example

posix_waitpid(int $pid, ?int &$status = null, int $options = 0): int

Wraps waitpid(2). Use $pid = -1 to wait for any child (same as posix_wait()). $options is typically 0 (block) or WNOHANG (do not block). Returns the child PID on success when a child was reaped, 0 when $options includes WNOHANG and no child was ready, or -1 on error. The raw status word is written to $status by reference only when the return value is greater than zero (a child was reaped).

Example

posix_hostname(): string|false

Returns the current host name via gethostname(2). Returns false if the syscall fails.

Registered only when posix_hostname() is not already defined.

Example

posix_lstat(string $path): array|false

Returns file status information via lstat(2). Unlike stat(2), lstat does not follow symbolic links — it reports metadata for the link itself.

On success, returns an associative array with the same keys as PHP’s built-in lstat():

Returns false if the syscall fails.

Example

Quick reference

License

MIT. See LICENSE.