IOCTL

The IOCTL function provides a thin wrapper over the UNIX ioctl(2) system call. IOTCL performs special functions on the specified file. The set of functions actually available depends on your version of UNIX and the type of file (tty, tape, disk file, etc.) referred to.

To use IOCTL, read the C programmer’s documentation describing the ioctl(2) function for the desired device and convert all constants and data to their IDL equivalents.

Examples

The following example prints the size of the terminal being used by the current IDL session. It is known to work under SunOS 4.1.2. Changes may be necessary for other operating systems or even other versions of SunOS.

; Variable to receive result. This structure is described in

; Section 4 of the SunOS manual pages under termios(4):

winsize = {row:0u, col:0u, xpixel:0u, ypixel:0u}

; The request code for obtaining the tty size, as determined by

; reading the termios(4) documentation, and reading the system

; include files in the /usr/include/sys directory:

TIOCGWINSZ = 21608L

; Make the information request. -1 is the IDL logical file unit for

; the standard output:

ret = IOCTL(-1, TIOCGWINSZ, winsize)

; Output the results:

PRINT,winsize.row, winsize.col, $

format='("TTY has ", I0," rows and ", I0," columns.")'

The following points should be noted in this example:

Even though we only want the number of rows and columns, we must include all the fields required by the TIOCGWINSIZ ioctl in the winsize variable (as documented in the termio(4) manual page). Not providing a large enough result buffer would cause IDL’s memory to be corrupted.
The value of TIOCGWINSZ was determined by examining the system header files provided in the /usr/include/sys directory. Such values are not always portable between major operating system releases.

Syntax

Result = IOCTL( File_Unit [, Request, Arg] [, /BY_VALUE] [, /MT_OFFLINE] [, /MT_REWIND] [, MT_SKIP_FILE=[-]number_of_files] [, MT_SKIP_RECORD=[-]number_of_records] [, /MT_WEOF] [, /SUPPRESS_ERROR] )

Return Value

The value returned by the system ioctl function is returned as the value of the IDL IOCTL function.

Arguments

File_Unit

The IDL logical unit number (LUN) for the open file on which the ioctl request is made.

Request

A longword integer that specifies the ioctl request code. These codes are usually contained in C language header files provided by the operating system, and are not generally portable between UNIX versions. If one of the “MT” keywords is used, this argument can be omitted.

Arg

A named variable through which data if passed to and from ioctl. IOCTL requests usually request data from the system or supply the system with information. The user must make Arg the correct type and size. Errors in typing or sizing Arg can corrupt the IDL address space and/or make IDL crash. If one of the MT keywords is used, this argument can be omitted.

Keywords

Note that the keywords below that start with “MT” can be used to issue commonly used magnetic tape ioctl() calls. When these keywords are used, the Request and Arg arguments are ignored and an be omitted. Magnetic tape operations not available via these keywords can still be executed by supplying the appropriate Request and Arg values. When issuing magnetic tape IOCTL calls different devices have different rules for which ioctl calls are allowed, and when. The documentation for your computer system explains those rules.

BY_VALUE

If this keyword is set, Arg is converted to a scalar longword and this longword is passed by value. Normally, Arg is passed to ioctl by reference (i.e., by address).

MT_OFFLINE

Set this keyword to rewind and unload a tape.

MT_REWIND

Set this keyword to rewind a tape.

MT_SKIP_FILE

Use this keyword to skip files on a tape. A positive value skips forward that number of files. A negative value skips backward.

MT_SKIP_RECORD

Use this keyword to skip records on tape. A positive value skips forward that number of files. A negative value skips backward.

MT_WEOF

Set this keyword to write an EOF (“tape mark”) on the tape at the current location.

SUPPRESS_ERROR

Set this keyword to log errors quietly and cause a value of -1 to be returned. The default is for IDL to notice any failures associated with the use of ioctl and issue the appropriate IDL error and halt execution.

Version History

Pre 4.0

Introduced