PHP binding for the ioctl system call.
This repository has been archived on 2018-05-01. You can view files and clone it, but cannot push or open issues or pull requests.
Go to file
CismonX 9ab1638ec1
archive
2018-05-01 17:57:55 +08:00
examples archive 2018-05-01 17:57:55 +08:00
src archive 2018-05-01 17:57:55 +08:00
tests archive 2018-05-01 17:57:55 +08:00
.gitattributes archive 2018-05-01 17:57:55 +08:00
.gitignore archive 2018-05-01 17:57:55 +08:00
.travis.yml archive 2018-05-01 17:57:55 +08:00
LICENSE archive 2018-05-01 17:57:55 +08:00
README.md archive 2018-05-01 17:57:55 +08:00
config.m4 archive 2018-05-01 17:57:55 +08:00

README.md

ext-ioctl

Travis-CI MIT license

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.