+.\" Copyright (c) 1994 Andries Brouwer (aeb@cwi.nl), Mon Oct 31 21:03:19 MET 1994

+.\"

+.\" This is free documentation; you can redistribute it and/or

+.\" modify it under the terms of the GNU General Public License as

+.\" published by the Free Software Foundation; either version 2 of

+.\" the License, or (at your option) any later version.

+.\"

+.\" Modified, Sun Feb 26 14:58:45 1995, faith@cs.unc.edu

+.\" "

+.TH CONSOLE 4 1994-10-31 "Linux" "Linux Programmer's Manual"

+.SH NAME

+console \- console terminal and virtual consoles

+.SH DESCRIPTION

+A Linux system has up to 63 \fIvirtual consoles\fP

+(character devices with major number 4 and minor number 1 to 63),

+usually called \fB/dev/tty\fP\fIn\fP with 1 \(<= \fIn\fP \(<= 63.

+The current console is also addressed by

+\fB/dev/console\fP or \fB/dev/tty0\fP, the character device with

+major number 4 and minor number 0.

+The device files /dev/* are usually created using the script MAKEDEV,

+or using

+.BR mknod (1),

+usually with mode 0622 and owner root.tty.

+.LP

+Before kernel version 1.1.54 the number of virtual consoles was

+compiled into the kernel (in tty.h: #define NR_CONSOLES 8)

+and could be changed by editing and recompiling.

+Since version 1.1.54 virtual consoles are created on the fly,

+as soon as they are needed.

+.LP

+Common ways to start a process on a console are:

+(a) tell

+.BR init (8)

+(in

+.BR inittab (5))

+to start a

+.BR getty (8)

+on the console;

+(b) ask

+.BR openvt (1)

+to start a process on the console;

+(c) start X - it will find the first unused console,

+and display its output there.

+(There is also the ancient

+.BR doshell (8).)

+.LP

+Common ways to switch consoles are: (a) use Alt+F\fIn\fP or

+Ctrl+Alt+F\fIn\fP to switch to console \fIn\fP; AltGr+F\fIn\fP

+might bring you to console \fIn\fP+12 [here Alt and AltGr refer

+to the left and right Alt keys, respectively];

+(b) use Alt+RightArrow or Alt+LeftArrow to cycle through

+the presently allocated consoles; (c) use the program chvt(1).

+(The key mapping is user settable, see

+.BR loadkeys (1);

+the above mentioned key combinations are according to the default settings.)

+.LP

+The command

+.BR deallocvt (1)

+(formerly \fBdisalloc\fP)

+will free the memory taken by the screen buffers for consoles

+that no longer have any associated process.

+

+.SH PROPERTIES

+Consoles carry a lot of state. I hope to document that some other time.

+The most important fact is that the consoles simulate vt100 terminals.

+In particular, a console is reset to the initial state by printing the two

+characters ESC c.

+All escape sequences can be found in

+.BR console_codes (4).

+

+.LP

+.SH FILES

+.I /dev/console

+.br

+.I /dev/tty*

+.SH "SEE ALSO"

+.BR chvt (1),

+.BR deallocvt (1),

+.BR loadkeys (1),

+.BR mknod (1),

+.BR openvt (1),

+.BR console_codes (4),

+.BR console_ioctl (4),

+.BR tty (4),

+.BR ttys (4),

+.BR charsets (7),

+.BR getty (8),

+.BR init (8),

+.BR mapscrn (8),

+.BR resizecons (8),

+.BR setfont (8)

+'\" t

+.\" Copyright (c) 1996 Andries Brouwer <aeb@cwi.nl>, Mon Oct 31 22:13:04 1996

+.\"

+.\" This is free documentation; you can redistribute it and/or

+.\" modify it under the terms of the GNU General Public License as

+.\" published by the Free Software Foundation; either version 2 of

+.\" the License, or (at your option) any later version.

+.\"

+.\" This is combined from many sources.

+.\" For Linux, the definitive source is of course console.c.

+.\" About vt100-like escape sequences in general there are

+.\" the ISO 6429 and ISO 2022 norms, the descriptions of

+.\" an actual vt100, and the xterm docs (ctlseqs.ms).

+.\" Substantial portions of this text are derived from a write-up

+.\" by Eric S. Raymond <esr@thyrsus.com>.

+.\"

+.\" Tiny correction, aeb, 961107.

+.\"

+.TH CONSOLE_CODES 4 1996-10-31 "Linux" "Linux Programmer's Manual"

+.SH NAME

+console_codes \- Linux console escape and control sequences

+.SH DESCRIPTION

+The Linux console implements a large subset of the VT102 and ECMA-48/ISO

+6429/ANSI X3.64 terminal controls, plus certain private-mode sequences

+for changing the color palette, character-set mapping, etc.

+In the tabular descriptions below, the second column gives ECMA-48 or DEC

+mnemonics (the latter if prefixed with DEC) for the given function.

+Sequences without a mnemonic are neither ECMA-48 nor VT102.

+.LP

+After all the normal output processing has been done, and a

+stream of characters arrives at the console driver for actual

+printing, the first thing that happens is a translation from

+the code used for processing to the code used for printing.

+.LP

+If the console is in UTF-8 mode, then the incoming bytes are

+first assembled into 16-bit Unicode codes. Otherwise

+each byte is transformed according to the current mapping table

+(which translates it to a Unicode value). See the CHARACTER SETS

+section below for discussion.

+.LP

+In the normal case, the Unicode value is converted to a font index,

+and this is stored in video memory, so that the corresponding glyph

+(as found in video ROM) appears on the screen.

+Note that the use of Unicode (and the design of the PC hardware)

+allows us to use 512 different glyphs simultaneously.

+.LP

+If the current Unicode value is a control character, or we are

+currently processing an escape sequence, the value will treated

+specially. Instead of being turned into a font index and rendered as

+a glyph, it may trigger cursor movement or other control functions.

+See the LINUX CONSOLE CONTROLS section below for discussion.

+.LP

+It is generally not good practice to hard-wire terminal controls into

+programs. Linux supports a

+.BR terminfo (5)

+database of terminal capabilities.

+Rather than emitting console escape sequences by hand, you will almost

+always want to use a terminfo-aware screen library or utility such as

+.BR ncurses (3),

+.BR tput (1),

+or

+.BR reset (1).

+

+.SH "LINUX CONSOLE CONTROLS"

+

+This section describes all the control characters and escape sequences

+that invoke special functions (i.e. anything other than writing a

+glyph at the current cursor location) on the Linux console.

+.SS "Control characters"

+A character is a control character if (before transformation

+according to the mapping table) it has one of the 14 codes

+00 (NUL), 07 (BEL), 08 (BS), 09 (HT), 0a (LF), 0b (VT),

+0c (FF), 0d (CR), 0e (SO), 0f (SI), 18 (CAN), 1a (SUB),

+1b (ESC), 7f (DEL).

+One can set a `display control characters' mode (see below),

+and allow 07, 09, 0b, 18, 1a, 7f to be displayed as glyphs.

+On the other hand, in UTF-8 mode all codes 00-1f are regarded

+as control characters, regardless of any `display control characters'

+mode.

+

+If we have a control character, it is acted upon immediately

+and then discarded (even in the middle of an escape sequence)

+and the escape sequence continues with the next character.

+(However, ESC starts a new escape sequence, possibly aborting a previous

+unfinished one, and CAN and SUB abort any escape sequence.)

+The recognized control characters are BEL, BS, HT, LF, VT, FF,

+CR, SO, SI, CAN, SUB, ESC, DEL, CSI. They do what one would expect:

+.HP

+BEL (0x07, ^G) beeps;

+.HP

+BS (0x08, ^H) backspaces one column

+(but not past the beginning of the line);

+.HP

+HT (0x09, ^I) goes to the next tab stop or to the end of the line

+if there is no earlier tab stop;

+.HP

+LF (0x0A, ^J), VT (0x0B, ^K) and FF (0x0C, ^L) all give a linefeed;

+.HP

+CR (0x0D, ^M) gives a carriage return;

+.HP

+SO (0x0E, ^N) activates the G1 character set,

+and if LF/NL (new line mode) is set also a carriage return;

+.HP

+SI (0x0F, ^O) activates the G0 character set;

+.HP

+CAN (0x18, ^X) and SUB (0x1A, ^Z) interrupt escape sequences;

+.HP

+ESC (0x1B, ^[) starts an escape sequence;

+.HP

+DEL (0x7F) is ignored;

+.HP

+CSI (0x9B) is equivalent to ESC [.

+.\" .LP

+.SS "ESC- but not CSI-sequences"

+.TS

+l l l.

+ESC c RIS Reset.

+ESC D IND Linefeed.

+ESC E NEL Newline.

+ESC H HTS Set tab stop at current column.

+ESC M RI Reverse linefeed.

+ESC Z DECID DEC private identification. The kernel

+ returns the string ESC [ ? 6 c, claiming

+ that it is a VT102.

+ESC 7 DECSC Save current state (cursor coordinates,

+ attributes, character sets pointed at by G0, G1).

+ESC 8 DECRC Restore state most recently saved by ESC 7.

+ESC [ CSI Control sequence introducer

+ESC % Start sequence selecting character set

+ESC % @ \0\0\0Select default (ISO 646 / ISO 8859-1)

+ESC % G \0\0\0Select UTF-8

+ESC % 8 \0\0\0Select UTF-8 (obsolete)

+ESC # 8 DECALN DEC screen alignment test - fill screen with E's.

+ESC ( Start sequence defining G0 character set

+ESC ( B \0\0\0Select default (ISO 8859-1 mapping)

+ESC ( 0 \0\0\0Select vt100 graphics mapping

+ESC ( U \0\0\0Select null mapping - straight to character ROM

+ESC ( K \0\0\0Select user mapping - the map that is loaded by

+ \0\0\0the utility \fBmapscrn\fP(8).

+ESC ) Start sequence defining G1

+ (followed by one of B, 0, U, K, as above).

+ESC > DECPNM Set numeric keypad mode

+ESC = DECPAM Set application keypad mode

+ESC ] OSC (Should be: Operating system command)

+ ESC ] P \fInrrggbb\fP: set palette, with parameter

+ given in 7 hexadecimal digits after the final P :-(.

+ Here \fIn\fP is the color (0-15), and \fIrrggbb\fP indicates

+ the red/green/blue values (0-255).

+ ESC ] R: reset palette

+.TE

+.SS "ECMA-48 CSI sequences"

+

+CSI (or ESC [) is followed by a sequence of parameters,

+at most NPAR (16), that are decimal numbers separated by

+semicolons. An empty or absent parameter is taken to be 0.

+The sequence of parameters may be preceded by a single question mark.

+

+However, after CSI [ (or ESC [ [) a single character is read

+and this entire sequence is ignored. (The idea is to ignore

+an echoed function key.)

+

+The action of a CSI sequence is determined by its final character.

+

+.TS

+l l l.

+@ ICH Insert the indicated # of blank characters.

+A CUU Move cursor up the indicated # of rows.

+B CUD Move cursor down the indicated # of rows.

+C CUF Move cursor right the indicated # of columns.

+D CUB Move cursor left the indicated # of columns.

+E CNL Move cursor down the indicated # of rows, to column 1.

+F CPL Move cursor up the indicated # of rows, to column 1.

+G CHA Move cursor to indicated column in current row.

+H CUP Move cursor to the indicated row, column (origin at 1,1).

+J ED Erase display (default: from cursor to end of display).

+ ESC [ 1 J: erase from start to cursor.

+ ESC [ 2 J: erase whole display.

+K EL Erase line (default: from cursor to end of line).

+ ESC [ 1 K: erase from start of line to cursor.

+ ESC [ 2 K: erase whole line.

+L IL Insert the indicated # of blank lines.

+M DL Delete the indicated # of lines.

+P DCH Delete the indicated # of characters on the current line.

+X ECH Erase the indicated # of characters on the current line.

+a HPR Move cursor right the indicated # of columns.

+c DA Answer ESC [ ? 6 c: `I am a VT102'.

+d VPA Move cursor to the indicated row, current column.

+e VPR Move cursor down the indicated # of rows.

+f HVP Move cursor to the indicated row, column.

+g TBC Without parameter: clear tab stop at the current position.

+ ESC [ 3 g: delete all tab stops.

+h SM Set Mode (see below).

+l RM Reset Mode (see below).

+m SGR Set attributes (see below).

+n DSR Status report (see below).

+q DECLL Set keyboard LEDs.

+ ESC [ 0 q: clear all LEDs

+ ESC [ 1 q: set Scroll Lock LED

+ ESC [ 2 q: set Num Lock LED

+ ESC [ 3 q: set Caps Lock LED

+r DECSTBM Set scrolling region; parameters are top and bottom row.

+s ? Save cursor location.

+u ? Restore cursor location.

+` HPA Move cursor to indicated column in current row.

+.TE

+.SS ECMA-48 Set Graphics Rendition

+

+The ECMA-48 SGR sequence ESC [ <parameters> m sets display attributes.

+Several attributes can be set in the same sequence.

+.LP

+.TS

+l l.

+par result

+0 reset all attributes to their defaults

+1 set bold

+2 set half-bright (simulated with color on a color display)

+4 set underscore (simulated with color on a color display)

+ (the colors used to simulate dim or underline are set

+ using ESC ] ...)

+5 set blink

+7 set reverse video

+10 reset selected mapping, display control flag,

+ and toggle meta flag.

+11 select null mapping, set display control flag,

+ reset toggle meta flag.

+12 select null mapping, set display control flag,

+ set toggle meta flag. (The toggle meta flag

+ causes the high bit of a byte to be toggled

+ before the mapping table translation is done.)

+21 set normal intensity (this is not compatible with ECMA-48)

+22 set normal intensity

+24 underline off

+25 blink off

+27 reverse video off

+30 set black foreground

+31 set red foreground

+32 set green foreground

+33 set brown foreground

+34 set blue foreground

+35 set magenta foreground

+36 set cyan foreground

+37 set white foreground

+38 set underscore on, set default foreground color

+39 set underscore off, set default foreground color

+40 set black background

+41 set red background

+42 set green background

+43 set brown background

+44 set blue background

+45 set magenta background

+46 set cyan background

+47 set white background

+49 set default background color

+.TE

+.SS ECMA-48 Mode Switches

+.TP

+ESC [ 3 h

+DECCRM (default off): Display control chars.

+.TP

+ESC [ 4 h

+DECIM (default off): Set insert mode.

+.TP

+ESC [ 20 h

+LF/NL (default off): Automatically follow echo of LF, VT or FF with CR.

+.\"

+.SS ECMA-48 Status Report Commands

+.\"

+.TP

+ESC [ 5 n

+Device status report (DSR): Answer is ESC [ 0 n (Terminal OK).

+.TP

+ESC [ 6 n

+Cursor position report (CPR): Answer is ESC [ \fIy\fP ; \fIx\fP R,

+where \fIx,y\fP is the cursor location.

+.\"

+.SS DEC Private Mode (DECSET/DECRST) sequences.

+.\"

+These are not described in ECMA-48. We list the Set Mode sequences;

+the Reset Mode sequences are obtained by replacing the final `h'

+by `l'.

+.TP

+ESC [ ? 1 h

+DECCKM (default off): When set, the cursor keys send an ESC O prefix,

+rather than ESC [.

+.TP

+ESC [ ? 3 h

+DECCOLM (default off = 80 columns): 80/132 col mode switch. The

+driver sources note that this alone does not suffice; some user-mode

+utility such as

+.BR resizecons (8)

+has to change the hardware registers on the console video card.

+.TP

+ESC [ ? 5 h

+DECSCNM (default off): Set reverse-video mode.

+.TP

+ESC [ ? 6 h

+DECOM (default off): When set, cursor addressing is relative to

+the upper left corner of the scrolling region.

+.TP

+ESC [ ? 7 h

+DECAWM (default on): Set autowrap on. In this mode, a graphic

+character emitted after column 80 (or column 132 of DECCOLM is on)

+forces a wrap to the beginning of the following line first.

+.TP

+ESC [ ? 8 h

+DECARM (default on): Set keyboard autorepreat on.

+.TP

+ESC [ ? 9 h

+X10 Mouse Reporting (default off): Set reporting mode to 1 (or reset to

+0) \- see below.

+.TP

+ESC [ ? 25 h

+DECCM (default on): Make cursor visible.

+.TP

+ESC [ ? 1000 h

+X11 Mouse Reporting (default off): Set reporting mode to 2 (or reset

+to 0) \- see below.

+.\"

+.SS Linux Console Private CSI Sequences

+.\"

+The following sequences are neither ECMA-48 nor native VT102. They

+are native to the Linux console driver. Colors are in SGR parameters:

+0 = black, 1 = red, 2 = green, 3 = brown, 4 = blue, 5 = magenta, 6 =

+cyan, 7 = white.

+

+.TS

+l l.

+ESC [ 1 ; \fIn\fP ] Set color \fIn\fP as the underline color

+ESC [ 2 ; \fIn\fP ] Set color \fIn\fP as the dim color

+ESC [ 8 ] Make the current color pair the default attributes.

+ESC [ 9 ; \fIn\fP ] Set screen blank timeout to \fIn\fP minutes.

+ESC [ 10 ; \fIn\fP ] Set bell frequency in Hz.

+ESC [ 11 ; \fIn\fP ] Set bell duration in msec.

+ESC [ 12 ; \fIn\fP ] Bring specified console to the front.

+ESC [ 13 ] Unblank the screen.

+ESC [ 14 ; \fIn\fP ] Set the VESA powerdown interval in minutes.

+.TE

+

+.SH "CHARACTER SETS"

+

+The kernel knows about 4 translations of bytes into console-screen symbols.

+The four tables are: a) Latin1 -> PC, b) VT100 graphics -> PC, c) PC -> PC,

+d) user-defined.

+

+There are two character sets, called G0 and G1, and one of them

+is the current character set. (Initially G0.)

+Typing ^N causes G1 to become current, ^O causes G0 to become current.

+

+These variables G0 and G1 point at a translation table, and can be changed

+by the user. Initially they point at tables a) and b), respectively.

+The sequences ESC ( B and ESC ( 0 and ESC ( U and ESC ( K cause G0 to point

+at translation table a), b), c) and d), respectively.

+The sequences ESC ) B and ESC ) 0 and ESC ) U and ESC ) K cause G1 to point

+at translation table a), b), c) and d), respectively.

+

+The sequence ESC c causes a terminal reset, which is what you want if the

+screen is all garbled. The oft-advised "echo ^V^O" will only make G0 current,

+but there is no guarantee that G0 points at table a).

+In some distributions there is a program

+.BR reset (1)

+that just does "echo ^[c".

+If your terminfo entry for the console is correct (and has an entry rs1=\\Ec),

+then "tput reset" will also work.

+

+The user-defined mapping table can be set using

+.BR mapscrn (8).

+The result of the mapping is that if a symbol c is printed, the symbol

+s = map[c] is sent to the video memory. The bitmap that corresponds to

+s is found in the character ROM, and can be changed using

+.BR setfont(8).

+

+.SH "MOUSE TRACKING"

+

+The mouse tracking facility is intended to return xterm-compatible

+mouse status reports. Because the console driver has no way to know

+the device or type of the mouse, these reports are returned in the

+console input stream only when the virtual terminal driver receives

+a mouse update ioctl. These ioctls must be generated by a mouse-aware

+user-mode application such as the \fBgpm(8)\fR daemon.

+

+Parameters for all mouse tracking escape sequences generated by

+\fIxterm\fP encode numeric parameters in a single character as

+\fIvalue\fP+040. For example, `!' is 1. The screen

+coordinate system is 1-based.

+

+The X10 compatibility mode sends an escape sequence on button press

+encoding the location and the mouse button pressed.

+It is enabled by sending ESC [ ? 9 h and disabled with ESC [ ? 9 l.

+On button press, \fIxterm\fP sends

+ESC [ M \fIbxy\fP (6 characters). Here \fIb\fP is button\-1,

+and \fIx\fP and \fIy\fP are the x and y coordinates of the mouse

+when the button was pressed.

+This is the same code the kernel also produces.

+

+Normal tracking mode (not implemented in Linux 2.0.24) sends an escape

+sequence on both button press and release. Modifier information is

+also sent. It is enabled by sending ESC [ ? 1000 h and disabled with

+ESC [ 1000 l. On button press or release, \fIxterm\fP sends ESC [ M

+\fIbxy\fP. The low two bits of \fIb\fP encode button information:

+0=MB1 pressed, 1=MB2 pressed, 2=MB3 pressed, 3=release. The upper

+bits encode what modifiers were down when the button was pressed and

+are added together: 4=Shift, 8=Meta, 16=Control. Again \fIx\fP and

+\fIy\fP are the x and y coordinates of the mouse event. The upper

+left corner is (1,1).

+

+.SH "COMPARISONS WITH OTHER TERMINALS"

+

+Many different terminal types are described, like the Linux console,

+as being `VT100-compatible'. Here we discuss differences vbetween the

+Linux console an the two most important others, the DEC VT102 and

+.BR xterm (1).

+.\"

+.SS Control-character handling

+The vt102 also recognized the following control characters:

+.HP

+NUL (0x00) was ignored;

+.HP

+ENQ (0x05) triggered an answerback message;

+.HP

+DC1 (0x11, ^Q, XON) resumed transmission;

+.HP

+DC3 (0x13, ^S, XOFF) caused vt100 to ignore (and stop transmitting)

+all codes except XOFF and XON.

+.LP

+VT100-like DC1/DC3 processing may be enabled by the tty driver.

+.LP

+The

+.I xterm

+program (in vt100 mode) recognizes the control characters

+BEL, BS, HT, LF, VT, FF, CR, SO, SI, ESC.

+.\"

+.SS Escape sequences

+VT100 console sequences not implemented on the Linux console:

+.LP

+.TS

+l l l.

+ESC N SS2 Single shift 2. (Select G2 character set for the next

+ character only.)

+ESC O SS3 Single shift 3. (Select G3 character set for the next

+ character only.)

+ESC P DCS Device control string (ended by ESC \e)

+ESC X SOS Start of string.

+ESC ^ PM Privacy message (ended by ESC \e)

+ESC \e ST String terminator

+ESC * ... Designate G2 character set

+ESC + ... Designate G3 character set

+.TE

+

+The program

+.I xterm

+(in vt100 mode) recognizes ESC c, ESC # 8, ESC >, ESC =,

+ESC D, ESC E, ESC H, ESC M, ESC N, ESC O, ESC P ... ESC \,

+ESC Z (it answers ESC [ ? 1 ; 2 c, `I am a vt100 with advanced video option')

+and ESC ^ ... ESC \ with the same meanings as indicated above.

+It accepts ESC (, ESC ), ESC *, ESC + followed by 0, A, B for

+the DEC special character and line drawing set, UK, and USASCII,

+respectively.

+It accepts ESC ] for the setting of certain resources:

+.LP

+.TS

+l l.

+ESC ] 0 ; txt BEL Set icon name and window title to txt.

+ESC ] 1 ; txt BEL Set icon name to txt.

+ESC ] 2 ; txt BEL Set window title to txt.

+ESC ] 4 6 ; name BEL Change log file to name (normally disabled

+ by a compile-time option)

+ESC ] 5 0 ; fn BEL Set font to fn.

+.TE

+

+It recognizes the following with slightly modified meaning:

+.LP

+.TS

+l l l.

+ESC 7 DECSC Save cursor

+ESC 8 DECRC Restore cursor

+.TE

+

+It also recognizes

+.LP

+.TS

+l l l.

+ESC F Cursor to lower left corner of screen (if enabled by

+ the hpLowerleftBugCompat resource)

+ESC l Memory lock (per HP terminals).

+ Locks memory above the cursor.

+ESC m Memory unlock (per HP terminals).

+ESC n LS2 Invoke the G2 character set.

+ESC o LS3 Invoke the G3 character set.

+ESC | LS3R Invoke the G3 character set as GR.

+ Has no visible effect in xterm.

+ESC } LS2R Invoke the G2 character set as GR.

+ Has no visible effect in xterm.

+ESC ~ LS1R Invoke the G1 character set as GR.

+ Has no visible effect in xterm.

+.TE

+

+It does not recognize ESC % ...

+.\"

+.SS CSI Sequences

+The

+.I xterm

+program (as of XFree86 3.1.2G) does not recognize the blink or invisible-mode

+SGRs. Stock X11R6 versions do not recognize the color-setting SGRs.

+All other ECMA-48 CSI sequences recognized by Linux are also recognized by

+.IR xterm ,

+and vice-versa.

+

+The

+.I xterm

+program will recognize all of the DEC Private Mode sequences listed

+above, but none of the Linux private-mode sequences. For discussion

+of

+.IR xterm 's

+own private-mode sequences, refer to the

+.I Xterm Control Sequences

+document by Edward Moy and Stephen Gildea, available with the X

+distribution.

+

+.SH BUGS

+

+In 2.0.23, CSI is broken, and NUL is not ignored inside escape sequences.

+

+.SH "SEE ALSO"

+.BR console (4),

+.BR console_ioctl (4),

+.BR charsets (7)

+.\" Copyright (c) 1995 Jim Van Zandt <jrv@vanzandt.mv.com> and aeb

+.\" Sun Feb 26 11:46:23 MET 1995

+.\"

+.\" This is free documentation; you can redistribute it and/or

+.\" modify it under the terms of the GNU General Public License as

+.\" published by the Free Software Foundation; either version 2 of

+.\" the License, or (at your option) any later version.

+.\"

+.\" The GNU General Public License's references to "object code"

+.\" and "executables" are to be interpreted as the output of any

+.\" document formatting or typesetting system, including

+.\" intermediate and printed output.

+.\"

+.\" This manual is distributed in the hope that it will be useful,

+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of

+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

+.\" GNU General Public License for more details.

+.\"

+.\" You should have received a copy of the GNU General Public

+.\" License along with this manual; if not, write to the Free

+.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,

+.\" USA.

+.\"

+.\" Modified, Sun Feb 26 15:04:20 1995, faith@cs.unc.edu

+.\" Modified, Thu Apr 20 22:08:17 1995, jrv@vanzandt.mv.com

+.\" Modified, Mon Sep 18 22:32:47 1995, hpa@storm.net (H. Peter Anvin)

+.\" "

+.TH CONSOLE_IOCTLS 4 1995-09-18 "Linux" "Linux Programmer's Manual"

+.SH NAME

+console ioctl \- ioctl's for console terminal and virtual consoles

+.SH DESCRIPTION

+The following Linux-peculiar \fBioctl()\fP requests are supported.

+Each requires a third argument, assumed here to be \fIargp\fP.

+.IP \fBKDGETLED\fP

+Get state of LEDs. \fIargp\fP points to a long int. The lower three bits

+of \fI*argp\fP are set to the state of the LEDs, as follows:

+

+ LED_CAP 0x04 caps lock led

+ LEC_NUM 0x02 num lock led

+ LED_SCR 0x01 scroll lock led

+

+.IP \fBKDSETLED\fP

+Set the LEDs. The LEDs are set to correspond to the lower three bits of

+\fIargp\fP. However, if a higher order bit is set,

+the LEDs revert to normal: displaying the state of the

+keyboard functions of caps lock, num lock, and scroll lock.

+.LP

+Before 1.1.54, the LEDs just reflected the state of the corresponding

+keyboard flags, and KDGETLED/KDSETLED would also change the keyboard

+flags. Since 1.1.54 the leds can be made to display arbitrary

+information, but by default they display the keyboard flags.

+The following two ioctl's are used to access the keyboard flags.

+

+.IP \fBKDGKBLED\fP

+Get keyboard flags CapsLock, NumLock, ScrollLock (not lights).

+\fIargp\fP points to a char which is set to the flag state.

+The low order three bits (mask 0x7) get the current flag state,

+and the low order bits of the next nibble (mask 0x70) get

+the default flag state. (Since 1.1.54.)

+

+.IP \fBKDSKBLED\fP

+Set keyboard flags CapsLock, NumLock, ScrollLock (not lights).

+\fIargp\fP has the desired flag state.

+The low order three bits (mask 0x7) have the flag state,

+and the low order bits of the next nibble (mask 0x70) have

+the default flag state. (Since 1.1.54.)

+

+.IP \fBKDGKBTYPE\fP

+Get keyboard type. This returns the value KB_101, defined as 0x02.

+

+.IP \fBKDADDIO\fP

+Add I/O port as valid. Equivalent to ioperm(arg,1,1).

+

+.IP \fBKDDELIO\fP

+Delete I/O port as valid. Equivalent to ioperm(arg,1,0).

+

+.IP \fBKDENABIO\fP

+Enable I/O to video board. Equivalent to ioperm(0x3b4, 0x3df-0x3b4+1, 1).

+

+.IP \fBKDDISABIO\fP

+Disable I/O to video board. Equivalent to ioperm(0x3b4, 0x3df-0x3b4+1, 0).

+

+.IP \fBKDSETMODE\fP

+Set text/graphics mode. \fIargp\fP is one of these:

+

+ KD_TEXT 0x00

+ KD_GRAPHICS 0x01

+

+.IP \fBKDGETMODE\fP

+Get text/graphics mode. \fIargp\fP points to a long which is set to one

+of the above values.

+

+.IP \fBKDMKTONE\fP

+Generate tone of specified length.

+The lower 16 bits of \fIargp\fP specify the period in clock cycles,

+and the upper 16 bits give the duration in msec.

+If the duration is zero, the sound is turned off.

+Control returns immediately.

+For example, \fIargp\fP = (125<<16) + 0x637 would specify

+the beep normally associated with a ctrl-G.

+(Thus since 0.99pl1; broken in 2.1.49-50.)

+

+.IP \fBKIOCSOUND\fP

+Start or stop sound generation. The lower 16 bits of

+\fIargp\fP specify the period in clock cycles

+(that is, \fIargp\fP = 1193180/frequency).

+\fIargp\fP = 0 turns sound off.

+In either case, control returns immediately.

+

+.IP \fBGIO_CMAP\fP

+Get the current default colour map from kernel. \fIargp\fP points to

+a 48-byte array. (Since 1.3.3.)

+

+.IP \fBPIO_CMAP\fP

+Change the default text-mode colour map. \fIargp\fP points to a

+48-byte array which contains, in order, the Red, Green, and Blue

+values for the 16 available screen colours: 0 is off, and 255 is full

+intensity. The default colours are, in order: black, dark red, dark

+green, brown, dark blue, dark purple, dark cyan, light grey, dark

+grey, bright red, bright green, yellow, bright blue, bright purple,

+bright cyan and white. (Since 1.3.3.)

+

+.IP \fBGIO_FONT\fP

+Gets 256-character screen font in expanded form. \fIargp\fP points to

+an 8192 byte array. Fails with error code \fBEINVAL\fP if the

+currently loaded font is a 512-character font, or if the console is

+not in text mode.

+

+.IP \fBGIO_FONTX\fP

+Gets screen font and associated information. \fIargp\fP points to a

+struct consolefontdesc (see \fBPIO_FONTX\fP). On call, the

+\fIcharcount\fP field should be set to the maximum number of

+characters that would fit in the buffer pointed to by \fIchardata\fP.

+On return, the \fIcharcount\fP and \fIcharheight\fP are filled with

+the respective data for the currently loaded font, and the

+\fIchardata\fP array contains the font data if the initial value of

+\fIcharcount\fP indicated enough space was available; otherwise the

+buffer is untouched and \fIerrno\fP is set to \fBENOMEM\fP. (Since

+1.3.1.)

+

+.IP \fBPIO_FONT\fP

+Sets 256-character screen font. Load font into the EGA/VGA character

+generator. \fIargp\fP points to a 8192 byte map, with 32 bytes per

+character. Only first \fIN\fP of them are used for an 8x\fIN\fP font

+(0 < \fIN\fP <= 32). This call also invalidates the Unicode mapping.

+

+.IP \fBPIO_FONTX\fP

+Sets screen font and associated rendering information. \fIargp\fP

+points to a

+

+.nf

+struct consolefontdesc {

+ u_short \fIcharcount\fP; /* characters in font (256 or 512) */

+ u_short \fIcharheight\fP; /* scan lines per character (1-32) */

+ char *\fIchardata\fP; /* font data in expanded form */

+};

+.fi

+

+If necessary, the screen will be appropriately resized, and

+\fBSIGWINCH\fP sent to the appropriate processes. This call also

+invalidates the Unicode mapping. (Since 1.3.1.)

+

+.IP \fBPIO_FONTRESET\fP

+Resets the screen font, size and Unicode mapping to the bootup

+defaults. \fIargp\fP is unused, but should be set to \fBNULL\fP to

+ensure compatibility with future versions of Linux. (Since 1.3.28.)

+

+.IP \fBGIO_SCRNMAP\fP

+Get screen mapping from kernel. \fIargp\fP points to an area of size

+E_TABSZ, which is loaded with the font positions used to display each

+character. This call is likely to return useless information if the

+currently loaded font is more than 256 characters.

+

+.IP \fBGIO_UNISCRNMAP\fP

+Get full Unicode screen mapping from kernel. \fIargp\fP points to an

+area of size E_TABSZ*sizeof(unsigned short), which is loaded with the

+Unicodes each character represent. A special set of Unicodes,

+starting at U+F000, are used to represent ``direct to font'' mappings.

+(Since 1.3.1.)

+

+.IP \fBPIO_SCRNMAP\fP

+Loads the ``user definable'' (fourth) table in the kernel which maps

+bytes into console screen symbols. \fIargp\fP points to an area of

+size E_TABSZ.

+

+.IP \fBPIO_UNISCRNMAP\fP

+Loads the ``user definable'' (fourth) table in the kernel which maps

+bytes into Unicodes, which are then translated into screen symbols

+according to the currently loaded Unicode-to-font map. Special

+Unicodes starting at U+F000 can be used to map directly to the font

+symbols. (Since 1.3.1.)

+

+.IP \fBGIO_UNIMAP\fP

+Get Unicode-to-font mapping from kernel. \fIargp\fP points to a

+

+.nf

+struct unimapdesc {

+ u_short \fIentry_ct\fP;

+ struct unipair *\fIentries\fP;

+};

+.fi

+

+where \fIentries\fP points to an array of

+

+.nf

+struct unipair {

+ u_short \fIunicode\fP;

+ u_short \fIfontpos\fP;

+};

+.fi

+

+(Since 1.1.92.)

+

+.IP \fBPIO_UNIMAP\fP

+Put unicode-to-font mapping in kernel. \fIargp\fP points to a

+struct unimapdesc. (Since 1.1.92)

+

+.IP \fBPIO_UNIMAPCLR\fP

+Clear table, possibly advise hash algorithm. \fIargp\fP points to a

+

+.nf

+struct unimapinit {

+ u_short \fIadvised_hashsize\fP; /* 0 if no opinion */

+ u_short \fIadvised_hashstep\fP; /* 0 if no opinion */

+ u_short \fIadvised_hashlevel\fP; /* 0 if no opinion */

+};

+.fi

+

+(Since 1.1.92.)

+

+.IP \fBKDGKBMODE\fP

+Gets current keyboard mode. \fIargp\fP points to a long which is set to one

+of these:

+

+ K_RAW 0x00

+ K_XLATE 0x01

+ K_MEDIUMRAW 0x02

+ K_UNICODE 0x03

+

+.IP \fBKDSKBMODE\fP

+Sets current keyboard mode.

+\fIargp\fP is a long equal to one of the above values.

+

+.IP \fBKDGKBMETA\fP

+Gets meta key handling mode. \fIargp\fP points to a long which is

+set to one of these:

+

+ K_METABIT 0x03 set high order bit

+ K_ESCPREFIX 0x04 escape prefix

+

+.IP \fBKDSKBMETA\fP

+Sets meta key handling mode.

+\fIargp\fP is a long equal to one of the above values.

+

+.IP \fBKDGKBENT\fP

+Gets one entry in key translation table (keycode to action code).

+\fIargp\fP points to a

+

+.nf

+struct kbentry {

+ u_char \fIkb_table\fP;

+ u_char \fIkb_index\fP;

+ u_short \fIkb_value\fP;

+};

+.fi

+

+with the first two members filled in:

+\fIkb_table\fP selects the key table (0 <= \fIkb_table\fP < MAX_NR_KEYMAPS),

+and \fIkb_index\fP is the keycode (0 <= \fIkb_index\fP < NR_KEYS).

+\fIkb_value\fP is set to the corresponding action code,

+or K_HOLE if there is no such key,

+or K_NOSUCHMAP if \fIkb_table\fP is invalid.

+

+.IP \fBKDSKBENT\fP

+Sets one entry in translation table. \fIargp\fP points to a struct kbentry.

+

+.IP \fBKDGKBSENT\fP

+Gets one function key string. \fIargp\fP points to a

+

+.nf

+struct kbsentry {

+ u_char \fIkb_func\fP;

+ u_char \fIkb_string\fP[512];

+};

+.fi

+

+\fIkb_string\fP is set to the (NULL terminated) string corresponding to

+the \fIkb_func\fPth function key action code.

+

+.IP \fBKDSKBSENT\fP

+Sets one function key string entry. \fIargp\fP points to a struct kbsentry.

+

+.IP \fBKDGKBDIACR\fP

+Read kernel accent table. \fIargp\fP points to a

+

+.nf

+struct kbdiacrs {

+ unsigned int \fIkb_cnt\fP;

+ struct kbdiacr \fIkbdiacr\fP[256];

+};

+.fi

+

+where \fIkb_cnt\fP is the number of entries in the array, each of which

+is a

+

+struct kbdiacr { u_char \fIdiacr\fP, \fIbase\fP, \fIresult\fP;

+};

+

+.IP \fBKDGETKEYCODE\fP

+Read kernel keycode table entry (scan code to keycode).

+\fIargp\fP points to a

+

+.nf

+struct kbkeycode { unsigned int \fIscancode\fP, \fIkeycode\fP; };

+.fi

+

+\fIkeycode\fP is set to correspond to the given \fIscancode\fP.

+(89 <= \fIscancode\fP <= 255 only.

+For 1 <= \fIscancode\fP <= 88, \fIkeycode\fP==\fIscancode\fP.)

+(Since 1.1.63.)

+

+.IP \fBKDSETKEYCODE\fP

+Write kernel keycode table entry. \fIargp\fP points to struct kbkeycode.

+(Since 1.1.63.)

+

+.IP \fBKDSIGACCEPT\fP

+The calling process indicates its willingness to accept the signal

+\fIargp\fP when it is generated by pressing an appropriate key combination.

+(1 <= \fIargp\fP <= NSIG).

+(See spawn_console() in linux/drivers/char/keyboard.c.)

+

+.IP \fBVT_OPENQRY\fP

+Returns the first available (non-opened) console.

+\fIargp\fP points to an int which is set to the

+number of the vt (1 <= \fI*argp\fP <= MAX_NR_CONSOLES).

+

+.IP \fBVT_GETMODE\fP

+Get mode of active vt. \fIargp\fP points to a

+

+.nf

+struct vt_mode {

+ char \fImode\fP; /* vt mode */

+ char \fIwaitv\fP; /* if set, hang on writes if not active */

+ short \fIrelsig\fP; /* signal to raise on release req */

+ short \fIacqsig\fP; /* signal to raise on acquisition */

+ short \fIfrsig\fP; /* unused (set to 0) */

+};

+.fi

+

+\&...which is set to the mode of the active vt.

+\fImode\fP is set to one of these values:

+

+ VT_AUTO auto vt switching

+ VT_PROCESS process controls switching

+ VT_ACKACQ acknowledge switch

+

+.IP \fBVT_SETMODE\fP

+Set mode of active vt. \fIargp\fP points to a struct vt_mode.

+

+.IP \fBVT_GETSTATE\fP

+Get global vt state info. \fIargp\fP points to a

+

+.nf

+struct vt_stat {

+ ushort \fIv_active\fP; /* active vt */

+ ushort \fIv_signal\fP; /* signal to send */

+ ushort \fIv_state\fP; /* vt bitmask */

+};

+.fi

+

+For each vt in use, the corresponding bit in the \fIv_state\fP member is set.

+(Kernels 1.0 through 1.1.92.)

+

+.IP \fBVT_RELDISP\fP

+Release a display.

+

+.IP \fBVT_ACTIVATE\fP

+Switch to vt \fIargp\fP (1 <= \fIargp\fP <= MAX_NR_CONSOLES).

+

+.IP \fBVT_WAITACTIVE\fP

+Wait until vt \fIargp\fP has been activated.

+

+.IP \fBVT_DISALLOCATE\fP

+Deallocate the memory associated with vt \fIargp\fP.

+(Since 1.1.54.)

+

+.IP \fBVT_RESIZE\fP

+Set the kernel's idea of screensize. \fIargp\fP points to a

+

+.nf

+struct vt_sizes {

+ ushort \fIv_rows\fP; /* # rows */

+ ushort \fIv_cols\fP; /* # columns */

+ ushort \fIv_scrollsize\fP; /* no longer used */

+};

+.fi

+

+Note that this does not change the videomode.

+See resizecons(8). (Since 1.1.54.)

+

+.IP \fBVT_RESIZEX\fP

+Set the kernel's idea of various screen parameters. \fIargp\fP

+points to a

+

+.nf

+struct vt_consize {

+ ushort \fIv_rows\fP; /* number of rows */

+ ushort \fIv_cols\fP; /* number of columns */

+ ushort \fIv_vlin\fP; /* number of pixel rows on screen */

+ ushort \fIv_clin\fP; /* number of pixel rows per character */

+ ushort \fIv_vcol\fP; /* number of pixel columns on screen */

+ ushort \fIv_ccol\fP; /* number of pixel columns per character */

+};

+.fi

+

+Any parameter may be set to zero, indicating ``no change'', but if

+multiple parameters are set, they must be self-consistent. Note that

+this does not change the videomode. See resizecons(8). (Since 1.3.3.)

+

+.PP

+The action of the following ioctls depends on the first byte in the struct

+pointed to by \fIargp\fP, referred to here as the \fIsubcode\fP.

+These are legal only for the superuser or the owner of the current tty.

+.IP "\fBTIOCLINUX, subcode=0\fP"

+Dump the screen.

+Disappeared in 1.1.92. (With kernel 1.1.92 or later, read from

+/dev/vcsN or /dev/vcsaN instead.)

+

+.IP "\fBTIOCLINUX, subcode=1\fP"

+Get task information. Disappeared in 1.1.92.

+

+.IP "\fBTIOCLINUX, subcode=2\fP"

+Set selection.

+\fIargp\fP points to a

+

+ struct {char \fIsubcode\fP;

+ short \fIxs\fP, \fIys\fP, \fIxe\fP, \fIye\fP;

+ short \fIsel_mode\fP;

+ }

+

+\fIxs\fP and \fIys\fP are the starting column and row.

+\fIxe\fP and \fIye\fP are the ending

+column and row. (Upper left corner is row=column=1.)

+\fIsel_mode\fP is 0 for character-by-character selection,

+1 for word-by-word selection,

+or 2 for line-by-line selection.

+The indicated screen characters are highlighted and saved

+in the static array sel_buffer in devices/char/console.c.

+

+.IP "\fBTIOCLINUX, subcode=3\fP"

+Paste selection.

+The characters in the selection buffer are

+written to \fIfd\fP.

+

+.IP "\fBTIOCLINUX, subcode=4\fP"

+Unblank the screen.

+

+.IP "\fBTIOCLINUX, subcode=5\fP"

+Sets contents of a 256-bit look up table defining characters in a "word",

+for word-by-word selection. (Since 1.1.32.)

+

+.IP "\fBTIOCLINUX, subcode=6\fP"

+\fIargp\fP points to a char which is set to the value of the kernel

+variable \fIshift_state\fP. (Since 1.1.32.)

+

+.IP "\fBTIOCLINUX, subcode=7\fP"

+\fIargp\fP points to a char which is set to the value of the kernel

+variable \fIreport_mouse\fP. (Since 1.1.33.)

+

+.IP "\fBTIOCLINUX, subcode=8\fP"

+Dump screen width and height, cursor position, and all the

+character-attribute pairs.

+(Kernels 1.1.67 through 1.1.91 only.

+With kernel 1.1.92 or later, read from /dev/vcsa* instead.)

+

+.IP "\fBTIOCLINUX, subcode=9\fP"

+Restore screen width and height, cursor position, and all the

+character-attribute pairs.

+(Kernels 1.1.67 through 1.1.91 only.

+With kernel 1.1.92 or later, write to /dev/vcsa* instead.)

+

+.IP "\fBTIOCLINUX, subcode=10\fP"

+Handles the Power Saving

+feature of the new generation of monitors.

+VESA screen blanking mode is set to \fIargp\fP[1], which governs what

+screen blanking does:

+

+ \fI0\fP: Screen blanking is disabled.

+

+ \fI1\fP: The current video adapter

+register settings are saved, then the controller is programmed to turn off

+the vertical synchronization pulses. This puts the monitor into "standby" mode.

+If your monitor has an Off_Mode timer, then

+it will eventually power down by itself.

+

+ \fI2\fP: The current

+settings are saved, then both the vertical and horizontal

+synchronization pulses are turned off.

+This puts the monitor into "off" mode.

+If your monitor has no Off_Mode timer,

+or if you want your monitor to power down immediately when the

+blank_timer times out, then you choose this option.

+(\fICaution:\fP Powering down frequently will damage the monitor.)

+

+(Since 1.1.76.)

+

+.SH "RETURN VALUE"

+On success, 0 is returned. On error \-1 is returned, and \fIerrno\fP is set.

+.SH ERRORS

+\fIerrno\fP may take on these values:

+

+.TP

+.B EBADF

+The file descriptor is invalid.

+.TP

+.B

+ENOTTY

+The file descriptor is not associated with a character special device,

+or the specified request does not apply to it.

+.TP

+.B EINVAL

+The file descriptor or \fIargp\fP is invalid.

+.TP

+.B EPERM

+Insufficient permission.

+.SH WARNING

+Do not regard this man page as documentation of the Linux console ioctl's.

+This is provided for the curious only, as an alternative to reading the

+source. Ioctl's are undocumented Linux internals, liable to be changed

+without warning. (And indeed, this page more or less describes the

+situation as of kernel version 1.1.94; there are many minor and not-so-minor

+differences with earlier versions.)

+

+Very often, ioctl's are introduced for communication between the

+kernel and one particular well-known program (fdisk, hdparm, setserial,

+tunelp, loadkeys, selection, setfont, etc.), and their behavior will be

+changed when required by this particular program.

+

+Programs using these ioctl's will not be portable to other versions

+of Unix, will not work on older versions of Linux, and will not work

+on future versions of Linux.

+

+Use POSIX functions.

+

+.SH "SEE ALSO"

+.BR dumpkeys (1),

+.BR kbd_mode (1),

+.BR loadkeys (1),

+.BR mknod (1),

+.BR setleds (1),

+.BR setmetamode (1),

+.BR execve (2),

+.BR fcntl (2),

+.BR ioperm (2),

+.BR termios (3),

+.BR console (4),

+.BR console_codes (4),

+.BR mt (4),

+.BR sd (4),

+.BR tty (4),

+.BR tty_ioctl (4),

+.BR ttys (4),

+.BR vcs (4),

+.BR vcsa (4),

+.BR charsets (7),

+.BR mapscrn (8),

+.BR resizecons (8),

+.BR setfont (8),

+.IR /usr/include/linux/kd.h ,

+.I /usr/include/linux/vt.h

+'\" t

+.\" Copyright (c) 2000 lars brinkhoff <lars@nocrew.org>

+.\"

+.\" This is free documentation; you can redistribute it and/or

+.\" modify it under the terms of the GNU General Public License as

+.\" published by the Free Software Foundation; either version 2 of

+.\" the License, or (at your option) any later version.

+.\"

+.\" The GNU General Public License's references to "object code"

+.\" and "executables" are to be interpreted as the output of any

+.\" document formatting or typesetting system, including

+.\" intermediate and printed output.

+.\"

+.\" This manual is distributed in the hope that it will be useful,

+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of

+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

+.\" GNU General Public License for more details.

+.\"

+.\" You should have received a copy of the GNU General Public

+.\" License along with this manual; if not, write to the Free

+.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,

+.\" USA.

+.\"

+.\" Modified, Thu Jan 27 19:16:19 CET 2000, lars@nocrew.org

+.\"

+.TH DSP56K 4 2000-03-01 "Special files" "Linux Programmer's Manual"

+.SH NAME

+dsp56k \- DSP56001 interface device

+.SH SYNOPSIS

+.nf

+#include <asm/dsp56k.h>

+.sp

+.BI "ssize_t read(int " fd ", void *" data ", size_t " length );

