93 lines
2.9 KiB
Markdown
93 lines
2.9 KiB
Markdown
|
# ext-ioctl
|
||
|
|
|
||
|
|
[](https://travis-ci.com/CismonX/ext-ioctl)
|
||
|
|
[](https://opensource.org/licenses/MIT)
|
||
|
|
|
||
|
|
## 1. Introduction
|
||
|
|
|
||
|
|
PHP binding for the [`ioctl()`](http://man7.org/linux/man-pages/man2/ioctl.2.html) 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
|
||
|
|
|
||
|
|
```PHP
|
||
|
|
/**
|
||
|
|
* 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](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.
|
||
|
|
|
||
|
|
```PHP
|
||
|
|
/**
|
||
|
|
* 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.
|
||
|
|
|
||
|
|
```PHP
|
||
|
|
/**
|
||
|
|
* 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.
|
||
|
|
|
||
|
|
```PHP
|
||
|
|
/**
|
||
|
|
* 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.
|