diff options
Diffstat (limited to 'man/man2/ioctl_console.2')
| -rw-r--r-- | man/man2/ioctl_console.2 | 915 |
1 files changed, 915 insertions, 0 deletions
diff --git a/man/man2/ioctl_console.2 b/man/man2/ioctl_console.2 new file mode 100644 index 000000000..93a992264 --- /dev/null +++ b/man/man2/ioctl_console.2 @@ -0,0 +1,915 @@ +'\" t +.\" Copyright (c) 1995 Jim Van Zandt <jrv@vanzandt.mv.com> and aeb +.\" Sun Feb 26 11:46:23 MET 1995 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified, Sun Feb 26 15:04:20 1995, faith@cs.unc.edu +.\" Modified, Thu Apr 20 22:08:17 1995, jrv@vanzandt.mv.com +.\" Modified, Mon Sep 18 22:32:47 1995, hpa@storm.net (H. Peter Anvin) +.\" FIXME The following are not documented: +.\" KDFONTOP (since Linux 2.1.111) +.\" KDGKBDIACRUC (since Linux 2.6.24) +.\" KDSKBDIACR +.\" KDSKBDIACRUC (since Linux 2.6.24) +.\" KDKBDREP (since Linux 2.1.113) +.\" KDMAPDISP (not implemented as at Linux 2.6.27) +.\" KDUNMAPDISP (not implemented as at Linux 2.6.27) +.\" VT_LOCKSWITCH (since Linux 1.3.47, needs CAP_SYS_TTY_CONFIG) +.\" VT_UNLOCKSWITCH (since Linux 1.3.47, needs CAP_SYS_TTY_CONFIG) +.\" VT_GETHIFONTMASK (since Linux 2.6.18) +.\" +.TH ioctl_console 2 (date) "Linux man-pages (unreleased)" +.SH NAME +ioctl_console \- ioctls for console terminal and virtual consoles +.SH DESCRIPTION +The following Linux-specific +.BR ioctl (2) +operations are supported for console terminals and virtual consoles. +Each operation requires a third argument, assumed here to be +.IR argp . +.TP +.B KDGETLED +Get state of LEDs. +.I argp +points to a +.IR char . +The lower three bits +of +.I *argp +are set to the state of the LEDs, as follows: +.TS +l l l. +LED_CAP 0x04 caps lock led +LED_NUM 0x02 num lock led +LED_SCR 0x01 scroll lock led +.TE +.TP +.B KDSETLED +Set the LEDs. +The LEDs are set to correspond to the lower three bits of the +unsigned long integer in +.IR argp . +However, if a higher order bit is set, +the LEDs revert to normal: displaying the state of the +keyboard functions of caps lock, num lock, and scroll lock. +.P +Before Linux 1.1.54, the LEDs just reflected the state of the corresponding +keyboard flags, and KDGETLED/KDSETLED would also change the keyboard +flags. +Since Linux 1.1.54 the LEDs can be made to display arbitrary +information, but by default they display the keyboard flags. +The following two ioctls are used to access the keyboard flags. +.TP +.B KDGKBLED +Get keyboard flags CapsLock, NumLock, ScrollLock (not lights). +.I argp +points to a char which is set to the flag state. +The low order three bits (mask 0x7) get the current flag state, +and the low order bits of the next nibble (mask 0x70) get +the default flag state. +(Since Linux 1.1.54.) +.TP +.B KDSKBLED +Set keyboard flags CapsLock, NumLock, ScrollLock (not lights). +.I argp +is an unsigned long integer that has the desired flag state. +The low order three bits (mask 0x7) have the flag state, +and the low order bits of the next nibble (mask 0x70) have +the default flag state. +(Since Linux 1.1.54.) +.TP +.B KDGKBTYPE +Get keyboard type. +This returns the value KB_101, defined as 0x02. +.TP +.B KDADDIO +Add I/O port as valid. +Equivalent to +.IR ioperm(arg,1,1) . +.TP +.B KDDELIO +Delete I/O port as valid. +Equivalent to +.IR ioperm(arg,1,0) . +.TP +.B KDENABIO +Enable I/O to video board. +Equivalent to +.IR "ioperm(0x3b4, 0x3df\-0x3b4+1, 1)" . +.TP +.B KDDISABIO +Disable I/O to video board. +Equivalent to +.IR "ioperm(0x3b4, 0x3df\-0x3b4+1, 0)" . +.TP +.B KDSETMODE +Set text/graphics mode. +.I argp +is an unsigned integer containing one of: +.TS +l l. +KD_TEXT 0x00 +KD_GRAPHICS 0x01 +.TE +.TP +.B KDGETMODE +Get text/graphics mode. +.I argp +points to an +.I int +which is set to one +of the values shown above for +.BR KDSETMODE . +.TP +.B KDMKTONE +Generate tone of specified length. +The lower 16 bits of the unsigned long integer in +.I argp +specify the period in clock cycles, +and the upper 16 bits give the duration in msec. +If the duration is zero, the sound is turned off. +Control returns immediately. +For example, +.I argp += (125<<16) + 0x637 would specify +the beep normally associated with a ctrl-G. +(Thus since Linux 0.99pl1; broken in Linux 2.1.49-50.) +.TP +.B KIOCSOUND +Start or stop sound generation. +The lower 16 bits of +.I argp +specify the period in clock cycles +(that is, +.I argp += 1193180/frequency). +.I argp += 0 turns sound off. +In either case, control returns immediately. +.TP +.B GIO_CMAP +Get the current default color map from kernel. +.I argp +points to +a 48-byte array. +(Since Linux 1.3.3.) +.TP +.B PIO_CMAP +Change the default text-mode color map. +.I argp +points to a +48-byte array which contains, in order, the Red, Green, and Blue +values for the 16 available screen colors: 0 is off, and 255 is full +intensity. +The default colors are, in order: black, dark red, dark +green, brown, dark blue, dark purple, dark cyan, light grey, dark +grey, bright red, bright green, yellow, bright blue, bright purple, +bright cyan, and white. +(Since Linux 1.3.3.) +.TP +.B GIO_FONT +Gets 256-character screen font in expanded form. +.I argp +points to an 8192-byte array. +Fails with error code +.B EINVAL +if the +currently loaded font is a 512-character font, or if the console is +not in text mode. +.TP +.B GIO_FONTX +Gets screen font and associated information. +.I argp +points to a +.I "struct consolefontdesc" +(see +.BR PIO_FONTX ). +On call, the +.I charcount +field should be set to the maximum number of +characters that would fit in the buffer pointed to by +.IR chardata . +On return, the +.I charcount +and +.I charheight +are filled with +the respective data for the currently loaded font, and the +.I chardata +array contains the font data if the initial value of +.I charcount +indicated enough space was available; otherwise the +buffer is untouched and +.I errno +is set to +.BR ENOMEM . +(Since Linux 1.3.1.) +.TP +.B PIO_FONT +Sets 256-character screen font. +Load font into the EGA/VGA character +generator. +.I argp +points to an 8192-byte map, with 32 bytes per +character. +Only the first +.I N +of them are used for an 8x\fIN\fP font +(0 < +.I N +<= 32). +This call also invalidates the Unicode mapping. +.TP +.B PIO_FONTX +Sets screen font and associated rendering information. +.I argp +points to a +.IP +.in +4n +.EX +struct consolefontdesc { + unsigned short charcount; /* characters in font + (256 or 512) */ + unsigned short charheight; /* scan lines per + character (1\-32) */ + char *chardata; /* font data in + expanded form */ +}; +.EE +.in +.IP +If necessary, the screen will be appropriately resized, and +.B SIGWINCH +sent to the appropriate processes. +This call also invalidates the Unicode mapping. +(Since Linux 1.3.1.) +.TP +.B PIO_FONTRESET +Resets the screen font, size, and Unicode mapping to the bootup +defaults. +.I argp +is unused, but should be set to NULL to +ensure compatibility with future versions of Linux. +(Since Linux 1.3.28.) +.TP +.B GIO_SCRNMAP +Get screen mapping from kernel. +.I argp +points to an area of size +E_TABSZ, which is loaded with the font positions used to display each +character. +This call is likely to return useless information if the +currently loaded font is more than 256 characters. +.TP +.B GIO_UNISCRNMAP +Get full Unicode screen mapping from kernel. +.I argp +points to an +area of size +.IR "E_TABSZ*sizeof(unsigned short)" , +which is loaded with the +Unicodes each character represent. +A special set of Unicodes, +starting at U+F000, are used to represent "direct to font" mappings. +(Since Linux 1.3.1.) +.TP +.B PIO_SCRNMAP +Loads the "user definable" (fourth) table in the kernel which maps +bytes into console screen symbols. +.I argp +points to an area of +size E_TABSZ. +.TP +.B PIO_UNISCRNMAP +Loads the "user definable" (fourth) table in the kernel which maps +bytes into Unicodes, which are then translated into screen symbols +according to the currently loaded Unicode-to-font map. +Special Unicodes starting at U+F000 can be used to map directly to the font +symbols. +(Since Linux 1.3.1.) +.TP +.B GIO_UNIMAP +Get Unicode-to-font mapping from kernel. +.I argp +points to a +.IP +.in +4n +.EX +struct unimapdesc { + unsigned short entry_ct; + struct unipair *entries; +}; +.EE +.in +.IP +where +.I entries +points to an array of +.IP +.in +4n +.EX +struct unipair { + unsigned short unicode; + unsigned short fontpos; +}; +.EE +.in +.IP +(Since Linux 1.1.92.) +.TP +.B PIO_UNIMAP +Put unicode-to-font mapping in kernel. +.I argp +points to a +.IR "struct unimapdesc" . +(Since Linux 1.1.92) +.TP +.B PIO_UNIMAPCLR +Clear table, possibly advise hash algorithm. +.I argp +points to a +.IP +.in +4n +.EX +struct unimapinit { + unsigned short advised_hashsize; /* 0 if no opinion */ + unsigned short advised_hashstep; /* 0 if no opinion */ + unsigned short advised_hashlevel; /* 0 if no opinion */ +}; +.EE +.in +.IP +(Since Linux 1.1.92.) +.TP +.B KDGKBMODE +Gets current keyboard mode. +.I argp +points to a +.I long +which is set to one +of these: +.TS +l l. +K_RAW 0x00 /* Raw (scancode) mode */ +K_XLATE 0x01 /* Translate keycodes using keymap */ +K_MEDIUMRAW 0x02 /* Medium raw (scancode) mode */ +K_UNICODE 0x03 /* Unicode mode */ +K_OFF 0x04 /* Disabled mode; since Linux 2.6.39 */ +.\" K_OFF: commit 9fc3de9c83565fcaa23df74c2fc414bb6e7efb0a +.TE +.TP +.B KDSKBMODE +Sets current keyboard mode. +.I argp +is a +.I long +equal to one of the values shown for +.BR KDGKBMODE . +.TP +.B KDGKBMETA +Gets meta key handling mode. +.I argp +points to a +.I long +which is +set to one of these: +.TS +l l l. +K_METABIT 0x03 set high order bit +K_ESCPREFIX 0x04 escape prefix +.TE +.TP +.B KDSKBMETA +Sets meta key handling mode. +.I argp +is a +.I long +equal to one of the values shown above for +.BR KDGKBMETA . +.TP +.B KDGKBENT +Gets one entry in key translation table (keycode to action code). +.I argp +points to a +.IP +.in +4n +.EX +struct kbentry { + unsigned char kb_table; + unsigned char kb_index; + unsigned short kb_value; +}; +.EE +.in +.IP +with the first two members filled in: +.I kb_table +selects the key table (0 <= +.I kb_table +< MAX_NR_KEYMAPS), +and +.I kb_index +is the keycode (0 <= +.I kb_index +< NR_KEYS). +.I kb_value +is set to the corresponding action code, +or K_HOLE if there is no such key, +or K_NOSUCHMAP if +.I kb_table +is invalid. +.TP +.B KDSKBENT +Sets one entry in translation table. +.I argp +points to a +.IR "struct kbentry" . +.TP +.B KDGKBSENT +Gets one function key string. +.I argp +points to a +.IP +.in +4n +.EX +struct kbsentry { + unsigned char kb_func; + unsigned char kb_string[512]; +}; +.EE +.in +.IP +.I kb_string +is set to the (null-terminated) string corresponding to +the +.IR kb_func th +function key action code. +.TP +.B KDSKBSENT +Sets one function key string entry. +.I argp +points to a +.IR "struct kbsentry" . +.TP +.B KDGKBDIACR +Read kernel accent table. +.I argp +points to a +.IP +.in +4n +.EX +struct kbdiacrs { + unsigned int kb_cnt; + struct kbdiacr kbdiacr[256]; +}; +.EE +.in +.IP +where +.I kb_cnt +is the number of entries in the array, each of which +is a +.IP +.in +4n +.EX +struct kbdiacr { + unsigned char diacr; + unsigned char base; + unsigned char result; +}; +.EE +.in +.TP +.B KDGETKEYCODE +Read kernel keycode table entry (scan code to keycode). +.I argp +points to a +.IP +.in +4n +.EX +struct kbkeycode { + unsigned int scancode; + unsigned int keycode; +}; +.EE +.in +.IP +.I keycode +is set to correspond to the given +.IR scancode . +(89 <= +.I scancode +<= 255 only. +For 1 <= +.I scancode +<= 88, +.IR keycode == scancode .) +(Since Linux 1.1.63.) +.TP +.B KDSETKEYCODE +Write kernel keycode table entry. +.I argp +points to a +.IR "struct kbkeycode" . +(Since Linux 1.1.63.) +.TP +.B KDSIGACCEPT +The calling process indicates its willingness to accept the signal +.I argp +when it is generated by pressing an appropriate key combination. +(1 <= +.I argp +<= NSIG). +(See +.IR spawn_console () +in +.IR linux/drivers/char/keyboard.c .) +.TP +.B VT_OPENQRY +Returns the first available (non-opened) console. +.I argp +points to an +.I int +which is set to the +number of the vt (1 <= +.I *argp +<= MAX_NR_CONSOLES). +.TP +.B VT_GETMODE +Get mode of active vt. +.I argp +points to a +.IP +.in +4n +.EX +struct vt_mode { + char mode; /* vt mode */ + char waitv; /* if set, hang on writes if not active */ + short relsig; /* signal to raise on release op */ + short acqsig; /* signal to raise on acquisition */ + short frsig; /* unused (set to 0) */ +}; +.EE +.in +.IP +which is set to the mode of the active vt. +.I mode +is set to one of these values: +.TS +l l. +VT_AUTO auto vt switching +VT_PROCESS process controls switching +VT_ACKACQ acknowledge switch +.TE +.TP +.B VT_SETMODE +Set mode of active vt. +.I argp +points to a +.IR "struct vt_mode" . +.TP +.B VT_GETSTATE +Get global vt state info. +.I argp +points to a +.IP +.in +4n +.EX +struct vt_stat { + unsigned short v_active; /* active vt */ + unsigned short v_signal; /* signal to send */ + unsigned short v_state; /* vt bit mask */ +}; +.EE +.in +.IP +For each vt in use, the corresponding bit in the +.I v_state +member is set. +(Linux 1.0 through Linux 1.1.92.) +.TP +.B VT_RELDISP +Release a display. +.TP +.B VT_ACTIVATE +Switch to vt +.I argp +(1 <= +.I argp +<= MAX_NR_CONSOLES). +.TP +.B VT_WAITACTIVE +Wait until vt +.I argp +has been activated. +.TP +.B VT_DISALLOCATE +Deallocate the memory associated with vt +.IR argp . +(Since Linux 1.1.54.) +.TP +.B VT_RESIZE +Set the kernel's idea of screensize. +.I argp +points to a +.IP +.in +4n +.EX +struct vt_sizes { + unsigned short v_rows; /* # rows */ + unsigned short v_cols; /* # columns */ + unsigned short v_scrollsize; /* no longer used */ +}; +.EE +.in +.IP +Note that this does not change the videomode. +See +.BR resizecons (8). +(Since Linux 1.1.54.) +.TP +.B VT_RESIZEX +Set the kernel's idea of various screen parameters. +.I argp +points to a +.IP +.in +4n +.EX +struct vt_consize { + unsigned short v_rows; /* number of rows */ + unsigned short v_cols; /* number of columns */ + unsigned short v_vlin; /* number of pixel rows + on screen */ + unsigned short v_clin; /* number of pixel rows + per character */ + unsigned short v_vcol; /* number of pixel columns + on screen */ + unsigned short v_ccol; /* number of pixel columns + per character */ +}; +.EE +.in +.IP +Any parameter may be set to zero, indicating "no change", but if +multiple parameters are set, they must be self-consistent. +Note that this does not change the videomode. +See +.BR resizecons (8). +(Since Linux 1.3.3.) +.P +The action of the following ioctls depends on the first byte in the struct +pointed to by +.IR argp , +referred to here as the +.IR subcode . +These are legal only for the superuser or the owner of the current terminal. +Symbolic +.IR subcode s +are available in +.I <linux/tiocl.h> +since +Linux 2.5.71. +.TP +.BR TIOCLINUX ", " subcode = 0 +Dump the screen. +Disappeared in Linux 1.1.92. +(With Linux 1.1.92 or later, read from +.I /dev/vcsN +or +.I /dev/vcsaN +instead.) +.TP +.BR TIOCLINUX ", " subcode = 1 +Get task information. +Disappeared in Linux 1.1.92. +.TP +.BR TIOCLINUX ", " subcode = TIOCL_SETSEL +Set selection. +.I argp +points to a +.IP +.in +4n +.EX +struct { + char subcode; + short xs, ys, xe, ye; + short sel_mode; +}; +.EE +.in +.IP +.I xs +and +.I ys +are the starting column and row. +.I xe +and +.I ye +are the ending +column and row. +(Upper left corner is row=column=1.) +.I sel_mode +is 0 for character-by-character selection, +1 for word-by-word selection, +or 2 for line-by-line selection. +The indicated screen characters are highlighted and saved +in a kernel buffer. +.IP +Since Linux 6.7, using this subcode requires the +.B CAP_SYS_ADMIN +capability. +.TP +.BR TIOCLINUX ", " subcode = TIOCL_PASTESEL +Paste selection. +The characters in the selection buffer are +written to +.IR fd . +.IP +Since Linux 6.7, using this subcode requires the +.B CAP_SYS_ADMIN +capability. +.TP +.BR TIOCLINUX ", " subcode = TIOCL_UNBLANKSCREEN +Unblank the screen. +.TP +.BR TIOCLINUX ", " subcode = TIOCL_SELLOADLUT +Sets contents of a 256-bit look up table defining characters in a "word", +for word-by-word selection. +(Since Linux 1.1.32.) +.IP +Since Linux 6.7, using this subcode requires the +.B CAP_SYS_ADMIN +capability. +.TP +.BR TIOCLINUX ", " subcode = TIOCL_GETSHIFTSTATE +.I argp +points to a char which is set to the value of the kernel +variable +.IR shift_state . +(Since Linux 1.1.32.) +.TP +.BR TIOCLINUX ", " subcode = TIOCL_GETMOUSEREPORTING +.I argp +points to a char which is set to the value of the kernel +variable +.IR report_mouse . +(Since Linux 1.1.33.) +.TP +.BR TIOCLINUX ", " subcode = 8 +Dump screen width and height, cursor position, and all the +character-attribute pairs. +(Linux 1.1.67 through Linux 1.1.91 only. +With Linux 1.1.92 or later, read from +.I /dev/vcsa* +instead.) +.TP +.BR TIOCLINUX ", " subcode = 9 +Restore screen width and height, cursor position, and all the +character-attribute pairs. +(Linux 1.1.67 through Linux 1.1.91 only. +With Linux 1.1.92 or later, write to +.I /dev/vcsa* +instead.) +.TP +.BR TIOCLINUX ", " subcode = TIOCL_SETVESABLANK +Handles the Power Saving +feature of the new generation of monitors. +VESA screen blanking mode is set to +.IR argp[1] , +which governs what +screen blanking does: +.RS +.TP +.B 0 +Screen blanking is disabled. +.TP +.B 1 +The current video adapter +register settings are saved, then the controller is programmed to turn off +the vertical synchronization pulses. +This puts the monitor into "standby" mode. +If your monitor has an Off_Mode timer, then +it will eventually power down by itself. +.TP +.B 2 +The current settings are saved, then both the vertical and horizontal +synchronization pulses are turned off. +This puts the monitor into "off" mode. +If your monitor has no Off_Mode timer, +or if you want your monitor to power down immediately when the +blank_timer times out, then you choose this option. +.RI ( Caution: +Powering down frequently will damage the monitor.) +(Since Linux 1.1.76.) +.RE +.TP +.BR TIOCLINUX ", " subcode = TIOCL_SETKMSGREDIRECT +Change target of kernel messages ("console"): +by default, and if this is set to +.BR 0 , +messages are written to the currently active VT. +The VT to write to is a single byte following +.BR subcode . +(Since Linux 2.5.36.) +.TP +.BR TIOCLINUX ", " subcode = TIOCL_GETFGCONSOLE +Returns the number of VT currently in foreground. +(Since Linux 2.5.36.) +.TP +.BR TIOCLINUX ", " subcode = TIOCL_SCROLLCONSOLE +Scroll the foreground VT by the specified amount of +.I lines +down, +or half the screen if +.BR 0 . +.I lines +is *(((int32_t *)&subcode) + 1). +(Since Linux 2.5.67.) +.TP +.BR TIOCLINUX ", " subcode = TIOCL_BLANKSCREEN +Blank the foreground VT, ignoring "pokes" (typing): +can only be unblanked explicitly (by switching VTs, to text mode, etc.). +(Since Linux 2.5.71.) +.TP +.BR TIOCLINUX ", " subcode = TIOCL_BLANKEDSCREEN +Returns the number of VT currently blanked, +.B 0 +if none. +(Since Linux 2.5.71.) +.TP +.BR TIOCLINUX ", " subcode = 16 +Never used. +.TP +.BR TIOCLINUX ", " subcode = TIOCL_GETKMSGREDIRECT +Returns target of kernel messages. +(Since Linux 2.6.17.) +.SH RETURN VALUE +On success, 0 is returned (except where indicated). +On failure, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +The file descriptor is invalid. +.TP +.B EINVAL +The file descriptor or +.I argp +is invalid. +.TP +.B ENOTTY +The file descriptor is not associated with a character special device, +or the specified operation does not apply to it. +.TP +.B EPERM +Insufficient permission. +.SH NOTES +.BR Warning : +Do not regard this man page as documentation of the Linux console ioctls. +This is provided for the curious only, as an alternative to reading the +source. +Ioctl's are undocumented Linux internals, liable to be changed +without warning. +(And indeed, this page more or less describes the +situation as of kernel version 1.1.94; +there are many minor and not-so-minor +differences with earlier versions.) +.P +Very often, ioctls are introduced for communication between the +kernel and one particular well-known program (fdisk, hdparm, setserial, +tunelp, loadkeys, selection, setfont, etc.), and their behavior will be +changed when required by this particular program. +.P +Programs using these ioctls will not be portable to other versions +of UNIX, will not work on older versions of Linux, and will not work +on future versions of Linux. +.P +Use POSIX functions. +.SH SEE ALSO +.BR dumpkeys (1), +.BR kbd_mode (1), +.BR loadkeys (1), +.BR mknod (1), +.BR setleds (1), +.BR setmetamode (1), +.BR execve (2), +.BR fcntl (2), +.BR ioctl_tty (2), +.BR ioperm (2), +.BR termios (3), +.BR console_codes (4), +.BR mt (4), +.BR sd (4), +.BR tty (4), +.BR ttyS (4), +.BR vcs (4), +.BR vcsa (4), +.BR charsets (7), +.BR mapscrn (8), +.BR resizecons (8), +.BR setfont (8) +.P +.IR /usr/include/linux/kd.h , +.I /usr/include/linux/vt.h |