ioctl(D2) ioctl(D2)
NAME
ioctl - control a character device
SYNOPSIS
#include <sys/types.h>
#include <sys/cred.h>
#include <sys/file.h>
#include <sys/errno.h>
#include <sys/ddi.h>
int prefixioctl(dev_t dev, int cmd, void *arg, int mode, cred_t *crp,
int *rvalp);
Arguments
dev Device number.
cmd Command argument the driver ioctl routine
interprets as the operation to be performed.
arg Passes 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.
mode Contains 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), and so on. See open(D2) for a
description of the values.
crp Pointer to the user credential structure.
rvalp Pointer to the return value for the calling
process. The driver may elect to set the value
if the ioctl(D2) succeeds.
DESCRIPTION
The ioctl(D2) 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.
The ioctl routine is basically a switch statement, with each
case definition corresponding to a different ioctl command
identifying the action to be taken.
Copyright 1994 Novell, Inc. Page 1
ioctl(D2) ioctl(D2)
Return Values
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.
USAGE
This entry point is optional, and is valid for character
device drivers only.
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(D3) and copyout(D3) to transfer data
between kernel and user space.
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(D2) or srv(D2) routine.
Synchronization Constraints
The ioctl routine has user context and can sleep.
Warnings
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)
Copyright 1994 Novell, Inc. Page 2
ioctl(D2) ioctl(D2)
REFERENCES
copyin(D3), copyout(D3), drv_priv(D3), errnos(D5), open(D2)
NOTICES
Portability
All processors
Applicability
ddi: 1, 2, 3, 4, 5, 5mp, 6, 6mp, 7, 7mp
Copyright 1994 Novell, Inc. Page 3