Skip to content

Commit 4b8a661

Browse files
roblablaroblabla
committed
Allow doc attributes in ioctl macro
1 parent 26c35c0 commit 4b8a661

File tree

2 files changed

+108
-13
lines changed

2 files changed

+108
-13
lines changed

‎src/sys/ioctl/mod.rs

Lines changed: 54 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -197,6 +197,34 @@
197197
//! of lines defining macros which use `_IO`, `_IOR`, `_IOW`, `_IOC`, and `_IORW`. Some `ioctl`s are
198198
//! documented directly in the headers defining their constants, but others have more extensive
199199
//! documentation in man pages (like termios' `ioctl`s which are in `tty_ioctl(4)`).
200+
//!
201+
//! Documenting the generated functions
202+
//! ===================================
203+
//!
204+
//! In many cases, users will wish for the functions generated by the `ioctl`
205+
//! macro to be public and documented. For this reason, the generated functions
206+
//! are public by default. If you wish to hide the ioctl, you will need to put
207+
//! them in a private module.
208+
//!
209+
//! For documentation, it is possible to use doc comments inside the `ioctl!`
210+
//! macro. Here is an example :
211+
//!
212+
//! ```
213+
//! # #[macro_use] extern crate nix;
214+
//! # use nix::libc::c_int;
215+
//! ioctl! {
216+
//! /// Make the given terminal the controlling terminal of the calling process. The calling
217+
//! /// process must be a session leader and not have a controlling terminal already. If the
218+
//! /// terminal is already the controlling terminal of a different session group then the
219+
//! /// ioctl will fail with **EPERM**, unless the caller is root (more precisely: has the
220+
//! /// **CAP_SYS_ADMIN** capability) and arg equals 1, in which case the terminal is stolen
221+
//! /// and all processes that had it as controlling terminal lose it.
222+
//! read tiocsctty with b't', 19; c_int
223+
//! }
224+
//!
225+
//! # fn main() {}
226+
//! ```
227+
//!
200228
#[cfg(any(target_os = "linux", target_os = "android"))]
201229
#[path = "platform/linux.rs"]
202230
#[macro_use]
@@ -228,89 +256,102 @@ macro_rules! convert_ioctl_res {
228256
/// Generates ioctl functions. See [::sys::ioctl](sys/ioctl/index.html).
229257
#[macro_export]
230258
macro_rules! ioctl {
231-
(bad none $name:ident with $nr:expr) => (
259+
($(#[$attr:meta])* bad none $name:ident with $nr:expr) => (
260+
$(#[$attr])*
232261
pub unsafe fn $name(fd: $crate::libc::c_int)
233262
-> $crate::Result<$crate::libc::c_int> {
234263
convert_ioctl_res!($crate::libc::ioctl(fd, $nr as $crate::sys::ioctl::ioctl_num_type))
235264
}
236265
);
237-
(bad read $name:ident with $nr:expr; $ty:ty) => (
266+
($(#[$attr:meta])* bad read $name:ident with $nr:expr; $ty:ty) => (
267+
$(#[$attr])*
238268
pub unsafe fn $name(fd: $crate::libc::c_int,
239269
data: *mut $ty)
240270
-> $crate::Result<$crate::libc::c_int> {
241271
convert_ioctl_res!($crate::libc::ioctl(fd, $nr as $crate::sys::ioctl::ioctl_num_type, data))
242272
}
243273
);
244-
(bad write_ptr $name:ident with $nr:expr; $ty:ty) => (
274+
($(#[$attr:meta])* bad write_ptr $name:ident with $nr:expr; $ty:ty) => (
275+
$(#[$attr])*
245276
pub unsafe fn $name(fd: $crate::libc::c_int,
246277
data: *const $ty)
247278
-> $crate::Result<$crate::libc::c_int> {
248279
convert_ioctl_res!($crate::libc::ioctl(fd, $nr as $crate::sys::ioctl::ioctl_num_type, data))
249280
}
250281
);
251-
(bad write_int $name:ident with $nr:expr) => (
282+
($(#[$attr:meta])* bad write_int $name:ident with $nr:expr) => (
283+
$(#[$attr])*
252284
pub unsafe fn $name(fd: $crate::libc::c_int,
253285
data: $crate::libc::c_int)
254286
-> $crate::Result<$crate::libc::c_int> {
255287
convert_ioctl_res!($crate::libc::ioctl(fd, $nr as $crate::sys::ioctl::ioctl_num_type, data))
256288
}
257289
);
258-
(bad readwrite $name:ident with $nr:expr; $ty:ty) => (
290+
($(#[$attr:meta])* bad readwrite $name:ident with $nr:expr; $ty:ty) => (
291+
$(#[$attr])*
259292
pub unsafe fn $name(fd: $crate::libc::c_int,
260293
data: *mut $ty)
261294
-> $crate::Result<$crate::libc::c_int> {
262295
convert_ioctl_res!($crate::libc::ioctl(fd, $nr as $crate::sys::ioctl::ioctl_num_type, data))
263296
}
264297
);
265-
(none $name:ident with $ioty:expr, $nr:expr) => (
298+
($(#[$attr:meta])* none $name:ident with $ioty:expr, $nr:expr) => (
299+
$(#[$attr])*
266300
pub unsafe fn $name(fd: $crate::libc::c_int)
267301
-> $crate::Result<$crate::libc::c_int> {
268302
convert_ioctl_res!($crate::libc::ioctl(fd, io!($ioty, $nr) as $crate::sys::ioctl::ioctl_num_type))
269303
}
270304
);
271-
(read $name:ident with $ioty:expr, $nr:expr; $ty:ty) => (
305+
($(#[$attr:meta])* read $name:ident with $ioty:expr, $nr:expr; $ty:ty) => (
306+
$(#[$attr])*
272307
pub unsafe fn $name(fd: $crate::libc::c_int,
273308
data: *mut $ty)
274309
-> $crate::Result<$crate::libc::c_int> {
275310
convert_ioctl_res!($crate::libc::ioctl(fd, ior!($ioty, $nr, ::std::mem::size_of::<$ty>()) as $crate::sys::ioctl::ioctl_num_type, data))
276311
}
277312
);
278-
(write_ptr $name:ident with $ioty:expr, $nr:expr; $ty:ty) => (
313+
($(#[$attr:meta])* write_ptr $name:ident with $ioty:expr, $nr:expr; $ty:ty) => (
314+
$(#[$attr])*
279315
pub unsafe fn $name(fd: $crate::libc::c_int,
280316
data: *const $ty)
281317
-> $crate::Result<$crate::libc::c_int> {
282318
convert_ioctl_res!($crate::libc::ioctl(fd, iow!($ioty, $nr, ::std::mem::size_of::<$ty>()) as $crate::sys::ioctl::ioctl_num_type, data))
283319
}
284320
);
285-
(write_int $name:ident with $ioty:expr, $nr:expr) => (
321+
($(#[$attr:meta])* write_int $name:ident with $ioty:expr, $nr:expr) => (
322+
$(#[$attr])*
286323
pub unsafe fn $name(fd: $crate::libc::c_int,
287324
data: $crate::libc::c_int)
288325
-> $crate::Result<$crate::libc::c_int> {
289326
convert_ioctl_res!($crate::libc::ioctl(fd, iow!($ioty, $nr, ::std::mem::size_of::<$crate::libc::c_int>()) as $crate::sys::ioctl::ioctl_num_type, data))
290327
}
291328
);
292-
(readwrite $name:ident with $ioty:expr, $nr:expr; $ty:ty) => (
329+
($(#[$attr:meta])* readwrite $name:ident with $ioty:expr, $nr:expr; $ty:ty) => (
330+
$(#[$attr])*
293331
pub unsafe fn $name(fd: $crate::libc::c_int,
294332
data: *mut $ty)
295333
-> $crate::Result<$crate::libc::c_int> {
296334
convert_ioctl_res!($crate::libc::ioctl(fd, iorw!($ioty, $nr, ::std::mem::size_of::<$ty>()) as $crate::sys::ioctl::ioctl_num_type, data))
297335
}
298336
);
299-
(read_buf $name:ident with $ioty:expr, $nr:expr; $ty:ty) => (
337+
($(#[$attr:meta])* read_buf $name:ident with $ioty:expr, $nr:expr; $ty:ty) => (
338+
$(#[$attr])*
300339
pub unsafe fn $name(fd: $crate::libc::c_int,
301340
data: &mut [$ty])
302341
-> $crate::Result<$crate::libc::c_int> {
303342
convert_ioctl_res!($crate::libc::ioctl(fd, ior!($ioty, $nr, data.len() * ::std::mem::size_of::<$ty>()) as $crate::sys::ioctl::ioctl_num_type, data))
304343
}
305344
);
306-
(write_buf $name:ident with $ioty:expr, $nr:expr; $ty:ty) => (
345+
($(#[$attr:meta])* write_buf $name:ident with $ioty:expr, $nr:expr; $ty:ty) => (
346+
$(#[$attr])*
307347
pub unsafe fn $name(fd: $crate::libc::c_int,
308348
data: &[$ty])
309349
-> $crate::Result<$crate::libc::c_int> {
310350
convert_ioctl_res!($crate::libc::ioctl(fd, iow!($ioty, $nr, data.len() * ::std::mem::size_of::<$ty>()) as $crate::sys::ioctl::ioctl_num_type, data))
311351
}
312352
);
313-
(readwrite_buf $name:ident with $ioty:expr, $nr:expr; $ty:ty) => (
353+
($(#[$attr:meta])* readwrite_buf $name:ident with $ioty:expr, $nr:expr; $ty:ty) => (
354+
$(#[$attr])*
314355
pub unsafe fn $name(fd: $crate::libc::c_int,
315356
data: &mut [$ty])
316357
-> $crate::Result<$crate::libc::c_int> {

‎test/sys/test_ioctl.rs

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,60 @@ ioctl!(write_buf writebuf_test_u32 with 0, 0; u32);
2222
ioctl!(write_buf writebuf_test_u64 with 0, 0; u64);
2323
ioctl!(readwrite_buf readwritebuf_test with 0, 0; u32);
2424

25+
// Make sure documentation works
26+
ioctl! {
27+
/// This documents the ioctl function
28+
bad none do_bad_docs with 0x1234
29+
}
30+
ioctl! {
31+
/// This documents the ioctl function
32+
bad read do_bad_read_docs with 0x1234; u16
33+
}
34+
ioctl! {
35+
/// This documents the ioctl function
36+
bad write_int do_bad_write_int_docs with 0x1234
37+
}
38+
ioctl! {
39+
/// This documents the ioctl function
40+
bad write_ptr do_bad_write_ptr_docs with 0x1234; u8
41+
}
42+
ioctl! {
43+
/// This documents the ioctl function
44+
bad readwrite do_bad_readwrite_docs with 0x1234; u32
45+
}
46+
ioctl! {
47+
/// This documents the ioctl function
48+
none do_none_docs with 0, 0
49+
}
50+
ioctl! {
51+
/// This documents the ioctl function
52+
read do_read_docs with 0, 0; u32
53+
}
54+
ioctl! {
55+
/// This documents the ioctl function
56+
write_int do_write_int_docs with 0, 0
57+
}
58+
ioctl! {
59+
/// This documents the ioctl function
60+
write_ptr do_write_ptr_docs with 0, 0; u32
61+
}
62+
ioctl! {
63+
/// This documents the ioctl function
64+
readwrite do_readwrite_docs with 0, 0; u32
65+
}
66+
ioctl! {
67+
/// This documents the ioctl function
68+
read_buf do_read_buf_docs with 0, 0; u32
69+
}
70+
ioctl! {
71+
/// This documents the ioctl function
72+
write_buf do_write_buf_docs with 0, 0; u32
73+
}
74+
ioctl! {
75+
/// This documents the ioctl function
76+
readwrite_buf do_readwrite_buf_docs with 0, 0; u32
77+
}
78+
2579
// See C code for source of values for op calculations (does NOT work for mips/powerpc):
2680
// https://gist.github.com/posborne/83ea6880770a1aef332e
2781
//

0 commit comments

Comments
 (0)