1ioctl_console(2)              System Calls Manual             ioctl_console(2)
2
3
4

NAME

6       ioctl_console - ioctls for console terminal and virtual consoles
7

DESCRIPTION

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
13       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
17              LED_CAP    0x04   caps lock led
18              LED_NUM    0x02   num lock led
19              LED_SCR    0x01   scroll lock led
20
21       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
28       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
34       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
41       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
48       KDGKBTYPE
49              Get keyboard type.  This returns the value  KB_101,  defined  as
50              0x02.
51
52       KDADDIO
53              Add I/O port as valid.  Equivalent to ioperm(arg,1,1).
54
55       KDDELIO
56              Delete I/O port as valid.  Equivalent to ioperm(arg,1,0).
57
58       KDENABIO
59              Enable   I/O   to  video  board.   Equivalent  to  ioperm(0x3b4,
60              0x3df-0x3b4+1, 1).
61
62       KDDISABIO
63              Disable  I/O  to  video  board.   Equivalent  to   ioperm(0x3b4,
64              0x3df-0x3b4+1, 0).
65
66       KDSETMODE
67              Set  text/graphics mode.  argp is an unsigned integer containing
68              one of:
69
70              KD_TEXT       0x00
71              KD_GRAPHICS   0x01
72
73       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
77       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
86       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
92       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
96       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
105       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
111       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
122       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
129       PIO_FONTX
130              Sets screen font and  associated  rendering  information.   argp
131              points to a
132
133                  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
142              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
146       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
152       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
158       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
165       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
170       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
177       GIO_UNIMAP
178              Get Unicode-to-font mapping from kernel.  argp points to a
179
180                  struct unimapdesc {
181                      unsigned short  entry_ct;
182                      struct unipair *entries;
183                  };
184
185              where entries points to an array of
186
187                  struct unipair {
188                      unsigned short unicode;
189                      unsigned short fontpos;
190                  };
191
192              (Since Linux 1.1.92.)
193
194       PIO_UNIMAP
195              Put  unicode-to-font mapping in kernel.  argp points to a struct
196              unimapdesc.  (Since Linux 1.1.92)
197
198       PIO_UNIMAPCLR
199              Clear table, possibly advise hash algorithm.  argp points to a
200
201                  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
207              (Since Linux 1.1.92.)
208
209       KDGKBMODE
210              Gets current keyboard mode.  argp points to a long which is  set
211              to one of these:
212
213              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
219       KDSKBMODE
220              Sets  current keyboard mode.  argp is a long equal to one of the
221              values shown for KDGKBMODE.
222
223       KDGKBMETA
224              Gets meta key handling mode.  argp points to a long which is set
225              to one of these:
226
227              K_METABIT     0x03   set high order bit
228              K_ESCPREFIX   0x04   escape prefix
229
230       KDSKBMETA
231              Sets meta key handling mode.  argp is a long equal to one of the
232              values shown above for KDGKBMETA.
233
234       KDGKBENT
235              Gets one entry in  key  translation  table  (keycode  to  action
236              code).  argp points to a
237
238                  struct kbentry {
239                      unsigned char  kb_table;
240                      unsigned char  kb_index;
241                      unsigned short kb_value;
242                  };
243
244              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
250       KDSKBENT
251              Sets  one  entry  in translation table.  argp points to a struct
252              kbentry.
253
254       KDGKBSENT
255              Gets one function key string.  argp points to a
256
257                  struct kbsentry {
258                      unsigned char kb_func;
259                      unsigned char kb_string[512];
260                  };
261
262              kb_string is set to the (null-terminated)  string  corresponding
263              to the kb_functh function key action code.
264
265       KDSKBSENT
266              Sets one function key string entry.  argp points to a struct kb‐
267              sentry.
268
269       KDGKBDIACR
270              Read kernel accent table.  argp points to a
271
272                  struct kbdiacrs {
273                      unsigned int   kb_cnt;
274                      struct kbdiacr kbdiacr[256];
275                  };
276
277              where kb_cnt is the number of entries  in  the  array,  each  of
278              which is a
279
280                  struct kbdiacr {
281                      unsigned char diacr;
282                      unsigned char base;
283                      unsigned char result;
284                  };
285
286       KDGETKEYCODE
287              Read  kernel  keycode  table entry (scan code to keycode).  argp
288              points to a
289
290                  struct kbkeycode {
291                      unsigned int scancode;
292                      unsigned int keycode;
293                  };
294
295              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
299       KDSETKEYCODE
300              Write kernel keycode table entry.  argp points to a struct  kbk‐
301              eycode.  (Since Linux 1.1.63.)
302
303       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
309       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
314       VT_GETMODE
315              Get mode of active vt.  argp points to a
316
317                  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
325              which is set to the mode of the active vt.  mode is set  to  one
326              of these values:
327
328              VT_AUTO      auto vt switching
329              VT_PROCESS   process controls switching
330              VT_ACKACQ    acknowledge switch
331
332       VT_SETMODE
333              Set mode of active vt.  argp points to a struct vt_mode.
334
335       VT_GETSTATE
336              Get global vt state info.  argp points to a
337
338                  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
344              For  each vt in use, the corresponding bit in the v_state member
345              is set.  (Linux 1.0 through Linux 1.1.92.)
346
347       VT_RELDISP
348              Release a display.
349
350       VT_ACTIVATE
351              Switch to vt argp (1 <= argp <= MAX_NR_CONSOLES).
352
353       VT_WAITACTIVE
354              Wait until vt argp has been activated.
355
356       VT_DISALLOCATE
357              Deallocate the memory associated with  vt  argp.   (Since  Linux
358              1.1.54.)
359
360       VT_RESIZE
361              Set the kernel's idea of screensize.  argp points to a
362
363                  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
369              Note  that  this  does  not  change  the videomode.  See resize‐
370              cons(8).  (Since Linux 1.1.54.)
371
372       VT_RESIZEX
373              Set the kernel's idea of various screen parameters.  argp points
374              to a
375
376                  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
389              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
394       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       Symbolic subcodes are available in <linux/tiocl.h> since Linux 2.5.71.
398
399       TIOCLINUX, subcode=0
400              Dump  the  screen.   Disappeared  in  Linux 1.1.92.  (With Linux
401              1.1.92 or later, read from /dev/vcsN or /dev/vcsaN instead.)
402
403       TIOCLINUX, subcode=1
404              Get task information.  Disappeared in Linux 1.1.92.
405
406       TIOCLINUX, subcode=TIOCL_SETSEL
407              Set selection.  argp points to a
408
409                  struct {
410                      char  subcode;
411                      short xs, ys, xe, ye;
412                      short sel_mode;
413                  };
414
415              xs and ys are the starting column and row.  xe and  ye  are  the
416              ending  column  and  row.   (Upper left corner is row=column=1.)
417              sel_mode is 0 for character-by-character selection, 1 for  word-
418              by-word  selection,  or 2 for line-by-line selection.  The indi‐
419              cated screen characters are highlighted and saved  in  a  kernel
420              buffer.
421
422       TIOCLINUX, subcode=TIOCL_PASTESEL
423              Paste  selection.   The  characters  in the selection buffer are
424              written to fd.
425
426       TIOCLINUX, subcode=TIOCL_UNBLANKSCREEN
427              Unblank the screen.
428
429       TIOCLINUX, subcode=TIOCL_SELLOADLUT
430              Sets contents of a 256-bit look up table defining characters  in
431              a "word", for word-by-word selection.  (Since Linux 1.1.32.)
432
433       TIOCLINUX, subcode=TIOCL_GETSHIFTSTATE
434              argp  points  to  a char which is set to the value of the kernel
435              variable shift_state.  (Since Linux 1.1.32.)
436
437       TIOCLINUX, subcode=TIOCL_GETMOUSEREPORTING
438              argp points to a char which is set to the value  of  the  kernel
439              variable report_mouse.  (Since Linux 1.1.33.)
440
441       TIOCLINUX, subcode=8
442              Dump screen width and height, cursor position, and all the char‐
443              acter-attribute pairs.  (Linux 1.1.67 through Linux 1.1.91 only.
444              With Linux 1.1.92 or later, read from /dev/vcsa* instead.)
445
446       TIOCLINUX, subcode=9
447              Restore  screen  width  and height, cursor position, and all the
448              character-attribute pairs.  (Linux 1.1.67 through  Linux  1.1.91
449              only.  With Linux 1.1.92 or later, write to /dev/vcsa* instead.)
450
451       TIOCLINUX, subcode=TIOCL_SETVESABLANK
452              Handles  the Power Saving feature of the new generation of moni‐
453              tors.  VESA screen blanking mode is set to argp[1],  which  gov‐
454              erns what screen blanking does:
455
456              0      Screen blanking is disabled.
457
458              1      The  current  video  adapter register settings are saved,
459                     then the controller is programmed to turn off the  verti‐
460                     cal  synchronization  pulses.  This puts the monitor into
461                     "standby" mode.  If your monitor has an  Off_Mode  timer,
462                     then it will eventually power down by itself.
463
464              2      The  current  settings  are saved, then both the vertical
465                     and horizontal synchronization  pulses  are  turned  off.
466                     This  puts  the monitor into "off" mode.  If your monitor
467                     has no Off_Mode timer, or if you  want  your  monitor  to
468                     power  down  immediately  when the blank_timer times out,
469                     then you choose this  option.   (Caution:  Powering  down
470                     frequently   will  damage  the  monitor.)   (Since  Linux
471                     1.1.76.)
472
473       TIOCLINUX, subcode=TIOCL_SETKMSGREDIRECT
474              Change target of kernel messages ("console"): by default, and if
475              this  is  set to 0, messages are written to the currently active
476              VT.  The VT to write to is  a  single  byte  following  subcode.
477              (Since Linux 2.5.36.)
478
479       TIOCLINUX, subcode=TIOCL_GETFGCONSOLE
480              Returns  the number of VT currently in foreground.  (Since Linux
481              2.5.36.)
482
483       TIOCLINUX, subcode=TIOCL_SCROLLCONSOLE
484              Scroll the foreground VT by the specified amount of lines  down,
485              or half the screen if 0.  lines is *(((int32_t *)&subcode) + 1).
486              (Since Linux 2.5.67.)
487
488       TIOCLINUX, subcode=TIOCL_BLANKSCREEN
489              Blank the foreground VT, ignoring "pokes" (typing): can only  be
490              unblanked  explicitly  (by  switching  VTs, to text mode, etc.).
491              (Since Linux 2.5.71.)
492
493       TIOCLINUX, subcode=TIOCL_BLANKEDSCREEN
494              Returns the number of VT currently blanked, 0 if  none.   (Since
495              Linux 2.5.71.)
496
497       TIOCLINUX, subcode=16
498              Never used.
499
500       TIOCLINUX, subcode=TIOCL_GETKMSGREDIRECT
501              Returns target of kernel messages.  (Since Linux 2.6.17.)
502

