1IOCTL_CONSOLE(2)           Linux Programmer's 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
31       arbitrary  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
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
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
90              returns 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
267              kbsentry.
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.  (Kernels 1.0 through 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
398       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
402       TIOCLINUX, subcode=1
403              Get task information.  Disappeared in Linux 1.1.92.
404
405       TIOCLINUX, subcode=2
406              Set selection.  argp points to a
407
408                  struct {
409                      char  subcode;
410                      short xs, ys, xe, ye;
411                      short sel_mode;
412                  };
413
414              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
421       TIOCLINUX, subcode=3
422              Paste selection.  The characters in  the  selection  buffer  are
423              written to fd.
424
425       TIOCLINUX, subcode=4
426              Unblank the screen.
427
428       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
432       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
436       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
440       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
445       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
450       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
455              0: Screen blanking is disabled.
456
457              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
463              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

RETURN VALUE

472       On success, 0 is returned.  On error, -1 is returned, and errno is set.
473

ERRORS

475       errno may take on these values:
476
477       EBADF  The file descriptor is invalid.
478
479       EINVAL The file descriptor or argp is invalid.
480
481       ENOTTY The file descriptor is not associated with a  character  special
482              device, or the specified request does not apply to it.
483
484       EPERM  Insufficient permission.
485

NOTES

487       Warning: Do not regard this man page as documentation of the Linux con‐
488       sole ioctls.  This is provided for the curious only, as an  alternative
489       to  reading  the  source.   Ioctl's  are  undocumented Linux internals,
490       liable to be changed without warning.  (And indeed, this page  more  or
491       less  describes  the  situation  as of kernel version 1.1.94; there are
492       many minor and not-so-minor differences with earlier versions.)
493
494       Very often, ioctls are introduced for communication between the  kernel
495       and  one  particular  well-known  program  (fdisk,  hdparm,  setserial,
496       tunelp, loadkeys, selection, setfont, etc.), and their behavior will be
497       changed when required by this particular program.
498
499       Programs  using  these ioctls will not be portable to other versions of
500       UNIX, will not work on older versions of Linux, and will  not  work  on
501       future versions of Linux.
502
503       Use POSIX functions.
504

SEE ALSO

506       dumpkeys(1),  kbd_mode(1),  loadkeys(1), mknod(1), setleds(1), setmeta‐
507       mode(1), execve(2), fcntl(2), ioctl_tty(2), ioperm(2), termios(3), con‐
508       sole_codes(4),   mt(4),   sd(4),   tty(4),  ttyS(4),  vcs(4),  vcsa(4),
509       charsets(7), mapscrn(8), resizecons(8), setfont(8)
510
511       /usr/include/linux/kd.h, /usr/include/linux/vt.h
512

COLOPHON

514       This page is part of release 5.04 of the Linux  man-pages  project.   A
515       description  of  the project, information about reporting bugs, and the
516       latest    version    of    this    page,    can     be     found     at
517       https://www.kernel.org/doc/man-pages/.
518
519
520
521Linux                             2017-09-15                  IOCTL_CONSOLE(2)
Impressum