Download the PHP package microscrap/posix without Composer

microscrap/posix — POSIX bindings for ScrapyardIO

Docs (production): ScrapyardIO · microscrap/posix 0.7.x

PHP library that wraps the posi extension (ext-posi) with global helpers and enums. Every helper delegates to Posi\System (or Posi\Memory for posi_mem_*).

This is the bindings package — not the native extension. Ecosystem docs: 0.7.x.

Highlights

• Retrieve file descriptors to replace fopen
• Read and write to file descriptors beyond streams, replacing fread and fwrite
• Direct access to fcntl and ioctl
• Optional posi_mem_* helpers over Posi\Memory
• Typed enums for common Linux O_* / F_* flag values

Requirements

• PHP ^8.4|^8.5|^8.6
• ext-posi ^0.7.0 — install from php-io-extensions/posi

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) — cases are FULLY UPPERCASE.

posix_open(), fcntl(), and ioctl() take the same flag and command integers as C (O_RDONLY, F_GETFL, and so on). Prefer the shipped enums for common Linux/glibc values, or define platform constants from your OS headers.

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

posi_mem_alloc(int $size): int

Allocates $size bytes via Posi\Memory::alloc and returns a pointer integer usable with the other posi_mem_* helpers.

posi_mem_free(int $ptr): void

Frees a pointer previously returned by posi_mem_alloc.

posi_mem_write(int $ptr, string $data, int $offset = 0): void

Writes $data into the allocated buffer at $offset.

posi_mem_read(int $ptr, int $size, int $offset = 0): string

Reads $size bytes from the allocated buffer at $offset.

Example

Quick reference

License

MIT. See LICENSE.