|
||
---|---|---|
examples | ||
src | ||
tests | ||
.gitattributes | ||
.gitignore | ||
.travis.yml | ||
LICENSE | ||
README.md | ||
config.m4 |
README.md
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 aresource
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()
andunpack()
functions can be very useful for this.
- If operation fails,
$errno
will be set, and the function will returnfalse
.
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 astring
(the char array itself, notzend_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.