+.BI "ssize_t write(int " fd ", void *" data ", size_t " length );

+.BI "int ioctl(int " fd ", \s-1DSP56K_UPLOAD\s+1, struct dsp56k_upload *" program );

+.BI "int ioctl(int " fd ", \s-1DSP56K_SET_TX_WSIZE\s+1, int " wsize );

+.BI "int ioctl(int " fd ", \s-1DSP56K_SET_RX_WSIZE\s+1, int " wsize );

+.BI "int ioctl(int " fd ", \s-1DSP56K_HOST_FLAGS\s+1, struct dsp56k_host_flags *" flags );

+.BI "int ioctl(int " fd ", \s-1DSP56K_HOST_CMD\s+1, int " cmd );

+.fi

+.SH CONFIGURATION

+The dsp56k device is a character device with major number 55 and minor

+number 0.

+.SH DESCRIPTION

+The Motorola DSP56001 is a fully programmable 24-bit digital signal

+processor found in Atari Falcon030-compatible computers. The

+\fBdsp56k\fP special file is used to control the DSP56001, and

+to send and receive data using the bi-directional handshaked host

+port.

+.PP

+To send a data stream to the signal processor, use write() to the

+device, and read() to receive processed data. The data can be sent or

+received in 8, 16, 24, or 32-bit quantities on the host side, but will

