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 ar‐
31 bitrary 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 un‐
79 signed long integer in argp specify the period in clock cycles,
80 and the upper 16 bits give the duration in msec. If the dura‐
81 tion is zero, the sound is turned off. Control returns immedi‐
82 ately. For example, argp = (125<<16) + 0x637 would specify the
83 beep normally associated with a ctrl-G. (Thus since Linux
84 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 re‐
90 turns 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
186 struct unipair {
188 unsigned short unicode;
189 unsigned short fontpos;
190 };
191 (Since Linux 1.1.92.)
193 PIO_UNIMAP
195 Put unicode-to-font mapping in kernel. argp points to a struct
196 unimapdesc. (Since Linux 1.1.92)
197 PIO_UNIMAPCLR
199 Clear table, possibly advise hash algorithm. argp points to a
200 struct unimapinit {
202 unsigned short advised_hashsize; /* 0 if no opinion */
203 unsigned short advised_hashstep; /* 0 if no opinion */
204 unsigned short advised_hashlevel; /* 0 if no opinion */
205 };
206 (Since Linux 1.1.92.)
208 KDGKBMODE
210 Gets current keyboard mode. argp points to a long which is set
211 to one of these:
212 K_RAW 0x00 /* Raw (scancode) mode */
214 K_XLATE 0x01 /* Translate keycodes using keymap */
215 K_MEDIUMRAW 0x02 /* Medium raw (scancode) mode */
216 K_UNICODE 0x03 /* Unicode mode */
217 K_OFF 0x04 /* Disabled mode; since Linux 2.6.39 */
218 KDSKBMODE
220 Sets current keyboard mode. argp is a long equal to one of the
221 values shown for KDGKBMODE.
222 KDGKBMETA
224 Gets meta key handling mode. argp points to a long which is set
225 to one of these:
226 K_METABIT 0x03 set high order bit
228 K_ESCPREFIX 0x04 escape prefix
229 KDSKBMETA
231 Sets meta key handling mode. argp is a long equal to one of the
232 values shown above for KDGKBMETA.
233 KDGKBENT
235 Gets one entry in key translation table (keycode to action
236 code). argp points to a
237 struct kbentry {
239 unsigned char kb_table;
240 unsigned char kb_index;
241 unsigned short kb_value;
242 };
243 with the first two members filled in: kb_table selects the key
245 table (0 <= kb_table < MAX_NR_KEYMAPS), and kb_index is the key‐
246 code (0 <= kb_index < NR_KEYS). kb_value is set to the corre‐
247 sponding action code, or K_HOLE if there is no such key, or
248 K_NOSUCHMAP if kb_table is invalid.
249 KDSKBENT
251 Sets one entry in translation table. argp points to a struct
252 kbentry.
253 KDGKBSENT
255 Gets one function key string. argp points to a
256 struct kbsentry {
258 unsigned char kb_func;
259 unsigned char kb_string[512];
260 };
261 kb_string is set to the (null-terminated) string corresponding
263 to the kb_functh function key action code.
264 KDSKBSENT
266 Sets one function key string entry. argp points to a struct kb‐
267 sentry.
268 KDGKBDIACR
270 Read kernel accent table. argp points to a
271 struct kbdiacrs {
273 unsigned int kb_cnt;
274 struct kbdiacr kbdiacr[256];
275 };
276 where kb_cnt is the number of entries in the array, each of
278 which is a
279 struct kbdiacr {
281 unsigned char diacr;
282 unsigned char base;
283 unsigned char result;
284 };
285 KDGETKEYCODE
287 Read kernel keycode table entry (scan code to keycode). argp
288 points to a
289 struct kbkeycode {
291 unsigned int scancode;
292 unsigned int keycode;
293 };
294 keycode is set to correspond to the given scancode. (89 <=
296 scancode <= 255 only. For 1 <= scancode <= 88, keycode==scan‐
297 code.) (Since Linux 1.1.63.)
298 KDSETKEYCODE
300 Write kernel keycode table entry. argp points to a struct kbk‐
301 eycode. (Since Linux 1.1.63.)
302 KDSIGACCEPT
304 The calling process indicates its willingness to accept the sig‐
305 nal argp when it is generated by pressing an appropriate key
306 combination. (1 <= argp <= NSIG). (See spawn_console() in
307 linux/drivers/char/keyboard.c.)
308 VT_OPENQRY
310 Returns the first available (non-opened) console. argp points
311 to an int which is set to the number of the vt (1 <= *argp <=
312 MAX_NR_CONSOLES).
313 VT_GETMODE
315 Get mode of active vt. argp points to a
316 struct vt_mode {
318 char mode; /* vt mode */
319 char waitv; /* if set, hang on writes if not active */
320 short relsig; /* signal to raise on release req */
321 short acqsig; /* signal to raise on acquisition */
322 short frsig; /* unused (set to 0) */
323 };
324 which is set to the mode of the active vt. mode is set to one
326 of these values:
327 VT_AUTO auto vt switching
329 VT_PROCESS process controls switching
330 VT_ACKACQ acknowledge switch
331 VT_SETMODE
333 Set mode of active vt. argp points to a struct vt_mode.
334 VT_GETSTATE
336 Get global vt state info. argp points to a
337 struct vt_stat {
339 unsigned short v_active; /* active vt */
340 unsigned short v_signal; /* signal to send */
341 unsigned short v_state; /* vt bit mask */
342 };
343 For each vt in use, the corresponding bit in the v_state member
345 is set. (Kernels 1.0 through 1.1.92.)
346 VT_RELDISP
348 Release a display.
349 VT_ACTIVATE
351 Switch to vt argp (1 <= argp <= MAX_NR_CONSOLES).
352 VT_WAITACTIVE
354 Wait until vt argp has been activated.
355 VT_DISALLOCATE
357 Deallocate the memory associated with vt argp. (Since Linux
358 1.1.54.)
359 VT_RESIZE
361 Set the kernel's idea of screensize. argp points to a
362 struct vt_sizes {
364 unsigned short v_rows; /* # rows */
365 unsigned short v_cols; /* # columns */
366 unsigned short v_scrollsize; /* no longer used */
367 };
368 Note that this does not change the videomode. See resize‐
370 cons(8). (Since Linux 1.1.54.)
371 VT_RESIZEX
373 Set the kernel's idea of various screen parameters. argp points
374 to a
375 struct vt_consize {
377 unsigned short v_rows; /* number of rows */
378 unsigned short v_cols; /* number of columns */
379 unsigned short v_vlin; /* number of pixel rows
380 on screen */
381 unsigned short v_clin; /* number of pixel rows
382 per character */
383 unsigned short v_vcol; /* number of pixel columns
384 on screen */
385 unsigned short v_ccol; /* number of pixel columns
386 per character */
387 };
388 Any parameter may be set to zero, indicating "no change", but if
390 multiple parameters are set, they must be self-consistent. Note
391 that this does not change the videomode. See resizecons(8).
392 (Since Linux 1.3.3.)
393 The action of the following ioctls depends on the first byte in the
395 struct pointed to by argp, referred to here as the subcode. These are
396 legal only for the superuser or the owner of the current terminal.
397 TIOCLINUX, subcode=0
399 Dump the screen. Disappeared in Linux 1.1.92. (With kernel
400 1.1.92 or later, read from /dev/vcsN or /dev/vcsaN instead.)
401 TIOCLINUX, subcode=1
403 Get task information. Disappeared in Linux 1.1.92.
404 TIOCLINUX, subcode=2
406 Set selection. argp points to a
407 struct {
409 char subcode;
410 short xs, ys, xe, ye;
411 short sel_mode;
412 };
413 xs and ys are the starting column and row. xe and ye are the
415 ending column and row. (Upper left corner is row=column=1.)
416 sel_mode is 0 for character-by-character selection, 1 for word-
417 by-word selection, or 2 for line-by-line selection. The indi‐
418 cated screen characters are highlighted and saved in the static
419 array sel_buffer in devices/char/console.c.
420 TIOCLINUX, subcode=3
422 Paste selection. The characters in the selection buffer are
423 written to fd.
424 TIOCLINUX, subcode=4
426 Unblank the screen.
427 TIOCLINUX, subcode=5
429 Sets contents of a 256-bit look up table defining characters in
430 a "word", for word-by-word selection. (Since Linux 1.1.32.)
431 TIOCLINUX, subcode=6
433 argp points to a char which is set to the value of the kernel
434 variable shift_state. (Since Linux 1.1.32.)
435 TIOCLINUX, subcode=7
437 argp points to a char which is set to the value of the kernel
438 variable report_mouse. (Since Linux 1.1.33.)
439 TIOCLINUX, subcode=8
441 Dump screen width and height, cursor position, and all the char‐
442 acter-attribute pairs. (Kernels 1.1.67 through 1.1.91 only.
443 With kernel 1.1.92 or later, read from /dev/vcsa* instead.)
444 TIOCLINUX, subcode=9
446 Restore screen width and height, cursor position, and all the
447 character-attribute pairs. (Kernels 1.1.67 through 1.1.91 only.
448 With kernel 1.1.92 or later, write to /dev/vcsa* instead.)
449 TIOCLINUX, subcode=10
451 Handles the Power Saving feature of the new generation of moni‐
452 tors. VESA screen blanking mode is set to argp[1], which gov‐
453 erns what screen blanking does:
454 0: Screen blanking is disabled.
456 1: The current video adapter register settings are saved, then
458 the controller is programmed to turn off the vertical syn‐
459 chronization pulses. This puts the monitor into "standby"
460 mode. If your monitor has an Off_Mode timer, then it will
461 eventually power down by itself.
462 2: The current settings are saved, then both the vertical and
464 horizontal synchronization pulses are turned off. This puts
465 the monitor into "off" mode. If your monitor has no Off_Mode
466 timer, or if you want your monitor to power down immediately
467 when the blank_timer times out, then you choose this option.
468 (Caution: Powering down frequently will damage the monitor.)
469 (Since Linux 1.1.76.)
470
472 On success, 0 is returned. On failure, -1 is returned, and errno is
473 set to indicate the error.
474
476 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, li‐
489 able 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 5.13 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 2021-03-22 IOCTL_CONSOLE(2)