Trait Ioctl

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>;
}

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 by as_ptr and produces the output as indicated by output.
• That output_from_ptr can safely take the pointer from as_ptr and cast it to the correct type, only after the ioctl call.
• That OPCODE uniquely identifies the ioctl 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 the ioctl call.

Required Associated Constants

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.

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 Associated Types

type Output

The type of the output data.

Given a pointer, one should be able to construct an instance of this type.

Required Methods

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.

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.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<'a, Opcode: CompileTimeOpcode, T> Ioctl for Updater<'a, Opcode, T>

const IS_MUTATING: bool = true

const OPCODE: Opcode = Opcode::OPCODE

type Output = ()

impl<Opcode: CompileTimeOpcode> Ioctl for IntegerSetter<Opcode>

const IS_MUTATING: bool = false

const OPCODE: Opcode = Opcode::OPCODE

type Output = ()

impl<Opcode: CompileTimeOpcode> Ioctl for NoArg<Opcode>

const IS_MUTATING: bool = false

const OPCODE: Opcode = Opcode::OPCODE

type Output = ()

impl<Opcode: CompileTimeOpcode, Input> Ioctl for Setter<Opcode, Input>

const IS_MUTATING: bool = false

const OPCODE: Opcode = Opcode::OPCODE

type Output = ()

impl<Opcode: CompileTimeOpcode, Output> Ioctl for Getter<Opcode, Output>

const IS_MUTATING: bool = true

const OPCODE: Opcode = Opcode::OPCODE

type Output = Output