1CONSOLE_IOCTL(4)           Linux Programmer's Manual          CONSOLE_IOCTL(4)
2
3
4

NAME

6       console_ioctl - ioctl's for console terminal and virtual consoles
7

DESCRIPTION

9       The  following  Linux-specific  ioctl(2)  requests are supported.  Each
10       requires a third argument, assumed here to be argp.
11
12       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
16                  LED_CAP       0x04   caps lock led
17                  LEC_NUM       0x02   num lock led
18                  LED_SCR       0x01   scroll lock led
19
20       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
26       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 ioctl's are used to access the keyboard flags.
31
32       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
39       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
45       KDGKBTYPE
46              Get  keyboard  type.   This returns the value KB_101, defined as
47              0x02.
48
49       KDADDIO
50              Add I/O port as valid.  Equivalent to ioperm(arg,1,1).
51
52       KDDELIO
53              Delete I/O port as valid.  Equivalent to ioperm(arg,1,0).
54
55       KDENABIO
56              Enable  I/O  to  video  board.   Equivalent   to   ioperm(0x3b4,
57              0x3df-0x3b4+1, 1).
58
59       KDDISABIO
60              Disable   I/O  to  video  board.   Equivalent  to  ioperm(0x3b4,
61              0x3df-0x3b4+1, 0).
62
63       KDSETMODE
64              Set text/graphics mode.  argp is one of these:
65
66                  KD_TEXT       0x00
67                  KD_GRAPHICS   0x01
68
69       KDGETMODE
70              Get text/graphics mode.  argp points to a long which is  set  to
71              one of the above values.
72
73       KDMKTONE
74              Generate  tone  of  specified length.  The lower 16 bits of argp
75              specify the period in clock cycles, and the upper 16  bits  give
76              the  duration  in  msec.   If the duration is zero, the sound is
77              turned off.  Control returns immediately.  For example,  argp  =
78              (125<<16)  +  0x637  would  specify the beep normally associated
79              with a ctrl-G.  (Thus since 0.99pl1; broken in 2.1.49-50.)
80
81       KIOCSOUND
82              Start or stop sound generation.  The lower 16 bits of argp spec‐
83              ify  the  period  in  clock cycles (that is, argp = 1193180/fre‐
84              quency).  argp = 0 turns sound off.   In  either  case,  control
85              returns immediately.
86
87       GIO_CMAP
88              Get the current default color map from kernel.  argp points to a
89              48-byte array.  (Since 1.3.3.)
90
91       PIO_CMAP
92              Change the default  text-mode  color  map.   argp  points  to  a
93              48-byte array which contains, in order, the Red, Green, and Blue
94              values for the 16 available screen colors: 0 is off, and 255  is
95              full  intensity.   The default colors are, in order: black, dark
96              red, dark green, brown, dark blue, dark purple, dark cyan, light
97              grey,  dark grey, bright red, bright green, yellow, bright blue,
98              bright purple, bright cyan and white.  (Since 1.3.3.)
99
100       GIO_FONT
101              Gets 256-character screen font in expanded form.  argp points to
102              an  8192  byte  array.  Fails with error code EINVAL if the cur‐
103              rently loaded font is a 512-character font, or if the console is
104              not in text mode.
105
106       GIO_FONTX
107              Gets  screen  font and associated information.  argp points to a
108              struct consolefontdesc (see PIO_FONTX).  On call, the  charcount
109              field  should  be  set  to the maximum number of characters that
110              would fit in the buffer pointed to by chardata.  On return,  the
111              charcount and charheight are filled with the respective data for
112              the currently loaded font, and the chardata array  contains  the
113              font  data  if  the  initial value of charcount indicated enough
114              space was available; otherwise the buffer is untouched and errno
115              is set to ENOMEM.  (Since 1.3.1.)
116
117       PIO_FONT
118              Sets  256-character  screen  font.   Load  font into the EGA/VGA
119              character generator.  argp points to a 8192 byte  map,  with  32
120              bytes  per  character.  Only first N of them are used for an 8xN
121              font (0 < N <= 32).  This call also invalidates the Unicode map‐
122              ping.
123
124       PIO_FONTX
125              Sets  screen  font  and  associated rendering information.  argp
126              points to a
127
128                  struct consolefontdesc {
129                      unsigned short charcount;  /* characters in font
130                                                    (256 or 512) */
131                      unsigned short charheight; /* scan lines per
132                                                    character (1-32) */
133                      char          *chardata;   /* font data in
134                                                    expanded form */
135                  };
136
137              If necessary, the screen will be appropriately resized, and SIG‐
138              WINCH sent to the appropriate processes.  This call also invali‐
139              dates the Unicode mapping.  (Since 1.3.1.)
140
141       PIO_FONTRESET
142              Resets the screen font, size and Unicode mapping to  the  bootup
143              defaults.   argp  is unused, but should be set to NULL to ensure
144              compatibility with future versions of Linux.  (Since 1.3.28.)
145
146       GIO_SCRNMAP
147              Get screen mapping from kernel.  argp points to an area of  size
148              E_TABSZ, which is loaded with the font positions used to display
149              each character.  This call is likely to return useless  informa‐
150              tion if the currently loaded font is more than 256 characters.
151
152       GIO_UNISCRNMAP
153              Get  full Unicode screen mapping from kernel.  argp points to an
154              area of size E_TABSZ*sizeof(unsigned  short),  which  is  loaded
155              with  the  Unicodes  each character represent.  A special set of
156              Unicodes, starting at U+F000, are used to represent  "direct  to
157              font" mappings.  (Since 1.3.1.)
158
159       PIO_SCRNMAP
160              Loads  the  "user  definable" (fourth) table in the kernel which
161              maps bytes into console screen symbols.  argp points to an  area
162              of size E_TABSZ.
163
164       PIO_UNISCRNMAP
165              Loads  the  "user  definable" (fourth) table in the kernel which
166              maps bytes into Unicodes, which are then translated into  screen
167              symbols  according  to the currently loaded Unicode-to-font map.
168              Special Unicodes starting at U+F000 can be used to map  directly
169              to the font symbols.  (Since 1.3.1.)
170
171       GIO_UNIMAP
172              Get Unicode-to-font mapping from kernel.  argp points to a
173
174                  struct unimapdesc {
175                      unsigned short  entry_ct;
176                      struct unipair *entries;
177                  };
178
179              where entries points to an array of
180
181                  struct unipair {
182                      unsigned short unicode;
183                      unsigned short fontpos;
184                  };
185
186              (Since 1.1.92.)
187
188       PIO_UNIMAP
189              Put unicode-to-font mapping in kernel.
190                  argp points to a struct unimapdesc.  (Since 1.1.92)
191
192       PIO_UNIMAPCLR
193              Clear table, possibly advise hash algorithm.  argp points to a
194
195                  struct unimapinit {
196                      unsigned short advised_hashsize;  /* 0 if no opinion */
197                      unsigned short advised_hashstep;  /* 0 if no opinion */
198                      unsigned short advised_hashlevel; /* 0 if no opinion */
199                  };
200
201              (Since 1.1.92.)
202
203       KDGKBMODE
204              Gets  current keyboard mode.  argp points to a long which is set
205              to one of these:
206
207                  K_RAW         0x00
208                  K_XLATE       0x01
209                  K_MEDIUMRAW   0x02
210                  K_UNICODE     0x03
211
212       KDSKBMODE
213              Sets current keyboard mode.  argp is a long equal to one of  the
214              above values.
215
216       KDGKBMETA
217              Gets meta key handling mode.  argp points to a long which is set
218              to one of these:
219
220                  K_METABIT     0x03   set high order bit
221                  K_ESCPREFIX   0x04   escape prefix
222
223       KDSKBMETA
224              Sets meta key handling mode.  argp is a long equal to one of the
225              above values.
226
227       KDGKBENT
228              Gets  one  entry  in  key  translation  table (keycode to action
229              code).  argp points to a
230
231                  struct kbentry {
232                      unsigned char  kb_table;
233                      unsigned char  kb_index;
234                      unsigned short kb_value;
235                  };
236
237              with the first two members filled in: kb_table selects  the  key
238              table (0 <= kb_table < MAX_NR_KEYMAPS), and kb_index is the key‐
239              code (0 <= kb_index < NR_KEYS).  kb_value is set to  the  corre‐
240              sponding  action  code,  or  K_HOLE  if there is no such key, or
241              K_NOSUCHMAP if kb_table is invalid.
242
243       KDSKBENT
244              Sets one entry in translation table.  argp points  to  a  struct
245              kbentry.
246
247       KDGKBSENT
248              Gets one function key string.  argp points to a
249
250                  struct kbsentry {
251                      unsigned char kb_func;
252                      unsigned char kb_string[512];
253                  };
254
255              kb_string  is  set to the (null-terminated) string corresponding
256              to the kb_functh function key action code.
257
258       KDSKBSENT
259              Sets one function key string entry.  argp  points  to  a  struct
260              kbsentry.
261
262       KDGKBDIACR
263              Read kernel accent table.  argp points to a
264
265                  struct kbdiacrs {
266                      unsigned int   kb_cnt;
267                      struct kbdiacr kbdiacr[256];
268                  };
269
270              where  kb_cnt  is  the  number  of entries in the array, each of
271              which is a
272
273                  struct kbdiacr {
274                      unsigned char diacr;
275                      unsigned char base;
276                      unsigned char result;
277                  };
278
279       KDGETKEYCODE
280              Read kernel keycode table entry (scan code  to  keycode).   argp
281              points to a
282
283                  struct kbkeycode {
284                      unsigned int scancode;
285                      unsigned int keycode;
286                  };
287
288              keycode  is  set  to  correspond  to the given scancode.  (89 <=
289              scancode <= 255 only.  For 1 <= scancode <=  88,  keycode==scan‐
290              code.)  (Since 1.1.63.)
291
292       KDSETKEYCODE
293              Write  kernel keycode table entry.  argp points to a struct kbk‐
294              eycode.  (Since 1.1.63.)
295
296       KDSIGACCEPT
297              The calling process indicates its willingness to accept the sig‐
298              nal  argp  when  it  is generated by pressing an appropriate key
299              combination.  (1 <= argp  <=  NSIG).   (See  spawn_console()  in
300              linux/drivers/char/keyboard.c.)
301
302       VT_OPENQRY
303              Returns  the  first available (non-opened) console.  argp points
304              to an int which is set to the number of the vt (1  <=  *argp  <=
305              MAX_NR_CONSOLES).
306
307       VT_GETMODE
308              Get mode of active vt.  argp points to a
309
310                  struct vt_mode {
311                      char  mode;    /* vt mode */
312                      char  waitv;   /* if set, hang on writes if not active */
313                      short relsig;  /* signal to raise on release req */
314                      short acqsig;  /* signal to raise on acquisition */
315                      short frsig;   /* unused (set to 0) */
316                  };
317
318              which  is  set to the mode of the active vt.  mode is set to one
319              of these values:
320
321                  VT_AUTO       auto vt switching
322                  VT_PROCESS    process controls switching
323                  VT_ACKACQ     acknowledge switch
324
325       VT_SETMODE
326              Set mode of active vt.  argp points to a struct vt_mode.
327
328       VT_GETSTATE
329              Get global vt state info.  argp points to a
330
331                  struct vt_stat {
332                      unsigned short v_active;  /* active vt */
333                      unsigned short v_signal;  /* signal to send */
334                      unsigned short v_state;   /* vt bit mask */
335                  };
336
337              For each vt in use, the corresponding bit in the v_state  member
338              is set.  (Kernels 1.0 through 1.1.92.)
339
340       VT_RELDISP
341              Release a display.
342
343       VT_ACTIVATE
344              Switch to vt argp (1 <= argp <= MAX_NR_CONSOLES).
345
346       VT_WAITACTIVE
347              Wait until vt argp has been activated.
348
349       VT_DISALLOCATE
350              Deallocate the memory associated with vt argp.  (Since 1.1.54.)
351
352       VT_RESIZE
353              Set the kernel's idea of screensize.  argp points to a
354
355                  struct vt_sizes {
356                      unsigned short v_rows;       /* # rows */
357                      unsigned short v_cols;       /* # columns */
358                      unsigned short v_scrollsize; /* no longer used */
359                  };
360
361              Note  that  this  does  not  change  the videomode.  See resize‐
362              cons(8).  (Since 1.1.54.)
363
364       VT_RESIZEX
365              Set the kernel's idea of various screen parameters.  argp points
366              to a
367
368                  struct vt_consize {
369                      unsigned short v_rows;  /* number of rows */
370                      unsigned short v_cols;  /* number of columns */
371                      unsigned short v_vlin;  /* number of pixel rows
372                                                 on screen */
373                      unsigned short v_clin;  /* number of pixel rows
374                                                 per character */
375                      unsigned short v_vcol;  /* number of pixel columns
376                                                 on screen */
377                      unsigned short v_ccol;  /* number of pixel columns
378                                                 per character */
379                  };
380
381              Any parameter may be set to zero, indicating "no change", but if
382              multiple parameters are set, they must be self-consistent.  Note
383              that  this  does  not  change the videomode.  See resizecons(8).
384              (Since 1.3.3.)
385
386       The action of the following ioctls depends on the  first  byte  in  the
387       struct  pointed to by argp, referred to here as the subcode.  These are
388       legal only for the superuser or the owner of the current tty.
389
390       TIOCLINUX, subcode=0
391              Dump the screen.  Disappeared in 1.1.92.  (With kernel 1.1.92 or
392              later, read from /dev/vcsN or /dev/vcsaN instead.)
393
394       TIOCLINUX, subcode=1
395              Get task information.  Disappeared in 1.1.92.
396
397       TIOCLINUX, subcode=2
398              Set selection.  argp points to a
399
400                  struct {
401                     char  subcode;
402                     short xs, ys, xe, ye;
403                     short sel_mode;
404                  };
405
406              xs  and  ys  are the starting column and row.  xe and ye are the
407              ending column and row.  (Upper  left  corner  is  row=column=1.)
408              sel_mode  is 0 for character-by-character selection, 1 for word-
409              by-word selection, or 2 for line-by-line selection.   The  indi‐
410              cated  screen characters are highlighted and saved in the static
411              array sel_buffer in devices/char/console.c.
412
413       TIOCLINUX, subcode=3
414              Paste selection.  The characters in  the  selection  buffer  are
415              written to fd.
416
417       TIOCLINUX, subcode=4
418              Unblank the screen.
419
420       TIOCLINUX, subcode=5
421              Sets  contents of a 256-bit look up table defining characters in
422              a "word", for word-by-word selection.  (Since 1.1.32.)
423
424       TIOCLINUX, subcode=6
425              argp points to a char which is set to the value  of  the  kernel
426              variable shift_state.  (Since 1.1.32.)
427
428       TIOCLINUX, subcode=7
429              argp  points  to  a char which is set to the value of the kernel
430              variable report_mouse.  (Since 1.1.33.)
431
432       TIOCLINUX, subcode=8
433              Dump screen width and height, cursor position, and all the char‐
434              acter-attribute  pairs.   (Kernels  1.1.67  through 1.1.91 only.
435              With kernel 1.1.92 or later, read from /dev/vcsa* instead.)
436
437       TIOCLINUX, subcode=9
438              Restore screen width and height, cursor position,  and  all  the
439              character-attribute pairs.  (Kernels 1.1.67 through 1.1.91 only.
440              With kernel 1.1.92 or later, write to /dev/vcsa* instead.)
441
442       TIOCLINUX, subcode=10
443              Handles the Power Saving feature of the new generation of  moni‐
444              tors.   VESA  screen blanking mode is set to argp[1], which gov‐
445              erns what screen blanking does:
446
447                  0: Screen blanking is disabled.
448
449                  1: The current video adapter register  settings  are  saved,
450              then  the controller is programmed to turn off the vertical syn‐
451              chronization pulses.  This puts the monitor into "standby" mode.
452              If  your  monitor has an Off_Mode timer, then it will eventually
453              power down by itself.
454
455                  2: The current settings are saved, then  both  the  vertical
456              and horizontal synchronization pulses are turned off.  This puts
457              the monitor into "off" mode.  If your monitor  has  no  Off_Mode
458              timer,  or  if  you  want your monitor to power down immediately
459              when the blank_timer times out, then  you  choose  this  option.
460              (Caution: Powering down frequently will damage the monitor.)
461
462              (Since 1.1.76.)
463

