ioctl-id 0.2.0

Rust identifiers for `ioctl(2)` calls on Unix-like systems.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

//! macOS-specific definitions.
//! 
//! On macOS, `ioctl(2)`identifiers are the size of C's `unsigned long` type,
//! equivalent to `u32` on 32-bit architectures and `u64` on 64-bit
//! architectures.
//! 
//! The `ioctl(2)` identifier is divided into three fields. From most-significant to least-significant in the identifier:
//! * The direction of the `ioctl(2)` call.
//! * The size of the structure passed to the `ioctl(2)` call.
//! * A group identifier.
//! * A call identifier.

use core::{ffi::c_ulong, mem::size_of};

/// The identifier type for ioctl calls.
pub type IoctlId = c_ulong;

/// A mask for the size of a parameter to the `ioctl(2)` call.
/// 
/// Reference: [`sys/ioccom.h`](https://opensource.apple.com/source/xnu/xnu-201.5/bsd/sys/ioccom.h.auto.html)
pub const IOCPARM_MASK: IoctlId = 0x1FFF;

/// The size of the parameter to the `ioctl(2)` call from its identifier.
/// 
/// Reference: [`sys/ioccom.h`](https://opensource.apple.com/source/xnu/xnu-201.5/bsd/sys/ioccom.h.auto.html)
pub const fn iocparm_len(value: IoctlId) -> IoctlId {
    (value >> 16) & IOCPARM_MASK
}

/// Reference: [`sys/ioccom.h`](https://opensource.apple.com/source/xnu/xnu-201.5/bsd/sys/ioccom.h.auto.html)
pub const fn iocbase_cmd(value: IoctlId) -> IoctlId {
    value & !(IOCPARM_MASK << 16)
}

/// Maximum size of `ioctl(2)` arguments.
/// 
/// Reference: [`sys/ioccom.h`](https://opensource.apple.com/source/xnu/xnu-201.5/bsd/sys/ioccom.h.auto.html)
pub const IOCPARM_MAX: usize = IOCPARM_MASK as usize + 1;

/// The `ioctl(2)` request takes no parameters.
/// 
/// Reference: [`sys/ioccom.h`](https://opensource.apple.com/source/xnu/xnu-201.5/bsd/sys/ioccom.h.auto.html)
pub const IOC_VOID: IoctlId = 0x20000000;

/// The `ioctl(2)` request receives parameters from the kernel.
/// 
/// Reference: [`sys/ioccom.h`](https://opensource.apple.com/source/xnu/xnu-201.5/bsd/sys/ioccom.h.auto.html)
pub const IOC_OUT: IoctlId = 0x40000000;

/// The `ioctl(2)` request sends parameters to the kernel.
/// 
/// Reference: [`sys/ioccom.h`](https://opensource.apple.com/source/xnu/xnu-201.5/bsd/sys/ioccom.h.auto.html)
pub const IOC_IN: IoctlId = 0x80000000;

/// The `ioctl(2)` request sends and receives parameters to and from the kernel.
/// 
/// Reference: [`sys/ioccom.h`](https://opensource.apple.com/source/xnu/xnu-201.5/bsd/sys/ioccom.h.auto.html)
pub const IOC_INOUT: IoctlId = IOC_IN | IOC_OUT;

/// Mask for the direction values.
///
/// Reference: [`sys/ioccom.h`](https://opensource.apple.com/source/xnu/xnu-201.5/bsd/sys/ioccom.h.auto.html)
pub const IOC_DIRMASK: IoctlId = 0xe0000000;

/// Create an `ioctl(2)` identifier from a direction value, group identifier,
/// call identifier, and size value.
/// 
/// This matches the definition of the `_IOC()` macro from the C headers.
///
/// Reference: [`sys/ioccom.h`](https://opensource.apple.com/source/xnu/xnu-201.5/bsd/sys/ioccom.h.auto.html)
pub const fn ioc(inout: IoctlId, group: IoctlId, num: IoctlId, size: IoctlId) -> IoctlId {
    inout | ((size & IOCPARM_MASK) << 16) | (group << 8) | num
}

/// Create an `ioctl(2)` identifier for a call that passes no data.
///
/// This is the equivalent of the `_IO()` macro from the C headers.
///
/// Reference: [`sys/ioccom.h`](https://opensource.apple.com/source/xnu/xnu-201.5/bsd/sys/ioccom.h.auto.html)
pub const fn io(group: IoctlId, num: IoctlId) -> IoctlId {
    ioc(IOC_VOID, group, num, 0)
}

/// Create an `ioctl(2)` identifier for a call that reads data.
///
/// This is the equivalent of the `_IOR()` macro from the C headers. The type must be passed as a generic parameter
/// to this function.
///
/// Reference: [`sys/ioccom.h`](https://opensource.apple.com/source/xnu/xnu-201.5/bsd/sys/ioccom.h.auto.html)
pub const fn ior<T>(group: IoctlId, num: IoctlId) -> IoctlId {
    ioc(IOC_OUT, group, num, size_of::<T>() as IoctlId)
}

/// Create an `ioctl(2)` identifier for a call that writes data.
/// 
/// This is the equivalent of the `_IOW()` macro from the C headers. The type must be passed as a generic parameter
/// to this function.
///
/// Reference: [`sys/ioccom.h`](https://opensource.apple.com/source/xnu/xnu-201.5/bsd/sys/ioccom.h.auto.html)
pub const fn iow<T>(group: IoctlId, num: IoctlId) -> IoctlId {
    ioc(IOC_IN, group, num, size_of::<T>() as IoctlId)
}

/// Create an `ioctl(2)` identifier for a call that reads and writes data.
///
/// This is the equivalent of the `_IOWR()` macro from the C headers. The type must be passed as a generic parameter
/// to this function.
///
/// Reference: [`sys/ioccom.h`](https://opensource.apple.com/source/xnu/xnu-201.5/bsd/sys/ioccom.h.auto.html)
pub const fn iowr<T>(group: IoctlId, num: IoctlId) -> IoctlId {
    ioc(IOC_INOUT, group, num, size_of::<T>() as IoctlId)
}