SCO OpenServer

ioctl(D2oddi)

ioctl -- device-specific operations

Synopsis

   void prefixioctl(dev_t dev, int cmd, int arg, int mode);

Description

The ioctl( ) entry point routine provides character-access drivers with an alternate entry point that can be used for almost any operation other than a simple transfer of characters in and out of buffers. ioctl( ) is used to control device-specific hardware parameters and establish the protocol that the driver will use when processing data.

Arguments

dev

device number

cmd

command argument indicating the operation to be performed. The command types vary according to the device.

Except for STREAMS devices, the kernel does not interpret the command so you are free to define your own commands. ioctl commands should be defined in the driver's header file and use a scheme to ensure that each command is unique.

The STREAMS ioctl commands are defined in the <sys/stropts.h> header file and documented on the streamio manual page.

arg

parameters being passed to the driver from the user-level program through the third argument to the ioctl(S) , system call.

mode

flags passed from the open system call when the device was opened. This mode is optional. The driver can use these flags to check conditions such as whether the device was opened for reading or writing. Valid values are defined in the <file.h> header file and documented on the open manual page.

Return values

None

Usage

User-level processes access the functionality coded in the ioctl( ) routine through the ioctl system call. The kernel looks up the device's file table entry, determines that this is a character device, and looks up the entry point routine in the cdevsw table. The kernel then packages the user request and arguments as integers and passes them to the driver's ioctl( ) routine. The kernel itself does not process the passed command, so it is up to the user program and the driver to agree on what the arguments mean. To iimplement I/O control commands for a driver, two steps are required:

Define the I/O control command names and the associated value in the driver's header file and comment the commands. These must be in the header file so user-level processes can reference them as well as the driver. For ioctls that are required by standard driver interfaces, the ioctls are already defined in header files for that interface.
Code the ioctl( ) entry point routine in the driver to define the functionality for each I/O control command name that is in the header file.

WARNING: Because of the flexibility in what an ioctl( ) routine can do, it is critical that any ioctls that are used be well-documented. The definitions in the header file should be commented copiously and the supported commands and arguments should be documented on the device's HW manual page for user-level programs that need to access this functionality. Uncommented commands can be very difficult to interpret at a later time.

Drivers that use an ioctl( ) routine typically have a command to read the current I/O control command settings and at least one other that creates new settings. You can use the mode argument to determine if the device unit was opened for reading or writing by checking the FREAD or FWRITE setting.

The ioctl( ) routine is coded with instructions on the proper action to take for each command. It is basically a switch statement, with each case definition correspoding to an ioctl name to identify the action that should be taken. A command passed to the driver by the user process is an integer value associated with a corresponding command name in the header file.

Context and synchronization

User context. The driver can block and can do operations such as copyout(D3) that require access to the requesting process's user-level address space.

Hardware applicability

All

Version applicability

oddi: 1, 2, 2mp, 3, 3mp, 4, 4mp, 5, 5mp, 6, 6mp

SVR5 DDI compatibility

The ioctl(D2) entry point routine provides similar functionality for DDI drivers, although note that the syntax is different. DDI 8 drivers provide additional support for custom I/O operations with the drvctl(D2) entry point routine, which handles custom I/O operations that are requested by another driver, and the do_ioctl(D3) function, which invokes another driver's ioctl(D2) entry point routine.

External dependencies

Drivers that contain a ioctl( ) routine must have an i in the second column of the mdevice(F) file and must be configured as character drivers.

References

ioctl(S) , open(S) , streamio(M)

M_IOCTL(D7str)