RETURN VALUE

465       On success, 0 is returned.  On error -1 is returned, and errno is set.
466

ERRORS

468       errno may take on these values:
469
470       EBADF  The file descriptor is invalid.
471
472       ENOTTY The  file  descriptor is not associated with a character special
473              device, or the specified request does not apply to it.
474
475       EINVAL The file descriptor or argp is invalid.
476
477       EPERM  Insufficient permission.
478

NOTES

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

SEE ALSO

499       dumpkeys(1), kbd_mode(1), loadkeys(1), mknod(1),  setleds(1),  setmeta‐
500       mode(1),  execve(2),  fcntl(2), ioperm(2), termios(3), console(4), con‐
501       sole_codes(4), mt(4), sd(4),  tty(4),  tty_ioctl(4),  ttyS(4),  vcs(4),
502       vcsa(4),    charsets(7),    mapscrn(8),    resizecons(8),   setfont(8),
503       /usr/include/linux/kd.h, /usr/include/linux/vt.h
504

COLOPHON

506       This page is part of release 3.25 of the Linux  man-pages  project.   A
507       description  of  the project, and information about reporting bugs, can
508       be found at http://www.kernel.org/doc/man-pages/.
509
510
511
512Linux                             2009-02-28                  CONSOLE_IOCTL(4)
Impressum