diff options
| author | Alejandro Colomar <alx.manpages@gmail.com> | 2022-09-09 14:15:08 +0200 |
|---|---|---|
| committer | Alejandro Colomar <alx.manpages@gmail.com> | 2022-09-09 14:15:08 +0200 |
| commit | 96e72ec1fbadd13cbcbc2b263540e4f5e9e09d7c (patch) | |
| tree | 70686b943e33a6e939ad265acb7ddfef70b91f32 /man4 | |
| parent | 8f4ed6463206e8ede815c72085c7305dafc2e4fc (diff) | |
Revert "src.mk, All pages: Move man* to man/"
This reverts commit 70ac1c4785fc1e158ab2349a962dba2526bf4fbc.
Link: <https://lore.kernel.org/linux-man/YxcV4h+Xn7cd6+q2@pevik/T/>
Reported-by: Petr Vorel <pvorel@suse.cz>
Reported-by: Jakub Wilk <jwilk@jwilk.net>
Cc: Stefan Puiu <stefan.puiu@gmail.com>
Signed-off-by: Alex Colomar <alx.manpages@gmail.com>
Diffstat (limited to 'man4')
| -rw-r--r-- | man4/cciss.4 | 384 | ||||
| -rw-r--r-- | man4/console_codes.4 | 809 | ||||
| -rw-r--r-- | man4/console_ioctl.4 | 2 | ||||
| -rw-r--r-- | man4/cpuid.4 | 81 | ||||
| -rw-r--r-- | man4/dsp56k.4 | 102 | ||||
| -rw-r--r-- | man4/fd.4 | 213 | ||||
| -rw-r--r-- | man4/full.4 | 46 | ||||
| -rw-r--r-- | man4/fuse.4 | 535 | ||||
| -rw-r--r-- | man4/hd.4 | 82 | ||||
| -rw-r--r-- | man4/hpsa.4 | 234 | ||||
| -rw-r--r-- | man4/initrd.4 | 479 | ||||
| -rw-r--r-- | man4/intro.4 | 22 | ||||
| -rw-r--r-- | man4/kmem.4 | 1 | ||||
| -rw-r--r-- | man4/lirc.4 | 422 | ||||
| -rw-r--r-- | man4/loop-control.4 | 1 | ||||
| -rw-r--r-- | man4/loop.4 | 359 | ||||
| -rw-r--r-- | man4/lp.4 | 126 | ||||
| -rw-r--r-- | man4/mem.4 | 81 | ||||
| -rw-r--r-- | man4/mouse.4 | 170 | ||||
| -rw-r--r-- | man4/msr.4 | 42 | ||||
| -rw-r--r-- | man4/null.4 | 52 | ||||
| -rw-r--r-- | man4/port.4 | 1 | ||||
| -rw-r--r-- | man4/ptmx.4 | 1 | ||||
| -rw-r--r-- | man4/pts.4 | 75 | ||||
| -rw-r--r-- | man4/ram.4 | 28 | ||||
| -rw-r--r-- | man4/random.4 | 347 | ||||
| -rw-r--r-- | man4/rtc.4 | 327 | ||||
| -rw-r--r-- | man4/sd.4 | 117 | ||||
| -rw-r--r-- | man4/sk98lin.4 | 581 | ||||
| -rw-r--r-- | man4/smartpqi.4 | 325 | ||||
| -rw-r--r-- | man4/st.4 | 947 | ||||
| -rw-r--r-- | man4/tty.4 | 67 | ||||
| -rw-r--r-- | man4/ttyS.4 | 33 | ||||
| -rw-r--r-- | man4/tty_ioctl.4 | 2 | ||||
| -rw-r--r-- | man4/urandom.4 | 1 | ||||
| -rw-r--r-- | man4/vcs.4 | 172 | ||||
| -rw-r--r-- | man4/vcsa.4 | 1 | ||||
| -rw-r--r-- | man4/veth.4 | 86 | ||||
| -rw-r--r-- | man4/wavelan.4 | 142 | ||||
| -rw-r--r-- | man4/zero.4 | 1 |
40 files changed, 7497 insertions, 0 deletions
diff --git a/man4/cciss.4 b/man4/cciss.4 new file mode 100644 index 000000000..dffc00d25 --- /dev/null +++ b/man4/cciss.4 @@ -0,0 +1,384 @@ +.\" Copyright (C) 2011, Hewlett-Packard Development Company, L.P. +.\" Written by Stephen M. Cameron <scameron@beardog.cce.hp.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-only +.\" +.\" shorthand for double quote that works everywhere. +.ds q \N'34' +.TH CCISS 4 2021-03-22 "Linux man-pages (unreleased)" +.SH NAME +cciss \- HP Smart Array block driver +.SH SYNOPSIS +.nf +modprobe cciss [ cciss_allow_hpsa=1 ] +.fi +.SH DESCRIPTION +.\" commit 253d2464df446456c0bba5ed4137a7be0b278aa8 +.BR Note : +This obsolete driver was removed from the kernel in version 4.14, +as it is superseded by the +.BR hpsa (4) +driver in newer kernels. +.PP +.B cciss +is a block driver for older HP Smart Array RAID controllers. +.SS Options +.IR "cciss_allow_hpsa=1" : +This option prevents the +.B cciss +driver from attempting to drive any controllers that the +.BR hpsa (4) +driver is capable of controlling, which is to say, the +.B cciss +driver is restricted by this option to the following controllers: +.PP +.nf + Smart Array 5300 + Smart Array 5i + Smart Array 532 + Smart Array 5312 + Smart Array 641 + Smart Array 642 + Smart Array 6400 + Smart Array 6400 EM + Smart Array 6i + Smart Array P600 + Smart Array P400i + Smart Array E200i + Smart Array E200 + Smart Array E200i + Smart Array E200i + Smart Array E200i + Smart Array E500 +.fi +.SS Supported hardware +The +.B cciss +driver supports the following Smart Array boards: +.PP +.nf + Smart Array 5300 + Smart Array 5i + Smart Array 532 + Smart Array 5312 + Smart Array 641 + Smart Array 642 + Smart Array 6400 + Smart Array 6400 U320 Expansion Module + Smart Array 6i + Smart Array P600 + Smart Array P800 + Smart Array E400 + Smart Array P400i + Smart Array E200 + Smart Array E200i + Smart Array E500 + Smart Array P700m + Smart Array P212 + Smart Array P410 + Smart Array P410i + Smart Array P411 + Smart Array P812 + Smart Array P712m + Smart Array P711m +.fi +.SS Configuration details +To configure HP Smart Array controllers, +use the HP Array Configuration Utility +(either +.BR hpacuxe (8) +or +.BR hpacucli (8)) +or the Offline ROM-based Configuration Utility (ORCA) +run from the Smart Array's option ROM at boot time. +.SH FILES +.SS Device nodes +The device naming scheme is as follows: +.PP +Major numbers: +.IP +.TS +r r. +104 cciss0 +105 cciss1 +106 cciss2 +105 cciss3 +108 cciss4 +109 cciss5 +110 cciss6 +111 cciss7 +.TE +.PP +Minor numbers: +.PP +.EX + b7 b6 b5 b4 b3 b2 b1 b0 + |\-\-\-\-+\-\-\-\-| |\-\-\-\-+\-\-\-\-| + | | + | +\-\-\-\-\-\-\-\- Partition ID (0=wholedev, 1\-15 partition) + | + +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- Logical Volume number +.EE +.PP +The device naming scheme is: +.TS +li l. +/dev/cciss/c0d0 Controller 0, disk 0, whole device +/dev/cciss/c0d0p1 Controller 0, disk 0, partition 1 +/dev/cciss/c0d0p2 Controller 0, disk 0, partition 2 +/dev/cciss/c0d0p3 Controller 0, disk 0, partition 3 + +/dev/cciss/c1d1 Controller 1, disk 1, whole device +/dev/cciss/c1d1p1 Controller 1, disk 1, partition 1 +/dev/cciss/c1d1p2 Controller 1, disk 1, partition 2 +/dev/cciss/c1d1p3 Controller 1, disk 1, partition 3 +.TE +.SS Files in /proc +The files +.I /proc/driver/cciss/cciss[0\-9]+ +contain information about +the configuration of each controller. +For example: +.PP +.in +4n +.EX +$ \fBcd /proc/driver/cciss\fP +$ \fBls \-l\fP +total 0 +-rw\-r\-\-r\-\- 1 root root 0 2010\-09\-10 10:38 cciss0 +-rw\-r\-\-r\-\- 1 root root 0 2010\-09\-10 10:38 cciss1 +-rw\-r\-\-r\-\- 1 root root 0 2010\-09\-10 10:38 cciss2 +$ \fBcat cciss2\fP +cciss2: HP Smart Array P800 Controller +Board ID: 0x3223103c +Firmware Version: 7.14 +IRQ: 16 +Logical drives: 1 +Current Q depth: 0 +Current # commands on controller: 0 +Max Q depth since init: 1 +Max # commands on controller since init: 2 +Max SG entries since init: 32 +Sequential access devices: 0 + +cciss/c2d0: 36.38GB RAID 0 +.EE +.in +.\" +.SS Files in /sys +.TP +.I /sys/bus/pci/devices/<dev>/ccissX/cXdY/model +Displays the SCSI INQUIRY page 0 model for logical drive +.I Y +of controller +.IR X . +.TP +.I /sys/bus/pci/devices/<dev>/ccissX/cXdY/rev +Displays the SCSI INQUIRY page 0 revision for logical drive +.I Y +of controller +.IR X . +.TP +.I /sys/bus/pci/devices/<dev>/ccissX/cXdY/unique_id +Displays the SCSI INQUIRY page 83 serial number for logical drive +.I Y +of controller +.IR X . +.TP +.I /sys/bus/pci/devices/<dev>/ccissX/cXdY/vendor +Displays the SCSI INQUIRY page 0 vendor for logical drive +.I Y +of controller +.IR X . +.TP +.I /sys/bus/pci/devices/<dev>/ccissX/cXdY/block:cciss!cXdY +A symbolic link to +.IR /sys/block/cciss!cXdY . +.TP +.I /sys/bus/pci/devices/<dev>/ccissX/rescan +When this file is written to, the driver rescans the controller +to discover any new, removed, or modified logical drives. +.TP +.I /sys/bus/pci/devices/<dev>/ccissX/resettable +A value of 1 displayed in this file indicates that +the "reset_devices=1" kernel parameter (used by +.BR kdump ) +is honored by this controller. +A value of 0 indicates that the +"reset_devices=1" kernel parameter will not be honored. +Some models of Smart Array are not able to honor this parameter. +.TP +.I /sys/bus/pci/devices/<dev>/ccissX/cXdY/lunid +Displays the 8-byte LUN ID used to address logical drive +.I Y +of controller +.IR X . +.TP +.I /sys/bus/pci/devices/<dev>/ccissX/cXdY/raid_level +Displays the RAID level of logical drive +.I Y +of controller +.IR X . +.TP +.I /sys/bus/pci/devices/<dev>/ccissX/cXdY/usage_count +Displays the usage count (number of opens) of logical drive +.I Y +of controller +.IR X . +.SS SCSI tape drive and medium changer support +SCSI sequential access devices and medium changer devices are supported and +appropriate device nodes are automatically created (e.g., +.IR /dev/st0 , +.IR /dev/st1 , +etc.; see +.BR st (4) +for more details.) +You must enable "SCSI tape drive support for Smart Array 5xxx" and +"SCSI support" in your kernel configuration to be able to use SCSI +tape drives with your Smart Array 5xxx controller. +.PP +Additionally, note that the driver will not engage the SCSI core at +init time. +The driver must be directed to dynamically engage the SCSI core via the +.I /proc +filesystem entry, +which the "block" side of the driver creates as +.I /proc/driver/cciss/cciss* +at run time. +This is because at driver init time, +the SCSI core may not yet be initialized (because the driver is a block +driver) and attempting to register it with the SCSI core in such a case +would cause a hang. +This is best done via an initialization script +(typically in +.IR /etc/init.d , +but could vary depending on distribution). +For example: +.PP +.in +4n +.EX +for x in /proc/driver/cciss/cciss[0\-9]* +do + echo "engage scsi" > $x +done +.EE +.in +.PP +Once the SCSI core is engaged by the driver, it cannot be disengaged +(except by unloading the driver, if it happens to be linked as a module.) +.PP +Note also that if no sequential access devices or medium changers are +detected, the SCSI core will not be engaged by the action of the above +script. +.SS Hot plug support for SCSI tape drives +Hot plugging of SCSI tape drives is supported, with some caveats. +The +.B cciss +driver must be informed that changes to the SCSI bus +have been made. +This may be done via the +.I /proc +filesystem. +For example: +.IP +echo "rescan" > /proc/scsi/cciss0/1 +.PP +This causes the driver to: +.RS +.IP 1. 3 +query the adapter about changes to the +physical SCSI buses and/or fiber channel arbitrated loop, and +.IP 2. +make note of any new or removed sequential access devices +or medium changers. +.RE +.PP +The driver will output messages indicating which +devices have been added or removed and the controller, bus, target, and +lun used to address each device. +The driver then notifies the SCSI midlayer +of these changes. +.PP +Note that the naming convention of the +.I /proc +filesystem entries +contains a number in addition to the driver name +(e.g., "cciss0" +instead of just "cciss", which you might expect). +.PP +Note: +.I Only +sequential access devices and medium changers are presented +as SCSI devices to the SCSI midlayer by the +.B cciss +driver. +Specifically, physical SCSI disk drives are +.I not +presented to the SCSI midlayer. +The only disk devices that are presented to the kernel are logical +drives that the array controller constructs from regions on +the physical drives. +The logical drives are presented to the block layer +(not to the SCSI midlayer). +It is important for the driver to prevent the kernel from accessing the +physical drives directly, since these drives are used by the array +controller to construct the logical drives. +.SS SCSI error handling for tape drives and medium changers +The Linux SCSI midlayer provides an error-handling protocol that +is initiated whenever a SCSI command fails to complete within a +certain amount of time (which can vary depending on the command). +The +.B cciss +driver participates in this protocol to some extent. +The normal protocol is a four-step process: +.IP * 3 +First, the device is told to abort the command. +.IP * +If that doesn't work, the device is reset. +.IP * +If that doesn't work, the SCSI bus is reset. +.IP * +If that doesn't work, the host bus adapter is reset. +.PP +The +.B cciss +driver is a block +driver as well as a SCSI driver and only the tape drives and medium +changers are presented to the SCSI midlayer. +Furthermore, unlike more +straightforward SCSI drivers, disk I/O continues through the block +side during the SCSI error-recovery process. +Therefore, the +.B cciss +driver implements only the first two of these actions, +aborting the command, and resetting the device. +Note also that most tape drives will not oblige +in aborting commands, and sometimes it appears they will not even +obey a reset command, though in most circumstances they will. +If the command cannot be aborted and the device cannot be +reset, the device will be set offline. +.PP +In the event that the error-handling code is triggered and a tape drive is +successfully reset or the tardy command is successfully aborted, the +tape drive may still not allow I/O to continue until some command +is issued that positions the tape to a known position. +Typically you must rewind the tape (by issuing +.I "mt \-f /dev/st0 rewind" +for example) before I/O can proceed again to a tape drive that was reset. +.SH SEE ALSO +.BR hpsa (4), +.BR cciss_vol_status (8), +.BR hpacucli (8), +.BR hpacuxe (8) +.PP +.UR http://cciss.sf.net +.UE , +and +.I Documentation/blockdev/cciss.txt +and +.I Documentation/ABI/testing/sysfs\-bus\-pci\-devices\-cciss +in the Linux kernel source tree +.\" .SH AUTHORS +.\" Don Brace, Steve Cameron, Chase Maupin, Mike Miller, Michael Ni, +.\" Charles White, Francis Wiran +.\" and probably some other people. diff --git a/man4/console_codes.4 b/man4/console_codes.4 new file mode 100644 index 000000000..c8bbbc12a --- /dev/null +++ b/man4/console_codes.4 @@ -0,0 +1,809 @@ +.\" Copyright (c) 1996 Andries Brouwer <aeb@cwi.nl>, Mon Oct 31 22:13:04 1996 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 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. +.\" +.\" 2006-05-27, Several corrections - Thomas E. Dickey +.\" +.TH CONSOLE_CODES 4 2021-03-22 "Linux man-pages (unreleased)" +.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, and so on. +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. +.PP +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. +.PP +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 \fBCharacter Sets\fP section below for discussion. +.PP +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. +.PP +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 \fBLinux Console Controls\fP section below for discussion. +.PP +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). +.SS 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. +.PP +.B "Control characters" +.PP +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\(en1f are regarded +as control characters, regardless of any "display control characters" +mode. +.PP +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: +.TP +BEL (0x07, \fB\(haG\fP) +beeps; +.TP +BS (0x08, \fB\(haH\fP) +backspaces one column +(but not past the beginning of the line); +.TP +HT (0x09, \fB\(haI\fP) +goes to the next tab stop or to the end of the line +if there is no earlier tab stop; +.TP +LF (0x0A, \fB\(haJ\fP) +.TQ +VT (0x0B, \fB\(haK\fP) +.TQ +FF (0x0C, \fB\(haL\fP) +all give a linefeed, +and if LF/NL (new-line mode) is set also a carriage return; +.TP +CR (0x0D, \fB\(haM\fP) +gives a carriage return; +.TP +SO (0x0E, \fB\(haN\fP) +activates the G1 character set; +.TP +SI (0x0F, \fB\(haO\fP) +activates the G0 character set; +.TP +CAN (0x18, \fB\(haX\fP) +.TQ +SUB (0x1A, \fB\(haZ\fP) +abort escape sequences; +.TP +ESC (0x1B, \fB\(ha[\fP) +starts an escape sequence; +.TP +DEL (0x7F) +is ignored; +.TP +CSI (0x9B) +is equivalent to ESC [. +.PP +.B "ESC- but not CSI-sequences" +.ad l +.TS +l l lx. +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 T{ +DEC private identification. The kernel +returns the string ESC [ ? 6 c, claiming +that it is a VT102. +T} +ESC 7 DECSC T{ +Save current state (cursor coordinates, +attributes, character sets pointed at by G0, G1). +T} +ESC 8 DECRC T{ +Restore state most recently saved by ESC 7. +T} +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 T{ +DEC screen alignment test \- fill screen with E's. +T} +ESC ( T{ +Start sequence defining G0 character set +(followed by one of B, 0, U, K, as below) +T} +ESC ( B T{ +Select default (ISO 8859-1 mapping). +T} +ESC ( 0 T{ +Select VT100 graphics mapping. +T} +ESC ( U T{ +Select null mapping \- straight to character ROM. +T} +ESC ( K T{ +Select user mapping \- the map that is loaded by the utility \fBmapscrn\fP(8). +T} +ESC ) T{ +Start sequence defining G1 (followed by one of B, 0, U, K, as above). +T} +ESC > DECPNM Set numeric keypad mode +ESC = DECPAM Set application keypad mode +ESC ] OSC T{ +Operating System Command prefix. +T} +ESC ] R Reset palette. +ESC ] P T{ +Set palette, with parameter given in 7 hexadecimal digits \fInrrggbb\fP after +the final P. Here \fIn\fP is the color (0\(en15), and \fIrrggbb\fP indicates +the red/green/blue values (0\(en255). +T} +.TE +.ad +.PP +.B "ECMA-48 CSI sequences" +.PP +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. +.PP +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.) +.PP +The action of a CSI sequence is determined by its final character. +.ad l +.TS +l l lx. +@ ICH T{ +Insert the indicated # of blank characters. +T} +A CUU T{ +Move cursor up the indicated # of rows. +T} +B CUD T{ +Move cursor down the indicated # of rows. +T} +C CUF T{ +Move cursor right the indicated # of columns. +T} +D CUB T{ +Move cursor left the indicated # of columns. +T} +E CNL T{ +Move cursor down the indicated # of rows, to column 1. +T} +F CPL T{ +Move cursor up the indicated # of rows, to column 1. +T} +G CHA T{ +Move cursor to indicated column in current row. +T} +H CUP T{ +Move cursor to the indicated row, column (origin at 1,1). +T} +J ED T{ +Erase display (default: from cursor to end of display). +T} + T{ +ESC [ 1 J: erase from start to cursor. +T} + T{ +ESC [ 2 J: erase whole display. +T} + T{ +ESC [ 3 J: erase whole display including scroll-back +buffer (since Linux 3.0). +T} +.\" ESC [ 3 J: commit f8df13e0a901fe55631fed66562369b4dba40f8b +K EL T{ +Erase line (default: from cursor to end of line). +T} + T{ +ESC [ 1 K: erase from start of line to cursor. +T} + T{ +ESC [ 2 K: erase whole line. +T} +L IL T{ +Insert the indicated # of blank lines. +T} +M DL T{ +Delete the indicated # of lines. +T} +P DCH T{ +Delete the indicated # of characters on current line. +T} +X ECH T{ +Erase the indicated # of characters on current line. +T} +a HPR T{ +Move cursor right the indicated # of columns. +T} +c DA T{ +Answer ESC [ ? 6 c: "I am a VT102". +T} +d VPA T{ +Move cursor to the indicated row, current column. +T} +e VPR T{ +Move cursor down the indicated # of rows. +T} +f HVP T{ +Move cursor to the indicated row, column. +T} +g TBC T{ +Without parameter: clear tab stop at current position. +T} + T{ +ESC [ 3 g: delete all tab stops. +T} +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 T{ +Set scrolling region; parameters are top and bottom row. +T} +s ? Save cursor location. +u ? Restore cursor location. +\` HPA T{ +Move cursor to indicated column in current row. +T} +.TE +.ad +.PP +.B ECMA-48 Select Graphic Rendition +.PP +The ECMA-48 SGR sequence ESC [ \fIparameters\fP m sets display +attributes. +Several attributes can be set in the same sequence, separated by +semicolons. +An empty parameter (between semicolons or string initiator or +terminator) is interpreted as a zero. +.ad l +.TS +l lx. +param result +0 T{ +reset all attributes to their defaults +T} +1 set bold +2 T{ +set half-bright (simulated with color on a color display) +T} +3 set italic (since Linux 2.6.22; simulated with color on a color display) +4 T{ +set underscore (simulated with color on a color display) +(the colors used to simulate dim or underline are set +using ESC ] ...) +T} +5 set blink +7 set reverse video +10 T{ +reset selected mapping, display control flag, +and toggle meta flag (ECMA-48 says "primary font"). +T} +11 T{ +select null mapping, set display control flag, +reset toggle meta flag (ECMA-48 says "first alternate font"). +T} +12 T{ +select null mapping, set display control flag, +set toggle meta flag (ECMA-48 says "second alternate font"). +The toggle meta flag +causes the high bit of a byte to be toggled +before the mapping table translation is done. +T} +21 T{ +set underline; before Linux 4.17, this value +set normal intensity (as is done in many other terminals) +T} +22 set normal intensity +23 italic off (since Linux 2.6.22) +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 T{ +256/24-bit foreground color follows, shoehorned into 16 basic colors +(before Linux 3.16: set underscore on, set default foreground color) +T} +39 T{ +set default foreground color +(before Linux 3.16: set underscore off, set default foreground color) +T} +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 +48 T{ +256/24-bit background color follows, shoehorned into 8 basic colors +T} +49 set default background color +90..97 T{ +set foreground to bright versions of 30..37 +T} +100..107 T{ +set background, same as 40..47 (bright not supported) +T} +.TE +.ad +.PP +Commands 38 and 48 require further arguments: +.TS +l lx. +;5;x T{ +256 color: values 0..15 are IBGR (black, red, green, ... white), +16..231 a 6x6x6 color cube, 232..255 a grayscale ramp +T} +;2;r;g;b T{ +24-bit color, r/g/b components are in the range 0..255 +T} +.TE +.PP +.B 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. +.\" +.PP +.B 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. +.\" +.PP +.B DEC Private Mode (DECSET/DECRST) sequences +.PP +.\" +These are not described in ECMA-48. +We list the Set Mode sequences; +the Reset Mode sequences are obtained by replacing the final \(aqh\(aq +by \(aql\(aq. +.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 autorepeat on. +.TP +ESC [ ? 9 h +X10 Mouse Reporting (default off): Set reporting mode to 1 (or reset to +0)\(emsee below. +.TP +ESC [ ? 25 h +DECTECM (default on): Make cursor visible. +.TP +ESC [ ? 1000 h +X11 Mouse Reporting (default off): Set reporting mode to 2 (or reset +to 0)\(emsee below. +.\" +.PP +.B Linux Console Private CSI Sequences +.PP +.\" +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; 8\(en15 = bright versions of 0\(en7. +.TS +l lx. +ESC [ 1 ; \fIn\fP ] T{ +Set color \fIn\fP as the underline color. +T} +ESC [ 2 ; \fIn\fP ] T{ +Set color \fIn\fP as the dim color. +T} +ESC [ 8 ] T{ +Make the current color pair the default attributes. +T} +ESC [ 9 ; \fIn\fP ] T{ +Set screen blank timeout to \fIn\fP minutes. +T} +ESC [ 10 ; \fIn\fP ] T{ +Set bell frequency in Hz. +T} +ESC [ 11 ; \fIn\fP ] T{ +Set bell duration in msec. +T} +ESC [ 12 ; \fIn\fP ] T{ +Bring specified console to the front. +T} +ESC [ 13 ] T{ +Unblank the screen. +T} +ESC [ 14 ; \fIn\fP ] T{ +Set the VESA powerdown interval in minutes. +T} +ESC [ 15 ] T{ +Bring the previous console to the front +(since Linux 2.6.0). +T} +ESC [ 16 ; \fIn\fP ] T{ +Set the cursor blink interval in milliseconds +(since Linux 4.2). +T} +.\" commit bd63364caa8df38bad2b25b11b2a1b849475cce5 +.TE +.SS 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. +.PP +There are two character sets, called G0 and G1, and one of them +is the current character set. +(Initially G0.) +Typing \fB\(haN\fP causes G1 to become current, +\fB\(haO\fP causes G0 to become current. +.PP +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. +.PP +The sequence ESC c causes a terminal reset, which is what you want if the +screen is all garbled. +The oft-advised "echo \(haV\(haO" will make only 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 \(ha[c". +If your terminfo entry for the console is correct +(and has an entry rs1=\eEc), then "tput reset" will also work. +.PP +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). +.SS Mouse tracking +The mouse tracking facility is intended to return +.BR xterm (1)-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 +.BR gpm (8) +daemon. +.PP +The mouse tracking escape sequences generated by +\fBxterm\fP(1) encode numeric parameters in a single character as +\fIvalue\fP+040. +For example, \(aq!\(aq is 1. +The screen coordinate system is 1-based. +.PP +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, \fBxterm\fP(1) 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. +.PP +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, \fBxterm\fP(1) 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). +.SS Comparisons with other terminals +Many different terminal types are described, like the Linux console, +as being "VT100-compatible". +Here we discuss differences between the +Linux console and the two most important others, the DEC VT102 and +.BR xterm (1). +.\" +.PP +.B Control-character handling +.PP +The VT102 also recognized the following control characters: +.TP +NUL (0x00) +was ignored; +.TP +ENQ (0x05) +triggered an answerback message; +.TP +DC1 (0x11, \fB\(haQ\fP, XON) +resumed transmission; +.TP +DC3 (0x13, \fB\(haS\fP, XOFF) +caused VT100 to ignore (and stop transmitting) +all codes except XOFF and XON. +.PP +VT100-like DC1/DC3 processing may be enabled by the terminal driver. +.PP +The +.BR xterm (1) +program (in VT100 mode) recognizes the control characters +BEL, BS, HT, LF, VT, FF, CR, SO, SI, ESC. +.\" +.PP +.B Escape sequences +.PP +VT100 console sequences not implemented on the Linux console: +.TS +l l l. +ESC N SS2 T{ +Single shift 2. (Select G2 character set for the next character only.) +T} +ESC O SS3 T{ +Single shift 3. (Select G3 character set for the next character only.) +T} +ESC P DCS T{ +Device control string (ended by ESC \e) +T} +ESC X SOS Start of string. +ESC \(ha PM Privacy message (ended by ESC \e) +ESC \e ST String terminator +ESC * ... Designate G2 character set +ESC + ... Designate G3 character set +.TE +.PP +The program +.BR xterm (1) +(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 \e, +ESC Z (it answers ESC [ ? 1 ; 2 c, "I am a VT100 with +advanced video option") +and ESC \(ha ... ESC \e 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 US-ASCII, +respectively. +.PP +The user can configure \fBxterm\fP(1) to respond to VT220-specific +control sequences, and it will identify itself as a VT52, VT100, and +up depending on the way it is configured and initialized. +.PP +It accepts ESC ] (OSC) for the setting of certain resources. +In addition to the ECMA-48 string terminator (ST), +\fBxterm\fP(1) accepts a BEL to terminate an OSC string. +These are a few of the OSC control sequences recognized by \fBxterm\fP(1): +.TS +l l. +ESC ] 0 ; \fItxt\fP ST T{ +Set icon name and window title to \fItxt\fP. +T} +ESC ] 1 ; \fItxt\fP ST Set icon name to \fItxt\fP. +ESC ] 2 ; \fItxt\fP ST Set window title to \fItxt\fP. +ESC ] 4 ; \fInum\fP; \fItxt\fP ST Set ANSI color \fInum\fP to \fItxt\fP. +ESC ] 10 ; \fItxt\fP ST Set dynamic text color to \fItxt\fP. +ESC ] 4 6 ; \fIname\fP ST T{ +Change log file to \fIname\fP (normally disabled by a compile-time option). +T} +ESC ] 5 0 ; \fIfn\fP ST Set font to \fIfn\fP. +.TE +.PP +It recognizes the following with slightly modified meaning +(saving more state, behaving closer to VT100/VT220): +.TS +l l l. +ESC 7 DECSC Save cursor +ESC 8 DECRC Restore cursor +.TE +.PP +It also recognizes +.TS +l l lx. +ESC F T{ +Cursor to lower left corner of screen (if enabled +by \fBxterm\fP(1)'s \fBhpLowerleftBugCompat\fP resource) +T} +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. +ESC } LS2R Invoke the G2 character set as GR. +ESC \(ti LS1R Invoke the G1 character set as GR. +.TE +.PP +It also recognizes ESC % and provides a more complete UTF-8 +implementation than Linux console. +.\" +.PP +.B CSI Sequences +.PP +Old versions of \fBxterm\fP(1), for example, from X11R5, +interpret the blink SGR as a bold SGR. +Later versions which implemented ANSI colors, for example, +XFree86 3.1.2A in 1995, improved this by allowing +the blink attribute to be displayed as a color. +Modern versions of xterm implement blink SGR as blinking text +and still allow colored text as an alternate rendering of SGRs. +Stock X11R6 versions did not recognize the color-setting SGRs until +the X11R6.8 release, which incorporated XFree86 xterm. +All ECMA-48 CSI sequences recognized by Linux are also recognized by +.IR xterm , +however \fBxterm\fP(1) implements several ECMA-48 and DEC control sequences +not recognized by Linux. +.PP +The \fBxterm\fP(1) +program recognizes all of the DEC Private Mode sequences listed +above, but none of the Linux private-mode sequences. +For discussion of \fBxterm\fP(1)'s +own private-mode sequences, refer to the +\fIXterm Control Sequences\fP +document by +Edward Moy, +Stephen Gildea, +and Thomas E.\& Dickey +available with the X distribution. +That document, though terse, is much longer than this manual page. +For a chronological overview, +.PP +.RS +.UR http://invisible\-island.net\:/xterm\:/xterm.log.html +.UE +.RE +.PP +details changes to xterm. +.PP +The \fIvttest\fP program +.PP +.RS +.UR http://invisible\-island.net\:/vttest/ +.UE +.RE +.PP +demonstrates many of these control sequences. +The \fBxterm\fP(1) source distribution also contains sample +scripts which exercise other features. +.SH NOTES +ESC 8 (DECRC) is not able to restore the character set changed with +ESC %. +.SH BUGS +In 2.0.23, CSI is broken, and NUL is not ignored inside +escape sequences. +.PP +Some older kernel versions (after 2.0) interpret 8-bit control +sequences. +These "C1 controls" use codes between 128 and 159 to replace +ESC [, ESC ] and similar two-byte control sequence initiators. +There are fragments of that in modern kernels (either overlooked or +broken by changes to support UTF-8), +but the implementation is incomplete and should be regarded +as unreliable. +.PP +Linux "private mode" sequences do not follow the rules in ECMA-48 +for private mode control sequences. +In particular, those ending with ] do not use a standard terminating +character. +The OSC (set palette) sequence is a greater problem, +since \fBxterm\fP(1) may interpret this as a control sequence +which requires a string terminator (ST). +Unlike the \fBsetterm\fP(1) sequences which will be ignored (since +they are invalid control sequences), the palette sequence will make +\fBxterm\fP(1) appear to hang (though pressing the return-key +will fix that). +To accommodate applications which have been hardcoded to use Linux +control sequences, +set the \fBxterm\fP(1) resource \fBbrokenLinuxOSC\fP to true. +.PP +An older version of this document implied that Linux recognizes the +ECMA-48 control sequence for invisible text. +It is ignored. +.SH SEE ALSO +.BR ioctl_console (2), +.BR charsets (7) diff --git a/man4/console_ioctl.4 b/man4/console_ioctl.4 new file mode 100644 index 000000000..5dfc68d8d --- /dev/null +++ b/man4/console_ioctl.4 @@ -0,0 +1,2 @@ +.so man2/ioctl_console.2 +.\" Link for old name of this page diff --git a/man4/cpuid.4 b/man4/cpuid.4 new file mode 100644 index 000000000..b5c3008e4 --- /dev/null +++ b/man4/cpuid.4 @@ -0,0 +1,81 @@ +.\" Copyright (c) 2009 Intel Corporation, Author Andi Kleen +.\" Description based on comments in arch/x86/kernel/cpuid.c +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH CPUID 4 2019-08-02 "Linux man-pages (unreleased)" +.SH NAME +cpuid \- x86 CPUID access device +.SH DESCRIPTION +CPUID provides an interface for querying information about the x86 CPU. +.PP +This device is accessed by +.BR lseek (2) +or +.BR pread (2) +to the appropriate CPUID level and reading in chunks of 16 bytes. +A larger read size means multiple reads of consecutive levels. +.PP +The lower 32 bits of the file position is used as the incoming +.IR %eax , +and the upper 32 bits of the file position as the incoming +.IR %ecx , +the latter is intended for "counting" +.I eax +levels like +.IR eax=4 . +.PP +This driver uses +.IR /dev/cpu/CPUNUM/cpuid , +where +.I CPUNUM +is the minor number, +and on an SMP box will direct the access to CPU +.I CPUNUM +as listed in +.IR /proc/cpuinfo . +.PP +This file is protected so that it can be read only by the user +.IR root , +or members of the group +.IR root . +.SH NOTES +The CPUID instruction can be directly executed by a program +using inline assembler. +However this device allows convenient +access to all CPUs without changing process affinity. +.PP +Most of the information in +.I cpuid +is reported by the kernel in cooked form either in +.I /proc/cpuinfo +or through subdirectories in +.IR /sys/devices/system/cpu . +Direct CPUID access through this device should only +be used in exceptional cases. +.PP +The +.I cpuid +driver is not auto-loaded. +On modular kernels you might need to use the following command +to load it explicitly before use: +.PP +.in +4n +.EX +$ modprobe cpuid +.EE +.in +.PP +There is no support for CPUID functions that require additional +input registers. +.PP +Very old x86 CPUs don't support CPUID. +.SH SEE ALSO +.BR cpuid (1) +.PP +Intel Corporation, Intel 64 and IA-32 Architectures +Software Developer's Manual Volume 2A: +Instruction Set Reference, A-M, 3-180 CPUID reference. +.PP +Intel Corporation, Intel Processor Identification and +the CPUID Instruction, Application note 485. diff --git a/man4/dsp56k.4 b/man4/dsp56k.4 new file mode 100644 index 000000000..1535e1288 --- /dev/null +++ b/man4/dsp56k.4 @@ -0,0 +1,102 @@ +.\" Copyright (c) 2000 lars brinkhoff <lars@nocrew.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified, Thu Jan 27 19:16:19 CET 2000, lars@nocrew.org +.\" +.TH DSP56K 4 2021-03-22 "Linux man-pages (unreleased)" +.SH NAME +dsp56k \- DSP56001 interface device +.SH SYNOPSIS +.nf +.B #include <asm/dsp56k.h> +.PP +.BI "ssize_t read(int " fd ", void *" data ", size_t " length ); +.BI "ssize_t write(int " fd ", void *" data ", size_t " length ); +.PP +.BI "int ioctl(int " fd ", DSP56K_UPLOAD, struct dsp56k_upload *" program ); +.BI "int ioctl(int " fd ", DSP56K_SET_TX_WSIZE, int " wsize ); +.BI "int ioctl(int " fd ", DSP56K_SET_RX_WSIZE, int " wsize ); +.BI "int ioctl(int " fd ", DSP56K_HOST_FLAGS, struct dsp56k_host_flags *" flags ); +.BI "int ioctl(int " fd ", DSP56K_HOST_CMD, int " cmd ); +.fi +.SH CONFIGURATION +The +.B 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 \fIdsp56k\fP special file is used to control the DSP56001, and +to send and receive data using the bidirectional handshaked host +port. +.PP +To send a data stream to the signal processor, use +.BR write (2) +to the +device, and +.BR read (2) +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 +.BR ioctl (2) +calls are used to control the +\fIdsp56k\fP device: +.IP \fBDSP56K_UPLOAD\fP +resets the DSP56001 and uploads a program. +The third +.BR ioctl (2) +argument must be a pointer to a \fIstruct dsp56k_upload\fP with members +\fIbin\fP pointing to a DSP56001 binary program, and \fIlen\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 bytes containing zero, +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 null byte (\(aq\e0\(aq) 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. +.IP +To access the host flags, the third +.BR ioctl (2) +argument must be a pointer +to a \fIstruct dsp56k_host_flags\fP. +If bit 0 or 1 is set in the +\fIdir\fP member, the corresponding bit in \fIout\fP will be written +to the host flags. +The state of all host flags will be returned in +the lower four bits of the \fIstatus\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 +.I /dev/dsp56k +.\" .SH AUTHORS +.\" Fredrik Noring <noring@nocrew.org>, lars brinkhoff <lars@nocrew.org>, +.\" Tomas Berndtsson <tomas@nocrew.org>. +.SH SEE ALSO +.IR linux/include/asm\-m68k/dsp56k.h , +.IR linux/drivers/char/dsp56k.c , +.UR http://dsp56k.nocrew.org/ +.UE , +DSP56000/DSP56001 Digital Signal Processor User's Manual diff --git a/man4/fd.4 b/man4/fd.4 new file mode 100644 index 000000000..7d25ee3fe --- /dev/null +++ b/man4/fd.4 @@ -0,0 +1,213 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@cantor.informatik.rwth-aachen.de) +.\" and 1994,1995 Alain Knaff (Alain.Knaff@imag.fr) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified, Sun Feb 26 15:00:02 1995, faith@cs.unc.edu +.\" +.TH FD 4 2020-08-13 "Linux man-pages (unreleased)" +.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. +If you are not sure, don't create device +entries for those formats, so as to prevent their usage. +.PP +Drive-independent device files which automatically detect the media +format and capacity: +.TS +l c +l c. +Name Base + minor # +_ +\fBfd\fP\fIn\fP 0 +.TE +.PP +5.25 inch double-density device files: +.TS +lw(1i) l l l l c +lw(1i) c c c c c. +Name Capacity Cyl. Sect. Heads Base + KiB minor # +_ +\fBfd\fP\fIn\fP\fBd360\fP 360 40 9 2 4 +.TE +.PP +5.25 inch high-density device files: +.TS +lw(1i) l l l l c +lw(1i) c c c c c. +Name Capacity Cyl. Sect. Heads Base + KiB minor # +_ +\fBfd\fP\fIn\fP\fBh360\fP 360 40 9 2 20 +\fBfd\fP\fIn\fP\fBh410\fP 410 41 10 2 48 +\fBfd\fP\fIn\fP\fBh420\fP 420 42 10 2 64 +\fBfd\fP\fIn\fP\fBh720\fP 720 80 9 2 24 +\fBfd\fP\fIn\fP\fBh880\fP 880 80 11 2 80 +\fBfd\fP\fIn\fP\fBh1200\fP 1200 80 15 2 8 +\fBfd\fP\fIn\fP\fBh1440\fP 1440 80 18 2 40 +\fBfd\fP\fIn\fP\fBh1476\fP 1476 82 18 2 56 +\fBfd\fP\fIn\fP\fBh1494\fP 1494 83 18 2 72 +\fBfd\fP\fIn\fP\fBh1600\fP 1600 80 20 2 92 +.TE +.PP +3.5 inch double-density device files: +.TS +lw(1i) l l l l c +lw(1i) c c c c c. +Name Capacity Cyl. Sect. Heads Base + KiB minor # +_ +\fBfd\fP\fIn\fP\fBu360\fP 360 80 9 1 12 +\fBfd\fP\fIn\fP\fBu720\fP 720 80 9 2 16 +\fBfd\fP\fIn\fP\fBu800\fP 800 80 10 2 120 +\fBfd\fP\fIn\fP\fBu1040\fP 1040 80 13 2 84 +\fBfd\fP\fIn\fP\fBu1120\fP 1120 80 14 2 88 +.TE +.PP +3.5 inch high-density device files: +.TS +lw(1i) l l l l c +lw(1i) c c c c c. +Name Capacity Cyl. Sect. Heads Base + KiB minor # +_ +\fBfd\fP\fIn\fP\fBu360\fP 360 40 9 2 12 +\fBfd\fP\fIn\fP\fBu720\fP 720 80 9 2 16 +\fBfd\fP\fIn\fP\fBu820\fP 820 82 10 2 52 +\fBfd\fP\fIn\fP\fBu830\fP 830 83 10 2 68 +\fBfd\fP\fIn\fP\fBu1440\fP 1440 80 18 2 28 +\fBfd\fP\fIn\fP\fBu1600\fP 1600 80 20 2 124 +\fBfd\fP\fIn\fP\fBu1680\fP 1680 80 21 2 44 +\fBfd\fP\fIn\fP\fBu1722\fP 1722 82 21 2 60 +\fBfd\fP\fIn\fP\fBu1743\fP 1743 83 21 2 76 +\fBfd\fP\fIn\fP\fBu1760\fP 1760 80 22 2 96 +\fBfd\fP\fIn\fP\fBu1840\fP 1840 80 23 2 116 +\fBfd\fP\fIn\fP\fBu1920\fP 1920 80 24 2 100 +.TE +.PP +3.5 inch extra-density device files: +.TS +lw(1i) l l l l c +lw(1i) c c c c c. +Name Capacity Cyl. Sect. Heads Base + KiB minor # +_ +\fBfd\fP\fIn\fP\fBu2880\fP 2880 80 36 2 32 +\fBfd\fP\fIn\fP\fBCompaQ\fP 2880 80 36 2 36 +\fBfd\fP\fIn\fP\fBu3200\fP 3200 80 40 2 104 +\fBfd\fP\fIn\fP\fBu3520\fP 3520 80 44 2 108 +\fBfd\fP\fIn\fP\fBu3840\fP 3840 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 reenable 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 \fI<linux/fd.h>\fP and +\fI<linux/fdreg.h>\fP include files, as well as the +.BR floppycontrol (1) +manual page. +.SH FILES +.I /dev/fd* +.SH NOTES +The various formats permit reading and writing many types of disks. +However, if a floppy is formatted with an inter-sector gap that is too small, +performance may drop, +to the point of needing a few seconds to access an entire track. +To prevent this, use interleaved formats. +.PP +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). +.PP +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 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) diff --git a/man4/full.4 b/man4/full.4 new file mode 100644 index 000000000..cc4b0f325 --- /dev/null +++ b/man4/full.4 @@ -0,0 +1,46 @@ +.\" This man-page is Copyright (C) 1997 John S. Kallal +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" correction, aeb, 970825 +.TH FULL 4 2019-03-06 "Linux man-pages (unreleased)" +.SH NAME +full \- always full device +.SH CONFIGURATION +If your system does not have +.I /dev/full +created already, it +can be created with the following commands: +.PP +.in +4n +.EX +mknod \-m 666 /dev/full c 1 7 +chown root:root /dev/full +.EE +.in +.SH DESCRIPTION +The file +.I /dev/full +has major device number 1 +and minor device number 7. +.PP +Writes to the +.I /dev/full +device fail with an +.B ENOSPC +error. +This can be used to test how a program handles disk-full errors. +.PP +Reads from the +.I /dev/full +device will return \e0 characters. +.PP +Seeks on +.I /dev/full +will always succeed. +.SH FILES +.I /dev/full +.SH SEE ALSO +.BR mknod (1), +.BR null (4), +.BR zero (4) diff --git a/man4/fuse.4 b/man4/fuse.4 new file mode 100644 index 000000000..219efd535 --- /dev/null +++ b/man4/fuse.4 @@ -0,0 +1,535 @@ +.\" Copyright (c) 2016 Julia Computing Inc, Keno Fischer +.\" Description based on include/uapi/fuse.h and code in fs/fuse +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH FUSE 4 2018-02-02 "Linux man-pages (unreleased)" +.SH NAME +fuse \- Filesystem in Userspace (FUSE) device +.SH SYNOPSIS +.nf +.B #include <linux/fuse.h> +.fi +.SH DESCRIPTION +This device is the primary interface between the FUSE filesystem driver +and a user-space process wishing to provide the filesystem (referred to +in the rest of this manual page as the +.IR "filesystem daemon" ). +This manual page is intended for those +interested in understanding the kernel interface itself. +Those implementing a FUSE filesystem may wish to make use of +a user-space library such as +.I libfuse +that abstracts away the low-level interface. +.PP +At its core, FUSE is a simple client-server protocol, in which the Linux +kernel is the client and the daemon is the server. +After obtaining a file descriptor for this device, the daemon may +.BR read (2) +requests from that file descriptor and is expected to +.BR write (2) +back its replies. +It is important to note that a file descriptor is +associated with a unique FUSE filesystem. +In particular, opening a second copy of this device, +will not allow access to resources created +through the first file descriptor (and vice versa). +.\" +.SS The basic protocol +Every message that is read by the daemon begins with a header described by +the following structure: +.PP +.in +4n +.EX +struct fuse_in_header { + uint32_t len; /* Total length of the data, + including this header */ + uint32_t opcode; /* The kind of operation (see below) */ + uint64_t unique; /* A unique identifier for this request */ + uint64_t nodeid; /* ID of the filesystem object + being operated on */ + uint32_t uid; /* UID of the requesting process */ + uint32_t gid; /* GID of the requesting process */ + uint32_t pid; /* PID of the requesting process */ + uint32_t padding; +}; +.EE +.in +.PP +The header is followed by a variable-length data portion +(which may be empty) specific to the requested operation +(the requested operation is indicated by +.IR opcode ). +.PP +The daemon should then process the request and if applicable send +a reply (almost all operations require a reply; if they do not, +this is documented below), by performing a +.BR write (2) +to the file descriptor. +All replies must start with the following header: +.PP +.in +4n +.EX +struct fuse_out_header { + uint32_t len; /* Total length of data written to + the file descriptor */ + int32_t error; /* Any error that occurred (0 if none) */ + uint64_t unique; /* The value from the + corresponding request */ +}; +.EE +.in +.PP +This header is also followed by (potentially empty) variable-sized +data depending on the executed request. +However, if the reply is an error reply (i.e., +.I error +is set), +then no further payload data should be sent, independent of the request. +.\" +.SS Exchanged messages +This section should contain documentation for each of the messages +in the protocol. +This manual page is currently incomplete, +so not all messages are documented. +For each message, first the struct sent by the kernel is given, +followed by a description of the semantics of the message. +.TP +.B FUSE_INIT +.IP +.in +4n +.EX +struct fuse_init_in { + uint32_t major; + uint32_t minor; + uint32_t max_readahead; /* Since protocol v7.6 */ + uint32_t flags; /* Since protocol v7.6 */ +}; +.EE +.in +.IP +This is the first request sent by the kernel to the daemon. +It is used to negotiate the protocol version and other filesystem parameters. +Note that the protocol version may affect the layout of any structure +in the protocol (including this structure). +The daemon must thus remember the negotiated version +and flags for each session. +As of the writing of this man page, +the highest supported kernel protocol version is +.IR 7.26 . +.IP +Users should be aware that the descriptions in this manual page +may be incomplete or incorrect for older or more recent protocol versions. +.IP +The reply for this request has the following format: +.IP +.in +4n +.EX +struct fuse_init_out { + uint32_t major; + uint32_t minor; + uint32_t max_readahead; /* Since v7.6 */ + uint32_t flags; /* Since v7.6; some flags bits + were introduced later */ + uint16_t max_background; /* Since v7.13 */ + uint16_t congestion_threshold; /* Since v7.13 */ + uint32_t max_write; /* Since v7.5 */ + uint32_t time_gran; /* Since v7.6 */ + uint32_t unused[9]; +}; +.EE +.in +.IP +If the major version supported by the kernel is larger than that supported +by the daemon, the reply shall consist of only +.I uint32_t major +(following the usual header), +indicating the largest major version supported by the daemon. +The kernel will then issue a new +.B FUSE_INIT +request conforming to the older version. +In the reverse case, the daemon should +quietly fall back to the kernel's major version. +.IP +The negotiated minor version is considered to be the minimum +of the minor versions provided by the daemon and the kernel and +both parties should use the protocol corresponding to said minor version. +.TP +.B FUSE_GETATTR +.IP +.in +4n +.EX +struct fuse_getattr_in { + uint32_t getattr_flags; + uint32_t dummy; + uint64_t fh; /* Set only if + (getattr_flags & FUSE_GETATTR_FH) +}; +.EE +.in +.IP +The requested operation is to compute the attributes to be returned +by +.BR stat (2) +and similar operations for the given filesystem object. +The object for which the attributes should be computed is indicated +either by +.I header\->nodeid +or, if the +.B FUSE_GETATTR_FH +flag is set, by the file handle +.IR fh . +The latter case of operation is analogous to +.BR fstat (2). +.IP +For performance reasons, these attributes may be cached in the kernel for +a specified duration of time. +While the cache timeout has not been exceeded, +the attributes will be served from the cache and will not cause additional +.B FUSE_GETATTR +requests. +.IP +The computed attributes and the requested +cache timeout should then be returned in the following structure: +.IP +.in +4n +.EX +struct fuse_attr_out { + /* Attribute cache duration (seconds + nanoseconds) */ + uint64_t attr_valid; + uint32_t attr_valid_nsec; + uint32_t dummy; + struct fuse_attr { + uint64_t ino; + uint64_t size; + uint64_t blocks; + uint64_t atime; + uint64_t mtime; + uint64_t ctime; + uint32_t atimensec; + uint32_t mtimensec; + uint32_t ctimensec; + uint32_t mode; + uint32_t nlink; + uint32_t uid; + uint32_t gid; + uint32_t rdev; + uint32_t blksize; + uint32_t padding; + } attr; +}; +.EE +.in +.TP +.B FUSE_ACCESS +.IP +.in +4n +.EX +struct fuse_access_in { + uint32_t mask; + uint32_t padding; +}; +.EE +.in +.IP +If the +.I default_permissions +mount options is not used, this request may be used for permissions checking. +No reply data is expected, but errors may be indicated +as usual by setting the +.I error +field in the reply header (in particular, access denied errors +may be indicated by returning +.BR \-EACCES ). +.TP +.BR FUSE_OPEN " and " FUSE_OPENDIR +.in +4n +.EX +struct fuse_open_in { + uint32_t flags; /* The flags that were passed + to the open(2) */ + uint32_t unused; +}; +.EE +.in +.IP +The requested operation is to open the node indicated by +.IR header\->nodeid . +The exact semantics of what this means will depend on the +filesystem being implemented. +However, at the very least the +filesystem should validate that the requested +.I flags +are valid for the indicated resource and then send a reply with the +following format: +.IP +.in +4n +.EX +struct fuse_open_out { + uint64_t fh; + uint32_t open_flags; + uint32_t padding; +}; +.EE +.in +.IP +The +.I fh +field is an opaque identifier that the kernel will use to refer +to this resource +The +.I open_flags +field is a bit mask of any number of the flags +that indicate properties of this file handle to the kernel: +.RS 7 +.TP 18 +.B FOPEN_DIRECT_IO +Bypass page cache for this open file. +.TP +.B FOPEN_KEEP_CACHE +Don't invalidate the data cache on open. +.TP +.B FOPEN_NONSEEKABLE +The file is not seekable. +.RE +.TP +.BR FUSE_READ " and " FUSE_READDIR +.IP +.in +4n +.EX +struct fuse_read_in { + uint64_t fh; + uint64_t offset; + uint32_t size; + uint32_t read_flags; + uint64_t lock_owner; + uint32_t flags; + uint32_t padding; +}; +.EE +.in +.IP +The requested action is to read up to +.I size +bytes of the file or directory, starting at +.IR offset . +The bytes should be returned directly following the usual reply header. +.TP +.B FUSE_INTERRUPT +.in +4n +.EX +struct fuse_interrupt_in { + uint64_t unique; +}; +.EE +.in +.IP +The requested action is to cancel the pending operation indicated by +.IR unique . +This request requires no response. +However, receipt of this message does +not by itself cancel the indicated operation. +The kernel will still expect a reply to said operation (e.g., an +.I EINTR +error or a short read). +At most one +.B FUSE_INTERRUPT +request will be issued for a given operation. +After issuing said operation, +the kernel will wait uninterruptibly for completion of the indicated request. +.TP +.B FUSE_LOOKUP +Directly following the header is a filename to be looked up in the directory +indicated by +.IR header\->nodeid . +The expected reply is of the form: +.IP +.in +4n +.EX +struct fuse_entry_out { + uint64_t nodeid; /* Inode ID */ + uint64_t generation; /* Inode generation */ + uint64_t entry_valid; + uint64_t attr_valid; + uint32_t entry_valid_nsec; + uint32_t attr_valid_nsec; + struct fuse_attr attr; +}; +.EE +.in +.IP +The combination of +.I nodeid +and +.I generation +must be unique for the filesystem's lifetime. +.IP +The interpretation of timeouts and +.I attr +is as for +.BR FUSE_GETATTR . +.TP +.B FUSE_FLUSH +.in +4n +.EX +struct fuse_flush_in { + uint64_t fh; + uint32_t unused; + uint32_t padding; + uint64_t lock_owner; +}; +.EE +.in +.IP +The requested action is to flush any pending changes to the indicated +file handle. +No reply data is expected. +However, an empty reply message +still needs to be issued once the flush operation is complete. +.TP +.BR FUSE_RELEASE " and " FUSE_RELEASEDIR +.in +4n +.EX +struct fuse_release_in { + uint64_t fh; + uint32_t flags; + uint32_t release_flags; + uint64_t lock_owner; +}; +.EE +.in +.IP +These are the converse of +.B FUSE_OPEN +and +.B FUSE_OPENDIR +respectively. +The daemon may now free any resources associated with the +file handle +.I fh +as the kernel will no longer refer to it. +There is no reply data associated with this request, +but a reply still needs to be issued once the request has +been completely processed. +.TP +.B FUSE_STATFS +This operation implements +.BR statfs (2) +for this filesystem. +There is no input data associated with this request. +The expected reply data has the following structure: +.IP +.in +4n +.EX +struct fuse_kstatfs { + uint64_t blocks; + uint64_t bfree; + uint64_t bavail; + uint64_t files; + uint64_t ffree; + uint32_t bsize; + uint32_t namelen; + uint32_t frsize; + uint32_t padding; + uint32_t spare[6]; +}; + +struct fuse_statfs_out { + struct fuse_kstatfs st; +}; +.EE +.in +.IP +For the interpretation of these fields, see +.BR statfs (2). +.SH ERRORS +.TP +.B E2BIG +Returned from +.BR read (2) +operations when the kernel's request is too large for the provided buffer +and the request was +.BR FUSE_SETXATTR . +.TP +.B EINVAL +Returned from +.BR write (2) +if validation of the reply failed. +Not all mistakes in replies will be caught by this validation. +However, basic mistakes, such as short replies or an incorrect +.I unique +value, are detected. +.TP +.B EIO +Returned from +.BR read (2) +operations when the kernel's request is too large for the provided buffer. +.IP +.IR Note : +There are various ways in which incorrect use of these interfaces can cause +operations on the provided filesystem's files and directories to fail with +.BR EIO . +Among the possible incorrect uses are: +.RS +.IP * 3 +changing +.I mode & S_IFMT +for an inode that has previously been reported to the kernel; or +.IP * +giving replies to the kernel that are shorter than what the kernel expected. +.RE +.TP +.B ENODEV +Returned from +.BR read (2) +and +.BR write (2) +if the FUSE filesystem was unmounted. +.TP +.B EPERM +Returned from operations on a +.I /dev/fuse +file descriptor that has not been mounted. +.SH STANDARDS +The FUSE filesystem is Linux-specific. +.SH NOTES +The following messages are not yet documented in this manual page: +.PP +.\" FIXME: Document the following. +.in +4n +.EX +.B FUSE_BATCH_FORGET +.B FUSE_BMAP +.B FUSE_CREATE +.B FUSE_DESTROY +.B FUSE_FALLOCATE +.B FUSE_FORGET +.B FUSE_FSYNC +.B FUSE_FSYNCDIR +.B FUSE_GETLK +.B FUSE_GETXATTR +.B FUSE_IOCTL +.B FUSE_LINK +.B FUSE_LISTXATTR +.B FUSE_LSEEK +.B FUSE_MKDIR +.B FUSE_MKNOD +.B FUSE_NOTIFY_REPLY +.B FUSE_POLL +.B FUSE_READDIRPLUS +.B FUSE_READLINK +.B FUSE_REMOVEXATTR +.B FUSE_RENAME +.B FUSE_RENAME2 +.B FUSE_RMDIR +.B FUSE_SETATTR +.B FUSE_SETLK +.B FUSE_SETLKW +.B FUSE_SYMLINK +.B FUSE_UNLINK +.B FUSE_WRITE +.EE +.in +.SH SEE ALSO +.BR fusermount (1), +.BR mount.fuse (8) diff --git a/man4/hd.4 b/man4/hd.4 new file mode 100644 index 000000000..0587e096f --- /dev/null +++ b/man4/hd.4 @@ -0,0 +1,82 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 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 2017-09-15 "Linux man-pages (unreleased)" +.SH NAME +hd \- MFM/IDE hard disk devices +.SH DESCRIPTION +The +.B hd* +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 +.BR hda ; +the slave drive is +.BR hdb . +The master drive of the second controller (major device number 22) +is +.B hdc +and the slave is +.BR hdd . +.PP +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\c +, is used to address the whole drive. +Partition numbers are assigned in the order the partitions +are discovered, and only nonempty, nonextended partitions +get a number. +However, partition numbers 1\(en4 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. +.PP +For example, +.I /dev/hda +refers to all of the first IDE drive in the system; and +.I /dev/hdb3 +refers to the third DOS "primary" partition on the second one. +.PP +They are typically created by: +.PP +.in +4n +.EX +mknod \-m 660 /dev/hda b 3 0 +mknod \-m 660 /dev/hda1 b 3 1 +mknod \-m 660 /dev/hda2 b 3 2 +\&... +mknod \-m 660 /dev/hda8 b 3 8 +mknod \-m 660 /dev/hdb b 3 64 +mknod \-m 660 /dev/hdb1 b 3 65 +mknod \-m 660 /dev/hdb2 b 3 66 +\&... +mknod \-m 660 /dev/hdb8 b 3 72 +chown root:disk /dev/hd* +.EE +.in +.SH FILES +.I /dev/hd* +.SH SEE ALSO +.BR chown (1), +.BR mknod (1), +.BR sd (4), +.BR mount (8) diff --git a/man4/hpsa.4 b/man4/hpsa.4 new file mode 100644 index 000000000..ae2eacebf --- /dev/null +++ b/man4/hpsa.4 @@ -0,0 +1,234 @@ +.\" Copyright (C) 2011, Hewlett-Packard Development Company, L.P. +.\" Written by Stephen M. Cameron <scameron@beardog.cce.hp.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-only +.\" +.\" shorthand for double quote that works everywhere. +.ds q \N'34' +.TH HPSA 4 2021-03-22 "Linux man-pages (unreleased)" +.SH NAME +hpsa \- HP Smart Array SCSI driver +.SH SYNOPSIS +.nf +modprobe hpsa [ hpsa_allow_any=1 ] +.fi +.SH DESCRIPTION +.B hpsa +is a SCSI driver for HP Smart Array RAID controllers. +.SS Options +.IR "hpsa_allow_any=1" : +This option allows the driver to attempt to operate on +any HP Smart Array hardware RAID controller, +even if it is not explicitly known to the driver. +This allows newer hardware to work with older drivers. +Typically this is used to allow installation of +operating systems from media that predates the +RAID controller, though it may also be used to enable +.B hpsa +to drive older controllers that would normally be handled by the +.BR cciss (4) +driver. +These older boards have not been tested and are +not supported with +.BR hpsa , +and +.BR cciss (4) +should still be used for these. +.SS Supported hardware +The +.B hpsa +driver supports the following Smart Array boards: +.PP +.nf + Smart Array P700M + Smart Array P212 + Smart Array P410 + Smart Array P410i + Smart Array P411 + Smart Array P812 + Smart Array P712m + Smart Array P711m + StorageWorks P1210m +.fi +.PP +.\" commit 135ae6edeb51979d0998daf1357f149a7d6ebb08 +Since Linux 4.14, the following Smart Array boards are also supported: +.PP +.nf + Smart Array 5300 + Smart Array 5312 + Smart Array 532 + Smart Array 5i + Smart Array 6400 + Smart Array 6400 EM + Smart Array 641 + Smart Array 642 + Smart Array 6i + Smart Array E200 + Smart Array E200i + Smart Array E200i + Smart Array E200i + Smart Array E200i + Smart Array E500 + Smart Array P400 + Smart Array P400i + Smart Array P600 + Smart Array P700m + Smart Array P800 +.fi +.SS Configuration details +To configure HP Smart Array controllers, +use the HP Array Configuration Utility (either +.BR hpacuxe (8) +or +.BR hpacucli (8)) +or the Offline ROM-based Configuration Utility (ORCA) +run from the Smart Array's option ROM at boot time. +.SH FILES +.SS Device nodes +Logical drives are accessed via the SCSI disk driver +.RB ( sd (4)), +tape drives via the SCSI tape driver +.RB ( st (4)), +and +the RAID controller via the SCSI generic driver +.RB ( sg (4)), +with device nodes named +.IR /dev/sd* , +.IR /dev/st* , +and +.IR /dev/sg* , +respectively. +.SS HPSA-specific host attribute files in /sys +.TP +.I /sys/class/scsi_host/host*/rescan +This is a write-only attribute. +Writing to this attribute will cause the driver to scan for +new, changed, or removed devices (e.g., hot-plugged tape drives, +or newly configured or deleted logical drives, etc.) +and notify the SCSI midlayer of any changes detected. +Normally a rescan is triggered automatically +by HP's Array Configuration Utility (either the GUI or the +command-line variety); +thus, for logical drive changes, the user should not +normally have to use this attribute. +This attribute may be useful when hot plugging devices like tape drives, +or entire storage boxes containing preconfigured logical drives. +.TP +.I /sys/class/scsi_host/host*/firmware_revision +This attribute contains the firmware version of the Smart Array. +.IP +For example: +.IP +.in +4n +.EX +# \fBcd /sys/class/scsi_host/host4\fP +# \fBcat firmware_revision\fP +7.14 +.EE +.in +.\" +.SS HPSA-specific disk attribute files in /sys +.TP +.I /sys/class/scsi_disk/c:b:t:l/device/unique_id +This attribute contains a 32 hex-digit unique ID for each logical drive. +.IP +For example: +.IP +.in +4n +.EX +# \fBcd /sys/class/scsi_disk/4:0:0:0/device\fP +# \fBcat unique_id\fP +600508B1001044395355323037570F77 +.EE +.in +.TP +.I /sys/class/scsi_disk/c:b:t:l/device/raid_level +This attribute contains the RAID level of each logical drive. +.IP +For example: +.IP +.in +4n +.EX +# \fBcd /sys/class/scsi_disk/4:0:0:0/device\fP +# \fBcat raid_level\fP +RAID 0 +.EE +.in +.TP +.I /sys/class/scsi_disk/c:b:t:l/device/lunid +This attribute contains the 16 hex-digit (8 byte) LUN ID +by which a logical drive or physical device can be addressed. +.IR c : b : t : l +are the controller, bus, target, and lun of the device. +.PP +For example: +.IP +.in +4n +.EX +# \fBcd /sys/class/scsi_disk/4:0:0:0/device\fP +# \fBcat lunid\fP +0x0000004000000000 +.EE +.in +.\" +.SS Supported ioctl() operations +For compatibility with applications written for the +.BR cciss (4) +driver, many, but +not all of the ioctls supported by the +.BR cciss (4) +driver are also supported by the +.B hpsa +driver. +The data structures used by these ioctls are described in +the Linux kernel source file +.IR include/linux/cciss_ioctl.h . +.TP +.BR CCISS_DEREGDISK ", " CCISS_REGNEWDISK ", " CCISS_REGNEWD +These three ioctls all do exactly the same thing, +which is to cause the driver to rescan for new devices. +This does exactly the same thing as writing to the +hpsa-specific host "rescan" attribute. +.TP +.B CCISS_GETPCIINFO +Returns PCI domain, bus, device, and function and "board ID" (PCI subsystem ID). +.TP +.B CCISS_GETDRIVVER +Returns driver version in three bytes encoded as: +.IP +.in +4n +.EX +(major_version << 16) | (minor_version << 8) | + (subminor_version) +.EE +.in +.TP +.BR CCISS_PASSTHRU ", " CCISS_BIG_PASSTHRU +Allows "BMIC" and "CISS" commands to be passed through to the Smart Array. +These are used extensively by the HP Array Configuration Utility, +SNMP storage agents, and so on. +See +.I cciss_vol_status +at +.UR http://cciss.sf.net +.UE +for some examples. +.SH SEE ALSO +.BR cciss (4), +.BR sd (4), +.BR st (4), +.BR cciss_vol_status (8), +.BR hpacucli (8), +.BR hpacuxe (8) +.PP +.UR http://cciss.sf.net +.UE , +and +.I Documentation/scsi/hpsa.txt +and +.I Documentation/ABI/testing/sysfs\-bus\-pci\-devices\-cciss +in the Linux kernel source tree +.\" .SH AUTHORS +.\" Don Brace, Steve Cameron, Tom Lawler, Mike Miller, Scott Teel +.\" and probably some other people. diff --git a/man4/initrd.4 b/man4/initrd.4 new file mode 100644 index 000000000..51f5dfc03 --- /dev/null +++ b/man4/initrd.4 @@ -0,0 +1,479 @@ +.\" This man-page is Copyright (C) 1997 John S. Kallal +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 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 2021-03-22 "Linux man-pages (unreleased)" +.SH NAME +initrd \- boot loader initialized RAM disk +.SH CONFIGURATION +.I /dev/initrd +is a read-only block device assigned +major number 1 and minor number 250. +Typically +.I /dev/initrd +is owned by +root:disk +with mode 0400 (read access by root only). +If the Linux system does not have +.I /dev/initrd +already created, it can be created with the following commands: +.PP +.in +4n +.EX +mknod \-m 400 /dev/initrd b 1 250 +chown root:disk /dev/initrd +.EE +.in +.PP +Also, support for both "RAM disk" and "Initial RAM disk" +(e.g., +.B CONFIG_BLK_DEV_RAM=y +and +.BR CONFIG_BLK_DEV_INITRD=y ) +must be compiled directly into the Linux kernel to use +.IR /dev/initrd . +When using +.IR /dev/initrd , +the RAM disk driver cannot be loaded as a module. +.\" +.\" +.\" +.SH DESCRIPTION +The special file +.I /dev/initrd +is a read-only block device. +This device is a RAM disk that is initialized (e.g., loaded) +by the boot loader before the kernel is started. +The kernel then can use +.IR /dev/initrd "'s" +contents for a two-phase system boot-up. +.PP +In the first boot-up phase, the kernel starts up +and mounts an initial root filesystem from the contents of +.I /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 filesystem +(i.e., the normal root filesystem) is mounted from a +different device. +.\" +.\" +.\" +.SS Boot-up operation +When booting up with +.BR initrd , +the system boots as follows: +.IP 1. 3 +The boot loader loads the kernel program and +.IR /dev/initrd 's +contents into memory. +.IP 2. +On kernel startup, +the kernel uncompresses and copies the contents of the device +.I /dev/initrd +onto device +.I /dev/ram0 +and then frees the memory used by +.IR /dev/initrd . +.IP 3. +The kernel then read-write mounts the device +.I /dev/ram0 +as the initial root filesystem. +.IP 4. +If the indicated normal root filesystem is also the initial +root filesystem (e.g., +.IR /dev/ram0 ) +then the kernel skips to the last step for the usual boot sequence. +.IP 5. +If the executable file +.I /linuxrc +is present in the initial root filesystem, +.I /linuxrc +is executed with UID 0. +(The file +.I /linuxrc +must have executable permission. +The file +.I /linuxrc +can be any valid executable, including a shell script.) +.IP 6. +If +.I /linuxrc +is not executed or when +.I /linuxrc +terminates, the normal root filesystem is mounted. +(If +.I /linuxrc +exits with any filesystems mounted on the initial root +filesystem, then the behavior of the kernel is +.BR UNSPECIFIED . +See the NOTES section for the current kernel behavior.) +.IP 7. +If the normal root filesystem has a directory +.IR /initrd , +the device +.I /dev/ram0 +is moved from +.I / +to +.IR /initrd . +Otherwise, if the directory +.I /initrd +does not exist, the device +.I /dev/ram0 +is unmounted. +(When moved from +.I / +to +.IR /initrd , +.I /dev/ram0 +is not unmounted and therefore processes can remain running from +.IR /dev/ram0 . +If directory +.I /initrd +does not exist on the normal root filesystem +and any processes remain running from +.I /dev/ram0 +when +.I /linuxrc +exits, the behavior of the kernel is +.BR UNSPECIFIED . +See the NOTES section for the current kernel behavior.) +.IP 8. +The usual boot sequence (e.g., invocation of +.IR /sbin/init ) +is performed on the normal root filesystem. +.\" +.\" +.\" +.SS 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 +.IR /dev/initrd . +For +.B LOADLIN +this is a command-line option. +For +.B LILO +you have to use this command in the +.B LILO +configuration file +.IR /etc/lilo.config . +The filename specified with this +option will typically be a gzipped filesystem image. +.TP +.B noinitrd +This boot option disables the two-phase boot-up operation. +The kernel performs the usual boot sequence as if +.I /dev/initrd +was not initialized. +With this option, any contents of +.I /dev/initrd +loaded into memory by the boot loader contents are preserved. +This option permits the contents of +.I /dev/initrd +to be any data and need not be limited to a filesystem image. +However, device +.I /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 filesystem. +For +.B LOADLIN +this is a command-line option. +For +.B LILO +this is a boot time option or +can be used as an option line in the +.B LILO +configuration file +.IR /etc/lilo.config . +The device specified by this option must be a mountable +device having a suitable root filesystem. +.\" +.\" +.\" +.SS Changing the normal root filesystem +By default, +the kernel's settings +(e.g., set in the kernel file with +.BR rdev (8) +or compiled into the kernel file), +or the boot loader option setting +is used for the normal root filesystems. +For an NFS-mounted normal root filesystem, one has to use the +.B nfs_root_name +and +.B nfs_root_addrs +boot options to give the NFS settings. +For more information on NFS-mounted root see the kernel documentation file +.I Documentation/filesystems/nfs/nfsroot.txt +.\" commit dc7a08166f3a5f23e79e839a8a88849bd3397c32 +(or +.I Documentation/filesystems/nfsroot.txt +before Linux 2.6.33). +For more information on setting the root filesystem see also the +.B LILO +and +.B LOADLIN +documentation. +.PP +It is also possible for the +.I /linuxrc +executable to change the normal root device. +For +.I /linuxrc +to change the normal root device, +.I /proc +must be mounted. +After mounting +.IR /proc , +.I /linuxrc +changes the normal root device by writing into the proc files +.IR /proc/sys/kernel/real\-root\-dev , +.IR /proc/sys/kernel/nfs\-root\-name , +and +.IR /proc/sys/kernel/nfs\-root\-addrs . +For a physical root device, the root device is changed by having +.I /linuxrc +write the new root filesystem device number into +.IR /proc/sys/kernel/real\-root\-dev . +For an NFS root filesystem, the root device is changed by having +.I /linuxrc +write the NFS setting into files +.I /proc/sys/kernel/nfs\-root\-name +and +.I /proc/sys/kernel/nfs\-root\-addrs +and then writing 0xff (e.g., the pseudo-NFS-device number) into file +.IR /proc/sys/kernel/real\-root\-dev . +For example, the following shell command line would change +the normal root device to +.IR /dev/hdb1 : +.PP +.in +4n +.EX +echo 0x365 >/proc/sys/kernel/real\-root\-dev +.EE +.in +.PP +For an NFS example, the following shell command lines would change the +normal root device to the NFS directory +.I /var/nfsroot +on a local networked NFS server with IP number 193.8.232.7 for a system with +IP number 193.8.232.2 and named "idefix": +.PP +.in +4n +.EX +echo /var/nfsroot >/proc/sys/kernel/nfs\-root\-name +echo 193.8.232.2:193.8.232.7::255.255.255.0:idefix \e + >/proc/sys/kernel/nfs\-root\-addrs +echo 255 >/proc/sys/kernel/real\-root\-dev +.EE +.in +.PP +.BR Note : +The use of +.I /proc/sys/kernel/real\-root\-dev +to change the root filesystem is obsolete. +See the Linux kernel source file +.I Documentation/admin\-guide/initrd.rst +.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 +(or +.I Documentation/initrd.txt +before Linux 4.10) +as well as +.BR pivot_root (2) +and +.BR pivot_root (8) +for information on the modern method of changing the root filesystem. +.\" FIXME . Should this manual page describe the pivot_root mechanism? +.\" +.\" +.\" +.SS Usage +The main motivation for implementing +.B initrd +was to allow for modular kernel configuration at system installation. +.PP +A possible system installation scenario is as follows: +.IP 1. 3 +The loader program boots from floppy or other media with a minimal kernel +(e.g., support for +.IR /dev/ram , +.IR /dev/initrd , +and the ext2 filesystem) and loads +.I /dev/initrd +with a gzipped version of the initial filesystem. +.IP 2. +The executable +.I /linuxrc +determines what is needed to (1) mount the normal root filesystem +(i.e., device type, device drivers, filesystem) 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. +.IP 3. +The executable +.I /linuxrc +loads the necessary modules from the initial root filesystem. +.IP 4. +The executable +.I /linuxrc +creates and populates the root filesystem. +(At this stage the normal root filesystem does not have to be a +completed system yet.) +.IP 5. +The executable +.I /linuxrc +sets +.IR /proc/sys/kernel/real\-root\-dev , +unmounts +.IR /proc , +the normal root filesystem and any other filesystems +it has mounted, and then terminates. +.IP 6. +The kernel then mounts the normal root filesystem. +.IP 7. +Now that the filesystem is accessible and intact, +the boot loader can be installed. +.IP 8. +The boot loader is configured to load into +.I /dev/initrd +a filesystem with the set of modules that was used to bring up the system. +(e.g., device +.I /dev/ram0 +can be modified, then unmounted, and finally, the image is written from +.I /dev/ram0 +to a file.) +.IP 9. +The system is now bootable and additional installation tasks can be +performed. +.PP +The key role of +.I /dev/initrd +in the above is to reuse 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 +.I /linuxrc +file or a file executed by +.I /linuxrc +would be different. +.PP +A third scenario is more convenient recovery disks. +Because information like the location of the root filesystem +partition is not needed at boot time, the system loaded from +.I /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 +.B initrd +for easy installation from the CD-ROM. +The distribution can use +.B LOADLIN +to directly load +.I /dev/initrd +from CD-ROM without the need of any floppies. +The distribution could also use a +.B LILO +boot floppy and then bootstrap a bigger RAM disk via +.I /dev/initrd +from the CD-ROM. +.\" +.\" +.\" +.SH FILES +.I /dev/initrd +.br +.I /dev/ram0 +.br +.I /linuxrc +.br +.I /initrd +.\" +.\" +.\" +.SH NOTES +.IP 1. 3 +With the current kernel, any filesystems that remain mounted when +.I /dev/ram0 +is moved from +.I / +to +.I /initrd +continue to be accessible. +However, the +.I /proc/mounts +entries are not updated. +.IP 2. +With the current kernel, if directory +.I /initrd +does not exist, then +.I /dev/ram0 +will +.B not +be fully unmounted if +.I /dev/ram0 +is used by any process or has any filesystem mounted on it. +If +.I /dev/ram0 +is +.B not +fully unmounted, then +.I /dev/ram0 +will remain in memory. +.IP 3. +Users of +.I /dev/initrd +should not depend on the behavior given in the above notes. +The behavior may change in future versions of the Linux kernel. +.\" +.\" +.\" +.\" .SH AUTHORS +.\" 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. +.SH SEE ALSO +.BR chown (1), +.BR mknod (1), +.BR ram (4), +.BR freeramdisk (8), +.BR rdev (8) +.PP +.I Documentation/admin\-guide/initrd.rst +.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 +(or +.I Documentation/initrd.txt +before Linux 4.10) +in the Linux kernel source tree, the LILO documentation, +the LOADLIN documentation, the SYSLINUX documentation diff --git a/man4/intro.4 b/man4/intro.4 new file mode 100644 index 000000000..220fe378a --- /dev/null +++ b/man4/intro.4 @@ -0,0 +1,22 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 16:57:14 1993 by Rik Faith (faith@cs.unc.edu) +.TH INTRO 4 2017-09-15 "Linux man-pages (unreleased)" +.SH NAME +intro \- introduction to special files +.SH DESCRIPTION +Section 4 of the manual describes special files (devices). +.SH FILES +/dev/* \(em device files +.SH NOTES +.SS Authors and copyright conditions +Look at the header of the manual page source for the author(s) and copyright +conditions. +Note that these can be different from page to page! +.SH SEE ALSO +.BR mknod (1), +.BR mknod (2), +.BR standards (7) diff --git a/man4/kmem.4 b/man4/kmem.4 new file mode 100644 index 000000000..d4c1762c5 --- /dev/null +++ b/man4/kmem.4 @@ -0,0 +1 @@ +.so man4/mem.4 diff --git a/man4/lirc.4 b/man4/lirc.4 new file mode 100644 index 000000000..2a2015098 --- /dev/null +++ b/man4/lirc.4 @@ -0,0 +1,422 @@ +.\" Copyright (c) 2015-2016, Alec Leamas +.\" Copyright (c) 2018, Sean Young <sean@mess.org> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.TH LIRC 4 2019-03-06 "Linux man-pages (unreleased)" +.SH NAME +lirc \- lirc devices +.SH DESCRIPTION +The +.I /dev/lirc* +character devices provide a low-level +bidirectional interface to infra-red (IR) remotes. +Most of these devices can receive, and some can send. +When receiving or sending data, the driver works in two different modes +depending on the underlying hardware. +.PP +Some hardware (typically TV-cards) decodes the IR signal internally +and provides decoded button presses as scancode values. +Drivers for this kind of hardware work in +.B LIRC_MODE_SCANCODE +mode. +Such hardware usually does not support sending IR signals. +Furthermore, such hardware can only decode a limited set of IR protocols, +usually only the protocol of the specific remote which is +bundled with, for example, a TV-card. +.PP +Other hardware provides a stream of pulse/space durations. +Such drivers work in +.B LIRC_MODE_MODE2 +mode. +Such hardware can be used with (almost) any kind of remote. +This type of hardware can also be used in +.B LIRC_MODE_SCANCODE +mode, in which case the kernel IR decoders will decode the IR. +These decoders can be written in extended BPF (see +.BR bpf (2)) +and attached to the +.B lirc +device. +Sometimes, this kind of hardware also supports +sending IR data. +.PP +The \fBLIRC_GET_FEATURES\fR ioctl (see below) allows probing for whether +receiving and sending is supported, and in which modes, amongst other +features. +.\" +.SS Reading input with the LIRC_MODE_MODE2 mode +In the \fBLIRC_MODE_MODE2 mode\fR, the data returned by +.BR read (2) +provides 32-bit values representing a space or a pulse duration. +The time of the duration (microseconds) is encoded in the lower 24 bits. +Pulse (also known as flash) +indicates a duration of infrared light being detected, +and space (also known as gap) indicates a duration with no infrared. +If the duration of space exceeds the inactivity timeout, +a special timeout package is delivered, +which marks the end of a message. +The upper 8 bits indicate the type of package: +.TP 4 +.B LIRC_MODE2_SPACE +Value reflects a space duration (microseconds). +.TP 4 +.B LIRC_MODE2_PULSE +Value reflects a pulse duration (microseconds). +.TP 4 +.B LIRC_MODE2_FREQUENCY +Value reflects a frequency (Hz); see the +.B LIRC_SET_MEASURE_CARRIER_MODE +ioctl. +.TP 4 +.B LIRC_MODE2_TIMEOUT +Value reflects a space duration (microseconds). +The package reflects a timeout; see the +.B LIRC_SET_REC_TIMEOUT_REPORTS +ioctl. +.\" +.TP 4 +.B LIRC_MODE2_OVERFLOW +The IR receiver encountered an overflow, +and as a result data is missing +(since Linux 5.18). +.SS Reading input with the LIRC_MODE_SCANCODE mode +In the \fBLIRC_MODE_SCANCODE\fR +mode, the data returned by +.BR read (2) +reflects decoded button presses, in the struct \fIlirc_scancode\fR. +The scancode is stored in the \fIscancode\fR field, and the IR protocol +is stored in \fIrc_proto\fR. +This field has one the values of the \fIenum rc_proto\fR. +.\" +.SS Writing output with the LIRC_MODE_PULSE mode +The data written to the character device using +.BR write (2) +is a pulse/space sequence of integer values. +Pulses and spaces are only marked implicitly by their position. +The data must start and end with a pulse, thus it must always include +an odd number of samples. +The +.BR write (2) +function blocks until the data has been transmitted by the +hardware. +If more data is provided than the hardware can send, the +.BR write (2) +call fails with the error +.BR EINVAL . +.SS Writing output with the LIRC_MODE_SCANCODE mode +The data written to the character devices must be a single struct +\fIlirc_scancode\fR. +The \fIscancode\fR and \fIrc_proto\fR fields must +filled in, all other fields must be 0. +The kernel IR encoders will +convert the scancode to pulses and spaces. +The protocol or scancode is invalid, or the +.B lirc +device cannot transmit. +.SH IOCTL COMMANDS +.nf +#include <linux/lirc.h> /* But see BUGS */ + +int ioctl(int fd, int cmd, int *val); +.fi +.PP +The following +.BR ioctl (2) +operations are provided by the +.B lirc +character device to probe or change specific +.B lirc +hardware settings. +.SS Always Supported Commands +\fI/dev/lirc*\fR devices always support the following commands: +.TP 4 +.BR LIRC_GET_FEATURES " (\fIvoid\fP)" +Returns a bit mask of combined features bits; see FEATURES. +.PP +If a device returns an error code for +.BR LIRC_GET_FEATURES , +it is safe to assume it is not a +.B lirc +device. +.\" +.SS Optional Commands +Some +.B lirc +devices support the commands listed below. +Unless otherwise stated, these fail with the error \fBENOTTY\fR if the +operation isn't supported, or with the error \fBEINVAL\fR if the operation +failed, or invalid arguments were provided. +If a driver does not announce support of certain features, invoking +the corresponding ioctls will fail with the error +.BR ENOTTY . +.TP +.BR LIRC_GET_REC_MODE " (\fIvoid\fP)" +If the +.B lirc +device has no receiver, this operation fails with the error +.BR ENOTTY . +Otherwise, it returns the receive mode, which will be one of: +.RS +.TP +.B LIRC_MODE_MODE2 +The driver returns a sequence of pulse/space durations. +.TP +.B LIRC_MODE_SCANCODE +The driver returns struct +.I lirc_scancode +values, each of which represents +a decoded button press. +.RE +.TP +.BR LIRC_SET_REC_MODE " (\fIint\fP)" +Set the receive mode. +.I val +is either +.B LIRC_MODE_SCANCODE +or +.BR LIRC_MODE_MODE2 . +If the +.B lirc +device has no receiver, this operation fails with the error +.B ENOTTY. +.TP +.BR LIRC_GET_SEND_MODE " (\fIvoid\fP)" +Return the send mode. +.B LIRC_MODE_PULSE +or +.B LIRC_MODE_SCANCODE +is supported. +If the +.B lirc +device cannot send, this operation fails with the error +.B ENOTTY. +.TP +.BR LIRC_SET_SEND_MODE " (\fIint\fP)" +Set the send mode. +.I val +is either +.B LIRC_MODE_SCANCODE +or +.BR LIRC_MODE_PULSE . +If the +.B lirc +device cannot send, this operation fails with the error +.BR ENOTTY . +.TP +.BR LIRC_SET_SEND_CARRIER " (\fIint\fP)" +Set the modulation frequency. +The argument is the frequency (Hz). +.TP +.BR LIRC_SET_SEND_DUTY_CYCLE " (\fIint\fP)" +Set the carrier duty cycle. +.I val +is a number in the range [0,100] which +describes the pulse width as a percentage of the total cycle. +Currently, no special meaning is defined for 0 or 100, but the values +are reserved for future use. +.TP +.BR LIRC_GET_MIN_TIMEOUT " (\fIvoid\fP)", " "\ +LIRC_GET_MAX_TIMEOUT " (\fIvoid\fP)" +Some devices have internal timers that can be used to detect when +there has been no IR activity for a long time. +This can help +.BR lircd (8) +in detecting that an IR signal is finished and can speed up the +decoding process. +These operations +return integer values with the minimum/maximum timeout that can be +set (microseconds). +Some devices have a fixed timeout. +For such drivers, +.B LIRC_GET_MIN_TIMEOUT +and +.B LIRC_GET_MAX_TIMEOUT +will fail with the error +.BR ENOTTY . +.TP +.BR LIRC_SET_REC_TIMEOUT " (\fIint\fP)" +Set the integer value for IR inactivity timeout (microseconds). +To be accepted, the value must be within the limits defined by +.B LIRC_GET_MIN_TIMEOUT +and +.BR LIRC_GET_MAX_TIMEOUT . +A value of 0 (if supported by the hardware) disables all hardware +timeouts and data should be reported as soon as possible. +If the exact value cannot be set, then the next possible value +.I greater +than the given value should be set. +.TP +.BR LIRC_GET_REC_TIMEOUT " (\fIvoid\fP)" +Return the current inactivity timeout (microseconds). +Available since Linux 4.18. +.TP +.BR LIRC_SET_REC_TIMEOUT_REPORTS " (\fIint\fP)" +Enable +.RI ( val +is 1) or disable +.RI ( val +is 0) timeout packages in +.BR LIRC_MODE_MODE2 . +The behavior of this operation has varied across kernel versions: +.RS +.IP * 3 +Since Linux 5.17: +timeout packages are always enabled and this ioctl is a no-op. +.IP * +Since Linux 4.16: +timeout packages are enabled by default. +Each time the +.B lirc +device is opened, the +.B LIRC_SET_REC_TIMEOUT +operation can be used to disable (and, if desired, to later re-enable) +the timeout on the file descriptor. +.IP * +In Linux 4.15 and earlier: +timeout packages are disabled by default, and enabling them (via +.BR LIRC_SET_REC_TIMEOUT ) +on any file descriptor associated with the +.B lirc +device has the effect of enabling timeouts for all file descriptors +referring to that device (until timeouts are disabled again). +.RE +.TP +.BR LIRC_SET_REC_CARRIER " (\fIint\fP)" +Set the upper bound of the receive carrier frequency (Hz). +See +.BR LIRC_SET_REC_CARRIER_RANGE . +.TP +.BR LIRC_SET_REC_CARRIER_RANGE " (\fIint\fP)" +Sets the lower bound of the receive carrier frequency (Hz). +For this to take affect, first set the lower bound using the +.B LIRC_SET_REC_CARRIER_RANGE +ioctl, and then the upper bound using the +.B LIRC_SET_REC_CARRIER +ioctl. +.TP +.BR LIRC_SET_MEASURE_CARRIER_MODE " (\fIint\fP)" +Enable +.RI ( val +is 1) or disable +.RI ( val +is 0) the measure mode. +If enabled, from the next key press on, the driver will send +.B LIRC_MODE2_FREQUENCY +packets. +By default, this should be turned off. +.TP +.BR LIRC_GET_REC_RESOLUTION " (\fIvoid\fP)" +Return the driver resolution (microseconds). +.TP +.BR LIRC_SET_TRANSMITTER_MASK " (\fIint\fP)" +Enable the set of transmitters specified in +.IR val , +which contains a bit mask where each enabled transmitter is a 1. +The first transmitter is encoded by the least significant bit, and so on. +When an invalid bit mask is given, for example a bit is set even +though the device does not have so many transmitters, +this operation returns the +number of available transmitters and does nothing otherwise. +.TP +.BR LIRC_SET_WIDEBAND_RECEIVER " (\fIint\fP)" +Some devices are equipped with a special wide band receiver which is +intended to be used to learn the output of an existing remote. +This ioctl can be used to enable +.RI ( val +equals 1) or disable +.RI ( val +equals 0) this functionality. +This might be useful for devices that otherwise have narrow band +receivers that prevent them to be used with certain remotes. +Wide band receivers may also be more precise. +On the other hand, their disadvantage usually is reduced range of +reception. +.IP +Note: wide band receiver may be implicitly enabled if you enable +carrier reports. +In that case, it will be disabled as soon as you disable carrier reports. +Trying to disable a wide band receiver while carrier reports are active +will do nothing. +.\" +.SH FEATURES +the +.B LIRC_GET_FEATURES +ioctl returns a bit mask describing features of the driver. +The following bits may be returned in the mask: +.TP +.B LIRC_CAN_REC_MODE2 +The driver is capable of receiving using +.BR LIRC_MODE_MODE2 . +.TP +.B LIRC_CAN_REC_SCANCODE +The driver is capable of receiving using +.BR LIRC_MODE_SCANCODE . +.TP +.B LIRC_CAN_SET_SEND_CARRIER +The driver supports changing the modulation frequency using +.BR LIRC_SET_SEND_CARRIER . +.TP +.B LIRC_CAN_SET_SEND_DUTY_CYCLE +The driver supports changing the duty cycle using +.BR LIRC_SET_SEND_DUTY_CYCLE . +.TP +.B LIRC_CAN_SET_TRANSMITTER_MASK +The driver supports changing the active transmitter(s) using +.BR LIRC_SET_TRANSMITTER_MASK . +.TP +.B LIRC_CAN_SET_REC_CARRIER +The driver supports setting the receive carrier frequency using +.BR LIRC_SET_REC_CARRIER . +Any +.B lirc +device since the drivers were merged in kernel release 2.6.36 +must have +.B LIRC_CAN_SET_REC_CARRIER_RANGE +set if +.B LIRC_CAN_SET_REC_CARRIER +feature is set. +.TP +.B LIRC_CAN_SET_REC_CARRIER_RANGE +The driver supports +.BR LIRC_SET_REC_CARRIER_RANGE . +The lower bound of the carrier must first be set using the +.B LIRC_SET_REC_CARRIER_RANGE +ioctl, before using the +.B LIRC_SET_REC_CARRIER +ioctl to set the upper bound. +.TP +.B LIRC_CAN_GET_REC_RESOLUTION +The driver supports +.BR LIRC_GET_REC_RESOLUTION . +.TP +.B LIRC_CAN_SET_REC_TIMEOUT +The driver supports +.BR LIRC_SET_REC_TIMEOUT . +.TP +.B LIRC_CAN_MEASURE_CARRIER +The driver supports measuring of the modulation frequency using +.BR LIRC_SET_MEASURE_CARRIER_MODE . +.TP +.B LIRC_CAN_USE_WIDEBAND_RECEIVER +The driver supports learning mode using +.BR LIRC_SET_WIDEBAND_RECEIVER . +.TP +.B LIRC_CAN_SEND_PULSE +The driver supports sending using +.B LIRC_MODE_PULSE +or +.B LIRC_MODE_SCANCODE +.\" +.SH BUGS +Using these devices requires the kernel source header file +.IR lirc.h . +This file is not available before kernel release 4.6. +Users of older kernels could use the file bundled in +.UR http://www.lirc.org +.UE . +.\" +.SH SEE ALSO +\fBir\-ctl\fP(1), \fBlircd\fP(8),\ \fBbpf\fP(2) +.PP +.UR https://www.kernel.org/\:doc/\:html/\:latest/\:userspace\-api/\:media/\:rc/\:lirc\-dev.html +.UE diff --git a/man4/loop-control.4 b/man4/loop-control.4 new file mode 100644 index 000000000..251e65203 --- /dev/null +++ b/man4/loop-control.4 @@ -0,0 +1 @@ +.so man4/loop.4 diff --git a/man4/loop.4 b/man4/loop.4 new file mode 100644 index 000000000..f4d4e7df2 --- /dev/null +++ b/man4/loop.4 @@ -0,0 +1,359 @@ +.\" Copyright 2002 Urs Thuermann (urs@isnogud.escape.de) +.\" and Copyright 2015 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH LOOP 4 2021-03-22 "Linux man-pages (unreleased)" +.SH NAME +loop, loop-control \- loop devices +.SH SYNOPSIS +.nf +#include <linux/loop.h> +.fi +.SH DESCRIPTION +The loop device is a block device that maps its data blocks not to a +physical device such as a hard disk or optical disk drive, +but to the blocks of +a regular file in a filesystem or to another block device. +This can be useful for example to provide a block device for a filesystem +image stored in a file, so that it can be mounted with the +.BR mount (8) +command. +You could do +.PP +.in +4n +.EX +$ \fBdd if=/dev/zero of=file.img bs=1MiB count=10\fP +$ \fBsudo losetup /dev/loop4 file.img\fP +$ \fBsudo mkfs \-t ext4 /dev/loop4\fP +$ \fBsudo mkdir /myloopdev\fP +$ \fBsudo mount /dev/loop4 /myloopdev\fP +.EE +.in +.PP +See +.BR losetup (8) +for another example. +.PP +A transfer function can be specified for each loop device for +encryption and decryption purposes. +.PP +The following +.BR ioctl (2) +operations are provided by the loop block device: +.TP +.B LOOP_SET_FD +Associate the loop device with the open file whose file descriptor is +passed as the (third) +.BR ioctl (2) +argument. +.TP +.B LOOP_CLR_FD +Disassociate the loop device from any file descriptor. +.TP +.B LOOP_SET_STATUS +Set the status of the loop device using the (third) +.BR ioctl (2) +argument. +This argument is a pointer to a +.I loop_info +structure, defined in +.I <linux/loop.h> +as: +.IP +.in +4n +.EX +struct loop_info { + int lo_number; /* ioctl r/o */ + dev_t lo_device; /* ioctl r/o */ + unsigned long lo_inode; /* ioctl r/o */ + dev_t lo_rdevice; /* ioctl r/o */ + int lo_offset; + int lo_encrypt_type; + int lo_encrypt_key_size; /* ioctl w/o */ + int lo_flags; /* ioctl r/w (r/o before + Linux 2.6.25) */ + char lo_name[LO_NAME_SIZE]; + unsigned char lo_encrypt_key[LO_KEY_SIZE]; + /* ioctl w/o */ + unsigned long lo_init[2]; + char reserved[4]; +}; +.EE +.in +.IP +The encryption type +.RI ( lo_encrypt_type ) +should be one of +.BR LO_CRYPT_NONE , +.BR LO_CRYPT_XOR , +.BR LO_CRYPT_DES , +.BR LO_CRYPT_FISH2 , +.BR LO_CRYPT_BLOW , +.BR LO_CRYPT_CAST128 , +.BR LO_CRYPT_IDEA , +.BR LO_CRYPT_DUMMY , +.BR LO_CRYPT_SKIPJACK , +or (since Linux 2.6.0) +.BR LO_CRYPT_CRYPTOAPI . +.IP +The +.I lo_flags +field is a bit mask that can include zero or more of the following: +.RS +.TP +.B LO_FLAGS_READ_ONLY +The loopback device is read-only. +.TP +.BR LO_FLAGS_AUTOCLEAR " (since Linux 2.6.25)" +.\" commit 96c5865559cee0f9cbc5173f3c949f6ce3525581 +The loopback device will autodestruct on last close. +.TP +.BR LO_FLAGS_PARTSCAN " (since Linux 3.2)" +.\" commit e03c8dd14915fabc101aa495828d58598dc5af98 +Allow automatic partition scanning. +.TP +.BR LO_FLAGS_DIRECT_IO " (since Linux 4.10)" +.\" commit 2e5ab5f379f96a6207c45be40c357ebb1beb8ef3 +Use direct I/O mode to access the backing file. +.RE +.IP +The only +.I lo_flags +that can be modified by +.B LOOP_SET_STATUS +are +.B LO_FLAGS_AUTOCLEAR +and +.BR LO_FLAGS_PARTSCAN . +.TP +.B LOOP_GET_STATUS +Get the status of the loop device. +The (third) +.BR ioctl (2) +argument must be a pointer to a +.IR "struct loop_info" . +.TP +.BR LOOP_CHANGE_FD " (since Linux 2.6.5)" +Switch the backing store of the loop device to the new file identified +file descriptor specified in the (third) +.BR ioctl (2) +argument, which is an integer. +This operation is possible only if the loop device is read-only and +the new backing store is the same size and type as the old backing store. +.TP +.BR LOOP_SET_CAPACITY " (since Linux 2.6.30)" +.\" commit 53d6660836f233df66490707365ab177e5fb2bb4 +Resize a live loop device. +One can change the size of the underlying backing store and then use this +operation so that the loop driver learns about the new size. +This operation takes no argument. +.TP +.BR LOOP_SET_DIRECT_IO " (since Linux 4.10)" +.\" commit ab1cb278bc7027663adbfb0b81404f8398437e11 +Set DIRECT I/O mode on the loop device, so that +it can be used to open backing file. +The (third) +.BR ioctl (2) +argument is an unsigned long value. +A nonzero represents direct I/O mode. +.TP +.BR LOOP_SET_BLOCK_SIZE " (since Linux 4.14)" +.\" commit 89e4fdecb51cf5535867026274bc97de9480ade5 +Set the block size of the loop device. +The (third) +.BR ioctl (2) +argument is an unsigned long value. +This value must be a power of two in the range +[512,pagesize]; +otherwise, an +.B EINVAL +error results. +.TP +.BR LOOP_CONFIGURE " (since Linux 5.8)" +.\" commit 3448914e8cc550ba792d4ccc74471d1ca4293aae +Setup and configure all loop device parameters in a single step using +the (third) +.BR ioctl (2) +argument. +This argument is a pointer to a +.I loop_config +structure, defined in +.I <linux/loop.h> +as: +.IP +.in +4n +.EX +struct loop_config { + __u32 fd; + __u32 block_size; + struct loop_info64 info; + __u64 __reserved[8]; +}; +.EE +.in +.IP +In addition to doing what +.B LOOP_SET_STATUS +can do, +.B LOOP_CONFIGURE +can also be used to do the following: +.RS +.IP * 2 +set the correct block size immediately by setting +.IR loop_config.block_size ; +.IP * +explicitly request direct I/O mode by setting +.B LO_FLAGS_DIRECT_IO +in +.IR loop_config.info.lo_flags ; +and +.IP * +explicitly request read-only mode by setting +.B LO_FLAGS_READ_ONLY +in +.IR loop_config.info.lo_flags . +.RE +.PP +Since Linux 2.6, there are two new +.BR ioctl (2) +operations: +.TP +.BR LOOP_SET_STATUS64 ", " LOOP_GET_STATUS64 +These are similar to +.BR LOOP_SET_STATUS " and " LOOP_GET_STATUS +described above but use the +.I loop_info64 +structure, +which has some additional fields and a larger range for some other fields: +.IP +.in +4n +.EX +struct loop_info64 { + uint64_t lo_device; /* ioctl r/o */ + uint64_t lo_inode; /* ioctl r/o */ + uint64_t lo_rdevice; /* ioctl r/o */ + uint64_t lo_offset; + uint64_t lo_sizelimit; /* bytes, 0 == max available */ + uint32_t lo_number; /* ioctl r/o */ + uint32_t lo_encrypt_type; + uint32_t lo_encrypt_key_size; /* ioctl w/o */ + uint32_t lo_flags; i /* ioctl r/w (r/o before + Linux 2.6.25) */ + uint8_t lo_file_name[LO_NAME_SIZE]; + uint8_t lo_crypt_name[LO_NAME_SIZE]; + uint8_t lo_encrypt_key[LO_KEY_SIZE]; /* ioctl w/o */ + uint64_t lo_init[2]; +}; +.EE +.in +.SS /dev/loop-control +Since Linux 3.1, +.\" commit 770fe30a46a12b6fb6b63fbe1737654d28e84844 +the kernel provides the +.I /dev/loop\-control +device, which permits an application to dynamically find a free device, +and to add and remove loop devices from the system. +To perform these operations, one first opens +.I /dev/loop\-control +and then employs one of the following +.BR ioctl (2) +operations: +.TP +.B LOOP_CTL_GET_FREE +Allocate or find a free loop device for use. +On success, the device number is returned as the result of the call. +This operation takes no argument. +.TP +.B LOOP_CTL_ADD +Add the new loop device whose device number is specified +as a long integer in the third +.BR ioctl (2) +argument. +On success, the device index is returned as the result of the call. +If the device is already allocated, the call fails with the error +.BR EEXIST . +.TP +.B LOOP_CTL_REMOVE +Remove the loop device whose device number is specified +as a long integer in the third +.BR ioctl (2) +argument. +On success, the device number is returned as the result of the call. +If the device is in use, the call fails with the error +.BR EBUSY . +.SH FILES +.TP +.I /dev/loop* +The loop block special device files. +.SH EXAMPLES +The program below uses the +.I /dev/loop\-control +device to find a free loop device, opens the loop device, +opens a file to be used as the underlying storage for the device, +and then associates the loop device with the backing store. +The following shell session demonstrates the use of the program: +.PP +.in +4n +.EX +$ \fBdd if=/dev/zero of=file.img bs=1MiB count=10\fP +10+0 records in +10+0 records out +10485760 bytes (10 MB) copied, 0.00609385 s, 1.7 GB/s +$ \fBsudo ./mnt_loop file.img\fP +loopname = /dev/loop5 +.EE +.in +.SS Program source +\& +.EX +#include <fcntl.h> +#include <linux/loop.h> +#include <sys/ioctl.h> +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> + +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e + } while (0) + +int +main(int argc, char *argv[]) +{ + int loopctlfd, loopfd, backingfile; + long devnr; + char loopname[4096]; + + if (argc != 2) { + fprintf(stderr, "Usage: %s backing\-file\en", argv[0]); + exit(EXIT_FAILURE); + } + + loopctlfd = open("/dev/loop\-control", O_RDWR); + if (loopctlfd == \-1) + errExit("open: /dev/loop\-control"); + + devnr = ioctl(loopctlfd, LOOP_CTL_GET_FREE); + if (devnr == \-1) + errExit("ioctl\-LOOP_CTL_GET_FREE"); + + sprintf(loopname, "/dev/loop%ld", devnr); + printf("loopname = %s\en", loopname); + + loopfd = open(loopname, O_RDWR); + if (loopfd == \-1) + errExit("open: loopname"); + + backingfile = open(argv[1], O_RDWR); + if (backingfile == \-1) + errExit("open: backing\-file"); + + if (ioctl(loopfd, LOOP_SET_FD, backingfile) == \-1) + errExit("ioctl\-LOOP_SET_FD"); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR losetup (8), +.BR mount (8) diff --git a/man4/lp.4 b/man4/lp.4 new file mode 100644 index 000000000..2e6630969 --- /dev/null +++ b/man4/lp.4 @@ -0,0 +1,126 @@ +.\" Copyright (c) Michael Haardt (michael@cantor.informatik.rwth-aachen.de), +.\" Sun Jan 15 19:16:33 1995 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified, Sun Feb 26 15:02:58 1995, faith@cs.unc.edu +.TH LP 4 2021-03-22 "Linux man-pages (unreleased)" +.SH NAME +lp \- line printer devices +.SH SYNOPSIS +.nf +.B #include <linux/lp.h> +.fi +.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 user +.I root +and group +.IR lp . +You can use printer ports either with polling or with interrupts. +Interrupts are recommended when high traffic is expected, for example, +for laser printers. +For typical 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 +.IR arg . +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 influences only 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 +.IR arg . +If printing is too slow, increase this number; if the +system gets too slow, decrease this number. +The default is 1000. +It influences only the polling driver. +.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPABORT, int \fP\fIarg\fP\fB)\fP" +If +.I arg +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 +.I arg +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 +.I arg +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 +.IR arg . +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. +.\" FIXME . Actually, since Linux 2.2, the default is 1 +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 +.BR ioctl (2) +requires superuser privileges. +It takes an +.I int +containing the new IRQ as argument. +As a side effect, the printer will be reset. +When +.I arg +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 +.IR arg . +.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPGETSTATUS, int *\fP\fIarg\fP\fB)\fP" +Stores the value of the status port in +.IR arg . +The bits have the following meaning: +.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 +.IP +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 +.I /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 modularized 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) diff --git a/man4/mem.4 b/man4/mem.4 new file mode 100644 index 000000000..9fc2f4608 --- /dev/null +++ b/man4/mem.4 @@ -0,0 +1,81 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 16:59:10 1993 by Rik Faith (faith@cs.unc.edu) +.TH MEM 4 2015-01-02 "Linux man-pages (unreleased)" +.SH NAME +mem, kmem, port \- system memory, kernel memory and system ports +.SH DESCRIPTION +.I /dev/mem +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. +.PP +Byte addresses in +.I /dev/mem +are interpreted as physical memory addresses. +References to nonexistent locations cause errors to be returned. +.PP +Examining and patching is likely to lead to unexpected results +when read-only or write-only bits are present. +.PP +Since Linux 2.6.26, and depending on the architecture, the +.B CONFIG_STRICT_DEVMEM +kernel configuration option limits the areas +which can be accessed through this file. +For example: on x86, RAM access is not allowed but accessing +memory-mapped PCI regions is. +.PP +It is typically created by: +.PP +.in +4n +.EX +mknod \-m 660 /dev/mem c 1 1 +chown root:kmem /dev/mem +.EE +.in +.PP +The file +.I /dev/kmem +is the same as +.IR /dev/mem , +except that the kernel virtual memory +rather than physical memory is accessed. +Since Linux 2.6.26, this file is available only if the +.B CONFIG_DEVKMEM +kernel configuration option is enabled. +.PP +It is typically created by: +.PP +.in +4n +.EX +mknod \-m 640 /dev/kmem c 1 2 +chown root:kmem /dev/kmem +.EE +.in +.PP +.I /dev/port +is similar to +.IR /dev/mem , +but the I/O ports are accessed. +.PP +It is typically created by: +.PP +.in +4n +.EX +mknod \-m 660 /dev/port c 1 4 +chown root:kmem /dev/port +.EE +.in +.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) diff --git a/man4/mouse.4 b/man4/mouse.4 new file mode 100644 index 000000000..4d21a9574 --- /dev/null +++ b/man4/mouse.4 @@ -0,0 +1,170 @@ +.\" This manpage is Copyright (C) 1996 Michael Haardt. +.\" Updates Nov 1998, Andries Brouwer +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.TH MOUSE 4 2020-08-13 "Linux man-pages (unreleased)" +.SH NAME +mouse \- serial mouse interface +.SH CONFIGURATION +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: +.PP +.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 +.PP +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 (\(aqM\(aq) on the data line. +After a further 63 ms, a Microsoft-compatible 3-button mouse will send +0x33 (\(aq3\(aq). +.PP +The relative mouse movement is sent as +.I dx +(positive means right) +and +.I dy +(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: +.PP +.TS +center; +l l. +bit/s string +9600 *q +4800 *p +2400 *o +1200 *n +.TE +.PP +The first byte of a data packet can be used for synchronization purposes. +.SS Microsoft protocol +The +.B Microsoft +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 +.I dx +and +.I dy +movements are sent as +two's-complement, +.I lb +.RI ( rb ) +are set when the left (right) +button is pressed: +.PP +.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 +.B Mousesystems +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. +.I dx +is sent as the sum of the two two's-complement +values, +.I dy +is send as negated sum of the two two's-complement +values. +.I lb +.RI ( mb , +.IR rb ) +are cleared when the left (middle, +right) button is pressed: +.PP +.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 +.PP +Bytes 4 and 5 describe the change that occurred since bytes 2 and 3 +were transmitted. +.SS Sun protocol +The +.B Sun +protocol is the 3-byte version of the above 5-byte +Mousesystems protocol: the last two bytes are not sent. +.SS MM protocol +The +.B MM +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. +.I dx +and +.I dy +are sent as single signed values, the +sign bit indicating a negative value. +.I lb +.RI ( mb , +.IR rb ) +are +set when the left (middle, right) button is pressed: +.PP +.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 symbolic link pointing to a mouse device. +.SH SEE ALSO +.BR ttyS (4), +.BR gpm (8) diff --git a/man4/msr.4 b/man4/msr.4 new file mode 100644 index 000000000..791c2fdee --- /dev/null +++ b/man4/msr.4 @@ -0,0 +1,42 @@ +.\" Copyright (c) 2009 Intel Corporation, Author Andi Kleen +.\" Some sentences copied from comments in arch/x86/kernel/msr.c +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH MSR 4 2021-03-22 "Linux man-pages (unreleased)" +.SH NAME +msr \- x86 CPU MSR access device +.SH DESCRIPTION +.I /dev/cpu/CPUNUM/msr +provides an interface to read and write the model-specific +registers (MSRs) of an x86 CPU. +.I CPUNUM +is the number of the CPU to access as listed in +.IR /proc/cpuinfo . +.PP +The register access is done by opening the file and seeking +to the MSR number as offset in the file, and then +reading or writing in chunks of 8 bytes. +An I/O transfer of more than 8 bytes means multiple reads or writes +of the same register. +.PP +This file is protected so that it can be read and written only by the user +.IR root , +or members of the group +.IR root . +.SH NOTES +The +.I msr +driver is not auto-loaded. +On modular kernels you might need to use the following command +to load it explicitly before use: +.PP +.in +4n +.EX +$ modprobe msr +.EE +.in +.SH SEE ALSO +Intel Corporation Intel 64 and IA-32 Architectures +Software Developer's Manual Volume 3B Appendix B, +for an overview of the Intel CPU MSRs. diff --git a/man4/null.4 b/man4/null.4 new file mode 100644 index 000000000..0d65f3ee8 --- /dev/null +++ b/man4/null.4 @@ -0,0 +1,52 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 17:00:12 1993 by Rik Faith (faith@cs.unc.edu) +.TH NULL 4 2015-07-23 "Linux man-pages (unreleased)" +.SH NAME +null, zero \- data sink +.SH DESCRIPTION +Data written to the +.I /dev/null +and +.I /dev/zero +special files is discarded. +.PP +Reads from +.I /dev/null +always return end of file (i.e., +.BR read (2) +returns 0), whereas reads from +.I /dev/zero +always return bytes containing zero (\(aq\e0\(aq characters). +.PP +These devices are typically created by: +.PP +.in +4n +.EX +mknod \-m 666 /dev/null c 1 3 +mknod \-m 666 /dev/zero c 1 5 +chown root:root /dev/null /dev/zero +.EE +.in +.SH FILES +.I /dev/null +.br +.I /dev/zero +.SH NOTES +If these devices are not writable and readable for all users, many +programs will act strangely. +.PP +Since Linux 2.6.31, +.\" commit 2b83868723d090078ac0e2120e06a1cc94dbaef0 +reads from +.I /dev/zero +are interruptible by signals. +(This change was made to help with bad latencies for large reads from +.IR /dev/zero .) +.SH SEE ALSO +.BR chown (1), +.BR mknod (1), +.BR full (4) diff --git a/man4/port.4 b/man4/port.4 new file mode 100644 index 000000000..d4c1762c5 --- /dev/null +++ b/man4/port.4 @@ -0,0 +1 @@ +.so man4/mem.4 diff --git a/man4/ptmx.4 b/man4/ptmx.4 new file mode 100644 index 000000000..b50d4e710 --- /dev/null +++ b/man4/ptmx.4 @@ -0,0 +1 @@ +.so man4/pts.4 diff --git a/man4/pts.4 b/man4/pts.4 new file mode 100644 index 000000000..5e2941175 --- /dev/null +++ b/man4/pts.4 @@ -0,0 +1,75 @@ +.\" This man page was written by Jeremy Phelps <jphelps@notreached.net>. +.\" Notes added - aeb +.\" +.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE) +.\" Redistribute and revise at will. +.\" %%%LICENSE_END +.\" +.TH PTS 4 2020-08-13 "Linux man-pages (unreleased)" +.SH NAME +ptmx, pts \- pseudoterminal master and slave +.SH DESCRIPTION +The file +.I /dev/ptmx +(the pseudoterminal multiplexor device) +is a character file with major number 5 and +minor number 2, usually with mode 0666 and ownership root:root. +It is used to create a pseudoterminal master and slave pair. +.PP +When a process opens +.IR /dev/ptmx , +it gets a file +descriptor for a pseudoterminal master +and a pseudoterminal slave device is created in the +.I /dev/pts +directory. +Each file descriptor obtained by opening +.I /dev/ptmx +is an independent pseudoterminal master with its own associated slave, +whose path can +be found by passing the file descriptor to +.BR ptsname (3). +.PP +Before opening the pseudoterminal slave, you must pass the master's file +descriptor to +.BR grantpt (3) +and +.BR unlockpt (3). +.PP +Once both the pseudoterminal 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 file descriptor as input. +Data written to the master is presented to the slave as input. +.PP +In practice, pseudoterminals are used for implementing terminal emulators +such as +.BR xterm (1), +in which data read from the pseudoterminal 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 pseudoterminal master is sent across the network +to a client program that is connected to a terminal or terminal emulator. +.PP +Pseudoterminals can also be used to send input to programs that normally +refuse to read input from pipes (such as +.BR su (1), +and +.BR passwd (1)). +.SH FILES +.IR /dev/ptmx , +.I /dev/pts/* +.SH NOTES +The Linux support for the above (known as UNIX 98 pseudoterminal naming) +is done using the +.I devpts +filesystem, which should be mounted on +.IR /dev/pts . +.SH SEE ALSO +.BR getpt (3), +.BR grantpt (3), +.BR ptsname (3), +.BR unlockpt (3), +.BR pty (7) diff --git a/man4/ram.4 b/man4/ram.4 new file mode 100644 index 000000000..218da4423 --- /dev/null +++ b/man4/ram.4 @@ -0,0 +1,28 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 17:01:11 1993 by Rik Faith (faith@cs.unc.edu) +.TH RAM 4 1992-11-21 "Linux man-pages (unreleased)" +.SH NAME +ram \- ram disk device +.SH DESCRIPTION +The +.I ram +device is a block device to access the ram disk in raw mode. +.PP +It is typically created by: +.PP +.in +4n +.EX +mknod \-m 660 /dev/ram b 1 1 +chown root:disk /dev/ram +.EE +.in +.SH FILES +.I /dev/ram +.SH SEE ALSO +.BR chown (1), +.BR mknod (1), +.BR mount (8) diff --git a/man4/random.4 b/man4/random.4 new file mode 100644 index 000000000..273bc051d --- /dev/null +++ b/man4/random.4 @@ -0,0 +1,347 @@ +.\" Copyright (c) 1997 John S. Kallal (kallal@voicenet.com) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Some changes by tytso and aeb. +.\" +.\" 2004-12-16, John V. Belmonte/mtk, Updated init and quit scripts +.\" 2004-04-08, AEB, Improved description of read from /dev/urandom +.\" 2008-06-20, George Spelvin <linux@horizon.com>, +.\" Matt Mackall <mpm@selenic.com> +.\" +.TH RANDOM 4 2021-03-22 "Linux man-pages (unreleased)" +.SH NAME +random, urandom \- kernel random number source devices +.SH SYNOPSIS +.nf +#include <linux/random.h> +.PP +.BI "int ioctl(" fd ", RND" request ", " param ");" +.fi +.SH DESCRIPTION +The character special files \fI/dev/random\fP and +\fI/dev/urandom\fP (present since Linux 1.3.30) +provide an interface to the kernel's random number generator. +The file +.I /dev/random +has major device number 1 and minor device number 8. +The file +.I /dev/urandom +has major device number 1 and minor device number 9. +.PP +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. +.PP +Linux 3.17 and later provides the simpler and safer +.BR getrandom (2) +interface which requires no special files; +see the +.BR getrandom (2) +manual page for details. +.PP +When read, the +.I /dev/urandom +device returns random bytes using a pseudorandom +number generator seeded from the entropy pool. +Reads from this device do not block (i.e., the CPU is not yielded), +but can incur an appreciable delay when requesting large amounts of data. +.PP +When read during early boot time, +.I /dev/urandom +may return data prior to the entropy pool being initialized. +.\" This is a real problem; see +.\" commit 9b4d008787f864f17d008c9c15bbe8a0f7e2fc24 +If this is of concern in your application, use +.BR getrandom (2) +or \fI/dev/random\fP instead. +.PP +The \fI/dev/random\fP device is a legacy interface which dates back to +a time where the cryptographic primitives used in the implementation +of \fI/dev/urandom\fP were not widely trusted. +It will return random bytes only within the estimated number of +bits of fresh noise in the entropy pool, blocking if necessary. +\fI/dev/random\fP is suitable for applications that need +high quality randomness, and can afford indeterminate delays. +.PP +When the entropy pool is empty, reads from \fI/dev/random\fP will block +until additional environmental noise is gathered. +Since Linux 5.6, the +.B O_NONBLOCK +flag is ignored as +.I /dev/random +will no longer block except during early boot process. +In earlier versions, if +.BR open (2) +is called for +.I /dev/random +with the +.B O_NONBLOCK +flag, a subsequent +.BR read (2) +will not block if the requested number of bytes is not available. +Instead, the available bytes are returned. +If no byte is available, +.BR read (2) +will return \-1 and +.I errno +will be set to +.BR EAGAIN . +.PP +The +.B O_NONBLOCK +flag has no effect when opening +.IR /dev/urandom . +When calling +.BR read (2) +for the device +.IR /dev/urandom , +reads of up to 256 bytes will return as many bytes as are requested +and will not be interrupted by a signal handler. +Reads with a buffer over this limit may return less than the +requested number of bytes or fail with the error +.BR EINTR , +if interrupted by a signal handler. +.PP +Since Linux 3.16, +.\" commit 79a8468747c5f95ed3d5ce8376a3e82e0c5857fc +a +.BR read (2) +from +.I /dev/urandom +will return at most 32\ MB. +A +.BR read (2) +from +.I /dev/random +will return at most 512 bytes +.\" SEC_XFER_SIZE in drivers/char/random.c +(340 bytes on Linux kernels before version 2.6.12). +.PP +Writing to \fI/dev/random\fP or \fI/dev/urandom\fP will update the +entropy pool with the data written, but this will not result in a +higher entropy count. +This means that it will impact the contents +read from both files, but it will not make reads from +\fI/dev/random\fP faster. +.SS Usage +The +.I /dev/random +interface is considered a legacy interface, and +.I /dev/urandom +is preferred and sufficient in all use cases, with the exception of +applications which require randomness during early boot time; for +these applications, +.BR getrandom (2) +must be used instead, +because it will block until the entropy pool is initialized. +.PP +If a seed file is saved across reboots as recommended below, +the output is +cryptographically secure against attackers without local root access as +soon as it is reloaded in the boot sequence, and perfectly adequate for +network encryption session keys. +(All major Linux distributions have saved the seed file across reboots +since 2000 at least.) +Since reads from +.I /dev/random +may block, users will usually want to open it in nonblocking mode +(or perform a read with timeout), +and provide some sort of user notification if the desired +entropy is not immediately available. +.\" +.SS Configuration +If your system does not have +\fI/dev/random\fP and \fI/dev/urandom\fP created already, they +can be created with the following commands: +.PP +.in +4n +.EX +mknod \-m 666 /dev/random c 1 8 +mknod \-m 666 /dev/urandom c 1 9 +chown root:root /dev/random /dev/urandom +.EE +.in +.PP +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 lines to an appropriate script +which is run during the Linux system start-up sequence: +.PP +.in +4n +.EX +echo "Initializing random number generator..." +random_seed=/var/run/random\-seed +# Carry a random seed from start\-up to start\-up +# Load and then save the whole entropy pool +if [ \-f $random_seed ]; then + cat $random_seed >/dev/urandom +else + touch $random_seed +fi +chmod 600 $random_seed +poolfile=/proc/sys/kernel/random/poolsize +[ \-r $poolfile ] && bits=$(cat $poolfile) || bits=4096 +bytes=$(expr $bits / 8) +dd if=/dev/urandom of=$random_seed count=1 bs=$bytes +.EE +.in +.PP +Also, add the following lines in an appropriate script which is +run during the Linux system shutdown: +.PP +.in +4n +.EX +# Carry a random seed from shut\-down to start\-up +# Save the whole entropy pool +echo "Saving random seed..." +random_seed=/var/run/random\-seed +touch $random_seed +chmod 600 $random_seed +poolfile=/proc/sys/kernel/random/poolsize +[ \-r $poolfile ] && bits=$(cat $poolfile) || bits=4096 +bytes=$(expr $bits / 8) +dd if=/dev/urandom of=$random_seed count=1 bs=$bytes +.EE +.in +.PP +In the above examples, we assume Linux 2.6.0 or later, where +.I /proc/sys/kernel/random/poolsize +returns the size of the entropy pool in bits (see below). +.\" +.SS /proc interfaces +The files in the directory +.I /proc/sys/kernel/random +(present since 2.3.16) provide additional information about the +.I /dev/random +device: +.TP +.I entropy_avail +This read-only file gives the available entropy, in bits. +This will be a number in the range 0 to 4096. +.TP +.I poolsize +This file +gives the size of the entropy pool. +The semantics of this file vary across kernel versions: +.RS +.TP +Linux 2.4: +This file gives the size of the entropy pool in +.IR bytes . +Normally, this file will have the value 512, but it is writable, +and can be changed to any value for which an algorithm is available. +The choices are 32, 64, 128, 256, 512, 1024, or 2048. +.TP +Linux 2.6 and later: +This file is read-only, and gives the size of the entropy pool in +.IR bits . +It contains the value 4096. +.RE +.TP +.I read_wakeup_threshold +This file +contains the number of bits of entropy required for waking up processes +that sleep waiting for entropy from +.IR /dev/random . +The default is 64. +.TP +.I write_wakeup_threshold +This file +contains the number of bits of entropy below which we wake up +processes that do a +.BR select (2) +or +.BR poll (2) +for write access to +.IR /dev/random . +These values can be changed by writing to the files. +.TP +.IR uuid " and " boot_id +These read-only files +contain random strings like 6fd5a44b-35f4-4ad4-a9b9-6b9be13e1fe9. +The former is generated afresh for each read, the latter was +generated once. +.\" +.SS ioctl(2) interface +The following +.BR ioctl (2) +requests are defined on file descriptors connected to either \fI/dev/random\fP +or \fI/dev/urandom\fP. +All requests performed will interact with the input +entropy pool impacting both \fI/dev/random\fP and \fI/dev/urandom\fP. +The +.B CAP_SYS_ADMIN +capability is required for all requests except +.BR RNDGETENTCNT . +.TP +.B RNDGETENTCNT +Retrieve the entropy count of the input pool, the contents will be the same +as the +.I entropy_avail +file under proc. +The result will be stored in the int pointed to by the argument. +.TP +.B RNDADDTOENTCNT +Increment or decrement the entropy count of the input pool +by the value pointed to by the argument. +.TP +.B RNDGETPOOL +Removed in Linux 2.6.9. +.TP +.B RNDADDENTROPY +Add some additional entropy to the input pool, +incrementing the entropy count. +This differs from writing to \fI/dev/random\fP or \fI/dev/urandom\fP, +which only adds some +data but does not increment the entropy count. +The following structure is used: +.IP +.in +4n +.EX +struct rand_pool_info { + int entropy_count; + int buf_size; + __u32 buf[0]; +}; +.EE +.in +.IP +Here +.I entropy_count +is the value added to (or subtracted from) the entropy count, and +.I buf +is the buffer of size +.I buf_size +which gets added to the entropy pool. +.TP +.BR RNDZAPENTCNT ", " RNDCLEARPOOL +Zero the entropy count of all pools and add some system data (such as +wall clock) to the pools. +.SH FILES +.I /dev/random +.br +.I /dev/urandom +.SH NOTES +For an overview and comparison of the various interfaces that +can be used to obtain randomness, see +.BR random (7). +.SH BUGS +During early boot time, reads from +.I /dev/urandom +may return data prior to the entropy pool being initialized. +.\" .SH AUTHOR +.\" The kernel's random number generator was written by +.\" Theodore Ts'o (tytso@athena.mit.edu). +.SH SEE ALSO +.BR mknod (1), +.BR getrandom (2), +.BR random (7) +.PP +RFC\ 1750, "Randomness Recommendations for Security" diff --git a/man4/rtc.4 b/man4/rtc.4 new file mode 100644 index 000000000..fd93c3970 --- /dev/null +++ b/man4/rtc.4 @@ -0,0 +1,327 @@ +.\" rtc.4 +.\" Copyright 2002 Urs Thuermann (urs@isnogud.escape.de) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" $Id: rtc.4,v 1.4 2005/12/05 17:19:49 urs Exp $ +.\" +.\" 2006-02-08 Various additions by mtk +.\" 2006-11-26 cleanup, cover the generic rtc framework; David Brownell +.\" +.TH RTC 4 2021-03-22 "Linux man-pages (unreleased)" +.SH NAME +rtc \- real-time clock +.SH SYNOPSIS +.nf +#include <linux/rtc.h> +.PP +.BI "int ioctl(" fd ", RTC_" request ", " param ");" +.fi +.SH DESCRIPTION +This is the interface to drivers for real-time clocks (RTCs). +.PP +Most computers have one or more hardware clocks which record the +current "wall clock" time. +These are called "Real Time Clocks" (RTCs). +One of these usually has battery backup power so that it tracks the time +even while the computer is turned off. +RTCs often provide alarms and other interrupts. +.PP +All i386 PCs, and ACPI-based systems, have an RTC that is compatible with +the Motorola MC146818 chip on the original PC/AT. +Today such an RTC is usually integrated into the mainboard's chipset +(south bridge), and uses a replaceable coin-sized backup battery. +.PP +Non-PC systems, such as embedded systems built around system-on-chip +processors, use other implementations. +They usually won't offer the same functionality as the RTC from a PC/AT. +.SS RTC vs system clock +RTCs should not be confused with the system clock, which is +a software clock maintained by the kernel and used to implement +.BR gettimeofday (2) +and +.BR time (2), +as well as setting timestamps on files, and so on. +The system clock reports seconds and microseconds since a start point, +defined to be the POSIX Epoch: 1970-01-01 00:00:00 +0000 (UTC). +(One common implementation counts timer interrupts, once +per "jiffy", at a frequency of 100, 250, or 1000 Hz.) +That is, it is supposed to report wall clock time, which RTCs also do. +.PP +A key difference between an RTC and the system clock is that RTCs +run even when the system is in a low power state (including "off"), +and the system clock can't. +Until it is initialized, the system clock can only report time since +system boot ... not since the POSIX Epoch. +So at boot time, and after resuming from a system low power state, the +system clock will often be set to the current wall clock time using an RTC. +Systems without an RTC need to set the system clock using another clock, +maybe across the network or by entering that data manually. +.SS RTC functionality +RTCs can be read and written with +.BR hwclock (8), +or directly with the +.BR ioctl (2) +requests listed below. +.PP +Besides tracking the date and time, many RTCs can also generate +interrupts +.IP * 3 +on every clock update (i.e., once per second); +.IP * +at periodic intervals with a frequency that can be set to +any power-of-2 multiple in the range 2 Hz to 8192 Hz; +.IP * +on reaching a previously specified alarm time. +.PP +Each of those interrupt sources can be enabled or disabled separately. +On many systems, the alarm interrupt can be configured as a system wakeup +event, which can resume the system from a low power state such as +Suspend-to-RAM (STR, called S3 in ACPI systems), +Hibernation (called S4 in ACPI systems), +or even "off" (called S5 in ACPI systems). +On some systems, the battery backed RTC can't issue +interrupts, but another one can. +.PP +The +.I /dev/rtc +(or +.IR /dev/rtc0 , +.IR /dev/rtc1 , +etc.) +device can be opened only once (until it is closed) and it is read-only. +On +.BR read (2) +and +.BR select (2) +the calling process is blocked until the next interrupt from that RTC +is received. +Following the interrupt, the process can read a long integer, of which +the least significant byte contains a bit mask encoding +the types of interrupt that occurred, +while the remaining 3 bytes contain the number of interrupts since the +last +.BR read (2). +.SS ioctl(2) interface +The following +.BR ioctl (2) +requests are defined on file descriptors connected to RTC devices: +.TP +.B RTC_RD_TIME +Returns this RTC's time in the following structure: +.IP +.in +4n +.EX +struct rtc_time { + int tm_sec; + int tm_min; + int tm_hour; + int tm_mday; + int tm_mon; + int tm_year; + int tm_wday; /* unused */ + int tm_yday; /* unused */ + int tm_isdst; /* unused */ +}; +.EE +.in +.IP +The fields in this structure have the same meaning and ranges as for the +.I tm +structure described in +.BR gmtime (3). +A pointer to this structure should be passed as the third +.BR ioctl (2) +argument. +.TP +.B RTC_SET_TIME +Sets this RTC's time to the time specified by the +.I rtc_time +structure pointed to by the third +.BR ioctl (2) +argument. +To set the +RTC's time the process must be privileged (i.e., have the +.B CAP_SYS_TIME +capability). +.TP +.BR RTC_ALM_READ ", " RTC_ALM_SET +Read and set the alarm time, for RTCs that support alarms. +The alarm interrupt must be separately enabled or disabled using the +.BR RTC_AIE_ON ", " RTC_AIE_OFF +requests. +The third +.BR ioctl (2) +argument is a pointer to an +.I rtc_time +structure. +Only the +.IR tm_sec , +.IR tm_min , +and +.I tm_hour +fields of this structure are used. +.TP +.BR RTC_IRQP_READ ", " RTC_IRQP_SET +Read and set the frequency for periodic interrupts, +for RTCs that support periodic interrupts. +The periodic interrupt must be separately enabled or disabled using the +.BR RTC_PIE_ON ", " RTC_PIE_OFF +requests. +The third +.BR ioctl (2) +argument is an +.I "unsigned long\ *" +or an +.IR "unsigned long" , +respectively. +The value is the frequency in interrupts per second. +The set of allowable frequencies is the multiples of two +in the range 2 to 8192. +Only a privileged process (i.e., one having the +.B CAP_SYS_RESOURCE +capability) can set frequencies above the value specified in +.IR /proc/sys/dev/rtc/max\-user\-freq . +(This file contains the value 64 by default.) +.TP +.BR RTC_AIE_ON ", " RTC_AIE_OFF +Enable or disable the alarm interrupt, for RTCs that support alarms. +The third +.BR ioctl (2) +argument is ignored. +.TP +.BR RTC_UIE_ON ", " RTC_UIE_OFF +Enable or disable the interrupt on every clock update, +for RTCs that support this once-per-second interrupt. +The third +.BR ioctl (2) +argument is ignored. +.TP +.BR RTC_PIE_ON ", " RTC_PIE_OFF +Enable or disable the periodic interrupt, +for RTCs that support these periodic interrupts. +The third +.BR ioctl (2) +argument is ignored. +Only a privileged process (i.e., one having the +.B CAP_SYS_RESOURCE +capability) can enable the periodic interrupt if the frequency is +currently set above the value specified in +.IR /proc/sys/dev/rtc/max\-user\-freq . +.TP +.BR RTC_EPOCH_READ ", " RTC_EPOCH_SET +Many RTCs encode the year in an 8-bit register which is either +interpreted as an 8-bit binary number or as a BCD number. +In both cases, +the number is interpreted relative to this RTC's Epoch. +The RTC's Epoch is +initialized to 1900 on most systems but on Alpha and MIPS it might +also be initialized to 1952, 1980, or 2000, depending on the value of +an RTC register for the year. +With some RTCs, +these operations can be used to read or to set the RTC's Epoch, +respectively. +The third +.BR ioctl (2) +argument is an +.I "unsigned long\ *" +or an +.IR "unsigned long" , +respectively, and the value returned (or assigned) is the Epoch. +To set the RTC's Epoch the process must be privileged (i.e., have the +.B CAP_SYS_TIME +capability). +.TP +.BR RTC_WKALM_RD ", " RTC_WKALM_SET +Some RTCs support a more powerful alarm interface, using these ioctls +to read or write the RTC's alarm time (respectively) with this structure: +.PP +.RS +.in +4n +.EX +struct rtc_wkalrm { + unsigned char enabled; + unsigned char pending; + struct rtc_time time; +}; +.EE +.in +.RE +.IP +The +.I enabled +flag is used to enable or disable the alarm interrupt, +or to read its current status; when using these calls, +.BR RTC_AIE_ON " and " RTC_AIE_OFF +are not used. +The +.I pending +flag is used by +.B RTC_WKALM_RD +to report a pending interrupt +(so it's mostly useless on Linux, except when talking +to the RTC managed by EFI firmware). +The +.I time +field is as used with +.B RTC_ALM_READ +and +.B RTC_ALM_SET +except that the +.IR tm_mday , +.IR tm_mon , +and +.I tm_year +fields are also valid. +A pointer to this structure should be passed as the third +.BR ioctl (2) +argument. +.SH FILES +.TP +.IR /dev/rtc ", " /dev/rtc0 ", " /dev/rtc1 ", etc." +RTC special character device files. +.TP +.I /proc/driver/rtc +status of the (first) RTC. +.SH NOTES +When the kernel's system time is synchronized with an external +reference using +.BR adjtimex (2) +it will update a designated RTC periodically every 11 minutes. +To do so, the kernel has to briefly turn off periodic interrupts; +this might affect programs using that RTC. +.PP +An RTC's Epoch has nothing to do with the POSIX Epoch which is +used only for the system clock. +.PP +If the year according to the RTC's Epoch and the year register is +less than 1970 it is assumed to be 100 years later, that is, between 2000 +and 2069. +.PP +Some RTCs support "wildcard" values in alarm fields, to support +scenarios like periodic alarms at fifteen minutes after every hour, +or on the first day of each month. +Such usage is nonportable; +portable user-space code expects only a single alarm interrupt, and +will either disable or reinitialize the alarm after receiving it. +.PP +Some RTCs support periodic interrupts with periods that are multiples +of a second rather than fractions of a second; +multiple alarms; +programmable output clock signals; +nonvolatile memory; +and other hardware +capabilities that are not currently exposed by this API. +.SH SEE ALSO +.BR date (1), +.BR adjtimex (2), +.BR gettimeofday (2), +.BR settimeofday (2), +.BR stime (2), +.BR time (2), +.BR gmtime (3), +.BR time (7), +.BR hwclock (8) +.PP +.I Documentation/rtc.txt +in the Linux kernel source tree diff --git a/man4/sd.4 b/man4/sd.4 new file mode 100644 index 000000000..37e404e83 --- /dev/null +++ b/man4/sd.4 @@ -0,0 +1,117 @@ +.\" sd.4 +.\" Copyright 1992 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH SD 4 2017-09-15 "Linux man-pages (unreleased)" +.SH NAME +sd \- driver for SCSI disk drives +.SH SYNOPSIS +.nf +.BR "#include <linux/hdreg.h> " "/* for HDIO_GETGEO */" +.BR "#include <linux/fs.h> " "/* for BLKGETSIZE and BLKRRPART */" +.fi +.SH CONFIGURATION +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. +.PP +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: +.IP +3 +partition 0 is the whole drive +.IP +partitions 1\(en4 are the DOS "primary" partitions +.IP +partitions 5\(en8 are the DOS "extended" (or "logical") partitions +.PP +For example, +.I /dev/sda +will have major 8, minor 0, and will refer to all of the first SCSI drive +in the system; and +.I /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. +.PP +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 +.B HDIO_GETGEO +Returns the BIOS disk parameters in the following structure: +.PP +.in +4n +.EX +struct hd_geometry { + unsigned char heads; + unsigned char sectors; + unsigned short cylinders; + unsigned long start; +}; +.EE +.in +.IP +A pointer to this structure is passed as the +.BR ioctl (2) +parameter. +.IP +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. +.TP +.B BLKGETSIZE +Returns the device size in sectors. +The +.BR ioctl (2) +parameter should be a pointer to a +.IR long . +.TP +.B BLKRRPART +Forces a reread of the SCSI disk partition tables. +No parameter is needed. +.IP +The SCSI +.BR ioctl (2) +operations are also supported. +If the +.BR ioctl (2) +parameter is required, and it is NULL, then +.BR ioctl (2) +fails with the error +.BR EINVAL . +.SH FILES +.TP +.I /dev/sd[a\-h] +the whole device +.TP +.I /dev/sd[a\-h][0\-8] +individual block partitions +.\".SH SEE ALSO +.\".BR scsi (4) diff --git a/man4/sk98lin.4 b/man4/sk98lin.4 new file mode 100644 index 000000000..13ba55841 --- /dev/null +++ b/man4/sk98lin.4 @@ -0,0 +1,581 @@ +.\" (C)Copyright 1999-2003 Marvell(R) -- linux@syskonnect.de +.\" sk98lin.4 1.1 2003/12/17 10:03:18 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" This manpage can be viewed using `groff -Tascii -man sk98lin.4 | less` +.\" +.TH SK98LIN 4 2020-08-13 "Linux man-pages (unreleased)" +.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 +.ad l +.hy 0 +.BR Note : +This obsolete driver was removed from the kernel in version 2.6.26. +.PP +.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. +.PP +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: +.PP +.in +4n +.EX +insmod sk98lin.o AutoNeg_A=On,Off +.EE +.in +.PP +After +.B sk98lin +is bound to one or more adapter cards and the +.I /proc +filesystem is mounted on your system, a dedicated statistics file +will be created in the folder +.I /proc/net/sk98lin +for all ports of the installed network adapter cards. +Those files are named +.IR eth[x] , +where +.I x +is the number of the interface that has been assigned to a +dedicated port by the system. +.PP +If loading is finished, any desired IP address can be +assigned to the respective +.I 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. +.PP +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: +.PP +.in +4n +.EX +ifconfig eth0 10.1.1.1 +ifconfig eth0 mtu 9000 +.EE +.in +.PP +Those two commands might even be combined into one: +.PP +.in +4n +.EX +ifconfig eth0 10.1.1.1 mtu 9000 +.EE +.in +.PP +Note that large frames can be used only if permitted by +your network infrastructure. +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. +.PP +Switching back to the standard Ethernet frame size can be done by using the +.BR ifconfig (8) +command again: +.PP +.in +4n +.EX +ifconfig eth0 mtu 1500 +.EE +.in +.PP +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 available only after installation of open source modules +which can be found on the Internet: +.PP +.IR VLAN \c +: +.UR http://www.candelatech.com\:/\(tigreear\:/vlan.html +.UE +.br +.I Link +.IR Aggregation \c +: +.UR http://www.st.rim.or.jp\:/\(tiyumo +.UE +.PP +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. +.SS 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 valid only for Yukon copper adapters. +Possible values are: +.IR 10 , +.IR 100 , +.IR 1000 , +or +.IR Auto ; +.I 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 valid only for Yukon copper adapters. +Possible values are: +.IR 10 , +.IR 100 , +.IR 1000 , +or +.IR Auto ; +.I 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 ; +.I On +is the default. +The +.I 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 ; +.I On +is the default. +The +.I 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 ; +.I Both +is the default. +This parameter is relevant only 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 +.I Full +and +.I 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 ; +.I Both +is the default. +This parameter is relevant only 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 +.I Full +and +.I 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 ; +.I SymOrRem +is the default. +The different modes have the following meaning: +.RS +.TP +.IR Sym " = Symmetric" +Both link partners are allowed to send PAUSE frames. +.TP +.IR SymOrRem " = SymmetricOrRemote" +Both or only remote partner are allowed to send PAUSE frames. +.TP +.IR LocSend " = LocalSend" +Only local link partner is allowed to send PAUSE frames. +.TP +.IR None " = None" +No link partner is allowed to send PAUSE frames. +.RE +.IP +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 ; +.I SymOrRem +is the default. +The different modes have the following meaning: +.RS +.TP +.IR Sym " = Symmetric" +Both link partners are allowed to send PAUSE frames. +.TP +.IR SymOrRem " = SymmetricOrRemote" +Both or only remote partner are allowed to send PAUSE frames. +.TP +.IR LocSend " = LocalSend" +Only local link partner is allowed to send PAUSE frames. +.TP +.IR None " = None" +No link partner is allowed to send PAUSE frames. +.RE +.IP +Note that this parameter is ignored if AutoNeg_B is set to +.IR Off . +.TP +.BI Role_A= i,j,... +This parameter is valid only 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 ; +.I 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 valid only 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 ; +.I 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: +.IP +.TS +lb lb lb lb lb lb +l l l l l l. +ConType DupCap AutoNeg FlowCtrl Role Speed +\fIAuto\fP Both On SymOrRem Auto Auto +\fI100FD\fP Full Off None Auto 100 +\fI100HD\fP Half Off None Auto 100 +\fI10FD\fP Full Off None Auto 10 +\fI10HD\fP Half Off None Auto 10 +.TE +.IP +Stating any other port parameter together with this +.I 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 +.I IntsPerSec +parameter, which is explained later below. +Possible moderation modes are: +.IR None , +.IR Static , +or +.IR Dynamic ; +.I None +is the default. +The different modes have the following meaning: +.IP +.I 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. +.IP +.I 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 +.I 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. +.IP +.I 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\(emat a later time\(emthe CPU utilization decreases +again (or if the network load is negligible), the interrupt +moderation will automatically be disabled. +.IP +Interrupt moderation should be used when the driver has to +handle one or more interfaces with a high network load, +which\(emas a consequence\(emleads also to a high CPU utilization. +When moderation is applied in such high network load situations, +CPU load might be reduced by 20\(en30% on slow computers. +.IP +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 +.I 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. +.IP +This parameter is used only if either static or dynamic interrupt moderation +is enabled on a network adapter card. +This parameter is ignored if no moderation is applied. +.IP +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: +.I A +or +.IR B ; +.I 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 ; +.I CheckLinkState +is the default. +The different modes have the following meaning: +.IP +.I 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. +.IP +.I 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). +.IP +.I 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 to be used only if Gigabit Ethernet +switches are installed on the network that have been +configured to use the Spanning Tree protocol. +.IP +.I 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 +.I 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. +.IP +Note that RLMT modes +.I CheckLocalPort +and +.I 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 +.I /proc/net/sk98lin/eth[x] +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 +.I /usr/src/linux/Documentation/networking/sk98lin.txt +This is the +.I README +file of the +.I 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 \(em rroesler@syskonnect.de +.\" .br +.\" Mirko Lindner \(em mlindner@syskonnect.de +.SH SEE ALSO +.BR ifconfig (8), +.BR insmod (8), +.BR modprobe (8) diff --git a/man4/smartpqi.4 b/man4/smartpqi.4 new file mode 100644 index 000000000..391f930ba --- /dev/null +++ b/man4/smartpqi.4 @@ -0,0 +1,325 @@ +.\" Copyright (C) 2019, Microchip Technology Inc. and its subsidiaries +.\" Copyright (C) 2016-2018, Microsemi Corporation +.\" Copyright (C) 2016, PMC-Sierra, Inc. +.\" Written by Kevin Barnett <kevin.barnett@microsemi.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-only +.TH SMARTPQI 4 2021-03-22 "Linux man-pages (unreleased)" +.SH NAME +smartpqi \- Microsemi Smart Family SCSI driver +.SH SYNOPSIS +.SY "modprobe smartpqi" +.RB [ disable_device_id_wildcards= { 0 | 1 }] +.RB [ disable_heartbeat= { 0 | 1 }] +.RB [ disable_ctrl_shutdown= { 0 | 1 }] +.RB [ lockup_action= { none | reboot | panic }] +.RB [ expose_ld_first= { 0 | 1 }] +.RB [ hide_vsep= { 0 | 1 }] +.YS +.SH DESCRIPTION +.B smartpqi +is a SCSI driver for Microsemi Smart Family controllers. +.SS Supported \f[BI]ioctl\fP\/() operations +For compatibility with applications written for the +.BR cciss (4) +and +.BR hpsa (4) +drivers, many, but not all of the +.BR ioctl (2) +operations supported by the +.B hpsa +driver are also supported by the +.B smartpqi +driver. +The data structures used by these operations +are described in the Linux kernel source file +.IR include/linux/cciss_ioctl.h . +.TP +.BR CCISS_DEREGDISK ", " CCISS_REGNEWDISK ", " CCISS_REGNEWD +These operations +all do exactly the same thing, which is to cause the driver to re-scan +for new devices. +This does exactly the same thing as writing to the +.BR smartpqi -specific +host +.I rescan +attribute. +.TP +.B CCISS_GETPCIINFO +This operation returns the PCI domain, bus, +device, and function and "board ID" (PCI subsystem ID). +.TP +.B CCISS_GETDRIVVER +This operation returns the driver version in four bytes, encoded as: +.IP +.in +4n +.EX +(major_version << 28) | (minor_version << 24) | + (release << 16) | revision +.EE +.in +.TP +.B CCISS_PASSTHRU +Allows BMIC and CISS commands to be passed through to the controller. +.SS Boot options +.TP +.BR disable_device_id_wildcards= { 0 | 1 } +Disables support for device ID wildcards. +The default value is 0. +.TP +.BR disable_heartbeat= { 0 | 1 } +Disables support for the controller's heartbeat check. +This parameter is used for debugging purposes. +The default value is 0, leaving the controller's heartbeat check active. +.TP +.BR disable_ctrl_shutdown= { 0 | 1 } +Disables support for shutting down the controller in the +event of a controller lockup. +The default value is 0. +.TP +.BR lockup_action= { none | reboot | panic } +Specifies the action the driver takes when a controller +lockup is detected. +The default action is +.BR none . +.TS +l l +--- +l l. +parameter action +\fBnone\fP take controller offline only +\fBreboot\fP reboot the system +\fBpanic\fP panic the system +.TE +.TP +.BR expose_ld_first= { 0 | 1 } +This option enables support for exposing logical devices to +the operating system before physical devices. +The default value is 0. +.TP +.BR hide_vsep= { 0 | 1 } +This option enables disabling exposure of the virtual SEP to the host. +This is usually associated with direct attached drives. +The default value is 0. +.SH FILES +.SS Device nodes +Logical drives are accessed via the SCSI disk driver +.RI ( sd ), +tape drives via the SCSI tape driver +.RI ( st ), +and the RAID controller via the SCSI generic driver +.RI ( sg ), +with device nodes named +.IR /dev/sd *, +.IR /dev/st *, +and +.IR /dev/sg *, +respectively. +.SS SmartPQI-specific host attribute files in \f[BI]/sys\fP +.TP +.IR /sys/class/scsi_host/host * /rescan +The host +.I rescan +attribute is a write-only attribute. +Writing to this attribute will cause the driver to scan for new, +changed, or removed devices (e.g., hot-plugged tape drives, or newly +configured or deleted logical drives) and notify the SCSI mid-layer of +any changes detected. +Usually this action is triggered automatically by configuration +changes, so the user should not normally have to write to this file. +Doing so may be useful when hot-plugging devices such as tape drives or +entire storage boxes containing pre-configured logical drives. +.TP +.IR /sys/class/scsi_host/host * /version +The host +.I version +attribute is a read-only attribute. +This attribute contains the driver version and the controller firmware +version. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_host/host1/version +driver: 1.1.2\-126 +firmware: 1.29\-112 +.EE +.in +.TP +.IR /sys/class/scsi_host/host * /lockup_action +The host +.I lockup_action +attribute is a read/write attribute. +This attribute will cause the driver to perform a specific action in the +unlikely event that a controller lockup has been detected. +See +.B OPTIONS +above +for an explanation of the +.I lockup_action +values. +.TP +.I /sys/class/scsi_host/host*/driver_version +The +.I driver_version +attribute is read-only. +This attribute contains the smartpqi driver version. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_host/host1/driver_version +1.1.2\-126 +.EE +.in +.TP +.I /sys/class/scsi_host/host*/firmware_version +The +.I firmware_version +attribute is read-only. +This attribute contains the controller firmware version. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_host/host1/firmware_version +1.29\-112 +.EE +.in +.TP +.I /sys/class/scsi_host/host*/model +The +.I model +attribute is read-only. +This attribute contains the product identification string of the controller. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_host/host1/model +1100\-16i +.EE +.in +.TP +.I /sys/class/scsi_host/host*/serial_number +The +.I serial_number +attribute is read-only. +This attribute contains the unique identification number of the controller. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_host/host1/serial_number +6A316373777 +.EE +.in +.TP +.I /sys/class/scsi_host/host*/vendor +The +.I vendor +attribute is read-only. +This attribute contains the vendor identification string of the controller. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_host/host1/vendor +Adaptec +.EE +.in +.SS SmartPQI-specific disk attribute files in \f[BI]/sys\fP +In the file specifications below, +.I c +stands for the number of the appropriate SCSI controller, +.I b +is the bus number, +.I t +the target number, and +.I l +is the logical unit number (LUN). +.TP +.IR /sys/class/scsi_disk/ c : b : t : l /device/raid_level +The +.I raid_level +attribute is read-only. +This attribute contains the RAID level of each logical drive. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_disk/4:0:0:0/device/raid_level +RAID 0 +.EE +.in +.TP +.IR /sys/class/scsi_disk/c : b : t : l/device/sas_address +The +.I sas_address +attribute is read-only. +This attribute contains the unique identifier of the disk. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_disk/1:0:3:0/device/sas_address +0x5001173d028543a2 +.EE +.in +.TP +.IR /sys/class/scsi_disk/c : b : t : l/device/ssd_smart_path_enabled +The +.I ssd_smart_path_enabled +attribute is read-only. +This attribute is for ioaccel-enabled volumes. +(Ioaccel is an alternative driver submission path that allows the +driver to send I/O requests directly to backend SCSI devices, +bypassing the controller firmware. +This results in an increase in performance. +This method is used for HBA disks and for logical volumes comprised of SSDs.) +Contains 1 if ioaccel is enabled for the volume and 0 otherwise. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_disk/1:0:3:0/device/ssd_smart_path_enabled +0 +.EE +.in +.SH VERSIONS +The +.B smartpqi +driver was added in Linux 4.9. +.SH NOTES +.SS Configuration +To configure a Microsemi Smart Family controller, +refer to the User Guide for the controller, +which can be found by searching for the specific controller at +.UR https://storage.microsemi.com/ +.UE . +.SH SEE ALSO +.BR cciss (4), +.BR hpsa (4), +.BR sd (4), +.BR st (4) +.PP +.I Documentation/ABI/testing/sysfs\-bus\-pci\-devices\-cciss +in the Linux kernel source tree. diff --git a/man4/st.4 b/man4/st.4 new file mode 100644 index 000000000..add90feb9 --- /dev/null +++ b/man4/st.4 @@ -0,0 +1,947 @@ +.\" Copyright 1995 Robert K. Nichols (Robert.K.Nichols@att.com) +.\" Copyright 1999-2005 Kai Mäkisara (Kai.Makisara@kolumbus.fi) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.TH ST 4 2020-04-11 "Linux man-pages (unreleased)" +.SH NAME +st \- SCSI tape device +.SH SYNOPSIS +.nf +.B #include <sys/mtio.h> +.PP +.BI "int ioctl(int " fd ", int " request " [, (void *)" arg3 "]);" +.BI "int ioctl(int " fd ", MTIOCTOP, (struct mtop *)" mt_cmd ); +.BI "int ioctl(int " fd ", MTIOCGET, (struct mtget *)" mt_status ); +.BI "int ioctl(int " fd ", MTIOCPOS, (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 lowermost five bits +in the minor numbers are assigned sequentially in the order of +detection. +In the 2.6 kernel, the bits above the eight lowermost bits are +concatenated to the five lowermost bits to form the tape number. +The minor numbers can be grouped into +two sets of four numbers: the principal (auto-rewind) minor device numbers, +.IR n , +and the \(lqno-rewind\(rq device numbers, +.RI ( n " + 128)." +Devices opened using the principal device number will be sent a +.B REWIND +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: +.PP +.in +4n +.EX +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 +.EE +.in +.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 32-bit architectures and +256\ kB for 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 +.BR ioctl (2) +calls and remain in effect when the device is closed and reopened. +Setting the options affects both the auto-rewind and the nonrewind +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 +.BR ioctl (2). +The tape +location is preserved within each partition across partition changes. +The partition used for subsequent tape operations is +selected with an +.BR ioctl (2). +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 +.BR ioctl (2) +that can format a tape with either one or two partitions. +.PP +Device +.I /dev/tape +is usually created as a hard or soft link to the default tape device +on the system. +.PP +Starting from kernel 2.6.2, the driver exports in the sysfs directory +.I /sys/class/scsi_tape +the attached devices and some parameters assigned to the devices. +.SS 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 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, an error is returned. +.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 +In the 2.6 kernel, the driver tries to use direct transfers between the user +buffer and the device. +If this is not possible, the driver's internal buffer +is used. +The reasons for not using direct transfers include improper alignment +of the user buffer (default is 512 bytes but this can be changed by the HBA +driver), one or more pages of the user buffer not reachable by the +SCSI adapter, and so on. +.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. +.SS Ioctls +The driver supports three +.BR ioctl (2) +requests. +Requests not recognized by the +.B st +driver are passed to the +.B SCSI +driver. +The definitions below are from +.IR /usr/include/linux/mtio.h : +.SS MTIOCTOP \(em perform a tape operation +This request takes an argument of type +.IR "(struct mtop\ *)" . +Not all drives support all operations. +The driver returns an +.B EIO +error if the drive rejects an operation. +.PP +.in +4n +.EX +/* Structure for MTIOCTOP \- mag tape op command: */ +struct mtop { + short mt_op; /* operations defined below */ + int mt_count; /* how many of them */ +}; +.EE +.in +.PP +Magnetic tape operations for normal tape use: +.TP +.B MTBSF +Backward space over +.I mt_count +filemarks. +.TP +.B MTBSFM +Backward space over +.I mt_count +filemarks. +Reposition the tape to the EOT side of the last filemark. +.TP +.B MTBSR +Backward space over +.I mt_count +records (tape blocks). +.TP +.B MTBSS +Backward space over +.I mt_count +setmarks. +.TP +.B MTCOMPRESSION +Enable compression of tape data within the drive if +.I mt_count +is nonzero and disable compression if +.I mt_count +is zero. +This command uses the MODE page 15 supported by most DATs. +.TP +.B MTEOM +Go to the end of the recorded media (for appending files). +.TP +.B MTERASE +Erase tape. +With 2.6 kernel, short erase (mark tape empty) is performed if the +argument is zero. +Otherwise, long erase (erase all) is done. +.TP +.B MTFSF +Forward space over +.I mt_count +filemarks. +.TP +.B MTFSFM +Forward space over +.I mt_count +filemarks. +Reposition the tape to the BOT side of the last filemark. +.TP +.B MTFSR +Forward space over +.I mt_count +records (tape blocks). +.TP +.B MTFSS +Forward space over +.I mt_count +setmarks. +.TP +.B MTLOAD +Execute the SCSI load command. +A special case is available for some HP +autoloaders. +If +.I mt_count +is the constant +.B MT_ST_HPLOADER_OFFSET +plus a number, the number is +sent to the drive to control the autoloader. +.TP +.B MTLOCK +Lock the tape drive door. +.TP +.B MTMKPART +Format the tape into one or two partitions. +If +.I mt_count +is positive, it gives the size of partition 1 and partition +0 contains the rest of the tape. +If +.I mt_count +is zero, the tape is formatted into one partition. +From kernel version 4.6, +.\" commit 8038e6456a3e6f5c4759e0d73c4f9165b90c93e7 +a negative +.I mt_count +specifies the size of partition 0 and +the rest of the tape contains partition 1. +The physical ordering of partitions depends on the drive. +This command is not allowed for a drive unless the partition support +is enabled for the drive (see +.B MT_ST_CAN_PARTITIONS +below). +.TP +.B MTNOP +No op\(emflushes the driver's buffer as a side effect. +Should be used before reading status with +.BR MTIOCGET . +.TP +.B MTOFFL +Rewind and put the drive off line. +.TP +.B MTRESET +Reset drive. +.TP +.B MTRETEN +Re-tension tape. +.TP +.B MTREW +Rewind. +.TP +.B MTSEEK +Seek to the tape block number specified in +.IR mt_count . +This operation requires either a SCSI-2 drive that supports the +.B LOCATE +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 +.B MTIOCPOS +if device-specific addresses are used. +.TP +.B MTSETBLK +Set the drive's block length to the value specified in +.IR mt_count . +A block length of zero sets the drive to variable block size mode. +.TP +.B MTSETDENSITY +Set the tape density to the code in +.IR mt_count . +The density codes supported by a drive can be found from the drive +documentation. +.TP +.B MTSETPART +The active partition is switched to +.IR 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 +.B MT_ST_CAN_PARTITIONS +below). +.TP +.B MTUNLOAD +Execute the SCSI unload command (does not eject the tape). +.TP +.B MTUNLOCK +Unlock the tape drive door. +.TP +.B MTWEOF +Write +.I mt_count +filemarks. +.TP +.B MTWSM +Write +.I mt_count +setmarks. +.PP +Magnetic tape operations for setting of device options (by the superuser): +.TP +.B MTSETDRVBUFFER +Set various drive and driver options according to bits encoded in +.IR mt_count . +These consist of the drive's buffering mode, a set of Boolean driver +options, the buffer write threshold, defaults for the block size and +density, and timeouts (only in kernels 2.1 and later). +A single operation can affect only one item in the list below (the +Booleans counted as one item.) +.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 +.B GOOD +status on write commands until the data +blocks are actually written to the medium. +.IP 1 +The drive may report +.B GOOD +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 +.B GOOD +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. +.RE +.IP +To control the write threshold the value in +.I mt_count +must include the constant +.B MT_ST_WRITE_THRESHOLD +bitwise 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 +DESCRIPTION, above). +.IP +To set and clear the Boolean options +the value in +.I mt_count +must include one of the constants +.BR MT_ST_BOOLEANS , +.BR MT_ST_SETBOOLEANS , +.BR MT_ST_CLEARBOOLEANS , +or +.B MT_ST_DEFBOOLEANS +bitwise ORed with +whatever combination of the following options is desired. +Using +.B MT_ST_BOOLEANS +the options can be set to the values +defined in the corresponding bits. +With +.B MT_ST_SETBOOLEANS +the options can be selectively set and with +.B MT_ST_DEFBOOLEANS +selectively cleared. +.IP +The default options for a tape device are set with +.BR MT_ST_DEFBOOLEANS . +A nonactive 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: +.RS +.TP +.BR MT_ST_BUFFER_WRITES " (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 multivolume archives. +.TP +.BR MT_ST_ASYNC_WRITES " (Default: true)" +When this option 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 multivolume archives. +.TP +.BR MT_ST_READ_AHEAD " (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. +.TP +.BR MT_ST_TWO_FM " (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. +.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. +.TP +.BR MT_ST_DEBUGGING " (Default: false)" +This option turns on various debugging messages from the driver +(effective only if the driver was compiled with +.B DEBUG +defined nonzero). +.TP +.BR MT_ST_FAST_EOM " (Default: false)" +This option causes the +.B MTEOM +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 +.B MTIOCGET +request. +If +.B MT_ST_FAST_EOM +is false, the driver will respond to an +.B MTEOM +request by forward spacing over files. +.TP +.BR MT_ST_AUTO_LOCK " (Default: false)" +When this option is true, the drive door is locked when the device file is +opened and unlocked when it is closed. +.TP +.BR MT_ST_DEF_WRITES " (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. +.TP +.BR MT_ST_CAN_BSR " (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 backward 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. +With 2.6 kernel, the +default is true for drives supporting SCSI-3. +.TP +.BR MT_ST_NO_BLKLIMS " (Default: false)" +Some drives don't accept the +.B "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. +.TP +.BR MT_ST_CAN_PARTITIONS " (Default: false)" +This option enables support for several partitions within a +tape. +The option applies to all devices linked to a drive. +.TP +.BR MT_ST_SCSI2LOGICAL " (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 +.B MTSEEK +and +.B 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 support only the logical block addresses. +.TP +.BR MT_ST_SYSV " (Default: false)" +When this option is enabled, the tape devices use the System V +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 System V 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. +.TP +.BR MT_NO_WAIT " (Default: false)" +Enables immediate mode (i.e., don't wait for the command to finish) for some +commands (e.g., rewind). +.PP +An example: +.PP +.in +4n +.EX +struct mtop mt_cmd; +mt_cmd.mt_op = MTSETDRVBUFFER; +mt_cmd.mt_count = MT_ST_BOOLEANS | + MT_ST_BUFFER_WRITES | MT_ST_ASYNC_WRITES; +ioctl(fd, MTIOCTOP, mt_cmd); +.EE +.in +.RE +.IP "" +The default block size for a device can be set with +.B MT_ST_DEF_BLKSIZE +and the default density code can be set with +.BR MT_ST_DEFDENSITY . +The values for the parameters are or'ed +with the operation code. +.IP "" +With kernels 2.1.x and later, the timeout values can be set with the +subcommand +.B MT_ST_SET_TIMEOUT +ORed with the timeout in seconds. +The long timeout (used for rewinds and other commands +that may take a long time) can be set with +.BR MT_ST_SET_LONG_TIMEOUT . +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. +.IP "" +Starting from kernels 2.4.19 and 2.5.43, the driver supports a status +bit which indicates whether the drive requests cleaning. +The method used by the +drive to return cleaning information is set using the +.B MT_ST_SEL_CLN +subcommand. +If the value is zero, the cleaning +bit is always zero. +If the value is one, the TapeAlert data defined +in the SCSI-3 standard is used (not yet implemented). +Values 2\(en17 are +reserved. +If the lowest eight bits are >= 18, bits from the extended +sense data are used. +The bits 9\(en16 specify a mask to select the bits +to look at and the bits 17\(en23 specify the bit pattern to look for. +If the bit pattern is zero, one or more bits under the mask indicate +the cleaning request. +If the pattern is nonzero, the pattern must match +the masked sense data byte. +.SS MTIOCGET \(em get status +This request takes an argument of type +.IR "(struct mtget\ *)" . +.PP +.in +4n +.EX +/* structure for MTIOCGET \- 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; +}; +.EE +.in +.TP +\fImt_type\fP +The header file defines many values for +.IR mt_type , +but the current driver reports only the generic types +.B MT_ISSCSI1 +(Generic SCSI-1 tape) +and +.B MT_ISSCSI2 +(Generic SCSI-2 tape). +.TP +\fImt_resid\fP +contains the current tape partition number. +.TP +\fImt_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 +.BR MT_ST_BLKSIZE_SHIFT , +.BR MT_ST_BLKSIZE_MASK , +.BR MT_ST_DENSITY_SHIFT , +and +.BR MT_ST_DENSITY_MASK . +.TP +\fImt_gstat\fP +reports generic (device independent) status information. +The header file defines macros for testing these status bits: +.RS +.TP +\fBGMT_EOF\fP(\fIx\fP) +The tape is positioned just after a filemark +(always false after an +.B MTSEEK +operation). +.TP +\fBGMT_BOT\fP(\fIx\fP) +The tape is positioned at the beginning of the first file (always false +after an +.B MTSEEK +operation). +.TP +\fBGMT_EOT\fP(\fIx\fP) +A tape operation has reached the physical End Of Tape. +.TP +\fBGMT_SM\fP(\fIx\fP) +The tape is currently positioned at a setmark +(always false after an +.B MTSEEK +operation). +.TP +\fBGMT_EOD\fP(\fIx\fP) +The tape is positioned at the end of recorded data. +.TP +\fBGMT_WR_PROT\fP(\fIx\fP) +The drive is write-protected. +For some drives this can also mean that the drive does not support +writing on the current medium type. +.TP +\fBGMT_ONLINE\fP(\fIx\fP) +The last +.BR open (2) +found the drive with a tape in place and ready for operation. +.TP +\fBGMT_D_6250\fP(\fIx\fP) +.TQ +\fBGMT_D_1600\fP(\fIx\fP) +.TQ +\fBGMT_D_800\fP(\fIx\fP) +This \(lqgeneric\(rq status information reports the current +density setting for 9-track \(12" tape drives only. +.TP +\fBGMT_DR_OPEN\fP(\fIx\fP) +The drive does not have a tape in place. +.TP +\fBGMT_IM_REP_EN\fP(\fIx\fP) +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. +.TP +\fBGMT_CLN\fP(\fIx\fP) +The drive has requested cleaning. +Implemented in kernels since 2.4.19 and 2.5.43. +.RE +.TP +\fImt_erreg\fP +The only field defined in +.I mt_erreg +is the recovered error count in the low 16 bits (as defined by +.B MT_ST_SOFTERR_SHIFT +and +.BR MT_ST_SOFTERR_MASK ). +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). +.TP +\fImt_fileno\fP +reports the current file number (zero-based). +This value is set to \-1 when the file number is unknown (e.g., after +.B MTBSS +or +.BR MTSEEK ). +.TP +\fImt_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 +.BR MTBSF , +.BR MTBSS , +or +.BR MTSEEK ). +.SS MTIOCPOS \(em get tape position +This request takes an argument of type +.I "(struct mtpos\ *)" +and reports the drive's notion of the current tape block number, +which is not the same as +.I mt_blkno +returned by +.BR MTIOCGET . +This drive must be a SCSI-2 drive that supports the +.B "READ POSITION" +command (device-specific address) +or a Tandberg-compatible SCSI-1 drive (Tandberg, Archive +Viper, Wangtek, ... ). +.PP +.in +4n +.EX +/* structure for MTIOCPOS \- mag tape get position command */ +struct mtpos { + long mt_blkno; /* current block number */ +}; +.EE +.in +.SH RETURN VALUE +.TP +.B EACCES +An attempt was made to write or erase a write-protected tape. +(This error is not detected during +.BR open (2).) +.TP +.B EBUSY +The device is already in use or the driver was unable to allocate a +buffer. +.TP +.B EFAULT +The command parameters point to memory not belonging to the calling +process. +.TP +.B EINVAL +An +.BR ioctl (2) +had an invalid argument, or a requested block size was invalid. +.TP +.B EIO +The requested operation could not be completed. +.TP +.B ENOMEM +The byte count in +.BR read (2) +is smaller than the next physical block on the tape. +(Before 2.2.18 and 2.4.0 the extra bytes have been +.\" Precisely: Linux 2.6.0-test6 +silently ignored.) +.TP +.B ENOSPC +A write operation could not be completed because the tape reached +end-of-medium. +.TP +.B ENOSYS +Unknown +.BR ioctl (2). +.TP +.B ENXIO +During opening, the tape device does not exist. +.TP +.B EOVERFLOW +An attempt was made to read or write a variable-length block that is +larger than the driver's internal buffer. +.TP +.B EROFS +Open is attempted with +.B O_WRONLY +or +.B O_RDWR +when the tape in the drive is write-protected. +.SH FILES +.TP +.I /dev/st* +the auto-rewind SCSI tape devices +.TP +.I /dev/nst* +the nonrewind 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 NOTES +.IP 1. 4 +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 to use +these drives in variable-block mode also in Linux (i.e., use +.B MTSETBLK +or +.B MTSETDEFBLK +at system startup to set the mode), at least when +exchanging data with a 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. +.IP 2. +Many programs (e.g., +.BR tar (1)) +allow the user to specify the blocking +factor on the command line. +Note that this determines the physical block +size on tape only in variable-block mode. +.IP 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. +.IP 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. +.IP 5. +The driver's internal buffering allows good throughput in fixed-block +mode also with small +.BR read (2) +and +.BR write (2) +byte counts. +With direct transfers +this is not possible and may cause a surprise when moving to the 2.6 +kernel. +The solution is to tell the software to use larger transfers (often +telling it to use larger blocks). +If this is not possible, direct transfers can be disabled. +.SH SEE ALSO +.BR mt (1) +.PP +The file +.I drivers/scsi/README.st +or +.I Documentation/scsi/st.txt +(kernel >= 2.6) in the Linux kernel source tree contains +the most recent information about the driver and its configuration +possibilities diff --git a/man4/tty.4 b/man4/tty.4 new file mode 100644 index 000000000..f2d21ab74 --- /dev/null +++ b/man4/tty.4 @@ -0,0 +1,67 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2003-04-07 by Michael Kerrisk +.\" +.TH TTY 4 2019-03-06 "Linux man-pages (unreleased)" +.SH NAME +tty \- controlling terminal +.SH DESCRIPTION +The file +.I /dev/tty +is a character file with major number 5 and +minor number 0, usually with mode 0666 and ownership root:tty. +It is a synonym for the controlling terminal of a process, if any. +.PP +In addition to the +.BR ioctl (2) +requests supported by the device that +.B tty +refers to, the +.BR ioctl (2) +request +.B TIOCNOTTY +is supported. +.SS TIOCNOTTY +Detach the calling process from its controlling terminal. +.PP +If the process is the session leader, +then +.B SIGHUP +and +.B SIGCONT +signals are sent to the foreground process group +and all processes in the current session lose their controlling tty. +.PP +This +.BR ioctl (2) +call works only on file descriptors connected +to +.IR /dev/tty . +It is used by daemon processes when they are invoked +by a user at a terminal. +The process attempts to open +.IR /dev/tty . +If the open succeeds, it +detaches itself from the terminal by using +.BR TIOCNOTTY , +while if the +open fails, it is obviously not attached to a terminal and does not need +to detach itself. +.SH FILES +.I /dev/tty +.SH SEE ALSO +.BR chown (1), +.BR mknod (1), +.BR ioctl (2), +.BR ioctl_console (2), +.BR ioctl_tty (2), +.BR termios (3), +.BR ttyS (4), +.BR vcs (4), +.BR pty (7), +.BR agetty (8), +.BR mingetty (8) diff --git a/man4/ttyS.4 b/man4/ttyS.4 new file mode 100644 index 000000000..59e3e24cc --- /dev/null +++ b/man4/ttyS.4 @@ -0,0 +1,33 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 17:03:24 1993 by Rik Faith (faith@cs.unc.edu) +.TH TTYS 4 1992-12-19 "Linux man-pages (unreleased)" +.SH NAME +ttyS \- serial terminal lines +.SH DESCRIPTION +.B ttyS[0\-3] +are character devices for the serial terminal lines. +.PP +They are typically created by: +.PP +.in +4n +.EX +mknod \-m 660 /dev/ttyS0 c 4 64 # base address 0x3f8 +mknod \-m 660 /dev/ttyS1 c 4 65 # base address 0x2f8 +mknod \-m 660 /dev/ttyS2 c 4 66 # base address 0x3e8 +mknod \-m 660 /dev/ttyS3 c 4 67 # base address 0x2e8 +chown root:tty /dev/ttyS[0\-3] +.EE +.in +.SH FILES +.I /dev/ttyS[0\-3] +.SH SEE ALSO +.BR chown (1), +.BR mknod (1), +.BR tty (4), +.BR agetty (8), +.BR mingetty (8), +.BR setserial (8) diff --git a/man4/tty_ioctl.4 b/man4/tty_ioctl.4 new file mode 100644 index 000000000..fc4736ed0 --- /dev/null +++ b/man4/tty_ioctl.4 @@ -0,0 +1,2 @@ +.so man2/ioctl_tty.2 +.\" Link for old name of this page diff --git a/man4/urandom.4 b/man4/urandom.4 new file mode 100644 index 000000000..b95979fa8 --- /dev/null +++ b/man4/urandom.4 @@ -0,0 +1 @@ +.so man4/random.4 diff --git a/man4/vcs.4 b/man4/vcs.4 new file mode 100644 index 000000000..ba75a589f --- /dev/null +++ b/man4/vcs.4 @@ -0,0 +1,172 @@ +.\" Copyright (c) 1995 James R. Van Zandt <jrv@vanzandt.mv.com> +.\" Sat Feb 18 09:11:07 EST 1995 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified, Sun Feb 26 15:08:05 1995, faith@cs.unc.edu +.\" 2007-12-17, Samuel Thibault <samuel.thibault@ens-lyon.org>: +.\" document the VT_GETHIFONTMASK ioctl +.\" " +.TH VCS 4 2020-11-01 "Linux man-pages (unreleased)" +.SH NAME +vcs, vcsa \- virtual console memory +.SH DESCRIPTION +.I /dev/vcs0 +is a character device with major number 7 and minor number +0, usually with mode 0644 and ownership root:tty. +It refers to the memory of the currently +displayed virtual console terminal. +.PP +.I /dev/vcs[1\-63] +are character devices for virtual console +terminals, they have major number 7 and minor number 1 to 63, usually +mode 0644 and ownership root:tty. +.I /dev/vcsa[0\-63] +are the same, but +using +.IR "unsigned short" s +(in host byte order) that include attributes, +and prefixed with four bytes giving the screen +dimensions and cursor position: +.IR lines , +.IR columns , +.IR x , +.IR y . +.RI ( x += +.I y += 0 at the top left corner of the screen.) +.PP +When a 512-character font is loaded, +the 9th bit position can be fetched by applying the +.BR ioctl (2) +.B VT_GETHIFONTMASK +operation +(available in Linux kernels 2.6.18 and above) +on +.IR /dev/tty[1\-63] ; +the value is returned in the +.I "unsigned short" +pointed to by the third +.BR ioctl (2) +argument. +.PP +These devices replace the screendump +.BR ioctl (2) +operations of +.BR ioctl_console (2), +so the system +administrator can control access using filesystem permissions. +.PP +The devices for the first eight virtual consoles may be created by: +.PP +.in +4n +.EX +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* +.EE +.in +.PP +No +.BR ioctl (2) +requests are supported. +.SH FILES +.I /dev/vcs[0\-63] +.br +.I /dev/vcsa[0\-63] +.\" .SH AUTHOR +.\" Andries Brouwer <aeb@cwi.nl> +.SH VERSIONS +Introduced with version 1.1.92 of the Linux kernel. +.SH EXAMPLES +You may do a screendump on vt3 by switching to vt1 and typing +.PP +.in +4n +.EX +cat /dev/vcs3 >foo +.EE +.in +.PP +Note that the output does not contain +newline characters, so some processing may be required, like +in +.PP +.in +4n +.EX +fold \-w 81 /dev/vcs3 | lpr +.EE +.in +.PP +or (horrors) +.PP +.in +4n +.EX +setterm \-dump 3 \-file /proc/self/fd/1 +.EE +.in +.PP +The +.I /dev/vcsa0 +device is used for Braille support. +.PP +This program displays the character and screen attributes under the +cursor of the second virtual console, then changes the background color +there: +.PP +.EX +#include <unistd.h> +#include <stdlib.h> +#include <stdio.h> +#include <fcntl.h> +#include <sys/ioctl.h> +#include <linux/vt.h> + +int +main(void) +{ + int fd; + char *device = "/dev/vcsa2"; + char *console = "/dev/tty2"; + struct {unsigned char lines, cols, x, y;} scrn; + unsigned short s; + unsigned short mask; + unsigned char attrib; + int ch; + + fd = open(console, O_RDWR); + if (fd < 0) { + perror(console); + exit(EXIT_FAILURE); + } + if (ioctl(fd, VT_GETHIFONTMASK, &mask) < 0) { + perror("VT_GETHIFONTMASK"); + exit(EXIT_FAILURE); + } + (void) close(fd); + fd = open(device, O_RDWR); + if (fd < 0) { + perror(device); + exit(EXIT_FAILURE); + } + (void) read(fd, &scrn, 4); + (void) lseek(fd, 4 + 2*(scrn.y*scrn.cols + scrn.x), SEEK_SET); + (void) read(fd, &s, 2); + ch = s & 0xff; + if (s & mask) + ch |= 0x100; + attrib = ((s & \(timask) >> 8); + printf("ch=%#03x attrib=%#02x\en", ch, attrib); + s \(ha= 0x1000; + (void) lseek(fd, \-2, SEEK_CUR); + (void) write(fd, &s, 2); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR ioctl_console (2), +.BR tty (4), +.BR ttyS (4), +.BR gpm (8) diff --git a/man4/vcsa.4 b/man4/vcsa.4 new file mode 100644 index 000000000..ffe8d9be5 --- /dev/null +++ b/man4/vcsa.4 @@ -0,0 +1 @@ +.so man4/vcs.4 diff --git a/man4/veth.4 b/man4/veth.4 new file mode 100644 index 000000000..66a2082d0 --- /dev/null +++ b/man4/veth.4 @@ -0,0 +1,86 @@ +.\" Copyright (c) 2012 Tomáš Pospíšek (tpo_deb@sourcepole.ch), +.\" Fri, 03 Nov 2012 22:35:33 +0100 +.\" and Copyright (c) 2012 Eric W. Biederman <ebiederm@xmission.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" +.TH VETH 4 2021-03-22 "Linux man-pages (unreleased)" +.SH NAME +veth \- Virtual Ethernet Device +.SH DESCRIPTION +The +.B veth +devices are virtual Ethernet devices. +They can act as tunnels between network namespaces to create +a bridge to a physical network device in another namespace, +but can also be used as standalone network devices. +.PP +.B veth +devices are always created in interconnected pairs. +A pair can be created using the command: +.PP +.in +4n +.EX +# ip link add <p1-name> type veth peer name <p2-name> +.EE +.in +.PP +In the above, +.I p1-name +and +.I p2-name +are the names assigned to the two connected end points. +.PP +Packets transmitted on one device in the pair are immediately received on +the other device. +When either device is down, the link state of the pair is down. +.PP +.B veth +device pairs are useful for combining the network +facilities of the kernel together in interesting ways. +A particularly interesting use case is to place one end of a +.B veth +pair in one network namespace and the other end in another network namespace, +thus allowing communication between network namespaces. +To do this, one can provide the +.B netns +parameter when creating the interfaces: +.PP +.in +4n +.EX +# ip link add <p1\-name> netns <p1\-ns> type veth peer <p2\-name> netns <p2\-ns> +.EE +.in +.PP +or, for an existing +.B veth +pair, move one side to the other namespace: +.PP +.in +4n +.EX +# ip link set <p2\-name> netns <p2\-ns> +.EE +.in +.PP +.BR ethtool (8) +can be used to find the peer of a +.B veth +network interface, using commands something like: +.PP +.in +4n +.EX +# \fBip link add ve_A type veth peer name ve_B\fP # Create veth pair +# \fBethtool \-S ve_A\fP # Discover interface index of peer +NIC statistics: + peer_ifindex: 16 +# \fBip link | grep \(aq\(ha16:\(aq\fP # Look up interface +16: ve_B@ve_A: <BROADCAST,MULTICAST,M\-DOWN> mtu 1500 qdisc ... +.EE +.in +.SH "SEE ALSO" +.BR clone (2), +.BR network_namespaces (7), +.BR ip (8), +.BR ip\-link (8), +.BR ip\-netns (8) diff --git a/man4/wavelan.4 b/man4/wavelan.4 new file mode 100644 index 000000000..af8af80f0 --- /dev/null +++ b/man4/wavelan.4 @@ -0,0 +1,142 @@ +.\" 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 +.\" +.\" Provenance of this page is unclear. +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH WAVELAN 4 2021-03-22 "Linux man-pages (unreleased)" +.SH NAME +wavelan \- AT&T GIS WaveLAN ISA device driver +.SH SYNOPSIS +.nf +.BI "insmod wavelan_cs.o [io=" B,B.. "] [ irq=" I,I.. "] [name=" N,N.. ] +.fi +.SH DESCRIPTION +.I This driver is obsolete: +it was removed from the kernel in version 2.6.35. +.PP +.B 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. +.SS Parameters +This section applies 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 addresses 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 IRQs that each wavelan card should use (the value is +saved in permanent storage for future use). +.TP +.B name +Set the list of names to be used for each wavelan card device (name +used by +.BR ifconfig (8)). +.SS Wireless extensions +Use +.BR iwconfig (8) +to manipulate wireless extensions. +.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 +reused at any further invocation of the driver. +.SS Frequency & channels +For the 2.4\ GHz 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 as a numeric value. +The frequency is changed immediately and +permanently. +Frequency availability depends on the regulations... +.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)). +.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. +.SS Private ioctl +You may use +.BR iwpriv (8) +to manipulate private ioctls. +.SS Quality and level threshold +Enables you to define the quality and level threshold used by the +modem (packet below that level are discarded). +.SS Histogram +This functionality makes it possible 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. +.SS Specific notes +This driver fails to detect some +.B non-NCR/AT&T/Lucent +Wavelan cards. +If this happens for you, 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. +.\" .SH AUTHOR +.\" Bruce Janson \(em bruce@cs.usyd.edu.au +.\" .br +.\" Jean Tourrilhes \(em jt@hplb.hpl.hp.com +.\" .br +.\" (and 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 iwpriv (8), +.BR iwspy (8) diff --git a/man4/zero.4 b/man4/zero.4 new file mode 100644 index 000000000..15a39be05 --- /dev/null +++ b/man4/zero.4 @@ -0,0 +1 @@ +.so man4/null.4 |