COHERENT manpages
This page displays the COHERENT manpage for ioctl() [Device-dependent control].
List of available manpages
Index
ioctl() -- System Call (libc)
Device-dependent control
#include <unistd.h>
#include <header.h>
ioctl(fd, command, arg)
int fd, command; char *arg;
ioctl() lets you interact directly with a device driver. You can use it to
set or retrieve parameters for devices (line printers, communications
lines, terminals), and non-standard spacing operations for tape drives.
ioctl() acts upon the block-special file or character-special file
associated with the file descriptor fd. command points to the specific
request.
header names the header file that defines symbolic commands for the device
you wish to manipulate. Using the symbolic command definitions from the
header files promotes device independence within each device type. A
complete list of symbolic commands appears below.
arg passes a buffer of information (defined by structures in the
appropriate header files) to the driver. For any command not needing
additional information, this argument should be NULL.
Some ioctl() requests work on all files, and are not passed to any driver.
ioctl() returns -1 on errors, such as a bad file descriptor. Because the
call is device dependent, almost any other error could be returned.
Commands
The following gives the commands that can be used with ioctl(), as
extracted from COHERENT's header files. Please note the following caveats:
-> New drivers are being added continually to COHERENT, both by Mark
Williams Company and by users and third-party vendors. You should
regard the following list as being tentative at best.
-> Because the commands and arguments with with ioctl() are unique to
COHERENT's suite of device drivers, ioctl() is one of the least portable
of all system calls. If you want your code to run on multiple operating
systems, you should use ioctl() judiciously.
<sys/cdrom.h>
Header file used to manipulate a CD-ROM device. Unless otherwise noted,
arg is ignored:
CDROMPAUSE Pause playing an audio CD.
CDROMRESUME Resume playing an audio CD.
CDROMPLAYMSF Play an audio CD at a given minute-second frame (MSF)
address. arg points to an array of six bytes that give
the MSF address.
CDROMPLAYTRKIND
Play a track on an audio CD. arg points to an array of
four bytes that give, respectively, the start track, the
start index, the end track, and the end index of the
track to be played.
CDROMREADTOCHDR
Read the CD's table-of-contents header. arg points to a
structure of type cdrom_tochdr into which the header is
written.
CDROMREADTOCENTRY
Read an entry from the table-of-contents header. arg
points to a structure of type cdrom_tocentry into which
the entry is written.
CDROMSTOP Spin down the CD-ROM drive's motor.
CDROMSTART Turn on the CD-ROM drive's motor.
CDROMEJECT Eject the CD-ROM. Note that this does not work on every
variety of CD-ROM drive.
CDROMVOLCTRL Control the volume on an audio CD. arg points to an
array of four bytes that, respectively, set the the
volume on channels zero through three.
CDROMSUBCHNL Read data about a sub-channel. arg points to a structure
of type cdrom_subchnl into which the information about
the sub-channel is written.
CDROMREADMODE1 Read type-1 data. arg points to a structure into which
the data are written.
CDROMREADMODE2 Read type-2 data. arg points to a structure into which
the data are written.
<sys/fdioctl.h>
This header file is used with the floppy-disk drive:
FDFORMAT Format a track on a floppy disk. arg points to a two-
byte array that identifies, respectively, the cylinder
and head to format.
<sys/hdioctl.h>
This header file is used with AT-style hard-disk drives (i.e., IDE,
ESDI, MFM, or RLL disks). arg gives the address in user memory where
drive attributes reside, or to which they should be written:
HDGETA Get drive attributes.
HDSETA Set drive attributes.
HDGETIDEINFO Get the attributes of an IDE drive. arg should point to
a copy of the structure ide_info; this call to ioctl()
initializes the structure with the requested information.
<sys/null.h>
This header file defines ioctls that examine system memory:
NLFREE Read the amounts of memory on your system that are
available and free. arg gives the address of an object
of type FREEMEM, which is defined in header file
<null.h>. This type is an array of two longs: the
first receives the amount of available memory, and the
second the amount of free memory. For an example of a
program that uses this ioctl(), see the Lexicon entry for
freemem.
NLIDLE Read the system's idle time. arg points to an array of
two longs. The first long receives system's idle ticks;
the second, the number of ticks since system startup.
From reading these values repeatedly, you can compute the
changes in system idle time and time since startup, and
so see what the system's load is. For an example of how
to this call to ioctl(), see the Lexicon entry for idle.
<sys/sdioctl.h>
The commands defined in this header file are passed to the driver aha,
which manipulates Adaptec SCSI disks. None does anything.
<sgtty.h>
The following commands are used with the sgtty method of controlling
terminal devices. They are documented in more detail in the Lexicon
entry for sgtty. arg points to a structure of type sgttyb, which is
defined in that header file:
TIOCHPCL Hang up on last close.
TIOCGETP Get modes (old gtty).
TIOCSETP Set modes (old stty).
TIOCSETN Set modes without delay or flush.
TIOCEXCL Set exclusive use.
TIOCNXCL Set non-exclusive use.
TIOCFLUSH Flush I/O queues.
TIOCSETC Set characters.
TIOCGETC Get characters.
<stropts.h>
STREAMS commands. arg points to a STREAMS control block that will be
used to generate an M_IOCTL message.
I_NREAD Get message length, count.
I_PUSH Push named module.
I_POP Pop topmost module.
I_LOOK Get name of the topmost module.
I_FLUSH Flush read/write side.
I_SRDOPT Set stream head read mode.
I_GRDOPT Get stream head read mode.
I_STR Send ioctl() message downstream.
I_SETSIG Register for signal SIGPOLL.
I_GETSIG Return registered event mask.
I_FIND Locate named module on stream.
I_LINK Link two streams.
I_UNLINK Unlink two streams.
I_RECVFD Receive file descriptor from pipe.
I_PEEK Examine stream head data.
I_SENDFD Send file descriptor to pipe.
The following commands are not covered by iBCS2:
I_SWROPT Set stream write mode.
I_GWROPT Get stream write mode.
I_LIST Get name of all modules/drivers.
I_PLINK Create persistent link.
I_PUNLINK Undo persistent link.
I_FLUSHBAND Flush priority band.
I_CKBAND Check for existence of priority band.
I_GETBAND Get band of first message.
I_ATMARK Check whether current message is marked.
I_SETCLTIME Set drain timeout for stream.
I_GETCLTIME Get the current close timeout.
I_CANPUT Check if band is writeable.
<sys/tape.h>
Header file for interfacing with magnetic-tape devices. arg points to
an area in user space that holds additional information for the tape
device. A tape driver may recognize any of the following ioctl()
commands:
T_ERASE Erase tape.
T_LOAD Load. Not used.
T_RDSTAT Read status.
T_RST Reset.
T_RETENSION Retension tape.
T_RWD Rewind tape.
T_SBB Space block backward -- move backward by arg blocks. Not
used.
T_SBF Space Block Forward -- move forward by arg blocks. Not
used.
T_SBREC Not used.
T_SFB Space Filemark Backward -- move backwards by arg files.
T_SFF Space Filemark Forward -- move forward by arg files.
T_SFREC Not used.
T_TINIT Not used.
T_UNLOAD Unload. Not used.
T_WRFILEM Write file marks. Not used.
<termio.h>
The following commands are used with the termio method of controlling a
terminal. They are documented in more detail in the Lexicon entry for
termio. arg points to a structure of type sgttyb, which is described
above.
TCGETA Get terminal parameters.
TCSETA Set terminal parameters.
TCSETAW Wait for drain, set parameters.
TCSETAF Wait for drain, flush input, set parms.
TCSBRK Send 0.25-second break.
The following commands also take arguments when called via ioctl():
TCXONC Start/stop control: An argument of zero suspends output;
an argument of one restarts suspended output.
TCFLSH Flush queues: An argument of zero flushes the input
queue; an argument of one flushes the output queue; and
an argument of two flushes both queues.
<sys/vtkd.h>
This header file defines commands used with the keyboard driver. arg
points to a structure of type sgttyb, which is defined in header file
sgtty.h.
KDMAPDISP Map the display into user space.
KDSKBMODE Toggle the scan code xlate.
KDMEMDISP Dump a byte of virtual or physical memory.
KDGKBSTATE Get the keyboard's shift state.
KIOCINFO Determine the workstation of the virtual terminal.
KIOCSOUND Start sound generation.
KDGETLED Get the state of the keyboard's LEDs.
KDSETLED Set the state of the LEDs.
The following four ioctl() commands allow user programs to perform I/O
instructions directly, rather than going through the system-call
interface and having the kernel perform the I/O. The most common need
for these functions is in window managers and similar applications,
where the usual kernel interface would be unacceptably slow.
Normally, any user program that attempts to execute I/O instructions
directly to hardware will get an immediate SIGSEGV and be terminated.
Use of the commands below allow user-level programs to perform I/O
without being terminated. The I/O operations are available through
functions inb(), outb(), etc., which are present in the kernel-support
library /etc/conf/lib/k386.a and are documented in the manual to the
COHERENT Device Driver Kit.
Access to any of these functions may be restricted to the superuser on
some systems:
KDENABIO Allow the user process permission to perform input/output
operations to all available I/O addresses. The third
argument to ioctl() is ignored.
KDDISABIO Prohibit user processes from performing input/output
operations to all available I/O addresses. The third
argument to ioctl() is ignored. It is normal for direct
I/O to ports to be disallowed at user level. The main
reason for this call is to undo the effect of preceding
KDENABIO or KDADDIO calls.
KDADDIO Allow user-level I/O to a port. The third argument to
ioctl() is an unsigned short that gives the single
address value of the port.
KDDELIO Disallow user-level I/O to a port. The third argument to
ioctl() is an unsigned short that gives the single
address value of the port.
It is normal for direct I/O to ports to be disallowed at
user level. The main reason for this call is to undo the
effect of preceding KDADDIO calls.
Example
The following program, by Udo Munk, demonstrates how to use ioctl() to read
a mouse plugged into a serial port. It takes one argument, the name of the
port you wish to check.
#include <fcntl.h>
#include <poll.h>
#include <signal.h>
#include <stdlib.h>
#include <stdio.h>
#include <termio.h>
char *mouse;
int mouse_fd;
struct termio old_tty, new_tty;
/* do the right thing by signals */
sig_handler()
{
ioctl(mouse_fd, TCSETAF, &old_tty);
exit(EXIT_SUCCESS);
}
/* cry and die */
void fatal(message)
char *message;
{
fprintf (stderr, "%s\n", message);
exit(EXIT_FAILURE);
}
/* run the whole shebang */
main(argc, argv)
int argc; char **argv;
{
struct pollfd fds[1];
if (argc != 2)
fatal ("Usage: findmouse /dev/com[1-4]pl");
if (strncmp(argv[1], "/dev/com1pl", 11) &&
strncmp(argv[1], "/dev/com2pl", 11) &&
strncmp(argv[1], "/dev/com3pl", 11) &&
strncmp(argv[1], "/dev/com4pl", 11))
fatal ("Usage: findmouse /dev/com[1-4]pl");
mouse = argv[1];
signal(SIGINT, sig_handler);
signal(SIGQUIT, sig_handler);
signal(SIGHUP, sig_handler);
fprintf(stdout, "Trying to open %s ...\n", mouse);
if ((mouse_fd = open(mouse, O_RDONLY)) < 0)
fatal ("Cannot open this device.");
fprintf(stdout, "Success.\n");
fprintf(stdout, "Trying to read line mode of %s ...\n", mouse);
if (ioctl(mouse_fd, TCGETA, &old_tty) < 0)
fatal ("Cannot read this device'ss line mode.");
fprintf(stdout, "Success.\n");
new_tty = old_tty;
new_tty.c_cflag &= ~(CBAUD | HUPCL);
new_tty.c_cflag |= CLOCAL | B1200;
new_tty.c_iflag = IGNBRK;
new_tty.c_oflag = new_tty.c_lflag = 0;
/*
* VMIN = 0, VTIME = 0 has the same effect as setting O_NDELAY on the
* input line.
*/
new_tty.c_cc[VMIN] = 0;
new_tty.c_cc[VTIME] = 0;
/* Set up to poll the input line. */
fds->fd = mouse_fd;
fds->events = POLLIN;
fprintf(stdout, "Trying to set new line mode for %s ...\n", mouse);
if (ioctl(mouse_fd, TCSETAF, &new_tty) < 0)
fatal ("Cannot set new tty line mode");
fprintf(stdout, "Success.\n");
fprintf(stdout, "\nI'm reading from %s. To exit, type <ctrl-C>.\n",
mouse);
fprintf(stdout,
"If you see stuff on the screen when you move the mouse,\n");
fprintf(stdout,
"then you have found the mouse port.\n");
fprintf(stdout, "\nNow wiggle your mouse:\n");
for (;;) {
size_t read_count;
unsigned char mousebuf [128];
/* Block waiting for mouse input. */
if (poll (fds, 1, -1) < 0)
break;
/* Drain input in large chunks until it becomes time to block. */
while ((read_count = read (mouse_fd, mousebuf,
sizeof (mousebuf))) != 0) {
unsigned char * scan = mousebuf;
do
printf ("%02x ", * scan ++);
while (-- read_count != 0);
fflush (stdout);
}
}
}
See Also
device drivers,
exec,
getty,
header files,
libc,
open(),
read(),
sgtty,
stty(),
termio
Notes
The type of the arg to ioctl() is declared as char * mainly to improve
portability. In most cases, the actual argument type will be something
like struct sgttyb *, depending on the device and command. The actual
argument should be cast to type char * to ensure cross-machine portability.
Under COHERENT 286, the main header file for ioctl() is <sgtty.h>.
This header file is also included with COHERENT 386 for compatibility with
older applications.