+always be seen as 24-bit quantities in the DSP56001.

+.PP

+The following

+.IR ioctl (2)

+calls are used to control the

+\fBdsp56k\fP device:

+.IP \fBDSP56K_UPLOAD\fP

+resets the DSP56001 and uploads a program. The third ioctl() argument

+must be a pointer to a \fBstruct dsp56k_binary\fP with members

+\fBbin\fP pointing to a DSP56001 binary program, and \fBlen\fP set to

+the length of the program, counted in 24-bit words.

+.IP \fBDSP56K_SET_TX_WSIZE\fP

+sets the transmit word size. Allowed values are in the range 1 to 4,

+and is the number of bytes that will be sent at a time to the

+DSP56001. These data quantities will either be padded with zero

+bytes, or truncated to fit the native 24-bit data format of the

+DSP56001.

+.IP \fBDSP56K_SET_RX_WSIZE\fP

+sets the receive word size. Allowed values are in the range 1 to 4,

+and is the number of bytes that will be received at a time from the

+DSP56001. These data quantities will either truncated, or padded with

+a zero byte to fit the native 24-bit data format of the DSP56001.

+.IP \fBDSP56K_HOST_FLAGS\fP

+read and write the host flags. The host flags are four

+general-purpose bits that can be read by both the hosting computer and

+the DSP56001. Bits 0 and 1 can be written by the host, and bits 2 and

+3 can be written by the DSP56001.

+

+To access the host flags, the third ioctl() argument must be a pointer

+to a \fBstruct dsp56k_host_flags\fP. If bit 0 or 1 is set in the

+\fBdir\fP member, the corresponding bit in \fBout\fP will be written

+to the host flags. The state of all host flags will be returned in

+the lower four bits of the \fBstatus\fP member.

+.IP \fBDSP56K_HOST_CMD\fP

+sends a host command. Allowed values are in the range 0 to 31, and is a

+user-defined command handled by the program running in the DSP56001.

+.SH FILES

+/dev/dsp56k

+.SH AUTHORS

+Fredrik Noring <noring@nocrew.org>, lars brinkhoff <lars@nocrew.org>,

+Tomas Berndtsson <tomas@nocrew.org>.

+.SH "SEE ALSO"

+linux/include/asm-m68k/dsp56k.h,

+linux/drivers/char/dsp56k.c,

+http://dsp56k.nocrew.org/,

+DSP56000/DSP56001 Digital Signal Processor User's Manual

+.\"

+.\" epoll by Davide Libenzi ( efficient event notification retrieval )

+.\" Copyright (C) 2003 Davide Libenzi

+.\"

+.\" This program is free software; you can redistribute it and/or modify

+.\" it under the terms of the GNU General Public License as published by

+.\" the Free Software Foundation; either version 2 of the License, or

+.\" (at your option) any later version.

+.\"

+.\" This program is distributed in the hope that it will be useful,

+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of

+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

+.\" GNU General Public License for more details.

+.\"

+.\" You should have received a copy of the GNU General Public License

+.\" along with this program; if not, write to the Free Software

+.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

+.\"

+.\" Davide Libenzi <davidel@xmailserver.org>

+.\"

+.\"

+.TH EPOLL 4 "2002-10-23" Linux "Linux Programmer's Manual"

+.SH NAME

+epoll \- I/O event notification facility

+.SH SYNOPSIS

+.B #include <sys/epoll.h>

+.SH DESCRIPTION

+.B epoll

+is a variant of

+.BR poll (2)

+that can be used either as Edge or Level Triggered interface and scales

+well to large numbers of watched fds. Three system calls are provided to

+set up and control an

+.B epoll

+set:

+.BR epoll_create (2),

+.BR epoll_ctl (2),

+.BR epoll_wait (2).

+

+An

+.B epoll

+set is connected to a file descriptor created by

+.BR epoll_create (2).

+Interest for certain file descriptors is then registered via

+.BR epoll_ctl (2).

+Finally, the actual wait is started by

+.BR epoll_wait (2).

+

+.SH NOTES

+The

+.B epoll

+event distribution interface is able to behave both as Edge Triggered

+( ET ) and Level Triggered ( LT ). The difference between ET and LT

+event distribution mechanism can be described as follows. Suppose that

+this scenario happens :

+.TP

+.B 1

+The file descriptor that represents the read side of a pipe (

+.B RFD

+) is added inside the

+.B epoll

+device.

+.TP

+.B 2

+Pipe writer writes 2Kb of data on the write side of the pipe.

+.TP

+.B 3

+A call to

+.BR epoll_wait (2)

+is done that will return

+.B RFD

+as ready file descriptor.

+.TP

+.B 4

+The pipe reader reads 1Kb of data from

+.BR RFD .

+.TP

+.B 5

+A call to

+.BR epoll_wait (2)

+is done.

+.PP

+

+If the

+.B RFD

+file descriptor has been added to the

+.B epoll

+interface using the

+.B EPOLLET

+flag, the call to

+.BR epoll_wait (2)

+done in step

+.B 5

+will probably hang because of the available data still present in the file

+input buffers and the remote peer might be expecting a response based on the

+data it already sent. The reason for this is that Edge Triggered event

+distribution delivers events only when events happens on the monitored file.

+So, in step

+.B 5

+the caller might end up waiting for some data that is already present inside

+the input buffer. In the above example, an event on

+.B RFD

+will be generated because of the write done in

+.B 2

+, and the event is consumed in

+.BR 3 .

+Since the read operation done in

+.B 4

+does not consume the whole buffer data, the call to

+.BR epoll_wait (2)

+done in step

+.B 5

+might lock indefinitely. The

+.B epoll

+interface, when used with the

+.B EPOLLET

+flag ( Edge Triggered )

+should use non-blocking file descriptors to avoid having a blocking

+read or write starve the task that is handling multiple file descriptors.

+The suggested way to use

+.B epoll

+as an Edge Triggered (

+.B EPOLLET

+) interface is below, and possible pitfalls to avoid follow.

+.RS

+.TP

+.B i

+with non-blocking file descriptors

+.TP

+.B ii

+by going to wait for an event only after

+.BR read (2)

+or

+.BR write (2)

+return EAGAIN

+.RE

+.PP

+On the contrary, when used as a Level Triggered interface,

+.B epoll

+is by all means a faster

+.BR poll (2),

+and can be used wherever the latter is used since it shares the

+same semantics. Since even with the Edge Triggered

+.B epoll

+multiple events can be generated up on receival of multiple chunks of data,

+the caller has the option to specify the

+.B EPOLLONESHOT

+flag, to tell

+.B epoll

+to disable the associated file descriptor after the receival of an event with

+.BR epoll_wait (2).

+When the

+.B EPOLLONESHOT

+flag is specified, it is caller responsibility to rearm the file descriptor using

+.BR epoll_ctl (2)

+with

+.BR EPOLL_CTL_MOD .

+

+.SH EXAMPLE FOR SUGGESTED USAGE

+

+While the usage of

+.B epoll

+when employed like a Level Triggered interface does have the same

+semantics of

+.BR poll (2),

+an Edge Triggered usage requires more clarifiction to avoid stalls

+in the application event loop. In this example, listener is a

+non-blocking socket on which

+.BR listen (2)

+has been called. The function do_use_fd() uses the new ready

+file descriptor until EAGAIN is returned by either

+.BR read (2)

+or

+.BR write (2).

+An event driven state machine application should, after having received

+EAGAIN, record its current state so that at the next call to do_use_fd()

+it will continue to

+.BR read (2)

+or

+.BR write (2)

+from where it stopped before.

+

+.nf

+struct epoll_event ev, *events;

+

+for(;;) {

+ nfds = epoll_wait(kdpfd, events, maxevents, -1);

+

+ for(n = 0; n < nfds; ++n) {

+ if(events[n].data.fd == listener) {

+ client = accept(listener, (struct sockaddr *) &local,

+ &addrlen);

+ if(client < 0){

+ perror("accept");

+ continue;

+ }

+ setnonblocking(client);

+ ev.events = EPOLLIN | EPOLLET;

+ ev.data.fd = client;

+ if (epoll_ctl(kdpfd, EPOLL_CTL_ADD, client, &ev) < 0) {

+ fprintf(stderr, "epoll set insertion error: fd=%d\n",

+ client);

+ return -1;

+ }

+ }

+ else

+ do_use_fd(events[n].data.fd);

+ }

+}

+.fi

+

+When used as an Edge triggered interface, for performance reasons, it is

+possible to add the file descriptor inside the epoll interface (

+.B EPOLL_CTL_ADD

+) once by specifying (

+.BR EPOLLIN | EPOLLOUT

+). This allows you to avoid

+continuously switching between

+.B EPOLLIN

+and

+.B EPOLLOUT

+calling

+.BR epoll_ctl (2)

+with

+.BR EPOLL_CTL_MOD .

+

+.SH QUESTIONS AND ANSWERS (from linux-kernel)

+

+.RS

+.TP

+.B Q1

+What happens if you add the same fd to an epoll_set twice?

+.TP

+.B A1

+You will probably get EEXIST. However, it is possible that two

+threads may add the same fd twice. This is a harmless condition.

+.TP

+.B Q2

+Can two

+.B epoll

+sets wait for the same fd? If so, are events reported

+to both

+.B epoll

+sets fds?

+.TP

+.B A2

+Yes. However, it is not recommended. Yes it would be reported to both.

+.TP

+.B Q3

+Is the

+.B epoll

+fd itself poll/epoll/selectable?

+.TP

+.B A3

+Yes.

+.TP

+.B Q4

+What happens if the

+.B epoll

+fd is put into its own fd set?

+.TP

+.B A4

+It will fail. However, you can add an

+.B epoll

+fd inside another epoll fd set.

+.TP

+.B Q5

+Can I send the

+.B epoll

+fd over a unix-socket to another process?

+.TP

+.B A5

+No.

+.TP

+.B Q6

+Will the close of an fd cause it to be removed from all

+.B epoll

+sets automatically?

+.TP

+.B A6

+Yes.

+.TP

+.B Q7

+If more than one event comes in between

+.BR epoll_wait (2)

+calls, are they combined or reported separately?

+.TP

+.B A7

+They will be combined.

+.TP

+.B Q8

+Does an operation on an fd affect the already collected but not yet reported

+events?

+.TP

+.B A8

+You can do two operations on an existing fd. Remove would be meaningless for

+this case. Modify will re-read available I/O.

+.TP

+.B Q9

+Do I need to continuously read/write an fd until EAGAIN when using the

+.B EPOLLET

+flag ( Edge Triggered behaviour ) ?

+.TP

+.B A9

+No you don't. Receiving an event from

+.BR epoll_wait (2)

+should suggest to you that such file descriptor is ready for the requested I/O

+operation. You have simply to consider it ready until you will receive the

+next EAGAIN. When and how you will use such file descriptor is entirely up

+to you. Also, the condition that the read/write I/O space is exhausted can

+be detected by checking the amount of data read/write from/to the target

+file descriptor. For example, if you call

+.BR read (2)

+by asking to read a certain amount of data and

+.BR read (2)

+returns a lower number of bytes, you can be sure to have exhausted the read

+I/O space for such file descriptor. Same is valid when writing using the

+.BR write (2)

+function.

+.RE

+

+.SH POSSIBLE PITFALLS AND WAYS TO AVOID THEM

+.RS

+.TP

+.B o Starvation ( Edge Triggered )

+.PP

+If there is a large amount of I/O space, it is possible that by trying to drain

+it the other files will not get processed causing starvation. This

+is not specific to

+.BR epoll .

+.PP

+.PP

+The solution is to maintain a ready list and mark the file descriptor as ready

+in its associated data structure, thereby allowing the application to

+remember which files need to be processed but still round robin amongst

+all the ready files. This also supports ignoring subsequent events you

+receive for fd's that are already ready.

+.PP

+

+.TP

+.B o If using an event cache...

+.PP

+If you use an event cache or store all the fd's returned from

+.BR epoll_wait (2),

