pub unsafe trait Ioctl {
type Output;
const OPCODE: Opcode;
const IS_MUTATING: bool;
// Required methods
fn as_ptr(&mut self) -> *mut c_void;
unsafe fn output_from_ptr(
out: IoctlOutput,
extract_output: *mut c_void,
) -> Result<Self::Output>;
}
Expand description
A trait defining the properties of an ioctl
command.
Objects implementing this trait can be passed to ioctl
to make an
ioctl
call. The contents of the object represent the inputs to the
ioctl
call. The inputs must be convertible to a pointer through the
as_ptr
method. In most cases, this involves either casting a number to a
pointer, or creating a pointer to the actual data. The latter case is
necessary for ioctl
calls that modify userspace data.
§Safety
This trait is unsafe to implement because it is impossible to guarantee
that the ioctl
call is safe. The ioctl
call may be proprietary, or it
may be unsafe to call in certain circumstances.
By implementing this trait, you guarantee that:
- The
ioctl
call expects the input provided byas_ptr
and produces the output as indicated byoutput
. - That
output_from_ptr
can safely take the pointer fromas_ptr
and cast it to the correct type, only after theioctl
call. - That
OPCODE
uniquely identifies theioctl
call. - That, for whatever platforms you are targeting, the
ioctl
call is safe to make. - If
IS_MUTATING
is false, that no userspace data will be modified by theioctl
call.
Required Associated Types§
Required Associated Constants§
sourceconst OPCODE: Opcode
const OPCODE: Opcode
The opcode used by this ioctl
command.
There are different types of opcode depending on the operation. See
documentation for the Opcode
struct for more information.
sourceconst IS_MUTATING: bool
const IS_MUTATING: bool
Does the ioctl
mutate any data in the userspace?
If the ioctl
call does not mutate any data in the userspace, then
making this false
enables optimizations that can make the call
faster. When in doubt, set this to true
.
§Safety
This should only be set to false
if the ioctl
call does not mutate
any data in the userspace. Undefined behavior may occur if this is set
to false
when it should be true
.
Required Methods§
sourcefn as_ptr(&mut self) -> *mut c_void
fn as_ptr(&mut self) -> *mut c_void
Get a pointer to the data to be passed to the ioctl
command.
See trait-level documentation for more information.
sourceunsafe fn output_from_ptr(
out: IoctlOutput,
extract_output: *mut c_void,
) -> Result<Self::Output>
unsafe fn output_from_ptr( out: IoctlOutput, extract_output: *mut c_void, ) -> Result<Self::Output>
Cast the output data to the correct type.
§Safety
The extract_output
value must be the resulting value after a
successful ioctl
call, and out
is the direct return value of an
ioctl
call that did not fail. In this case extract_output
is the
pointer that was passed to the ioctl
call.