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 ,IP
186                  struct unipair {
187                      unsigned short unicode;
188                      unsigned short fontpos;
189                  };
190
191              (Since Linux 1.1.92.)
192
193       PIO_UNIMAP
194              Put  unicode-to-font mapping in kernel.  argp points to a struct
195              unimapdesc.  (Since Linux 1.1.92)
196
197       PIO_UNIMAPCLR
198              Clear table, possibly advise hash algorithm.  argp points to a
199
200                  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
206              (Since Linux 1.1.92.)
207
208       KDGKBMODE
209              Gets current keyboard mode.  argp points to a long which is  set
210              to one of these:
211
212              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
218       KDSKBMODE
219              Sets  current keyboard mode.  argp is a long equal to one of the
220              values shown for KDGKBMODE.
221
222       KDGKBMETA
223              Gets meta key handling mode.  argp points to a long which is set
224              to one of these:
225
226              K_METABIT     0x03   set high order bit
227              K_ESCPREFIX   0x04   escape prefix
228
229       KDSKBMETA
230              Sets meta key handling mode.  argp is a long equal to one of the
231              values shown above for KDGKBMETA.
232
233       KDGKBENT
234              Gets one entry in  key  translation  table  (keycode  to  action
235              code).  argp points to a
236
237                  struct kbentry {
238                      unsigned char  kb_table;
239                      unsigned char  kb_index;
240                      unsigned short kb_value;
241                  };
242
243              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
249       KDSKBENT
250              Sets  one  entry  in translation table.  argp points to a struct
251              kbentry.
252
253       KDGKBSENT
254              Gets one function key string.  argp points to a
255
256                  struct kbsentry {
257                      unsigned char kb_func;
258                      unsigned char kb_string[512];
259                  };
260
261              kb_string is set to the (null-terminated)  string  corresponding
262              to the kb_functh function key action code.
263
264       KDSKBSENT
265              Sets  one  function  key  string entry.  argp points to a struct
266              kbsentry.
267
268       KDGKBDIACR
269              Read kernel accent table.  argp points to a
270
271                  struct kbdiacrs {
272                      unsigned int   kb_cnt;
273                      struct kbdiacr kbdiacr[256];
274                  };
275
276              where kb_cnt is the number of entries  in  the  array,  each  of
277              which is a
278
279                  struct kbdiacr {
280                      unsigned char diacr;
281                      unsigned char base;
282                      unsigned char result;
283                  };
284
285       KDGETKEYCODE
286              Read  kernel  keycode  table entry (scan code to keycode).  argp
287              points to a
288
289                  struct kbkeycode {
290                      unsigned int scancode;
291                      unsigned int keycode;
292                  };
293
294              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
298       KDSETKEYCODE
299              Write kernel keycode table entry.  argp points to a struct  kbk‐
300              eycode.  (Since Linux 1.1.63.)
301
302       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
308       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
313       VT_GETMODE
314              Get mode of active vt.  argp points to a
315
316                  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
324              which is set to the mode of the active vt.  mode is set  to  one
325              of these values:
326
327              VT_AUTO      auto vt switching
328              VT_PROCESS   process controls switching
329              VT_ACKACQ    acknowledge switch
330
331       VT_SETMODE
332              Set mode of active vt.  argp points to a struct vt_mode.
333
334       VT_GETSTATE
335              Get global vt state info.  argp points to a
336
337                  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
343              For  each vt in use, the corresponding bit in the v_state member
344              is set.  (Kernels 1.0 through 1.1.92.)
345
346       VT_RELDISP
347              Release a display.
348
349       VT_ACTIVATE
350              Switch to vt argp (1 <= argp <= MAX_NR_CONSOLES).
351
352       VT_WAITACTIVE
353              Wait until vt argp has been activated.
354
355       VT_DISALLOCATE
356              Deallocate the memory associated with  vt  argp.   (Since  Linux
357              1.1.54.)
358
359       VT_RESIZE
360              Set the kernel's idea of screensize.  argp points to a
361
362                  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
368              Note  that  this  does  not  change  the videomode.  See resize‐
369              cons(8).  (Since Linux 1.1.54.)
370
371       VT_RESIZEX
372              Set the kernel's idea of various screen parameters.  argp points
373              to a
374
375                  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
388              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
393       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
397       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
401       TIOCLINUX, subcode=1
402              Get task information.  Disappeared in Linux 1.1.92.
403
404       TIOCLINUX, subcode=2
405              Set selection.  argp points to a
406
407                  struct {
408                      char  subcode;
409                      short xs, ys, xe, ye;
410                      short sel_mode;
411                  };
412
413              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
420       TIOCLINUX, subcode=3
421              Paste selection.  The characters in  the  selection  buffer  are
422              written to fd.
423
424       TIOCLINUX, subcode=4
425              Unblank the screen.
426
427       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
431       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
435       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
439       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
444       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
449       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
454              0: Screen blanking is disabled.
455
456              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
462              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

RETURN VALUE

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

ERRORS

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

NOTES

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
493       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
498       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
502       Use POSIX functions.
503

SEE ALSO

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
510       /usr/include/linux/kd.h, /usr/include/linux/vt.h
511

COLOPHON

513       This page is part of release 4.15 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/.
517
518
519
520Linux                             2017-09-15                  IOCTL_CONSOLE(2)
Impressum