ddioctl Device Driver Entry Point

Purpose

Performs the special I/O operations requested in an ioctl or ioctlx subroutine call.

Syntax

#include <sys/device.h>

int ddioctl (devno, cmd, arg, devflag, chan, ext) dev_t devno; int cmd; void *arg; ulong devflag; chan_t chan; int ext;

Description

When a program issues an ioctl or ioctlx subroutine call, the kernel calls the ddioctl routine of the specified device driver. The ddioctl routine is responsible for performing whatever functions are requested. In addition, it must return whatever control information has been specified by the original caller of the ioctl subroutine. The cmd parameter contains the name of the operation to be performed.

Most ioctl operations depend on the specific device involved. However, all ioctl routines must respond to the following command:

Item	Description
IOCINFO	Returns a devinfo structure (defined in the /usr/include/sys/devinfo.h file) that describes the device. (Refer to the description of the special file for a particular device in the Application Programming Interface.) Only the first two fields of the data structure need to be returned if the remaining fields of the structure do not apply to the device.

The devflag parameter indicates one of several types of information. It can give conditions in which the device was opened. (These conditions can subsequently be changed by the fcntl subroutine call.) Alternatively, it can tell which of two ways the entry point was invoked:

By the file system on behalf of a using application
Directly by a kernel routine using the fp_ioctl kernel service

Thus flags in the devflag parameter have the following definitions, as defined in the /usr/include/sys/device.h file:

Item	Description
DKERNEL	Entry point called by kernel routine using the fp_ioctl service.
DREAD	Open for reading.
DWRITE	Open for writing.
DAPPEND	Open for appending.
DNDELAY	Device open in nonblocking mode.

Parameters

Item	Description
devno	Specifies the major and minor device numbers.
cmd	The parameter from the ioctl subroutine call that specifies the operation to be performed.
arg	The parameter from the ioctl subroutine call that specifies an additional argument for the cmd operation.
devflag	Specifies the device open or file control flags.
chan	Specifies the channel number.
ext	Specifies the extension parameter.

Execution Environment

The ddioctl routine is executed only in the process environment. It should provide the required serialization of its data structures by using the locking kernel services in conjunction with a private lock word defined in the driver.

Return Values

The ddioctl entry point can indicate an error condition to the user-mode application program by returning a nonzero return code. This causes the ioctl subroutine to return a value of -1 and makes the return code available to the user-mode application in the errno global variable. The error code used should be one of the values defined in the /usr/include/sys/errno.h file.

When applicable, the return values defined in the POSIX 1003.1 standard for the ioctl subroutine should be used.