1IOCTL_CONSOLE(2) Linux Programmer's Manual IOCTL_CONSOLE(2)
2
6 ioctl_console - ioctls for console terminal and virtual consoles
7
9 The following Linux-specific ioctl(2) requests are supported for con‐
10 sole terminals and virtual consoles. Each requires a third argument,
11 assumed here to be argp.
12 KDGETLED
14 Get state of LEDs. argp points to a char. The lower three bits
15 of *argp are set to the state of the LEDs, as follows:
16 LED_CAP 0x04 caps lock led
18 LED_NUM 0x02 num lock led
19 LED_SCR 0x01 scroll lock led
20 KDSETLED
22 Set the LEDs. The LEDs are set to correspond to the lower three
23 bits of the unsigned long integer in argp. However, if a higher
24 order bit is set, the LEDs revert to normal: displaying the
25 state of the keyboard functions of caps lock, num lock, and
26 scroll lock.
27 Before Linux 1.1.54, the LEDs just reflected the state of the corre‐
29 sponding keyboard flags, and KDGETLED/KDSETLED would also change the
30 keyboard flags. Since Linux 1.1.54 the LEDs can be made to display
31 arbitrary information, but by default they display the keyboard flags.
32 The following two ioctls are used to access the keyboard flags.
33 KDGKBLED
35 Get keyboard flags CapsLock, NumLock, ScrollLock (not lights).
36 argp points to a char which is set to the flag state. The low
37 order three bits (mask 0x7) get the current flag state, and the
38 low order bits of the next nibble (mask 0x70) get the default
39 flag state. (Since Linux 1.1.54.)
40 KDSKBLED
42 Set keyboard flags CapsLock, NumLock, ScrollLock (not lights).
43 argp is an unsigned long integer that has the desired flag
44 state. The low order three bits (mask 0x7) have the flag state,
45 and the low order bits of the next nibble (mask 0x70) have the
46 default flag state. (Since Linux 1.1.54.)
47 KDGKBTYPE
49 Get keyboard type. This returns the value KB_101, defined as
50 0x02.
51 KDADDIO
53 Add I/O port as valid. Equivalent to ioperm(arg,1,1).
54 KDDELIO
56 Delete I/O port as valid. Equivalent to ioperm(arg,1,0).
57 KDENABIO
59 Enable I/O to video board. Equivalent to ioperm(0x3b4,
60 0x3df-0x3b4+1, 1).
61 KDDISABIO
63 Disable I/O to video board. Equivalent to ioperm(0x3b4,
64 0x3df-0x3b4+1, 0).
65 KDSETMODE
67 Set text/graphics mode. argp is an unsigned integer containing
68 one of:
69 KD_TEXT 0x00
71 KD_GRAPHICS 0x01
72 KDGETMODE
74 Get text/graphics mode. argp points to an int which is set to
75 one of the values shown above for KDSETMODE.
76 KDMKTONE
78 Generate tone of specified length. The lower 16 bits of the
79 unsigned long integer in argp specify the period in clock
80 cycles, and the upper 16 bits give the duration in msec. If the
81 duration is zero, the sound is turned off. Control returns
82 immediately. For example, argp = (125<<16) + 0x637 would spec‐
83 ify the beep normally associated with a ctrl-G. (Thus since
84 Linux 0.99pl1; broken in Linux 2.1.49-50.)
85 KIOCSOUND
87 Start or stop sound generation. The lower 16 bits of argp spec‐
88 ify the period in clock cycles (that is, argp = 1193180/fre‐
89 quency). argp = 0 turns sound off. In either case, control
90 returns immediately.
91 GIO_CMAP
93 Get the current default color map from kernel. argp points to a
94 48-byte array. (Since Linux 1.3.3.)
95 PIO_CMAP
97 Change the default text-mode color map. argp points to a
98 48-byte array which contains, in order, the Red, Green, and Blue
99 values for the 16 available screen colors: 0 is off, and 255 is
100 full intensity. The default colors are, in order: black, dark
101 red, dark green, brown, dark blue, dark purple, dark cyan, light
102 grey, dark grey, bright red, bright green, yellow, bright blue,
103 bright purple, bright cyan and white. (Since Linux 1.3.3.)
104 GIO_FONT
106 Gets 256-character screen font in expanded form. argp points to
107 an 8192-byte array. Fails with error code EINVAL if the cur‐
108 rently loaded font is a 512-character font, or if the console is
109 not in text mode.
110 GIO_FONTX
112 Gets screen font and associated information. argp points to a
113 struct consolefontdesc (see PIO_FONTX). On call, the charcount
114 field should be set to the maximum number of characters that
115 would fit in the buffer pointed to by chardata. On return, the
116 charcount and charheight are filled with the respective data for
117 the currently loaded font, and the chardata array contains the
118 font data if the initial value of charcount indicated enough
119 space was available; otherwise the buffer is untouched and errno
120 is set to ENOMEM. (Since Linux 1.3.1.)
121 PIO_FONT
123 Sets 256-character screen font. Load font into the EGA/VGA
124 character generator. argp points to an 8192-byte map, with 32
125 bytes per character. Only the first N of them are used for an
126 8xN font (0 < N <= 32). This call also invalidates the Unicode
127 mapping.
128 PIO_FONTX
130 Sets screen font and associated rendering information. argp
131 points to a
132 struct consolefontdesc {
134 unsigned short charcount; /* characters in font
135 (256 or 512) */
136 unsigned short charheight; /* scan lines per
137 character (1-32) */
138 char *chardata; /* font data in
139 expanded form */
140 };
141 If necessary, the screen will be appropriately resized, and SIG‐
143 WINCH sent to the appropriate processes. This call also invali‐
144 dates the Unicode mapping. (Since Linux 1.3.1.)
145 PIO_FONTRESET
147 Resets the screen font, size and Unicode mapping to the bootup
148 defaults. argp is unused, but should be set to NULL to ensure
149 compatibility with future versions of Linux. (Since Linux
150 1.3.28.)
151 GIO_SCRNMAP
153 Get screen mapping from kernel. argp points to an area of size
154 E_TABSZ, which is loaded with the font positions used to display
155 each character. This call is likely to return useless informa‐
156 tion if the currently loaded font is more than 256 characters.
157 GIO_UNISCRNMAP
159 Get full Unicode screen mapping from kernel. argp points to an
160 area of size E_TABSZ*sizeof(unsigned short), which is loaded
161 with the Unicodes each character represent. A special set of
162 Unicodes, starting at U+F000, are used to represent "direct to
163 font" mappings. (Since Linux 1.3.1.)
164 PIO_SCRNMAP
166 Loads the "user definable" (fourth) table in the kernel which
167 maps bytes into console screen symbols. argp points to an area
168 of size E_TABSZ.
169 PIO_UNISCRNMAP
171 Loads the "user definable" (fourth) table in the kernel which
172 maps bytes into Unicodes, which are then translated into screen
173 symbols according to the currently loaded Unicode-to-font map.
174 Special Unicodes starting at U+F000 can be used to map directly
175 to the font symbols. (Since Linux 1.3.1.)
176 GIO_UNIMAP
178 Get Unicode-to-font mapping from kernel. argp points to a
179 struct unimapdesc {
181 unsigned short entry_ct;
182 struct unipair *entries;
183 };
184 where entries points to an array of ,IP
186 struct unipair {
187 unsigned short unicode;
188 unsigned short fontpos;
189 };
190 (Since Linux 1.1.92.)
192 PIO_UNIMAP
194 Put unicode-to-font mapping in kernel. argp points to a struct
195 unimapdesc. (Since Linux 1.1.92)
196 PIO_UNIMAPCLR
198 Clear table, possibly advise hash algorithm. argp points to a
199 struct unimapinit {
201 unsigned short advised_hashsize; /* 0 if no opinion */
202 unsigned short advised_hashstep; /* 0 if no opinion */
203 unsigned short advised_hashlevel; /* 0 if no opinion */
204 };
205 (Since Linux 1.1.92.)
207 KDGKBMODE
209 Gets current keyboard mode. argp points to a long which is set
210 to one of these:
211 K_RAW 0x00 /* Raw (scancode) mode */
213 K_XLATE 0x01 /* Translate keycodes using keymap */
214 K_MEDIUMRAW 0x02 /* Medium raw (scancode) mode */
215 K_UNICODE 0x03 /* Unicode mode */
216 K_OFF 0x04 /* Disabled mode; since Linux 2.6.39 */
217 KDSKBMODE
219 Sets current keyboard mode. argp is a long equal to one of the
220 values shown for KDGKBMODE.
221 KDGKBMETA
223 Gets meta key handling mode. argp points to a long which is set
224 to one of these:
225 K_METABIT 0x03 set high order bit
227 K_ESCPREFIX 0x04 escape prefix
228 KDSKBMETA
230 Sets meta key handling mode. argp is a long equal to one of the
231 values shown above for KDGKBMETA.
232 KDGKBENT
234 Gets one entry in key translation table (keycode to action
235 code). argp points to a
236 struct kbentry {
238 unsigned char kb_table;
239 unsigned char kb_index;
240 unsigned short kb_value;
241 };
242 with the first two members filled in: kb_table selects the key
244 table (0 <= kb_table < MAX_NR_KEYMAPS), and kb_index is the key‐
245 code (0 <= kb_index < NR_KEYS). kb_value is set to the corre‐
246 sponding action code, or K_HOLE if there is no such key, or
247 K_NOSUCHMAP if kb_table is invalid.
248 KDSKBENT
250 Sets one entry in translation table. argp points to a struct
251 kbentry.
252 KDGKBSENT
254 Gets one function key string. argp points to a
255 struct kbsentry {
257 unsigned char kb_func;
258 unsigned char kb_string[512];
259 };
260 kb_string is set to the (null-terminated) string corresponding
262 to the kb_functh function key action code.
263 KDSKBSENT
265 Sets one function key string entry. argp points to a struct
266 kbsentry.
267 KDGKBDIACR
269 Read kernel accent table. argp points to a
270 struct kbdiacrs {
272 unsigned int kb_cnt;
273 struct kbdiacr kbdiacr[256];
274 };
275 where kb_cnt is the number of entries in the array, each of
277 which is a
278 struct kbdiacr {
280 unsigned char diacr;
281 unsigned char base;
282 unsigned char result;
283 };
284 KDGETKEYCODE
286 Read kernel keycode table entry (scan code to keycode). argp
287 points to a
288 struct kbkeycode {
290 unsigned int scancode;
291 unsigned int keycode;
292 };
293 keycode is set to correspond to the given scancode. (89 <=
295 scancode <= 255 only. For 1 <= scancode <= 88, keycode==scan‐
296 code.) (Since Linux 1.1.63.)
297 KDSETKEYCODE
299 Write kernel keycode table entry. argp points to a struct kbk‐
300 eycode. (Since Linux 1.1.63.)
301 KDSIGACCEPT
303 The calling process indicates its willingness to accept the sig‐
304 nal argp when it is generated by pressing an appropriate key
305 combination. (1 <= argp <= NSIG). (See spawn_console() in
306 linux/drivers/char/keyboard.c.)
307 VT_OPENQRY
309 Returns the first available (non-opened) console. argp points
310 to an int which is set to the number of the vt (1 <= *argp <=
311 MAX_NR_CONSOLES).
312 VT_GETMODE
314 Get mode of active vt. argp points to a
315 struct vt_mode {
317 char mode; /* vt mode */
318 char waitv; /* if set, hang on writes if not active */
319 short relsig; /* signal to raise on release req */
320 short acqsig; /* signal to raise on acquisition */
321 short frsig; /* unused (set to 0) */
322 };
323 which is set to the mode of the active vt. mode is set to one
325 of these values:
326 VT_AUTO auto vt switching
328 VT_PROCESS process controls switching
329 VT_ACKACQ acknowledge switch
330 VT_SETMODE
332 Set mode of active vt. argp points to a struct vt_mode.
333 VT_GETSTATE
335 Get global vt state info. argp points to a
336 struct vt_stat {
338 unsigned short v_active; /* active vt */
339 unsigned short v_signal; /* signal to send */
340 unsigned short v_state; /* vt bit mask */
341 };
342 For each vt in use, the corresponding bit in the v_state member
344 is set. (Kernels 1.0 through 1.1.92.)
345 VT_RELDISP
347 Release a display.
348 VT_ACTIVATE
350 Switch to vt argp (1 <= argp <= MAX_NR_CONSOLES).
351 VT_WAITACTIVE
353 Wait until vt argp has been activated.
354 VT_DISALLOCATE
356 Deallocate the memory associated with vt argp. (Since Linux
357 1.1.54.)
358 VT_RESIZE
360 Set the kernel's idea of screensize. argp points to a
361 struct vt_sizes {
363 unsigned short v_rows; /* # rows */
364 unsigned short v_cols; /* # columns */
365 unsigned short v_scrollsize; /* no longer used */
366 };
367 Note that this does not change the videomode. See resize‐
369 cons(8). (Since Linux 1.1.54.)
370 VT_RESIZEX
372 Set the kernel's idea of various screen parameters. argp points
373 to a
374 struct vt_consize {
376 unsigned short v_rows; /* number of rows */
377 unsigned short v_cols; /* number of columns */
378 unsigned short v_vlin; /* number of pixel rows
379 on screen */
380 unsigned short v_clin; /* number of pixel rows
381 per character */
382 unsigned short v_vcol; /* number of pixel columns
383 on screen */
384 unsigned short v_ccol; /* number of pixel columns
385 per character */
386 };
387 Any parameter may be set to zero, indicating "no change", but if
389 multiple parameters are set, they must be self-consistent. Note
390 that this does not change the videomode. See resizecons(8).
391 (Since Linux 1.3.3.)
392 The action of the following ioctls depends on the first byte in the
394 struct pointed to by argp, referred to here as the subcode. These are
395 legal only for the superuser or the owner of the current terminal.
396 TIOCLINUX, subcode=0
398 Dump the screen. Disappeared in Linux 1.1.92. (With kernel
399 1.1.92 or later, read from /dev/vcsN or /dev/vcsaN instead.)
400 TIOCLINUX, subcode=1
402 Get task information. Disappeared in Linux 1.1.92.
403 TIOCLINUX, subcode=2
405 Set selection. argp points to a
406 struct {
408 char subcode;
409 short xs, ys, xe, ye;
410 short sel_mode;
411 };
412 xs and ys are the starting column and row. xe and ye are the
414 ending column and row. (Upper left corner is row=column=1.)
415 sel_mode is 0 for character-by-character selection, 1 for word-
416 by-word selection, or 2 for line-by-line selection. The indi‐
417 cated screen characters are highlighted and saved in the static
418 array sel_buffer in devices/char/console.c.
419 TIOCLINUX, subcode=3
421 Paste selection. The characters in the selection buffer are
422 written to fd.
423 TIOCLINUX, subcode=4
425 Unblank the screen.
426 TIOCLINUX, subcode=5
428 Sets contents of a 256-bit look up table defining characters in
429 a "word", for word-by-word selection. (Since Linux 1.1.32.)
430 TIOCLINUX, subcode=6
432 argp points to a char which is set to the value of the kernel
433 variable shift_state. (Since Linux 1.1.32.)
434 TIOCLINUX, subcode=7
436 argp points to a char which is set to the value of the kernel
437 variable report_mouse. (Since Linux 1.1.33.)
438 TIOCLINUX, subcode=8
440 Dump screen width and height, cursor position, and all the char‐
441 acter-attribute pairs. (Kernels 1.1.67 through 1.1.91 only.
442 With kernel 1.1.92 or later, read from /dev/vcsa* instead.)
443 TIOCLINUX, subcode=9
445 Restore screen width and height, cursor position, and all the
446 character-attribute pairs. (Kernels 1.1.67 through 1.1.91 only.
447 With kernel 1.1.92 or later, write to /dev/vcsa* instead.)
448 TIOCLINUX, subcode=10
450 Handles the Power Saving feature of the new generation of moni‐
451 tors. VESA screen blanking mode is set to argp[1], which gov‐
452 erns what screen blanking does:
453 0: Screen blanking is disabled.
455 1: The current video adapter register settings are saved, then
457 the controller is programmed to turn off the vertical syn‐
458 chronization pulses. This puts the monitor into "standby"
459 mode. If your monitor has an Off_Mode timer, then it will
460 eventually power down by itself.
461 2: The current settings are saved, then both the vertical and
463 horizontal synchronization pulses are turned off. This puts
464 the monitor into "off" mode. If your monitor has no Off_Mode
465 timer, or if you want your monitor to power down immediately
466 when the blank_timer times out, then you choose this option.
467 (Caution: Powering down frequently will damage the monitor.)
468 (Since Linux 1.1.76.)
469
471 On success, 0 is returned. On error, -1 is returned, and errno is set.
472
474 errno may take on these values:
475 EBADF The file descriptor is invalid.
477 EINVAL The file descriptor or argp is invalid.
479 ENOTTY The file descriptor is not associated with a character special
481 device, or the specified request does not apply to it.
482 EPERM Insufficient permission.
484
486 Warning: Do not regard this man page as documentation of the Linux con‐
487 sole ioctls. This is provided for the curious only, as an alternative
488 to reading the source. Ioctl's are undocumented Linux internals,
489 liable to be changed without warning. (And indeed, this page more or
490 less describes the situation as of kernel version 1.1.94; there are
491 many minor and not-so-minor differences with earlier versions.)
492 Very often, ioctls are introduced for communication between the kernel
494 and one particular well-known program (fdisk, hdparm, setserial,
495 tunelp, loadkeys, selection, setfont, etc.), and their behavior will be
496 changed when required by this particular program.
497 Programs using these ioctls will not be portable to other versions of
499 UNIX, will not work on older versions of Linux, and will not work on
500 future versions of Linux.
501 Use POSIX functions.
503
505 dumpkeys(1), kbd_mode(1), loadkeys(1), mknod(1), setleds(1), setmeta‐
506 mode(1), execve(2), fcntl(2), ioctl_tty(2), ioperm(2), termios(3), con‐
507 sole_codes(4), mt(4), sd(4), tty(4), ttyS(4), vcs(4), vcsa(4),
508 charsets(7), mapscrn(8), resizecons(8), setfont(8)
509 /usr/include/linux/kd.h, /usr/include/linux/vt.h
511
513 This page is part of release 4.16 of the Linux man-pages project. A
514 description of the project, information about reporting bugs, and the
515 latest version of this page, can be found at
516 https://www.kernel.org/doc/man-pages/.
517Linux 2017-09-15 IOCTL_CONSOLE(2)