ext-ioctl

1. Introduction

PHP binding for the ioctl() system call. Supports PHP 7.1 and above.

Using this extension is like playing with fire. Do not touch it unless you know EXACTLY what you are doing.

2. Documentation

2.1 Basic usage

/**
 * Manipulates the underlying device parameters of special files.
 *
 * @param resource|int $fd
 * @param int $request
 * @param string $argp[optional]
 * @param int $errno[optional]
 * @return int|false
 */
function ioctl($fd, $request, $argp, &$errno) {}

• The $fd parameter can be an exact file descriptor (integer) or a resource holding it.
• The $argp parameter should be treated with care.
  • If the underlying data type is a struct, memory alignment should be taken into consideration.
  • If the ioctl() system call will write to $argp, you must pass a string buffer with enough size.
  • PHP's pack() and unpack() functions can be very useful for this.
• If operation fails, $errno will be set, and the function will return false.

See also: examples.

2.2 Helper functions

In userland PHP it's not possible to allocate a string buffer without initialization, all we can do is something like $buffer = str_repeat("\0", $length);.

This extension provides a helper function for better performance.

/**
 * Allocate a string with given length without initialization.
 * 
 * @param int $len
 * @return string
 */
function str_alloc($len) {}

Sometimes, if the struct you are working with contains pointers, what you actually get is an unsigned integer, and there's nothing you can do with it.

This extension provides two simple helper functions as a workaround.

/**
 * Get the address of a string.
 * 
 * @param string $str
 * @return int
 */
function str2ptr($str) {}

/**
 * Copy data from the specified address into a string.
 * 
 * @param int $ptr
 * @param int $length
 * @return string
 */
function ptr2str($ptr, $length) {}

• With str2ptr(), you can get the address of the initial byte of a string (the char array itself, not zend_string).
• If you receive a pointer, you can use ptr2str() to copy data from that address to a string buffer.

Some ioctl operations requires a file descriptor in $argp. However, you cannot extract the underlying file descriptor from a resource in userland PHP. So we need another helper function.

/**
 * Get underlying file descriptor of a resource. Returns -1 on failure.
 * 
 * @param resource $res
 * @return int
 */
function res2fd($res) {}

Note that the helper functions are not enabled by default. You should add --enable-ioctl-helper when executing configure script.