+then make sure to provide a way to mark its closure dynamically (ie- caused by

+a previous event's processing). Suppose you receive 100 events from

+.BR epoll_wait (2),

+and in eventi #47 a condition causes event #13 to be closed.

+If you remove the structure and close() the fd for event #13, then your

+event cache might still say there are events waiting for that fd causing

+confusion.

+.PP

+.PP

+One solution for this is to call, during the processing of event 47,

+.BR epoll_ctl ( EPOLL_CTL_DEL )

+to delete fd 13 and close(), then mark its associated

+data structure as removed and link it to a cleanup list. If you find another

+event for fd 13 in your batch processing, you will discover the fd had been

+previously removed and there will be no confusion.

+.PP

+

+.RE

+.SH CONFORMING TO

+.BR epoll (4)

+is a new API introduced in Linux kernel 2.5.44.

+Its interface should be finalized in Linux kernel 2.5.66.

+.SH "SEE ALSO"

+.BR epoll_create (2),

+.BR epoll_ctl (2),

+.BR epoll_wait (2)

+'\" t

+.\" Copyright (c) 1993 Michael Haardt (michael@cantor.informatik.rwth-aachen.de)

+.\" and 1994,1995 Alain Knaff (Alain.Knaff@imag.fr)

+.\"

+.\" This is free documentation; you can redistribute it and/or

+.\" modify it under the terms of the GNU General Public License as

+.\" published by the Free Software Foundation; either version 2 of

+.\" the License, or (at your option) any later version.

+.\"

+.\" The GNU General Public License's references to "object code"

+.\" and "executables" are to be interpreted as the output of any

+.\" document formatting or typesetting system, including

+.\" intermediate and printed output.

+.\"

+.\" This manual is distributed in the hope that it will be useful,

+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of

+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

+.\" GNU General Public License for more details.

+.\"

+.\" You should have received a copy of the GNU General Public

+.\" License along with this manual; if not, write to the Free

+.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,

+.\" USA.

+.\"

+.\" Modified, Sun Feb 26 15:00:02 1995, faith@cs.unc.edu

+.\"

+.TH FD 4 1995-01-29 "Special files" "Linux Programmer's Manual"

+.SH NAME

+fd \- floppy disk device

+.SH CONFIGURATION

+Floppy drives are block devices with major number 2. Typically they

+are owned by root.floppy (i.e., user root, group floppy) and have

+either mode 0660 (access checking via group membership) or mode 0666

+(everybody has access). The minor

+numbers encode the device type, drive number, and controller number.

+For each device type (that is, combination of density and track count)

+there is a base minor number. To this base number, add the drive's

+number on its controller and 128 if the drive is on the secondary

+controller. In the following device tables, \fIn\fP represents the

+drive number.

+.PP

+\fBWarning: If you use formats with more tracks

+than supported by your drive, you may cause it mechanical damage.\fP Trying

+once if more tracks than the usual 40/80 are supported should not

+damage it, but no warranty is given for that. Don't create device

+entries for those formats to prevent their usage if you are not sure.

+.PP

+Drive independent device files which automatically detect the media

+format and capacity:

+.PP

+.TS

+l l.

+Name Base minor #

+_

+\fBfd\fP\fIn\fP 0

+.TE

+.PP

+5.25 inch double density device files:

+.PP

+.TS

+lw(1i) l l l l l.

+Name Capac. Cyl. Sect. Heads Base minor #

+_

+\fBfd\fP\fIn\fP\fBd360\fP 360K 40 9 2 4

+.TE

+.PP

+5.25 inch high density device files:

+.PP

+.TS

+lw(1i) l l l l l.

+Name Capac. Cyl. Sect. Heads Base minor #

+_

+\fBfd\fP\fIn\fP\fBh360\fP 360K 40 9 2 20

+\fBfd\fP\fIn\fP\fBh410\fP 410K 41 10 2 48

+\fBfd\fP\fIn\fP\fBh420\fP 420K 42 10 2 64

+\fBfd\fP\fIn\fP\fBh720\fP 720K 80 9 2 24

+\fBfd\fP\fIn\fP\fBh880\fP 880K 80 11 2 80

+\fBfd\fP\fIn\fP\fBh1200\fP 1200K 80 15 2 8

+\fBfd\fP\fIn\fP\fBh1440\fP 1440K 80 18 2 40

+\fBfd\fP\fIn\fP\fBh1476\fP 1476K 82 18 2 56

+\fBfd\fP\fIn\fP\fBh1494\fP 1494K 83 18 2 72

+\fBfd\fP\fIn\fP\fBh1600\fP 1600K 80 20 2 92

+.TE

+.PP

+3.5 inch double density device files:

+.PP

+.TS

+lw(1i) l l l l l.

+Name Capac. Cyl. Sect. Heads Base minor #

+_

+\fBfd\fP\fIn\fP\fBD360\fP 360K 80 9 1 12

+\fBfd\fP\fIn\fP\fBD720\fP 720K 80 9 2 16

+\fBfd\fP\fIn\fP\fBD800\fP 800K 80 10 2 120

+\fBfd\fP\fIn\fP\fBD1040\fP 1040K 80 13 2 84

+\fBfd\fP\fIn\fP\fBD1120\fP 1120K 80 14 2 88

+.TE

+.PP

+3.5 inch high density device files:

+.PP

+.TS

+lw(1i) l l l l l.

+Name Capac. Cyl. Sect. Heads Base minor #

+_

+\fBfd\fP\fIn\fP\fBH360\fP 360K 40 9 2 12

+\fBfd\fP\fIn\fP\fBH720\fP 720K 80 9 2 16

+\fBfd\fP\fIn\fP\fBH820\fP 820K 82 10 2 52

+\fBfd\fP\fIn\fP\fBH830\fP 830K 83 10 2 68

+\fBfd\fP\fIn\fP\fBH1440\fP 1440K 80 18 2 28

+\fBfd\fP\fIn\fP\fBH1600\fP 1600K 80 20 2 124

+\fBfd\fP\fIn\fP\fBH1680\fP 1680K 80 21 2 44

+\fBfd\fP\fIn\fP\fBH1722\fP 1722K 82 21 2 60

+\fBfd\fP\fIn\fP\fBH1743\fP 1743K 83 21 2 76

+\fBfd\fP\fIn\fP\fBH1760\fP 1760K 80 22 2 96

+\fBfd\fP\fIn\fP\fBH1840\fP 1840K 80 23 2 116

+\fBfd\fP\fIn\fP\fBH1920\fP 1920K 80 24 2 100

+.TE

+.PP

+3.5 inch extra density device files:

+.PP

+.TS

+lw(1i) l l l l l.

+Name Capac. Cyl. Sect. Heads Base minor #

+_

+\fBfd\fP\fIn\fP\fBE2880\fP 2880K 80 36 2 32

+\fBfd\fP\fIn\fP\fBCompaQ\fP 2880K 80 36 2 36

+\fBfd\fP\fIn\fP\fBE3200\fP 3200K 80 40 2 104

+\fBfd\fP\fIn\fP\fBE3520\fP 3520K 80 44 2 108

+\fBfd\fP\fIn\fP\fBE3840\fP 3840K 80 48 2 112

+.TE

+.SH DESCRIPTION

+\fBfd\fP special files access the floppy disk drives in raw mode.

+The following

+.BR ioctl (2)

+calls are supported by \fBfd\fP devices:

+.IP \fBFDCLRPRM\fP

+clears the media information of a drive (geometry of disk in drive).

+.IP \fBFDSETPRM\fP

+sets the media information of a drive. The media information will be

+lost when the media is changed.

+.IP \fBFDDEFPRM\fP

+sets the media information of a drive (geometry of disk in drive). The

+media information will not be lost when the media is changed. This

+will disable autodetection. In order to re-enable autodetection, you

+have to issue an \fBFDCLRPRM\fP .

+.IP \fBFDGETDRVTYP\fP

+returns the type of a drive (name parameter). For formats which work

+in several drive types, \fBFDGETDRVTYP\fP returns a name which is

+appropriate for the oldest drive type which supports this format.

+.IP \fBFDFLUSH\fP

+invalidates the buffer cache for the given drive.

+.IP \fBFDSETMAXERRS\fP

+sets the error thresholds for reporting errors, aborting the operation,

+recalibrating, resetting, and reading sector by sector.

+.IP \fBFDSETMAXERRS\fP

+gets the current error thresholds.

+.IP \fBFDGETDRVTYP\fP

+gets the internal name of the drive.

+.IP \fBFDWERRORCLR\fP

+clears the write error statistics.

+.IP \fBFDWERRORGET\fP

+reads the write error statistics. These include the total number of

+write errors, the location and disk of the first write error, and the

+location and disk of the last write error. Disks are identified by a

+generation number which is incremented at (almost) each disk change.

+.IP \fBFDTWADDLE\fP

+Switch the drive motor off for a few microseconds. This might be

+needed in order to access a disk whose sectors are too close together.

+.IP \fBFDSETDRVPRM\fP

+sets various drive parameters.

+.IP \fBFDGETDRVPRM\fP

+reads these parameters back.

+.IP \fBFDGETDRVSTAT\fP

+gets the cached drive state (disk changed, write protected et al.)

+.IP \fBFDPOLLDRVSTAT\fP

+polls the drive and return its state.

+.IP \fBFDGETFDCSTAT\fP

+gets the floppy controller state.

+.IP \fBFDRESET\fP

+resets the floppy controller under certain conditions.

+.IP \fBFDRAWCMD\fP

+sends a raw command to the floppy controller.

+.PP

+For more precise information, consult also the <linux/fd.h> and

+<linux/fdreg.h> include files, as well as the manual page for

+floppycontrol.

+.SH NOTES

+The various formats allow to read and write many types of disks.

+However, if a floppy is formatted with a too small inter sector gap,

+performance may drop, up to needing a few seconds to access an entire

+track. To prevent this, use interleaved formats. It is not possible to

+read floppies which are formatted using GCR (group code recording),

+which is used by Apple II and Macintosh computers (800k disks).

+Reading floppies which are hard sectored (one hole per sector, with

+the index hole being a little skewed) is not supported. This used to

+be common with older 8 inch floppies.

+.SH FILES

+/dev/fd*

+.SH AUTHORS

+Alain Knaff (Alain.Knaff@imag.fr), David Niemi

+(niemidc@clark.net), Bill Broadhurst (bbroad@netcom.com).

+.SH "SEE ALSO"

+.BR chown (1),

+.BR floppycontrol (1),

+.BR getfdprm (1),

+.BR mknod (1),

+.BR superformat (1),

+.BR mount (8),

+.BR setfdprm (8)

+.\" This man page is Copyright (C) 1999 Claus Fischer.

+.\" Permission is granted to distribute possibly modified copies

+.\" of this page provided the header is included verbatim,

+.\" and in case of nontrivial modification author and date

+.\" of the modification is added to the header.

+.\"

+.\" 990620 - page created - aeb@cwi.nl

+.\"

+.TH FIFO 4 1999-06-20 "Linux" "Linux Programmer's Manual"

+.SH NAME

+fifo \- first-in first-out special file, named pipe

+.SH DESCRIPTION

+A FIFO special file (a named pipe) is similar to a pipe,

+except that it is accessed as part of the file system.

+It can be opened by multiple processes for reading or

+writing. When processes are exchanging data via the FIFO,

+the kernel passes all data internally without writing it

+to the file system. Thus, the FIFO special file has no

+contents on the file system, the file system entry merely

+serves as a reference point so that processes can access

+the pipe using a name in the file system.

+.PP

+The kernel maintains exactly one pipe object for each

+FIFO special file that is opened by at least one process.

+The FIFO must be opened on both ends (reading and writing)

+before data can be passed. Normally, opening the FIFO blocks

+until the other end is opened also.

+.PP

+A process can open a FIFO in non-blocking mode. In this

+case, opening for read only will succeed even if noone has

+opened on the write side yet; opening for write only will

+fail with ENXIO (no such device or address) unless the other

+end has already been opened.

+.PP

+Under Linux, opening a FIFO for read and write will succeed

+both in blocking and non-blocking mode. POSIX leaves this

+behaviour undefined. This can be used to open a FIFO for

+writing while there are no readers available. A process

+that uses both ends of the connection in order to communicate

+with itself should be very careful to avoid deadlocks.

+.SH NOTES

+When a process tries to write to a FIFO that is not opened

+for read on the other side, the process is sent a SIGPIPE

+signal.

+

+FIFO special files can be created by

+.BR mkfifo (3),

+and are specially indicated in

+.IR "ls -l" .

+.SH "SEE ALSO"

+.BR mkfifo (1),

+.BR open (2),

+.BR pipe (2),

+.BR sigaction (2),

+.BR signal (2),

+.BR socketpair (2),

+.BR mkfifo (3)

+.\" -*- nroff -*-

+.\"

+.\" This man-page is Copyright (C) 1997 John S. Kallal

+.\"

+.\" Permission is granted to make and distribute verbatim copies of this

+.\" manual provided the copyright notice and this permission notice are

+.\" preserved on all copies.

+.\"

+.\" Permission is granted to copy and distribute modified versions of this

+.\" manual under the conditions for verbatim copying, provided that the

+.\" entire resulting derived work is distributed under the terms of a

+.\" permission notice identical to this one.

+.\"

+.\" Since the Linux kernel and libraries are constantly changing, this

+.\" manual page may be incorrect or out-of-date. The author(s) assume no

+.\" responsibility for errors or omissions, or for damages resulting from

+.\" the use of the information contained herein. The author(s) may not

+.\" have taken the same level of care in the production of this manual,

+.\" which is licensed free of charge, as they might when working

+.\" professionally.

+.\"

+.\" Formatted or processed versions of this manual, if unaccompanied by

+.\" the source, must acknowledge the copyright and authors of this work.

+.\"

+.\" correction, aeb, 970825

+.TH FULL 4 1997-08-02 "Linux" "Linux Programmer's Manual"

+.SH NAME

+full \- always full device

+.SH DESCRIPTION

+File \fB/dev/full\fP has major device number 1

+and minor device number 7.

+.LP

+Writes to the \fB/dev/full\fP device will fail with an ENOSPC error.

+

+Reads from the \fB/dev/full\fP device will return \\0 characters.

+

+Seeks on \fB/dev/full\fP will always succeed.

+.SH CONFIGURING

+If your system does not have \fB/dev/full\fP created already, it

+can be created with the following commands:

+.nf

+

+ mknod -m 666 /dev/full c 1 7

+ chown root:root /dev/full

+

+.fi

+.SH FILES

+/dev/full

+.SH "SEE ALSO"

+.BR mknod (1),

+.BR null (4),

+.BR zero (4)

+.\" This manpage has been automatically generated by docbook2man

+.\" from a DocBook document. This tool can be found at:

+.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/>

+.\" Please send any bug reports, improvements, comments, patches,

+.\" etc. to Steve Cheng <steve@ggi-project.org>.

+.TH FUTEX 4 2002-12-31 "" "Linux Programmer's Manual"

+.SH NAME

+futex \- Fast Userspace Locking

+.SH SYNOPSIS

+.nf

+#include <linux/futex.h>

+.fi

+.SH DESCRIPTION

+.PP

+The Linux kernel provides futexes ('Fast Userspace muTexes') as a building block for fast userspace

+locking and semaphores. Futexes are very basic and lend themselves well for building higher level

+locking abstractions such as POSIX mutexes.

+.PP

+This page does not set out to document all design decisions but restricts itself to issues relevant for

+application and library development. Most programmers will in fact not be using futexes directly but

+instead rely on system libraries built on them, such as the NPTL pthreads implementation.

+.PP

+A futex is identified by a piece of memory which can be shared between different processes. In these

+different processes, it need not have identical addresses. In its bare form, a futex has semaphore

+semantics; it is a counter that can be incremented and decremented atomically; processes can wait for the

+value to become positive.

+.PP

+Futex operation is entirely userspace for the non-contended case. The kernel is only involved to arbitrate

+the contended case. As any sane design will strive for non-contension, futexes are also optimised

+for this situation.

+.PP

+In its bare form, a futex is an aligned integer which is only touched by atomic assembler

+instructions. Processes can share this integer over mmap, via shared segments or because they

+share memory space, in which case the application is commonly called multithreaded.

+.SH "SEMANTICS"

+.PP

+Any futex operation starts in userspace, but it may necessary to communicate with the kernel using the

+\fBfutex\fR(2) system call.

+.PP

+To 'up' a futex, execute the proper assembler instructions that will cause the host CPU to atomically

+increment the integer. Afterwards, check if it has in fact changed from 0 to 1, in which case

+there were no waiters and the operation is done. This is the non-contended case which is fast and

+should be common.

+.PP

+In the contended case, the atomic increment changed the counter from -1 (or some other negative number). If this is detected,

+there are waiters. Userspace should now set the counter to 1 and instruct the kernel to wake up any

+waiters using the FUTEX_WAKE operation.

+.PP

+Waiting on a futex, to 'down' it, is the reverse operation. Atomically decrement the counter and

+check if it changed to 0, in which case the operation is done and the futex was uncontended. In all

+other circumstances, the process should set the counter to -1 and request that the kernel wait for

+another process to up the futex. This is done using the FUTEX_WAIT operation.

+.PP

+The futex system call can optionally be passed a timeout specifying how long the kernel should

+wait for the futex to be upped. In this case, semantics are more complex and the programmer is referred

+to \fBfutex\fR(2) for

+more details. The same holds for asynchronous futex waiting.

+.SH "NOTES"

+.PP

+To reiterate, bare futexes are not intended as an easy to use abstraction for end-users. Implementors

+are expected to be assembly literate and to have read the sources of the futex userspace library referenced

+below.

+.PP

+This man page illustrates the most common use of the \fBfutex\fR(2) primitives: it is by no means the only one.

+.SH "AUTHORS"

+.PP

+Futexes were designed and worked on by Hubertus Franke (IBM Thomas J. Watson Research Center),

+Matthew Kirkwood, Ingo Molnar (Red Hat) and Rusty Russell (IBM Linux Technology Center). This page written

+by bert hubert.

+.SH "VERSIONS"

+.PP

+Initial futex support was merged in Linux 2.5.7 but with different semantics from those described above.

+Current semantics are available from Linux 2.5.40 onwards.

+.SH "SEE ALSO"

+.PP

+\fBfutex\fR(2),

+`Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux' (proceedings of the Ottawa Linux

+Symposium 2002),

+futex example library, futex-*.tar.bz2 <URL:ftp://ftp.kernel.org:/pub/linux/kernel/people/rusty/>.

+.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993

+.\"

+.\" This is free documentation; you can redistribute it and/or

+.\" modify it under the terms of the GNU General Public License as

+.\" published by the Free Software Foundation; either version 2 of

+.\" the License, or (at your option) any later version.

+.\"

+.\" The GNU General Public License's references to "object code"

+.\" and "executables" are to be interpreted as the output of any

+.\" document formatting or typesetting system, including

+.\" intermediate and printed output.

+.\"

+.\" This manual is distributed in the hope that it will be useful,

+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of

+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

+.\" GNU General Public License for more details.

+.\"

+.\" You should have received a copy of the GNU General Public

+.\" License along with this manual; if not, write to the Free

+.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,

+.\" USA.

+.\"

+.\" Modified Sat Jul 24 16:56:20 1993 by Rik Faith <faith@cs.unc.edu>

+.\" Modified Mon Oct 21 21:38:51 1996 by Eric S. Raymond <esr@thyrsus.com>

+.\" (and some more by aeb)

+.\"

+.TH HD 4 1992-12-17 "Linux" "Linux Programmer's Manual"

+.SH NAME

+hd \- MFM/IDE hard disk devices

+.SH DESCRIPTION

+The \fBhd*\fP devices are block devices to access MFM/IDE hard disk drives

+in raw mode. The master drive on the primary IDE controller (major device

+number 3) is \fBhda\fR; the slave drive is \fBhdb\fR. The master

+drive of the second controller (major device number 22) is \fBhdc\fR

+and the slave \fBhdd\fR.

+.LP

+General IDE block device names have the form

+.BI hd X\c

+, or

+.BI hd XP\c

+, where

+.I X

+is a letter denoting the physical drive, and

+.I P

+is a number denoting the partition on that physical drive.

+The first form,

+.BI hd X,

+is used to address the whole drive.

+Partition numbers are assigned in the order the partitions

+are discovered, and only non-empty, non-extended partitions

+get a number. However, partition numbers 1-4 are given to the

+four partitions described in the MBR (the `primary' partitions),

+regardless of whether they are unused or extended.

+Thus, the first logical partition will be

+.BI hd X 5\c

+\&.

+Both DOS-type partitioning and BSD-disklabel partitioning are supported.

+You can have at most 63 partitions on an IDE disk.

+.LP

+For example,

+.B /dev/hda

+refers to all of the first IDE drive in the system; and

+.B /dev/hdb3

+refers to the third DOS `primary' partition on the second one.

+.LP

+They are typically created by:

+.RS

+.sp

+mknod -m 660 /dev/hda b 3 0

+.br

+mknod -m 660 /dev/hda1 b 3 1

+.br

+mknod -m 660 /dev/hda2 b 3 2

+.br

+\&...

+.br

+mknod -m 660 /dev/hda8 b 3 8

+.br

+mknod -m 660 /dev/hdb b 3 64

+.br

+mknod -m 660 /dev/hdb1 b 3 65

+.br

+mknod -m 660 /dev/hdb2 b 3 66

+.br

+\&...

+.br

+mknod -m 660 /dev/hdb8 b 3 72

+.br

+chown root:disk /dev/hd*

+.RE

+.SH FILES

+/dev/hd*

+.SH "SEE ALSO"

+.BR chown (1),

+.BR mknod (1),

+.BR sd (4),

+.BR mount (8)

+.\" -*- nroff -*-

+.\" This man-page is Copyright (C) 1997 John S. Kallal

+.\"

+.\" Permission is granted to make and distribute verbatim copies of this

+.\" manual provided the copyright notice and this permission notice are

+.\" preserved on all copies.

+.\"

+.\" Permission is granted to copy and distribute modified versions of this

+.\" manual under the conditions for verbatim copying, provided that the

+.\" entire resulting derived work is distributed under the terms of a

+.\" permission notice identical to this one.

+.\"

+.\" Since the Linux kernel and libraries are constantly changing, this

+.\" manual page may be incorrect or out-of-date. The author(s) assume no

+.\" responsibility for errors or omissions, or for damages resulting from

+.\" the use of the information contained herein. The author(s) may not

+.\" have taken the same level of care in the production of this manual,

+.\" which is licensed free of charge, as they might when working

+.\" professionally.

+.\"

+.\" Formatted or processed versions of this manual, if unaccompanied by

+.\" the source, must acknowledge the copyright and author(s) of this work.

+.\"

+.\" If the you wish to distribute versions of this work under other

+.\" conditions than the above, please contact the author(s) at the following

+.\" for permission:

+.\"

+.\" John S. Kallal -

+.\" email: <kallal@voicenet.com>

+.\" mail: 518 Kerfoot Farm RD, Wilmington, DE 19803-2444, USA

+.\" phone: (302)654-5478

+.\"

+.\" $Id: initrd.4,v 0.9 1997/11/07 05:05:32 kallal Exp kallal $

+.TH INITRD 4 1997-11-06 "Linux 2.0" "Linux Programmer's Manual"

+.SH NAME

+initrd \- boot loader initialized RAM disk

+.\"

+.\"

+.\"

+.SH DESCRIPTION

+The special file

+.B /dev/initrd

+is a read-only block device.

+Device

+.B /dev/initrd

+is a RAM disk that is initialized (e.g. loaded) by the boot loader before

+the kernel is started.

+The kernel then can use the the block device

+.BR /dev/initrd "'s "

+contents for a two phased system boot-up.

+.PP

+In the first boot-up phase, the kernel starts up

+and mounts an initial root file-system from the contents

+of

+.B /dev/initrd

+(e.g. RAM disk initialized by the boot loader).

+In the second phase, additional drivers or other modules

+are loaded from the initial root device's contents.

+After loading the additional modules, a new root file system

+(i.e. the normal root file system) is mounted from a

+different device.

+.\"

+.\"

+.\"

+.SH "BOOT-UP OPERATION"

+When booting up with

+.BR initrd ", the system boots as follows:"

+.RS 0.2i

+.PP

+1. The boot loader loads the kernel program and

+.BR /dev/initrd "'s contents into memory."

+.PP

+2. On kernel startup, the kernel uncompresses and copies the contents of the device

+.B /dev/initrd

+onto device

+.B /dev/ram0

+and then frees the memory used by

+.BR /dev/initrd "."

+.PP

+3. The kernel then read-write mounts device

+.B /dev/ram0

+as the initial root file system.

+.PP

+4. If the indicated normal root file system is also the initial root file-system

+(e.g.

+.B /dev/ram0

+) then the kernel skips to the last step for the usual boot sequence.

+.PP

+5. If the executable file

+.BR /linuxrc " is present in the initial root file-system, " /linuxrc

+is executed with uid 0.

+(The file

+.B /linuxrc

+must have executable permission.

+The file

+.B /linuxrc

+can be any valid executable, including a shell script.)

+.PP

+6. If

+.B /linuxrc

+is not executed or when

+.B /linuxrc

+terminates, the normal root file system is mounted.

+(If

+.BR /linuxrc

+exits with any file-systems mounted on the initial root

+file-system, then the behavior of the kernel is

+.BR UNSPECIFIED "."

+See the

+.BR NOTES

+section for the current kernel behavior.)

+.PP

+7. If the normal root file has directory

+.BR /initrd ", device"

+.B /dev/ram0

+is moved from

+.BR / " to " /initrd "."

+Otherwise if directory

+.BR /initrd " does not exist device " /dev/ram0 " is unmounted."

+(When moved from

+.BR / " to " /initrd ", " /dev/ram0

+is not unmounted and therefore processes can remain running from

+.BR /dev/ram0 "."

+If directory

+.BR /initrd

+does not exist on the normal root file-system

+and any processes remain running from

+.BR /dev/ram0 " when " /linuxrc

+exits, the behavior of the kernel is

+.BR UNSPECIFIED "."

+See the

+.BR NOTES

+section for the current kernel behavior.)

+.PP

+8. The usual boot sequence (e.g. invocation of

+.BR /sbin/init ") is performed on the normal root file system."

+.\"

+.\"

+.\"

+.SH OPTIONS

+The following boot loader options when used with

+.BR initrd ", affect the kernel's boot-up operation:"

+.TP

+.BI initrd= "filename"

+Specifies the file to load as the contents of

+.BR /dev/initrd "."

+.RB "For " LOADLIN

+this is a command line option.

+.RB "For " LILO " you have to use this command in the

+.BR LILO " configuration file " /etc/lilo.config "."

+The filename specified with this

+option will typically be a gzipped file-system image.

+.TP

+.B noinitrd

+This boot time option disables the two phase boot-up operation.

+The kernel performs the usual boot sequence as if

+.B /dev/initrd

+was not initialized.

+With this option, any contents of

+.B /dev/initrd

+loaded into memory by the boot loader contents are preserved.

+This option permits the contents of

+.B /dev/initrd

+to be any data and need not be limited to a file system image.

+However, device

+.B /dev/initrd

+is read-only and can be read only one time after system startup.

+.TP

+.BI root= "device-name"

+Specifies the device to be used as the normal root file system.

+.RB "For " LOADLIN

+this is a command line option.

+.RB "For " LILO " this is a boot time option or

+can be used as an option line in the

+.BR LILO " configuration file " /etc/lilo.config "."

+The device specified by the this option must be a mountable

+device having a suitable root file-system.

+.\"

+.\"

+.\"

+.SH "CHANGING THE NORMAL ROOT FILE SYSTEM"

+By default,

+the kernel's settings

+(e.g. set in the kernel file with

+.B rdev

+or compiled into the kernel file),

+or the boot loader option setting

+is used for the normal root file systems.

+For a NFS-mounted normal root file system, one has to use the

+.BR nfs_root_name " and " nfs_root_addrs

+boot options to give the NFS settings.

+For more information on NFS-mounted root see the kernel documentation file

+.BR nfsroot.txt "."

+For more information on setting the root file system also see the

+.BR LILO " and " LOADLIN " documentation."

+.PP

+It is also possible for the

+.BR /linuxrc

+executable to change the normal root device.

+For

+.BR /linuxrc

+to change the normal root device,

+.BR /proc " must be mounted."

+After mounting

+.BR /proc ", " /linuxrc

+changes the normal root device by writing into the proc files

+.BR /proc/sys/kernel/real-root-dev ", "

+.BR /proc/sys/kernel/nfs-root-name ", and "

+.BR /proc/sys/kernel/nfs-root-addrs "."

+For a physical root device, the root device is changed by having

+.BR /linuxrc

+write the new root file system device number into

+.BR /proc/sys/kernel/real-root-dev "."

+For a NFS root file system, the root device is changed by having

+.BR /linuxrc

+write the NFS setting into files

+.BR /proc/sys/kernel/nfs-root-name " and "

+.BR /proc/sys/kernel/nfs-root-addrs

+and then writing 0xff (e.g. the pseudo-NFS-device number) into file

+.BR /proc/sys/kernel/real-root-dev "."

+For example, the following shell command line would change

+the normal root device to

+.BR /dev/hdb1 :

+.nf

+ echo 0x365 >/proc/sys/kernel/real-root-dev

+.fi

+For a NFS example, the following shell command lines would change the

+normal root device to the NFS directory

+.BR /var/nfsroot

+on a local networked NFS server with IP number 193.8.232.7 for a system with

+IP number 193.8.232.7 and named 'idefix':

+.nf

+ echo /var/nfsroot >/proc/sys/kernel/nfs-root-name

+ echo 193.8.232.2:193.8.232.7::255.255.255.0:idefix \\

+ >/proc/sys/kernel/nfs-root-addrs

+ echo 255 >/proc/sys/kernel/real-root-dev

+.fi

+.\"

+.\"

+.\"

+.SH USAGE

+The main motivation for implementing

+.BR initrd

+was to allow for modular kernel configuration at system installation.

+.PP

+A possible system installation scenario is as follows:

+.RS 0.2i

+.PP

+1. The loader program boots from floppy or other media with a minimal kernel

+(e.g. support for

+.BR /dev/ram ", " /dev/initrd ", and the ext2 file-system) and loads "

+.BR /dev/initrd " with a gzipped version of the initial file-system.

+.PP

+2. The executable

+.BR /linuxrc

+determines what is needed to (1) mount the normal root file-system

+(i.e. device type, device drivers, file system) and (2) the

+distribution media (e.g. CD-ROM, network, tape, ...). This can be

+done by asking the user, by auto-probing, or by using a hybrid

+approach.

+.PP

+3. The executable

+.BR /linuxrc

+loads the necessary modules from the initial root file-system.

+.PP

+4. The executable

+.BR /linuxrc

+creates and populates the root file system. (At this stage the normal

+root file system does not have to be a

+completed system yet.)

+.PP

+5. The executable

+.BR /linuxrc " sets " /proc/sys/kernel/real-root-dev,

+unmount

+.BR /proc ", "

+the normal root file system and any other file

+systems it has mounted, and then terminates.

+.PP

+6. The kernel then mounts the normal root file system.

+.PP

+7. Now that the file system is accessible and intact,

+the boot loader can be installed.

+.PP

+8. The boot loader is configured to load into

+.BR /dev/initrd

+a file system with the set of modules that was used to bring up the system.

+(e.g. Device

+.BR /dev/ram0

+can be modified, then unmounted, and finally, the image is written from

+.BR /dev/ram0

+to a file.)

+.PP

+9. The system is now bootable and additional installation tasks can be

+performed.

+.RE

+.PP

+The key role of

+.BR /dev/initrd

+in the above is to re-use the configuration data during normal system operation

+without requiring initial kernel selection, a large generic kernel or,

+recompiling the kernel.

+.PP

+A second scenario is for installations where Linux runs on systems with

+different hardware configurations in a single administrative network.

+In such cases, it may be desirable to use only a small set of kernels

+(ideally only one) and to keep the system-specific part of configuration

+information as small as possible.

+In this case, create a common file

+with all needed modules.

+Then, only the the

+.B /linuxrc

+file or a file executed by

+.B /linuxrc

+would be different.

+.PP

+A third scenario is more convenient recovery disks.

+Because information like the location of the root file-system

+partition is not needed at boot time, the system loaded from

+.B /dev/initrd

+can use a dialog and/or auto-detection followed by a

+possible sanity check.

+.PP

+Last but not least, Linux distributions on CD-ROM may use

+.BR initrd

+for easy installation from the CD-ROM.

+The distribution can use

+.BR LOADLIN

+to directly load

+.BR /dev/initrd

+from CD-ROM without the need of any floppies.

+The distribution could also use a

+.BR LILO

+boot floppy and then bootstrap a bigger ram disk via

+.BR /dev/initrd " from the CD-ROM."

+.\"

+.\"

+.\"

+.SH CONFIGURATION

+The

+.B /dev/initrd

+is a read-only block device assigned

+major number 1 and minor number 250.

+Typically

+.B /dev/initrd

+is owned by

+.B root.disk

+with mode 0400 (read access by root only).

+If the Linux system does not have

+.B /dev/initrd

+already created, it can be created with the following commands:

+.nf

+\fB

+ mknod -m 400 /dev/initrd b 1 250

+ chown root:disk /dev/initrd

+\fP

+.fi

+Also, support for both "RAM disk" and "Initial RAM disk"

+(e.g.

+.BR CONFIG_BLK_DEV_RAM=y " and " CONFIG_BLK_DEV_INITRD=y

+) support must be compiled directly into the Linux kernel to use

+.BR /dev/initrd "."

+When using

+.BR /dev/initrd ", "

+the RAM disk driver cannot be loaded as a module.

+.\"

+.\"

+.\"

+.SH FILES

+.I /dev/initrd

+.br

+.I /dev/ram0

+.br

+.I /linuxrc

+.br

+.I /initrd

+.SH "SEE ALSO"

+.BR chown (1),

+.BR mknod (1),

+.BR ram (4),

+.BR freeramdisk (8),

+.BR rdev (8)

+

+The documentation file

+.I initrd.txt

+in the kernel source package, the LILO documentation,

+the LOADLIN documentation, the SYSLINUX documentation.

+.\"

+.\"

+.\"

+.SH NOTES

+1. With the current kernel, any file systems that remain mounted when

+.BR /dev/ram0 " is moved from " / " to " /initrd

+continue to be accessible. However, the

+.BR /proc/mounts

+entries are not updated.

+.PP

+2. With the current kernel, if directory

+.BR /initrd " does not exist, then " /dev/ram0

+will NOT be fully unmounted if

+.BR /dev/ram0

+is used by any process or has any file-system mounted on it.

+If

+.BR /dev/ram0 " is NOT fully unmounted, "

+then

+.BR /dev/ram0

+will remain in memory.

+.PP

+3. Users of

+.BR /dev/initrd

+should not depend on the behavior give in the above notes.

+The behavior may change in future versions of the Linux kernel.

+.\"

+.\"

+.\"

+.SH AUTHOR

+The kernel code for device

+.BR initrd

+was written by Werner Almesberger <almesber@lrc.epfl.ch> and

+Hans Lermen <lermen@elserv.ffm.fgan.de>.

+The code for

+.BR initrd

+was added to the baseline Linux kernel in development version 1.3.73.

+.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993

+.\"

+.\" This is free documentation; you can redistribute it and/or

+.\" modify it under the terms of the GNU General Public License as

+.\" published by the Free Software Foundation; either version 2 of

+.\" the License, or (at your option) any later version.

+.\"

+.\" The GNU General Public License's references to "object code"

+.\" and "executables" are to be interpreted as the output of any

+.\" document formatting or typesetting system, including

+.\" intermediate and printed output.

+.\"

+.\" This manual is distributed in the hope that it will be useful,

+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of

+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

+.\" GNU General Public License for more details.

+.\"

+.\" You should have received a copy of the GNU General Public

+.\" License along with this manual; if not, write to the Free

+.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,

+.\" USA.

+.\"

+.\" Modified Sat Jul 24 16:57:14 1993 by Rik Faith (faith@cs.unc.edu)

+.TH INTRO 4 1993-07-24 "Linux" "Linux Programmer's Manual"

+.SH NAME

+intro \- Introduction to special files

+.SH DESCRIPTION

+This chapter describes special files.

+.SH FILES

+/dev/* \(em device files

+.SH AUTHORS

+Look at the header of the manual page for the author(s) and copyright

+conditions. Note that these can be different from page to page!

+.so man4/mem.4

+'\" t

+.\" Copyright (c) Michael Haardt (michael@cantor.informatik.rwth-aachen.de), Sun Jan 15 19:16:33 1995

+.\"

+.\" This is free documentation; you can redistribute it and/or

+.\" modify it under the terms of the GNU General Public License as

+.\" published by the Free Software Foundation; either version 2 of

+.\" the License, or (at your option) any later version.

+.\"

+.\" The GNU General Public License's references to "object code"

+.\" and "executables" are to be interpreted as the output of any

+.\" document formatting or typesetting system, including

+.\" intermediate and printed output.

+.\"

+.\" This manual is distributed in the hope that it will be useful,

+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of

+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

+.\" GNU General Public License for more details.

+.\"

+.\" You should have received a copy of the GNU General Public

+.\" License along with this manual; if not, write to the Free

+.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,

+.\" USA.

+.\"

+.\" Modified, Sun Feb 26 15:02:58 1995, faith@cs.unc.edu

+.TH LP 4 1995-01-15 "Special files" "Linux Programmer's Manual"

+.SH NAME

+lp \- line printer devices

+.SH SYNOPSIS

+.B #include <linux/lp.h>

+.SH CONFIGURATION

+\fBlp\fP[0\(en2] are character devices for the parallel line printers;

+they have major number 6 and minor number 0\(en2. The minor numbers

+correspond to the printer port base addresses 0x03bc, 0x0378 and 0x0278.

+Usually they have mode 220 and are owned by root and group lp. You can

+use printer ports either with polling or with interrupts. Interrupts

+are recommended when high traffic is expected, e.g.\& for laser

+printers. For usual dot matrix printers polling will usually be

+enough. The default is polling.

+.SH DESCRIPTION

+The following

+.BR ioctl (2)

+calls are supported:

+.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPTIME, int \fP\fIarg\fP\fB)\fP"

+Sets the amount of time that the driver sleeps before rechecking the printer

+when the printer's buffer appears to be filled to \fIarg\fP. If you

+have a fast printer, decrease this number; if you have a slow printer

+then increase it. This is in hundredths of a second, the default 2

+being 0.02 seconds. It only influences the polling driver.

+.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPCHAR, int \fP\fIarg\fP\fB)\fP"

+Sets the maximum number of busy-wait iterations which the polling driver does

+while waiting for the printer to get ready for receiving a character to

+\fIarg\fP. If printing is too slow, increase this number; if the

+system gets too slow, decrease this number. The default is 1000.

+It only influences the polling driver.

+.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPABORT, int \fP\fIarg\fP\fB)\fP"

+If \fIarg\fP is 0, the printer driver will retry on errors, otherwise

+it will abort. The default is 0.

+.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPABORTOPEN, int \fP\fIarg\fP\fB)\fP"

+If \fIarg\fP is 0,

+.BR open (2)

+will be aborted on error, otherwise error will be ignored. The default is

+to ignore it.

+.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPCAREFUL, int \fP\fIarg\fP\fB)\fP"

+If \fIarg\fP is 0, then the out-of-paper, offline and error signals are

+required to be false on all writes, otherwise they are ignored. The

+default is to ignore them.

+.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPWAIT, int \fP\fIarg\fP\fB)\fP"

+Sets the number of busy waiting iterations to wait before strobing the

+printer to accept a just-written character, and the number of iterations to

+wait before turning the strobe off again,

+to \fIarg\fP. The specification says this time should be 0.5

+microseconds, but experience has shown the delay caused by the code is

+already enough. For that reason, the default value is 0. This is

+used for both the polling and the interrupt driver.

+.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPSETIRQ, int \fP\fIarg\fP\fB)\fP"

+This ioctl() requires superuser privileges. It takes an int containing the

+new IRQ as argument. As a side effect, the printer will be reset. When

+\fIarg\fP is 0, the polling driver will be used, which is also default.

+.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPGETIRQ, int *\fP\fIarg\fP\fB)\fP"

+Stores the currently used IRQ in \fIarg\fP.

+.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPGETSTATUS, int *\fP\fIarg\fP\fB)\fP"

+Stores the value of the status port in \fIarg\fP. The bits have the following

+meaning:

+.sp

+.TS

+l l.

+LP_PBUSY inverted busy input, active high

+LP_PACK unchanged acknowledge input, active low

+LP_POUTPA unchanged out-of-paper input, active high

+LP_PSELECD unchanged selected input, active high

+LP_PERRORP unchanged error input, active low

+.TE

+.sp

+Refer to your printer manual for the meaning of the signals.

+Note that undocumented bits may also be set, depending on your printer.

+.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPRESET)\fP"

+Resets the printer. No argument is used.

+.SH FILES

+/dev/lp*

+.SH AUTHORS

+The printer driver was originally written by Jim Weigand and Linus

+Torvalds. It was further improved by Michael K.\& Johnson. The

+interrupt code was written by Nigel Gamble. Alan Cox modularised it.

+LPCAREFUL, LPABORT, LPGETSTATUS were added by Chris Metcalf.

+.SH "SEE ALSO"

+.BR chmod (1),

+.BR chown (1),

+.BR mknod (1),

+.BR lpcntl (8),

+.BR tunelp (8)

+.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993

+.\"

+.\" This is free documentation; you can redistribute it and/or

+.\" modify it under the terms of the GNU General Public License as

+.\" published by the Free Software Foundation; either version 2 of

+.\" the License, or (at your option) any later version.

+.\"

+.\" The GNU General Public License's references to "object code"

+.\" and "executables" are to be interpreted as the output of any

+.\" document formatting or typesetting system, including

+.\" intermediate and printed output.

+.\"

+.\" This manual is distributed in the hope that it will be useful,

+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of

+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

+.\" GNU General Public License for more details.

+.\"

+.\" You should have received a copy of the GNU General Public

+.\" License along with this manual; if not, write to the Free

+.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,

+.\" USA.

+.\"

+.\" Modified Sat Jul 24 16:59:10 1993 by Rik Faith (faith@cs.unc.edu)

+.TH MEM 4 1992-11-21 "Linux" "Linux Programmer's Manual"

+.SH NAME

+mem, kmem, port \- system memory, kernel memory and system ports

+.SH DESCRIPTION

+\fBMem\fP is a character device file

+that is an image of the main memory of the

+computer. It may be used, for example, to examine (and even patch) the

+system.

+.LP

+Byte addresses in mem are interpreted as physical memory addresses.

+References to non-existent locations cause errors to be returned.

+.LP

+Examining and patching is likely to lead to unexpected results

+when read-only or write-only bits are present.

+.LP

+It is typically created by:

+.RS

+.sp

+mknod -m 660 /dev/mem c 1 1

+.br

+chown root:mem /dev/mem

+.sp

+.RE

+.LP

+The file kmem is the same as mem, except that the kernel virtual memory

+rather than physical memory is accessed.

+.LP

+It is typically created by:

+.RS

+.sp

+mknod -m 640 /dev/kmem c 1 2

+.br

+chown root:mem /dev/kmem

+.sp

+.RE

+.LP

+\fBPort\fP is similar to mem, but the IO ports are accessed.

+.LP

+It is typically created by:

+.RS

+.sp

+mknod -m 660 /dev/port c 1 4

+.br

+chown root:mem /dev/port

+.sp

+.RE

+.SH FILES

+.I /dev/mem

+.br

+.I /dev/kmem

+.br

+.I /dev/port

+.SH "SEE ALSO"

+.BR chown (1),

+.BR mknod (1),

+.BR ioperm (2)

+'\" t

+.\"roff.\" Copyright

+.\" This manpage is Copyright (C) 1996 Michael Haardt.

+.\" Updates Nov 1998, Andries Brouwer

+.\"

+.\" Permission is granted to make and distribute verbatim copies of this

+.\" manual provided the copyright notice and this permission notice are

+.\" preserved on all copies.

+.\"

+.\" Permission is granted to copy and distribute modified versions of this

+.\" manual under the conditions for verbatim copying, provided that the

+.\" entire resulting derived work is distributed under the terms of a

+.\" permission notice identical to this one.

+.\"

+.\" Since the Linux kernel and libraries are constantly changing, this

+.\" manual page may be incorrect or out-of-date. The author(s) assume no

+.\" responsibility for errors or omissions, or for damages resulting from

+.\" the use of the information contained herein. The author(s) may not

+.\" have taken the same level of care in the production of this manual,

+.\" which is licensed free of charge, as they might when working

+.\" professionally.

+.\"

+.\" Formatted or processed versions of this manual, if unaccompanied by

+.\" the source, must acknowledge the copyright and authors of this work.

+.TH MOUSE 4 1996-02-10 "Special files" "Linux Programmer's Manual"

+.SH NAME

+mouse \- serial mouse interface

+.SH CONFIG

+Serial mice are connected to a serial RS232/V24 dialout line, see

+.BR ttys (4)

+for a description.

+.SH DESCRIPTION

+.SS Introduction

+The pinout of the usual 9 pin plug as used for serial mice is:

+

+.TS

+center;

+r c l.

+pin name used for

+2 RX Data

+3 TX -12 V, Imax = 10 mA

+4 DTR +12 V, Imax = 10 mA

+7 RTS +12 V, Imax = 10 mA

+5 GND Ground

+.TE

+

+This is the specification, in fact 9 V suffices with most mice.

+.PP

+The mouse driver can recognize a mouse by dropping RTS to low and raising

+it again. About 14 ms later the mouse will send 0x4D ('M') on the data line.

+After a further 63 ms, a Microsoft-compatible 3-button mouse will send

+0x33 ('3').

+.PP

+The relative mouse movement is sent as \fIdx\fP (positive means right)

+and \fIdy\fP (positive means down). Various mice can operate at different

+speeds. To select speeds, cycle through the

+speeds 9600, 4800, 2400 and 1200 bit/s, each time writing the two characters

+from the table below and waiting 0.1 seconds. The following table shows

+available speeds and the strings that select them:

+

+.TS

+center;

+l l.

+bit/s string

+9600 *q

+4800 *p

+2400 *o

+1200 *n

+.TE

+

+The first byte of a data packet can be used to synchronisation purposes.

+.SS "Microsoft protocol"

+The \fBMicrosoft\fP protocol uses 1 start bit, 7 data bits, no parity

+and one stop bit at the speed of 1200 bits/sec. Data is sent to RxD in

+3-byte packets. The \fIdx\fP and \fIdy\fP movements are sent as

+two's-complement, \fIlb\fP (\fIrb\fP) are set when the left (right)

+button is pressed:

+

+.TS

+center;

+r c c c c c c c.

+byte d6 d5 d4 d3 d2 d1 d0

+1 1 lb rb dy7 dy6 dx7 dx6

+2 0 dx5 dx4 dx3 dx2 dx1 dx0

+3 0 dy5 dy4 dy3 dy2 dy1 dy0

+.TE

+.SS "3-button Microsoft protocol"

+Original Microsoft mice only have two buttons. However, there are some

+three button mice which also use the Microsoft protocol. Pressing or

+releasing the middle button is reported by sending a packet with zero

+movement and no buttons pressed.

+(Thus, unlike for the other two buttons, the status of the middle

+button is not reported in each packet.)

+.SS "Logitech protocol"

+Logitech serial 3-button mice use a different extension of the

+Microsoft protocol: when the middle button is up, the above 3-byte

+packet is sent. When the middle button is down a 4-byte packet is

+sent, where the 4th byte has value 0x20 (or at least has the 0x20

+bit set). In particular, a press of the middle button is reported

+as 0,0,0,0x20 when no other buttons are down.

+.SS "Mousesystems protocol"

+The \fBMousesystems\fP protocol uses 1 start bit, 8 data bits, no parity

+and two stop bits at the speed of 1200 bits/sec. Data is sent to RxD in

+5-byte packets. \fIdx\fP is sent as the sum of the two two's-complement

+values, \fIdy\fP is send as negated sum of the two two's-complement

+values. \fIlb\fP (\fImb\fP, \fIrb\fP) are cleared when the left (middle,

+right) button is pressed:

+

+.TS

+center;

+r c c c c c c c c.

+byte d7 d6 d5 d4 d3 d2 d1 d0

+1 1 0 0 0 0 lb mb rb

+2 0 dxa6 dxa5 dxa4 dxa3 dxa2 dxa1 dxa0

+3 0 dya6 dya5 dya4 dya3 dya2 dya1 dya0

+4 0 dxb6 dxb5 dxb4 dxb3 dxb2 dxb1 dxb0

+5 0 dyb6 dyb5 dyb4 dyb3 dyb2 dyb1 dyb0

+.TE

+

+Bytes 4 and 5 describe the change that occurred since bytes 2 and 3

+were transmitted.

+.SS "Sun protocol"

+The \fBSun\fP protocol is the 3-byte version of the above 5-byte

+Mousesystems protocol: the last two bytes are not sent.

+.SS "MM protocol"

+The \fBMM\fP protocol uses 1 start bit, 8 data bits, odd parity and one

+stop bit at the speed of 1200 bits/sec. Data is sent to RxD in 3-byte

+packets. \fIdx\fP and \fIdy\fP are sent as single signed values, the

+sign bit indicating a negative value. \fIlb\fP (\fImb\fP, \fIrb\fP) are

+set when the left (middle, right) button is pressed:

+

+.TS

+center;

+r c c c c c c c c.

+byte d7 d6 d5 d4 d3 d2 d1 d0

+1 1 0 0 dxs dys lb mb rb

+2 0 dx6 dx5 dx4 dx3 dx2 dx1 dx0

+3 0 dy6 dy5 dy4 dy3 dy2 dy1 dy0

+.TE

+

+.SH FILES

+.TP

+.I /dev/mouse

+A commonly used symlink pointing to a mouse device.

+

+.SH "SEE ALSO"

+.BR ttys (4),

+.BR gpm (8)

+.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993

+.\"

+.\" This is free documentation; you can redistribute it and/or

+.\" modify it under the terms of the GNU General Public License as

+.\" published by the Free Software Foundation; either version 2 of

+.\" the License, or (at your option) any later version.

+.\"

+.\" The GNU General Public License's references to "object code"

+.\" and "executables" are to be interpreted as the output of any

+.\" document formatting or typesetting system, including

+.\" intermediate and printed output.

+.\"

+.\" This manual is distributed in the hope that it will be useful,

+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of

+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

+.\" GNU General Public License for more details.

+.\"

+.\" You should have received a copy of the GNU General Public

+.\" License along with this manual; if not, write to the Free

+.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,

+.\" USA.

+.\"

+.\" Modified Sat Jul 24 17:00:12 1993 by Rik Faith (faith@cs.unc.edu)

+.TH NULL 4 1992-11-21 "Linux" "Linux Programmer's Manual"

+.SH NAME

+null, zero \- data sink

+.SH DESCRIPTION

+Data written on a \fBnull\fP or \fBzero\fP special file is discarded.

+.PP

+Reads from the \fBnull\fP special file always return end of file, whereas

+reads from \fBzero\fP always return \e0 characters.

+.LP

+\fBnull\fP and \fBzero\fP are typically created by:

+.RS

+.sp

+mknod -m 666 /dev/null c 1 3

+.br

+mknod -m 666 /dev/zero c 1 5

+.br

+chown root:mem /dev/null /dev/zero

+.sp

+.RE

+.SH NOTES

+If these devices are not writable and readable for all users, many

+programs will act strange.

+.SH FILES

+.I /dev/null

+.br

+.I /dev/zero

+.SH "SEE ALSO"

+.BR chown (1),

+.BR mknod (1)

+.so man4/mem.4

+.so man4/pts.4

+.\" Hey Emacs! This file is -*- nroff -*- source.

+.\" This man page was written by Jeremy Phelps <jphelps@notreached.net>.

+.\" Notes added - aeb

+.\" Redistribute and revise at will.

+.\"

+.TH PTS 4 "2002-10-09" "Linux" "Linux Programmer's Manual"

+.SH NAME

+ptmx and pts \- pseudo-terminal master and slave

+.SH DESCRIPTION

+The file \fB/dev/ptmx\fP is a character file with major number 5 and

+minor number 2, usually of mode 0666 and owner.group of root.root.

+It is used to create a pseudo-terminal master and slave pair.

+.PP

+When a process opens \fB/dev/ptmx\fP, it gets a file

+descriptor for a pseudo-terminal master (PTM),

+and a pseudo-terminal slave (PTS) device is created in the

+.I /dev/pts

+directory. Each file descriptor obtained by opening \fB/dev/ptmx\fP

+is an independent PTM with its own associated PTS, whose path can

+be found by passing the descriptor to

+.BR ptsname (3).

+.PP

+Before opening the pseudo-terminal slave, you must pass the master's file

+descriptor to

+.BR grantpt (3)

+and

+.BR unlockpt (3).

+.PP

+Once both the pseudo-terminal master and slave are open, the slave provides

+processes with an interface that is identical to that of a real terminal.

+.PP

+Data written to the slave is presented on the master descriptor as input.

+Data written to the master is presented to the slave as input.

+.PP

+In practice, pseudo-terminals are used for implementing terminal emulators

+such as

+.BR xterm (1),

+in which data read from the pseudo-terminal master is interpreted by the

+application in the same way

+a real terminal would interpret the data, and for implementing remote-login

+programs such as

+.BR sshd (8),

+in which data read from the pseudo-terminal master is sent across the network

+to a client program that is connected to a terminal or terminal emulator.

+.PP

+Pseudo-terminals can also be used to send input to programs that normally

+refuse to read input from pipes (such as

+.BR su (8),

+and

+.BR passwd (8)).

+.SH FILES

+.IR /dev/ptmx ,

+.I /dev/pts/*

+.SH NOTES

+The Linux support for the above (known as Unix98 pty naming)

+is done using the

+.I devpts

+filesystem, that should be mounted on

+.IR /dev/pts .

+.LP

+Before this Unix98 scheme, master ptys were called

+.IR /dev/ptyp0 ", ..."

+and slave ptys

+.IR /dev/ttyp0 ", ..."

+and one needed lots of preallocated device nodes.

+.SH "SEE ALSO"

+.BR getpt (3),

+.BR grantpt (3),

+.BR ptsname (3),

+.BR unlockpt (3)

+.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993

+.\"

+.\" This is free documentation; you can redistribute it and/or

+.\" modify it under the terms of the GNU General Public License as

+.\" published by the Free Software Foundation; either version 2 of

+.\" the License, or (at your option) any later version.

+.\"

+.\" The GNU General Public License's references to "object code"

+.\" and "executables" are to be interpreted as the output of any

+.\" document formatting or typesetting system, including

+.\" intermediate and printed output.

+.\"

+.\" This manual is distributed in the hope that it will be useful,

+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of

+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

+.\" GNU General Public License for more details.

+.\"

+.\" You should have received a copy of the GNU General Public

+.\" License along with this manual; if not, write to the Free

+.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,

+.\" USA.

+.\"

+.\" Modified Sat Jul 24 17:01:11 1993 by Rik Faith (faith@cs.unc.edu)

+.TH RAM 4 1992-11-21 "Linux" "Linux Programmer's Manual"

+.SH NAME

+ram \- ram disk device

+.SH DESCRIPTION

+The \fBRam\fP device is a block device to access the ram disk in raw mode.

+.LP

+It is typically created by:

+.RS

+.sp

+mknod -m 660 /dev/ram b 1 1

+.br

+chown root:disk /dev/ram

+.sp

+.RE

+.SH FILES

+/dev/ram

+.SH "SEE ALSO"

+.BR chown (1),

+.BR mknod (1),

+.BR mount (8)

+.\" Copyright (c) 1997 John S. Kallal (kallal@voicenet.com)

+.\"

+.\" This is free documentation; you can redistribute it and/or

+.\" modify it under the terms of the GNU General Public License as

+.\" published by the Free Software Foundation; either version 2 of

+.\" the License, or (at your option) any later version.

+.\"

+.\" Some changes by tytso and aeb.

+.\"

+.TH RANDOM 4 2003-10-25 "Linux" "Linux Programmer's Manual"

+.SH NAME

+random, urandom \- kernel random number source devices

+.SH DESCRIPTION

+The character special files \fB/dev/random\fP and

+\fB/dev/urandom\fP (present since Linux 1.3.30)

+provide an interface to the kernel's random number generator.

+File \fB/dev/random\fP has major device number 1

+and minor device number 8. File \fB/dev/urandom\fP

+has major device number 1 and minor device number 9.

+.LP

+The random number generator gathers environmental noise

+from device drivers and other sources into an entropy pool.

+The generator also keeps an estimate of the

+number of bits of noise in the entropy pool.

+From this entropy pool random numbers are created.

+.LP

+When read, the \fB/dev/random\fP device will only return random bytes

+within the estimated number of bits of noise in the entropy

+pool. \fB/dev/random\fP should be suitable for uses that need very

+high quality randomness such as one-time pad or key generation.

+When the entropy pool is empty, reads from \fB/dev/random\fP will block

+until additional environmental noise is gathered.

+.LP

+When read, \fB/dev/urandom\fP device will return as many bytes as are

+requested. As a result, if there is not sufficient entropy in the

+entropy pool, the returned values are theoretically vulnerable to a

+cryptographic attack on the algorithms used by the driver. Knowledge of

+how to do this is not available in the current non-classified

+literature, but it is theoretically possible that such an attack may

+exist. If this is a concern in your application, use \fB/dev/random\fP

+instead.

+.SH CONFIGURING

+If your system does not have

+\fB/dev/random\fP and \fB/dev/urandom\fP created already, they

+can be created with the following commands:

+

+.nf

+ mknod -m 644 /dev/random c 1 8

+ mknod -m 644 /dev/urandom c 1 9

+ chown root:root /dev/random /dev/urandom

+.fi

+

+When a Linux system starts up without much operator interaction,

+the entropy pool may be in a fairly predictable state.

+This reduces the actual amount of noise in the entropy pool

+below the estimate. In order to counteract this effect, it helps to carry

+entropy pool information across shut-downs and start-ups.

+To do this, add the following lines to an appropriate script

+which is run during the Linux system start-up sequence:

+

+.nf

+ echo "Initializing kernel random number generator..."

+ # Initialize kernel random number generator with random seed

+ # from last shut-down (or start-up) to this start-up. Load and

+ # then save 512 bytes, which is the size of the entropy pool.

+ if [ -f /var/random-seed ]; then

+ cat /var/random-seed >/dev/urandom

+ fi

+ dd if=/dev/urandom of=/var/random-seed count=1

+.fi

+

+Also, add the following lines in an appropriate script which is

+run during the Linux system shutdown:

+

+.nf

+ # Carry a random seed from shut-down to start-up for the random

+ # number generator. Save 512 bytes, which is the size of the

+ # random number generator's entropy pool.

+ echo "Saving random seed..."

+ dd if=/dev/urandom of=/var/random-seed count=1

+.fi

+.SH "PROC INTERFACE"

+The files in the directory

+.I /proc/sys/kernel/random

+(present since 2.3.16) provide an additional interface to the

+.B /dev/random

+device.

+.LP

+The read-only file

+.I entropy_avail

+gives the available entropy. Normally, this will be 4096 (bits),

+a full entropy pool.

+.LP

+The file

+.I poolsize

+gives the size of the entropy pool. Normally, this will be 512 (bytes).

+It can be changed to any value for which an algorithm is available.

+Currently the choices are 32, 64, 128, 256, 512, 1024, 2048.

+.LP

+The file

+.I read_wakeup_threshold

+contains the number of bits of entropy required for waking up processes

+that sleep waiting for entropy from

+.BR /dev/random .

+The default is 64.

+The file

+.I write_wakeup_threshold

+contains the number of bits of entropy below which we wake up

+processes that do a

+.I select()

+or

+.I poll()

+for write access to

+.BR /dev/random .

+These values can be changed by writing to the files.

+.LP

+The read-only files

+.I uuid

+and

+.I boot_id

+contain random strings like 6fd5a44b-35f4-4ad4-a9b9-6b9be13e1fe9.

+The former is generated afresh for each read, the latter was

+generated once.

+.SH FILES

+/dev/random

+.br

+/dev/urandom

+.SH AUTHOR

+The kernel's random number generator was written by

+Theodore Ts'o (tytso@athena.mit.edu).

+.SH "SEE ALSO"

+mknod (1)

+.br

+RFC 1750, "Randomness Recommendations for Security"

+.\" sd.4

+.\" Copyright 1992 Rickard E. Faith (faith@cs.unc.edu)

+.\"

+.\" Permission is granted to make and distribute verbatim copies of this

+.\" manual provided the copyright notice and this permission notice are

+.\" preserved on all copies.

+.\"

+.\" Permission is granted to copy and distribute modified versions of this

+.\" manual under the conditions for verbatim copying, provided that the

+.\" entire resulting derived work is distributed under the terms of a

+.\" permission notice identical to this one.

+.\"

+.\" Since the Linux kernel and libraries are constantly changing, this

+.\" manual page may be incorrect or out-of-date. The author(s) assume no

+.\" responsibility for errors or omissions, or for damages resulting from

+.\" the use of the information contained herein. The author(s) may not

+.\" have taken the same level of care in the production of this manual,

+.\" which is licensed free of charge, as they might when working

+.\" professionally.

+.\"

+.\" Formatted or processed versions of this manual, if unaccompanied by

+.\" the source, must acknowledge the copyright and authors of this work.

+.\"

+.TH SD 4 1992-12-17 "" "Linux Programmer's Manual"

+.SH NAME

+sd \- Driver for SCSI Disk Drives

+.SH SYNOPSIS

+#include <linux/hdreg.h> /* for HDIO_GETGEO */

+#include <linux/fs.h> /* for BLKGETSIZE and BLKRRPART */

+.SH CONFIG

+The block device name has the following form:

+.BI sd lp,

+where

+.I l

+is a letter denoting the physical drive, and

+.I p

+is a number denoting the partition on that physical drive. Often, the

+partition number,

+.IR p ,

+will be left off when the device corresponds to the whole drive.

+

+SCSI disks have a major device number of 8, and a minor device number of

+the form (16 *

+.IR drive_number ") + " partition_number ,

+where

+.I drive_number

+is the number of the physical drive in order of detection, and

+.I partition_number

+is as follows:

+.sp

+partition 0 is the whole drive

+.br

+partitions 1-4 are the DOS "primary" partitions

+.br

+partitions 5-8 are the DOS "extended" (or "logical") partitions

+

+For example,

+.B /dev/sda

+will have major 8, minor 0, and will refer to all of the first SCSI drive

+in the system; and

+.B /dev/sdb3

+will have major 8, minor 19, and will refer to the third DOS "primary"

+partition on the second SCSI drive in the system.

+

+At this time, only block devices are provided. Raw devices have not yet

+been implemented.

+.SH DESCRIPTION

+The following

+.IR ioctl s

+are provided:

+.TP

+HDIO_GETGEO

+.RS

+Returns the BIOS disk parameters in the following structure:

+.RS

+.nf

+.ft B

+struct hd_geometry {

+ unsigned char heads;

+ unsigned char sectors;

+ unsigned short cylinders;

+ unsigned long start;

+};

+.ft R

+.fi

+.RE

+

+A pointer to this structure is passed as the

+.BR ioctl (2)

+parameter.

+

+The information returned in the parameter is the disk geometry of the drive

+.I "as understood by DOS!"

+This geometry is

+.I not

+the physical geometry of the drive. It is used when constructing the

+drive's partition table, however, and is needed for convenient operation

+of

+.BR fdisk (1),

+.BR efdisk (1),

+and

+.BR lilo (1).

+If the geometry information is not available, zero will be returned for all

+of the parameters.

+.RE

+.TP

+BLKGETSIZE

+Returns the device size in sectors. The

+.BR ioctl (2)

+parameter should be a pointer to a

+.BR long .

+.TP

+BLKRRPART

+Forces a re-read of the SCSI disk partition tables. No parameter is needed.

+

+The

+.BR scsi (4)

+.IR ioctl s

+are also supported. If the

+.BR ioctl (2)

+parameter is required, and it is NULL, then

+.IR ioctl ()

+will return -EINVAL.

+.SH FILES

+/dev/sd[a-h]: the whole device

+.br

+/dev/sd[a-h][0-8]: individual block partitions

+.SH "SEE ALSO"

+.BR scsi (4)

+.\" (C)Copyright 1999-2003 Marvell(R) -- linux@syskonnect.de

+.\" sk98lin.4 1.1 2003/12/17 10:03:18

+.\" This manpage can be viewed using `groff -Tascii -man sk98lin.4 | less`

+.\"

+.\" This is free documentation; you can redistribute it and/or

+.\" modify it under the terms of the GNU General Public License as

+.\" published by the Free Software Foundation; either version 2 of

+.\" the License, or (at your option) any later version.

+.\"

+.\" The GNU General Public License's references to "object code"

+.\" and "executables" are to be interpreted as the output of any

+.\" document formatting or typesetting system, including

+.\" intermediate and printed output.

+.\"

+.\" This manual is distributed in the hope that it will be useful,

+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of

+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

+.\" GNU General Public License for more details.

+.\"

+.\" You should have received a copy of the GNU General Public

+.\" License along with this manual; if not, write to the Free

+.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,

+.\" USA.

+.\"

+.TH SK98LIN 4 "2003/12/17 10:03:18" "sk98lin 6.21"

+.SH NAME

+sk98lin \- Marvell/SysKonnect Gigabit Ethernet driver v6.21

+.SH SYNOPSIS

+.B insmod sk98lin.o

+.RB [ Speed_A=\c

+.IR i,j,... ]

+.RB [ Speed_B=\c

+.IR i,j,... ]

+.RB [ AutoNeg_A=\c

+.IR i,j,... ]

+.RB [ AutoNeg_B=\c

+.IR i,j,... ]

+.RB [ DupCap_A=\c

+.IR i,j,... ]

+.RB [ DupCap_B=\c

+.IR i,j,... ]

+.RB [ FlowCtrl_A=\c

+.IR i,j,... ]

+.RB [ FlowCtrl_B=\c

+.IR i,j,... ]

+.RB [ Role_A=\c

+.IR i,j,... ]

+.RB [ Role_B=\c

+.IR i,j,... ]

+.RB [ ConType=\c

+.IR i,j,... ]

+.RB [ Moderation=\c

+.IR i,j,... ]

+.RB [ IntsPerSec=\c

+.IR i,j,... ]

+.RB [ PrefPort=\c

+.IR i,j,... ]

+.RB [ RlmtMode=\c

+.IR i,j,... ]

+.SH DESCRIPTION

+.B sk98lin

+is the Gigabit Ethernet driver for Marvell and SysKonnect network adapter cards.

+It supports SysKonnect SK-98xx/SK-95xx compliant Gigabit Ethernet Adapter and any Yukon compliant chipset.

+

+When loading the driver using insmod, parameters for the network adapter cards might be stated as a sequence of comma separated commands. If for instance two network adapters are installed and AutoNegotiation on Port A of the first adapter should be ON, but on the Port A of the second adapter switched OFF, one must enter:

+

+ insmod sk98lin.o AutoNeg_A=On,Off

+

+After

+.B sk98lin

+is bound to one or more adapter cards and the

+.IR /proc

+filesystem is mounted on your system, a dedicated statistics file will be created in folder

+.IR /proc/net/sk98lin

+for all ports of the installed network adapter cards. Those files are named

+.IR eth[x]

+whereas

+.IR x

+is the number of the interface that has been assigned to a dedicated port by the system.

+

+If loading is finished, any desired IP address can be assigned to the respective

+.IR eth[x]

+interface using the

+.BR ifconfig (8)

+command. This causes the adapter to connect to the Ethernet and to display a status message on the console saying "ethx: network connection up using port y" followed by the configured or detected connection parameters.

+

+The

+.B sk98lin

+also supports large frames (also called jumbo frames). Using jumbo frames can improve throughput tremendously when transferring large amounts of data. To enable large frames, the MTU (maximum transfer unit) size for an interface is to be set to a high value. The default MTU size is 1500 and can be changed up to 9000 (bytes). Setting the MTU size can be done when assigning the IP address to the interface or later by using the

+.BR ifconfig (8)

+command with the mtu parameter. If for instance eth0 needs an IP address and a large frame MTU size, the following two commands might be used:

+

+ ifconfig eth0 10.1.1.1

+ ifconfig eth0 mtu 9000

+

+Those two commands might even be combined into one:

+

+ ifconfig eth0 10.1.1.1 mtu 9000

+

+Note that large frames can only be used if your network infrastructure allows to do so. This means, that any switch being used in your Ethernet must also support large frames. Quite some switches support large frames, but need to be configured to do so. Most of the times, their default setting is to support only standard frames with an MTU size of 1500 (bytes). In addition to the switches inside the network, all network adapters that are to be used must also be enabled regarding jumbo frames. If an adapter is not set to receive large frames it will simply drop them.

+

+Switching back to the standard Ethernet frame size can be done by using the

+.BR ifconfig (8)

+command again:

+

+ ifconfig eth0 mtu 1500

+

+The Marvell/SysKonnect Gigabit Ethernet driver for Linux is able to support VLAN and Link Aggregation according to IEEE standards 802.1, 802.1q, and 802.3ad. Those features are only available after installation of open source modules which can be found on the Internet:

+

+.IR VLAN \c

+: http://www.candelatech.com/~greear/vlan.html

+.br

+.IR Link

+.IR Aggregation \c

+: http://www.st.rim.or.jp/~yumo

+

+.br

+Note that Marvell/SysKonnect does not offer any support for these open source modules and does not take the responsibility for any kind of failures or problems arising when using these modules.

+.SH PARAMETERS

+.TP

+.BI Speed_A= i,j,...

+This parameter is used to set the speed capabilities of port A of an adapter card. It is only valid for Yukon copper adapters. Possible values are:

+.IR 10

+,

+.IR 100

+,

+.IR 1000

+or

+.IR Auto

+whereas

+.IR Auto

+is the default. Usually, the speed is negotiated between the two ports during link establishment. If this fails, a port can be forced to a specific setting with this parameter.

+.TP

+.BI Speed_B= i,j,...

+This parameter is used to set the speed capabilities of port B of an adapter card. It is only valid for Yukon copper adapters. Possible values are:

+.IR 10

+,

+.IR 100

+,

+.IR 1000

+or

+.IR Auto

+whereas

+.IR Auto

+is the default. Usually, the speed is negotiated between the two ports during link establishment. If this fails, a port can be forced to a specific setting with this parameter.

+.TP

+.BI AutoNeg_A= i,j,...

+Enables or disables the use of autonegotiation of port A of an adapter card. Possible values are:

+.IR On

+,

+.IR Off

+or

+.IR Sense

+whereas

+.IR On

+is the default. The

+.IR Sense

+mode automatically detects whether the link partner supports auto-negotiation or not.

+.TP

+.BI AutoNeg_B= i,j,...

+Enables or disables the use of autonegotiation of port B of an adapter card. Possible values are:

+.IR On

+,

+.IR Off

+or

+.IR Sense

+whereas

+.IR On

+is the default. The

+.IR Sense

+mode automatically detects whether the link partner supports auto-negotiation or not.

+.TP

+.BI DupCap_A= i,j,...

+This parameter indicates the duplex mode to be used for port A of an adapter card. Possible values are:

+.IR Half

+,

+.IR Full

+or

+.IR Both

+whereas

+.IR Both

+is the default. This parameter is only relevant if AutoNeg_A of port A is not set to

+.IR Sense.

+If AutoNeg_A is set to

+.IR On

+, all three values of DupCap_A (

+.IR Half

+,

+.IR Full

+or

+.IR Both

+) might be stated. If AutoNeg_A is set to

+.IR Off

+, only DupCap_A values

+.IR Full

+and

+.IR Half

+are allowed. This DupCap_A parameter is useful if your link partner does not support all possible duplex combinations.

+.TP

+.BI DupCap_B= i,j,...

+This parameter indicates the duplex mode to be used for port B of an adapter card. Possible values are:

+.IR Half

+,

+.IR Full

+or

+.IR Both

+whereas

+.IR Both

+is the default. This parameter is only relevant if AutoNeg_B of port B is not set to

+.IR Sense.

+If AutoNeg_B is set to

+.IR On

+, all three values of DupCap_B (

+.IR Half

+,

+.IR Full

+or

+.IR Both

+) might be stated. If AutoNeg_B is set to

+.IR Off

+, only DupCap_B values

+.IR Full

+and

+.IR Half

+are allowed. This DupCap_B parameter is useful if your link partner does not support all possible duplex combinations.

+.TP

+.BI FlowCtrl_A= i,j,...

+This parameter can be used to set the flow control capabilities the port reports during auto-negotiation. Possible values are:

+.IR Sym

+,

+.IR SymOrRem

+,

+.IR LocSend

+or

+.IR None

+whereas

+.IR SymOrRem

+is the default. The different modes have the following meaning:

+

+.br

+.IR Sym

+= Symmetric

+ both link partners are allowed to send PAUSE frames

+.br

+.IR SymOrRem

+= SymmetricOrRemote

+ both or only remote partner are allowed to send PAUSE frames

+.br

+.IR LocSend

+= LocalSend

+ only local link partner is allowed to send PAUSE frames

+.br

+.IR None

+= None

+ no link partner is allowed to send PAUSE frames

+

+Note that this parameter is ignored if AutoNeg_A is set to

+.IR Off .

+.TP

+.BI FlowCtrl_B= i,j,...

+This parameter can be used to set the flow control capabilities the port reports during auto-negotiation. Possible values are:

+.IR Sym

+,

+.IR SymOrRem

+,

+.IR LocSend

+or

+.IR None

+whereas

+.IR SymOrRem

+is the default. The different modes have the following meaning:

+

+.IR Sym

+= Symmetric

+ both link partners are allowed to send PAUSE frames

+.br

+.IR SymOrRem

+= SymmetricOrRemote

+ both or only remote partner are allowed to send PAUSE frames

+.br

+.IR LocSend

+= LocalSend

+ only local link partner is allowed to send PAUSE frames

+.br

+.IR None

+= None

+ no link partner is allowed to send PAUSE frames

+.br

+

+Note that this parameter is ignored if AutoNeg_B is set to

+.IR Off .

+.TP

+.BI Role_A= i,j,...

+This parameter is only valid for 1000Base-T adapter cards. For two 1000Base-T ports to communicate, one must take the role of the master (providing timing information), while the other must be the slave. Possible values are:

+.IR Auto

+,

+.IR Master

+or

+.IR Slave

+whereas

+.IR Auto

+is the default. Usually, the role of a port is negotiated between two ports during link establishment, but if that fails the port A of an adapter card can be forced to a specific setting with this parameter.

+.TP

+.BI Role_B= i,j,...

+This parameter is only valid for 1000Base-T adapter cards. For two 1000Base-T ports to communicate, one must take the role of the master (providing timing information), while the other must be the slave. Possible values are:

+.IR Auto

+,

+.IR Master

+or

+.IR Slave

+whereas

+.IR Auto

+is the default. Usually, the role of a port is negotiated between two ports during link establishment, but if that fails the port B of an adapter card can be forced to a specific setting with this parameter.

+.TP

+.BI ConType= i,j,...

+This parameter is a combination of all five per-port parameters within one single parameter. This simplifies the configuration of both ports of an adapter card. The different values of this variable reflect the most meaningful combinations of port parameters. Possible values and their corresponding combination of per-port parameters:

+

+.br

+.ad l

+ConType | DupCap AutoNeg FlowCtrl Role Speed

+--------+-------------------------------------------

+.br

+.IR Auto \c

+ | Both On SymOrRem Auto Auto

+.br

+.IR 100FD \c

+ | Full Off None Auto 100

+.br

+.IR 100HD \c

+ | Half Off None Auto 100

+.br

+.IR 10FD \c

+ | Full Off None Auto 10

+.br

+.IR 10HD \c

+ | Half Off None Auto 10

+

+.ad b

+Stating any other port parameter together with this

+.IR ConType

+parameter will result in a merged configuration of those settings. This is due to

+the fact, that the per-port parameters (e.g.

+.IR Speed_A

+) have a higher priority than the combined variable

+.IR ConType

+.

+.TP

+.BI Moderation= i,j,...

+Interrupt moderation is employed to limit the maximum number of interrupts the driver has to serve. That is, one or more interrupts (which indicate any transmit or receive packet to be processed) are queued until the driver processes them. When queued interrupts are to be served, is determined by the

+.IR IntsPerSec

+parameter, which is explained later below. Possible moderation modes are:

+.IR None

+,

+.IR Static

+or

+.IR Dynamic

+whereas

+.IR None

+is the default. The different modes have the following meaning:

+

+.IR None

+No interrupt moderation is applied on the adapter card. Therefore, each transmit or receive interrupt is served immediately as soon as it appears on the interrupt line of the adapter card.

+

+.br

+.IR Static

+Interrupt moderation is applied on the adapter card. All transmit and receive interrupts are queued until a complete moderation interval ends. If such a moderation interval ends, all queued interrupts are processed in one big bunch without any delay. The term

+.IR Static

+reflects the fact, that interrupt moderation is always enabled, regardless how much network load is currently passing via a particular interface. In addition, the duration of the moderation interval has a fixed length that never changes while the driver is operational.

+

+.br

+.IR Dynamic

+Interrupt moderation might be applied on the adapter card, depending on the load of the system. If the driver detects that the system load is too high, the driver tries to shield the system against too much network load by enabling interrupt moderation. If - at a later time - the CPU utilization decreases again (or if the network load is negligible) the interrupt moderation will automatically be disabled.

+

+Interrupt moderation should be used when the driver has to handle one or more interfaces with a high network load, which - as a consequence - leads also to a high CPU utilization. When moderation is applied in such high network load situations, CPU load might be reduced by 20-30% on slow computers.

+

+Note that the drawback of using interrupt moderation is an increase of the round-trip-time (RTT), due to the queuing and serving of interrupts at dedicated

+moderation times.

+.TP

+.BI IntsPerSec= i,j,...

+This parameter determines the length of any interrupt moderation interval.

+Assuming that static interrupt moderation is to be used, an

+.IR IntsPerSec

+parameter value of 2000 will lead to an interrupt moderation interval of

+500 microseconds. Possible values for this parameter are in the range of 30...40000 (interrupts per second). The default value is 2000.

+

+This parameter is only used, if either static or dynamic interrupt moderation

+is enabled on a network adapter card. This parameter is ignored if no moderation is

+applied.

+

+Note that the duration of the moderation interval is to be chosen with care.

+At first glance, selecting a very long duration (e.g. only 100 interrupts per

+second) seems to be meaningful, but the increase of packet-processing delay

+is tremendous. On the other hand, selecting a very short moderation time might

+compensate the use of any moderation being applied.

+.TP

+.BI PrefPort= i,j,...

+This parameter is used to force the preferred port to A or B (on dual-port network adapters). The preferred port is the one that is used if both ports A and B are detected as fully functional. Possible values are:

+.IR A

+or

+.IR B

+whereas

+.IR A

+is the default.

+.TP

+.BI RlmtMode= i,j,...

+RLMT monitors the status of the port. If the link of the active port fails, RLMT switches immediately to the standby link. The virtual link is maintained as long as at least one 'physical' link is up. This parameters states how RLMT should monitor both ports. Possible values are:

+.IR CheckLinkState

+,

+.IR CheckLocalPort

+,

+.IR CheckSeg

+or

+.IR DualNet

+whereas

+.IR CheckLinkState

+is the default. The different modes have the following meaning:

+

+.IR CheckLinkState

+Check link state only: RLMT uses the link state reported by the adapter hardware for each individual port to determine whether a port can be used for all network traffic or not.

+

+.br

+.IR CheckLocalPort

+In this mode, RLMT monitors the network path between the two ports of an adapter by regularly exchanging packets between them. This mode requires a network configuration in which the two ports are able to "see" each other (i.e. there must not be any router between the ports).

+

+.br

+.IR CheckSeg

+Check local port and segmentation: This mode supports the same functions as the CheckLocalPort mode and additionally checks network segmentation between the ports. Therefore, this mode is only to be used if Gigabit Ethernet switches are installed on the network that have been configured to use the Spanning Tree protocol.

+

+.br

+.IR DualNet

+In this mode, ports A and B are used as separate devices. If you have a dual port adapter, port A will be configured as

+.IR eth[x] and port B as

+.IR eth[x+1]

+. Both ports can be used independently with distinct IP addresses. The preferred port setting is not used. RLMT is turned off.

+

+Note that RLMT modes

+.IR CheckLocalPort

+and

+.IR CheckLinkState

+are designed to operate in configurations where a network path between the ports on one adapter exists. Moreover, they are not designed to work where adapters are connected back-to-back.

+.SH FILES

+.TP

+.B /proc/net/sk98lin/eth[x]

+.br

+The statistics file of a particular interface of an adapter card. It contains generic information about the adapter card plus a detailed summary of all transmit and receive counters.

+.TP

+.B /usr/src/linux/Documentation/network/sk98lin.txt

+.br

+This is the

+.IR README

+file of the

+.IR sk98lin

+driver. It contains a detailed installation HOWTO and describes all parameters of the driver. It denotes also common problems and provides the solution to them.

+.SH BUGS

+Report any bugs to linux@syskonnect.de

+.SH AUTHORS

+Ralph Roesler \- rroesler@syskonnect.de

+.br

+Mirko Lindner \- mlindner@syskonnect.de

+.SH "SEE ALSO"

+modprobe(8), insmod(8), ifconfig(8).

+.\" Copyright 1995 Robert K. Nichols (Robert.K.Nichols@att.com)

+.\" Copyright 1999 Kai M�kisara (Kai.Makisara@metla.fi)

+.\"

+.\" Permission is granted to make and distribute verbatim copies of this

+.\" manual provided the copyright notice and this permission notice are

+.\" preserved on all copies.

+.\"

+.\" Permission is granted to copy and distribute modified versions of this

+.\" manual under the conditions for verbatim copying, provided that the

+.\" entire resulting derived work is distributed under the terms of a

+.\" permission notice identical to this one.

+.\"

+.\" Since the Linux kernel and libraries are constantly changing, this

+.\" manual page may be incorrect or out-of-date. The author(s) assume no

+.\" responsibility for errors or omissions, or for damages resulting from

+.\" the use of the information contained herein. The author(s) may not

+.\" have taken the same level of care in the production of this manual,

+.\" which is licensed free of charge, as they might when working

+.\" professionally.

+.\"

+.\" Formatted or processed versions of this manual, if unaccompanied by

+.\" the source, must acknowledge the copyright and authors of this work.

+.TH ST 4 1999-01-18 "Linux 2.0 - 2.2" "Linux Programmer's Manual"

+.SH NAME

+st \- SCSI tape device

+.SH SYNOPSIS

+.nf

+.B #include <sys/mtio.h>

+.sp

+.BI "int ioctl(int " fd ", int " request " [, (void *)" arg3 "]);"

+.BI "int ioctl(int " fd ", \s-1MTIOCTOP\s+1, (struct mtop *)" mt_cmd );

+.BI "int ioctl(int " fd ", \s-1MTIOCGET\s+1, (struct mtget *)" mt_status );

+.BI "int ioctl(int " fd ", \s-1MTIOCPOS\s+1, (struct mtpos *)" mt_pos );

+.fi

+.SH DESCRIPTION

+The

+.B st

+driver provides the interface to a variety of SCSI tape devices.

+Currently, the driver takes control of all detected devices of type

+\(lqsequential-access.\(rq

+The

+.B st

+driver uses major device number 9.

+.PP

+Each device uses eight minor device numbers. The lower-most five bits

+in the minor numbers are assigned sequentially in the order of

+detection. The minor numbers can be grouped into

+two sets of four numbers: the principal (auto-rewind) minor device numbers,

+.IR n ,

+and a \(lqno-rewind\(rq device numbers,

+.IR "" ( n "+ 128)."

+Devices opened using the principal device number will be sent a

+\s-1REWIND\s+1 command when they are closed.

+Devices opened using the \(lqno-rewind\(rq device number will not.

+(Note that using an auto-rewind device for positioning the tape with,

+for instance, mt does not lead to the desired result: the tape is

+rewound after the mt command and the next command starts from the

+beginning of the tape).

+.PP

+Within each group, four minor numbers are available to define

+devices with different characteristics (block size, compression,

+density, etc.) When the system starts up, only the first device is

+available. The other three are activated when the default

+characteristics are defined (see below). (By changing compile-time

+constants, it is possible to change the balance between the maximum

+number of tape drives and the number of minor numbers for each

+drive. The default allocation allows control of 32 tape drives.

+For instance, it is possible to control up to 64 tape drives

+with two minor numbers for different options.)

+.PP

+Devices are typically created by:

+.RS

+.nf

+mknod -m 666 /dev/st0 c 9 0

+mknod -m 666 /dev/st0l c 9 32

+mknod -m 666 /dev/st0m c 9 64

+mknod -m 666 /dev/st0a c 9 96

+mknod -m 666 /dev/nst0 c 9 128

+mknod -m 666 /dev/nst0l c 9 160

+mknod -m 666 /dev/nst0m c 9 192

+mknod -m 666 /dev/nst0a c 9 224

+.fi

+.RE

+.PP

+There is no corresponding block device.

+.PP

+The driver uses an internal buffer that has to be large enough to hold

+at least one tape block. In kernels before 2.1.121, the buffer is

+allocated as one contiguous block. This limits the block size to the

+largest contiguous block of memory the kernel allocator can provide.

+The limit is currently 128 kB for the 32-bit architectures and

+256 kB for the 64-bit architectures. In newer kernels the driver

+allocates the buffer in several parts if necessary. By default, the

+maximum number of parts is 16. This means that the maximum block size

+is very large (2 MB if allocation of 16 blocks of 128 kB succeeds).

+.PP

+The driver's internal buffer size is determined by a compile-time

+constant which can be overridden with a kernel startup option.

+In addition to this, the driver tries to allocate a larger temporary

+buffer at run-time if necessary. However, run-time allocation of large

+contiguous blocks of memory may fail and it is advisable not to rely

+too much on dynamic buffer allocation with kernels older than 2.1.121

+(this applies also to demand-loading the driver with kerneld or kmod).

+.PP

+The driver does not specifically support any tape drive brand or

+model. After system start-up the tape device options are defined by

+the drive firmware. For example, if the drive firmware selects fixed

+block mode, the tape device uses fixed block mode. The options can

+be changed with explicit

+.B ioctl()

+calls and remain in effect when the device is closed and reopened.

+Setting the options affects both the auto-rewind and the non-rewind

+device.

+.PP

+Different options can be specified for the different devices within

+the subgroup of four. The options take effect when the device is

+opened. For example, the system administrator can define

+one device that writes in fixed block mode with a certain block size,

+and one which writes in variable block mode (if the drive supports

+both modes).

+.PP

+The driver supports

+.B tape partitions

+if they are supported by the drive. (Note that the tape partitions

+have nothing to do with disk partitions. A partitioned tape can be

+seen as several logical tapes within one medium.) Partition

+support has to be enabled with an ioctl. The tape

+location is preserved within each partition across partition changes.

+The partition used for subsequent tape operations is

+selected with an ioctl. The partition switch is executed together with

+the next tape operation in order to avoid unnecessary tape

+movement. The maximum number of partitions on a tape is defined by a

+compile-time constant (originally four). The driver contains an

+ioctl that can format a tape with either one or two partitions.

+.PP

+Device

+.B /dev/tape

+is usually created as a hard or soft link to the default tape device

+on the system.

+.SH "DATA TRANSFER"

+The driver supports operation in both fixed block mode and variable

+block mode (if supported by the drive). In fixed block mode the drive

+writes blocks of the specified size and the block size is not

+dependent on the byte counts of the write system calls. In variable

+block mode one tape block is written for each write call and the byte

+count determines the size of the corresponding tape block. Note that

+the blocks on the tape do don't contain any information about the

+writing mode: when reading, the only important thing is to use

+commands that accept the block sizes on the tape.

+.PP

+In variable block mode the read byte count does not have to match

+the tape block size exactly. If the byte count is larger than the

+next block on tape, the driver returns the data and the function

+returns the actual block size. If the block size is larger than the

+byte count, the requested amount of data from the start of the block

+is returned and the rest of the block is discarded.

+.PP

+In fixed block mode the read byte counts can be arbitrary if

+buffering is enabled, or a multiple of the tape block size if

+buffering is disabled. Kernels before 2.1.121 allow writes with

+arbitrary byte count if buffering is enabled. In all other cases

+(kernel before 2.1.121 with buffering disabled or newer kernel) the

+write byte count must be a multiple of the tape block size.

+.PP

+A filemark is automatically written to tape if the last tape operation

+before close was a write.

+.PP

+When a filemark is encountered while reading, the following

+happens. If there are data remaining in the buffer when the filemark

+is found, the buffered data is returned. The next read returns zero

+bytes. The following read returns data from the next file. The end of

+recorded data is signaled by returning zero bytes for two consecutive

+read calls. The third read returns an error.

+.SH IOCTLS

+The driver supports three ioctl requests.

+Requests not recognized by the

+.B st

+driver are passed to the

+.B SCSI

+driver.

+The definitions below are from

+.BR /usr/include/linux/mtio.h :

+.SS "\s-1MTIOCTOP\s+1 \- Perform a tape operation"

+.PP

+This request takes an argument of type

+.BR "(struct mtop *)" .

+Not all drives support all operations.

+The driver returns an EIO error if the drive rejects an operation.

+.PP

+.nf

+.ta +.4i +.7i +1i

+/* Structure for \s-1MTIOCTOP\s+1 \- mag tape op command: */

+struct mtop {

+ short mt_op; /* operations defined below */

+ int mt_count; /* how many of them */

+};

+.fi

+.PP

+Magnetic Tape operations for normal tape use:

+.PD 0

+.IP MTBSF 14

+Backward space over

+.B mt_count

+filemarks.

+.IP MTBSFM

+Backward space over

+.B mt_count

+filemarks.

+Reposition the tape to the EOT side of the last filemark.

+.IP MTBSR

+Backward space over

+.B mt_count

+records (tape blocks).

+.IP MTBSS

+Backward space over

+.B mt_count

+setmarks.

+.IP MTCOMPRESSION

+Enable compression of tape data within the drive if

+.B mt_count

+is non-zero and disable compression if

+.B mt_count

+is zero. This command uses the MODE page 15 supported by most DATs.

+.IP MTEOM

+Go to the end of the recorded media (for appending files).

+.IP MTERASE

+Erase tape.

+.IP MTFSF

+Forward space over

+.B mt_count

+filemarks.

+.IP MTFSFM

+Forward space over

+.B mt_count

+filemarks.

+Reposition the tape to the BOT side of the last filemark.

+.IP MTFSR

+Forward space over

+.B mt_count

+records (tape blocks).

+.IP MTFSS

+Forward space over

+.B mt_count

+setmarks.

+.IP MTLOAD

+Execute the SCSI load command. A special case is available for some HP

+autoloaders. If

+.B mt_count

+is the constant MT_ST_HPLOADER_OFFSET plus a number, the number is

+sent to the drive to control the autoloader.

+.IP MTLOCK

+Lock the tape drive door.

+.IP MTMKPART

+Format the tape into one or two partitions. If

+.B mt_count

+is non-zero, it gives the size of the first partition and the second

+partition contains the rest of the tape. If

+.B mt_count

+is zero, the tape is formatted into one partition.

+This command is not allowed for a drive unless the partition support

+is enabled for the drive (see MT_ST_CAN_PARTITIONS below).

+.IP MTNOP

+No op \- flushes the driver's buffer as a side effect.

+Should be used before reading status with \s-1MTIOCGET\s+1.

+.IP MTOFFL

+Rewind and put the drive off line.

+.IP MTRESET

+Reset drive.

+.IP MTRETEN

+Retension tape.

+.IP MTREW

+Rewind.

+.IP MTSEEK

+Seek to the tape block number specified in

+.BR mt_count .

+This operation requires either a SCSI-2 drive that supports the \s-1LOCATE\s+1

+command (device-specific address)

+or a Tandberg-compatible SCSI-1 drive (Tandberg, Archive

+Viper, Wangtek, ... ).

+The block number should be one that was previously returned by

+\s-1MTIOCPOS\s+1 if device-specific addresses are used.

+.IP MTSETBLK

+Set the drive's block length to the value specified in

+.BR mt_count .

+A block length of zero sets the drive to variable block size mode.

+.IP MTSETDENSITY

+Set the tape density to the code in

+.BR mt_count .

+The density codes supported by a drive can be found from the drive

+documentation.

+.IP MTSETPART

+The active partition is switched to

+.B mt_count .

+The partitions are numbered from zero. This command is not allowed for

+a drive unless the partition support is enabled for the drive (see

+MT_ST_CAN_PARTITIONS below).

+.IP MTUNLOAD

+Execute the SCSI unload command (does not eject the tape).

+.IP MTUNLOCK

+Unlock the tape drive door.

+.IP MTWEOF

+Write

+.B mt_count

+filemarks.

+.IP MTWSM

+Write

+.B mt_count

+setmarks.

+.PD

+.PP

+Magnetic Tape operations for setting of device options (by the superuser):

+.PD 0

+.IP MTSETDRVBUFFER 8

+Set various drive and driver options according to bits encoded in

+.BR mt_count .

+These consist of the drive's buffering mode, 13 Boolean driver

+options, the buffer write threshold, defaults for the block size and

+density, and timeouts (only in kernels >= 2.1).

+A single operation can affect only one item in the list above (the

+Booleans counted as one item.)

+.PD

+.IP

+A value having zeros in the high-order 4 bits will be used to set the

+drive's buffering mode.

+The buffering modes are:

+.RS 12

+.IP 0 4

+The drive will not report \s-1GOOD\s+1 status on write commands until the data

+blocks are actually written to the medium.

+.PD 0

+.IP 1

+The drive may report \s-1GOOD\s+1 status on write commands as soon as all the

+data has been transferred to the drive's internal buffer.

+.IP 2

+The drive may report \s-1GOOD\s+1 status on write commands as soon as (a) all

+the data has been transferred to the drive's internal buffer, and

+(b) all buffered data from different initiators has been successfully

+written to the medium.

+.PD

+.RE

+.IP ""

+To control the write threshold the value in

+.B mt_count

+must include the constant

+\s-1MT_ST_WRITE_THRESHOLD\s+1 logically ORed with a block count in the low 28

+bits.

+The block count refers to 1024-byte blocks, not the physical block

+size on the tape.

+The threshold cannot exceed the driver's internal buffer size (see

+.BR \s-1DESCRIPTION\s+1 ,

+above).

+.IP

+To set and clear the Boolean options

+the value in

+.B mt_count

+must include one the constants \s-1MT_ST_BOOLEANS\s+1,

+\s-1MT_ST_SETBOOLEANS\s+1, \s-1MT_ST_CLEARBOOLEANS\s+1, or

+\s-1MT_ST_DEFBOOLEANS\s+1 logically ORed with

+whatever combination of the following options is desired.

+Using \s-1MT_ST_BOOLEANS\s+1 the options can be set to the values

+defined in the corresponding bits. With \s-1MT_ST_SETBOOLEANS\s+1 the

+options can be selectively set and with \s-1MT_ST_DEFBOOLEANS\s+1

+selectively cleared.

+.IP ""

+The default options for a tape device are set with

+\s-1MT_ST_DEFBOOLEANS\s+1. A non-active tape device (e.g., device with

+minor 32 or 160) is activated when the default options for it are

+defined the first time. An activated device inherits from the device

+activated at start-up the options not set explicitly.

+.IP ""

+The Boolean options are:

+.IP

+.PD 0

+.RS

+.IP "\s-1MT_ST_BUFFER_WRITES\s+1 (Default: true)"

+Buffer all write operations in fixed block mode.

+If this option is false and the drive uses a fixed block size, then

+all write operations must be for a multiple of the block size.

+This option must be set false to write reliable multi-volume archives.

+.IP "\s-1MT_ST_ASYNC_WRITES\s+1 (Default: true)"

+When this options is true write operations return immediately without

+waiting for the data to be transferred to the drive if the data fits

+into the driver's buffer.

+The write threshold determines how full the buffer must be before a

+new SCSI write command is issued.

+Any errors reported by the drive will be held until the next

+operation.

+This option must be set false to write reliable multi-volume archives.

+.IP "\s-1MT_ST_READ_AHEAD\s+1 (Default: true)"

+This option causes the driver to provide read buffering and

+read-ahead in fixed block mode.

+If this option is false and the drive uses a fixed block size, then

+all read operations must be for a multiple of the block size.

+.IP "\s-1MT_ST_TWO_FM\s+1 (Default: false)"

+This option modifies the driver behavior when a file is closed.

+The normal action is to write a single filemark.

+If the option is true the driver will write two filemarks and

+backspace over the second one.

+.PD

+.IP

+Note:

+This option should not be set true for QIC tape drives since they are

+unable to overwrite a filemark.

+These drives detect the end of recorded data by testing for blank tape

+rather than two consecutive filemarks. Most other current drives also

+detect the end of recorded data and using two filemarks is usually

+necessary only when interchanging tapes with some other systems.

+.PP

+.PD 0

+.IP "\s-1MT_ST_DEBUGGING\s+1 (Default: false)"

+This option turns on various debugging messages from the driver

+(effective only if the driver was compiled with \s-1DEBUG\s+1 defined

+non-zero).

+.IP "\s-1MT_ST_FAST_EOM\s+1 (Default: false)"

+This option causes the \s-1MTEOM\s+1 operation to be sent directly to the

+drive, potentially speeding up the operation but causing the driver to

+lose track of the current file number normally returned by the

+\s-1MTIOCGET\s+1 request.

+If \s-1MT_ST_FAST_EOM\s+1 is false the driver will respond to an

+\s-1MTEOM\s+1 request by forward spacing over files.

+.IP "\s-1MT_ST_AUTO_LOCK\s+1 (Default: false)"

+When this option is true, the drive door is locked when the device is

+opened and unlocked when it is closed.

+.IP "\s-1MT_ST_DEF_WRITES\s+1 (Default: false)"

+The tape options (block size, mode, compression, etc.) may change

+when changing from one device linked to a drive to another device

+linked to the same drive depending on how the devices are

+defined. This option defines when the changes are enforced by the

+driver using SCSI-commands and when the drives auto-detection

+capabilities are relied upon. If this option is false, the driver

+sends the SCSI-commands immediately when the device is changed. If the

+option is true, the SCSI-commands are not sent until a write is

+requested. In this case the drive firmware is allowed to detect the

+tape structure when reading and the SCSI-commands are used only to

+make sure that a tape is written according to the correct specification.

+.IP "\s-1MT_ST_CAN_BSR\s+1 (Default: false)"

+When read-ahead is used, the tape must sometimes be spaced backward to the

+correct position when the device is closed and the SCSI command to

+space backwards over records is used for this purpose. Some older

+drives can't process this command reliably and this option can be used

+to instruct the driver not to use the command. The end result is that,

+with read-ahead and fixed block mode, the tape may not be correctly

+positioned within a file when the device is closed.

+.IP "\s-1MT_ST_NO_BLKLIMS\s+1 (Default: false)"

+Some drives don't accept the READ BLOCK LIMITS SCSI command. If

+this is used, the driver does not use the command. The drawback is

+that the driver can't check before sending commands if the selected

+block size is acceptable to the drive.

+.IP "\s-1MT_ST_CAN_PARTITIONS\s+1 (Default: false)"

+This option enables support for several partitions within a

+tape. The option applies to all devices linked to a drive.

+.IP "\s-1MT_ST_SCSI2LOGICAL\s+1 (Default: false)"

+This option instructs the driver to use the logical block addresses

+defined in the SCSI-2 standard when performing the seek and tell

+operations (both with MTSEEK and MTIOCPOS commands and when changing tape

+partition). Otherwise the device-specific addresses are used.

+It is highly advisable to set this option if the drive supports the

+logical addresses because they count also filemarks. There are some

+drives that only support the logical block addresses.

+.IP "\s-1MT_ST_SYSV\s+1 (Default: false)"

+When this option is enabled, the tape devices use the SystemV

+semantics. Otherwise the BSD semantics are used. The most important

+difference between the semantics is what happens when a device used

+for reading is closed: in SYSV semantics the tape is spaced forward

+past the next filemark if this has not happened while using the

+device. In BSD semantics the tape position is not changed.

+.IP \s-1EXAMPLE\s+1

+.nf

+.ta +.4i +.7i +1i

+.BI "struct mtop " mt_cmd ;

+.IB "mt_cmd.mt_op" " = \s-1MTSETDRVBUFFER\s+1;"

+.IB "mt_cmd.mt_count" " = \s-1MT_ST_BOOLEANS\s+1 |"

+.B " \s-1MT_ST_BUFFER_WRITES\s+1 |"

+.B " \s-1MT_ST_ASYNC_WRITES\s+1;"

+.BI "ioctl(" fd ", \s-1MTIOCTOP\s+1, &" mt_cmd ");"

+.fi

+.RE

+.PD

+.IP ""

+The default block size for a device can be set with

+\s-1MT_ST_DEF_BLKSIZE\s+1 and the default density code can be set with

+\s-1MT_ST_DEFDENSITY\s+1. The values for the parameters are ORed

+with the operation code.

+.IP ""

+With kernels 2.1.x and later, the timeout values can be set with the

+subcommand \s-1MT_ST_SET_TIMEOUT\s+1 or'ed with the timeout in seconds.

+The long timeout (used for rewinds and other commands

+that may take a long time) can be set with

+\s-1MT_ST_SET_LONG_TIMEOUT\s+1. The kernel defaults are very long to

+make sure that a successful command is not timed out with any

+drive. Because of this the driver may seem stuck even if it is only

+waiting for the timeout. These commands can be used to set more

+practical values for a specific drive. The timeouts set for one device

+apply for all devices linked to the same drive.

+.SS "\s-1MTIOCGET\s+1 \- Get status"

+.PP

+This request takes an argument of type

+.BR "(struct mtget *)" .

+.PP

+.nf

+/* structure for \s-1MTIOCGET\s+1 - mag tape get status command */

+struct mtget {

+ long mt_type;

+ long mt_resid;

+ /* the following registers are device dependent */

+ long mt_dsreg;

+ long mt_gstat;

+ long mt_erreg;

+ /* The next two fields are not always used */

+ daddr_t mt_fileno;

+ daddr_t mt_blkno;

+};

+.fi

+.IP \fBmt_type\fP 11

+The header file defines many values for

+.BR mt_type ,

+but the current driver reports only the generic types

+\s-1MT_ISSCSI1\s+1 (Generic SCSI-1 tape) and \s-1MT_ISSCSI2\s+1 (Generic SCSI-2 tape).

+.PD 0

+.IP \fBmt_resid\fP

+contains the current tape partition number.

+.IP \fBmt_dsreg\fP

+reports the drive's current settings for block size (in the low 24

+bits) and density (in the high 8 bits).

+These fields are defined by \s-1MT_ST_BLKSIZE_SHIFT\s+1, \s-1MT_ST_BLKSIZE_MASK\s+1,

+\s-1MT_ST_DENSITY_SHIFT\s+1, and \s-1MT_ST_DENSITY_MASK\s+1.

+.IP \fBmt_gstat\fP

+reports generic (device independent) status information.

+The header file defines macros for testing these status bits:

+.RS

+.HP 4

+\s-1GMT_EOF(\s+1\fIx\fP\s-1)\s+1:

+The tape is positioned just after a filemark

+(always false after an \s-1MTSEEK\s+1 operation).

+.HP

+\s-1GMT_BOT(\s+1\fIx\fP\s-1)\s+1:

+The tape is positioned at the beginning of the first file (always false

+after an \s-1MTSEEK\s+1 operation).

+.HP

+\s-1GMT_EOT(\s+1\fIx\fP\s-1)\s+1:

+A tape operation has reached the physical End Of Tape.

+.HP

+\s-1GMT_SM(\s+1\fIx\fP\s-1)\s+1:

+The tape is currently positioned at a setmark

+(always false after an \s-1MTSEEK\s+1 operation).

+.HP

+\s-1GMT_EOD(\s+1\fIx\fP\s-1)\s+1:

+The tape is positioned at the end of recorded data.

+.HP

+\s-1GMT_WR_PROT(\s+1\fIx\fP\s-1)\s+1:

+The drive is write-protected.

+For some drives this can also mean that the drive does not support

+writing on the current medium type.

+.HP

+\s-1GMT_ONLINE(\s+1\fIx\fP\s-1)\s+1:

+The last

+.B open()

+found the drive with a tape in place and ready for operation.

+.HP

+\s-1GMT_D_6250(\s+1\fIx\fP\s-1)\s+1, \s-1GMT_D_1600(\s+1\fIx\fP\s-1)\s+1, \s-1GMT_D_800(\s+1\fIx\fP\s-1)\s+1:

+This \(lqgeneric\(rq status information reports the current

+density setting for 9-track \(12" tape drives only.

+.HP

+\s-1GMT_DR_OPEN(\s+1\fIx\fP\s-1)\s+1:

+The drive does not have a tape in place.

+.HP

+\s-1GMT_IM_REP_EN(\s+1\fIx\fP\s-1)\s+1:

+Immediate report mode. This bit is set if there are no guarantees that

+the data has been physically written to the tape when the write call

+returns. It is set zero only when the driver does not buffer data and

+the drive is set not to buffer data.

+.RE

+.IP \fBmt_erreg\fP

+The only field defined in

+.B mt_erreg

+is the recovered error count in the low 16 bits (as defined by

+\s-1MT_ST_SOFTERR_SHIFT\s+1 and \s-1MT_ST_SOFTERR_MASK\s+1).

+Due to inconsistencies in the way drives report recovered errors, this

+count is often not maintained (most drives do not by default report

+soft errors but this can be changed with a SCSI MODE SELECT command).

+.IP \fBmt_fileno\fP

+reports the current file number (zero-based).

+This value is set to \-1 when the file number is unknown (e.g., after

+\s-1MTBSS\s+1

+or \s-1MTSEEK\s+1).

+.IP \fBmt_blkno\fP

+reports the block number (zero-based) within the current file.

+This value is set to \-1 when the block number is unknown (e.g., after

+\s-1MTBSF\s+1,

+\s-1MTBSS\s+1, or \s-1MTSEEK\s+1).

+.PD

+.SS "\s-1MTIOCPOS\s+1 \- Get tape position"

+.PP

+This request takes an argument of type

+.B "(struct mtpos *)"

+and reports the drive's notion of the current tape block number,

+which is not the same as

+.B mt_blkno

+returned by \s-1MTIOCGET\s+1.

+This drive must be a SCSI-2 drive that supports the \s-1READ POSITION\s+1

+command (device-specific address)

+or a Tandberg-compatible SCSI-1 drive (Tandberg, Archive

+Viper, Wangtek, ... ).

+.PP

+.nf

+/* structure for \s-1MTIOCPOS\s+1 - mag tape get position command */

+struct mtpos {

+ long mt_blkno; /* current block number */

+};

+

+.fi

+.SH "RETURN VALUE"

+.IP EIO 14

+The requested operation could not be completed.

+.IP ENOSPC

+A write operation could not be completed because the tape reached

+end-of-medium.

+.IP EACCES

+An attempt was made to write or erase a write-protected tape.

+(This error is not detected during

+.BR open() .)

+.IP EFAULT

+The command parameters point to memory not belonging to the calling

+process.

+.IP ENXIO

+During opening, the tape device does not exist.

+.IP EBUSY

+The device is already in use or the driver was unable to allocate a

+buffer.

+.IP EOVERFLOW

+An attempt was made to read or write a variable-length block that is

+larger than the driver's internal buffer.

+.IP EINVAL

+An

+.B ioctl()

+had an illegal argument, or a requested block size was illegal.

+.IP ENOSYS

+Unknown

+.BR ioctl() .

+.IP EROFS

+Open is attempted with O_WRONLY or O_RDWR when the tape in the drive is

+write-protected.

+.SH FILES

+/dev/st* : the auto-rewind SCSI tape devices

+.br

+/dev/nst* : the non-rewind SCSI tape devices

+.SH AUTHOR

+The driver has been written by Kai M\(:akisara (Kai.Makisara@metla.fi)

+starting from a driver written by Dwayne Forsyth. Several other

+people have also contributed to the driver.

+.SH "SEE ALSO"

+.BR mt (1)

+.PP

+The file README.st in the kernel sources contains the most recent

+information about the driver and its configuration

+possibilities.

+.SH NOTES

+1. When exchanging data between systems, both systems have to agree on

+the physical tape block size. The parameters of a drive after startup

+are often not the ones most operating systems use with these

+devices. Most systems use drives in variable block mode if the drive

+supports that mode. This applies to most modern drives, including

+DATs, 8mm helical scan drives, DLTs, etc. It may be advisable use

+these drives in variable block mode also in Linux (i.e., use MTSETBLK

+or MTSETDEFBLK at system startup to set the mode), at least when

+exchanging data with foreign system. The drawback of

+this is that a fairly large tape block size has to be used to get

+acceptable data transfer rates on the SCSI bus.

+.PP

+2. Many programs (e.g., tar) allow the user to specify the blocking

+factor on command line. Note that this determines the physical block

+size on tape only in variable block mode.

+.PP

+3. In order to use SCSI tape drives, the basic SCSI driver,

+a SCSI-adapter driver and the SCSI tape driver must be either

+configured into the kernel or loaded as modules. If the SCSI-tape

+driver is not present, the drive is recognized but the tape support

+described in this page is not available.

+.PP

+4. The driver writes error messages to the console/log. The SENSE

+codes written into some messages are automatically translated to text

+if verbose SCSI messages are enabled in kernel configuration.

+.SH COPYRIGHT

+Copyright \(co 1995 Robert K. Nichols.

+.br

+Copyright \(co 1999 Kai M\(:akisara.

+.PP

+Permission is granted to make and distribute verbatim copies of this

+manual provided the copyright notice and this permission notice are

+preserved on all copies.

+Additional permissions are contained in the header of the source file.

+.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993

+.\"

+.\" This is free documentation; you can redistribute it and/or

+.\" modify it under the terms of the GNU General Public License as

+.\" published by the Free Software Foundation; either version 2 of

+.\" the License, or (at your option) any later version.

+.\"

+.\" The GNU General Public License's references to "object code"

+.\" and "executables" are to be interpreted as the output of any

+.\" document formatting or typesetting system, including

+.\" intermediate and printed output.

+.\"

+.\" This manual is distributed in the hope that it will be useful,

+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of

+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

+.\" GNU General Public License for more details.

+.\"

+.\" You should have received a copy of the GNU General Public

+.\" License along with this manual; if not, write to the Free

+.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,

+.\" USA.

+.\"

+.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu)

+.\" Modified 2003-04-07 by Michael Kerrisk

+.\"

+.TH TTY 4 2003-04-07 "Linux" "Linux Programmer's Manual"

+.SH NAME

+tty \- controlling terminal

+.SH DESCRIPTION

+The file \fB/dev/tty\fP is a character file with major number 5 and

+minor number 0, usually of mode 0666 and owner.group root.tty. It is a

+synonym for the controlling terminal of a process, if any.

+.LP

+In addition to the \fBioctl()\fP requests supported by the device that

+\fBtty\fP refers to, the \fBioctl()\fP request \fBTIOCNOTTY\fP is supported.

+.SS TIOCNOTTY

+Detach the current process from its controlling terminal.

+.sp

+If the process is the session leader,

+then SIGHUP and SIGCONT signals are sent to the foreground process group

+and all processes in the current session lose their controlling tty.

+.sp

+This \fBioctl()\fP call only works on file descriptors connected

+to \fB/dev/tty\fP. It is used by daemon processes when they are invoked

+by a user at a terminal.

+The process attempts to open \fB/dev/tty\fP. If the open succeeds, it

+detaches itself from the terminal by using \fBTIOCNOTTY\fP, while if the

+open fails, it is obviously not attached to a terminal and does not need

+to detach itself.

+.SH FILES

+/dev/tty

+.SH "SEE ALSO"

+.BR chown (1),

+.BR getty (1),

+.BR mknod (1),

+.BR ioctl (2),

+.BR termios (3),

+.BR console (4),

+.BR ttys (4)

+.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), Fri Apr 2 11:32:09 MET DST 1993

+.\"

+.\" This is free documentation; you can redistribute it and/or

+.\" modify it under the terms of the GNU General Public License as

+.\" published by the Free Software Foundation; either version 2 of

+.\" the License, or (at your option) any later version.

+.\"

+.\" The GNU General Public License's references to "object code"

+.\" and "executables" are to be interpreted as the output of any

+.\" document formatting or typesetting system, including

+.\" intermediate and printed output.

+.\"

+.\" This manual is distributed in the hope that it will be useful,

+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of

+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

+.\" GNU General Public License for more details.

+.\"

+.\" You should have received a copy of the GNU General Public

+.\" License along with this manual; if not, write to the Free

+.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,

+.\" USA.

+.\"

+.\" Modified Sat Jul 24 17:03:24 1993 by Rik Faith (faith@cs.unc.edu)

+.TH TTYS 4 1992-12-19 "Linux" "Linux Programmer's Manual"

+.SH NAME

+ttyS \- serial terminal lines

+.SH DESCRIPTION

+\fBttyS[0-3]\fP are character devices for the serial terminal lines.

+.LP

+They are typically created by:

+.RS

+.sp

+mknod -m 660 /dev/ttyS0 c 4 64 # base address 0x3f8

+.br

+mknod -m 660 /dev/ttyS1 c 4 65 # base address 0x2f8

+.br

+mknod -m 660 /dev/ttyS2 c 4 66 # base address 0x3e8

+.br

+mknod -m 660 /dev/ttyS3 c 4 67 # base address 0x2e8

+.br

+chown root:tty /dev/ttyS[0-3]

+.sp

+.RE

+.SH FILES

+/dev/ttyS[0-3]

+.SH "SEE ALSO"

+.BR chown (1),

+.BR getty (1),

+.BR mknod (1),

+.BR tty (4),

+.BR setserial (8)

+.\" Copyright 2002 Walter Harms <walter.harms@informatik.uni-oldenburg.de>

+.\" and Andries Brouwer <aeb@cwi.nl>.

+.\" Distributed under GPL.

+.\"

+.TH TTY_IOCTL 4 2002-12-29 "Linux" "Linux Programmer's Manual"

+.SH NAME

+tty ioctl \- ioctls for terminals and serial lines

+.SH SYNOPSIS

+.sp

+.BR "#include <termios.h>"

+.sp

+.BI "int ioctl(int " fd ", int " cmd ", ...);"

+.sp

+.SH DESCRIPTION

+The

+.I ioctl()

+call for terminals and serial ports accepts many possible command arguments.

+Most require a third argument, of varying type, here called \fIargp\fP

+or \fIarg\fP.

+.LP

+Use of

+.I ioctl

+makes for non-portable programs. Use the POSIX interface described in

+.BR termios (3)

+whenever possible.

+

+.SS "Get and Set Terminal Attributes"

+.TP

+.BI "TCGETS struct termios *" argp

+Equivalent to

+.IR "tcgetattr(fd, argp)" .

+.br

+Get the current serial port settings.

+.TP

+.BI "TCSETS const struct termios *" argp

+Equivalent to

+.IR "tcsetattr(fd, TCSANOW, argp)" .

+.br

+Set the current serial port settings.

+.TP

+.BI "TCSETSW const struct termios *" argp

+Equivalent to

+.IR "tcsetattr(fd, TCSADRAIN, argp)" .

+.br

+Allow the output buffer to drain, and

+set the current serial port settings.

+.TP

+.BI "TCSETSF const struct termios *" argp

+Equivalent to

+.IR "tcsetattr(fd, TCSAFLUSH, argp)" .

+.br

+Allow the output buffer to drain, discard pending input, and

+set the current serial port settings.

+.LP

+The following four ioctls are just like TCGETS, TCSETS, TCSETSW, TCSETSF,

+except that they take a

+.B "struct termio *"

+instead of a

+.BR "struct termios *" .

+.TP

+.BI "TCGETA struct termio *" argp

+.TP

+.BI "TCSETA const struct termio *" argp

+.TP

+.BI "TCSETAW const struct termio *" argp

+.TP

+.BI "TCSETAF const struct termio *" argp

+

+.SS "Locking the termios structure"

+The termios structure of a tty can be locked. The lock is itself

+a termios structure, with nonzero bits or fields indicating a

+locked value.

+.TP

+.BI "TIOCGLCKTRMIOS struct termios *" argp

+Gets the locking status of the termios structure of

+the terminal.

+.TP

+.BI "TIOCSLCKTRMIOS const struct termios *" argp

+Sets the locking status of the termios structure of

+the terminal. Only root can do this.

+

+.SS "Get and Set Window Size"

+Window sizes are kept in the kernel, but not used by the kernel

+(except in the case of virtual consoles, where the kernel will

+update the window size when the size of the virtual console changes,

+e.g. by loading a new font).

+.TP

+.BI "TIOCGWINSZ struct winsize *" argp

+Get window size.

+.TP

+.BI "TIOCSWINSZ const struct winsize *" argp

+Set window size.

+.LP

+The struct used by these ioctls is defined as

+

+.nf

+struct winsize {

+ unsigned short ws_row;

+ unsigned short ws_col;

+ unsigned short ws_xpixel; /* unused */

+ unsigned short ws_ypixel; /* unused */

+};

+.fi

+

+When the window size changes, a SIGWINCH signal is sent to the

+foreground process group.

+

+.SS "Sending a Break"

+.TP

+.BI "TCSBRK int " arg

+Equivalent to

+.IR "tcsendbreak(fd, arg)" .

+.br

+If the terminal is using asynchronous serial data transmission, and

+.I arg

+is zero, then send a break (a stream of zero bits) for between

+0.25 and 0.5 seconds. If the terminal is not using asynchronous

+serial data transmission, then either a break is sent, or the function

+returns without doing anything.

+When

+.I arg

+is nonzero, nobody knows what will happen.

+

+(SVR4, UnixWare, Solaris, Linux treat

+.I "tcsendbreak(fd,arg)"

+with nonzero

+.I arg

+like

+.IR "tcdrain(fd)" .

+SunOS treats

+.I arg

+as a multiplier, and sends a stream of bits

+.I arg

+times as long as done for zero

+.IR arg .

+DG-UX and AIX treat

+.I arg

+(when nonzero) as a timeinterval measured in milliseconds.

+HP-UX ignores

+.IR arg .)

+.TP

+.BI "TCSBRKP int " arg

+So-called "POSIX version" of TCSBRK. It treats nonzero

+.I arg

+as a timeinterval measured in deciseconds, and does nothing

+when the driver does not support breaks.

+.TP

+.BI "TIOCSBRK void"

+Turn break on, that is, start sending zero bits.

+.TP

+.BI "TIOCCBRK void"

+Turn break off, that is, stop sending zero bits.

+

+.SS "Software flow control"

+.TP

+.BI "TCXONC int " arg

+Equivalent to

+.IR "tcflow(fd, arg)" .

+.br

+See

+.BR tcflow (3)

+for the argument values TCOOFF, TCOON, TCIOFF, TCION.

+

+.SS "Buffer count and flushing"

+.TP

+.BI "FIONREAD int *" argp

+Get the number of bytes in the input buffer.

+.TP

+.BI "TIOCINQ int *" argp

+Same as FIONREAD.

+.TP

+.BI "TIOCOUTQ int *" argp

+Get the number of bytes in the output buffer.

+.TP

+.BI "TCFLSH int " arg

+Equivalent to

+.IR "tcflush(fd, arg)" .

+.br

+See

+.BR tcflush (3)

+for the argument values TCIFLUSH, TCOFLUSH, TCIOFLUSH.

+

+.SS "Faking input"

+.TP

+.BI "TIOCSTI const char *" argp

+Insert the given byte in the input queue.

+

+.SS "Redirecting console output"

+.TP

+.BI "TIOCCONS void"

+Redirect output that would have gone to

+.I /dev/console

+or

+.I /dev/tty0

+to the given tty. If that was a pty master, send it to the slave.

+Anybody can do this as long as the output was not redirected yet.

+If it was redirected already EBUSY is returned,

+but root may stop redirection by using this ioctl with

+.I fd

+pointing at

+.I /dev/console

+or

+.IR /dev/tty0 .

+

+.SS "Controlling tty"

+.TP

+.BI "TIOCSCTTY int " arg

+Make the given tty the controlling tty of the current process.

+The current process must be a session leader and not have a

+controlling tty already. If this tty is already the controlling tty

+of a different session group then the ioctl fails with EPERM,

+unless the caller is root and

+.I arg

+equals 1, in which case the tty is stolen, and all processes that had

+it as controlling tty lose it.

+.TP

+.BI TIOCNOTTY void

+If the given tty was the controlling tty of the current process,

+give up this controlling tty. If the process was session leader,

+then send SIGHUP and SIGCONT to the foreground process group

+and all processes in the current session lose their controlling tty.

+

+.SS "Process group and session ID"

+.TP

+.BI "TIOCGPGRP pid_t *" argp

+When successful, equivalent to

+.IR "*argp = tcgetpgrp(fd)" .

+.br

+Get the process group ID of the foreground proces group on this tty.

+.TP

+.BI "TIOCSPGRP const pid_t *" argp

+Equivalent to

+.IR "tcsetpgrp(fd, *argp)" .

+.br

+Set the foreground process group id of this tty.

+.TP

+.BI "TIOCGSID pid_t *" argp

+Get the session ID of the given tty. This will fail with ENOTTY

+in case the tty is not a master pty and not our controlling tty. Strange.

+

+.SS "Exclusive mode"

+.TP

+.BI "TIOCEXCL void"

+Put the tty into exclusive mode.

+No further

+.BR open (2)

+operations on the terminal are permitted.

+(They will fail with EBUSY, except for root.)

+.TP

+.BI "TIOCNXCL void"

+Disable exclusive mode.

+

+.SS "Line discipline"

+.TP

+.BI "TIOCGETD int *" argp

+Get the line discipline of the tty.

+.TP

+.BI "TIOCSETD const int *" argp

+Set the line discipline of the tty.

+

+.SS "Pseudo-tty ioctls"

+.TP

+.BI "TIOCPKT const int *" argp

+Enable (when

+.RI * argp

+is nonzero) or disable packet mode.

+Can be applied to the master side of a pseudotty only (and will return

+ENOTTY otherwise). In packet mode, each subsequent

+.BR read (2)

+will return a packet that either contains a single nonzero control byte,

+or has a single zero byte followed by data written on the slave side of

+the pty. If the first byte is not TIOCPKT_DATA (0), it is an OR of one

+or more of the following bits:

+

+.nf

+TIOCPKT_FLUSHREAD The read queue for the terminal is flushed.

+TIOCPKT_FLUSHWRITE The write queue for the terminal is flushed.

+TIOCPKT_STOP Output to the terminal is stopped.

+TIOCPKT_START Output to the terminal is restarted.

+TIOCPKT_DOSTOP t_stopc is `^S' and t_startc is `^Q'.

+TIOCPKT_NOSTOP the start and stop characters are not `^S/^Q'.

+.fi

+

+While this mode is in use, the presence

+of control status information to be read

+from the master side may be detected by a

+.BR select (2)

+for exceptional conditions.

+

+This mode is used by

+.BR rlogin (1)

+and

+.BR rlogind (8)

+to implement a remote-echoed, locally `^S/^Q' flow-controlled remote login.

+

+The BSD ioctls TIOCSTOP, TIOCSTART, TIOCUCNTL, TIOCREMOTE

+have not been implemented under Linux.

+

+.SS "Modem control"

+.TP

+.BI "TIOCMGET int *" argp

+get the status of modem bits.

+.TP

+.BI "TIOCMSET const int *" argp

+set the status of modem bits.

+.TP

+.BI "TIOCMBIC const int *" argp

+clear the indicated modem bits.

+.TP

+.BI "TIOCMBIS const int *" argp

+set the indicated modem bits.

+.LP

+Bits used by these four ioctls:

+

+.nf

+TIOCM_LE DSR (data set ready/line enable)

+TIOCM_DTR DTR (data terminal ready)

+TIOCM_RTS RTS (request to send)

+TIOCM_ST Secondary TXD (transmit)

+TIOCM_SR Secondary RXD (receive)

+TIOCM_CTS CTS (clear to send)

+TIOCM_CAR DCD (data carrier detect)

+TIOCM_CD see TIOCM_CAR

+TIOCM_RNG RNG (ring)

+TIOCM_RI see TIOCM_RNG

+TIOCM_DSR DSR (data set ready)

+.fi

+

+.SS "Marking a line as local"

+.TP

+.BI "TIOCGSOFTCAR int *" argp

+("Get software carrier flag")

+Get the status of the CLOCAL flag in the c_cflag field of the

+termios structure.

+.TP

+.BI "TIOCSSOFTCAR const int *" argp

+("Set software carrier flag")

+Set the CLOCAL flag in the termios structure when

+.RI * argp

+is nonzero, and clear it otherwise.

+.LP

+If the CLOCAL flag for a line is off, the hardware carrier detect (DCD)

+signal is significant, and an

+.BR open (2)

+of the corresponding tty will block until DCD is asserted,

+unless the O_NONBLOCK flag is given.

+If CLOCAL is set, the line behaves as if DCD is always asserted.

+The software carrier flag is usually turned on for local devices,

+and is off for lines with modems.

+

+.SS "Linux specific"

+For the TIOCLINUX ioctl, see

+.BR console_ioctl (4).

+

+.SS "Kernel debugging"

+.sp

+.BR "#include <linux/tty.h>"

+.sp

+.TP

+.BI "TIOCTTYGSTRUCT struct tty_struct *" argp

+Get the tty_struct corresponding to

+.IR fd .

+.\"

+.\" .SS "Serial info"

+.\" .sp

+.\" .BR "#include <linux/serial.h>"

+.\" .sp

+.\" .TP

+.\" .BI "TIOCGSERIAL struct serial_struct *" argp

+.\" Get serial info.

+.\" .TP

+.\" .BI "TIOCSSERIAL const struct serial_struct *" argp

+.\" Set serial info.

+

+.SH "RETURN VALUE"

+The

+.I ioctl()

+system call returns 0 on success. On error it returns \-1 and sets

+.I errno

+appropriately.

+

+.SH ERRORS

+.TP

+.B ENOIOCTLCMD

+Unknown command.

+.TP

+.B EINVAL

+Invalid command parameter.

+.TP

+.B EPERM

+Insufficient permission.

+.TP

+.B ENOTTY

+Inappropriate

+.IR fd .

+.SH EXAMPLE

+Check the condition of DTR on the serial port.

+

+.nf

+#include <termios.h>

+#include <fcntl.h>

+#include <sys/ioctl.h>

+

+main() {

+ int fd, serial;

+

+ fd = open("/dev/ttyS0", O_RDONLY);

+ ioctl(fd, TIOCMGET, &serial);

+ if (serial & TIOCM_DTR)

+ puts("TIOCM_DTR is not set");

+ else

+ puts("TIOCM_DTR is set");

+ close(fd);

+}

+.fi

+

+.SH "SEE ALSO"

+.BR ioctl (2),

+.BR termios (3),

+.BR console_ioctl (4)

+

+.\" FIONBIO const int *

+.\" FIONCLEX void

+.\" FIOCLEX void

+.\" FIOASYNC const int *

+.\" from serial.c:

+.\" TIOCSERCONFIG void

+.\" TIOCSERGWILD int *

+.\" TIOCSERSWILD const int *

+.\" TIOCSERGSTRUCT struct async_struct *

+.\" TIOCSERGETLSR int *

+.\" TIOCSERGETMULTI struct serial_multiport_struct *

+.\" TIOCSERSETMULTI const struct serial_multiport_struct *

+.\" TIOCGSERIAL, TIOCSSERIAL (see above)

+.so man4/random.4

+.\" Copyright (c) 1995 James R. Van Zandt <jrv@vanzandt.mv.com>

+.\" Sat Feb 18 09:11:07 EST 1995

+.\"

+.\" This is free documentation; you can redistribute it and/or

+.\" modify it under the terms of the GNU General Public License as

+.\" published by the Free Software Foundation; either version 2 of

+.\" the License, or (at your option) any later version.

+.\"

+.\" The GNU General Public License's references to "object code"

+.\" and "executables" are to be interpreted as the output of any

+.\" document formatting or typesetting system, including

+.\" intermediate and printed output.

+.\"

+.\" This manual is distributed in the hope that it will be useful,

+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of

+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

+.\" GNU General Public License for more details.

+.\"

+.\" You should have received a copy of the GNU General Public

+.\" License along with this manual; if not, write to the Free

+.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,

+.\" USA.

+.\"

+.\" Modified, Sun Feb 26 15:08:05 1995, faith@cs.unc.edu

+.\" "

+.TH VCS 4 1995-02-19 "Linux" "Linux Programmer's Manual"

+.SH NAME

+vcs, vcsa \- virtual console memory

+.SH DESCRIPTION

+\fB/dev/vcs0\fP is a character device with major number 7 and minor number

+0, usually of mode 0644 and owner root.tty. It refers to the memory

+of the currently

+displayed virtual console terminal.

+.LP

+\fB/dev/vcs[1-63]\fP are character devices for virtual console

+terminals, they have major number 7 and minor number 1 to 63, usually

+mode 0644 and owner root.tty. \fB/dev/vcsa[0-63]\fP are the same, but

+including attributes, and prefixed with four bytes giving the screen

+dimensions and cursor position: \fIlines\fP, \fIcolumns\fP, \fIx\fP, \fIy\fP.

+(\fIx\fP = \fIy\fP = 0 at the top left corner of the screen.)

+.PP

+These replace the screendump

+.IR ioctl s

+of \fBconsole\fP(4), so the system

+administrator can control access using file system permissions.

+.PP

+The devices for the first eight virtual consoles may be created by:

+

+.nf

+ for x in 0 1 2 3 4 5 6 7 8; do

+ mknod -m 644 /dev/vcs$x c 7 $x;

+ mknod -m 644 /dev/vcsa$x c 7 $[$x+128];

+ done

+ chown root:tty /dev/vcs*

+.fi

+

+No

+.IR ioctl ()

+requests are supported.

+.SH EXAMPLES

+You may do a screendump on vt3 by switching to vt1 and typing

+\fIcat /dev/vcs3 >foo\fP. Note that the output does not contain

+newline characters, so some processing may be required, like

+in \fIfold -w 81 /dev/vcs3 | lpr\fP or (horrors)

+\fIsetterm -dump 3 -file /proc/self/fd/1\fP.

+.LP

+The \fI/dev/vcsa0\fP device is used for Braille support.

+

+This program displays the character and screen attributes under the

+cursor of the second virtual console, then changes the background color

+there:

+

+.nf

+ #include <unistd.h>

+ #include <stdlib.h>

+ #include <stdio.h>

+ #include <fcntl.h>

+

+ int main() {

+ int fd;

+ char *device = "/dev/vcsa2";

+ struct {unsigned char lines, cols, x, y;} scrn;

+ char ch, attrib;

+

+ fd = open(device, O_RDWR);

+ if (fd < 0) {

+ perror(device);

+ exit(1);

+ }

+ (void)read(fd, &scrn, 4);

+ (void)lseek(fd, 4 + 2*(scrn.y*scrn.cols + scrn.x), 0);

+ (void)read(fd, &ch, 1);

+ (void)read(fd, &attrib, 1);

+ printf("ch='%c' attrib=0x%02x\\n", ch, attrib);

+ attrib ^= 0x10;

+ (void)lseek(fd, -1, 1);

+ (void)write(fd, &attrib, 1);

+ return 0;

+ }

+.fi

+

+.SH FILES

+/dev/vcs[0-63]

+.br

+/dev/vcsa[0-63]

+.SH AUTHOR

+Andries Brouwer <aeb@cwi.nl>

+.SH HISTORY

+Introduced with version 1.1.92 of the Linux kernel.

+.SH "SEE ALSO"

+.BR selection (1),

+.BR console (4),

+.BR tty (4),

+.BR ttys (4)

+.so man4/vcs.4

+.\" From jt@hplb.hpl.hp.com Thu Dec 19 18:31:49 1996

+.\" From: Jean Tourrilhes <jt@hplb.hpl.hp.com>

+.\" Address: HP Labs, Filton Road, Stoke Gifford, Bristol BS12 6QZ, U.K.

+.\" Jean II - HPLB - '96

+.\" wavelan.c.4

+.\"

+.TH WAVELAN 4 1996-10-22 "Univ. of Sydney (Basser Dep. of Comp. Sci.)"

+.\"

+.\" NAME part

+.\"

+.SH NAME

+wavelan \- AT&T GIS WaveLAN ISA device driver

+.\"

+.\" SYNOPSIS part

+.\"

+.SH SYNOPSIS

+.BI "insmod wavelan_cs.o [io=" B,B.. "] [ irq=" I,I.. "] [name=" N,N.. ]