RETURN VALUE

504       On  success, 0 is returned (except where indicated).  On failure, -1 is
505       returned, and errno is set to indicate the error.
506

ERRORS

508       EBADF  The file descriptor is invalid.
509
510       EINVAL The file descriptor or argp is invalid.
511
512       ENOTTY The file descriptor is not associated with a  character  special
513              device, or the specified request does not apply to it.
514
515       EPERM  Insufficient permission.
516

NOTES

518       Warning: Do not regard this man page as documentation of the Linux con‐
519       sole ioctls.  This is provided for the curious only, as an  alternative
520       to  reading  the source.  Ioctl's are undocumented Linux internals, li‐
521       able to be changed without warning.  (And indeed,  this  page  more  or
522       less  describes  the  situation  as of kernel version 1.1.94; there are
523       many minor and not-so-minor differences with earlier versions.)
524
525       Very often, ioctls are introduced for communication between the  kernel
526       and  one  particular  well-known  program  (fdisk,  hdparm,  setserial,
527       tunelp, loadkeys, selection, setfont, etc.), and their behavior will be
528       changed when required by this particular program.
529
530       Programs  using  these ioctls will not be portable to other versions of
531       UNIX, will not work on older versions of Linux, and will  not  work  on
532       future versions of Linux.
533
534       Use POSIX functions.
535

SEE ALSO

537       dumpkeys(1),  kbd_mode(1),  loadkeys(1), mknod(1), setleds(1), setmeta‐
538       mode(1), execve(2), fcntl(2), ioctl_tty(2), ioperm(2), termios(3), con‐
539       sole_codes(4),   mt(4),   sd(4),   tty(4),  ttyS(4),  vcs(4),  vcsa(4),
540       charsets(7), mapscrn(8), resizecons(8), setfont(8)
541
542       /usr/include/linux/kd.h, /usr/include/linux/vt.h
543
544
545
546Linux man-pages 6.04              2023-01-22                  ioctl_console(2)
Impressum