#ioctl #posix #syscalls #io #control #low-level #systems

ioctl-sys

IO Control for POSIX-and-beyond systems (core fn & macros, see ioctls for many ioctl definitions)

9 unstable releases

Uses old Rust 2015

0.8.0 Feb 28, 2022
0.7.1 Mar 17, 2021
0.6.0 Nov 17, 2020
0.5.2 Mar 17, 2017
0.4.1 Aug 17, 2016

#260 in Unix APIs

Download history 10491/week @ 2024-08-03 12696/week @ 2024-08-10 11775/week @ 2024-08-17 13121/week @ 2024-08-24 11942/week @ 2024-08-31 9002/week @ 2024-09-07 10526/week @ 2024-09-14 11687/week @ 2024-09-21 9541/week @ 2024-09-28 9414/week @ 2024-10-05 10913/week @ 2024-10-12 11948/week @ 2024-10-19 10783/week @ 2024-10-26 11158/week @ 2024-11-02 11481/week @ 2024-11-09 9545/week @ 2024-11-16

44,543 downloads per month
Used in 63 crates (18 directly)

MIT/Apache

14KB
361 lines

ioctl-sys & ioctls

ioctl-sys Crates.io ioctls Crates.io ioctl-sys ioctl-sys Documentation ioctls ioctls Documentation

Helpers for binding ioctls in Rust. Currently supports Linux on all architectures except SPARC and Alpha. Other platforms welcome!

The ioctl-sys crate provides a basic interface to write your own ioctl wrappers.

The ioctls crate provides wrappers for a bunch of ioctls.

This library is pretty low-level and messy. ioctl is not fun.

What is an ioctl?

The ioctl function is the grab-bag system call on POSIX systems. Don't want to add a new syscall? Make it an ioctl! ioctl refers to both the syscall, and the commands that can be send with it. ioctl stands for "IO control", and the commands are always sent to a file descriptor.

What does this library support?

This library provides the ioctl! macro, for binding ioctls. It also tries to bind every ioctl supported by the system with said macro, but many ioctls require some amount of manual work to support (usually by providing structs or other types) that this library does not support yet.

Additionally, in etc, there are scripts for scraping system headers for ioctl definitions, and generating calls to ioctl! corresponding to them.

How do I get the magic numbers?

Look at your system's headers. For example, /usr/include/linux/input.h has a lot of lines defining macros which use _IOR, _IOW, _IOC, and _IORW. These macros correspond to the ior!, iow!, ioc!, and iorw! macros defined in this crate. Additionally, there is the ioctl! macro for creating a wrapper around ioctl that is somewhat more type-safe.

Most ioctls have no or little documentation. You'll need to scrounge through the source to figure out what they do and how they should be used.

How do I figure out an ioctl's calling convention?

For linux, you must look at the ioctl handlers in the kernel itself to determine how the value passed is being used. Look for the copy_from_user() and get_user() calls, these copy memory from userspace and may indicate that the ioctl's arg is a pointer. In othercases, the ioctl argument may simply be cast to an integer of some sort.

Example

use ioctl_sys::ioctl;

ioctl!(bad kiocsound with 0x4B2F);
ioctl!(none drm_ioctl_set_master with b'd', 0x1e);
ioctl!(read ev_get_version with b'E', 0x01; u32);
ioctl!(write ev_set_repeat with b'E', 0x03; [u32; 2]);

fn main() {
    let mut x = 0;
    let ret = unsafe { ev_get_version(0, &mut x) };
    println!("returned {}, x = {}", ret, x);
}

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

No runtime deps