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.

   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)

REFERENCES
     copyin(D3), copyout(D3), drv_priv(D3), errnos(D5), open(D2)