+.\"

+.\" DESCRIPTION part

+.\"

+.SH DESCRIPTION

+.I wavelan

+is the low-level device driver for the NCR / AT&T / Lucent

+.B WaveLAN ISA

+and Digital (DEC)

+.B RoamAbout DS

+wireless ethernet adapter. This driver is available as a module or

+might be compiled in the kernel. This driver supports multiple cards

+in both forms (up to 4) and allocates the next available ethernet

+device (eth0..eth#) for each card found, unless a device name is

+explicitly specified (see below). This device name will be reported

+in the kernel log file with the MAC address, NWID and frequency used

+by the card.

+.\"

+.\" PARAMETER part

+.\"

+.SH PARAMETERS

+This section apply to the module form (parameters passed on the

+.BR insmod (8)

+command line). If the driver is included in the kernel, use the

+.I ether=IRQ,IO,NAME

+syntax on the kernel command line.

+.TP

+.B io

+Specify the list of base address where to search for wavelan cards

+(setting by dip switch on the card). If you don't specify any io

+address, the driver will scan 0x390 and 0x3E0 addresses, which might

+conflict with other hardware...

+.TP

+.B irq

+Set the list of irq that each wavelan card should use (the value is

+saved in permanent storage for future use).

+.TP

+.B name

+Set the list of name to be used for each wavelan cards device (name

+used by

+.BR ifconfig (8)).

+.\"

+.\" WIRELESS part

+.\"

+.SH "WIRELESS EXTENSIONS"

+Use

+.BR iwconfig (8)

+to manipulate wireless extensions.

+.\" NWID sub part

+.SS NWID (or domain)

+Set the network ID

+.RI [ 0

+to

+.IR FFFF ]

+or disable it

+.RI [ off ].

+As the NWID is stored in the card Permanent Storage Area, it will be

+reuse at any further invocation of the driver.

+.\" Frequency sub part

+.SS Frequency & channels

+For the 2.4GHz 2.00 Hardware, you are able to set the frequency by

+specifying one of the 10 defined channels

+.RI ( 2.412,

+.I 2.422, 2.425, 2.4305, 2.432, 2.442, 2.452, 2.460, 2.462

+or

+.IR 2.484 )

+or directly by its value. The frequency is changed immediately and

+permanentely. Frequency availability depend on the regulations...

+.\" Spy sub part

+.SS Statistics spy

+Set a list of MAC addresses in the driver (up to 8) and get the last

+quality of link for each of those (see

+.BR iwspy (8)).

+.\" /proc/net/wireless part

+.SS /proc/net/wireless

+.I status

+is the status reported by the modem.

+.I Link quality

+reports the quality of the modulation on the air (direct sequence

+spread spectrum) [max = 16].

+.I Level

+and

+.I Noise

+refer to the signal level and noise level [max = 64].

+The

+.I crypt discarded packet

+and

+.I misc discarded packet

+counters are not implemented.

+.\"

+.\" IOCTL part

+.\"

+.SH "PRIVATE IOCTL"

+You may use

+.BR iwpriv (8)

+to manipulate private ioctls.

+.\" threshold part

+.SS Quality and Level threshold

+Enable you the define the quality and level threshold used by the

+modem (packet below that level are discarded).

+.\" Histogram part

+.SS Histogram

+This functionality allow to set a number of signal level intervals and

+to count the number of packets received in each of those defined

+intervals. This distribution might be used to calculate the mean value

+and standard deviation of the signal level.

+.\"

+.\" SPECIFIC part

+.\"

+.SH "SPECIFIC NOTES"

+This driver will fail to detect some

+.B non NCR/ATT&T/Lucent

+Wavelan cards. If it's your case, you must look in the source code on

+how to add your card to the detection routine.

+.PP

+Some of the mentioned features are optional. You may enable to disable

+them by changing flags in the driver header and recompile.

+.\"

+.\" AUTHOR part

+.\"

+.SH AUTHOR

+Bruce Janson \- bruce@cs.usyd.edu.au

+.br

+Jean Tourrilhes \- jt@hplb.hpl.hp.com

+.br

+(+ others - see source code for details)

+.\"

+.\" SEE ALSO part

+.\"

+.SH "SEE ALSO"

+.BR wavelan_cs (4),

+.BR ifconfig (8),

+.BR insmod (8),

+.BR iwconfig (8),

+.BR iwspy (8),

+.BR iwpriv (8)

+.so man4/null.4