Lines Matching refs:ioctl
1 //! Provide helpers for making ioctl system calls.
3 //! This library is pretty low-level and messy. `ioctl` is not fun.
5 //! What is an `ioctl`?
8 //! The `ioctl` syscall is the grab-bag syscall on POSIX systems. Don't want to add a new
9 //! syscall? Make it an `ioctl`! `ioctl` refers to both the syscall, and the commands that can be
10 //! sent with it. `ioctl` stands for "IO control", and the commands are always sent to a file
13 //! It is common to see `ioctl`s used for the following purposes:
23 //! `ioctl`s are synchronous system calls and are similar to read and write calls in that regard.
24 //! They operate on file descriptors and have an identifier that specifies what the ioctl is.
29 //! Historically `ioctl` numbers were arbitrary hard-coded values. In Linux (before 2.6) and some
30 //! unices this has changed to a more-ordered system where the ioctl numbers are partitioned into
32 //! [`Documentation/ioctl/ioctl-number.rst`](https://elixir.bootlin.com/linux/latest/source/Documentation/userspace-api/ioctl/ioctl-number.rst)):
34 //! * Number: The actual ioctl ID
39 //! Newer drivers should not generate complete integer identifiers for their `ioctl`s instead
40 //! preferring to use the 4 components above to generate the final ioctl identifier. Because of
41 //! how old `ioctl`s are, however, there are many hard-coded `ioctl` identifiers. These are
42 //! commonly referred to as "bad" in `ioctl` documentation.
44 //! Defining `ioctl`s
47 //! This library provides several `ioctl_*!` macros for binding `ioctl`s. These generate public
48 //! unsafe functions that can then be used for calling the ioctl. This macro has a few different
49 //! ways it can be used depending on the specific ioctl you're working with.
51 //! A simple `ioctl` is `SPI_IOC_RD_MODE`. This ioctl works with the SPI interface on Linux. This
52 //! specific `ioctl` reads the mode of the SPI device as a `u8`. It's declared in
54 //! macro, we know it's a `read` ioctl and can use the `ioctl_read!` macro as follows:
75 //! let res = libc::ioctl(fd, request_code_read!(SPI_IOC_MAGIC, SPI_IOC_TYPE_MODE, mem::size_of::<u8>()), data);
82 //! These are generated by assuming the return value of the ioctl is `-1` on error and everything
86 //! Writing `ioctl`s generally use pointers as their data source and these should use the
87 //! `ioctl_write_ptr!`. But in some cases an `int` is passed directly. For these `ioctl`s use the
98 //! Some `ioctl`s don't transfer any data, and those should use `ioctl_none!`. This macro
101 //! The mode for a given `ioctl` should be clear from the documentation if it has good
102 //! documentation. Otherwise it will be clear based on the macro used to generate the `ioctl`
108 //! large number of `ioctl`s and describes their argument data type.
110 //! Using "bad" `ioctl`s
113 //! As mentioned earlier, there are many old `ioctl`s that do not use the newer method of
114 //! generating `ioctl` numbers and instead use hardcoded values. These can be used with the
116 //! `ioctl`s as "bad". These are a different variant as they bypass calling the macro that generates
117 //! the ioctl number and instead use the defined value directly.
119 //! For example the `TCGETS` `ioctl` reads a `termios` data structure for a given file descriptor.
142 //! Some `ioctl`s work with entire arrays of elements. These are supported by the `ioctl_*_buf`
148 //! Again looking to the SPI `ioctl`s on Linux for an example, there is a `SPI_IOC_MESSAGE` `ioctl`
150 //! `linux/spi/spidev.h` defines a macro to calculate the `ioctl` number like:
159 //! needed to define this `ioctl` is:
182 //! let res = libc::ioctl(fd,
190 //! Finding `ioctl` Documentation
194 //! of lines defining macros which use `_IO`, `_IOR`, `_IOW`, `_IOC`, and `_IOWR`. Some `ioctl`s are
196 //! documentation in man pages (like termios' `ioctl`s which are in `tty_ioctl(4)`).
201 //! In many cases, users will wish for the functions generated by the `ioctl`
203 //! are public by default. If you wish to hide the ioctl, you will need to put
216 //! /// ioctl will fail with **EPERM**, unless the caller is root (more precisely: has the
262 /// Convert raw ioctl return value to a Nix result
271 /// Generates a wrapper function for an ioctl that passes no data to the kernel.
276 /// * The ioctl identifier
277 /// * The ioctl sequence number
285 /// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html).
289 /// The `videodev2` driver on Linux defines the `log_status` `ioctl` as:
308 convert_ioctl_res!($crate::libc::ioctl(fd, request_code_none!($ioty, $nr) as $crate::sys::ioctl::ioctl_num_type))
313 /// Generates a wrapper function for a "bad" ioctl that passes no data to the kernel.
318 /// * The ioctl request code
326 /// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html).
348 convert_ioctl_res!($crate::libc::ioctl(fd, $nr as $crate::sys::ioctl::ioctl_num_type))
353 /// Generates a wrapper function for an ioctl that reads data from the kernel.
358 /// * The ioctl identifier
359 /// * The ioctl sequence number
360 /// * The data type passed by this ioctl
368 /// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html).
386 convert_ioctl_res!($crate::libc::ioctl(fd, request_code_read!($ioty, $nr, ::std::mem::size_of::<$ty>()) as $crate::sys::ioctl::ioctl_num_type, data))
391 /// Generates a wrapper function for a "bad" ioctl that reads data from the kernel.
396 /// * The ioctl request code
397 /// * The data type passed by this ioctl
405 /// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html).
422 convert_ioctl_res!($crate::libc::ioctl(fd, $nr as $crate::sys::ioctl::ioctl_num_type, data))
427 /// Generates a wrapper function for an ioctl that writes data through a pointer to the kernel.
432 /// * The ioctl identifier
433 /// * The ioctl sequence number
434 /// * The data type passed by this ioctl
442 /// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html).
459 convert_ioctl_res!($crate::libc::ioctl(fd, request_code_write!($ioty, $nr, ::std::mem::size_of::<$ty>()) as $crate::sys::ioctl::ioctl_num_type, data))
464 /// Generates a wrapper function for a "bad" ioctl that writes data through a pointer to the kernel.
469 /// * The ioctl request code
470 /// * The data type passed by this ioctl
478 /// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html).
495 convert_ioctl_res!($crate::libc::ioctl(fd, $nr as $crate::sys::ioctl::ioctl_num_type, data))
502 /// Generates a wrapper function for a ioctl that writes an integer to the kernel.
507 /// * The ioctl identifier
508 /// * The ioctl sequence number
513 /// pub unsafe fn FUNCTION_NAME(fd: libc::c_int, data: nix::sys::ioctl::ioctl_param_type) -> Result<libc::c_int>
516 /// `nix::sys::ioctl::ioctl_param_type` depends on the OS:
520 /// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html).
534 data: $crate::sys::ioctl::ioctl_param_type)
536 convert_ioctl_res!($crate::libc::ioctl(fd, request_code_write_int!($ioty, $nr) as $crate::sys::ioctl::ioctl_num_type, data))
541 /// Generates a wrapper function for a ioctl that writes an integer to the kernel.
546 /// * The ioctl identifier
547 /// * The ioctl sequence number
552 /// pub unsafe fn FUNCTION_NAME(fd: libc::c_int, data: nix::sys::ioctl::ioctl_param_type) -> Result<libc::c_int>
555 /// `nix::sys::ioctl::ioctl_param_type` depends on the OS:
559 /// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html).
575 data: $crate::sys::ioctl::ioctl_param_type)
577 convert_ioctl_res!($crate::libc::ioctl(fd, request_code_write!($ioty, $nr, ::std::mem::size_of::<$crate::libc::c_int>()) as $crate::sys::ioctl::ioctl_num_type, data))
584 /// Generates a wrapper function for a "bad" ioctl that writes an integer to the kernel.
589 /// * The ioctl request code
597 /// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html).
621 convert_ioctl_res!($crate::libc::ioctl(fd, $nr as $crate::sys::ioctl::ioctl_num_type, data))
626 /// Generates a wrapper function for an ioctl that reads and writes data to the kernel.
631 /// * The ioctl identifier
632 /// * The ioctl sequence number
633 /// * The data type passed by this ioctl
641 /// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html).
658 convert_ioctl_res!($crate::libc::ioctl(fd, request_code_readwrite!($ioty, $nr, ::std::mem::size_of::<$ty>()) as $crate::sys::ioctl::ioctl_num_type, data))
663 /// Generates a wrapper function for a "bad" ioctl that reads and writes data to the kernel.
668 /// * The ioctl request code
669 /// * The data type passed by this ioctl
677 /// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html).
686 convert_ioctl_res!($crate::libc::ioctl(fd, $nr as $crate::sys::ioctl::ioctl_num_type, data))
691 /// Generates a wrapper function for an ioctl that reads an array of elements from the kernel.
696 /// * The ioctl identifier
697 /// * The ioctl sequence number
698 /// * The data type passed by this ioctl
706 /// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html).
715 convert_ioctl_res!($crate::libc::ioctl(fd, request_code_read!($ioty, $nr, data.len() * ::std::mem::size_of::<$ty>()) as $crate::sys::ioctl::ioctl_num_type, data))
720 /// Generates a wrapper function for an ioctl that writes an array of elements to the kernel.
725 /// * The ioctl identifier
726 /// * The ioctl sequence number
727 /// * The data type passed by this ioctl
735 /// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html).
754 convert_ioctl_res!($crate::libc::ioctl(fd, request_code_write!($ioty, $nr, data.len() * ::std::mem::size_of::<$ty>()) as $crate::sys::ioctl::ioctl_num_type, data))
759 /// Generates a wrapper function for an ioctl that reads and writes an array of elements to the kernel.
764 /// * The ioctl identifier
765 /// * The ioctl sequence number
766 /// * The data type passed by this ioctl
774 /// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html).
783 convert_ioctl_res!($crate::libc::ioctl(fd, request_code_readwrite!($ioty, $nr, data.len() * ::std::mem::size_of::<$ty>()) as $crate::sys::ioctl::ioctl_num_type, data))