ioctl(D2DK) —

NAME

ioctl − control a character device

SYNOPSIS

#include <sys/types.h>
#include <sys/cred.h>
#include <sys/file.h>
#include <sys/errno.h>
int prefixioctl(dev_t dev, int cmd, void ∗arg, int mode, cred_t ∗crp,
int ∗rvalp);

ARGUMENTS

devDevice number.

cmdCommand argument the driver ioctl routine interprets as the operation to be performed.

argPasses parameters between the user and the driver. The interpretation of the argument is dependent on the command and the driver. For example, the argument can be an integer, or it can be the address of a user structure containing driver or hardware settings.

modeContains the file modes set when the device was opened. The driver can use this to determine if the device was opened for reading (FREAD), writing (FWRITE), etc. See open(D2DK) for a description of the values.

crpPointer to the user credential structure.

rvalpPointer to the return value for the calling process. The driver may elect to set the value if the ioctl(D2DK) succeeds.

DESCRIPTION

The ioctl(D2DK) routine provides non-STREAMS character drivers with an alternate entry point that can be used for almost any operation other than a simple transfer of data. Most often, ioctl is used to control device hardware parameters and establish the protocol used by the driver in processing data. I/O control commands are used to implement terminal settings, to format disk devices, to implement a trace driver for debugging, and to flush queues.

If the third argument, arg, is a pointer to user space, the driver can use copyin(D3DK) and copyout(D3DK) to transfer data between kernel and user space.

The ioctl routine is basically a switch statement, with each case definition corresponding to a different ioctl command identifying the action to be taken.

NOTES

This entry point is optional. The ioctl routine has user context and can sleep. STREAMS drivers do not have ioctl routines. The stream head converts I/O control commands to M_IOCTL messages, which are handled by the driver’s put(D2DK) or srv(D2DK) routine. An attempt should be made to keep the values for driver-specific I/O control commands distinct from others in the system. Each driver’s I/O control commands are unique, but it is possible for user-level code to access a driver with an I/O control command that is intended for another driver, which can have serious results. A common method to assign I/O control command values that are less apt to be duplicated is to compose the commands from some component unique to the driver (such as a module name or ID), and a counter, as in:

#define PREFIX(’h’<<16|’d’<<8)
#define COMMAND1(PREFIX|1)
#define COMMAND2(PREFIX|2)
#define COMMAND3(PREFIX|3)

RETURN VALUE

The ioctl routine should return 0 on success, or the appropriate error number on failure. The system call will usually return 0 on success or −1 on failure. However, the driver can choose to have the system call return a different value on success by passing the value through the rvalp pointer.

ERROR RETURN CODES

EAGAINTemporary resource allocation failure; try again later. Drivers can return this error when resource allocation fails, for example, kmem_alloc(D3DK) or allocb(D3DK).

EFAULTBad address. Drivers should return this error whenever a call to copyin(D3DK) or copyout(D3DK) fails.

EINTRInterrupted operation. Drivers can return this error whenever an interruptible operation is interrupted by receipt of an asynchronous signal.

EINVALInvalid argument. Drivers can return this error for operations that have invalid parameters specified.

EIOAn I/O error has occurred. Drivers can return this error when an input or output request has failed.

ENXIONo such device or address. Drivers can return this error when trying to open an invalid minor device, or when trying to perform I/O past the end of a device.

EPERMPermission denied. Drivers can return this error when the current process doesn’t have sufficient privilege for the operation attempted.

Museum