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