diff options
| author | Michael Kerrisk <mtk.manpages@gmail.com> | 2007-04-12 22:42:49 +0000 |
|---|---|---|
| committer | Michael Kerrisk <mtk.manpages@gmail.com> | 2007-04-12 22:42:49 +0000 |
| commit | c13182efa3b3d77f2563034c8212c0ca798243ca (patch) | |
| tree | e7652b26018b7c22cd6a4e4b41404dfaab911303 /man7 | |
| parent | 4174ff5658082832c2ed511720f18881b3a80a34 (diff) | |
| download | man-pages-c13182efa3b3d77f2563034c8212c0ca798243ca.tar.gz | |
Wrapped long lines, wrapped at sentence boundaries; stripped trailing
white space.
Diffstat (limited to 'man7')
60 files changed, 3096 insertions, 2454 deletions
diff --git a/man7/LDP.7 b/man7/LDP.7 index 5376f7314f..b54b982159 100644 --- a/man7/LDP.7 +++ b/man7/LDP.7 @@ -25,7 +25,7 @@ free documentation resources including guides, FAQs, HOWTOs, and man-pages to the Linux community. .SH AUTHORS The various documents in the LDP archives are maintained by individual -authors, and are listed in the beginning of each HOWTO. +authors, and are listed in the beginning of each HOWTO. If you have any questions or inputs to a document we encourage you to contact the authors directly. @@ -62,7 +62,8 @@ For subscription information, see the website. .PP If you are interested in DocBook beyond the simple markup of your LDP document, you may want to consider joining one of the OASIS DocBook -mailing lists. Please see +mailing lists. +Please see \fBhttp://docbook\&.org/mailinglist/index\&.html\fP for more information. .SH FILES diff --git a/man7/arp.7 b/man7/arp.7 index 84146f23ef..4a0515f990 100644 --- a/man7/arp.7 +++ b/man7/arp.7 @@ -6,60 +6,68 @@ .\" of the modification is added to the header. .\" Modified June 1999 Andi Kleen .\" $Id: arp.7,v 1.10 2000/04/27 19:31:38 ak Exp $ -.TH ARP 7 1999-06-03 "Linux Man Page" "Linux Programmer's Manual" +.TH ARP 7 1999-06-03 "Linux Man Page" "Linux Programmer's Manual" .SH NAME -arp \- Linux ARP kernel module. +arp \- Linux ARP kernel module. .SH DESCRIPTION This kernel protocol module implements the Address Resolution Protocol defined in RFC\ 826. It is used to convert between Layer2 hardware addresses -and IPv4 protocol addresses on directly connected networks. -The user normally doesn't interact directly with this module except to -configure it; +and IPv4 protocol addresses on directly connected networks. +The user normally doesn't interact directly with this module except to +configure it; instead it provides a service for other protocols in the kernel. A user process can receive ARP packets by using .BR packet (7) -sockets. There is also a mechanism for managing the ARP cache +sockets. +There is also a mechanism for managing the ARP cache in user-space by using .BR netlink (7) -sockets. The ARP table can also be controlled via -.BR ioctl (2) -on any -.B PF_INET +sockets. +The ARP table can also be controlled via +.BR ioctl (2) +on any +.B PF_INET socket. The ARP module maintains a cache of mappings between hardware addresses -and protocol addresses. The cache has a limited size so old and less -frequently used entries are garbage-collected. Entries which are marked -as permanent are never deleted by the garbage-collector. The cache can +and protocol addresses. +The cache has a limited size so old and less +frequently used entries are garbage-collected. +Entries which are marked +as permanent are never deleted by the garbage-collector. +The cache can be directly manipulated by the use of ioctls and its behaviour can be -tuned by the sysctls defined below. +tuned by the sysctls defined below. When there is no positive feedback for an existing mapping after some time (see the sysctls below) a neighbour cache entry is considered stale. Positive feedback can be gotten from a higher layer; for example from -a successful TCP ACK. Other protocols can signal forward progress +a successful TCP ACK. +Other protocols can signal forward progress using the .B MSG_CONFIRM flag to .BR sendmsg (2). When there is no forward progress ARP tries to reprobe. It first tries to ask a local arp daemon -.B app_solicit +.B app_solicit times for an updated MAC address. If that fails and an old MAC address is known an unicast probe is send .B ucast_solicit -times. If that fails too it will broadcast a new ARP -request to the network. Requests are only send when there is data queued -for sending. +times. +If that fails too it will broadcast a new ARP +request to the network. +Requests are only send when there is data queued +for sending. -Linux will automatically add a non-permanent proxy arp entry when it -receives a request for an address it forwards to and proxy arp is -enabled on the receiving interface. +Linux will automatically add a non-permanent proxy arp entry when it +receives a request for an address it forwards to and proxy arp is +enabled on the receiving interface. When there is a reject route for the target no proxy arp entry is added. .SH IOCTLS -Three ioctls are available on all +Three ioctls are available on all .B PF_INET sockets. They take a pointer to a @@ -113,23 +121,24 @@ If the .B ATF_NETMASK flag is set, then .I arp_netmask -should be valid. +should be valid. Linux 2.2 does not support proxy network ARP entries, so this -should be set to 0xffffffff, or 0 to remove an existing proxy arp entry. +should be set to 0xffffffff, or 0 to remove an existing proxy arp entry. .B ATF_USETRAILERS is obsolete and should not be used. .SH SYSCTLS ARP supports a sysctl interface to configure parameters on a global or per-interface basis. -The sysctls can be accessed by reading or writing the +The sysctls can be accessed by reading or writing the .I /proc/sys/net/ipv4/neigh/*/* -files or with the +files or with the .BR sysctl (2) -interface. Each interface in the system has its own directory in +interface. +Each interface in the system has its own directory in /proc/sys/net/ipv4/neigh/. -The setting in the `default' directory is used for all newly created +The setting in the `default' directory is used for all newly created devices. -Unless otherwise specified time related sysctls are specified +Unless otherwise specified time related sysctls are specified in seconds. .TP .B anycast_delay @@ -154,18 +163,18 @@ Defaults to 30 seconds. .TP .B delay_first_probe_time Delay before first probe after it has been decided that a neighbour -is stale. +is stale. Defaults to 5 seconds. .TP .B gc_interval -How frequently the garbage collector for neighbour entries +How frequently the garbage collector for neighbour entries should attempt to run. Defaults to 30 seconds. .TP .B gc_stale_time -Determines how often to check for stale neighbour entries. When -a neighbour entry is considered stale it is resolved again before -sending data to it. +Determines how often to check for stale neighbour entries. +When a neighbour entry is considered stale it is resolved again before +sending data to it. Defaults to 60 seconds. .TP .B gc_thresh1 @@ -193,7 +202,7 @@ mapping (generally due to network misconfiguration). Defaults to 1 second. .TP .B mcast_solicit -The maximum number of attempts to resolve an address by +The maximum number of attempts to resolve an address by multicast/broadcast before marking the entry as unreachable. Defaults to 3. .TP @@ -223,18 +232,18 @@ The maximum number of packets which may be queued for each unresolved address by other network layers. Defaults to 3. .SH BUGS -Some timer settings are specified in jiffies, which is architecture +Some timer settings are specified in jiffies, which is architecture related. -On the Alpha a jiffy is 1/1024 of a second, on most other +On the Alpha a jiffy is 1/1024 of a second, on most other architectures it is 1/100s. -There is no way to signal positive feedback from user space. -This means connection oriented protocols implemented in user space -will generate excessive ARP traffic, because ndisc will regularly +There is no way to signal positive feedback from user space. +This means connection oriented protocols implemented in user space +will generate excessive ARP traffic, because ndisc will regularly reprobe the MAC address. The same problem applies for some kernel protocols (e.g. NFS over UDP). -This man page mashes IPv4 specific and shared between IPv4 and IPv6 +This man page mashes IPv4 specific and shared between IPv4 and IPv6 functionality together. .SH VERSIONS The @@ -244,9 +253,10 @@ changed in Linux 2.0 to include the member and the ioctl numbers changed at the same time. Support for the old ioctls was dropped in Linux 2.2. -Support for proxy arp entries for networks (netmask not equal 0xffffffff) -was dropped in Linux 2.2. It is replaced by automatic proxy arp setup by -the kernel for all reachable hosts on other interfaces (when +Support for proxy arp entries for networks (netmask not equal 0xffffffff) +was dropped in Linux 2.2. +It is replaced by automatic proxy arp setup by +the kernel for all reachable hosts on other interfaces (when forwarding and proxy arp is enabled for the interface). The neigh/* sysctls did not exist before Linux 2.2. diff --git a/man7/ascii.7 b/man7/ascii.7 index c898a8c585..f0747d51cf 100644 --- a/man7/ascii.7 +++ b/man7/ascii.7 @@ -36,7 +36,8 @@ ascii \- the ASCII character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION ASCII is the American Standard Code for Information Interchange. -It is a 7-bit code. Many 8-bit codes (such as ISO 8859-1, the +It is a 7-bit code. +Many 8-bit codes (such as ISO 8859-1, the Linux default character set) contain ASCII as their lower half. The international counterpart of ASCII is known as ISO 646. .LP diff --git a/man7/boot.7 b/man7/boot.7 index 0c3160b8e8..516d5bc2ae 100644 --- a/man7/boot.7 +++ b/man7/boot.7 @@ -14,7 +14,7 @@ .LP boot\-scripts \- General description of boot sequence .SH "DESCRIPTION" -.LP +.LP The boot sequence varies in details among systems but can be roughly divided to the following steps: (i) hardware boot, (ii) OS loader, @@ -24,12 +24,13 @@ We will describe each of these in more detail below. .SS "Hardware\-boot" After power\-on or hard reset, control is given to a program stored on read only memory (normally -PROM). In PC we usually call this program the -\fBBIOS\fR. +PROM). +In PC we usually call this program the \fBBIOS\fR. This program normally makes a basic self\-test of the machine and accesses non\-volatile memory to read -further parameters. This memory in the PC is +further parameters. +This memory in the PC is battery\-backed CMOS memory, so most people refer to it as the \fBCMOS\fR, although outside of the PC world, it is usually called \fBnvram\fR @@ -43,9 +44,10 @@ to probe as possible boot devices. Then the hardware boot stage accesses the boot device, loads the OS Loader, which is located on a fixed position on the boot device, and transfers control to it. -.TP +.TP Note: -We do not cover here booting from network. Those who want +We do not cover here booting from network. +Those who want to investigate this subject may want to research: DHCP, TFTP, PXE, Etherboot. .SS "OS Loader" @@ -54,7 +56,8 @@ of the boot device \- this is the \fBMBR\fR (Master Boot Record). In most systems, this primary loader is very -limited due to various constraints. Even on non\-PC systems +limited due to various constraints. +Even on non\-PC systems there are some limitations to the size and complexity of this loader, but the size limitation of the PC MBR (512 bytes including the partition table) makes it @@ -75,7 +78,8 @@ containing the bootstrap code to load the second part of the loader from the root partition. The main job of the OS Loader is to locate the kernel -on the disk, load it and run it. Most OS loaders allow +on the disk, load it and run it. +Most OS loaders allow interactive use, to enable specification of alternative kernel (maybe a backup in case the last compiled one isn't functioning) and to pass optional parameters @@ -88,12 +92,14 @@ file system (/). Some of the parameters that may be passed to the kernel relate to these activities (e.g: You can override the -default root file system). For further information +default root file system). +For further information on Linux kernel parameters read .BR bootparam (7). Only then the kernel creates the first (user land) -process which is numbered 1. This process executes the +process which is numbered 1. +This process executes the program .IR /sbin/init , passing any parameters that weren't handled by the kernel already. @@ -106,7 +112,8 @@ This file defines what should be run in different \fIrun-levels\fR. This gives the system administrator an easy management scheme, where each run-level is associated with a set of services (e.g: \fBS\fR is \fIsingle\-user\fR, on \fB2\fR most network -services start, etc.). The administrator may change the current +services start, etc.). +The administrator may change the current run-level via .BR init (8) and query the current run-level via @@ -117,12 +124,13 @@ by editing this file, inittab only bootstraps a set of scripts that actually start/stop the individual services. .SS "Boot Scripts" -.TP +.TP Note: The following description applies to System V release 4 based system, which currently covers most commercial Unix systems (Solaris, HP-UX, Irix, Tru64) as well as the major Linux distributions (RedHat, Debian, Mandrake, -Suse, Caldera). Some systems (Slackware Linux, FreeBSD, OpenBSD) +Suse, Caldera). +Some systems (Slackware Linux, FreeBSD, OpenBSD) have a somewhat different scheme of boot scripts. .LP For each managed service (mail, nfs server, cron, etc.) there is @@ -131,31 +139,38 @@ a single startup script located in a specific directory in most versions of Linux). Each of these scripts accepts as a single argument the word 'start' \-\- causing it to start the service, or the word -\&'stop' \-\- causing it to stop the service. The script may optionally +\&'stop' \-\- causing it to stop the service. +The script may optionally accept other "convenience" parameters (e.g: 'restart', to stop and then -start, 'status' do display the service status). Running the script +start, 'status' do display the service status). +Running the script without parameters displays the possible arguments. .SS "Sequencing Directories" To make specific scripts start/stop at specific run-levels and in -specific order, there are \fIsequencing directories\fR. These -are normally in \fI/etc/rc[0\-6S].d\fR. In each of these directories +specific order, there are \fIsequencing directories\fR. +These +are normally in \fI/etc/rc[0\-6S].d\fR. +In each of these directories there are links (usually symbolic) to the scripts in the \fIinit.d\fR directory. -A primary script (usually \fI/etc/rc\fR) is called from +A primary script (usually \fI/etc/rc\fR) is called from .BR inittab (5) and calls the services scripts via the links in the sequencing directories. All links with names that begin with 'S' are being called with -the argument 'start' (thereby starting the service). All links with +the argument 'start' (thereby starting the service). +All links with names that begin with 'K' are being called with the argument 'stop' (thereby stopping the service). To define the starting or stopping order within the same run-level, the names of the links contain order-numbers. Also, to make the names clearer, they usually -end with the name of the service they refer to. Example: +end with the name of the service they refer to. +Example: the link \fI/etc/rc2.d/S80sendmail\fR starts the sendmail service on -runlevel 2. This happens after \fI/etc/rc2.d/S12syslog\fR is run +runlevel 2. +This happens after \fI/etc/rc2.d/S12syslog\fR is run but before \fI/etc/rc2.d/S90xfs\fR is run. To manage the boot order and run-levels, we have to manage these links. @@ -164,19 +179,21 @@ However, on many versions of Linux, there are tools to help with this task .BR chkconfig (8)). .SS "Boot Configuration" Usually the daemons started may optionally receive command line options -and parameters. To allow system administrators to change these -parameters without editing the boot scripts themselves, -configuration files are used. These are located in a specific +and parameters. +To allow system administrators to change these +parameters without editing the boot scripts themselves, +configuration files are used. +These are located in a specific directory (\fI/etc/sysconfig\fR on RedHat systems) and are used by the boot scripts. In older Unix systems, these files contained the actual command line options for the daemons, but in modern Linux systems (and also -in HP-UX), these files just contain shell variables. The boot -scripts in \fI/etc/init.d\fR \fBsource\fR the configuration +in HP-UX), these files just contain shell variables. +The boot scripts in \fI/etc/init.d\fR \fBsource\fR the configuration files, and then use the variable values. .SH "FILES" -.LP +.LP .IR /etc/init.d/ , .IR /etc/rc[S0\-6].d/ . .I /etc/sysconfig/ diff --git a/man7/bootparam.7 b/man7/bootparam.7 index 5a08df228b..0a4d442bae 100644 --- a/man7/bootparam.7 +++ b/man7/bootparam.7 @@ -29,7 +29,8 @@ bootparam \- Introduction to boot time parameters of the Linux kernel .SH DESCRIPTION The Linux kernel accepts certain `command line options' or `boot time -parameters' at the moment it is started. In general this is used to +parameters' at the moment it is started. +In general this is used to supply the kernel with information about hardware parameters that the kernel would not be able to determine on its own, or to avoid/override the values that the kernel would otherwise detect. @@ -45,8 +46,10 @@ using rdev, see for further details. The LILO program (LInux LOader) written by Werner Almesberger is the -most commonly used. It has the ability to boot various kernels, and -stores the configuration information in a plain text file. (See +most commonly used. +It has the ability to boot various kernels, and +stores the configuration information in a plain text file. +(See .BR lilo (8) and .BR lilo.conf (5).) @@ -58,51 +61,59 @@ prompt (with boot-args) assuming that certain resources are available. This is good for people that want to launch Linux from DOS. It is also very useful if you have certain hardware which relies on -the supplied DOS driver to put the hardware into a known state. A -common example is `SoundBlaster Compatible' sound cards that require +the supplied DOS driver to put the hardware into a known state. +A common example is `SoundBlaster Compatible' sound cards that require the DOS driver to twiddle a few mystical registers to put the card -into a SB compatible mode. Booting DOS with the supplied driver, and +into a SB compatible mode. +Booting DOS with the supplied driver, and then loading Linux from the DOS prompt with loadlin avoids the reset of the card that happens if one rebooted instead. .SH "THE ARGUMENT LIST" The kernel command line is parsed into a list of strings -(boot arguments) separated by spaces. Most of the boot args -take the form of: +(boot arguments) separated by spaces. +Most of the boot args take the form of: .IP name[=value_1][,value_2]...[,value_10] .LP where `name' is a unique keyword that is used to identify what part of the kernel the associated values (if any) are to be given to. Note the limit of 10 is real, as the present code only handles 10 comma -separated parameters per keyword. (However, you can re-use the same +separated parameters per keyword. +(However, you can re-use the same keyword with up to an additional 10 parameters in unusually complicated situations, assuming the setup function supports it.) -Most of the sorting goes on in linux/init/main.c. First, the kernel +Most of the sorting goes on in linux/init/main.c. +First, the kernel checks to see if the argument is any of the special arguments `root=', -`nfsroot=', `nfsaddrs=', `ro', `rw', `debug' or `init'. The meaning -of these special arguments is described below. +`nfsroot=', `nfsaddrs=', `ro', `rw', `debug' or `init'. +The meaning of these special arguments is described below. Then it walks a list of setup functions (contained in the bootsetups array) to see if the specified argument string (such as `foo') has been associated with a setup function (`foo_setup()') for a particular -device or part of the kernel. If you passed the kernel the line +device or part of the kernel. +If you passed the kernel the line foo=3,4,5,6 then the kernel would search the bootsetups array to see -if `foo' was registered. If it was, then it would call the setup +if `foo' was registered. +If it was, then it would call the setup function associated with `foo' (foo_setup()) and hand it the arguments 3, 4, 5 and 6 as given on the kernel command line. Anything of the form `foo=bar' that is not accepted as a setup function as described above is then interpreted as an environment variable to -be set. A (useless?) example would be to use `TERM=vt100' as a boot +be set. +A (useless?) example would be to use `TERM=vt100' as a boot argument. Any remaining arguments that were not picked up by the kernel and were not interpreted as environment variables are then passed onto process -one, which is usually the init program. The most common argument that +one, which is usually the init program. +The most common argument that is passed to the init process is the word `single' which instructs init to boot the computer in single user mode, and not launch all the usual -daemons. Check the manual page for the version of init installed on +daemons. +Check the manual page for the version of init installed on your system to see what arguments it accepts. .SH "GENERAL NON-DEVICE SPECIFIC BOOT ARGS" .SS "`init=...'" @@ -120,30 +131,38 @@ and panic if all of this fails. This sets the nfs boot address to the given string. This boot address is used in case of a net boot. .SS "`nfsroot=...'" -This sets the nfs root name to the given string. If this string +This sets the nfs root name to the given string. +If this string does not begin with '/' or ',' or a digit, then it is prefixed by -`/tftpboot/'. This root name is used in case of a net boot. +`/tftpboot/'. +This root name is used in case of a net boot. .SS "`no387'" (Only when CONFIG_BUGi386 is defined.) Some i387 coprocessor chips have bugs that show up when used in 32 bit -protected mode. For example, some of the early ULSI-387 chips would +protected mode. +For example, some of the early ULSI-387 chips would cause solid lockups while performing floating point calculations. Using the `no387' boot arg causes Linux to ignore the maths -coprocessor even if you have one. Of course you must then have your +coprocessor even if you have one. +Of course you must then have your kernel compiled with math emulation support! .SS "`no-hlt'" (Only when CONFIG_BUGi386 is defined.) Some of the early i486DX-100 chips have a problem with the `hlt' instruction, in that they can't reliably return to operating mode -after this instruction is used. Using the `no-hlt' instruction tells +after this instruction is used. +Using the `no-hlt' instruction tells Linux to just run an infinite loop when there is nothing else to do, -and to not halt the CPU. This allows people with these broken chips +and to not halt the CPU. +This allows people with these broken chips to use Linux. .SS "`root=...'" This argument tells the kernel what device is to be used as the root -filesystem while booting. The default of this setting is determined +filesystem while booting. +The default of this setting is determined at compile time, and usually is the value of the root device of the -system that the kernel was built on. To override this value, and +system that the kernel was built on. +To override this value, and select the second floppy drive as the root device, one would use `root=/dev/fd1'. (The root device can also be set using .BR rdev (8).) @@ -158,22 +177,25 @@ the device type (`hd' for ST-506 compatible hard disk, with Y in floppy disk, with Y the floppy drive number \(em fd0 would be the DOS `A:' drive, and fd1 would be `B:'), Y the driver letter or number, and N the number (in decimal) of the partition on this device -(absent in the case of floppies). Recent kernels allow many other +(absent in the case of floppies). +Recent kernels allow many other types, mostly for CD-ROMs: nfs, ram, scd, mcd, cdu535, aztcd, cm206cd, gscd, sbpcd, sonycd, bpcd. (The type nfs specifies a net boot; ram refers to a ram disk.) Note that this has nothing to do with the designation of these -devices on your file system. The `/dev/' part is purely conventional. +devices on your file system. +The `/dev/' part is purely conventional. The more awkward and less portable numeric specification of the above -possible root devices in major/minor format is also accepted. (E.g., -/dev/sda3 is major 8, minor 3, so you could use `root=0x803' as an +possible root devices in major/minor format is also accepted. +(E.g., /dev/sda3 is major 8, minor 3, so you could use `root=0x803' as an alternative.) .SS "`ro' and `rw'" The `ro' option tells the kernel to mount the root filesystem as `readonly' so that filesystem consistency check programs (fsck) -can do their work on a quiescent file system. No processes can +can do their work on a quiescent file system. +No processes can write to files on the filesystem in question until it is `remounted' as read/write capable, e.g., by `mount \-w \-n \-o remount /'. (See also @@ -185,19 +207,21 @@ This is the default. The choice between read-only and read/write can also be set using .BR rdev (8). .SS "`reserve=...'" -This is used to protect I/O port regions from probes. The form of the -command is: +This is used to protect I/O port regions from probes. +The form of the command is: .IP .BI reserve= iobase,extent[,iobase,extent]... .LP In some machines it may be necessary to prevent device drivers from -checking for devices (auto-probing) in a specific region. This may be +checking for devices (auto-probing) in a specific region. +This may be because of hardware that reacts badly to the probing, or hardware that would be mistakenly identified, or merely hardware you don't want the kernel to initialize. The reserve boot-time argument specifies an I/O port region that -shouldn't be probed. A device driver will not probe a reserved region, +shouldn't be probed. +A device driver will not probe a reserved region, unless another boot argument explicitly specifies that it do so. For example, the boot line @@ -209,25 +233,30 @@ keeps all device drivers except the driver for `blah' from probing .SS "`mem=...'" The BIOS call defined in the PC specification that returns the amount of installed memory was only designed to be able -to report up to 64MB. Linux uses this BIOS call at boot to -determine how much memory is installed. If you have more than 64MB of +to report up to 64MB. +Linux uses this BIOS call at boot to +determine how much memory is installed. +If you have more than 64MB of RAM installed, you can use this boot arg to tell Linux how much memory -you have. The value is in decimal or hexadecimal (prefix 0x), +you have. +The value is in decimal or hexadecimal (prefix 0x), and the suffixes `k' (times 1024) or `M' (times 1048576) can be used. Here is a quote from Linus on usage of the `mem=' parameter. \&``The kernel will accept any `mem=xx' parameter you give it, and if it turns out that you lied to it, it will crash horribly sooner or later. The parameter indicates the highest addressable RAM address, so -\&`mem=0x1000000' means you have 16MB of memory, for example. For a -96MB machine this would be `mem=0x6000000'. +\&`mem=0x1000000' means you have 16MB of memory, for example. +For a 96MB machine this would be `mem=0x6000000'. NOTE NOTE NOTE: some machines might use the top of memory for BIOS cacheing or whatever, so you might not actually have up to the full -96MB addressable. The reverse is also true: some chipsets will map +96MB addressable. +The reverse is also true: some chipsets will map the physical memory that is covered by the BIOS area into the area just past the top of memory, so the top-of-mem might actually be 96MB -+ 384kB for example. If you tell linux that it has more memory than ++ 384kB for example. +If you tell linux that it has more memory than it actually does have, bad things will happen: maybe not at once, but surely eventually.'' @@ -247,7 +276,8 @@ but might destroy not yet written data in a disk cache. A warm reboot may be faster.) By default a reboot is hard, by asking the keyboard controller to pulse the reset line low, but there is at least one type -of motherboard where that doesn't work. The option `reboot=bios' will +of motherboard where that doesn't work. +The option `reboot=bios' will instead jump through the BIOS. .SS "`nosmp'" and "`maxcpus=N'" (Only when __SMP__ is defined.) @@ -257,26 +287,32 @@ of CPUs activated in SMP mode to N. .SH "BOOT ARGUMENTS FOR USE BY KERNEL DEVELOPERS" .SS "`debug'" Kernel messages are handed off to the kernel log daemon klogd so that they -may be logged to disk. Messages with a priority above +may be logged to disk. +Messages with a priority above .I console_loglevel -are also printed on the console. (For these levels, see <linux/kernel.h>.) +are also printed on the console. +(For these levels, see <linux/kernel.h>.) By default this variable is set to log anything more important than -debug messages. This boot argument will cause the kernel to also +debug messages. +This boot argument will cause the kernel to also print the messages of DEBUG priority. The console loglevel can also be set at run time via an option -to klogd. See +to klogd. +See .BR klogd (8). .SS "`profile=N'" It is possible to enable a kernel profiling function, if one wishes to find out where the kernel is spending its CPU cycles. Profiling is enabled by setting the variable .I prof_shift -to a non-zero value. This is done either by specifying CONFIG_PROFILE at +to a non-zero value. +This is done either by specifying CONFIG_PROFILE at compile time, or by giving the `profile=' option. Now the value that .I prof_shift gets will be N, when given, or CONFIG_PROFILE_SHIFT, when that is given, -or 2, the default. The significance of this variable is that it +or 2, the default. +The significance of this variable is that it gives the granularity of the profiling: each clock tick, if the system was executing kernel code, a counter is incremented: .IP @@ -296,20 +332,23 @@ For kernel tuners only. .SS "`buff=N1,N2,N3,N4,N5,N6'" Set the six parameters max_buff_age, buff_advance, buff_decline, buff_initial_age, bufferout_weight, buffermem_grace that control -kernel buffer memory management. For kernel tuners only. +kernel buffer memory management. +For kernel tuners only. .SH "BOOT ARGUMENTS FOR RAMDISK USE" (Only if the kernel was compiled with CONFIG_BLK_DEV_RAM.) In general it is a bad idea to use a ramdisk under Linux \(em the system will use available memory more efficiently itself. But while booting (or while constructing boot floppies) it is often useful to load the floppy contents into a -ramdisk. One might also have a system in which first +ramdisk. +One might also have a system in which first some modules (for filesystem or hardware) must be loaded before the main disk can be accessed. In Linux 1.3.48, ramdisk handling was changed drastically. Earlier, the memory was allocated statically, and there was -a `ramdisk=N' parameter to tell its size. (This could also +a `ramdisk=N' parameter to tell its size. +(This could also be set in the kernel image at compile time, or by use of .BR rdev (8).) These days ram disks use the buffer cache, and grow dynamically. @@ -320,13 +359,17 @@ in conjunction with the new ramdisk setup), see There are four parameters, two boolean and two integral. .SS "`load_ramdisk=N'" -If N=1, do load a ramdisk. If N=0, do not load a ramdisk. +If N=1, do load a ramdisk. +If N=0, do not load a ramdisk. (This is the default.) .SS "`prompt_ramdisk=N'" -If N=1, do prompt for insertion of the floppy. (This is the default.) -If N=0, do not prompt. (Thus, this parameter is never needed.) +If N=1, do prompt for insertion of the floppy. +(This is the default.) +If N=0, do not prompt. +(Thus, this parameter is never needed.) .SS "`ramdisk_size=N' or (obsolete) `ramdisk=N'" -Set the maximal size of the ramdisk(s) to N kB. The default is 4096 (4 MB). +Set the maximal size of the ramdisk(s) to N kB. +The default is 4096 (4 MB). .SS "`ramdisk_start=N'" Sets the starting block number (the offset on the floppy where the ramdisk starts) to N. @@ -356,45 +399,54 @@ the last process that used it has closed General notation for this section: .I iobase --- the first I/O port that the SCSI host occupies. These are -specified in hexadecimal notation, and usually lie in the range from -0x200 to 0x3ff. +-- the first I/O port that the SCSI host occupies. +These are specified in hexadecimal notation, +and usually lie in the range from 0x200 to 0x3ff. .I irq -- the hardware interrupt that the card is configured to use. Valid values will be dependent on the card in question, but will -usually be 5, 7, 9, 10, 11, 12, and 15. The other values are usually +usually be 5, 7, 9, 10, 11, 12, and 15. +The other values are usually used for common peripherals like IDE hard disks, floppies, serial ports, etc. .I scsi-id -- the ID that the host adapter uses to identify itself on the -SCSI bus. Only some host adapters allow you to change this value, as -most have it permanently specified internally. The usual default value +SCSI bus. +Only some host adapters allow you to change this value, as +most have it permanently specified internally. +The usual default value is 7, but the Seagate and Future Domain TMC-950 boards use 6. .I parity -- whether the SCSI host adapter expects the attached devices -to supply a parity value with all information exchanges. Specifying a -one indicates parity checking is enabled, and a zero disables parity -checking. Again, not all adapters will support selection of parity +to supply a parity value with all information exchanges. +Specifying a one indicates parity checking is enabled, +and a zero disables parity checking. +Again, not all adapters will support selection of parity behaviour as a boot argument. .SS "`max_scsi_luns=...'" A SCSI device can have a number of `sub-devices' contained within -itself. The most common example is one of the new SCSI CD-ROMs that -handle more than one disk at a time. Each CD is addressed as a -`Logical Unit Number' (LUN) of that particular device. But most +itself. +The most common example is one of the new SCSI CD-ROMs that +handle more than one disk at a time. +Each CD is addressed as a +`Logical Unit Number' (LUN) of that particular device. +But most devices, such as hard disks, tape drives and such are only one device, and will be assigned to LUN zero. Some poorly designed SCSI devices cannot handle being probed for -LUNs not equal to zero. Therefore, if the compile time flag +LUNs not equal to zero. +Therefore, if the compile time flag CONFIG_SCSI_MULTI_LUN is not set, newer kernels will by default only probe LUN zero. To specify the number of probed LUNs at boot, one enters `max_scsi_luns=n' as a boot arg, where n is a number between one and -eight. To avoid problems as described above, one would use n=1 to +eight. +To avoid problems as described above, one would use n=1 to avoid upsetting such broken devices. .SS "SCSI tape configuration" Some boot time configuration of the SCSI tape driver can be achieved @@ -402,13 +454,16 @@ by using the following: .IP .BI st= buf_size[,write_threshold[,max_bufs]] .LP -The first two numbers are specified in units of kB. The default +The first two numbers are specified in units of kB. +The default .I buf_size is 32kB, and the maximum size that can be specified is a -ridiculous 16384kB. The +ridiculous 16384kB. +The .I write_threshold is the value at which the buffer is committed to tape, with a -default value of 30kB. The maximum number of buffers varies +default value of 30kB. +The maximum number of buffers varies with the number of drives detected, and has a default of two. An example usage would be: .IP @@ -421,7 +476,8 @@ The aha numbers refer to cards and the aic numbers refer to the actual SCSI chip on these type of cards, including the Soundblaster-16 SCSI. The probe code for these SCSI hosts looks for an installed BIOS, and -if none is present, the probe will not find your card. Then you will +if none is present, the probe will not find your card. +Then you will have to use a boot arg of the form: .IP .BI aha152x= iobase[,irq[,scsi-id[,reconnect[,parity]]]] @@ -432,7 +488,8 @@ value can be specified to set the debug level. All the parameters are as described at the top of this section, and the .I reconnect value will allow device disconnect/reconnect if a non-zero value -is used. An example usage is as follows: +is used. +An example usage is as follows: .IP aha152x=0x340,11,7,1 .LP @@ -441,28 +498,34 @@ you want to specify a parity setting, then you will have to specify an iobase, irq, scsi-id and reconnect value as well. .SS "Adaptec aha154x configuration" The aha1542 series cards have an i82077 floppy controller onboard, -while the aha1540 series cards do not. These are busmastering cards, +while the aha1540 series cards do not. +These are busmastering cards, and have parameters to set the ``fairness'' that is used to share -the bus with other devices. The boot arg looks like the following. +the bus with other devices. +The boot arg looks like the following. .IP .BI aha1542= iobase[,buson,busoff[,dmaspeed]] .LP Valid iobase values are usually one of: 0x130, 0x134, 0x230, 0x234, -0x330, 0x334. Clone cards may permit other values. +0x330, 0x334. +Clone cards may permit other values. The .IR buson ", " busoff values refer to the number of microseconds that the -card dominates the ISA bus. The defaults are 11us on, and 4us off, so +card dominates the ISA bus. +The defaults are 11us on, and 4us off, so that other cards (such as an ISA LANCE Ethernet card) have a chance to get access to the ISA bus. The .I dmaspeed value refers to the rate (in MB/s) at which the DMA -(Direct Memory Access) transfers proceed. The default is 5MB/s. +(Direct Memory Access) transfers proceed. +The default is 5MB/s. Newer revision cards allow you to select this value as part of the -soft-configuration, older cards use jumpers. You can use values up to +soft-configuration, older cards use jumpers. +You can use values up to 10MB/s assuming that your motherboard is capable of handling it. Experiment with caution if using values over 5MB/s. .SS "Adaptec aha274x, aha284x, aic7xxx configuration" @@ -473,17 +536,22 @@ These boards can accept an argument of the form: The .I extended value, if non-zero, indicates that extended translation for large -disks is enabled. The +disks is enabled. +The .I no_reset value, if non-zero, tells the driver not to reset the SCSI bus when setting up the host adaptor at boot. .SS "AdvanSys SCSI Hosts configuration (`advansys=')" The AdvanSys driver can accept up to four i/o addresses that will be -probed for an AdvanSys SCSI card. Note that these values (if used) do -not effect EISA or PCI probing in any way. They are only used for -probing ISA and VLB cards. In addition, if the driver has been +probed for an AdvanSys SCSI card. +Note that these values (if used) do +not effect EISA or PCI probing in any way. +They are only used for +probing ISA and VLB cards. +In addition, if the driver has been compiled with debugging enabled, the level of debugging output can be -set by adding an 0xdeb[0-f] parameter. The 0-f allows setting the +set by adding an 0xdeb[0-f] parameter. +The 0-f allows setting the level of the debugging messages to any of 16 levels of verbosity. .SS "AM53C974" .IP @@ -495,14 +563,17 @@ level of the debugging messages to any of 16 levels of verbosity. For an extensive discussion of the BusLogic command line parameters, see .IR /usr/src/linux/drivers/scsi/BusLogic.c -(lines 3149-3270 in the kernel version I am looking at). The text +(lines 3149-3270 in the kernel version I am looking at). +The text below is a very much abbreviated extract. -The parameters N1-N5 are integers. The parameters S1,... are strings. +The parameters N1-N5 are integers. +The parameters S1,... are strings. N1 is the I/O Address at which the Host Adapter is located. N2 is the Tagged Queue Depth to use for Target Devices that support Tagged Queuing. -N3 is the Bus Settle Time in seconds. This is the amount of time +N3 is the Bus Settle Time in seconds. +This is the amount of time to wait between a Host Adapter Hard Reset which initiates a SCSI Bus Reset and issuing any SCSI Commands. N4 is the Local Options (for one Host Adapter). @@ -530,7 +601,8 @@ The default list of i/o ports to be probed can be changed by The .I mem_base value is the value of the memory mapped I/O region that -the card uses. This will usually be one of the following values: +the card uses. +This will usually be one of the following values: 0xc8000, 0xca000, 0xcc000, 0xce000, 0xdc000, 0xde000. .SS "IN2000 configuration" .IP @@ -539,7 +611,8 @@ the card uses. This will usually be one of the following values: where S is a comma-separated string of items keyword[:value]. Recognized keywords (possibly with value) are: ioport:addr, noreset, nosync:x, period:ns, disconnect:x, -debug:x, proc:x. For the function of these parameters, see +debug:x, proc:x. +For the function of these parameters, see .IR /usr/src/linux/drivers/scsi/in2000.c . .SS "NCR5380 and NCR53C400 configuration" The boot arg is of the form @@ -551,7 +624,9 @@ or .BI ncr53c400= iobase,irq .LP If the card doesn't use interrupts, then an IRQ value of 255 (0xff) will -disable interrupts. An IRQ value of 254 means to autoprobe. More +disable interrupts. +An IRQ value of 254 means to autoprobe. +More details can be found in the file .IR /usr/src/linux/drivers/scsi/README.g_NCR5380 . .SS "NCR53C8xx configuration" @@ -573,13 +648,15 @@ Specify irq = 0 for non-interrupt driven mode. Set fastpio = 1 for fast pio mode, 0 for slow mode. .SS "Pro Audio Spectrum configuration" The PAS16 uses a NC5380 SCSI chip, and newer models support -jumperless configuration. The boot arg is of the form: +jumperless configuration. +The boot arg is of the form: .IP .BI pas16= iobase,irq .LP The only difference is that you can specify an IRQ value of 255, which will tell the driver to work without using interrupts, albeit at a -performance loss. The iobase is usually 0x388. +performance loss. +The iobase is usually 0x388. .SS "Seagate ST-0x configuration" If your card is not detected at boot time, you will then have to use a boot arg of the form: @@ -589,7 +666,8 @@ you will then have to use a boot arg of the form: The .I mem_base value is the value of the memory mapped I/O region that -the card uses. This will usually be one of the following values: +the card uses. +This will usually be one of the following values: 0xc8000, 0xca000, 0xcc000, 0xce000, 0xdc000, 0xde000. .SS "Trantor T128 configuration" These cards are also based on the NCR5380 chip, and accept the @@ -611,35 +689,43 @@ The default list of i/o ports to be probed can be changed by .IP .BI wd33c93= S .LP -where S is a comma-separated string of options. Recognized options are +where S is a comma-separated string of options. +Recognized options are nosync:bitmask, nodma:x, period:ns, disconnect:x, debug:x, -clock:x, next. For details, see +clock:x, next. +For details, see .IR /usr/src/linux/drivers/scsi/wd33c93.c . .SH "HARD DISKS" .SS "IDE Disk/CD-ROM Driver Parameters" The IDE driver accepts a number of parameters, which range from disk -geometry specifications, to support for broken controller chips. Drive -specific options are specified by using `hdX=' with X in `a'-`h'. +geometry specifications, to support for broken controller chips. +Drive specific options are specified by using `hdX=' with X in `a'-`h'. -Non-drive specific options are specified with the prefix `hd='. Note -that using a drive specific prefix for a non-drive specific option +Non-drive specific options are specified with the prefix `hd='. +Note that using a drive specific prefix for a non-drive specific option will still work, and the option will just be applied as expected. Also note that `hd=' can be used to refer to the next unspecified -drive in the (a, ..., h) sequence. For the following discussions, -the `hd=' option will be cited for brevity. See the file +drive in the (a, ..., h) sequence. +For the following discussions, +the `hd=' option will be cited for brevity. +See the file README.ide in linux/drivers/block for more details. .SS "The `hd=cyls,heads,sects[,wpcom[,irq]]' options" These options are used to specify the physical geometry of the disk. -Only the first three values are required. The cylinder/head/sectors -values will be those used by fdisk. The write precompensation value -is ignored for IDE disks. The IRQ value specified will be the IRQ +Only the first three values are required. +The cylinder/head/sectors +values will be those used by fdisk. +The write precompensation value +is ignored for IDE disks. +The IRQ value specified will be the IRQ used for the interface that the drive resides on, and is not really a drive specific parameter. .SS "The `hd=serialize' option" The dual IDE interface CMD-640 chip is broken as designed such that when drives on the secondary interface are used at the same time as -drives on the primary interface, it will corrupt your data. Using this +drives on the primary interface, it will corrupt your data. +Using this option tells the driver to make sure that both interfaces are never used at the same time. .SS "The `hd=dtc2278' option" @@ -647,7 +733,8 @@ This option tells the driver that you have a DTC-2278D IDE interface. The driver then tries to do DTC specific operations to enable the second interface and to enable faster transfer modes. .SS "The `hd=noprobe' option" -Do not probe for this drive. For example, +Do not probe for this drive. +For example, .IP hdb=noprobe hdb=1166,7,17 .LP @@ -659,14 +746,17 @@ Some drives apparently have the WRERR_STAT bit stuck on permanently. This enables a work-around for these broken devices. .SS "The `hd=cdrom' option" This tells the IDE driver that there is an ATAPI compatible CD-ROM -attached in place of a normal IDE hard disk. In most cases the CD-ROM +attached in place of a normal IDE hard disk. +In most cases the CD-ROM is identified automatically, but if it isn't then this may help. .SS "Standard ST-506 Disk Driver Options (`hd=')" The standard disk driver can accept geometry arguments for the disks -similar to the IDE driver. Note however that it only expects three -values (C/H/S); any more or any less and it will silently ignore -you. Also, it only accepts `hd=' as an argument, i.e. `hda=' -and so on are not valid here. The format is as follows: +similar to the IDE driver. +Note however that it only expects three +values (C/H/S); any more or any less and it will silently ignore you. +Also, it only accepts `hd=' as an argument, i.e. `hda=' +and so on are not valid here. +The format is as follows: .IP hd=cyls,heads,sects .LP @@ -680,20 +770,25 @@ If the card is not recognised, you will have to use a boot arg of the form: xd=type,irq,iobase,dma_chan .LP The type value specifies the particular manufacturer of the card, -overriding autodetection. For the types to use, consult the +overriding autodetection. +For the types to use, consult the .I drivers/block/xd.c -source file of the kernel you are using. The type is an index in the list +source file of the kernel you are using. +The type is an index in the list .I xd_sigs and in the course of time .\" 1.1.50, 1.3.81, 1.3.99, 2.0.34, 2.1.67, 2.1.78, 2.1.127 types have been added to or deleted from the middle of the list, -changing all type numbers. Today (Linux 2.5.0) the types are +changing all type numbers. +Today (Linux 2.5.0) the types are 0=generic; 1=DTC 5150cx; 2,3=DTC 5150x; 4,5=Western Digital; 6,7,8=Seagate; 9=Omti; 10=XEBEC, and where here several types are given with the same designation, they are equivalent. The xd_setup() function does no checking on the values, and assumes -that you entered all four values. Don't disappoint it. Here is an +that you entered all four values. +Don't disappoint it. +Here is an example usage for a WD1002 controller with the BIOS disabled/removed, using the `default' XT controller parameters: .IP @@ -723,7 +818,8 @@ The syntax for this type of card is: aztcd=iobase[,magic_number] .LP If you set the magic_number to 0x79 then the driver will try and run -anyway in the event of an unknown firmware version. All other values +anyway in the event of an unknown firmware version. +All other values are ignored. .SS "Parallel port CD-ROM drives" Syntax: @@ -735,18 +831,19 @@ pcd.nice=nice where `port' is the base address, `pro' is the protocol number, `uni' is the unit selector (for chained devices), `mod' is the mode (or \-1 to choose the best automatically), `slv' is 1 if it should be a slave, -and `dly' is a small integer for slowing down port accesses. The -`nice' parameter controls the driver's use of idle CPU time, at the +and `dly' is a small integer for slowing down port accesses. +The `nice' parameter controls the driver's use of idle CPU time, at the expense of some speed. .SS "The CDU-31A and CDU-33A Sony Interface" This CD-ROM interface is found on some of the Pro Audio Spectrum sound -cards, and other Sony supplied interface cards. The syntax is as -follows: +cards, and other Sony supplied interface cards. +The syntax is as follows: .IP cdu31a=iobase,[irq[,is_pas_card]] .LP Specifying an IRQ value of zero tells the driver that hardware -interrupts aren't supported (as on some PAS cards). If your card +interrupts aren't supported (as on some PAS cards). +If your card supports interrupts, you should use them as it cuts down on the CPU usage of the driver. @@ -770,8 +867,10 @@ Syntax: .IP isp16=[iobase[,irq[,dma[,type]]]] .LP -(three integers and a string). If the type is given as `noisp16', -the interface will not be configured. Other recognized types +(three integers and a string). +If the type is given as `noisp16', +the interface will not be configured. +Other recognized types are: `Sanyo", `Sony', `Panasonic' and `Mitsumi'. .SS "The Mitsumi Standard Interface" The syntax for this CD-ROM interface is: @@ -801,7 +900,8 @@ cm206=[iobase][,irq] .LP The driver assumes numbers between 3 and 11 are IRQ values, and numbers between 0x300 and 0x370 are I/O ports, so you can specify one, -or both numbers, in any order. It also accepts `cm206=auto' to enable +or both numbers, in any order. +It also accepts `cm206=auto' to enable autoprobing. .SS "The Sanyo Interface" The syntax for this type of card is: @@ -813,24 +913,26 @@ The syntax for this type of card is: sbpcd=iobase,type .LP where type is one of the following (case sensitive) strings: -`SoundBlaster', `LaserMate', or `SPEA'. The I/O base is that of the +`SoundBlaster', `LaserMate', or `SPEA'. +The I/O base is that of the CD-ROM interface, and not that of the sound portion of the card. .SH "ETHERNET DEVICES" Different drivers make use of different parameters, but they all at -least share having an IRQ, an I/O port base value, and a name. In its -most generic form, it looks something like this: +least share having an IRQ, an I/O port base value, and a name. +In its most generic form, it looks something like this: .IP ether=irq,iobase[,param_1[,...param_8]],name .LP -The first non-numeric argument is taken as the name. The param_n -values (if applicable) usually have different meanings for each -different card/driver. Typical param_n values are used to specify +The first non-numeric argument is taken as the name. +The param_n values (if applicable) usually have different meanings for each +different card/driver. +Typical param_n values are used to specify things like shared memory address, interface selection, DMA channel and the like. The most common use of this parameter is to force probing for a second -ethercard, as the default is to only probe for one. This can be -accomplished with a simple: +ethercard, as the default is to only probe for one. +This can be accomplished with a simple: .IP ether=0,0,eth1 .LP @@ -839,60 +941,77 @@ example tell the driver(s) to autoprobe. The Ethernet-HowTo has extensive documentation on using multiple cards and on the card/driver specific implementation -of the param_n values where used. Interested readers should refer to +of the param_n values where used. +Interested readers should refer to the section in that document on their particular card. .SH "THE FLOPPY DISK DRIVER" There are many floppy driver options, and they are all listed in -README.fd in linux/drivers/block. This information is taken directly +README.fd in linux/drivers/block. +This information is taken directly from that file. .SS "floppy=mask,allowed_drive_mask" -Sets the bitmask of allowed drives to mask. By default, only units 0 -and 1 of each floppy controller are allowed. This is done because +Sets the bitmask of allowed drives to mask. +By default, only units 0 +and 1 of each floppy controller are allowed. +This is done because certain non-standard hardware (ASUS PCI motherboards) mess up the -keyboard when accessing units 2 or 3. This option is somewhat +keyboard when accessing units 2 or 3. +This option is somewhat obsoleted by the cmos option. .SS "floppy=all_drives" -Sets the bitmask of allowed drives to all drives. Use this if you have +Sets the bitmask of allowed drives to all drives. +Use this if you have more than two drives connected to a floppy controller. .SS "floppy=asus_pci" Sets the bitmask to allow only units 0 and 1. (The default) .SS "floppy=daring" Tells the floppy driver that you have a well behaved floppy -controller. This allows more efficient and smoother operation, but -may fail on certain controllers. This may speed up certain operations. +controller. +This allows more efficient and smoother operation, but +may fail on certain controllers. +This may speed up certain operations. .SS "floppy=0,daring" Tells the floppy driver that your floppy controller should be used with caution. .SS "floppy=one_fdc" Tells the floppy driver that you have only floppy controller (default) .SS "floppy=two_fdc or floppy=address,two_fdc" -Tells the floppy driver that you have two floppy controllers. The -second floppy controller is assumed to be at address. If address is +Tells the floppy driver that you have two floppy controllers. +The second floppy controller is assumed to be at address. +If address is not given, 0x370 is assumed. .SS "floppy=thinkpad" -Tells the floppy driver that you have a Thinkpad. Thinkpads use an +Tells the floppy driver that you have a Thinkpad. +Thinkpads use an inverted convention for the disk change line. .SS "floppy=0,thinkpad" Tells the floppy driver that you don't have a Thinkpad. .SS "floppy=drive,type,cmos" -Sets the cmos type of drive to type. Additionally, this drive is -allowed in the bitmask. This is useful if you have more than two +Sets the cmos type of drive to type. +Additionally, this drive is +allowed in the bitmask. +This is useful if you have more than two floppy drives (only two can be described in the physical cmos), or if -your BIOS uses non-standard CMOS types. Setting the CMOS to 0 for the +your BIOS uses non-standard CMOS types. +Setting the CMOS to 0 for the first two drives (default) makes the floppy driver read the physical cmos for those drives. .SS "floppy=unexpected_interrupts" Print a warning message when an unexpected interrupt is received (default behaviour) .SS "floppy=no_unexpected_interrupts or floppy=L40SX" -Don't print a message when an unexpected interrupt is received. This -is needed on IBM L40SX laptops in certain video modes. (There seems to -be an interaction between video and floppy. The unexpected interrupts +Don't print a message when an unexpected interrupt is received. +This is needed on IBM L40SX laptops in certain video modes. +(There seems to +be an interaction between video and floppy. +The unexpected interrupts only affect performance, and can safely be ignored.) .SH "THE SOUND DRIVER" The sound driver can also accept boot args to override the compiled in -values. This is not recommended, as it is rather complex. It is -described in the Readme.Linux file, in linux/drivers/sound. It accepts +values. +This is not recommended, as it is rather complex. +It is described in the Readme.Linux file, in linux/drivers/sound. +It accepts a boot arg of the form: .IP sound=device1[,device2[,device3...[,device10]]] @@ -910,7 +1029,8 @@ I \- interrupt line in hex (i.e 10=a, 11=b, ...) d \- DMA channel. As you can see it gets pretty messy, and you are better off to compile -in your own personal values as recommended. Using a boot arg of +in your own personal values as recommended. +Using a boot arg of `sound=0' will disable the sound driver entirely. .SH "ISDN DRIVERS" .SS "The ICN ISDN driver" @@ -926,7 +1046,8 @@ Syntax: pcbit=membase1,irq1[,membase2,irq2] .LP where membaseN is the shared memory base of the N'th card, and irqN is -the interrupt setting of the N'th card. The default is IRQ 5 and +the interrupt setting of the N'th card. +The default is IRQ 5 and membase 0xD0000. .SS "The Teles ISDN driver" Syntax: @@ -974,7 +1095,8 @@ Syntax: baycom=iobase,irq,modem .LP There are precisely 3 parameters; for several cards, give -several `baycom=' commands. The modem parameter is a string +several `baycom=' commands. +The modem parameter is a string that can take one of the values ser12, ser12*, par96, par96*. Here the * denotes that software DCD is to be used, and ser12/par96 chooses between the supported modem types. @@ -1003,13 +1125,16 @@ lp=reset lp=port[,port...] .LP You can tell the printer driver what ports to use and what ports not -to use. The latter comes in handy if you don't want the printer driver +to use. +The latter comes in handy if you don't want the printer driver to claim all available parallel ports, so that other drivers (e.g. PLIP, PPA) can use them instead. -The format of the argument is multiple port names. For example, +The format of the argument is multiple port names. +For example, lp=none,parport0 would use the first parallel port for lp1, and -disable lp0. To disable the printer driver entirely, one can use +disable lp0. +To disable the printer driver entirely, one can use lp=0. .SS "WDT500/501 driver" Syntax: @@ -1026,14 +1151,16 @@ And precisely the same is true for the msmouse driver. atamouse=threshold[,y-threshold] .IP If only one argument is given, it is used for both -x-threshold and y-threshold. Otherwise, the first argument +x-threshold and y-threshold. +Otherwise, the first argument is the x-threshold, and the second the y-threshold. These values must lie between 1 and 20 (inclusive); the default is 2. .SH "VIDEO HARDWARE" .SS "`no-scroll'" This option tells the console driver not to use hardware scroll (where a scroll is effected by moving the screen origin in video -memory, instead of moving the data). It is required by certain +memory, instead of moving the data). +It is required by certain Braille machines. .SH AUTHORS Linus Torvalds (and many others) diff --git a/man7/capabilities.7 b/man7/capabilities.7 index c82d8e1a0f..c6c599648d 100644 --- a/man7/capabilities.7 +++ b/man7/capabilities.7 @@ -39,8 +39,8 @@ while unprivileged processes are subject to full permission checking based on the process's credentials (usually: effective UID, effective GID, and supplementary group list). -Starting with kernel 2.2, Linux divides the privileges traditionally -associated with superuser into distinct units, known as +Starting with kernel 2.2, Linux divides the privileges traditionally +associated with superuser into distinct units, known as .IR capabilities , which can be independently enabled and disabled. Capabilities are a per-thread attribute. @@ -111,7 +111,7 @@ This includes use of the KDSIGACCEPT ioctl. .\" FIXME CAP_KILL also has an effect for threads + setting child .\" termination signal to other than SIGCHLD: without this .\" capability, the termination signal reverts to SIGCHLD -.\" if the child does an exec(). What is the rationale +.\" if the child does an exec(). What is the rationale .\" for this? .TP .B CAP_LEASE @@ -195,11 +195,11 @@ to assign and .B IOPRIO_CLASS_IDLE I/O scheduling classes; -perform +perform .BR keyctl (2) .B KEYCTL_CHOWN and -.B KEYCTL_SETPERM +.B KEYCTL_SETPERM operations. allow forged UID when passing socket credentials; exceed @@ -209,17 +209,17 @@ in system calls that open files (e.g., .BR accept (2), .BR execve (2), .BR open (2), -.BR pipe (2); -without this capability these system calls will fail with the error -.B ENFILE +.BR pipe (2); +without this capability these system calls will fail with the error +.B ENFILE if this limit is encountered); -employ -.BR CLONE_NEWNS +employ +.BR CLONE_NEWNS flag with .BR clone (2) and .BR unshare (2); -perform +perform .B KEYCTL_CHOWN and .B KEYCTL_SETPERM @@ -253,14 +253,14 @@ and setting scheduling policies and priorities for arbitrary processes .RB ( sched_setscheduler (2), .BR sched_setparam (2)); set CPU affinity for arbitrary processes -.RB ( sched_setaffinity (2)); +.RB ( sched_setaffinity (2)); set I/O scheduling class and priority for arbitrary processes -.RB ( ioprio_set (2)); +.RB ( ioprio_set (2)); allow .BR migrate_pages (2) to be applied to arbitrary processes and allow processes to be migrated to arbitrary nodes; -.\" FIXME CAP_SYS_NICE also has the following effect for +.\" FIXME CAP_SYS_NICE also has the following effect for .\" migrate_pages(2): .\" do_migrate_pages(mm, &old, &new, .\" capable(CAP_SYS_NICE) ? MPOL_MF_MOVE_ALL : MPOL_MF_MOVE); @@ -269,9 +269,9 @@ allow to be applied to arbitrary processes; use the .B MPOL_MF_MOVE_ALL -flag with +flag with .BR mbind (2) -and +and .BR move_pages (2). .TP .B CAP_SYS_PACCT @@ -330,8 +330,8 @@ perform permission checks for the thread. the capabilities that the thread may assume (i.e., a limiting superset for the effective and inheritable sets). If a thread drops a capability from its permitted set, -it can never re-acquire that capability (unless it -.BR exec ()s +it can never re-acquire that capability (unless it +.BR exec ()s a set-user-ID-root program). .TP .IR inheritable : @@ -384,7 +384,7 @@ that for all privileged operations, the kernel check whether the thread has the required capability in its effective set. .IP 2. 4 -that the kernel provide +that the kernel provide system calls allowing a thread's capability sets to be changed and retrieved. .IP 3. 4 @@ -393,7 +393,7 @@ so that a process gains those capabilities when the file is execed. .PP As at Linux 2.6.14, only the first two of these requirements are met. -Eventually, it should be possible to associate three +Eventually, it should be possible to associate three capability sets with an executable file, which, in conjunction with the capability sets of the thread, will determine the capabilities of a thread after an @@ -401,7 +401,7 @@ will determine the capabilities of a thread after an .TP .IR Inheritable " (formerly known as " allowed ): this set is ANDed with the thread's inheritable set to determine which -inheritable capabilities are permitted to the thread after the +inheritable capabilities are permitted to the thread after the .BR exec (). .TP .IR Permitted " (formerly known as " forced ): @@ -414,7 +414,7 @@ also to be set in the new effective set. (F(effective) would normally be either all zeroes or all ones.) .PP In the meantime, since the current implementation does not -support file capability sets, during an +support file capability sets, during an .BR exec (): .IP 1. 4 All three file capability sets are initially assumed to be cleared. @@ -428,14 +428,14 @@ If a set-user-ID-root program is being executed, then the file effective set is defined to be all ones. .SS Transformation of Capabilities During exec() .PP -During an -.BR exec (), +During an +.BR exec (), the kernel calculates the new capabilities of the process using the following algorithm: .in +4 .nf -P'(permitted) = (P(inheritable) & F(inheritable)) | +P'(permitted) = (P(inheritable) & F(inheritable)) | (F(permitted) & cap_bset) P'(effective) = P'(permitted) & F(effective) @@ -446,10 +446,10 @@ P'(inheritable) = P(inheritable) [i.e., unchanged] .in -4 where: .IP P 10 -denotes the value of a thread capability set before the +denotes the value of a thread capability set before the .BR exec () .IP P' 10 -denotes the value of a capability set after the +denotes the value of a capability set after the .BR exec () .IP F 10 denotes a file capability set @@ -457,40 +457,40 @@ denotes a file capability set is the value of the capability bounding set. .PP In the current implementation, the upshot of this algorithm is that -when a process +when a process .BR exec ()s a set-user-ID-root program, or when a process with an effective UID of 0 .BR exec ()s a program, -it gains all capabilities in its permitted and effective capability sets, -except those masked out by the capability bounding set (i.e., +it gains all capabilities in its permitted and effective capability sets, +except those masked out by the capability bounding set (i.e., .BR CAP_SETPCAP ). -.\" If a process with real UID 0, and non-zero effective UID does an -.\" exec(), then it gets all capabilities (less CAP_SETPCAP) in its +.\" If a process with real UID 0, and non-zero effective UID does an +.\" exec(), then it gets all capabilities (less CAP_SETPCAP) in its .\" permitted set, and no effective capabilities This provides semantics that are the same as those provided by traditional Unix systems. .SS Effect of User ID Changes on Capabilities -To preserve the traditional semantics for transitions between -0 and non-zero user IDs, -the kernel makes the following changes to a thread's capability -sets on changes to the thread's real, effective, saved set, +To preserve the traditional semantics for transitions between +0 and non-zero user IDs, +the kernel makes the following changes to a thread's capability +sets on changes to the thread's real, effective, saved set, and file system user IDs (using .BR setuid (2), .BR setresuid (2), or similar): .IP 1. 4 -If one or more of the real, effective or saved set user IDs -was previously 0, and as a result of the UID changes all of these IDs -have a non-zero value, -then all capabilities are cleared from the permitted and effective +If one or more of the real, effective or saved set user IDs +was previously 0, and as a result of the UID changes all of these IDs +have a non-zero value, +then all capabilities are cleared from the permitted and effective capability sets. .IP 2. 4 -If the effective user ID is changed from 0 to non-zero, +If the effective user ID is changed from 0 to non-zero, then all capabilities are cleared from the effective set. .IP 3. 4 If the effective user ID is changed from non-zero to 0, -then the permitted set is copied to the effective set. +then the permitted set is copied to the effective set. .IP 4. 4 If the file system user ID is changed from 0 to non-zero (see .BR setfsuid (2)) @@ -502,7 +502,7 @@ then the following capabilities are cleared from the effective set: and .BR CAP_FSETID . If the file system UID is changed from non-zero to 0, -then any of these capabilities that are enabled in the permitted set +then any of these capabilities that are enabled in the permitted set are enabled in the effective set. .PP If a thread that has a 0 value for one or more of its user IDs wants diff --git a/man7/charsets.7 b/man7/charsets.7 index 9b1cb7ecdd..209b8e3f33 100644 --- a/man7/charsets.7 +++ b/man7/charsets.7 @@ -14,31 +14,36 @@ .SH NAME charsets \- programmer's view of character sets and internationalization .SH DESCRIPTION -Linux is an international operating system. Various of its utilities +Linux is an international operating system. +Various of its utilities and device drivers (including the console driver) support multilingual character sets including Latin-alphabet letters with diacritical marks, accents, ligatures, and entire non-Latin alphabets including Greek, Cyrillic, Arabic, and Hebrew. .LP This manual page presents a programmer's-eye view of different -character-set standards and how they fit together on Linux. Standards +character-set standards and how they fit together on Linux. +Standards discussed include ASCII, ISO 8859, KOI8-R, Unicode, ISO 2022 and -ISO 4873. The primary emphasis is on character sets actually used as +ISO 4873. +The primary emphasis is on character sets actually used as locale character sets, not the myriad others that can be found in data from other systems. .LP A complete list of charsets used in a officially supported locale in glibc 2.2.3 is: ISO-8859-{1,2,3,5,6,7,8,9,13,15}, CP1251, UTF-8, EUC-{KR,JP,TW}, KOI8-{R,U}, GB2312, GB18030, GBK, BIG5, BIG5-HKSCS and TIS-620 (in no -particular order.) (Romanian may be switching to ISO-8859-16.) +particular order.) +(Romanian may be switching to ISO-8859-16.) .SH ASCII ASCII (American Standard Code For Information Interchange) is the original -7-bit character set, originally designed for American English. It is -currently described by the ECMA-6 standard. +7-bit character set, originally designed for American English. +It is currently described by the ECMA-6 standard. .LP Various ASCII variants replacing the dollar sign with other currency symbols and replacing punctuation with non-English alphabetic characters -to cover German, French, Spanish and others in 7 bits exist. All are +to cover German, French, Spanish and others in 7 bits exist. +All are deprecated; GNU libc doesn't support locales whose character sets aren't true supersets of ASCII. (These sets are also known as ISO-646, a close relative of ASCII that permitted replacing these characters.) @@ -50,7 +55,8 @@ ISO 8859 is a series of 15 8-bit character sets all of which have US ASCII in their low (7-bit) half, invisible control characters in positions 128 to 159, and 96 fixed-width graphics in positions 160-255. .LP -Of these, the most important is ISO 8859-1 (Latin-1). It is natively +Of these, the most important is ISO 8859-1 (Latin-1). +It is natively supported in the Linux console driver, fairly well supported in X11R6, and is the base character set of HTML. .LP @@ -68,7 +74,8 @@ Here are brief descriptions of each set: Latin-1 covers most Western European languages such as Albanian, Catalan, Danish, Dutch, English, Faroese, Finnish, French, German, Galician, Irish, Icelandic, Italian, Norwegian, Portuguese, Spanish, and -Swedish. The lack of the ligatures Dutch ij, French oe and old-style +Swedish. +The lack of the ligatures Dutch ij, French oe and old-style ,,German`` quotation marks is considered tolerable. .TP 8859-2 (Latin-2) @@ -81,17 +88,20 @@ Latin-3 is popular with authors of Esperanto, Galician, and Maltese. (Turkish is now written with 8859-9 instead.) .TP 8859-4 (Latin-4) -Latin-4 introduced letters for Estonian, Latvian, and Lithuanian. It -is essentially obsolete; see 8859-10 (Latin-6) and 8859-13 (Latin-7). +Latin-4 introduced letters for Estonian, Latvian, and Lithuanian. +It is essentially obsolete; see 8859-10 (Latin-6) and 8859-13 (Latin-7). .TP 8859-5 Cyrillic letters supporting Bulgarian, Byelorussian, Macedonian, -Russian, Serbian and Ukrainian. Ukrainians read the letter `ghe' +Russian, Serbian and Ukrainian. +Ukrainians read the letter `ghe' with downstroke as `heh' and would need a ghe with upstroke to write a -correct ghe. See the discussion of KOI8-R below. +correct ghe. +See the discussion of KOI8-R below. .TP 8859-6 -Supports Arabic. The 8859-6 glyph table is a fixed font of separate +Supports Arabic. +The 8859-6 glyph table is a fixed font of separate letter forms, but a proper display engine should combine these using the proper initial, medial, and final forms. .TP @@ -99,8 +109,8 @@ using the proper initial, medial, and final forms. Supports Modern Greek. .TP 8859-8 -Supports modern Hebrew without niqud (punctuation signs). Niqud -and full-fledged Biblical Hebrew are outside the scope of this +Supports modern Hebrew without niqud (punctuation signs). +Niqud and full-fledged Biblical Hebrew are outside the scope of this character set; under Linux, UTF-8 is the preferred encoding for these. .TP @@ -110,18 +120,22 @@ Turkish ones. .TP 8859-10 (Latin-6) Latin 6 adds the last Inuit (Greenlandic) and Sami (Lappish) letters -that were missing in Latin 4 to cover the entire Nordic area. RFC -1345 listed a preliminary and different `latin6'. Skolt Sami still +that were missing in Latin 4 to cover the entire Nordic area. +RFC 1345 listed a preliminary and different `latin6'. +Skolt Sami still needs a few more accents than these. .TP 8859-11 -This only exists as a rejected draft standard. The draft standard +This only exists as a rejected draft standard. +The draft standard was identical to TIS-620, which is used under Linux for Thai. .TP 8859-12 -This set does not exist. While Vietnamese has been suggested for this +This set does not exist. +While Vietnamese has been suggested for this space, it does not fit within the 96 (non-combining) characters ISO -8859 offers. UTF-8 is the preferred character set for Vietnamese use +8859 offers. +UTF-8 is the preferred character set for Vietnamese use under Linux. .TP 8859-13 (Latin-7) @@ -140,114 +154,148 @@ Latin-1. This set covers many of the languages covered by 8859-2, and supports Romanian more completely then that set does. .SH KOI8-R -KOI8-R is a non-ISO character set popular in Russia. The lower half +KOI8-R is a non-ISO character set popular in Russia. +The lower half is US ASCII; the upper is a Cyrillic character set somewhat better -designed than ISO 8859-5. KOI8-U is a common character set, based off -KOI8-R, that has better support for Ukrainian. Neither of these sets +designed than ISO 8859-5. +KOI8-U is a common character set, based off +KOI8-R, that has better support for Ukrainian. +Neither of these sets are ISO-2022 compatible, unlike the ISO-8859 series. .LP Console support for KOI8-R is available under Linux through user-mode utilities that modify keyboard bindings and the EGA graphics table, and employ the "user mapping" font table in the console driver. -.\" Thanks to Tomohiro KUBOTA for the following sections about +.\" Thanks to Tomohiro KUBOTA for the following sections about .\" national standards. .SH JIS X 0208 -JIS X 0208 is a Japanese national standard character set. Though -there are some more Japanese national standard character sets (like -JIS X 0201, JIS X 0212, and JIS X 0213), this is the most important -one. Characters are mapped into a 94x94 two-byte matrix, -whose each byte is in the range 0x21-0x7e. Note that JIS X 0208 -is a character set, not an encoding. This means that JIS X 0208 -itself is not used for expressing text data. JIS X 0208 is used +JIS X 0208 is a Japanese national standard character set. +Though there are some more Japanese national standard character sets (like +JIS X 0201, JIS X 0212, and JIS X 0213), this is the most important one. +Characters are mapped into a 94x94 two-byte matrix, +whose each byte is in the range 0x21-0x7e. +Note that JIS X 0208 is a character set, not an encoding. +This means that JIS X 0208 +itself is not used for expressing text data. +JIS X 0208 is used as a component to construct encodings such as EUC-JP, Shift_JIS, -and ISO-2022-JP. EUC-JP is the most important encoding for Linux -and includes US ASCII and JIS X 0208. In EUC-JP, JIS X 0208 +and ISO-2022-JP. +EUC-JP is the most important encoding for Linux +and includes US ASCII and JIS X 0208. +In EUC-JP, JIS X 0208 characters are expressed in two bytes, each of which is the JIS X 0208 code plus 0x80. .SH KS X 1001 -KS X 1001 is a Korean national standard character set. Just as +KS X 1001 is a Korean national standard character set. +Just as JIS X 0208, characters are mapped into a 94x94 two-byte matrix. KS X 1001 is used like JIS X 0208, as a component to construct encodings such as EUC-KR, Johab, and ISO-2022-KR. EUC-KR is the most important encoding for Linux and includes -US ASCII and KS X 1001. KS C 5601 is an older name for KS X 1001. +US ASCII and KS X 1001. +KS C 5601 is an older name for KS X 1001. .SH GB 2312 GB 2312 is a mainland Chinese national standard character set used -to express simplified Chinese. Just like JIS X 0208, characters are -mapped into a 94x94 two-byte matrix used to construct EUC-CN. EUC-CN +to express simplified Chinese. +Just like JIS X 0208, characters are +mapped into a 94x94 two-byte matrix used to construct EUC-CN. +EUC-CN is the most important encoding for Linux and includes US ASCII and -GB 2312. Note that EUC-CN is often called as GB, GB 2312, or CN-GB. +GB 2312. +Note that EUC-CN is often called as GB, GB 2312, or CN-GB. .SH Big5 Big5 is a popular character set in Taiwan to express traditional -Chinese. (Big5 is both a character set and an encoding.) It is a -superset of US ASCII. Non-ASCII characters are expressed in two -bytes. Bytes 0xa1-0xfe are used as leading bytes for two-byte -characters. Big5 and its extension is widely used in Taiwan and Hong -Kong. It is not ISO 2022-compliant. +Chinese. +(Big5 is both a character set and an encoding.) +It is a superset of US ASCII. +Non-ASCII characters are expressed in two bytes. +Bytes 0xa1-0xfe are used as leading bytes for two-byte characters. +Big5 and its extension is widely used in Taiwan and Hong Kong. +It is not ISO 2022-compliant. .SH TIS 620 TIS 620 is a Thai national standard character set and a superset -of US ASCII. Like ISO 8859 series, Thai characters are mapped into -0xa1-0xfe. TIS 620 is the only commonly used character set under +of US ASCII. +Like ISO 8859 series, Thai characters are mapped into +0xa1-0xfe. +TIS 620 is the only commonly used character set under Linux besides UTF-8 to have combining characters. .SH UNICODE Unicode (ISO 10646) is a standard which aims to unambiguously represent every -character in every human language. Unicode's structure permits 20.1 bits -to encode every character. Since most computers don't include 20.1-bit +character in every human language. +Unicode's structure permits 20.1 bits to encode every character. +Since most computers don't include 20.1-bit integers, Unicode is usually encoded as 32-bit integers internally and either a series of 16-bit integers (UTF-16) (needing two 16-bit integers only when encoding certain rare characters) or a series of 8-bit bytes -(UTF-8). Information on Unicode is available at <http://www.unicode.com>. +(UTF-8). +Information on Unicode is available at <http://www.unicode.com>. .LP Linux represents Unicode using the 8-bit Unicode Transformation Format -(UTF-8). UTF-8 is a variable length encoding of Unicode. It uses 1 +(UTF-8). +UTF-8 is a variable length encoding of Unicode. +It uses 1 byte to code 7 bits, 2 bytes for 11 bits, 3 bytes for 16 bits, 4 bytes for 21 bits, 5 bytes for 26 bits, 6 bytes for 31 bits. .LP -Let 0,1,x stand for a zero, one, or arbitrary bit. A byte 0xxxxxxx +Let 0,1,x stand for a zero, one, or arbitrary bit. +A byte 0xxxxxxx stands for the Unicode 00000000 0xxxxxxx which codes the same symbol -as the ASCII 0xxxxxxx. Thus, ASCII goes unchanged into UTF-8, and +as the ASCII 0xxxxxxx. +Thus, ASCII goes unchanged into UTF-8, and people using only ASCII do not notice any change: not in code, and not in file size. .LP A byte 110xxxxx is the start of a 2-byte code, and 110xxxxx 10yyyyyy -is assembled into 00000xxx xxyyyyyy. A byte 1110xxxx is the start +is assembled into 00000xxx xxyyyyyy. +A byte 1110xxxx is the start of a 3-byte code, and 1110xxxx 10yyyyyy 10zzzzzz is assembled into xxxxyyyy yyzzzzzz. (When UTF-8 is used to code the 31-bit ISO 10646 then this progression continues up to 6-byte codes.) .LP For most people who use ISO-8859 character sets, this means that the -characters outside of ASCII are now coded with two bytes. This tends -to expand ordinary text files by only one or two percent. For Russian +characters outside of ASCII are now coded with two bytes. +This tends +to expand ordinary text files by only one or two percent. +For Russian or Greek users, this expands ordinary text files by 100%, since text in -those languages is mostly outside of ASCII. For Japanese users this means -that the 16-bit codes now in common use will take three bytes. While there +those languages is mostly outside of ASCII. +For Japanese users this means +that the 16-bit codes now in common use will take three bytes. +While there are algorithmic conversions from some character sets (esp. ISO-8859-1) to Unicode, general conversion requires carrying around conversion tables, which can be quite large for 16-bit codes. .LP Note that UTF-8 is self-synchronizing: 10xxxxxx is a tail, any other -byte is the head of a code. Note that the only way ASCII bytes occur -in a UTF-8 stream, is as themselves. In particular, there are no +byte is the head of a code. +Note that the only way ASCII bytes occur +in a UTF-8 stream, is as themselves. +In particular, there are no embedded NULs ('\\0') or '/'s that form part of some larger code. .LP Since ASCII, and, in particular, NUL and '/', are unchanged, the -kernel does not notice that UTF-8 is being used. It does not care at +kernel does not notice that UTF-8 is being used. +It does not care at all what the bytes it is handling stand for. .LP Rendering of Unicode data streams is typically handled through -`subfont' tables which map a subset of Unicode to glyphs. Internally +`subfont' tables which map a subset of Unicode to glyphs. +Internally the kernel uses Unicode to describe the subfont loaded in video RAM. This means that in UTF-8 mode one can use a character set with 512 -different symbols. This is not enough for Japanese, Chinese and +different symbols. +This is not enough for Japanese, Chinese and Korean, but it is enough for most other purposes. .LP At the current time, the console driver does not handle combining -characters. So Thai, Sioux and any other script needing combining +characters. +So Thai, Sioux and any other script needing combining characters can't be handled on the console. .SH "ISO 2022 AND ISO 4873" The ISO 2022 and 4873 standards describe a font-control model -based on VT100 practice. This model is (partially) supported +based on VT100 practice. +This model is (partially) supported by the Linux kernel and by .BR xterm (1). It is popular in Japan and Korea. @@ -257,7 +305,8 @@ and one of them is the current character set for codes with high bit zero (initially G0), and one of them is the current character set for codes with high bit one (initially G1). Each graphic character set has 94 or 96 characters, and is -essentially a 7-bit character set. It uses codes either +essentially a 7-bit character set. +It uses codes either 040-0177 (041-0176) or 0240-0377 (0241-0376). G0 always has size 94 and uses codes 041-0176. .LP diff --git a/man7/complex.7 b/man7/complex.7 index 7fb5f9b806..55343f141b 100644 --- a/man7/complex.7 +++ b/man7/complex.7 @@ -10,11 +10,14 @@ complex \- basics of complex mathematics Complex numbers are numbers of the form z = a+b*i, where a and b are real numbers and i = sqrt(\-1), so that i*i = \-1. .br -There are other ways to represent that number. The pair (a,b) of real +There are other ways to represent that number. +The pair (a,b) of real numbers may be viewed as a point in the plane, given by X- and -Y-coordinates. This same point may also be described by giving +Y-coordinates. +This same point may also be described by giving the pair of real numbers (r,phi), where r is the distance to the origin O, -and phi the angle between the X-axis and the line Oz. Now +and phi the angle between the X-axis and the line Oz. +Now z = r*exp(i*phi) = r*(cos(phi)+i*sin(phi)). .PP The basic operations are defined on z = a+b*i and w = c+d*i as: @@ -29,7 +32,8 @@ Nearly all math function have a complex counterpart but there are some complex only functions. .SH EXAMPLE Your C-compiler can work with complex numbers if it supports the C99 standard. -Link with \-lm. The imaginary unit is represented by I. +Link with \-lm. +The imaginary unit is represented by I. .sp .nf /* check that exp(i * pi) == \-1 */ @@ -37,7 +41,7 @@ Link with \-lm. The imaginary unit is represented by I. #include <complex.h> int -main(void) +main(void) { double pi = 4 * atan(1); complex z = cexp(I * pi); diff --git a/man7/ddp.7 b/man7/ddp.7 index 4d2e1342a4..9800f77d32 100644 --- a/man7/ddp.7 +++ b/man7/ddp.7 @@ -4,57 +4,62 @@ .\" and in case of nontrivial modification author and date .\" of the modification is added to the header. .\" $Id: ddp.7,v 1.3 1999/05/13 11:33:22 freitag Exp $ -.TH DDP 7 1999-05-01 "Linux Man Page" "Linux Programmer's Manual" +.TH DDP 7 1999-05-01 "Linux Man Page" "Linux Programmer's Manual" .SH NAME ddp \- Linux AppleTalk protocol implementation .SH SYNOPSIS .B #include <sys/socket.h> .br -.B #include <netatalk/at.h> +.B #include <netatalk/at.h> .sp .IB ddp_socket " = socket(PF_APPLETALK, SOCK_DGRAM, 0);" -.br +.br .IB raw_socket " = socket(PF_APPLETALK, SOCK_RAW, " protocol ");" .SH DESCRIPTION -Linux implements the Appletalk protocols described in +Linux implements the Appletalk protocols described in .IR "Inside Appletalk" . Only the DDP layer and AARP are present in -the kernel. They are designed to be used via the -.B netatalk +the kernel. +They are designed to be used via the +.B netatalk protocol -libraries. This page documents the interface for those who wish or need to +libraries. +This page documents the interface for those who wish or need to use the DDP layer directly. .PP The communication between Appletalk and the user program works using a -BSD-compatible socket interface. For more information on sockets, see -.BR socket (7). +BSD-compatible socket interface. +For more information on sockets, see +.BR socket (7). .PP -An AppleTalk socket is created by calling the -.BR socket (2) -function with a +An AppleTalk socket is created by calling the +.BR socket (2) +function with a .B PF_APPLETALK -socket family argument. Valid socket types are +socket family argument. +Valid socket types are .B SOCK_DGRAM -to open a -.B ddp +to open a +.B ddp socket or .B SOCK_RAW -to open a -.B raw -socket. -.I protocol -is the Appletalk protocol to be received or sent. For -.B SOCK_RAW +to open a +.B raw +socket. +.I protocol +is the Appletalk protocol to be received or sent. +For +.B SOCK_RAW you must specify .BR ATPROTO_DDP . .PP -Raw sockets may be only opened by a process with effective user ID 0 -or when the process has the -.B CAP_NET_RAW -capability. +Raw sockets may be only opened by a process with effective user ID 0 +or when the process has the +.B CAP_NET_RAW +capability. .SH "ADDRESS FORMAT" An Appletalk socket address is defined as a combination of a network number, -a node number, and a port number. +a node number, and a port number. .PP .RS .nf @@ -70,49 +75,52 @@ struct sockaddr_atalk { }; .ta .fi -.RE +.RE .PP .I sat_family -is always set to -.BR AF_APPLETALK . +is always set to +.BR AF_APPLETALK . .I sat_port -contains the port. The port numbers below 129 are known as +contains the port. +The port numbers below 129 are known as .I reserved ports. -Only processes with the effective user ID 0 or the -.B CAP_NET_BIND_SERVICE -capability may -.BR bind (2) -to these sockets. -.I sat_addr +Only processes with the effective user ID 0 or the +.B CAP_NET_BIND_SERVICE +capability may +.BR bind (2) +to these sockets. +.I sat_addr is the host address. -The +The .I net -member of +member of .I struct at_addr -contains the host network in network byte order. The value of -.B AT_ANYNET -is a +contains the host network in network byte order. +The value of +.B AT_ANYNET +is a wildcard and also implies \(lqthis network.\(rq -The +The .I node -member of +member of .I struct at_addr -contains the host node number. The value of -.B AT_ANYNODE -is a -wildcard and also implies \(lqthis node.\(rq The value of -.B ATADDR_BCAST +contains the host node number. +The value of +.B AT_ANYNODE +is a +wildcard and also implies \(lqthis node.\(rq The value of +.B ATADDR_BCAST is a link local broadcast address. .\" FIXME this doesn't make sense [johnl] .SH "SOCKET OPTIONS" No protocol-specific socket options are supported. .SH SYSCTLS -IP supports a sysctl interface to configure some global AppleTalk -parameters. -The sysctls can be accessed by reading or writing the -.I /proc/sys/net/atalk/* -files or with the +IP supports a sysctl interface to configure some global AppleTalk +parameters. +The sysctls can be accessed by reading or writing the +.I /proc/sys/net/atalk/* +files or with the .BR sysctl (2) interface. .TP @@ -120,11 +128,11 @@ interface. The time interval (in seconds) before an AARP cache entry expires. .TP .B aarp-resolve-time -The time interval (in seconds) before an AARP cache entry is resolved. +The time interval (in seconds) before an AARP cache entry is resolved. .TP .B aarp-retransmit-limit The number of retransmissions of an AARP query before the node is declared -dead. +dead. .TP .B aarp-tick-time The timer rate (in seconds) for the timer driving AARP. @@ -133,22 +141,24 @@ The default values match the specification and should never need to be changed. .SH IOCTLS All ioctls described in -.BR socket (7) +.BR socket (7) apply to ddp. .\" FIXME Add a section about multicasting .SH NOTES -Be very careful with the +Be very careful with the .B SO_BROADCAST -option \- it is not privileged in Linux. It is easy to overload the network -with careless sending to broadcast addresses. +option \- it is not privileged in Linux. +It is easy to overload the network +with careless sending to broadcast addresses. .SH VERSIONS -Appletalk is supported by Linux 2.0 or higher. The -.B sysctl +Appletalk is supported by Linux 2.0 or higher. +The +.B sysctl interface is new in Linux 2.2. .SH ERRORS .\" FIXME document all errors. We should really fix the kernels to -.\" give more uniform error returns (ENOMEM vs ENOBUFS, EPERM vs +.\" give more uniform error returns (ENOMEM vs ENOBUFS, EPERM vs .\" EACCES etc.) .TP .B ENOTCONN @@ -156,29 +166,29 @@ The operation is only defined on a connected socket, but the socket wasn't connected. .TP .B EINVAL -Invalid argument passed. +Invalid argument passed. .TP -.B EMSGSIZE +.B EMSGSIZE Datagram is bigger than the DDP MTU. .TP .B EACCES -The user tried to execute an operation without the necessary permissions. -These include sending to a broadcast address without +The user tried to execute an operation without the necessary permissions. +These include sending to a broadcast address without having the broadcast flag set, -and trying to bind to a reserved port without effective user ID 0 or -.BR CAP_NET_BIND_SERVICE . +and trying to bind to a reserved port without effective user ID 0 or +.BR CAP_NET_BIND_SERVICE . .TP .B EADDRINUSE Tried to bind to an address already in use. .TP .BR ENOMEM " and " ENOBUFS -Not enough memory available. +Not enough memory available. .TP .BR ENOPROTOOPT " and " EOPNOTSUPP Invalid socket option passed. .TP .B EPERM -User doesn't have permission to set high priority, +User doesn't have permission to set high priority, make a configuration change, or send signals to the requested process or group, .TP @@ -193,46 +203,47 @@ Operation on a nonblocking socket would block. The socket was unconfigured, or an unknown socket type was requested. .TP .B EISCONN -.BR connect (2) +.BR connect (2) was called on an already connected socket. .TP .B EALREADY A connection operation on a non-blocking socket is already in progress. .TP .B ECONNABORTED -A connection was closed during an -.BR accept (2). +A connection was closed during an +.BR accept (2). .TP .B EPIPE The connection was unexpectedly closed or shut down by the other end. .TP .B ENOENT -.B SIOCGSTAMP +.B SIOCGSTAMP was called on a socket where no packet arrived. .TP .B EHOSTUNREACH -No routing table entry matches the destination address. +No routing table entry matches the destination address. .TP -.B ENODEV +.B ENODEV Network device not available or not capable of sending IP. .TP -.B ENOPKG +.B ENOPKG A kernel subsystem was not configured. .SH COMPATIBILITY -The basic AppleTalk socket interface is compatible with -.B netatalk -on BSD-derived systems. Many BSD systems fail to check +The basic AppleTalk socket interface is compatible with +.B netatalk +on BSD-derived systems. +Many BSD systems fail to check .B SO_BROADCAST when sending broadcast frames; this can lead to compatibility problems. .PP -The +The raw socket mode is unique to Linux and exists to support the alternative CAP package and AppleTalk monitoring tools more easily. .SH BUGS -There are too many inconsistent error values. +There are too many inconsistent error values. .PP -The ioctls used to configure routing tables, devices, +The ioctls used to configure routing tables, devices, AARP tables and other devices are not yet described. .SH "SEE ALSO" .BR recvmsg (2), diff --git a/man7/environ.7 b/man7/environ.7 index 7066c0a289..ac90444571 100644 --- a/man7/environ.7 +++ b/man7/environ.7 @@ -21,7 +21,7 @@ .\" License along with this manual; if not, write to the Free .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, .\" USA. -.\" +.\" .\" Modified Sun Jul 25 10:45:30 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified Sun Jul 21 21:25:26 1996 by Andries Brouwer (aeb@cwi.nl) .\" Modified Mon Oct 21 17:47:19 1996 by Eric S. Raymond (esr@thyrsus.com) @@ -53,8 +53,10 @@ in case they came from glibc and was defined.) This array of strings is made available to the process by the .BR exec (3) -call that started the process. By convention these strings -have the form `\fIname\fP\fB=\fP\fIvalue\fP'. Common examples are: +call that started the process. +By convention these strings +have the form `\fIname\fP\fB=\fP\fIvalue\fP'. +Common examples are: .TP .B USER The name of the logged-in user (used by some BSD-derived programs). @@ -84,7 +86,8 @@ of a change directory command, \fBMANPATH\fP used by \fBman\fP(1) to find manual pages, etc.) .TP .B PWD -The current working directory. Set by some shells. +The current working directory. +Set by some shells. .TP .B SHELL The pathname of the user's login shell. @@ -122,7 +125,7 @@ influenced by the presence or value of certain environment variables. A random collection: .LP The variables -.BR LANG ", " LANGUAGE ", " NLSPATH ", " LOCPATH ", " +.BR LANG ", " LANGUAGE ", " NLSPATH ", " LOCPATH ", " .BR LC_ALL ", " LC_MESSAGES ", " etc. influence locale handling, cf. .BR locale (5). @@ -166,12 +169,14 @@ gives information on how to address a given terminal tell applications about the window size, possibly overriding the actual size. .LP .BR PRINTER " or " LPDEST -may specify the desired printer to use. See +may specify the desired printer to use. +See .BR lpr (1). .LP Etc. .SH BUGS -Clearly there is a security risk here. Many a system command has been +Clearly there is a security risk here. +Many a system command has been tricked into mischief by a user who specified unusual values for .BR IFS " or " LD_LIBRARY_PATH . @@ -202,7 +207,8 @@ Thus, one has and .BR GZIP . Such usage is considered mistaken, and to be avoided in new -programs. The authors of +programs. +The authors of .I gzip should consider renaming their option to .BR GZIP_OPT . diff --git a/man7/epoll.7 b/man7/epoll.7 index 02f288370d..e37bc24f9c 100644 --- a/man7/epoll.7 +++ b/man7/epoll.7 @@ -26,13 +26,14 @@ epoll \- I/O event notification facility .B #include <sys/epoll.h> .SH DESCRIPTION .B epoll -is a variant of +is a variant of .BR poll (2) that can be used either as Edge or Level Triggered interface and scales -well to large numbers of watched fds. Three system calls are provided to +well to large numbers of watched fds. +Three system calls are provided to set up and control an .B epoll -set: +set: .BR epoll_create (2), .BR epoll_ctl (2), .BR epoll_wait (2). @@ -41,16 +42,18 @@ An .B epoll set is connected to a file descriptor created by .BR epoll_create (2). -Interest for certain file descriptors is then registered via +Interest for certain file descriptors is then registered via .BR epoll_ctl (2). -Finally, the actual wait is started by +Finally, the actual wait is started by .BR epoll_wait (2). .SH NOTES The .B epoll event distribution interface is able to behave both as Edge Triggered -( ET ) and Level Triggered ( LT ). The difference between ET and LT -event distribution mechanism can be described as follows. Suppose that +( ET ) and Level Triggered ( LT ). +The difference between ET and LT +event distribution mechanism can be described as follows. +Suppose that this scenario happens : .TP .B 1 @@ -91,12 +94,14 @@ done in step .B 5 will probably hang because of the available data still present in the file input buffers and the remote peer might be expecting a response based on the -data it already sent. The reason for this is that Edge Triggered event +data it already sent. +The reason for this is that Edge Triggered event distribution delivers events only when events happens on the monitored file. So, in step .B 5 the caller might end up waiting for some data that is already present inside -the input buffer. In the above example, an event on +the input buffer. +In the above example, an event on .B RFD will be generated because of the write done in .BR 2 @@ -108,7 +113,8 @@ does not consume the whole buffer data, the call to .BR epoll_wait (2) done in step .B 5 -might lock indefinitely. The +might lock indefinitely. +The .B epoll interface, when used with the .B EPOLLET @@ -117,18 +123,18 @@ should use non-blocking file descriptors to avoid having a blocking read or write starve the task that is handling multiple file descriptors. The suggested way to use .B epoll -as an Edge Triggered +as an Edge Triggered .RB ( EPOLLET ) interface is below, and possible pitfalls to avoid follow. .RS -.TP +.TP .B i with non-blocking file descriptors -.TP +.TP .B ii by going to wait for an event only after .BR read (2) -or +or .BR write (2) return EAGAIN .RE @@ -138,7 +144,8 @@ On the contrary, when used as a Level Triggered interface, is by all means a faster .BR poll (2), and can be used wherever the latter is used since it shares the -same semantics. Since even with the Edge Triggered +same semantics. +Since even with the Edge Triggered .B epoll multiple events can be generated up on receipt of multiple chunks of data, the caller has the option to specify the @@ -149,7 +156,8 @@ to disable the associated file descriptor after the receipt of an event with .BR epoll_wait (2). When the .B EPOLLONESHOT -flag is specified, it is caller responsibility to rearm the file descriptor using +flag is specified, +it is caller responsibility to rearm the file descriptor using .BR epoll_ctl (2) with .BR EPOLL_CTL_MOD . @@ -160,10 +168,12 @@ when employed like a Level Triggered interface does have the same semantics of .BR poll (2), an Edge Triggered usage requires more clarification to avoid stalls -in the application event loop. In this example, listener is a +in the application event loop. +In this example, listener is a non-blocking socket on which .BR listen (2) -has been called. The function do_use_fd() uses the new ready +has been called. +The function do_use_fd() uses the new ready file descriptor until EAGAIN is returned by either .BR read (2) or @@ -174,7 +184,7 @@ it will continue to .BR read (2) or .BR write (2) -from where it stopped before. +from where it stopped before. .nf struct epoll_event ev, *events; @@ -210,7 +220,8 @@ possible to add the file descriptor inside the epoll interface ( .B EPOLL_CTL_ADD ) once by specifying ( .BR EPOLLIN | EPOLLOUT -). This allows you to avoid +). +This allows you to avoid continuously switching between .B EPOLLIN and @@ -219,16 +230,18 @@ calling .BR epoll_ctl (2) with .BR EPOLL_CTL_MOD . -.SH QUESTIONS AND ANSWERS -.TP -.B Q1 +.SH QUESTIONS AND ANSWERS +.TP +.B Q1 What happens if you add the same fd to an epoll_set twice? .TP -.B A1 -You will probably get EEXIST. However, it is possible that two -threads may add the same fd twice. This is a harmless condition. +.B A1 +You will probably get EEXIST. +However, it is possible that two +threads may add the same fd twice. +This is a harmless condition. .TP -.B Q2 +.B Q2 Can two .B epoll sets wait for the same fd? If so, are events reported @@ -237,7 +250,9 @@ to both sets fds? .TP .B A2 -Yes. However, it is not recommended. Yes it would be reported to both. +Yes. +However, it is not recommended. +Yes it would be reported to both. .TP .B Q3 Is the @@ -247,15 +262,16 @@ fd itself poll/epoll/selectable? .B A3 Yes. .TP -.B Q4 +.B Q4 What happens if the .B epoll fd is put into its own fd set? .TP .B A4 -It will fail. However, you can add an +It will fail. +However, you can add an .B epoll -fd inside another epoll fd set. +fd inside another epoll fd set. .TP .B Q5 Can I send the @@ -273,7 +289,7 @@ sets automatically? .B A6 Yes. .TP -.B Q7 +.B Q7 If more than one event comes in between .BR epoll_wait (2) calls, are they combined or reported separately? @@ -286,8 +302,10 @@ Does an operation on an fd affect the already collected but not yet reported events? .TP .B A8 -You can do two operations on an existing fd. Remove would be meaningless for -this case. Modify will re-read available I/O. +You can do two operations on an existing fd. +Remove would be meaningless for +this case. +Modify will re-read available I/O. .TP .B Q9 Do I need to continuously read/write an fd until EAGAIN when using the @@ -295,64 +313,76 @@ Do I need to continuously read/write an fd until EAGAIN when using the flag ( Edge Triggered behaviour ) ? .TP .B A9 -No you don't. Receiving an event from +No you don't. +Receiving an event from .BR epoll_wait (2) -should suggest to you that such file descriptor is ready for the requested I/O -operation. You have simply to consider it ready until you will receive the -next EAGAIN. When and how you will use such file descriptor is entirely up -to you. Also, the condition that the read/write I/O space is exhausted can +should suggest to you that such file descriptor is ready +for the requested I/O operation. +You have simply to consider it ready until you will receive the +next EAGAIN. +When and how you will use such file descriptor is entirely up +to you. +Also, the condition that the read/write I/O space is exhausted can be detected by checking the amount of data read/write from/to the target -file descriptor. For example, if you call +file descriptor. +For example, if you call .BR read (2) by asking to read a certain amount of data and .BR read (2) returns a lower number of bytes, you can be sure to have exhausted the read -I/O space for such file descriptor. Same is valid when writing using the +I/O space for such file descriptor. +Same is valid when writing using the .BR write (2) function. .SH POSSIBLE PITFALLS AND WAYS TO AVOID THEM .TP .B o Starvation ( Edge Triggered ) .PP -If there is a large amount of I/O space, it is possible that by trying to drain -it the other files will not get processed causing starvation. This -is not specific to +If there is a large amount of I/O space, +it is possible that by trying to drain +it the other files will not get processed causing starvation. +This is not specific to .BR epoll . .PP -The solution is to maintain a ready list and mark the file descriptor as ready +The solution is to maintain a ready list +and mark the file descriptor as ready in its associated data structure, thereby allowing the application to remember which files need to be processed but still round robin amongst -all the ready files. This also supports ignoring subsequent events you +all the ready files. +This also supports ignoring subsequent events you receive for fd's that are already ready. .TP -.B o If using an event cache... +.B o If using an event cache... .PP If you use an event cache or store all the fd's returned from .BR epoll_wait (2), -then make sure to provide a way to mark its closure dynamically (ie- caused by -a previous event's processing). Suppose you receive 100 events from +then make sure to provide a way to mark +its closure dynamically (ie- caused by +a previous event's processing). +Suppose you receive 100 events from .BR epoll_wait (2), -and in event #47 a condition causes event #13 to be closed. -If you remove the structure and +and in event #47 a condition causes event #13 to be closed. +If you remove the structure and .BR close () -the fd for event #13, then your -event cache might still say there are events waiting for that fd causing +the fd for event #13, then your +event cache might still say there are events waiting for that fd causing confusion. -.PP +.PP One solution for this is to call, during the processing of event 47, .BR epoll_ctl ( EPOLL_CTL_DEL ) -to delete fd 13 and -.BR close (), +to delete fd 13 and +.BR close (), then mark its associated -data structure as removed and link it to a cleanup list. If you find another +data structure as removed and link it to a cleanup list. +If you find another event for fd 13 in your batch processing, you will discover the fd had been previously removed and there will be no confusion. .SH CONFORMING TO -The epoll API is Linux specific. +The epoll API is Linux specific. Some other systems provide similar -mechanisms, e.g., FreeBSD has -.IR kqueue , -and Solaris has +mechanisms, e.g., FreeBSD has +.IR kqueue , +and Solaris has .IR /dev/poll . .SH VERSIONS .BR epoll (7) diff --git a/man7/feature_test_macros.7 b/man7/feature_test_macros.7 index 2f9f799ba3..85efdcb5d5 100644 --- a/man7/feature_test_macros.7 +++ b/man7/feature_test_macros.7 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -32,11 +32,11 @@ feature_test_macros \- feature test macros .SH DESCRIPTION Feature test macros allow the programmer to control the definitions that are exposed by system header files when a program is compiled. -This can be useful for creating portable applications, +This can be useful for creating portable applications, by preventing non-standard definitions from being exposed. Other macros can be used to expose non-standard definitions that are not exposed by default. -The precise effects of each of the feature test macros described below +The precise effects of each of the feature test macros described below can be ascertained by inspecting the .I <features.h> header file. @@ -45,21 +45,21 @@ In order to be effective, a feature test macro .IR "must be defined before including any header files" . This can either be done in the compilation command .RI ( "cc -DMACRO=value" ) -or by defining the macro within the source code before +or by defining the macro within the source code before including any headers. Linux/glibc understands the following feature test macros: .TP .B _POSIX_C_SOURCE -Defining this macro with the value 1 causes header files to expose +Defining this macro with the value 1 causes header files to expose definitions conforming to POSIX.1-1990 and ISO C (1990). -Defining with the value 199309 or greater additionally exposes +Defining with the value 199309 or greater additionally exposes definitions for POSIX.1b (real-time extensions). -Defining with the value 199506 or greater additionally exposes +Defining with the value 199506 or greater additionally exposes definitions for POSIX.1c (threads). -Defining with the value 200112 exposes definitions corresponding +Defining with the value 200112 exposes definitions corresponding to the POSIX.1-2001 base specification (excluding the XSI extension). -.TP +.TP .B _POSIX_SOURCE Defining this obsolete macro with any value is equivalent to defining .B _POSIX_C_SOURCE @@ -71,7 +71,7 @@ definitions conforming to POSIX.1, POSIX.2, and XPG4. Defining with the value 500 or greater additionally exposes definitions for SUSv2 (UNIX 98). Defining with the value 600 or greater additionally exposes -definitions for SUSv3 (UNIX 03; i.e., the POSIX.1-2001 base specification +definitions for SUSv3 (UNIX 03; i.e., the POSIX.1-2001 base specification plus the XSI extension) and C 99 definitions. .TP .B _XOPEN_SOURCE_EXTENDED @@ -84,28 +84,28 @@ UNIX extensions. Exposes C 99 extensions to ISO C (1990). .TP .B _LARGEFILE64_SOURCE -Expose definitions for the alternative API specified by the -LFS (Large File Summit) as a "transitional extension" to the -Single UNIX Specification. +Expose definitions for the alternative API specified by the +LFS (Large File Summit) as a "transitional extension" to the +Single UNIX Specification. (See http://opengroup.org/platform/lfs.html.) .TP .B _FILE_OFFSET_BITS -Defining this macro with the value 64 -automatically converts references to 32-bit functions and data types -related to file I/O and file system operations into references to +Defining this macro with the value 64 +automatically converts references to 32-bit functions and data types +related to file I/O and file system operations into references to their 64-bit counterparts. This is useful for performing I/O on large files (> 2 Gigabytes) on 32-bit systems. .TP .B _BSD_SOURCE -Defining this macro with any value cause header files to expose +Defining this macro with any value cause header files to expose BSD-derived definitions. Defining this macro also causes BSD definitions to be preferred in some situations where standards conflict. .TP .B _SVID_SOURCE -Defining this macro with any value cause header files to expose -System V-derived definitions. +Defining this macro with any value cause header files to expose +System V-derived definitions. (SVID == System V Interface Definition; see .BR standards (7).) .TP @@ -129,7 +129,7 @@ For multithreaded programs, use instead. .TP .B _THREAD_SAFE -Synonym for +Synonym for .BR _REENTRANT , provided for compatibility with some other implementations. .TP @@ -145,7 +145,7 @@ to detect some buffer overflow errors when employing various string and memory manipulation functions. Not all buffer overflows are detected, just some common cases. In the current implementation checks are added for -calls to +calls to .BR memcpy (3), .BR mempcpy (3), .BR memmove (3), @@ -159,21 +159,21 @@ calls to .BR snprintf (3), .BR vsprintf (3), .BR vsnprintf (3), -and +and .BR gets (3). -If -.B _FORTIFY_SOURCE -is set to 1, with compiler optimization level 1 +If +.B _FORTIFY_SOURCE +is set to 1, with compiler optimization level 1 .RI ( "gcc -O1" ) -and above, checks that shouldn't change the behaviour of +and above, checks that shouldn't change the behaviour of conforming programs are performed. -With -.B _FORTIFY_SOURCE +With +.B _FORTIFY_SOURCE set to 2 some more checking is added, but some conforming programs might fail. -Some of the checks can be performed at compile time, -and result in compiler warnings; -other checks take place at run time, +Some of the checks can be performed at compile time, +and result in compiler warnings; +other checks take place at run time, and result in a run-time error if the check fails. Use of this macro requires compiler support, available with .BR gcc (1) @@ -188,10 +188,10 @@ is invoked, the following macros are defined by default: and .BR _POSIX_C_SOURCE =199506. If individual macros are defined, then other macros are disabled -unless they are also explicitly defined. (Exception: -if +unless they are also explicitly defined. +(Exception: if .BR _POSIX_C_SOURCE -is not otherwise defined, +is not otherwise defined, then it is always defined with the value 200112 (199506 in glibc versions before 2.4), unless the compiler is invoked in one of its standard modes, e.g., the @@ -206,8 +206,8 @@ and .BR _XOPEN_SOURCE . .BR _XOPEN_SOURCE_EXTENDED was specified by XPG4v2 (aka SUSv1). -.BR _FILE_OFFSET_BITS -is not specified by any standard, +.BR _FILE_OFFSET_BITS +is not specified by any standard, but is employed on some other implementations. .BR _BSD_SOURCE , .BR _SVID_SOURCE , @@ -221,15 +221,15 @@ are Linux (glibc) specific. .I <features.h> is a Linux/glibc specific header file. Other systems have an analogous file, but typically with a different name. -This header file is automatically included by other header files as -required: it is not necessary to explicitly include it in order to +This header file is automatically included by other header files as +required: it is not necessary to explicitly include it in order to employ feature test macros. According to which of the above feature test macros are defined, .I <features.h> -internally defines various other macros that are checked by -other glibc header files. +internally defines various other macros that are checked by +other glibc header files. These macros have names prefixed by two underscores (e.g., __USE_MISC). Programs should \fInever\fP define these macros directly: -instead, the appropriate feature test macro(s) from the +instead, the appropriate feature test macro(s) from the list above should be employed. diff --git a/man7/fifo.7 b/man7/fifo.7 index 4733b82efe..d33b85fa4a 100644 --- a/man7/fifo.7 +++ b/man7/fifo.7 @@ -3,19 +3,21 @@ .\" of this page provided the header is included verbatim, .\" and in case of nontrivial modification author and date .\" of the modification is added to the header. -.\" +.\" .\" 990620 - page created - aeb@cwi.nl .\" -.TH FIFO 7 1999-06-20 "Linux" "Linux Programmer's Manual" +.TH FIFO 7 1999-06-20 "Linux" "Linux Programmer's Manual" .SH NAME fifo \- first-in first-out special file, named pipe .SH DESCRIPTION A FIFO special file (a named pipe) is similar to a pipe, except that it is accessed as part of the file system. It can be opened by multiple processes for reading or -writing. When processes are exchanging data via the FIFO, +writing. +When processes are exchanging data via the FIFO, the kernel passes all data internally without writing it -to the file system. Thus, the FIFO special file has no +to the file system. +Thus, the FIFO special file has no contents on the file system, the file system entry merely serves as a reference point so that processes can access the pipe using a name in the file system. @@ -23,19 +25,24 @@ the pipe using a name in the file system. The kernel maintains exactly one pipe object for each FIFO special file that is opened by at least one process. The FIFO must be opened on both ends (reading and writing) -before data can be passed. Normally, opening the FIFO blocks +before data can be passed. +Normally, opening the FIFO blocks until the other end is opened also. .PP -A process can open a FIFO in non-blocking mode. In this +A process can open a FIFO in non-blocking mode. +In this case, opening for read only will succeed even if no-one has opened on the write side yet; opening for write only will fail with ENXIO (no such device or address) unless the other end has already been opened. .PP Under Linux, opening a FIFO for read and write will succeed -both in blocking and non-blocking mode. POSIX leaves this -behaviour undefined. This can be used to open a FIFO for -writing while there are no readers available. A process +both in blocking and non-blocking mode. +POSIX leaves this +behaviour undefined. +This can be used to open a FIFO for +writing while there are no readers available. +A process that uses both ends of the connection in order to communicate with itself should be very careful to avoid deadlocks. .SH NOTES diff --git a/man7/futex.7 b/man7/futex.7 index b1ddc3ebfe..645de63b06 100644 --- a/man7/futex.7 +++ b/man7/futex.7 @@ -1,9 +1,9 @@ .\" This page is made available under the MIT license. .\" -.\" This manpage has been automatically generated by docbook2man +.\" This manpage has been automatically generated by docbook2man .\" from a DocBook document. This tool can be found at: -.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> -.\" Please send any bug reports, improvements, comments, patches, +.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, .\" etc. to Steve Cheng <steve@ggi-project.org>. .TH FUTEX 7 2002-12-31 "" "Linux Programmer's Manual" .SH NAME @@ -14,96 +14,97 @@ futex \- Fast Userspace Locking .fi .SH DESCRIPTION .PP -The Linux kernel provides futexes ('Fast Userspace muTexes') -as a building block for fast userspace -locking and semaphores. -Futexes are very basic and lend themselves well for building higher level +The Linux kernel provides futexes ('Fast Userspace muTexes') +as a building block for fast userspace +locking and semaphores. +Futexes are very basic and lend themselves well for building higher level locking abstractions such as POSIX mutexes. .PP -This page does not set out to document all design decisions -but restricts itself to issues relevant for -application and library development. -Most programmers will in fact not be using futexes directly but -instead rely on system libraries built on them, +This page does not set out to document all design decisions +but restricts itself to issues relevant for +application and library development. +Most programmers will in fact not be using futexes directly but +instead rely on system libraries built on them, such as the NPTL pthreads implementation. .PP -A futex is identified by a piece of memory which can be -shared between different processes. -In these different processes, it need not have identical addresses. -In its bare form, a futex has semaphore semantics; -it is a counter that can be incremented and decremented atomically; +A futex is identified by a piece of memory which can be +shared between different processes. +In these different processes, it need not have identical addresses. +In its bare form, a futex has semaphore semantics; +it is a counter that can be incremented and decremented atomically; processes can wait for the value to become positive. .PP -Futex operation is entirely userspace for the non-contended case. -The kernel is only involved to arbitrate the contended case. -As any sane design will strive for non-contention, +Futex operation is entirely userspace for the non-contended case. +The kernel is only involved to arbitrate the contended case. +As any sane design will strive for non-contention, futexes are also optimised for this situation. .PP -In its bare form, a futex is an aligned integer which is -only touched by atomic assembler instructions. -Processes can share this integer using -.BR mmap (), -via shared memory segments or because they share memory space, +In its bare form, a futex is an aligned integer which is +only touched by atomic assembler instructions. +Processes can share this integer using +.BR mmap (), +via shared memory segments or because they share memory space, in which case the application is commonly called multithreaded. .SH "SEMANTICS" .PP -Any futex operation starts in userspace, +Any futex operation starts in userspace, but it may necessary to communicate with the kernel using the \fBfutex\fR(2) system call. .PP -To 'up' a futex, execute the proper assembler instructions that -will cause the host CPU to atomically increment the integer. -Afterwards, check if it has in fact changed from 0 to 1, in which case -there were no waiters and the operation is done. +To 'up' a futex, execute the proper assembler instructions that +will cause the host CPU to atomically increment the integer. +Afterwards, check if it has in fact changed from 0 to 1, in which case +there were no waiters and the operation is done. This is the non-contended case which is fast and should be common. .PP -In the contended case, the atomic increment changed the counter -from \-1 (or some other negative number). -If this is detected, there are waiters. -Userspace should now set the counter to 1 and instruct the +In the contended case, the atomic increment changed the counter +from \-1 (or some other negative number). +If this is detected, there are waiters. +Userspace should now set the counter to 1 and instruct the kernel to wake up any waiters using the FUTEX_WAKE operation. .PP -Waiting on a futex, to 'down' it, is the reverse operation. -Atomically decrement the counter and check if it changed to 0, -in which case the operation is done and the futex was uncontended. -In all other circumstances, the process should set the counter to \-1 -and request that the kernel wait for another process to up the futex. +Waiting on a futex, to 'down' it, is the reverse operation. +Atomically decrement the counter and check if it changed to 0, +in which case the operation is done and the futex was uncontended. +In all other circumstances, the process should set the counter to \-1 +and request that the kernel wait for another process to up the futex. This is done using the FUTEX_WAIT operation. .PP -The -.BR futex () -system call can optionally be passed a timeout specifying how long +The +.BR futex () +system call can optionally be passed a timeout specifying how long the kernel should -wait for the futex to be upped. +wait for the futex to be upped. In this case, semantics are more complex and the programmer is referred to \fBfutex\fR(2) for -more details. The same holds for asynchronous futex waiting. +more details. +The same holds for asynchronous futex waiting. .SH "NOTES" .PP -To reiterate, bare futexes are not intended as an easy to use -abstraction for end-users. -Implementors are expected to be assembly literate and to have read +To reiterate, bare futexes are not intended as an easy to use +abstraction for end-users. +Implementors are expected to be assembly literate and to have read the sources of the futex userspace library referenced below. .PP -This man page illustrates the most common use of the \fBfutex\fR(2) +This man page illustrates the most common use of the \fBfutex\fR(2) primitives: it is by no means the only one. .SH "AUTHORS" .PP -Futexes were designed and worked on by Hubertus Franke -(IBM Thomas J. Watson Research Center), -Matthew Kirkwood, Ingo Molnar (Red Hat) and -Rusty Russell (IBM Linux Technology Center). +Futexes were designed and worked on by Hubertus Franke +(IBM Thomas J. Watson Research Center), +Matthew Kirkwood, Ingo Molnar (Red Hat) and +Rusty Russell (IBM Linux Technology Center). This page written by bert hubert. .SH "VERSIONS" .PP -Initial futex support was merged in Linux 2.5.7 +Initial futex support was merged in Linux 2.5.7 but with different semantics from those described above. Current semantics are available from Linux 2.5.40 onwards. .SH "SEE ALSO" .PP \fBfutex\fR(2), -`Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux' -(proceedings of the Ottawa Linux Symposium 2002), -futex example library, futex-*.tar.bz2 +`Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux' +(proceedings of the Ottawa Linux Symposium 2002), +futex example library, futex-*.tar.bz2 <URL:ftp://ftp.kernel.org:/pub/linux/kernel/people/rusty/>. diff --git a/man7/glob.7 b/man7/glob.7 index c27eda9451..81a073c0f6 100644 --- a/man7/glob.7 +++ b/man7/glob.7 @@ -38,9 +38,11 @@ that will perform this function for a user program. The rules are as follows (POSIX.2, 3.13). .SH "WILDCARD MATCHING" A string is a wildcard pattern if it contains one of the -characters `?', `*' or `['. Globbing is the operation +characters `?', `*' or `['. +Globbing is the operation that expands a wildcard pattern into the list of pathnames -matching the pattern. Matching is defined by: +matching the pattern. +Matching is defined by: A `?' (not between brackets) matches any single character. @@ -52,8 +54,8 @@ leading `[' is not an `!' matches a single character, namely any of the characters enclosed by the brackets. The string enclosed by the brackets cannot be empty; therefore `]' can be allowed between the brackets, provided -that it is the first character. (Thus, `[][!]' matches the -three characters `[', `]' and `!'.) +that it is the first character. +(Thus, `[][!]' matches the three characters `[', `]' and `!'.) .SS Ranges There is one special convention: two characters separated by `\-' denote a range. @@ -76,8 +78,10 @@ Between brackets these characters stand for themselves. Thus, `[[?*\e]' matches the four characters `[', `?', `*' and `\e'. .SH PATHNAMES Globbing is applied on each of the components of a pathname -separately. A `/' in a pathname cannot be matched by a `?' or `*' -wildcard, or by a range like `[.\-0]'. A range cannot contain an +separately. +A `/' in a pathname cannot be matched by a `?' or `*' +wildcard, or by a range like `[.\-0]'. +A range cannot contain an explicit `/' character; this would lead to a syntax error. If a filename starts with a `.', this character must be matched explicitly. @@ -86,7 +90,8 @@ archive all your files; `tar c .' is better.) .SH "EMPTY LISTS" The nice and simple rule given above: `expand a wildcard pattern into the list of matching pathnames' was the original Unix -definition. It allowed one to have patterns that expand into +definition. +It allowed one to have patterns that expand into an empty list, as in .br .nf @@ -102,7 +107,8 @@ With one can force the classical behaviour by setting .IR allow_null_glob_expansion=true . -(Similar problems occur elsewhere. E.g., where old scripts have +(Similar problems occur elsewhere. +E.g., where old scripts have .br .nf rm `find . \-name "*~"` @@ -118,7 +124,8 @@ called with an empty argument list.) .SH NOTES .SS Regular expressions Note that wildcard patterns are not regular expressions, -although they are a bit similar. First of all, they match +although they are a bit similar. +First of all, they match filenames, rather than text, and secondly, the conventions are not the same: e.g., in a regular expression `*' means zero or more copies of the preceding thing. @@ -132,7 +139,8 @@ so that `[\ \-%]' stands for `[\ !"#$%]' and `[a\-z]' stands for "any lowercase letter". Some Unix implementations generalized this so that a range X\-Y stands for the set of characters with code between the codes for -X and for Y. However, this requires the user to know the +X and for Y. +However, this requires the user to know the character coding in use on the local system, and moreover, is not convenient if the collating sequence for the local alphabet differs from the ordering of the character codes. @@ -140,7 +148,8 @@ Therefore, POSIX extended the bracket notation greatly, both for wildcard patterns and for regular expressions. In the above we saw three types of items that can occur in a bracket expression: namely (i) the negation, (ii) explicit single characters, -and (iii) ranges. POSIX specifies ranges in an internationally +and (iii) ranges. +POSIX specifies ranges in an internationally more useful way and adds three more types: (iii) Ranges X\-Y comprise all characters that fall between X @@ -163,13 +172,15 @@ in the current locale. (v) Collating symbols, like `[.ch.]' or `[.a-acute.]', where the string between `[.' and `.]' is a collating -element defined for the current locale. Note that this may +element defined for the current locale. +Note that this may be a multi-character element. (vi) Equivalence class expressions, like `[=a=]', where the string between `[=' and `=]' is any collating element from its equivalence class, as defined for the -current locale. For example, `[[=a=]]' might be equivalent +current locale. +For example, `[[=a=]]' might be equivalent to `[a����]' (warning: Latin-1 here), that is, to `[a[.a-acute.][.a-grave.][.a-umlaut.][.a-circumflex.]]'. .SH "SEE ALSO" diff --git a/man7/hier.7 b/man7/hier.7 index 7bb0323f2d..0ffe0428ff 100644 --- a/man7/hier.7 +++ b/man7/hier.7 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -33,22 +33,26 @@ hier \- Description of the file system hierarchy A typical Linux system has, among others, the following directories: .TP .I / -This is the root directory. This is where the whole tree starts. +This is the root directory. +This is where the whole tree starts. .TP .I /bin This directory contains executable programs which are needed in single user mode and to bring the system up or repair it. .TP .I /boot -Contains static files for the boot loader. This directory only holds -the files which are needed during the boot process. The map installer +Contains static files for the boot loader. +This directory only holds +the files which are needed during the boot process. +The map installer and configuration files should go to .I /sbin and .IR /etc . .TP .I /dev -Special or device files, which refer to physical devices. See +Special or device files, which refer to physical devices. +See .BR mknod (1). .TP .I /dos @@ -56,7 +60,8 @@ If both MS\-DOS and Linux are run on one computer, this is a typical place to mount a DOS file system. .TP .I /etc -Contains configuration files which are local to the machine. Some +Contains configuration files which are local to the machine. +Some larger software packages, like X11, can have their own subdirectories below .IR /etc . @@ -69,7 +74,7 @@ and you may have links for these files to .TP .I /etc/opt Host-specific configuration files for add-on applications installed -in +in .IR /opt . .TP .I /etc/sgml @@ -84,7 +89,8 @@ Configuration files for the X11 window system (optional). .TP .I /home On machines with home directories for users, these are usually beneath -this directory, directly or not. The structure of this directory +this directory, directly or not. +The structure of this directory depends on local administration decisions. .TP .I /lib @@ -101,7 +107,8 @@ This directory should contain add-on packages that contain static files. This is a mount point for the .I proc filesystem, which provides information about running processes and -the kernel. This pseudo-file system is described in more detail in +the kernel. +This pseudo-file system is described in more detail in .BR proc (5). .TP .I /root @@ -118,8 +125,8 @@ This directory contains temporary files which may be deleted with no notice, such as by a regular job or at system boot up. .TP .I /usr -This directory is usually mounted from a separate partition. It -should hold only sharable, read-only data, so that it can be mounted +This directory is usually mounted from a separate partition. +It should hold only sharable, read-only data, so that it can be mounted by various machines running Linux. .TP .I /usr/X11R6 @@ -136,18 +143,20 @@ Data files associated with the X\-Windows system. .TP .I /usr/X11R6/lib/X11 These contain miscellaneous files needed to run X; Often, there is a -symbolic link from +symbolic link from .I /usr/lib/X11 to this directory. .TP .I /usr/X11R6/include/X11 Contains include files needed for compiling programs using the X11 -window system. Often, there is a symbolic link from +window system. +Often, there is a symbolic link from .I /usr/include/X11 to this directory. .TP .I /usr/bin -This is the primary directory for executable programs. Most programs +This is the primary directory for executable programs. +Most programs executed by normal users which are not needed for booting or for repairing the system and which are not installed locally should be placed in this directory. @@ -167,10 +176,12 @@ Replaced by .TP .I /usr/etc Site-wide configuration files to be shared between several machines -may be stored in this directory. However, commands should always +may be stored in this directory. +However, commands should always reference those files using the .I /etc -directory. Links from files in +directory. +Links from files in .I /etc should point to the appropriate files in .IR /usr/etc . @@ -182,12 +193,14 @@ Binaries for games and educational programs (optional). Include files for the C compiler. .TP .I /usr/include/X11 -Include files for the C compiler and the X\-Windows system. This is +Include files for the C compiler and the X\-Windows system. +This is usually a symbolic link to .IR /usr/X11R6/include/X11 . .TP .I /usr/include/asm -Include files which declare some assembler functions. This used to be a +Include files which declare some assembler functions. +This used to be a symbolic link to .IR /usr/src/linux/include/asm . .TP @@ -198,14 +211,17 @@ system release and used to be a symbolic link to to get at operating system specific information. (Note that one should have include files there that work correctly with -the current libc and in user space. However, Linux kernel source is not +the current libc and in user space. +However, Linux kernel source is not designed to be used with user programs and does not know anything -about the libc you are using. It is very likely that things will break +about the libc you are using. +It is very likely that things will break if you let .I /usr/include/asm and .I /usr/include/linux -point at a random kernel tree. Debian systems don't do this +point at a random kernel tree. +Debian systems don't do this and use headers from a known good kernel version, provided in the libc*-dev package.) .TP @@ -214,12 +230,14 @@ Include files to use with the GNU C++ compiler. .TP .I /usr/lib Object libraries, including dynamic libraries, plus some executables -which usually are not invoked directly. More complicated programs may +which usually are not invoked directly. +More complicated programs may have whole subdirectories there. .TP .I /usr/lib/X11 The usual place for data files associated with X programs, and -configuration files for the X system itself. On Linux, it usually is +configuration files for the X system itself. +On Linux, it usually is a symbolic link to .IR /usr/X11R6/lib/X11 . .TP @@ -231,7 +249,7 @@ contains executables and include files for the GNU C compiler, Files for the GNU groff document formatting system. .TP .I /usr/lib/uucp -Files for +Files for .BR uucp (1). .TP .I /usr/local @@ -272,7 +290,7 @@ of the same OS. Source code for locally installed software. .TP .I /usr/man -Replaced by +Replaced by .IR /usr/share/man . .TP .I /usr/sbin @@ -293,7 +311,7 @@ or .TP .I /usr/share/dict Contains the word lists used by spell checkers. -.TP +.TP .I /usr/share/doc Documentation about installed programs. .TP @@ -311,8 +329,9 @@ Locale information goes here. Manual pages go here in subdirectories according to the man page sections. .TP .I /usr/share/man/<locale>/man[1\-9] -These directories contain manual pages for the specific locale in source code -form. Systems which use a unique language and code set for all manual pages +These directories contain manual pages for the +specific locale in source code form. +Systems which use a unique language and code set for all manual pages may omit the <locale> substring. .TP .I /usr/share/misc @@ -336,7 +355,8 @@ Files for timezone information. .TP .I /usr/src Source files for different parts of the system, included with some packages -for reference purposes. Don't work here with your own projects, as files +for reference purposes. +Don't work here with your own projects, as files below /usr should be read-only except when installing software. .TP .I /usr/src/linux @@ -345,7 +365,8 @@ Some distributions put here the source for the default kernel they ship. You should probably use another directory when building your own kernel. .TP .I /usr/tmp -Obsolete. This should be a link +Obsolete. +This should be a link to .IR /var/tmp . This link is present only for compatibility reasons and shouldn't be used. @@ -368,7 +389,8 @@ Data cached for programs. .TP .IR /var/catman/cat[1\-9] " or " /var/cache/man/cat[1\-9] These directories contain preformatted manual pages according to their -man page section. (The use of preformatted manual pages is deprecated.) +man page section. +(The use of preformatted manual pages is deprecated.) .TP .I /var/cron Reserved for historical reasons. @@ -381,7 +403,8 @@ Variable data for .IR /usr/local . .TP .I /var/lock -Lock files are placed in this directory. The naming convention for +Lock files are placed in this directory. +The naming convention for device lock files is .I LCK..<device> where @@ -395,11 +418,12 @@ character. Miscellaneous log files. .TP .I /var/opt -Variable data for +Variable data for .IR /opt . .TP .I /var/mail -Users' mailboxes. Replaces +Users' mailboxes. +Replaces .IR /var/spool/mail . .TP .I /var/msgs @@ -429,7 +453,7 @@ Spooled jobs for Spooled files for printing. .TP .I /var/spool/mail -Replaced by +Replaced by .IR /var/mail . .TP .I /var/spool/mqueue @@ -439,7 +463,7 @@ Queued outgoing mail. Spool directory for news. .TP .I /var/spool/rwho -Spooled files for +Spooled files for .BR rwhod (8). .TP .I /var/spool/smail diff --git a/man7/icmp.7 b/man7/icmp.7 index 738dc2c732..b98d5dda06 100644 --- a/man7/icmp.7 +++ b/man7/icmp.7 @@ -4,27 +4,28 @@ .\" and in case of nontrivial modification author and date .\" of the modification is added to the header. .\" $Id: icmp.7,v 1.6 2000/08/14 08:03:45 ak Exp $ -.TH ICMP 7 1999-04-27 "Linux Man Page" "Linux Programmer's Manual" +.TH ICMP 7 1999-04-27 "Linux Man Page" "Linux Programmer's Manual" .SH NAME -icmp, IPPROTO_ICMP \- Linux IPv4 ICMP kernel module. +icmp, IPPROTO_ICMP \- Linux IPv4 ICMP kernel module. .SH DESCRIPTION -This kernel protocol module implements the Internet Control -Message Protocol defined in RFC\ 792. +This kernel protocol module implements the Internet Control +Message Protocol defined in RFC\ 792. It is used to signal error conditions and for diagnosis. -The user doesn't interact directly with this module; -instead it communicates with the other protocols in the kernel -and these pass the ICMP errors to the application layers. +The user doesn't interact directly with this module; +instead it communicates with the other protocols in the kernel +and these pass the ICMP errors to the application layers. The kernel ICMP module also answers ICMP requests. .PP A user protocol may receive ICMP packets for all local sockets by opening -a raw socket with the protocol +a raw socket with the protocol .BR IPPROTO_ICMP . See .BR raw (7) for more information. The types of ICMP packets passed to the socket can be filtered using the -.B ICMP_FILTER -socket option. ICMP packets are always processed by the kernel too, even +.B ICMP_FILTER +socket option. +ICMP packets are always processed by the kernel too, even when passed to a user socket. .LP Linux limits the rate of ICMP error packets to each destination. @@ -34,22 +35,22 @@ and are also limited by the destination route of the incoming packets. .SH SYSCTLS ICMP supports a sysctl interface to configure some global IP parameters. -The sysctls can be accessed by reading or writing the -.I /proc/sys/net/ipv4/* -files or with the +The sysctls can be accessed by reading or writing the +.I /proc/sys/net/ipv4/* +files or with the .BR sysctl (2) -interface. +interface. Most of these sysctls are rate limitations for specific ICMP types. -Linux 2.2 uses a token bucket filter to limit ICMPs. +Linux 2.2 uses a token bucket filter to limit ICMPs. .\" FIXME better description needed -The value is the timeout in jiffies until the token bucket filter is -cleared after a burst. +The value is the timeout in jiffies until the token bucket filter is +cleared after a burst. A jiffy is a system dependent unit, usually 10ms on x86 and about 1ms on alpha and IA64. .TP .B icmp_destunreach_rate -Maximum rate to send ICMP Destination Unreachable packets. -This limits the rate at which packets are sent to any individual +Maximum rate to send ICMP Destination Unreachable packets. +This limits the rate at which packets are sent to any individual route or destination. The limit does not affect sending of .B ICMP_FRAG_NEEDED @@ -58,17 +59,17 @@ packets needed for path MTU discovery. .B icmp_echo_ignore_all If this value is non-zero, Linux will ignore all .B ICMP_ECHO -requests. +requests. .TP .B icmp_echo_ignore_broadcasts If this value is non-zero, Linux will ignore all .B ICMP_ECHO -packets sent to broadcast addresses. +packets sent to broadcast addresses. .TP .B icmp_echoreply_rate Maximum rate for sending .B ICMP_ECHOREPLY -packets in response to +packets in response to .B ICMP_ECHOREQUEST packets. .TP @@ -81,11 +82,12 @@ These packets are sent when a packet arrives with an invalid IP header. .B icmp_timeexceed_rate Maximum rate for sending .B ICMP_TIME_EXCEEDED -packets. These packets are -sent to prevent loops when a packet has crossed too many hops. +packets. +These packets are +sent to prevent loops when a packet has crossed too many hops. .SH NOTES -As many other implementations don't support -.B IPPROTO_ICMP +As many other implementations don't support +.B IPPROTO_ICMP raw sockets, this feature should not be relied on in portable programs. .\" not really true ATM @@ -94,14 +96,14 @@ should not be relied on in portable programs. .PP .B ICMP_REDIRECT packets are not sent when Linux is not acting as a router. -They are also only accepted from the old gateway defined in the +They are also only accepted from the old gateway defined in the routing table and the redirect routes are expired after some time. .PP The 64-bit timestamp returned by .B ICMP_TIMESTAMP is in milliseconds since January 1, 1970. .PP -Linux ICMP internally uses a raw socket to send ICMPs. +Linux ICMP internally uses a raw socket to send ICMPs. This raw socket may appear in .BR netstat (8) output with a zero inode. diff --git a/man7/inotify.7 b/man7/inotify.7 index 8e09ff7b34..61a1099d38 100644 --- a/man7/inotify.7 +++ b/man7/inotify.7 @@ -11,12 +11,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -25,29 +25,29 @@ inotify \- monitoring file system events .SH DESCRIPTION The -.I inotify +.I inotify API provides a mechanism for monitoring file system events. Inotify can be used to monitor individual files, or to monitor directories. When a directory is monitored, inotify will return events for the directory itself, and for files inside the directory. -The following system calls are used with this API: +The following system calls are used with this API: .BR inotify_init (), .BR inotify_add_watch (), .BR inotify_rm_watch (), .BR read (), -and +and .BR close (). .BR inotify_init (2) -creates an inotify instance and returns a file descriptor +creates an inotify instance and returns a file descriptor referring to the inotify instance. .BR inotify_add_watch (2) manipulates the "watch list" associated with an inotify instance. Each item ("watch") in the watch list specifies the pathname of -a file or directory, +a file or directory, along with some set of events that the kernel should monitor for the file referred to by that pathname. .BR inotify_add_watch () @@ -60,16 +60,16 @@ when the watch is created. .BR inotify_rm_watch (2) removes an item from an inotify watch list. -When all file descriptors referring to an inotify +When all file descriptors referring to an inotify instance have been closed, -the underlying object and its resources are +the underlying object and its resources are freed for re-use by the kernel; all associated watches are automatically freed. To determine what events have occurred, an application .BR read (2)s from the inotify file descriptor. -If no events have so far occurred, then, +If no events have so far occurred, then, assuming a blocking file descriptor, .BR read () will block until at least one event occurs. @@ -83,7 +83,7 @@ returns a buffer containing one or more of the following structures: struct inotify_event { int wd; /* Watch descriptor */ uint32_t mask; /* Mask of events */ - uint32_t cookie; /* Unique cookie associating related + uint32_t cookie; /* Unique cookie associating related events (for rename(2)) */ uint32_t len; /* Size of 'name' field */ char name[]; /* Optional null-terminated name */ @@ -93,7 +93,7 @@ struct inotify_event { .I wd identifies the watch for which this event occurs. -It is one of the watch descriptors returned by a previous call to +It is one of the watch descriptors returned by a previous call to .BR inotify_add_watch (). .I mask @@ -104,33 +104,33 @@ is a unique integer that connects related events. Currently this is only used for rename events, and allows the resulting pair of .B IN_MOVE_FROM -and +and .B IN_MOVE_TO events to be connected by the application. -The +The .I name field is only present when an event is returned -for a file inside a watched directory; +for a file inside a watched directory; it identifies the file pathname relative to the watched directory. -This pathname is null-terminated, +This pathname is null-terminated, and may include further null bytes to align subsequent reads to a suitable address boundary. The .I len -field counts all of the bytes in +field counts all of the bytes in .IR name , -including the null bytes; +including the null bytes; the length of each .I inotify_event structure is thus .IR "sizeof(inotify_event)+len" . .SS inotify events -The +The .BR inotify_add_watch (2) .I mask -argument and the +argument and the .I mask field of the .I inotify_event @@ -142,7 +142,7 @@ The following bits can be specified in .I mask when calling .BR inotify_add_watch () -and may be returned in the +and may be returned in the .I mask field returned by .BR read (): @@ -152,7 +152,7 @@ lB lB lB l. Bit Description IN_ACCESS File was accessed (read) (*) -IN_ATTRIB Metadata changed (permissions, timestamps, +IN_ATTRIB Metadata changed (permissions, timestamps, extended attributes, etc.) (*) IN_CLOSE_WRITE File opened for writing was closed (*) IN_CLOSE_NOWRITE File not opened for writing was closed (*) @@ -167,8 +167,8 @@ IN_OPEN File was opened (*) .TE .in -0.25i .PP -When monitoring a directory, -the events marked with an asterisk (*) above can occur for +When monitoring a directory, +the events marked with an asterisk (*) above can occur for files in the directory, in which case the .I name field in the returned @@ -192,7 +192,7 @@ and which equates to IN_CLOSE_WRITE|IN_CLOSE_NOWRITE. .PP -The following further bits can be specified in +The following further bits can be specified in .I mask when calling .BR inotify_add_watch (): @@ -201,10 +201,10 @@ when calling lB lB lB l. Bit Description -IN_DONT_FOLLOW Don't dereference \fIpathname\fP if it is a symbolic link +IN_DONT_FOLLOW Don't dereference \fIpathname\fP if it is a symbolic link IN_MASK_ADD Add (OR) events to watch mask for this pathname if it already exists (instead of replacing mask) -IN_ONESHOT Monitor \fIpathname\fP for one event, then remove from +IN_ONESHOT Monitor \fIpathname\fP for one event, then remove from watch list IN_ONLYDIR Only watch \fIpathname\fP if it is a directory .TE @@ -219,7 +219,7 @@ field returned by lB lB lB l. Bit Description -IN_IGNORED Watch was removed explicitly (\fBinotify_rm_watch\fP()) +IN_IGNORED Watch was removed explicitly (\fBinotify_rm_watch\fP()) or automatically (file was deleted, or file system was unmounted) IN_ISDIR Subject of this event is a directory @@ -228,51 +228,51 @@ IN_UNMOUNT File system containing watched object was unmounted .TE .in -0.25i .SS /proc interfaces -The following interfaces can be used to limit the amount of +The following interfaces can be used to limit the amount of kernel memory consumed by inotify: .TP .IR /proc/sys/fs/inotify/max_queued_events The value in this file is used when an application calls .BR inotify_init (2) -to set an upper limit on the number of events that can be +to set an upper limit on the number of events that can be queued to the corresponding inotify instance. Events in excess of this limit are dropped, but an .B IN_Q_OVERFLOW event is always generated. .TP .IR /proc/sys/fs/inotify/max_user_instances -This specifies an upper limit on the number of inotify instances +This specifies an upper limit on the number of inotify instances that can be created per real user ID. .TP .IR /proc/sys/fs/inotify/max_user_watches -This specifies a limit on the number of watches that can be associated +This specifies a limit on the number of watches that can be associated with each inotify instance. .SH "NOTES" Inotify file descriptors can be monitored using .BR select (2), .BR poll (2), -and +and .BR epoll (7). -If successive output inotify events produced on the -inotify file descriptor are identical (same -.IR wd , -.IR mask , +If successive output inotify events produced on the +inotify file descriptor are identical (same +.IR wd , +.IR mask , .IR cookie , and .IR name ) then they are coalesced into a single event. -The events returned by reading from an inotify file descriptor -form an ordered queue. -Thus, for example, it is guaranteed that when renaming from -one directory to another, events will be produced in the +The events returned by reading from an inotify file descriptor +form an ordered queue. +Thus, for example, it is guaranteed that when renaming from +one directory to another, events will be produced in the correct order on the inotify file descriptor. The .B FIONREAD .BR ioctl () -returns the number of bytes available to read from an +returns the number of bytes available to read from an inotify file descriptor. Inotify monitoring of directories is not recursive: @@ -284,17 +284,17 @@ The required library interfaces were added to glibc in version 2.4. .SH "BUGS" In kernels before 2.6.16, the .B IN_ONESHOT -.I mask +.I mask flag does not work. -As at glibc 2.4, the definitions for -.BR IN_DONT_FOLLOW , +As at glibc 2.4, the definitions for +.BR IN_DONT_FOLLOW , .BR IN_MASK_ADD , -and -.B IN_ONLYDIR -are missing from +and +.B IN_ONLYDIR +are missing from .IR <sys/inotify.h> . -.\" FIXME . but these definitions were added to the glibc on 17 May 06: +.\" FIXME . but these definitions were added to the glibc on 17 May 06: .\" check later to see in which glibc version these changes are actually .\" released. .SH "CONFORMING TO" diff --git a/man7/intro.7 b/man7/intro.7 index 2423231552..1522026cea 100644 --- a/man7/intro.7 +++ b/man7/intro.7 @@ -21,19 +21,20 @@ .\" License along with this manual; if not, write to the Free .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, .\" USA. -.\" +.\" .\" Modified by Thomas Koenig (ig25@rz.uni-karlsruhe.de) 24 Apr 1993 .\" Modified Sat Jul 24 17:28:08 1993 by Rik Faith (faith@cs.unc.edu) .TH INTRO 7 1993-04-23 "Linux" "Linux Programmer's Manual" .SH NAME intro \- Introduction to overview, conventions, and miscellany section .SH DESCRIPTION -This chapter provides overviews on various topics, and -describes conventions and protocols, +This chapter provides overviews on various topics, and +describes conventions and protocols, character set standards, the standard file system layout, and miscellaneous other things. .SH AUTHORS Look at the header of the manual page for the author(s) and copyright -conditions. Note that these can be different from page to page! +conditions. +Note that these can be different from page to page! .SH "SEE ALSO" .BR standards (7) @@ -6,7 +6,7 @@ .\" and in case of nontrivial modification author and date .\" of the modification is added to the header. .\" $Id: ip.7,v 1.19 2000/12/20 18:10:31 ak Exp $ -.TH IP 7 2001-06-19 "Linux Man Page" "Linux Programmer's Manual" +.TH IP 7 2001-06-19 "Linux Man Page" "Linux Programmer's Manual" .SH NAME ip \- Linux IPv4 protocol implementation .SH SYNOPSIS @@ -21,40 +21,40 @@ ip \- Linux IPv4 protocol implementation .IB tcp_socket " = socket(PF_INET, SOCK_STREAM, 0);" .br .IB udp_socket " = socket(PF_INET, SOCK_DGRAM, 0);" -.br +.br .IB raw_socket " = socket(PF_INET, SOCK_RAW, " protocol ");" .SH DESCRIPTION -Linux implements the Internet Protocol, version 4, -described in RFC\ 791 and RFC\ 1122. -.B ip -contains a level 2 -multicasting implementation conforming to RFC\ 1112. +Linux implements the Internet Protocol, version 4, +described in RFC\ 791 and RFC\ 1122. +.B ip +contains a level 2 +multicasting implementation conforming to RFC\ 1112. It also contains an IP router including a packet filter. .\" FIXME has someone verified that 2.1 is really 1812 compliant? .PP The programming interface is BSD sockets compatible. -For more information on sockets, see -.BR socket (7). +For more information on sockets, see +.BR socket (7). .PP An IP socket is created by calling the -.BR socket (2) -function as +.BR socket (2) +function as .BR "socket(PF_INET, socket_type, protocol)" . -Valid socket types are -.B SOCK_STREAM -to open a -.BR tcp (7) -socket, +Valid socket types are +.B SOCK_STREAM +to open a +.BR tcp (7) +socket, .B SOCK_DGRAM to open a .BR udp (7) socket, or .B SOCK_RAW -to open a +to open a .BR raw (7) -socket to access the IP protocol directly. -.I protocol -is the IP protocol in the IP header to be received or sent. +socket to access the IP protocol directly. +.I protocol +is the IP protocol in the IP header to be received or sent. The only valid values for .I protocol are @@ -64,25 +64,27 @@ and for TCP sockets and .B 0 and -.B IPPROTO_UDP -for UDP sockets. For -.B SOCK_RAW +.B IPPROTO_UDP +for UDP sockets. +For +.B SOCK_RAW you may specify -a valid IANA IP protocol defined in +a valid IANA IP protocol defined in RFC\ 1700 assigned numbers. .PP -.\" FIXME ip current does an autobind in listen, but I'm not sure +.\" FIXME ip current does an autobind in listen, but I'm not sure .\" if that should be documented. -When a process wants to receive new incoming packets or connections, it +When a process wants to receive new incoming packets or connections, it should bind a socket to a local interface address using .BR bind (2). Only one IP socket may be bound to any given local (address, port) pair. -When -.B INADDR_ANY +When +.B INADDR_ANY is specified in the bind call the socket will be bound to .I all -local interfaces. When +local interfaces. +When .BR listen (2) or .BR connect (2) @@ -90,17 +92,18 @@ are called on an unbound socket, it is automatically bound to a random free port with the local address set to .BR INADDR_ANY . -A TCP local socket address that has been bound is unavailable for +A TCP local socket address that has been bound is unavailable for some time after closing, -unless the +unless the .B SO_REUSEADDR -flag has been set. Care should be taken when using this flag as it -makes TCP less reliable. +flag has been set. +Care should be taken when using this flag as it +makes TCP less reliable. .SH "ADDRESS FORMAT" -An IP socket address is defined as a combination of an IP interface +An IP socket address is defined as a combination of an IP interface address and a 16-bit port number. The basic IP protocol does not supply port numbers, they -are implemented by higher level protocols like +are implemented by higher level protocols like .BR udp (7) and .BR tcp (7). @@ -123,35 +126,35 @@ struct in_addr { .fi .in -0.25i .PP -.I sin_family -is always set to -.BR AF_INET . -This is required; in Linux 2.2 most networking functions return +.I sin_family +is always set to +.BR AF_INET . +This is required; in Linux 2.2 most networking functions return .B EINVAL when this setting is missing. .I sin_port -contains the port in network byte order. +contains the port in network byte order. The port numbers below 1024 are called .IR "reserved ports" . Only privileged processes (i.e., those having the -.B CAP_NET_BIND_SERVICE -capability) may -.BR bind (2) -to these sockets. -Note that the raw IPv4 protocol as such has no concept of a +.B CAP_NET_BIND_SERVICE +capability) may +.BR bind (2) +to these sockets. +Note that the raw IPv4 protocol as such has no concept of a port, they are only implemented by higher protocols like .BR tcp (7) and .BR udp (7). .PP -.I sin_addr +.I sin_addr is the IP host address. -The +The .I s_addr -member of +member of .I struct in_addr -contains the host interface address in network byte order. -.I in_addr +contains the host interface address in network byte order. +.I in_addr should be assigned one of the INADDR_* values (e.g., INADDR_ANY) or set using the .BR inet_aton (3), @@ -159,35 +162,36 @@ or set using the .BR inet_makeaddr (3) library functions or directly with the name resolver (see .BR gethostbyname (3)). -IPv4 addresses are divided into unicast, broadcast -and multicast addresses. +IPv4 addresses are divided into unicast, broadcast +and multicast addresses. Unicast addresses specify a single interface of a host, -broadcast addresses specify all hosts on a network and multicast -addresses address all hosts in a multicast group. -Datagrams to broadcast addresses can be only sent or received when the +broadcast addresses specify all hosts on a network and multicast +addresses address all hosts in a multicast group. +Datagrams to broadcast addresses can be only sent or received when the .B SO_BROADCAST socket flag is set. -In the current implementation connection oriented sockets are only allowed +In the current implementation connection oriented sockets are only allowed to use unicast addresses. .\" Leave a loophole for XTP @) -Note that the address and the port are always stored in +Note that the address and the port are always stored in network byte order. In particular, this means that you need to call -.BR htons (3) -on the number that is assigned to a port. All address/port manipulation +.BR htons (3) +on the number that is assigned to a port. +All address/port manipulation functions in the standard library work in network byte order. -There are several special addresses: +There are several special addresses: .B INADDR_LOOPBACK (127.0.0.1) always refers to the local host via the loopback device; -.B INADDR_ANY +.B INADDR_ANY (0.0.0.0) means any address for binding; .B INADDR_BROADCAST (255.255.255.255) -means any host and has the same effect on bind as +means any host and has the same effect on bind as .B INADDR_ANY for historical reasons. .SH "SOCKET OPTIONS" @@ -195,24 +199,26 @@ IP supports some protocol specific socket options that can be set with .BR setsockopt (2) and read with .BR getsockopt (2). -The socket option level for IP is +The socket option level for IP is .BR IPPROTO_IP . .\" or SOL_IP on Linux A boolean integer flag is zero when it is false, otherwise true. -.\" +.\" .\" FIXME Document IP_FREEBIND .\" .TP .B IP_OPTIONS Sets or get the IP options to be sent with every packet from this -socket. -The arguments are a pointer to a memory buffer containing the options +socket. +The arguments are a pointer to a memory buffer containing the options and the option length. The .BR setsockopt (2) call sets the IP options associated with a socket. -The maximum option size for IPv4 is 40 bytes. See RFC\ 791 for the allowed -options. When the initial connection request packet for a +The maximum option size for IPv4 is 40 bytes. +See RFC\ 791 for the allowed +options. +When the initial connection request packet for a .B SOCK_STREAM socket contains IP options, the IP options will be set automatically to the options from the initial packet with routing headers reversed. @@ -221,7 +227,8 @@ is established. The processing of all incoming source routing options is disabled by default and can be enabled by using the .B accept_source_route -sysctl. Other options like timestamps are still handled. +sysctl. +Other options like timestamps are still handled. For datagram sockets, IP options can be only set by the local user. Calling .BR getsockopt (2) @@ -232,12 +239,12 @@ puts the current IP options used for sending into the supplied buffer. .B IP_PKTINFO Pass an .I IP_PKTINFO -ancillary message that contains a -.I pktinfo +ancillary message that contains a +.I pktinfo structure that supplies some information about the incoming packet. This only works for datagram oriented sockets. -The argument is a flag that tells the socket whether the IP_PKTINFO -message should be passed or not. +The argument is a flag that tells the socket whether the IP_PKTINFO +message should be passed or not. The message itself can only be sent/retrieved as control message with a packet using .BR recvmsg (2) @@ -249,7 +256,7 @@ or struct in_pktinfo { unsigned int ipi_ifindex; /* Interface index */ struct in_addr ipi_spec_dst; /* Local address */ - struct in_addr ipi_addr; /* Header Destination + struct in_addr ipi_addr; /* Header Destination address */ }; .fi @@ -263,7 +270,7 @@ is the local address of the packet and .I ipi_addr is the destination address in the packet header. If -.I IP_PKTINFO +.I IP_PKTINFO is passed to .BR sendmsg (2) and @@ -279,43 +286,46 @@ index overwrites for the routing table lookup. .TP .B IP_RECVTOS -If enabled the -.I IP_TOS -ancillary message is passed with incoming packets. -It contains a byte which specifies the Type of Service/Precedence +If enabled the +.I IP_TOS +ancillary message is passed with incoming packets. +It contains a byte which specifies the Type of Service/Precedence field of the packet header. -Expects a boolean integer flag. +Expects a boolean integer flag. .TP .B IP_RECVTTL When this flag is set -pass a -.I IP_TTL -control message with the time to live -field of the received packet as a byte. Not supported for +pass a +.I IP_TTL +control message with the time to live +field of the received packet as a byte. +Not supported for .B SOCK_STREAM sockets. .TP .B IP_RECVOPTS Pass all incoming IP options to the user in a -.I IP_OPTIONS -control message. +.I IP_OPTIONS +control message. The routing header and other options are already filled in -for the local host. Not supported for -.I SOCK_STREAM +for the local host. +Not supported for +.I SOCK_STREAM sockets. .TP .B IP_RETOPTS -Identical to +Identical to .I IP_RECVOPTS but returns raw unprocessed options with timestamp and route record options not filled in for this hop. .TP .B IP_TOS -Set or receive the Type-Of-Service (TOS) field that is sent -with every IP packet originating from this socket. +Set or receive the Type-Of-Service (TOS) field that is sent +with every IP packet originating from this socket. It is used to prioritize packets on the network. -TOS is a byte. There are some standard TOS flags defined: -.B IPTOS_LOWDELAY +TOS is a byte. +There are some standard TOS flags defined: +.B IPTOS_LOWDELAY to minimize delays for interactive traffic, .B IPTOS_THROUGHPUT to optimize throughput, @@ -323,33 +333,35 @@ to optimize throughput, to optimize for reliability, .B IPTOS_MINCOST should be used for "filler data" where slow transmission doesn't matter. -At most one of these TOS values can be specified. +At most one of these TOS values can be specified. Other bits are invalid and shall be cleared. -Linux sends -.B IPTOS_LOWDELAY +Linux sends +.B IPTOS_LOWDELAY datagrams first by default, -but the exact behaviour depends on the configured queueing discipline. -.\" FIXME elaborate on this +but the exact behaviour depends on the configured queueing discipline. +.\" FIXME elaborate on this Some high priority levels may require superuser privileges (the .B CAP_NET_ADMIN capability). The priority can also be set in a protocol independent way by the .RB ( SOL_SOCKET ", " SO_PRIORITY ) socket option (see -.BR socket (7)). -.TP +.BR socket (7)). +.TP .B IP_TTL Set or retrieve the current time to live field that is used in every packet sent from this socket. .TP .B IP_HDRINCL -If enabled -the user supplies an IP header in front of the user data. -Only valid for -.B SOCK_RAW -sockets. See +If enabled +the user supplies an IP header in front of the user data. +Only valid for +.B SOCK_RAW +sockets. +See .BR raw (7) -for more information. When this flag is enabled the values set by +for more information. +When this flag is enabled the values set by .IR IP_OPTIONS , .I IP_TTL and @@ -357,29 +369,31 @@ and are ignored. .TP .BR IP_RECVERR " (defined in <linux/errqueue.h>)" -Enable extended reliable error message passing. +Enable extended reliable error message passing. When enabled on a datagram socket all -generated errors will be queued in a per-socket error queue. When the user +generated errors will be queued in a per-socket error queue. +When the user receives an error from a socket operation the errors can -be received by calling -.BR recvmsg (2) -with the -.B MSG_ERRQUEUE -flag set. The -.I sock_extended_err -structure describing the error will be passed in a ancillary message with -the type -.I IP_RECVERR -and the level -.BR IPPROTO_IP . +be received by calling +.BR recvmsg (2) +with the +.B MSG_ERRQUEUE +flag set. +The +.I sock_extended_err +structure describing the error will be passed in a ancillary message with +the type +.I IP_RECVERR +and the level +.BR IPPROTO_IP . .\" or SOL_IP on Linux This is useful for reliable error handling on unconnected sockets. The received data portion of the error queue contains the error packet. .IP -The -.I IP_RECVERR -control message contains a +The +.I IP_RECVERR +control message contains a .I sock_extended_err structure: .IP @@ -393,118 +407,126 @@ structure: struct sock_extended_err { u_int32_t ee_errno; /* error number */ - u_int8_t ee_origin; /* where the error originated */ + u_int8_t ee_origin; /* where the error originated */ u_int8_t ee_type; /* type */ u_int8_t ee_code; /* code */ u_int8_t ee_pad; u_int32_t ee_info; /* additional information */ - u_int32_t ee_data; /* other data */ - /* More data may follow */ + u_int32_t ee_data; /* other data */ + /* More data may follow */ }; struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *); .fi .in -0.25i .IP -.I ee_errno -contains the errno number of the queued error. +.I ee_errno +contains the errno number of the queued error. .I ee_origin -is the origin code of where the error originated. -The other fields are protocol specific. The macro -.B SO_EE_OFFENDER +is the origin code of where the error originated. +The other fields are protocol specific. +The macro +.B SO_EE_OFFENDER returns a pointer to the address of the network object where the error originated from given a pointer to the ancillary message. If this address is not known, the -.I sa_family -member of the -.I sockaddr -contains +.I sa_family +member of the +.I sockaddr +contains .B AF_UNSPEC -and the other fields of the -.I sockaddr -are undefined. +and the other fields of the +.I sockaddr +are undefined. .IP -IP uses the +IP uses the .I sock_extended_err structure as follows: -.I ee_origin -is set to -.B SO_EE_ORIGIN_ICMP +.I ee_origin +is set to +.B SO_EE_ORIGIN_ICMP for errors received as an ICMP packet, or -.B SO_EE_ORIGIN_LOCAL -for locally generated errors. Unknown values should be ignored. -.I ee_type -and -.I ee_code +.B SO_EE_ORIGIN_LOCAL +for locally generated errors. +Unknown values should be ignored. +.I ee_type +and +.I ee_code are set from the type and code fields of the ICMP header. .I ee_info -contains the discovered MTU for -.B EMSGSIZE -errors. The message also contains the +contains the discovered MTU for +.B EMSGSIZE +errors. +The message also contains the .I sockaddr_in of the node -caused the error, which can be accessed with the +caused the error, which can be accessed with the .B SO_EE_OFFENDER -macro. The +macro. +The .I sin_family -field of the SO_EE_OFFENDER address is +field of the SO_EE_OFFENDER address is .I AF_UNSPEC when the source was unknown. -When the error originated from the network, all IP options +When the error originated from the network, all IP options .RI ( IP_OPTIONS ", " IP_TTL ", " -etc.) enabled on the socket and contained in the -error packet are passed as control messages. The payload of the packet +etc.) enabled on the socket and contained in the +error packet are passed as control messages. +The payload of the packet causing the error is returned as normal payload. .\" FIXME . Is it a good idea to document that? It is a dubious feature. -.\" On -.\" .B SOCK_STREAM +.\" On +.\" .B SOCK_STREAM .\" sockets, -.\" .I IP_RECVERR +.\" .I IP_RECVERR .\" has slightly different semantics. Instead of .\" saving the errors for the next timeout, it passes all incoming -.\" errors immediately to the user. +.\" errors immediately to the user. .\" This might be useful for very short-lived TCP connections which -.\" need fast error handling. Use this option with care: +.\" need fast error handling. Use this option with care: .\" it makes TCP unreliable -.\" by not allowing it to recover properly from routing +.\" by not allowing it to recover properly from routing .\" shifts and other normal -.\" conditions and breaks the protocol specification. -Note that TCP has no error queue; -.B MSG_ERRQUEUE +.\" conditions and breaks the protocol specification. +Note that TCP has no error queue; +.B MSG_ERRQUEUE is illegal on -.B SOCK_STREAM -sockets. -.B IP_RECVERR +.B SOCK_STREAM +sockets. +.B IP_RECVERR is valid for TCP, but all errors are -returned by socket function return or -.B SO_ERROR +returned by socket function return or +.B SO_ERROR only. .IP For raw sockets, -.I IP_RECVERR +.I IP_RECVERR enables passing of all received ICMP errors to the application, otherwise errors are only reported on connected sockets .IP -It sets or retrieves an integer boolean flag. +It sets or retrieves an integer boolean flag. .I IP_RECVERR -defaults to off. +defaults to off. .TP .B IP_MTU_DISCOVER Sets or receives the Path MTU Discovery setting -for a socket. When enabled, Linux will perform Path MTU Discovery +for a socket. +When enabled, Linux will perform Path MTU Discovery as defined in RFC\ 1191 -on this socket. The don't fragment flag is set on all outgoing datagrams. -The system-wide default is controlled by the -.B ip_no_pmtu_disc -sysctl for -.B SOCK_STREAM -sockets, and disabled on all others. For non -.B SOCK_STREAM -sockets it is the user's responsibility to packetize the data -in MTU sized chunks and to do the retransmits if necessary. +on this socket. +The don't fragment flag is set on all outgoing datagrams. +The system-wide default is controlled by the +.B ip_no_pmtu_disc +sysctl for +.B SOCK_STREAM +sockets, and disabled on all others. +For non +.B SOCK_STREAM +sockets it is the user's responsibility to packetize the data +in MTU sized chunks and to do the retransmits if necessary. The kernel will reject packets that are bigger than the known path MTU if this flag is set (with .B EMSGSIZE -). +). .TS tab(:); c l @@ -512,32 +534,34 @@ l l. Path MTU discovery flags:Meaning IP_PMTUDISC_WANT:Use per-route settings. IP_PMTUDISC_DONT:Never do Path MTU Discovery. -IP_PMTUDISC_DO:Always do Path MTU Discovery. +IP_PMTUDISC_DO:Always do Path MTU Discovery. IP_PMTUDISC_PROBE:Set DF but ignore Path MTU. -.TE +.TE When PMTU discovery is enabled the kernel automatically keeps track of -the path MTU per destination host. +the path MTU per destination host. When it is connected to a specific peer with .BR connect (2) -the currently known path MTU can be retrieved conveniently using the -.B IP_MTU -socket option (e.g. after a -.B EMSGSIZE -error occurred). It may change over time. -For connectionless sockets with many destinations -the new also MTU for a given destination can also be accessed using the -error queue (see +the currently known path MTU can be retrieved conveniently using the +.B IP_MTU +socket option (e.g. after a +.B EMSGSIZE +error occurred). +It may change over time. +For connectionless sockets with many destinations +the new also MTU for a given destination can also be accessed using the +error queue (see .BR IP_RECVERR ). A new error will be queued for every incoming MTU update. While MTU discovery is in progress initial packets from datagram sockets -may be dropped. Applications using UDP should be aware of this and not +may be dropped. +Applications using UDP should be aware of this and not take it into account for their packet retransmit strategy. To bootstrap the path MTU discovery process on unconnected sockets it is possible to start with a big datagram size -(up to 64K-headers bytes long) and let it shrink by updates of the +(up to 64K-headers bytes long) and let it shrink by updates of the path MTU. .\" FIXME this is an ugly hack @@ -548,65 +572,69 @@ and retrieve the MTU by calling .BR getsockopt (2) with the .B IP_MTU -option. +option. It is possible to implement RFC 4821 MTU probing with .B SOCK_DGRAM of .B SOCK_RAW -sockets by setting a value of +sockets by setting a value of .BR IP_PMTUDISC_PROBE . This is also particularly useful for diagnostic tools such as .BR tracepath (8) -that wish to deliberately send probe packets larger than +that wish to deliberately send probe packets larger than the observed Path MTU. .TP .B IP_MTU -Retrieve the current known path MTU of the current socket. -Only valid when the socket has been connected. Returns an integer. -Only valid as a -.BR getsockopt (2). +Retrieve the current known path MTU of the current socket. +Only valid when the socket has been connected. +Returns an integer. +Only valid as a +.BR getsockopt (2). .\" .TP .B IP_ROUTER_ALERT -Pass all to-be forwarded packets with the -IP Router Alert -option -set to this socket. Only valid for raw sockets. +Pass all to-be forwarded packets with the +IP Router Alert +option +set to this socket. +Only valid for raw sockets. This is useful, for instance, for user -space RSVP daemons. -The tapped packets are not forwarded by the kernel, it is -the users responsibility to send them out again. +space RSVP daemons. +The tapped packets are not forwarded by the kernel, it is +the users responsibility to send them out again. Socket binding is ignored, such packets are only filtered by protocol. -Expects an integer flag. +Expects an integer flag. .\" .TP .B IP_MULTICAST_TTL Set or reads the time-to-live value of outgoing multicast packets for this -socket. It is -very important for multicast packets to set the smallest TTL possible. +socket. +It is very important for multicast packets to set the smallest TTL possible. The default is 1 which means that multicast packets don't leave the local -network unless the user program explicitly requests it. Argument is an +network unless the user program explicitly requests it. +Argument is an integer. .\" .TP .B IP_MULTICAST_LOOP -Sets or reads a boolean integer argument whether sent multicast +Sets or reads a boolean integer argument whether sent multicast packets should be looped back to the local sockets. .\" .TP .B IP_ADD_MEMBERSHIP -Join a multicast group. Argument is an +Join a multicast group. +Argument is an .I ip_mreqn -structure. +structure. .sp .in +0.25i .nf struct ip_mreqn { - struct in_addr imr_multiaddr; /* IP multicast group + struct in_addr imr_multiaddr; /* IP multicast group address */ - struct in_addr imr_address; /* IP address of local + struct in_addr imr_address; /* IP address of local interface */ int imr_ifindex; /* interface index */ }; @@ -614,60 +642,64 @@ struct ip_mreqn { .in -0.25i .sp .I imr_multiaddr -contains the address of the multicast group the application +contains the address of the multicast group the application wants to join or leave. -It must be a valid multicast address. +It must be a valid multicast address. .I imr_address -is the address of the local interface with which the system +is the address of the local interface with which the system should join the multicast -group; if it is equal to +group; if it is equal to .B INADDR_ANY an appropriate interface is chosen by the system. .I imr_ifindex is the interface index of the interface that should join/leave the -.I imr_multiaddr -group, or 0 to indicate any interface. +.I imr_multiaddr +group, or 0 to indicate any interface. .IP -For compatibility, the old -.I ip_mreq -structure is still supported. It differs from -.I ip_mreqn +For compatibility, the old +.I ip_mreq +structure is still supported. +It differs from +.I ip_mreqn only by not including -the -.I imr_ifindex -field. Only valid as a +the +.I imr_ifindex +field. +Only valid as a .BR setsockopt (2). .\" .TP .B IP_DROP_MEMBERSHIP -Leave a multicast group. Argument is an -.I ip_mreqn -or -.I ip_mreq +Leave a multicast group. +Argument is an +.I ip_mreqn +or +.I ip_mreq structure similar to -.IR IP_ADD_MEMBERSHIP . +.IR IP_ADD_MEMBERSHIP . .\" .TP .B IP_MULTICAST_IF -Set the local device for a multicast socket. Argument is an -.I ip_mreqn -or -.I ip_mreq -structure similar to +Set the local device for a multicast socket. +Argument is an +.I ip_mreqn +or +.I ip_mreq +structure similar to .IR IP_ADD_MEMBERSHIP . .IP When an invalid socket option is passed, .B ENOPROTOOPT -is returned. +is returned. .SH SYSCTLS The IP protocol -supports the sysctl interface to configure some global options. -The sysctls can be accessed by reading or writing the -.I /proc/sys/net/ipv4/* +supports the sysctl interface to configure some global options. +The sysctls can be accessed by reading or writing the +.I /proc/sys/net/ipv4/* files or using the .\" FIXME As at 2.6.12, 14 Jun 2005, the following are undocumented: .\" ip_queue_maxlen -.\" ip_conntrack_max +.\" ip_conntrack_max .BR sysctl (2) interface. Variables described as @@ -678,12 +710,12 @@ meaning that the option is disabled. .\" .TP .BR ip_always_defrag " (Boolean)" -[New with kernel 2.2.13; in earlier kernel version the feature +[New with kernel 2.2.13; in earlier kernel version the feature was controlled at compile time by the -.B CONFIG_IP_ALWAYS_DEFRAG +.B CONFIG_IP_ALWAYS_DEFRAG option; this file is not present in 2.4.x and later] -When this boolean frag is enabled (not equal 0) incoming fragments +When this boolean frag is enabled (not equal 0) incoming fragments (parts of IP packets that arose when some host between origin and destination decided that the packets were too large and cut them into pieces) will be @@ -692,8 +724,10 @@ about to be forwarded. Only enable if running either a firewall that is the sole link to your network or a transparent proxy; never ever turn on here for a -normal router or host. Otherwise fragmented communication may me disturbed -when the fragments would travel over different links. Defragmentation +normal router or host. +Otherwise fragmented communication may me disturbed +when the fragments would travel over different links. +Defragmentation also has a large memory and CPU time cost. This is automagically turned on when masquerading or transparent @@ -706,50 +740,50 @@ Not documented. .\" .TP .BR ip_default_ttl " (integer; default: 64)" -Set the default time-to-live value of outgoing packets. -This can be changed per socket with the -.I IP_TTL +Set the default time-to-live value of outgoing packets. +This can be changed per socket with the +.I IP_TTL option. .\" .TP .BR ip_dynaddr " (Boolean; default: disabled)" -Enable dynamic socket address and masquerading entry rewriting on interface -address change. +Enable dynamic socket address and masquerading entry rewriting on interface +address change. This is useful for dialup interface with changing IP addresses. 0 means no rewriting, 1 turns it on and 2 enables verbose mode. .\" .TP .BR ip_forward " (Boolean; default: disabled)" -Enable IP forwarding with a boolean flag. -IP forwarding can be also set on a per interface basis. +Enable IP forwarding with a boolean flag. +IP forwarding can be also set on a per interface basis. .\" .TP .BR ip_local_port_range -Contains two integers that define the default local port range -allocated to sockets. +Contains two integers that define the default local port range +allocated to sockets. Allocation starts with the first number and ends with the second number. -Note that these should not conflict with the ports used by masquerading -(although the case is handled). -Also arbitrary choices may cause problems with some firewall packet +Note that these should not conflict with the ports used by masquerading +(although the case is handled). +Also arbitrary choices may cause problems with some firewall packet filters that make assumptions about the local ports in use. -First number should be at least >1024, better >4096 to avoid clashes -with well known ports and to minimize firewall problems. +First number should be at least >1024, better >4096 to avoid clashes +with well known ports and to minimize firewall problems. .\" .TP .BR ip_no_pmtu_disc " (Boolean; default: disabled)" -If enabled, don't do Path MTU Discovery for TCP sockets by default. -Path MTU discovery may fail if misconfigured firewalls (that drop -all ICMP packets) or misconfigured interfaces (e.g., a point-to-point -link where the both ends don't agree on the MTU) are on the path. -It is better to fix the broken routers on the path than to turn off -Path MTU Discovery globally, because not doing it incurs a high cost +If enabled, don't do Path MTU Discovery for TCP sockets by default. +Path MTU discovery may fail if misconfigured firewalls (that drop +all ICMP packets) or misconfigured interfaces (e.g., a point-to-point +link where the both ends don't agree on the MTU) are on the path. +It is better to fix the broken routers on the path than to turn off +Path MTU Discovery globally, because not doing it incurs a high cost to the network. .\" .\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt .TP .BR ip_nonlocal_bind " (Boolean; default: disabled)" -If set, allows processes to -.BR bind () +If set, allows processes to +.BR bind () to non-local IP addresses, which can be quite useful, but may break some applications. .\" @@ -765,53 +799,55 @@ Regeneration interval (in seconds) of the hash secret (or lifetime for the hash secret) for IPv6 fragments. .TP .BR ipfrag_high_thresh " (integer), " ipfrag_low_thresh " (integer)" -If the amount of queued IP fragments reaches +If the amount of queued IP fragments reaches .BR ipfrag_high_thresh , -the queue -is pruned down to -.BR ipfrag_low_thresh . -Contains an integer with the number of +the queue +is pruned down to +.BR ipfrag_low_thresh . +Contains an integer with the number of bytes. .TP .B neigh/* -See -.BR arp (7). -.\" FIXME Document the conf/*/* sysctls +See +.BR arp (7). +.\" FIXME Document the conf/*/* sysctls .\" FIXME Document the route/* sysctls .\" FIXME document them all .SH IOCTLS All ioctls described in -.BR socket (7) +.BR socket (7) apply to ip. .\" 2006-04-02, mtk .\" commented out the following because ipchains is obsolete -.\" .PP +.\" .PP .\" The ioctls to configure firewalling are documented in .\" .BR ipfw (4) -.\" from the -.\" .B ipchains -.\" package. +.\" from the +.\" .B ipchains +.\" package. .PP -Ioctls to configure generic device parameters are described in -.BR netdevice (7). +Ioctls to configure generic device parameters are described in +.BR netdevice (7). .\" FIXME Add a discussion of multicasting .SH NOTES -Be very careful with the +Be very careful with the .B SO_BROADCAST -option \- it is not privileged in Linux. +option \- it is not privileged in Linux. It is easy to overload the network -with careless broadcasts. For new application protocols -it is better to use a multicast group instead of broadcasting. -Broadcasting is discouraged. +with careless broadcasts. +For new application protocols +it is better to use a multicast group instead of broadcasting. +Broadcasting is discouraged. .PP -Some other BSD sockets implementations provide -.I IP_RCVDSTADDR -and -.I IP_RECVIF -socket options to get the destination address and the interface of -received datagrams. Linux has the more general +Some other BSD sockets implementations provide +.I IP_RCVDSTADDR +and +.I IP_RECVIF +socket options to get the destination address and the interface of +received datagrams. +Linux has the more general .I IP_PKTINFO -for the same task. +for the same task. .PP Some BSD sockets implementations also provide an .I IP_RECVTTL @@ -828,30 +864,30 @@ socket options level isn't portable, BSD-based stacks use .I IPPROTO_IP level. .SH ERRORS -.\" FIXME document all errors. +.\" FIXME document all errors. .\" We should really fix the kernels to give more uniform -.\" error returns (ENOMEM vs ENOBUFS, EPERM vs EACCES etc.) +.\" error returns (ENOMEM vs ENOBUFS, EPERM vs EACCES etc.) .TP .B ENOTCONN The operation is only defined on a connected socket, but the socket wasn't connected. .TP .B EINVAL -Invalid argument passed. -For send operations this can be caused by sending to a +Invalid argument passed. +For send operations this can be caused by sending to a .I blackhole route. .TP -.B EMSGSIZE +.B EMSGSIZE Datagram is bigger than an MTU on the path and it cannot be fragmented. .TP .B EACCES -The user tried to execute an operation without the necessary permissions. +The user tried to execute an operation without the necessary permissions. These include: -sending a packet to a broadcast address without having the +sending a packet to a broadcast address without having the .B SO_BROADCAST flag set; -sending a packet via a +sending a packet via a .I prohibit route; modifying firewall settings without superuser privileges (the @@ -872,7 +908,7 @@ User doesn't have permission to set high priority, change configuration, or send signals to the requested process or group. .TP .B EADDRNOTAVAIL -A non-existent interface was requested or the requested source +A non-existent interface was requested or the requested source address was not local. .TP @@ -891,30 +927,30 @@ An connection operation on a non-blocking socket is already in progress. .TP .B ECONNABORTED A connection was closed during an -.BR accept (2). +.BR accept (2). .TP .B EPIPE The connection was unexpectedly closed or shut down by the other end. .TP .B ENOENT -.B SIOCGSTAMP +.B SIOCGSTAMP was called on a socket where no packet arrived. .TP .B EHOSTUNREACH -No valid routing table entry matches the destination address. -This error can be caused by a ICMP message from a remote router or +No valid routing table entry matches the destination address. +This error can be caused by a ICMP message from a remote router or for the local routing table. .TP -.B ENODEV +.B ENODEV Network device not available or not capable of sending IP. .TP -.B ENOPKG +.B ENOPKG A kernel subsystem was not configured. .TP .BR ENOBUFS ", " ENOMEM -Not enough free memory. -This often means that the memory allocation is limited by the socket -buffer limits, not by the system memory, but this is not +Not enough free memory. +This often means that the memory allocation is limited by the socket +buffer limits, not by the system memory, but this is not 100% consistent. .PP Other errors may be generated by the overlaying protocols; see @@ -924,9 +960,9 @@ Other errors may be generated by the overlaying protocols; see and .BR socket (7). .SH VERSIONS -.IR IP_MTU , -.IR IP_MTU_DISCOVER , -.IR IP_PKTINFO , +.IR IP_MTU , +.IR IP_MTU_DISCOVER , +.IR IP_PKTINFO , .I IP_RECVERR and .I IP_ROUTER_ALERT @@ -939,25 +975,27 @@ programs intended to be portable. .I IP_PMTUDISC_PROBE is new in Linux 2.6.22. .PP -.I struct ip_mreqn -is new in Linux 2.2. Linux 2.0 only supported +.I struct ip_mreqn +is new in Linux 2.2. +Linux 2.0 only supported .BR ip_mreq . .PP -The sysctls were introduced with Linux 2.2. +The sysctls were introduced with Linux 2.2. .SH COMPATIBILITY -For compatibility with Linux 2.0, the obsolete +For compatibility with Linux 2.0, the obsolete .BI "socket(PF_INET, SOCK_PACKET, " protocol ) -syntax is still supported to open a -.BR packet (7) -socket. This is deprecated and should be replaced by +syntax is still supported to open a +.BR packet (7) +socket. +This is deprecated and should be replaced by .BI "socket(PF_PACKET, SOCK_RAW, " protocol ) -instead. The main difference is the -new -.I sockaddr_ll -address structure for generic link layer information instead of the old +instead. +The main difference is the new +.I sockaddr_ll +address structure for generic link layer information instead of the old .BR sockaddr_pkt . .SH BUGS -There are too many inconsistent error values. +There are too many inconsistent error values. .PP The ioctls to configure IP-specific interface options and ARP tables are not described. @@ -974,7 +1012,7 @@ by .BR recvmsg (2) does not work in some 2.2 kernels. .\" .SH AUTHORS -.\" This man page was written by Andi Kleen. +.\" This man page was written by Andi Kleen. .SH "SEE ALSO" .BR recvmsg (2), .BR sendmsg (2), diff --git a/man7/ipv6.7 b/man7/ipv6.7 index 8e2fd65421..a9b9395be1 100644 --- a/man7/ipv6.7 +++ b/man7/ipv6.7 @@ -10,52 +10,55 @@ ipv6, PF_INET6 \- Linux IPv6 protocol implementation .SH SYNOPSIS .B #include <sys/socket.h> .br -.B #include <netinet/in.h> +.B #include <netinet/in.h> .sp .IB tcp6_socket " = socket(PF_INET6, SOCK_STREAM, 0);" -.br +.br .IB raw6_socket " = socket(PF_INET6, SOCK_RAW, " protocol ");" .br .IB udp6_socket " = socket(PF_INET6, SOCK_DGRAM, " protocol ");" .SH DESCRIPTION -Linux 2.2 optionally implements the Internet Protocol, version 6. -This man page contains a description of the IPv6 basic API as -implemented by the Linux kernel and glibc 2.1. The interface +Linux 2.2 optionally implements the Internet Protocol, version 6. +This man page contains a description of the IPv6 basic API as +implemented by the Linux kernel and glibc 2.1. +The interface is based on the BSD sockets interface; see -.BR socket (7). +.BR socket (7). .PP -The IPv6 API aims to be mostly compatible with the -.BR ip (7) -v4 API. Only differences are described in this man page. +The IPv6 API aims to be mostly compatible with the +.BR ip (7) +v4 API. +Only differences are described in this man page. .PP -To bind an +To bind an .I AF_INET6 -socket to any process the local address should be copied from the +socket to any process the local address should be copied from the .B in6addr_any -variable which has -.I in6_addr +variable which has +.I in6_addr type. -In static initializations +In static initializations .B IN6ADDR_ANY_INIT may also be used, which expands to a constant expression. Both of them are in network order. .PP The IPv6 loopback address (::1) is available in the global .B in6addr_loopback -variable. For initializations +variable. +For initializations .B IN6ADDR_LOOPBACK_INIT should be used. .PP -IPv4 connections can be handled with the v6 API by using the -v4-mapped-on-v6 address type; +IPv4 connections can be handled with the v6 API by using the +v4-mapped-on-v6 address type; thus a program only needs only to support this API type to -support both protocols. +support both protocols. This is handled transparently by the address -handling functions in libc. +handling functions in libc. .PP -IPv4 and IPv6 share the local port space. +IPv4 and IPv6 share the local port space. When you get an IPv4 connection -or packet to a IPv6 socket its source address will be mapped +or packet to a IPv6 socket its source address will be mapped to v6 and it'll be mapped to v6. .SH "ADDRESS FORMAT" .sp @@ -66,7 +69,7 @@ struct sockaddr_in6 { u_int16_t sin6_port; /* port number */ u_int32_t sin6_flowinfo; /* IPv6 flow information */ struct in6_addr sin6_addr; /* IPv6 address */ - u_int32_t sin6_scope_id; /* Scope ID (new in 2.4) */ + u_int32_t sin6_scope_id; /* Scope ID (new in 2.4) */ }; struct in6_addr { @@ -75,20 +78,20 @@ struct in6_addr { .fi .RE .sp -.B sin6_family -is always set to -.BR AF_INET6 ; -.B sin6_port +.B sin6_family +is always set to +.BR AF_INET6 ; +.B sin6_port is the protocol port (see .B sin_port -in +in .BR ip (7)); .B sin6_flowinfo is the IPv6 flow identifier; .B sin6_addr is the 128bit IPv6 address. -.B sin6_scope_id -is an ID of depending of on the scope of the address. +.B sin6_scope_id +is an ID of depending of on the scope of the address. It is new in Linux 2.4. Linux only supports it for link scope addresses, in that case .I sin6_scope_id @@ -96,14 +99,14 @@ contains the interface index (see .BR netdevice (7)) .PP IPv6 supports several address types: unicast to address a single -host, multicast to address a group of hosts, -anycast to address the nearest member of a group of hosts +host, multicast to address a group of hosts, +anycast to address the nearest member of a group of hosts (not implemented in Linux), IPv4-on-IPv6 to address a IPv4 host, and other reserved address types. .PP -The address notation for IPv6 is a group of 16 2 digit hexadecimal -numbers, separated with a ':'. '::' stands for a string of 0 bits. -Special addresses are ::1 for loopback and ::FFFF:<IPv4 address> +The address notation for IPv6 is a group of 16 2 digit hexadecimal +numbers, separated with a ':'. '::' stands for a string of 0 bits. +Special addresses are ::1 for loopback and ::FFFF:<IPv4 address> for IPv4-mapped-on-IPv6. .PP The port space of IPv6 is shared with IPv4. @@ -112,24 +115,27 @@ IPv6 supports some protocol specific socket options that can be set with .BR setsockopt (2) and read with .BR getsockopt (2). -The socket option level for IPv6 is +The socket option level for IPv6 is .BR IPPROTO_IPV6 . A boolean integer flag is zero when it is false, otherwise true. .TP .B IPV6_ADDRFORM -Turn an +Turn an .I AF_INET6 -socket into a socket of a different address family. Only +socket into a socket of a different address family. +Only .I AF_INET -is currently supported for that. It is only allowed for IPv6 sockets -that are connected and bound to a v4-mapped-on-v6 address. The argument -is a pointer to a integer containing -.BR AF_INET . -This is useful to pass v4-mapped sockets as file descriptors to +is currently supported for that. +It is only allowed for IPv6 sockets +that are connected and bound to a v4-mapped-on-v6 address. +The argument is a pointer to a integer containing +.BR AF_INET . +This is useful to pass v4-mapped sockets as file descriptors to programs that don't know how to deal with the IPv6 API. .TP .B IPV6_ADD_MEMBERSHIP, IPV6_DROP_MEMBERSHIP -Control membership in multicast groups. Argument is a pointer to a +Control membership in multicast groups. +Argument is a pointer to a .I struct ipv6_mreq structure. .\" FIXME IPV6_CHECKSUM is not documented, and probably should be @@ -138,33 +144,36 @@ structure. .\" FIXME IPV6_V6ONLY is not documented, and probably should be .\" FIXME IPV6_RECVPKTINFO is not documented, and probably should be .\" FIXME IPV6_2292PKTINFO is not documented, and probably should be -.\" FIXME there are probably many other IPV6_* socket options that +.\" FIXME there are probably many other IPV6_* socket options that .\" should be documented .TP .B IPV6_MTU -Set the MTU to be used for the socket. The MTU is limited by the device +Set the MTU to be used for the socket. +The MTU is limited by the device MTU or the path mtu when path mtu discovery is enabled. Argument is a pointer to integer. .TP .B IPV6_MTU_DISCOVER -Control path mtu discovery on the socket. See +Control path mtu discovery on the socket. +See .I IP_MTU_DISCOVER -in +in .BR ip (7) for details. .TP .B IPV6_MULTICAST_HOPS -Set the multicast hop limit for the socket. Argument is a pointer to an -integer. -\-1 in the value means use the route default, otherwise it should be +Set the multicast hop limit for the socket. +Argument is a pointer to an +integer. +\-1 in the value means use the route default, otherwise it should be between 0 and 255. -.TP +.TP .B IPV6_MULTICAST_IF Set the device for outgoing multicast packets on the socket. This is only allowed -for +for .I SOCK_DGRAM -and +and .I SOCK_RAW socket. The argument is an pointer to an interface index (see @@ -174,21 +183,23 @@ in an integer. .B IPV6_MULTICAST_LOOP Control whether the socket sees multicast packets that it has send itself. Argument is a pointer to boolean. -.TP +.TP .B IPV6_PKTINFO -Set delivery of the -.B IPV6_PKTINFO -control message on incoming datagrams. Only allowed for +Set delivery of the +.B IPV6_PKTINFO +control message on incoming datagrams. +Only allowed for .B SOCK_DGRAM or .B SOCK_RAW -sockets. Argument is a pointer to a boolean value in an integer. +sockets. +Argument is a pointer to a boolean value in an integer. .TP .nh .B IPV6_RTHDR, IPV6_AUTHHDR, IPV6_DSTOPS, IPV6_HOPOPTS, IPV6_FLOWINFO, IPV6_HOPLIMIT .hy -Set delivery of control messages for incoming datagrams containing -extension headers from the received packet. +Set delivery of control messages for incoming datagrams containing +extension headers from the received packet. .I IPV6_RTHDR delivers the routing header, .I IPV6_AUTHHDR @@ -196,23 +207,25 @@ delivers the authentication header, .I IPV6_DSTOPTS delivers the destination options, .I IPV6_HOPOPTS -delivers the hop options, +delivers the hop options, .I IPV6_FLOWINFO delivers an integer containing the flow ID, .I IPV6_HOPLIMIT -delivers an integer containing the hop count of the packet. -The control messages have the same type as the socket option. All these -header options can also be set for outgoing packets -by putting the appropriate control message into the control buffer of +delivers an integer containing the hop count of the packet. +The control messages have the same type as the socket option. +All these header options can also be set for outgoing packets +by putting the appropriate control message into the control buffer of .BR sendmsg (2). Only allowed for .B SOCK_DGRAM or .B SOCK_RAW -sockets. Argument is a pointer to a boolean value. +sockets. +Argument is a pointer to a boolean value. .TP .B IPV6_RECVERR -Control receiving of asynchronous error options. See +Control receiving of asynchronous error options. +See .I IP_RECVERR in .BR ip (7) @@ -220,52 +233,56 @@ for details. Argument is a pointer to boolean. .TP .B IPV6_ROUTER_ALERT -Pass all forwarded packets containing an router alert option to +Pass all forwarded packets containing an router alert option to this socket. -Only allowed for datagram sockets and for root. +Only allowed for datagram sockets and for root. Argument is a pointer to boolean. .TP .B IPV6_UNICAST_HOPS -Set the unicast hop limit for the socket. Argument is an pointer to an -integer. \-1 in the value means use the route default, +Set the unicast hop limit for the socket. +Argument is an pointer to an integer. +\-1 in the value means use the route default, otherwise it should be between 0 and 255. .\" FLOWLABEL_MGR, FLOWINFO_SEND .SH VERSIONS -The older +The older .I libinet6 libc5 based IPv6 API implementation for Linux is not described here -and may vary in details. +and may vary in details. .PP -Linux 2.4 will break binary compatibility for the sockaddr_in6 for 64bit +Linux 2.4 will break binary compatibility for the sockaddr_in6 for 64bit hosts by changing the alignment of -.I in6_addr -and adding an additional +.I in6_addr +and adding an additional .I sin6_scope_id -field. The kernel interfaces stay compatible, but a program including -sockaddr_in6 or in6_addr into other structures may not be. This is not +field. +The kernel interfaces stay compatible, but a program including +sockaddr_in6 or in6_addr into other structures may not be. +This is not a problem for 32bit hosts like i386. .PP The .B sin6_flowinfo -field is new in Linux 2.4. It is transparently passed/read by the kernel -when the passed address length contains it. -Some programs that pass a longer address buffer and then +field is new in Linux 2.4. +It is transparently passed/read by the kernel +when the passed address length contains it. +Some programs that pass a longer address buffer and then check the outgoing address length may break. .SH "PORTING NOTES" The .I sockaddr_in6 structure is bigger than the generic -.BR sockaddr . -Programs that assume that all address types can be stored safely in a +.BR sockaddr . +Programs that assume that all address types can be stored safely in a .I struct sockaddr -need to be changed to use +need to be changed to use .I struct sockaddr_storage for that instead. .SH BUGS -The IPv6 extended API as in RFC\ 2292 is currently only partly +The IPv6 extended API as in RFC\ 2292 is currently only partly implemented; although the 2.2 kernel has near complete support for receiving options, -the macros for generating IPv6 options are missing in glibc 2.1. +the macros for generating IPv6 options are missing in glibc 2.1. .PP IPSec support for EH and AH headers is missing. .PP @@ -276,6 +293,7 @@ This man page is not complete. .BR cmsg (3), .BR ip (7) .PP -RFC\ 2553: IPv6 BASIC API. Linux tries to be compliant to this. +RFC\ 2553: IPv6 BASIC API. +Linux tries to be compliant to this. .PP -RFC\ 2460: IPv6 specification. +RFC\ 2460: IPv6 specification. diff --git a/man7/iso_8859-1.7 b/man7/iso_8859-1.7 index c0f574eddd..b2180f03c3 100644 --- a/man7/iso_8859-1.7 +++ b/man7/iso_8859-1.7 @@ -30,7 +30,8 @@ iso_8859-1 \- the ISO 8859-1 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). Especially important is +character set (also known as ISO 646-IRV). +Especially important is ISO 8859-1, the "Latin Alphabet No. 1", which has become widely implemented and may already be seen as the de-facto standard ASCII replacement. @@ -66,7 +67,8 @@ ISO 8859-16 Romanian (Latin-10) The following table displays the characters in ISO 8859-1 (Latin-1), which are printable and unlisted in the .BR ascii (7) -manual page. The fourth column will only show the proper glyphs +manual page. +The fourth column will only show the proper glyphs in an environment configured for ISO 8859-1. .TS l l l c lp-1. diff --git a/man7/iso_8859-15.7 b/man7/iso_8859-15.7 index 9946d305a5..110788fcc5 100644 --- a/man7/iso_8859-15.7 +++ b/man7/iso_8859-15.7 @@ -28,11 +28,14 @@ iso_8859-15 \- the ISO 8859-15 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). Especially important is +character set (also known as ISO 646-IRV). +Especially important is ISO 8859-1, the "Latin Alphabet No. 1", which has become widely implemented and may already be seen as the de-facto standard ASCII -replacement. However, it lacks the EURO symbol and does not fully -cover Finnish and French. ISO 8859-15 is a modification of ISO 8859-1 +replacement. +However, it lacks the EURO symbol and does not fully +cover Finnish and French. +ISO 8859-15 is a modification of ISO 8859-1 that covers these needs. .P ISO 8859-15 supports the following languages: Albanian, Basque, Breton, @@ -64,7 +67,8 @@ ISO 8859-16 Romanian (Latin-10) The following table displays the characters in ISO 8859-15 (Latin-9), which are printable and unlisted in the .BR ascii (7) -manual page. The fourth column will only show the proper glyphs +manual page. +The fourth column will only show the proper glyphs in an environment configured for ISO 8859-15. .TS l l l c lp-1. diff --git a/man7/iso_8859-16.7 b/man7/iso_8859-16.7 index 303f9cad81..f665e4c91f 100644 --- a/man7/iso_8859-16.7 +++ b/man7/iso_8859-16.7 @@ -28,13 +28,14 @@ iso_8859-16 \- the ISO 8859-16 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). ISO 8859-16, the "Latin +character set (also known as ISO 646-IRV). +ISO 8859-16, the "Latin Alphabet No. 10" is used to encode Central and Eastern European Latin characters and is not implemented yet by any program vendors. .P ISO 8859-16 supports the following languages: Albanian, Bosnian, Croatian, English, Finnish, German, Hungarian, Irish, Polish, -Romanian, Slovenian and Serbian. +Romanian, Slovenian and Serbian. .P Also note that the following Cyrillic-based languages have one-to-one transliterations to Latin 10: Macedonian and Serbian. @@ -62,7 +63,8 @@ ISO 8859-16 Romanian (Latin-10) The following table displays the characters in ISO 8859-16 (Latin-10), which are printable and unlisted in the .BR ascii (7) -manual page. The fourth column will only show the proper glyphs +manual page. +The fourth column will only show the proper glyphs in an environment configured for ISO 8859-16. .TS l l l c lp-1. diff --git a/man7/iso_8859-2.7 b/man7/iso_8859-2.7 index 4a859395d0..1e2efdf6e8 100644 --- a/man7/iso_8859-2.7 +++ b/man7/iso_8859-2.7 @@ -31,7 +31,8 @@ iso_8859-2 \- the ISO 8859-2 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). ISO 8859-2, the "Latin +character set (also known as ISO 646-IRV). +ISO 8859-2, the "Latin Alphabet No. 2" is used to encode Central and Eastern European Latin characters and is implemented by several program vendors. .P @@ -65,7 +66,8 @@ ISO 8859-16 Romanian (Latin-10) The following table displays the characters in ISO 8859-2 (Latin-2), which are printable and unlisted in the .BR ascii (7) -manual page. The fourth column will only show the proper glyphs +manual page. +The fourth column will only show the proper glyphs in an environment configured for ISO 8859-2. .TS l l l c lp-1. diff --git a/man7/iso_8859-7.7 b/man7/iso_8859-7.7 index 2251004809..c9d8f2611b 100644 --- a/man7/iso_8859-7.7 +++ b/man7/iso_8859-7.7 @@ -27,7 +27,8 @@ iso_8859-7 \- the ISO 8859-7 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). ISO 8859-7 encodes the +character set (also known as ISO 646-IRV). +ISO 8859-7 encodes the characters used in modern monotonic Greek. .SS "ISO 8859 Alphabets" The full set of ISO 8859 alphabets includes: @@ -53,7 +54,8 @@ ISO 8859-16 Romanian (Latin-10) The following table displays the characters in ISO 8859-7, which are printable and unlisted in the .BR ascii (7) -manual page. The fourth column will only show the proper glyphs +manual page. +The fourth column will only show the proper glyphs in an environment configured for ISO 8859-7. .TS l l l c lp-1. diff --git a/man7/iso_8859-9.7 b/man7/iso_8859-9.7 index 9ab429d7bc..25be153104 100644 --- a/man7/iso_8859-9.7 +++ b/man7/iso_8859-9.7 @@ -27,7 +27,8 @@ iso_8859-9 \- the ISO 8859-9 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). ISO 8859-9, also known as +character set (also known as ISO 646-IRV). +ISO 8859-9, also known as the "Latin Alphabet No. 5", encodes the characters used in Turkish. .SS "ISO 8859 Alphabets" The full set of ISO 8859 alphabets includes: @@ -53,7 +54,8 @@ ISO 8859-16 Romanian (Latin-10) The following table displays the characters in ISO 8859-9 (Latin-5), which are printable and unlisted in the .BR ascii (7) -manual page. The fourth column will only show the proper glyphs +manual page. +The fourth column will only show the proper glyphs in an environment configured for ISO 8859-9. .TS l l l c lp-1. diff --git a/man7/koi8-r.7 b/man7/koi8-r.7 index 9d1529ef6f..ff00ba605e 100644 --- a/man7/koi8-r.7 +++ b/man7/koi8-r.7 @@ -29,7 +29,8 @@ koi8-r \- Russian Net Character Set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION KOI8-R is the character set of choice for encoding Russian texts for -many Unix-like operation systems. KOI8-R is a successor for KOI-8, a +many Unix-like operation systems. +KOI8-R is a successor for KOI-8, a de-facto standard for Internet Mail, News, WWW and other interactive services at least all over the ex-SU territory. .PP @@ -38,7 +39,8 @@ Set). .SH NOTE KOI8-R was designed for mixed Russian/English texts and covers only Russian Cyrillic characters, so if you're looking for Ukrainian, -Byelorussian, etc. Cyrillic characters, try ISO-IR-111, or KOI8-U +Byelorussian, etc. +Cyrillic characters, try ISO-IR-111, or KOI8-U (Ukrainian Character Set), or KOI8-C (for ancient Russian texts) instead, which are identical to KOI8-R in the Russian Cyrillic letters area. diff --git a/man7/locale.7 b/man7/locale.7 index a4ff35ae4f..29b61155d5 100644 --- a/man7/locale.7 +++ b/man7/locale.7 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -33,9 +33,11 @@ locale \- Description of multi-language support .B #include <locale.h> .fi .SH DESCRIPTION -A locale is a set of language and cultural rules. These cover aspects +A locale is a set of language and cultural rules. +These cover aspects such as language for messages, different character sets, lexicographic -conventions, etc. A program needs to be able to determine its locale +conventions, etc. +A program needs to be able to determine its locale and act accordingly to be portable to different cultures. .PP The header @@ -50,7 +52,8 @@ to set the current locale, and to get information about number formatting. .PP There are different categories for local information a program might -need; they are declared as macros. Using them as the first argument +need; they are declared as macros. +Using them as the first argument to the .BR setlocale () function, it is possible to set one of these to the desired locale: @@ -60,7 +63,8 @@ This is used to change the behaviour of the functions .BR strcoll () and .BR strxfrm (), -which are used to compare strings in the local alphabet. For example, +which are used to compare strings in the local alphabet. +For example, the German sharp s is sorted as "ss". .TP .B LC_CTYPE @@ -78,18 +82,21 @@ or changes the information returned by .BR localeconv () which describes the way numbers are usually printed, with details such -as decimal point versus decimal comma. This information is internally +as decimal point versus decimal comma. +This information is internally used by the function .BR strfmon (). .TP .B LC_MESSAGES changes the language messages are displayed in and how an affirmative or -negative answer looks like. The GNU C-library contains the +negative answer looks like. +The GNU C-library contains the .BR gettext (), .BR ngettext (), and .BR rpmatch () -functions to ease the use of these information. The GNU gettext family of +functions to ease the use of these information. +The GNU gettext family of functions also obey the environment variable .BR LANGUAGE . .TP @@ -98,8 +105,8 @@ changes the information used by the .BR printf () and .BR scanf () -family of functions, when they are advised to use the -locale-settings. This information can also be read with the +family of functions, when they are advised to use the locale-settings. +This information can also be read with the .BR localeconv () function. .TP @@ -107,7 +114,7 @@ function. changes the behaviour of the .BR strftime () function to display the current time in a locally acceptable form; for -example, most of Europe uses a 24\-hour clock versus the +example, most of Europe uses a 24\-hour clock versus the 12\-hour clock used in the United States. .TP .B LC_ALL @@ -150,19 +157,19 @@ struct lconv { /* Numeric (non-monetary) information */ char *decimal_point; /* Radix character */ - char *thousands_sep; /* Separator for digit groups to left + char *thousands_sep; /* Separator for digit groups to left of radix character */ - char *grouping; /* Each element is the number of digits in a - group; elements with higher indices are - further left. An element with value CHAR_MAX - means that no further grouping is done. An - element with value 0 means that the previous + char *grouping; /* Each element is the number of digits in a + group; elements with higher indices are + further left. An element with value CHAR_MAX + means that no further grouping is done. An + element with value 0 means that the previous element is used for all groups further left. */ /* Remaining fields are for monetary information */ - char *int_curr_symbol; /* First three chars are a currency symbol - from ISO 4217. Fourth char is the + char *int_curr_symbol; /* First three chars are a currency symbol + from ISO 4217. Fourth char is the separator. Fifth char is '\0'. */ char *currency_symbol; /* Local currency symbol */ char *mon_decimal_point; /* Radix character */ @@ -172,11 +179,11 @@ struct lconv { char *negative_sign; /* Sign for negative values */ char int_frac_digits; /* Int'l fractional digits */ char frac_digits; /* Local fractional digits */ - char p_cs_precedes; /* 1 if currency_symbol precedes a + char p_cs_precedes; /* 1 if currency_symbol precedes a positive value, 0 if succeeds */ - char p_sep_by_space; /* 1 if a space separates currency_symbol + char p_sep_by_space; /* 1 if a space separates currency_symbol from a positive value */ - char n_cs_precedes; /* 1 if currency_symbol precedes a + char n_cs_precedes; /* 1 if currency_symbol precedes a negative value, 0 if succeeds */ char n_sep_by_space; /* 1 if a space separates currency_symbol from a negative value */ diff --git a/man7/mailaddr.7 b/man7/mailaddr.7 index 1c05ff6cc3..5d0570e4b9 100644 --- a/man7/mailaddr.7 +++ b/man7/mailaddr.7 @@ -23,14 +23,15 @@ .\" account for changes since 1995. Route-addrs are now even less .\" common, etc. Some minor wording improvements. Same copyright. .\" -.TH MAILADDR 7 2004-09-15 Linux "Linux User's Manual" +.TH MAILADDR 7 2004-09-15 Linux "Linux User's Manual" .UC 5 .SH NAME mailaddr \- mail addressing description .SH DESCRIPTION .nh This manual page gives a brief introduction to SMTP mail addresses, as -used on the Internet. These addresses are in the general format +used on the Internet. +These addresses are in the general format .PP user@domain .PP @@ -43,13 +44,15 @@ These examples are valid forms of the same address: .br eric@monet.berkeley.edu (Eric Allman) .PP -The domain part ("monet.berkeley.edu") is a mail-accepting domain. It -can be a host and in the past it usually was, but it doesn't have to -be. The domain part is not case sensitive. +The domain part ("monet.berkeley.edu") is a mail-accepting domain. +It can be a host and in the past it usually was, but it doesn't have to be. +The domain part is not case sensitive. .PP The local part ("eric") is often a user name, but its meaning is -defined by the local software. Sometimes it is case sensitive, -although that is unusual. If you see a local-part that looks like +defined by the local software. +Sometimes it is case sensitive, +although that is unusual. +If you see a local-part that looks like garbage, it is usually because of a gateway between an internal e-mail system and the net, here are some examples: .PP @@ -66,14 +69,16 @@ internal mail system that lacks proper internet support, an UUCP gateway, and the last one is just boring username policy.) .PP The real-name part ("Eric Allman") can either be placed before -<>, or in () at the end. (Strictly speaking the two aren't the same, -but the difference is beyond the scope of this page.) The name may -have to be quoted using "", e.g. if it contains ".": +<>, or in () at the end. +(Strictly speaking the two aren't the same, +but the difference is beyond the scope of this page.) +The name may have to be quoted using "", e.g. if it contains ".": .PP "Eric P. Allman" <eric@monet.berkeley.edu> .SS Abbreviation. .PP -Many mail systems let users abbreviate the domain name. For instance, +Many mail systems let users abbreviate the domain name. +For instance, users at berkeley.edu may get away with "eric@monet" to send mail to Eric Allman. .I "This behavior is deprecated." @@ -81,23 +86,29 @@ Sometimes it works, but you should not depend on it. .SS Route-addrs. .PP In the past, sometimes one had to route a message through -several hosts to get it to its final destination. Addresses which -show these relays are termed "route-addrs". These use the syntax: +several hosts to get it to its final destination. +Addresses which +show these relays are termed "route-addrs". +These use the syntax: .PP <@hosta,@hostb:user@hostc> .PP This specifies that the message should be sent to hosta, from there -to hostb, and finally to hostc. Many hosts disregard route-addrs +to hostb, and finally to hostc. +Many hosts disregard route-addrs and send directly to hostc. .PP -Route-addrs are very unusual now. They occur sometimes in old mail -archives. It is generally possible to ignore all but the "user@hostc" +Route-addrs are very unusual now. +They occur sometimes in old mail +archives. +It is generally possible to ignore all but the "user@hostc" part of the address to determine the actual address. .SS Postmaster. .PP Every site is required to have a user or user alias designated "postmaster" to which problems with the mail system may be -addressed. The "postmaster" address is not case sensitive. +addressed. +The "postmaster" address is not case sensitive. .SH FILES .I /etc/aliases .br diff --git a/man7/man.7 b/man7/man.7 index e567e0fc62..e660fd3c0b 100644 --- a/man7/man.7 +++ b/man7/man.7 @@ -9,7 +9,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -17,7 +17,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -52,7 +52,8 @@ macro package (often called the .B man macro package) and related conventions for creating manual (man) pages. This macro package should be used by developers when -writing or porting man pages for Linux. It is fairly compatible with other +writing or porting man pages for Linux. +It is fairly compatible with other versions of this macro package, so porting man pages should not be a major problem (exceptions include the NET-2 BSD release, which uses a totally different macro package called mdoc; see @@ -64,7 +65,8 @@ simply by specifying the .B \-mdoc option instead of the .B \-man -option. Using the +option. +Using the .B \-mandoc option is, however, recommended, since this will automatically detect which macro package is in use. @@ -156,16 +158,19 @@ many of which only root can execute. This is an obsolete manual section. Once it was thought a good idea to document the Linux kernel here, but in fact very little has been documented, and the documentation -that exists is outdated already. There are better sources of -information for kernel developers. +that exists is outdated already. +There are better sources of +information for kernel developers. .RE .SH SECTIONS Sections are started with .B \&.SH -followed by the heading name. If the name contains spaces and appears +followed by the heading name. +If the name contains spaces and appears on the same line as .BR \&.SH , -then place the heading in double quotes. Traditional or suggested +then place the heading in double quotes. +Traditional or suggested headings include: NAME, SYNOPSIS, DESCRIPTION, RETURN VALUE, EXIT STATUS, ERROR HANDLING, ERRORS, @@ -185,8 +190,8 @@ chess \\- the game of chess .sp .RE It is extremely important that this format is followed, and that there is a -backslash before the single dash which follows the command name. This -syntax is used by the +backslash before the single dash which follows the command name. +This syntax is used by the .BR makewhatis (8) program to create a database of short command descriptions for the .BR whatis (1) @@ -201,7 +206,8 @@ briefly describes the command or function's interface. For commands, this shows the syntax of the command and its arguments (including options); boldface is used for as-is text and italics are used to indicate replaceable -arguments. Brackets ([]) surround optional arguments, vertical bars (|) +arguments. +Brackets ([]) surround optional arguments, vertical bars (|) separate choices, and ellipses (\&...) can be repeated. For functions, it shows any required data declarations or .B #include @@ -261,7 +267,8 @@ and how they affect it. .TP .B DIAGNOSTICS gives an overview of the most common error messages and how to -cope with them. You don't need to explain system error messages +cope with them. +You don't need to explain system error messages or fatal signals that can appear during execution of any program unless they're special in some way to your program. .TP @@ -323,7 +330,8 @@ usually uses the macro). .IP Any reference to another man page (or to the subject of the current man -page) is in bold. If the manual section number is given, it is given in +page) is in bold. +If the manual section number is given, it is given in Roman (normal) font, without any spaces (e.g., .BR man (7)). .LP @@ -365,9 +373,9 @@ Small (useful for acronyms) Traditionally, each command can have up to six arguments, but the GNU implementation removes this limitation (you might still want to limit yourself to 6 arguments for portability's sake). -Arguments are delimited by -spaces. Double quotes can be used to specify an argument which contains -spaces. All of the arguments will be printed next to each other without +Arguments are delimited by spaces. +Double quotes can be used to specify an argument which contains spaces. +All of the arguments will be printed next to each other without intervening spaces, so that the .B \&.BR command can be used to specify a word in bold followed by a mark of @@ -390,7 +398,7 @@ As a result, successive indented paragraphs can use the same indent without re-specifying the indent value. A normal (non-indented) paragraph resets the prevailing indent value to its default value (0.5 inches). -By default a given indent is measured in ens; +By default a given indent is measured in ens; try to use ens or ems as units for indents, since these will automatically adjust to font size changes. The other key macro definitions are: @@ -453,7 +461,8 @@ a period as the tag; this simplifies translation to other formats. .TP .BI \&.TP " i" -Begin paragraph with hanging tag. The tag is given on the next line, but +Begin paragraph with hanging tag. +The tag is given on the next line, but its results are like those of the .B \&.IP command. @@ -529,7 +538,8 @@ is being used, the macro package's definition of the URL macro will supersede the locally defined one. .PP -A number of other link macros are available. See +A number of other link macros are available. +See .BR groff_www (7) for more details. .SS "Miscellaneous Macros" @@ -575,7 +585,7 @@ Avoid using the various troff preprocessors .BR tbl (1), but try to use the .B IP -and +and .B TP commands instead for two-column tables). Avoid using computations; most other tools can't process them. @@ -653,7 +663,7 @@ macros instead). The condition test .RB ( if,ie ) should only have 't' or 'n' as the condition. -Only translations +Only translations .RB ( tr ) that can be ignored should be used. Font changes @@ -682,10 +692,12 @@ If you include URLs, use the full URL can automatically find the URLs. .PP Tools processing these files should open the file and examine the first -non-whitespace character. A period (.) or single quote (') +non-whitespace character. +A period (.) or single quote (') at the beginning of a line indicates a troff-based file (such as man or mdoc). A left angle bracket (<) indicates an SGML/XML-based -file (such as HTML or Docbook). Anything else suggests simple ASCII +file (such as HTML or Docbook). +Anything else suggests simple ASCII text (e.g., a "catman" result). .PP Many man pages begin with '\e" followed by a space and a list of characters, diff --git a/man7/mdoc.7 b/man7/mdoc.7 index 0c58e806af..4a5f4d8b6f 100644 --- a/man7/mdoc.7 +++ b/man7/mdoc.7 @@ -197,7 +197,8 @@ is used. End-display (matches \&.Bd). .It Li \&.Bl Begin-list. -Create lists or columns. Options: +Create lists or columns. +Options: .Bl -tag -width flag -compact .It Ar List-types .Bl -column xbullet -compact diff --git a/man7/mdoc.samples.7 b/man7/mdoc.samples.7 index 9520b84aab..d3e120532b 100644 --- a/man7/mdoc.samples.7 +++ b/man7/mdoc.samples.7 @@ -307,7 +307,7 @@ manual .Xr mdoc 7 . This is a technical .Em faux pas -as almost all of the macros in +as almost all of the macros in .Nm \-mdoc are parsed, but as it was cumbersome to constantly refer to macros as being callable and being able to call other macros, @@ -442,7 +442,7 @@ The body of a man page is easily constructed from a basic template found in the file .Pa /usr/share/misc/mdoc.template . Several example man pages can also be found -in +in .Pa /usr/share/examples/mdoc . .Pp .Ss A manual page template @@ -831,7 +831,7 @@ The .Ql \&.An macro is used to specify the name of the author of the item being documented, or the name of the author of the actual manual page. -Any remaining arguments after the name information are assumed +Any remaining arguments after the name information are assumed to be punctuation. .Pp .Dl Usage: .An author_name \*(Pu @@ -1856,7 +1856,7 @@ name macro .Ql \&.Nm is required for sections 1, 5, 6, 7, 8. Section 4 manuals require a -.Ql ".Nm" , +.Ql ".Nm" , .Ql ".Fd" or a .Ql ".Cd" @@ -2371,7 +2371,7 @@ The font-mode must be one of the following three types: .Pp .Bl -tag -width "file file_name " -compact .It Sy \&Em | Fl emphasis -Same as if the +Same as if the .Ql \&.Em macro was used for the entire block of text. .It Sy \&Li | Fl literal diff --git a/man7/mq_overview.7 b/man7/mq_overview.7 index ba59c70b58..fd48c3088b 100644 --- a/man7/mq_overview.7 +++ b/man7/mq_overview.7 @@ -11,20 +11,20 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" .TH MQ_OVERVIEW 7 2006-02-25 "Linux 2.6.16" "Linux Programmer's Manual" .SH NAME -mq_overview \- Overview of POSIX message queues +mq_overview \- Overview of POSIX message queues .SH DESCRIPTION -POSIX message queues allow processes to exchange data in +POSIX message queues allow processes to exchange data in the form of messages. This API is distinct from that provided by System V message queues .RB ( msgget (2), @@ -38,7 +38,7 @@ this function returns a .I message queue descriptor .RI ( mqd_t ), which is used to refer to the open message queue in later calls. -Each message queue is identified by a name of the form +Each message queue is identified by a name of the form .IR /somename . Two processes can operate on the same queue by passing the same name to .BR mq_open (). @@ -48,39 +48,39 @@ Messages are transferred to and from a queue using and .BR mq_receive (3). When a process has finished using the queue, it closes it using -.BR mq_close (3), +.BR mq_close (3), and when the queue is no longer required, it can be deleted using .BR mq_unlink (3). Queue attributes can be retrieved and (in some cases) modified using .BR mq_getattr (3) and .BR mq_setattr (3). -A process can request asynchronous notification +A process can request asynchronous notification of the arrival of a message on a previously empty queue using .BR mq_notify (3). A message queue descriptor is a reference to an -.IR "open message queue description" -(cf. +.IR "open message queue description" +(cf. .BR open (2)). -After a +After a .BR fork (2), a child inherits copies of its parent's message queue descriptors, -and these descriptors refer to the same open message queue descriptions +and these descriptors refer to the same open message queue descriptions as the corresponding descriptors in the parent. -Corresponding descriptors in the two processes share the flags +Corresponding descriptors in the two processes share the flags .RI ( mq_flags ) that are associated with the open message queue description. -Each message has an associated -.IR priority , -and messages are always delivered to the receiving process +Each message has an associated +.IR priority , +and messages are always delivered to the receiving process highest priority first. -Message priorities range from 0 (low) to +Message priorities range from 0 (low) to .I sysconf(_SC_MQ_PRIO_MAX)\ -\ 1 (high). On Linux, -.I sysconf(_SC_MQ_PRIO_MAX) +.I sysconf(_SC_MQ_PRIO_MAX) returns 32768, but POSIX.1-2001 only requires an implementation to support priorities in the range 0 to 31; some implementations only provide this range. @@ -113,7 +113,7 @@ Glibc support has been provided since version 2.3.4. .SS Kernel configuration Support for POSIX message queues is configurable via the .B CONFIG_POSIX_MQUEUE -kernel configuration option. +kernel configuration option. This option is enabled by default. .SS Persistence POSIX message queues have kernel persistence: @@ -126,11 +126,11 @@ Programs using the POSIX message queue API must be compiled with to link against the real-time library, .IR librt . .SS /proc interfaces -The following interfaces can be used to limit the amount of +The following interfaces can be used to limit the amount of kernel memory consumed by POSIX message queues: .TP .I /proc/sys/fs/mqueue/msg_max -This file can be used to view and change the ceiling value for the +This file can be used to view and change the ceiling value for the maximum number of messages in a queue. This value acts as a ceiling on the .I attr->mq_maxmsg @@ -139,14 +139,14 @@ argument given to The default and minimum value for .I msg_max is 10; the upper limit is HARD_MAX: -.IR "(131072\ /\ sizeof(void\ *))" +.IR "(131072\ /\ sizeof(void\ *))" (32768 on Linux/86). This limit is ignored for privileged processes .RB ( CAP_SYS_RESOURCE ), but the HARD_MAX ceiling is nevertheless imposed. .TP .I /proc/sys/fs/mqueue/msgsize_max -This file can be used to view and change the ceiling on the +This file can be used to view and change the ceiling on the maximum message size. This value acts as a ceiling on the .I attr->mq_msgsize @@ -160,9 +160,9 @@ This limit is ignored for privileged processes .RB ( CAP_SYS_RESOURCE ). .TP .I /proc/sys/fs/mqueue/queues_max -This file can be used to view and change the system-wide limit on the +This file can be used to view and change the system-wide limit on the number of message queues that can be created. -Only privileged processes +Only privileged processes .RB ( CAP_SYS_RESOURCE ) can create new message queues once this limit has been reached. The default value for @@ -171,13 +171,13 @@ is 256; it can be changed to any value in the range 0 to INT_MAX. .SS Resource limit The .BR RLIMIT_MSGQUEUE -resource limit, which places a limit on the amount of space -that can be consumed by all of the message queues -belonging to a process's real user ID, is described in +resource limit, which places a limit on the amount of space +that can be consumed by all of the message queues +belonging to a process's real user ID, is described in .BR getrlimit (2). .SS Mounting the message queue file system On Linux, message queues are created in a virtual file system. -(Other implementations may also provide such a feature, +(Other implementations may also provide such a feature, but the details are likely to differ.) This file system can be mounted using the following commands: .in +0.25i @@ -190,14 +190,14 @@ $ mount -t mqueue none /dev/mqueue .in -0.25i The sticky bit is automatically enabled on the mount directory. -After the file system has been mounted, the message queues on the system +After the file system has been mounted, the message queues on the system can be viewed and manipulated using the commands usually used for files (e.g., .BR ls (1) and .BR rm (1)). -The contents of each file in the directory consist of a single line +The contents of each file in the directory consist of a single line containing information about the queue: .in +0.25i .nf @@ -217,16 +217,16 @@ Number of bytes of data in all messages in the queue. .B NOTIFY_PID If this is non-zero, then the process with this PID has used .BR mq_notify (3) -to register for asynchronous message notification, +to register for asynchronous message notification, and the remaining fields describe how notification occurs. .TP .B NOTIFY Notification method: -0 is +0 is .BR SIGEV_SIGNAL ; 1 is -.BR SIGEV_NONE; -and +.BR SIGEV_NONE; +and 2 is .BR SIGEV_THREAD . .TP @@ -250,8 +250,8 @@ System V message queues .BR msgrcv (2), etc.) are an older API for exchanging messages between processes. POSIX message queues provide a better designed interface than -System V message queues; -on the other hand POSIX message queues are less widely available +System V message queues; +on the other hand POSIX message queues are less widely available (especially on older systems) than System V message queues. .SH EXAMPLE An example of the use of various message queue functions is shown in diff --git a/man7/netdevice.7 b/man7/netdevice.7 index b3ab1d9dc0..2b6885174b 100644 --- a/man7/netdevice.7 +++ b/man7/netdevice.7 @@ -9,7 +9,7 @@ .\" .\" Modified, 2004-11-25, mtk, formatting and a few wording fixes .\" -.TH NETDEVICE 7 1999-05-02 "Linux Man Page" "Linux Programmer's Manual" +.TH NETDEVICE 7 1999-05-02 "Linux Man Page" "Linux Programmer's Manual" .SH NAME netdevice \- Low level access to Linux network devices .SH SYNOPSIS @@ -20,11 +20,11 @@ netdevice \- Low level access to Linux network devices This man page describes the sockets interface which is used to configure network devices. -Linux supports some standard ioctls to configure network devices. -They can be used on any socket's file descriptor regardless of the -family or type. -They pass an -.B ifreq +Linux supports some standard ioctls to configure network devices. +They can be used on any socket's file descriptor regardless of the +family or type. +They pass an +.B ifreq structure: .nf @@ -47,24 +47,26 @@ struct ifreq { }; }; -struct ifconf { +struct ifconf { int ifc_len; /* size of buffer */ - union { - char * ifc_buf; /* buffer address */ + union { + char * ifc_buf; /* buffer address */ struct ifreq * ifc_req; /* array of structures */ - }; -}; + }; +}; .fi Normally, the user specifies which device to affect by setting .B ifr_name -to the name of the interface. All other members of the structure may -share memory. +to the name of the interface. +All other members of the structure may +share memory. .SH IOCTLS If an ioctl is marked as privileged then using it requires an effective user ID of 0 or the .B CAP_NET_ADMIN -capability. If this is not the case +capability. +If this is not the case .B EPERM will be returned. .TP @@ -107,7 +109,7 @@ IFF_AUTOMEDIA:Auto media selection active. IFF_DYNAMIC:T{ The addresses are lost when the interface goes down. T} -.TE +.TE Setting the active flag word is a privileged operation, but any process may read it. .TP @@ -123,7 +125,8 @@ if you attempt to set it. .BR SIOCGIFMTU ", " SIOCSIFMTU Get or set the MTU (Maximum Transfer Unit) of a device using .BR ifr_mtu . -Setting the MTU is a privileged operation. Setting the MTU to +Setting the MTU is a privileged operation. +Setting the MTU to too small values may cause kernel crashes. .TP .BR SIOCGIFHWADDR ", " SIOCSIFHWADDR @@ -131,10 +134,10 @@ Get or set the hardware address of a device using .BR ifr_hwaddr . The hardware address is specified in a struct .IR sockaddr . -.I sa_family -contains the ARPHRD_* device type, +.I sa_family +contains the ARPHRD_* device type, .I sa_data -the L2 hardware address starting from byte 0. +the L2 hardware address starting from byte 0. Setting the hardware address is a privileged operation. .TP .B SIOCSIFHWBROADCAST @@ -151,10 +154,10 @@ Setting the parameters is a privileged operation. struct ifmap { unsigned long mem_start; unsigned long mem_end; - unsigned short base_addr; - unsigned char irq; - unsigned char dma; - unsigned char port; + unsigned short base_addr; + unsigned char irq; + unsigned char dma; + unsigned char port; }; .fi @@ -176,38 +179,42 @@ Get or set the transmit queue length of a device using Setting the transmit queue length is a privileged operation. .TP .B SIOCSIFNAME -Changes the name of the interface specified in +Changes the name of the interface specified in .BR ifr_name to .BR ifr_newname . -This is a privileged operation. It is only allowed when the interface +This is a privileged operation. +It is only allowed when the interface is not up. .TP .B SIOCGIFCONF -Return a list of interface (transport layer) addresses. This currently -means only addresses of the AF_INET (IPv4) family for compatibility. -The user passes a +Return a list of interface (transport layer) addresses. +This currently +means only addresses of the AF_INET (IPv4) family for compatibility. +The user passes a .B ifconf -structure as argument to the ioctl. It contains a pointer to an array of +structure as argument to the ioctl. +It contains a pointer to an array of .I ifreq -structures in +structures in .B ifc_req -and its length in bytes in +and its length in bytes in .BR ifc_len . The kernel fills the ifreqs with all current L3 interface addresses that -are running: -.I ifr_name -contains the interface name (eth0:1 etc.), +are running: +.I ifr_name +contains the interface name (eth0:1 etc.), .I ifr_addr the address. -The kernel returns with the actual length in +The kernel returns with the actual length in .IR ifc_len . -If +If .I ifc_len is equal to the original length the buffer probably has overflowed and you should retry with a bigger buffer to get all addresses. When no error occurs the ioctl returns 0; -otherwise \-1. Overflow is not an error. +otherwise \-1. +Overflow is not an error. .\" FIXME Slaving isn't supported in 2.2 .\" . .\" .TP @@ -218,30 +225,32 @@ otherwise \-1. Overflow is not an error. .\" .PP .\" FIXME add amateur radio stuff. .PP -Most protocols support their own ioctls to configure protocol specific -interface options. See the protocol man pages for a description. -For configuring IP addresses see +Most protocols support their own ioctls to configure protocol specific +interface options. +See the protocol man pages for a description. +For configuring IP addresses see .BR ip (7). .PP -In addition some devices support private ioctls. +In addition some devices support private ioctls. These are not described here. .SH NOTES Strictly speaking, -.B SIOCGIFCONF -is IP specific and belongs in +.B SIOCGIFCONF +is IP specific and belongs in .BR ip (7). .LP The names of interfaces with no addresses or that don't have the -.B IFF_RUNNING +.B IFF_RUNNING flag set can be found via .IR /proc/net/dev . .LP -Local IPv6 IP addresses can be found via /proc/net or via +Local IPv6 IP addresses can be found via /proc/net or via .BR rtnetlink (7). .SH BUGS -glibc 2.1 is missing the -.I ifr_newname -macro in net/if.h. Add the following to your program as a workaround: +glibc 2.1 is missing the +.I ifr_newname +macro in net/if.h. +Add the following to your program as a workaround: .sp .RS .nf diff --git a/man7/netlink.7 b/man7/netlink.7 index 39aca26e2d..a135a0ac5b 100644 --- a/man7/netlink.7 +++ b/man7/netlink.7 @@ -27,7 +27,8 @@ There is also an obsolete netlink interface via netlink character devices; this interface is not documented here and is only provided for backwards compatibility. -Netlink is a datagram-oriented service. Both +Netlink is a datagram-oriented service. +Both .B SOCK_RAW and .B SOCK_DGRAM @@ -54,7 +55,8 @@ Messages from 1-wire subsystem. Reserved for user-mode socket protocols. .TP .B NETLINK_FIREWALL -Transport IPv4 packets from netfilter to userspace. Used by +Transport IPv4 packets from netfilter to userspace. +Used by .I ip_queue kernel module. .TP @@ -85,7 +87,8 @@ Auditing. Access to FIB lookup from userspace. .TP .B NETLINK_CONNECTOR -Kernel connector. See +Kernel connector. +See .I Documentation/connector/* in the kernel source for further information. .TP @@ -94,7 +97,8 @@ in the kernel source for further information. Netfilter subsystem. .TP .B NETLINK_IP6_FW -Transport IPv6 packets from netfilter to userspace. Used by +Transport IPv6 packets from netfilter to userspace. +Used by .I ip6_queue kernel module. .TP @@ -113,7 +117,8 @@ Netlink messages consist of a byte stream with one or multiple headers and associated payload. The byte stream should only be accessed with the standard .B NLMSG_* -macros. See +macros. +See .BR netlink (3) for further information. @@ -241,14 +246,17 @@ are opaque to netlink core. Netlink is not a reliable protocol. It tries its best to deliver a message to its destination(s), but may drop messages when an out-of-memory condition or -other error occurs. For reliable transfer the sender can request an +other error occurs. +For reliable transfer the sender can request an acknowledgement from the receiver by setting the .B NLM_F_ACK -flag. An acknowledgment is an +flag. +An acknowledgment is an .B NLMSG_ERROR packet with the error field set to 0. The application must generate acknowledgements for -received messages itself. The kernel tries to send an +received messages itself. +The kernel tries to send an .B NLMSG_ERROR message for every failed packet. A user process should follow this convention too. diff --git a/man7/packet.7 b/man7/packet.7 index 6ee2985534..865782263b 100644 --- a/man7/packet.7 +++ b/man7/packet.7 @@ -4,9 +4,9 @@ .\" and in case of nontrivial modification author and date .\" of the modification is added to the header. .\" $Id: packet.7,v 1.13 2000/08/14 08:03:45 ak Exp $ -.TH PACKET 7 1999-04-29 "Linux Man Page" "Linux Programmer's Manual" +.TH PACKET 7 1999-04-29 "Linux Man Page" "Linux Programmer's Manual" .SH NAME -packet, PF_PACKET \- packet interface on device level. +packet, PF_PACKET \- packet interface on device level. .SH SYNOPSIS .nf .B #include <sys/socket.h> @@ -15,70 +15,77 @@ packet, PF_PACKET \- packet interface on device level. .br .B #include <net/ethernet.h> /* the L2 protocols */ .sp -.BI "packet_socket = socket(PF_PACKET, int " socket_type ", int "protocol ); +.BI "packet_socket = socket(PF_PACKET, int " socket_type ", int "protocol ); .fi .SH DESCRIPTION Packet sockets are used to receive or send raw packets at the device driver -(OSI Layer 2) -level. They allow the user to implement protocol modules in user space +(OSI Layer 2) level. +They allow the user to implement protocol modules in user space on top of the physical layer. The .I socket_type -is either -.B SOCK_RAW -for raw packets including the link level header or +is either +.B SOCK_RAW +for raw packets including the link level header or .B SOCK_DGRAM -for cooked packets with the link level header removed. The link level -header information is available in a common format in a -.BR sockaddr_ll . -.I protocol -is the IEEE 802.3 protocol number in network order. See the -.I <linux/if_ether.h> -include file for a list of allowed protocols. When protocol +for cooked packets with the link level header removed. +The link level +header information is available in a common format in a +.BR sockaddr_ll . +.I protocol +is the IEEE 802.3 protocol number in network order. +See the +.I <linux/if_ether.h> +include file for a list of allowed protocols. +When protocol is set to -.B htons(ETH_P_ALL) +.B htons(ETH_P_ALL) then all protocols are received. All incoming packets of that protocol type will be passed to the packet socket before they are passed to the protocols implemented in the kernel. - + Only processes with effective UID 0 or the .B CAP_NET_RAW -capability may open packet sockets. +capability may open packet sockets. .B SOCK_RAW packets are passed to and from the device driver without any changes in -the packet data. +the packet data. When receiving a packet, the address is still parsed and passed in a standard .B sockaddr_ll -address structure. When transmitting a packet, the user supplied buffer -should contain the physical layer header. That packet is then +address structure. +When transmitting a packet, the user supplied buffer +should contain the physical layer header. +That packet is then queued unmodified to the network driver of the interface defined by the -destination address. Some device drivers always add other headers. +destination address. +Some device drivers always add other headers. .B SOCK_RAW -is similar to but not compatible with the obsolete +is similar to but not compatible with the obsolete .B PF_INET/SOCK_PACKET of Linux 2.0. -.B SOCK_DGRAM -operates on a slightly higher level. -The physical header is removed before the packet is passed to the user. +.B SOCK_DGRAM +operates on a slightly higher level. +The physical header is removed before the packet is passed to the user. Packets sent through a .B SOCK_DGRAM -packet socket get a suitable physical layer header based on the -information in the -.B sockaddr_ll +packet socket get a suitable physical layer header based on the +information in the +.B sockaddr_ll destination address before they are queued. By default all packets of the specified protocol type -are passed to a packet socket. +are passed to a packet socket. To only get packets from a specific interface use .BR bind (2) specifying an address in a .I struct sockaddr_ll -to bind the packet socket to an interface. Only the -.B sll_protocol +to bind the packet socket to an interface. +Only the +.B sll_protocol and the .B sll_ifindex address fields are used for purposes of binding. @@ -93,7 +100,7 @@ flag is passed to .BR recvmsg (2), .BR recv (2), .BR recvfrom (2) -the real length of the packet on the wire is always returned, +the real length of the packet on the wire is always returned, even when it is longer than the buffer. .SH "ADDRESS TYPES" The sockaddr_ll is a device independent physical layer address. @@ -104,30 +111,32 @@ struct sockaddr_ll { unsigned short sll_family; /* Always AF_PACKET */ unsigned short sll_protocol; /* Physical layer protocol */ int sll_ifindex; /* Interface number */ - unsigned short sll_hatype; /* Header type */ + unsigned short sll_hatype; /* Header type */ unsigned char sll_pkttype; /* Packet type */ - unsigned char sll_halen; /* Length of address */ + unsigned char sll_halen; /* Length of address */ unsigned char sll_addr[8]; /* Physical layer address */ }; .fi .in -0.25i -.B sll_protocol +.B sll_protocol is the standard ethernet protocol type in network order as defined in the .I <linux/if_ether.h> -include file. It defaults to the socket's protocol. -.B sll_ifindex +include file. +It defaults to the socket's protocol. +.B sll_ifindex is the interface index of the interface (see .BR netdevice (7)); -0 matches any interface (only legal for binding). -.B sll_hatype -is a ARP type as defined in the +0 matches any interface (only legal for binding). +.B sll_hatype +is a ARP type as defined in the .I <linux/if_arp.h> include file. -.B sll_pkttype -contains the packet type. Valid types are +.B sll_pkttype +contains the packet type. +Valid types are .B PACKET_HOST for a packet addressed to the local host, .B PACKET_BROADCAST @@ -139,12 +148,13 @@ for a packet to some other host that has been caught by a device driver in promiscuous mode, and .B PACKET_OUTGOING for a packet originated from the local host that is looped back to a packet -socket. These types make only sense for receiving. +socket. +These types make only sense for receiving. .B sll_addr and .B sll_halen -contain the physical layer (e.g. IEEE 802.3) address and its length. The -exact interpretation depends on the device. +contain the physical layer (e.g. IEEE 802.3) address and its length. +The exact interpretation depends on the device. When you send packets it is enough to specify .BR sll_family , @@ -162,15 +172,16 @@ and .B sll_ifindex are used. .SH "SOCKET OPTIONS" -Packet sockets can be used to configure physical layer multicasting -and promiscuous mode. It works by calling -.BR setsockopt (2) -on a packet socket for SOL_PACKET and one of the options -.B PACKET_ADD_MEMBERSHIP -to add a binding or +Packet sockets can be used to configure physical layer multicasting +and promiscuous mode. +It works by calling +.BR setsockopt (2) +on a packet socket for SOL_PACKET and one of the options +.B PACKET_ADD_MEMBERSHIP +to add a binding or .B PACKET_DROP_MEMBERSHIP to drop it. -They both expect a +They both expect a .B packet_mreq structure as argument: @@ -180,7 +191,7 @@ struct packet_mreq { int mr_ifindex; /* interface index */ unsigned short mr_type; /* action */ unsigned short mr_alen; /* address length */ - unsigned char mr_address[8]; /* physical layer address */ + unsigned char mr_address[8]; /* physical layer address */ }; .fi .in -0.25i @@ -194,35 +205,35 @@ parameter specifies which action to perform. .B PACKET_MR_PROMISC enables receiving all packets on a shared medium (often known as ``promiscuous mode''), -.B PACKET_MR_MULTICAST -binds the socket to the physical layer multicast group specified in +.B PACKET_MR_MULTICAST +binds the socket to the physical layer multicast group specified in .B mr_address and .BR mr_alen , and .B PACKET_MR_ALLMULTI -sets the socket up to receive all multicast packets arriving at -the interface. +sets the socket up to receive all multicast packets arriving at +the interface. -In addition the traditional ioctls +In addition the traditional ioctls .BR SIOCSIFFLAGS , -.BR SIOCADDMULTI , +.BR SIOCADDMULTI , .B SIOCDELMULTI can be used for the same purpose. .SH IOCTLS .B SIOCGSTAMP -can be used to receive the time stamp of the last received packet. -Argument is a +can be used to receive the time stamp of the last received packet. +Argument is a .I struct timeval. In addition all standard ioctls defined in .BR netdevice (7) -and +and .BR socket (7) are valid on packet sockets. .SH "ERROR HANDLING" -Packet sockets do no error handling other than errors occurred -while passing the packet to the device driver. +Packet sockets do no error handling other than errors occurred +while passing the packet to the device driver. They don't have the concept of a pending error. .SH COMPATIBILITY In Linux 2.0, the only way to get a packet socket was by calling @@ -232,7 +243,7 @@ The main difference between the two methods is that .B SOCK_PACKET uses the old .I struct sockaddr_pkt -to specify an interface, which doesn't provide physical layer +to specify an interface, which doesn't provide physical layer independence. .in +0.25i @@ -245,21 +256,21 @@ struct sockaddr_pkt { .fi .in -0.25i -.B spkt_family -contains +.B spkt_family +contains the device type, -.B spkt_protocol +.B spkt_protocol is the IEEE 802.3 protocol type as defined in .I <sys/if_ether.h> and -.B spkt_device -is the device name as a null terminated string, e.g. eth0. +.B spkt_device +is the device name as a null terminated string, e.g. eth0. This structure is obsolete and should not be used in new code. .SH NOTES -For portable programs it is suggested to use +For portable programs it is suggested to use .B PF_PACKET -via +via .BR pcap (3); although this only covers a subset of the .B PF_PACKET @@ -267,29 +278,30 @@ features. The .B SOCK_DGRAM -packet sockets make no attempt to create or parse the IEEE 802.2 LLC -header for a IEEE 802.3 frame. -When -.B ETH_P_802_3 -is specified as protocol for sending the kernel creates the -802.3 frame and fills out the length field; the user has to supply the LLC -header to get a fully conforming packet. -Incoming 802.3 packets are not multiplexed on the DSAP/SSAP protocol -fields; instead they are supplied to the user as protocol +packet sockets make no attempt to create or parse the IEEE 802.2 LLC +header for a IEEE 802.3 frame. +When +.B ETH_P_802_3 +is specified as protocol for sending the kernel creates the +802.3 frame and fills out the length field; the user has to supply the LLC +header to get a fully conforming packet. +Incoming 802.3 packets are not multiplexed on the DSAP/SSAP protocol +fields; instead they are supplied to the user as protocol .B ETH_P_802_2 -with the LLC header prepended. It is thus not possible to bind to +with the LLC header prepended. +It is thus not possible to bind to .BR ETH_P_802_3 ; -bind to -.B ETH_P_802_2 +bind to +.B ETH_P_802_2 instead and do the protocol multiplex yourself. -The default for sending is the standard Ethernet DIX -encapsulation with the protocol filled in. +The default for sending is the standard Ethernet DIX +encapsulation with the protocol filled in. Packet sockets are not subject to the input or output firewall chains. .SH ERRORS .TP .B ENETDOWN -Interface is not up. +Interface is not up. .TP .B ENOTCONN No interface address passed. @@ -298,7 +310,7 @@ No interface address passed. Unknown device name or interface index specified in interface address. .TP .B EMSGSIZE -Packet is bigger than interface MTU. +Packet is bigger than interface MTU. .TP .B ENOBUFS Not enough memory to allocate the packet. @@ -323,11 +335,12 @@ No packet received. In addition other errors may be generated by the low-level driver. .SH VERSIONS -.B PF_PACKET -is a new feature in Linux 2.2. Earlier Linux versions supported only +.B PF_PACKET +is a new feature in Linux 2.2. +Earlier Linux versions supported only .BR SOCK_PACKET . .SH BUGS -glibc 2.1 does not have a define for +glibc 2.1 does not have a define for .BR SOL_PACKET . The suggested workaround is to use: .in +0.5i @@ -339,10 +352,10 @@ The suggested workaround is to use: .fi .in -0.5i -This is fixed in later glibc versions and also does not occur on +This is fixed in later glibc versions and also does not occur on libc5 systems. -The IEEE 802.2/803.3 LLC handling could be considered as a bug. +The IEEE 802.2/803.3 LLC handling could be considered as a bug. Socket filters are not documented. @@ -355,7 +368,8 @@ packets via SOCK_DGRAM. .SH HISTORICAL NOTE The include file .I <netpacket/packet.h> -is present since glibc2.1. Older systems need +is present since glibc2.1. +Older systems need .sp .nf .B #include <asm/types.h> @@ -381,6 +395,6 @@ RFC\ 894 for the standard IP Ethernet encapsulation. RFC\ 1700 for the IEEE 802.3 IP encapsulation. -The +The .I <linux/if_ether.h> include file for physical layer protocols. diff --git a/man7/pipe.7 b/man7/pipe.7 index f2babfafd0..0dbba4cbbf 100644 --- a/man7/pipe.7 +++ b/man7/pipe.7 @@ -10,12 +10,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -23,22 +23,22 @@ .SH NAME pipe \- overview of pipes and FIFOs .SH DESCRIPTION -Pipes and FIFOs (also known as named pipes) +Pipes and FIFOs (also known as named pipes) provide a unidirectional interprocess communication channel. -A pipe has a -.I read end -and a +A pipe has a +.I read end +and a .IR "write end" . Data written to the write end of a pipe can be read from the read end of the pipe. -A pipe is created using +A pipe is created using .BR pipe (2), which creates a new pipe and returns two file descriptors, -one referring to the read end of the pipe, +one referring to the read end of the pipe, the other referring to the write end. -Pipes can be used to create a communication channel between related -processes; see +Pipes can be used to create a communication channel between related +processes; see .BR pipe (2) for an example. @@ -46,9 +46,9 @@ A FIFO (short for First In First Out) has a name within the file system (created using .BR mkfifo (3)), and is opened using -.BR open (2). +.BR open (2). Any process may open a FIFO, assuming the file permissions allow it. -The read end is opened using the +The read end is opened using the .B O_RDONLY flag; the write end is opened using the .B O_WRONLY @@ -56,41 +56,41 @@ flag. See .BR fifo (7) for further details. -.IR Note : +.IR Note : although FIFOs have a pathname in the file system, -I/O on FIFOs does not involve operations on the underlying device +I/O on FIFOs does not involve operations on the underlying device (if there is one). .SS "I/O on Pipes and FIFOs" The only difference between pipes and FIFOs is the manner in which -they are created and opened. -Once these tasks have been accomplished, +they are created and opened. +Once these tasks have been accomplished, I/O on pipes and FIFOs has exactly the same semantics. If a process attempts to read from an empty pipe, then -.BR read (2) +.BR read (2) will block until data is available. If a process attempts to write to a full pipe (see below), then .BR write (2) blocks until sufficient data has been read from the pipe to allow the write to complete. -Non-blocking I/O is possible by using the +Non-blocking I/O is possible by using the .BR fcntl (2) -.B F_SETFL +.B F_SETFL operation to enable the .B O_NONBLOCK open file status flag. The communication channel provided by a pipe is a -.IR "byte stream" : +.IR "byte stream" : there is no concept of message boundaries. -If all file descriptors referring to the write end of a pipe -have been closed, then an attempt to +If all file descriptors referring to the write end of a pipe +have been closed, then an attempt to .BR read (2) from the pipe will see end-of-file .RB ( read (2) will return 0). -If all file descriptors referring to the read end of a pipe +If all file descriptors referring to the read end of a pipe have been closed, then a .BR write (2) will cause a @@ -100,15 +100,15 @@ If the calling process is ignoring this signal, then .BR write (2) fails with the error .BR EPIPE . -An application that uses +An application that uses .BR pipe (2) and .BR fork (2) -should use suitable +should use suitable .BR close (2) calls to close unnecessary duplicate file descriptors; -this ensures that end-of-file and -.BR SIGPIPE / EPIPE +this ensures that end-of-file and +.BR SIGPIPE / EPIPE are delivered when appropriate. It is not possible to apply @@ -119,36 +119,37 @@ A pipe has a limited capacity. If the pipe is full, then a .BR write (2) will block or fail, depending on whether the -.B O_NONBLOCK +.B O_NONBLOCK flag is set (see below). Different implementations have different limits for the pipe capacity. -Applications should not rely on a particular capacity: -an application should be designed so that a reading process consumes data -as soon as it is available, +Applications should not rely on a particular capacity: +an application should be designed so that a reading process consumes data +as soon as it is available, so that a writing process does not remain blocked. -In Linux versions before 2.6.11, the capacity of a pipe was the same as +In Linux versions before 2.6.11, the capacity of a pipe was the same as the system page size (e.g., 4096 bytes on x86). Since Linux 2.6.11, the pipe capacity is 65536 bytes. .SS PIPE_BUF POSIX.1-2001 says that .BR write (2)s -of less than -.B PIPE_BUF -bytes must be atomic: the output data is written to the pipe as a +of less than +.B PIPE_BUF +bytes must be atomic: the output data is written to the pipe as a contiguous sequence. Writes of more than .B PIPE_BUF -bytes may be non-atomic: the kernel may interleave the data +bytes may be non-atomic: the kernel may interleave the data with data written by other processes. -POSIX.1-2001 requires -.B PIPE_BUF -to be at least 512 bytes. (On Linux, -.B PIPE_BUF +POSIX.1-2001 requires +.B PIPE_BUF +to be at least 512 bytes. +(On Linux, +.B PIPE_BUF is 4096 bytes.) The precise semantics depend on whether the file descriptor is non-blocking .RB ( O_NONBLOCK ), -whether there are multiple writers to the pipe, and on +whether there are multiple writers to the pipe, and on .IR n , the number of bytes to be written: .TP @@ -168,7 +169,7 @@ bytes to the pipe, then .BR write (2) succeeds immediately, writing all .I n -bytes; otherwise +bytes; otherwise .BR write (2) fails, with .I errno @@ -176,54 +177,54 @@ set to .BR EAGAIN . .TP \fBO_NONBLOCK\fP disabled, \fIn\fP > \fBPIPE_BUF\fP -The write is non-atomic: the data given to -.BR write (2) -may be interleaved with -.BR write (2)s -by other process; +The write is non-atomic: the data given to +.BR write (2) +may be interleaved with +.BR write (2)s +by other process; the .BR write (2) -blocks until +blocks until .I n bytes have been written. .TP \fBO_NONBLOCK\fP enabled, \fIn\fP > \fBPIPE_BUF\fP -If the pipe is full, then +If the pipe is full, then .BR write (2) fails, with .I errno set to .BR EAGAIN . Otherwise, from 1 to -.I n +.I n bytes may be written (i.e., a "partial write" may occur; -the caller should check the return value from +the caller should check the return value from .BR write (2) to see how many bytes were actually written), and these bytes may be interleaved with writes by other processes. .SS "Open File Status Flags" -The only open file status flags that can be meaningfully applied to +The only open file status flags that can be meaningfully applied to a pipe or FIFO are .B O_NONBLOCK -and +and .BR O_ASYNC . Setting the .B O_ASYNC -flag for the read end of a pipe causes a signal +flag for the read end of a pipe causes a signal .RB ( SIGIO by default) to be generated when new input becomes available on the pipe (see .BR fcntl (2) for details). On Linux, -.B O_ASYNC +.B O_ASYNC is supported for pipes and FIFOs only since kernel 2.6. .SS "Portability notes" -On some systems (but not Linux), pipes are bidirectional: +On some systems (but not Linux), pipes are bidirectional: data can be transmitted in both directions between the pipe ends. According to POSIX.1-2001, pipes only need to be unidirectional. -Portable applications should avoid reliance on +Portable applications should avoid reliance on bidirectional pipe semantics. .SH "SEE ALSO" .BR dup (2), diff --git a/man7/posixoptions.7 b/man7/posixoptions.7 index e403faa57c..3c50006267 100644 --- a/man7/posixoptions.7 +++ b/man7/posixoptions.7 @@ -32,7 +32,8 @@ to test the availability of interfaces at compile time, and functions .BR fpathconf (3), .BR pathconf (3), .BR confstr (3) -to do this at run time. From shell scripts one can use +to do this at run time. +From shell scripts one can use .BR getconf (1). For more detail, see .BR sysconf (3). @@ -132,7 +133,8 @@ is present. .\" .SS "FR" .\" Fortran runtime .SS "--- - _POSIX_FILE_LOCKING - _SC_FILE_LOCKING" -This option has been deleted. Not in final XPG6. +This option has been deleted. +Not in final XPG6. .SS "FSC - _POSIX_FSYNC - _SC_FSYNC " The function .IR fsync () @@ -156,20 +158,24 @@ then the system implements POSIX-style job control, and the functions are present. .fi .SS "MF - _POSIX_MAPPED_FILES - _SC_MAPPED_FILES" -Shared memory is supported. The include file +Shared memory is supported. +The include file .I <sys/mman.h> -is present. The functions +is present. +The functions .IR mmap (), .IR msync (), .IR munmap () are present. .SS "ML - _POSIX_MEMLOCK - _SC_MEMLOCK" -Shared memory can be locked into core. The functions +Shared memory can be locked into core. +The functions .IR mlockall (), .IR munlockall () are present. .SS "MR/MLR - _POSIX_MEMLOCK_RANGE - _SC_MEMLOCK_RANGE" -More precisely, ranges can be locked into core. The functions +More precisely, ranges can be locked into core. +The functions .IR mlock (), .IR munlock () are present. @@ -180,7 +186,8 @@ is present. .SS "MSG - _POSIX_MESSAGE_PASSING - _SC_MESSAGE_PASSING" The include file .IR <mqueue.h> -is present. The functions +is present. +The functions .br .nf .in +4 @@ -210,7 +217,8 @@ Affected functions are .in -4 .fi .SS "--- - _POSIX_MULTI_PROCESS - _SC_MULTI_PROCESS" -This option has been deleted. Not in final XPG6. +This option has been deleted. +Not in final XPG6. .\" .SS "MX" .\" IEC 60559 Floating-Point Option. .SS "--- - _POSIX_NO_TRUNC" @@ -231,7 +239,8 @@ This affects the functions .SS "PS - _POSIX_PRIORITY_SCHEDULING - _SC_PRIORITY_SCHEDULING" The include file .I <sched.h> -is present. The functions +is present. +The functions .br .nf .in +4 @@ -259,11 +268,13 @@ If also _POSIX_SPAWN is in effect, then the functions are present. .fi .SS "RS - _POSIX_RAW_SOCKETS" -Raw sockets are supported. Affected functions are +Raw sockets are supported. +Affected functions are .IR getsockopt (), .IR setsockopt (). .SS "--- - _POSIX_READER_WRITER_LOCKS - _SC_READER_WRITER_LOCKS" -This option implies the _POSIX_THREADS option. Conversely, +This option implies the _POSIX_THREADS option. +Conversely, under POSIX.1-2001 the _POSIX_THREADS option implies this option. .nf The functions @@ -281,7 +292,8 @@ The functions are present. .fi .SS "RTS - _POSIX_REALTIME_SIGNALS - _SC_REALTIME_SIGNALS" -Realtime signals are supported. The functions +Realtime signals are supported. +The functions .br .nf .in +4 @@ -579,7 +591,8 @@ Affected functions are .br .fi .SS "THR - _POSIX_THREADS - _SC_THREADS" -Basic support for POSIX threads is available. The functions +Basic support for POSIX threads is available. +The functions .br .nf .in +4 @@ -670,7 +683,8 @@ The functions .fi are present. .SS "TRC - _POSIX_TRACE - _SC_TRACE" -POSIX tracing is available. The functions +POSIX tracing is available. +The functions .br .nf .in +4 @@ -771,7 +785,8 @@ The functions .fi are present. .SS "--- - _POSIX_VDISABLE" -Always present (probably 0). Value to set a changeable special control +Always present (probably 0). +Value to set a changeable special control character to indicate that it is disabled. .SH "XOPEN EXTENSIONS" .BR _XOPEN_CRYPT , diff --git a/man7/pthreads.7 b/man7/pthreads.7 index 02ad57a508..b4c384a189 100644 --- a/man7/pthreads.7 +++ b/man7/pthreads.7 @@ -137,7 +137,7 @@ latter being the default (if supported by the underlying kernel). .SS LinuxThreads The notable features of this implementation are the following: .IP \- 3 -In addition to the main (initial) thread, +In addition to the main (initial) thread, and the threads that the program creates using .BR pthread_create (), the implementation creates a "manager" thread. @@ -265,7 +265,7 @@ Only the main thread is permitted to start a new session using .IP \- 3 Only the main thread is permitted to make the process into a process group leader using -.BR setpgid (2) +.BR setpgid (2) (fixed in kernel 2.6.16). .IP \- 3 Threads have distinct alternate signal stack settings. @@ -277,7 +277,7 @@ the threads initially share an alternate signal stack Note the following further points about the NPTL implementation: .IP \- 3 If the stack size soft resource limit (see the description of -.B RLIMIT_STACK +.B RLIMIT_STACK in .BR setrlimit (2)) is set to a value other than @@ -286,7 +286,7 @@ then this value defines the default stack size for new threads. To be effective, this limit must be set before the program is executed, perhaps using the .I ulimit -s -shell built-in command +shell built-in command .RI ( "limit stacksize" in the C shell). .SS "Determining the Threading Implementation" diff --git a/man7/pty.7 b/man7/pty.7 index 55f1bd7cab..ea11779b8b 100644 --- a/man7/pty.7 +++ b/man7/pty.7 @@ -10,12 +10,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -23,25 +23,25 @@ .SH NAME pty \- pseudo-terminal interfaces .SH DESCRIPTION -A pseudo-terminal is a pair of virtual character devices that -provide a bidirectional communication channel. -One end of the channel is called the +A pseudo-terminal is a pair of virtual character devices that +provide a bidirectional communication channel. +One end of the channel is called the .IR master ; -the other end is called the +the other end is called the .IR slave . The slave end of the pseudo-terminal provides an interface that behaves exactly like a classical terminal. A process that expects to be connected to a terminal, can open the slave end of a pseudo-terminal and then be driven by a program that has opened the master end. -Anything that is written on the master end is provided to the process -on the slave end as though it was input typed on a terminal. +Anything that is written on the master end is provided to the process +on the slave end as though it was input typed on a terminal. For example, writing the interrupt character (usually control-C) to the master device would cause an interrupt signal (SIGINT) -to be generated for the foreground process group +to be generated for the foreground process group that is connected to the slave. -Conversely, anything that is written to the slave end of the -pseudo-terminal can be read by the process that is connected to +Conversely, anything that is written to the slave end of the +pseudo-terminal can be read by the process that is connected to the master end. Pseudo-terminals are used by applications such as network login services .RB ( ssh "(1), " rlogin "(1), " telnet (1)), @@ -53,30 +53,30 @@ and Historically, two pseudo-terminal APIs have evolved: BSD and System V. SUSv1 standardized a pseudo-terminal API based on the System V API, -and this API should be employed in all new programs that use +and this API should be employed in all new programs that use pseudo-terminals. -Linux provides both BSD-style and (standardised) System V-style +Linux provides both BSD-style and (standardised) System V-style pseudo-terminals. -System V-style terminals are commonly called Unix 98 pseudo-terminals +System V-style terminals are commonly called Unix 98 pseudo-terminals on Linux systems. Since kernel 2.6.4, BSD-style pseudo-terminals are considered deprecated -(they can be disabled when configuring the kernel); +(they can be disabled when configuring the kernel); Unix 98 pseudo-terminals should be used in new applications. .SS "Unix 98 pseudo-terminals" -An unused Unix 98 pseudo-terminal master is opened by calling +An unused Unix 98 pseudo-terminal master is opened by calling .BR posix_openpt (3). (This function opens the master clone device, -.IR /dev/ptmx ; -see +.IR /dev/ptmx ; +see .BR pts (4).) After performing any program-specific initialisations, -changing the ownership and permissions of the slave device using +changing the ownership and permissions of the slave device using .BR grantpt (3), -and unlocking the slave using +and unlocking the slave using .BR unlockpt (3)), the corresponding slave device can be opened by passing -the name returned by +the name returned by .BR ptsname (3) in a call to .BR open (2). @@ -84,10 +84,10 @@ in a call to The Linux kernel imposes a limit on the number of available Unix 98 pseudo-terminals. In kernels up to and including 2.6.3, this limit is configured -at kernel compilation time (CONFIG_UNIX98_PTYS), +at kernel compilation time (CONFIG_UNIX98_PTYS), and the permitted number of pseudo-terminals can be up to 2048, with a default setting of 256. -Since kernel 2.6.4, the limit is dynamically adjustable via +Since kernel 2.6.4, the limit is dynamically adjustable via .IR /proc/sys/kernel/pty/max , and a corresponding file, .IR /proc/sys/kernel/pty/nr , @@ -96,45 +96,45 @@ For further details on these two files, see .BR proc (5). .SS "BSD pseudo-terminals" BSD-style pseudo-terminals are provided as pre-created pairs, with -names of the form +names of the form .I /dev/ptyXY (master) and .I /dev/ttyXY (slave), where X is a letter from the 16-character set [p-za-e], and Y is a letter from the 16-character set [0-9a-f]. -(The precise range of letters in these two sets varies across Unix +(The precise range of letters in these two sets varies across Unix implementations.) For example, .I /dev/ptyp1 and .I /dev/ttyp1 constitute a BSD pseudo-terminal pair. -A process finds an unused pseudo-terminal pair by trying to +A process finds an unused pseudo-terminal pair by trying to .BR open (2) each pseudo-terminal master until an open succeeds. -The corresponding pseudo-terminal slave (substitute "tty" +The corresponding pseudo-terminal slave (substitute "tty" for "pty" in the name of the master) can then be opened. .SH "NOTES" -A description of the -.B TIOCPKT -.BR ioctl (), +A description of the +.B TIOCPKT +.BR ioctl (), which controls packet mode operation, can be found in .BR tty_ioctl (4). The BSD ioctl()s TIOCSTOP, TIOCSTART, TIOCUCNTL, TIOCREMOTE have not been implemented under Linux. .SH "FILES" -.I /dev/ptmx +.I /dev/ptmx (Unix 98 master clone device) .br .I /dev/pts/* (Unix 98 slave devices) .br -.I /dev/pty[p-za-e][0-9a-f] +.I /dev/pty[p-za-e][0-9a-f] (BSD master devices) .br -.I /dev/tty[p-za-e][0-9a-f] +.I /dev/tty[p-za-e][0-9a-f] (BSD slave devices) .I .SH "SEE ALSO" diff --git a/man7/raw.7 b/man7/raw.7 index f62dd71261..1a4e81e521 100644 --- a/man7/raw.7 +++ b/man7/raw.7 @@ -6,7 +6,7 @@ .\" and in case of nontrivial modification author and date .\" of the modification is added to the header. .\" $Id: raw.7,v 1.6 1999/06/05 10:32:08 freitag Exp $ -.TH RAW 7 1998-10-02 "Linux Man Page" "Linux Programmer's Manual" +.TH RAW 7 1998-10-02 "Linux Man Page" "Linux Programmer's Manual" .SH NAME raw, SOCK_RAW \- Linux IPv4 raw sockets .SH SYNOPSIS @@ -14,10 +14,10 @@ raw, SOCK_RAW \- Linux IPv4 raw sockets .br .B #include <netinet/in.h> .br -.BI "raw_socket = socket(PF_INET, SOCK_RAW, int " protocol ); +.BI "raw_socket = socket(PF_INET, SOCK_RAW, int " protocol ); .SH DESCRIPTION Raw sockets allow new IPv4 protocols to be implemented in user space. -A raw socket receives or sends the raw datagram not +A raw socket receives or sends the raw datagram not including link level headers. The IPv4 layer generates an IP header when sending a packet unless the @@ -26,22 +26,22 @@ socket option is enabled on the socket. When it is enabled, the packet must contain an IP header. For receiving the IP header is always included in the packet. -Only processes with an effective user ID of 0 or the -.B CAP_NET_RAW +Only processes with an effective user ID of 0 or the +.B CAP_NET_RAW capability are allowed to open raw sockets. All packets or errors matching the .I protocol number specified -for the raw socket are passed to this socket. For a list of the -allowed protocols see RFC\ 1700 assigned numbers and +for the raw socket are passed to this socket. +For a list of the allowed protocols see RFC\ 1700 assigned numbers and .BR getprotobyname (3). A protocol of .B IPPROTO_RAW implies enabled -.B IP_HDRINCL -and is able to send any IP protocol that is specified in the passed +.B IP_HDRINCL +and is able to send any IP protocol that is specified in the passed header. Receiving of all IP protocols via .B IPPROTO_RAW @@ -60,10 +60,11 @@ Total Length:Always filled in. .RE .sp .PP -If +If .B IP_HDRINCL is specified and the IP header has a non-zero destination address then -the destination address of the socket is used to route the packet. When +the destination address of the socket is used to route the packet. +When .B MSG_DONTROUTE is specified the destination address should refer to a local interface, otherwise a routing table lookup is done anyway but gatewayed routes @@ -74,78 +75,81 @@ If isn't set then IP header options can be set on raw sockets with .BR setsockopt (2); see -.BR ip (7) +.BR ip (7) for more information. In Linux 2.2 all IP header fields and options can be set using -IP socket options. This means raw sockets are usually only needed for new +IP socket options. +This means raw sockets are usually only needed for new protocols or protocols with no user interface (like ICMP). When a packet is received, it is passed to any raw sockets which have been bound to its protocol before it is passed to other protocol handlers -(e.g. kernel protocol modules). +(e.g. kernel protocol modules). .SH "ADDRESS FORMAT" -Raw sockets use the standard -.I sockaddr_in -address structure defined in +Raw sockets use the standard +.I sockaddr_in +address structure defined in .BR ip (7). -The +The .I sin_port -field could be used to specify the IP protocol number, +field could be used to specify the IP protocol number, but it is ignored for sending in Linux 2.2 and should be always set to 0 (see BUGS) -For incoming packets -.I sin_port -is set to the protocol of the packet. +For incoming packets +.I sin_port +is set to the protocol of the packet. See the .I <netinet/in.h> -include file for valid IP protocols. +include file for valid IP protocols. .SH "SOCKET OPTIONS" Raw socket options can be set with .BR setsockopt (2) and read with .BR getsockopt (2) -by passing the +by passing the .B IPPROTO_RAW .\" Or SOL_RAW on Linux -family flag. +family flag. .TP .B ICMP_FILTER -Enable a special filter for raw sockets bound to the -.B IPPROTO_ICMP -protocol. The value has a bit set for each ICMP message type which -should be filtered out. The default is to filter no ICMP messages. +Enable a special filter for raw sockets bound to the +.B IPPROTO_ICMP +protocol. +The value has a bit set for each ICMP message type which +should be filtered out. +The default is to filter no ICMP messages. .PP -In addition all +In addition all .BR ip (7) -.B IPPROTO_IP +.B IPPROTO_IP socket options valid for datagram sockets are supported. .SH NOTES -By default raw sockets do path MTU (Maximum Transmission Unit) discovery. +By default raw sockets do path MTU (Maximum Transmission Unit) discovery. This means the kernel will keep track of the MTU to a specific target IP address and return .I EMSGSIZE -when a raw packet write exceeds it. -When this happens the application should decrease the packet size. +when a raw packet write exceeds it. +When this happens the application should decrease the packet size. Path MTU discovery can be also turned off using the .B IP_MTU_DISCOVER -socket option or the +socket option or the .B ip_no_pmtu_disc -sysctl, see -.BR ip(7) -for details. +sysctl, see +.BR ip(7) +for details. When turned off raw sockets will fragment outgoing packets -that exceed the interface MTU. +that exceed the interface MTU. However disabling it is not recommended for performance and reliability reasons. -A raw socket can be bound to a specific local address using the +A raw socket can be bound to a specific local address using the .BR bind (2) -call. +call. If it isn't bound all packets with the specified IP protocol are received. In addition a RAW socket can be bound to a specific network device using .BR SO_BINDTODEVICE ; -see +see .BR socket (7). An @@ -155,56 +159,60 @@ If you really want to receive all IP packets use a .BR packet (7) socket with the .B ETH_P_IP -protocol. Note that packet sockets don't reassemble IP fragments, +protocol. +Note that packet sockets don't reassemble IP fragments, unlike raw sockets. -If you want to receive all ICMP packets for a datagram socket +If you want to receive all ICMP packets for a datagram socket it is often better to use .B IP_RECVERR on that particular socket; see .BR ip (7). Raw sockets may tap all IP protocols in Linux, even -protocols like ICMP or TCP which have a protocol module in the kernel. +protocols like ICMP or TCP which have a protocol module in the kernel. In this case the packets are passed to both the kernel module and the raw -socket(s). -This should not be relied upon in portable programs, many other BSD +socket(s). +This should not be relied upon in portable programs, many other BSD socket implementation have limitations here. -Linux never changes headers passed from the user (except for filling +Linux never changes headers passed from the user (except for filling in some zeroed fields as described for .BR IP_HDRINCL ). This differs from many other implementations of raw sockets. -RAW sockets are generally rather unportable and should be avoided in +RAW sockets are generally rather unportable and should be avoided in programs intended to be portable. -Sending on raw sockets should take the IP protocol from +Sending on raw sockets should take the IP protocol from .IR sin_port ; -this ability was lost in Linux 2.2. +this ability was lost in Linux 2.2. The workaround is to use .BR IP_HDRINCL . .SH "ERROR HANDLING" Errors originating from the network are only passed to the user when the -socket is connected or the +socket is connected or the .B IP_RECVERR -flag is enabled. For connected sockets only -.B EMSGSIZE -and -.B EPROTO -are passed for compatibility. With +flag is enabled. +For connected sockets only +.B EMSGSIZE +and +.B EPROTO +are passed for compatibility. +With .B IP_RECVERR -all network errors are saved in the error queue. +all network errors are saved in the error queue. .SH ERRORS .TP -.B EMSGSIZE -Packet too big. Either Path MTU Discovery is enabled (the +.B EMSGSIZE +Packet too big. +Either Path MTU Discovery is enabled (the .B IP_MTU_DISCOVER -socket flag) or the packet size exceeds the maximum allowed IPv4 -packet size of 64KB. +socket flag) or the packet size exceeds the maximum allowed IPv4 +packet size of 64KB. .TP .B EACCES -User tried to send to a broadcast address without having the +User tried to send to a broadcast address without having the broadcast flag set on the socket. .TP .B EPROTO @@ -214,45 +222,45 @@ An ICMP error has arrived reporting a parameter problem. An invalid memory address was supplied. .TP .B EOPNOTSUPP -Invalid flag has been passed to a socket call (like +Invalid flag has been passed to a socket call (like .BR MSG_OOB ). .TP .B EINVAL Invalid argument. .TP .B EPERM -The user doesn't have permission to open raw sockets. Only processes -with a effective user ID of 0 or the -.B CAP_NET_RAW +The user doesn't have permission to open raw sockets. +Only processes with a effective user ID of 0 or the +.B CAP_NET_RAW attribute may do that. .SH VERSIONS -.B IP_RECVERR -and -.B ICMP_FILTER -are new in Linux 2.2. They are Linux extensions -and should not be used in portable programs. +.B IP_RECVERR +and +.B ICMP_FILTER +are new in Linux 2.2. +They are Linux extensions and should not be used in portable programs. -Linux 2.0 enabled some bug-to-bug compatibility with BSD in the -raw socket code when the -SO_BSDCOMPAT socket option was set \(em since Linux 2.2, +Linux 2.0 enabled some bug-to-bug compatibility with BSD in the +raw socket code when the +SO_BSDCOMPAT socket option was set \(em since Linux 2.2, this option no longer has that effect. .SH BUGS Transparent proxy extensions are not described. -When the +When the .B IP_HDRINCL -option is set datagrams will not be fragmented and are limited to -the interface MTU. +option is set datagrams will not be fragmented and are limited to +the interface MTU. Setting the IP protocol for sending in .I sin_port -got lost in Linux 2.2. +got lost in Linux 2.2. The protocol that the socket was bound to or that -was specified in the initial +was specified in the initial .BR socket (2) call is always used. .SH AUTHORS -This man page was written by Andi Kleen. +This man page was written by Andi Kleen. .SH "SEE ALSO" .BR recvmsg (2), .BR sendmsg (2), @@ -260,10 +268,10 @@ This man page was written by Andi Kleen. .BR ip (7), .BR socket (7) -.B RFC\ 1191 +.B RFC\ 1191 for path MTU discovery. -.B RFC\ 791 +.B RFC\ 791 and the .I <linux/ip.h> include file for the IP protocol. diff --git a/man7/regex.7 b/man7/regex.7 index 201dfb1748..672bfff3e0 100644 --- a/man7/regex.7 +++ b/man7/regex.7 @@ -4,24 +4,24 @@ .\" Copyright 1992, 1993, 1994 Henry Spencer. All rights reserved. .\" This software is not subject to any license of the American Telephone .\" and Telegraph Company or of the Regents of the University of California. -.\" +.\" .\" Permission is granted to anyone to use this software for any purpose .\" on any computer system, and to alter it and redistribute it, subject .\" to the following restrictions: -.\" +.\" .\" 1. The author is not responsible for the consequences of use of this .\" software, no matter how awful, even if they arise from flaws in it. -.\" +.\" .\" 2. The origin of this software must not be misrepresented, either by .\" explicit claim or by omission. Since few users ever read sources, .\" credits must appear in the documentation. -.\" +.\" .\" 3. Altered versions must be plainly marked as such, and must not be .\" misrepresented as being the original software. Since few users .\" ever read sources, credits must appear in the documentation. -.\" +.\" .\" 4. This notice may not be removed or altered. -.\" +.\" .\" In order to comply with `credits must appear in the documentation' .\" I added an AUTHOR paragraph below - aeb. .\" @@ -32,7 +32,7 @@ .\" .ie t .ds dg \(dg .el .ds dg (!) -.TH REGEX 7 1994-02-07 +.TH REGEX 7 1994-02-07 .SH NAME regex \- POSIX.2 regular expressions .SH DESCRIPTION @@ -126,7 +126,7 @@ or a collating-sequence name for either) enclosed in `[.' and `.]' stands for the sequence of characters of that collating element. The sequence is a single element of the bracket expression's list. -A bracket expression containing a multi-character collating element +A bracket expression containing a multi-character collating element can thus match more than one character, e.g. if the collating sequence includes a `ch' collating element, then the RE `[[.ch.]]*c' matches the first five characters diff --git a/man7/rtnetlink.7 b/man7/rtnetlink.7 index 35c5a70809..f21a3490e0 100644 --- a/man7/rtnetlink.7 +++ b/man7/rtnetlink.7 @@ -6,9 +6,9 @@ .\" and in case of nontrivial modification author and date .\" of the modification is added to the header. .\" Based on the original comments from Alexey Kuznetsov, written with -.\" help from Matthew Wilcox. +.\" help from Matthew Wilcox. .\" $Id: rtnetlink.7,v 1.8 2000/01/22 01:55:04 freitag Exp $ -.TH RTNETLINK 7 1999-04-30 "Linux Man Page" "Linux Programmer's Manual" +.TH RTNETLINK 7 1999-04-30 "Linux Man Page" "Linux Programmer's Manual" .SH NAME rtnetlink, NETLINK_ROUTE \- Linux IPv4 routing socket .SH SYNOPSIS @@ -22,18 +22,19 @@ rtnetlink, NETLINK_ROUTE \- Linux IPv4 routing socket .BI "rtnetlink_socket = socket(PF_NETLINK, int " socket_type ", NETLINK_ROUTE);" .SH DESCRIPTION -Rtnetlink allows the kernel's routing tables to be read and altered. +Rtnetlink allows the kernel's routing tables to be read and altered. It is used within the kernel to communicate between -various subsystems, though this usage is not documented here, and for +various subsystems, though this usage is not documented here, and for communication with user-space programs. Network routes, ip addresses, link parameters, neighbour setups, queueing disciplines, traffic classes and packet classifiers may all be controlled through .B NETLINK_ROUTE -sockets. It is based on netlink messages, see +sockets. +It is based on netlink messages, see .BR netlink (7) -for more information. -.\" FIXME all these macros could be moved to rtnetlink(3) +for more information. +.\" FIXME all these macros could be moved to rtnetlink(3) .SH "ROUTING ATTRIBUTES" Some rtnetlink messages have optional attributes after the initial header: @@ -41,11 +42,11 @@ Some rtnetlink messages have optional attributes after the initial header: struct rtattr { unsigned short rta_len; /* Length of option */ unsigned short rta_type; /* Type of option */ - /* Data follows */ + /* Data follows */ }; .fi -These attributes should be only manipulated using the RTA_* macros +These attributes should be only manipulated using the RTA_* macros or libnetlink, see .BR rtnetlink (3). .SH MESSAGES @@ -53,7 +54,7 @@ Rtnetlink consists of these message types (in addition to standard netlink messages): .TP .BR RTM_NEWLINK ", " RTM_DELLINK ", " RTM_GETLINK -Create, remove or get information about a specific network interface. +Create, remove or get information about a specific network interface. These messages contain an .B ifinfomsg structure followed by a series of @@ -63,7 +64,7 @@ structures. .nf struct ifinfomsg { unsigned char ifi_family; /* AF_UNSPEC */ - unsigned short ifi_type; /* Device type */ + unsigned short ifi_type; /* Device type */ int ifi_index; /* Interface index */ unsigned int ifi_flags; /* Device flags */ unsigned int ifi_change; /* change mask */ @@ -71,13 +72,13 @@ struct ifinfomsg { .fi .\" FIXME ifi_type -.B ifi_flags +.B ifi_flags contains the device flags, see .BR netdevice(7); .B ifi_index is the unique interface index, .B ifi_change -is reserved for future use and should be always set to 0xFFFFFFFF. +is reserved for future use and should be always set to 0xFFFFFFFF. .TS tab(:); c @@ -86,7 +87,7 @@ Routing attributes rta_type:value type:description _ IFLA_UNSPEC:-:unspecified. -IFLA_ADDRESS:hardware address:interface L2 address +IFLA_ADDRESS:hardware address:interface L2 address IFLA_BROADCAST:hardware address:L2 broadcast address. IFLA_IFNAME:asciiz string:Device name. IFLA_MTU:unsigned int:MTU of the device. @@ -98,10 +99,13 @@ T}:Interface Statistics. .TE .TP .BR RTM_NEWADDR ", " RTM_DELADDR ", " RTM_GETADDR -Add, remove or receive information about an IP address associated with -an interface. In Linux 2.2 an interface can carry multiple IP addresses, -this replaces the alias device concept in 2.0. In Linux 2.2 these messages -support IPv4 and IPv6 addresses. They contain an +Add, remove or receive information about an IP address associated with +an interface. +In Linux 2.2 an interface can carry multiple IP addresses, +this replaces the alias device concept in 2.0. +In Linux 2.2 these messages +support IPv4 and IPv6 addresses. +They contain an .B ifaddrmsg structure, optionally followed by .B rtaddr @@ -118,21 +122,21 @@ struct ifaddrmsg { .fi .B ifa_family -is the address family type (currently +is the address family type (currently .B AF_INET or -.BR AF_INET6 ), +.BR AF_INET6 ), .B ifa_prefixlen -is the length of the address mask of the address if defined for the -family (like for IPv4), +is the length of the address mask of the address if defined for the +family (like for IPv4), .B ifa_scope is the address scope, .B ifa_index -is the interface index of the interface the address is associated with. +is the interface index of the interface the address is associated with. .B ifa_flags is a flag word of .B IFA_F_SECONDARY -for secondary address (old alias interface), +for secondary address (old alias interface), .B IFA_F_PERMANENT for a permanent address set by the user and other undocumented flags. @@ -149,7 +153,7 @@ IFA_LOCAL:raw protocol address:local address IFA_LABEL:asciiz string:name of the interface IFA_BROADCAST:raw protocol address:broadcast address. IFA_ANYCAST:raw protocol address:anycast address -IFA_CACHEINFO:struct ifa_cacheinfo:Address information. +IFA_CACHEINFO:struct ifa_cacheinfo:Address information. .TE .\" FIXME struct ifa_cacheinfo .TP @@ -157,18 +161,19 @@ IFA_CACHEINFO:struct ifa_cacheinfo:Address information. Create, remove or receive information about a network route. These messages contain an .B rtmsg -structure with an optional sequence of +structure with an optional sequence of .B rtattr -structures following. For +structures following. +For .B RTM_GETROUTE -setting -.B rtm_dst_len -and -.B rtm_src_len +setting +.B rtm_dst_len +and +.B rtm_src_len to 0 means you get all entries for the specified routing table. -For the other fields except -.B rtm_table -and +For the other fields except +.B rtm_table +and .B rtm_protocol 0 is the wildcard. @@ -176,12 +181,12 @@ and struct rtmsg { unsigned char rtm_family; /* Address family of route */ unsigned char rtm_dst_len; /* Length of source */ - unsigned char rtm_src_len; /* Length of destination */ + unsigned char rtm_src_len; /* Length of destination */ unsigned char rtm_tos; /* TOS filter */ unsigned char rtm_table; /* Routing table ID */ unsigned char rtm_protocol; /* Routing protocol; see below */ - unsigned char rtm_scope; /* See below */ + unsigned char rtm_scope; /* See below */ unsigned char rtm_type; /* See below */ unsigned int rtm_flags; @@ -231,13 +236,14 @@ RTPROT_STATIC:by the administrator Values larger than .B RTPROT_STATIC are not interpreted by the kernel, they are just for user information. -They may be used to tag the source of a routing information or to -distinguish between multiple routing daemons. See +They may be used to tag the source of a routing information or to +distinguish between multiple routing daemons. +See .IR <linux/rtnetlink.h> -for the routing daemon identifiers which are already assigned. +for the routing daemon identifiers which are already assigned. -.B rtm_scope -is the distance to the destination: +.B rtm_scope +is the distance to the destination: .TS tab(:); @@ -313,8 +319,9 @@ RTA_CACHEINFO:: .B Fill these values in! .TP .BR RTM_NEWNEIGH ", " RTM_DELNEIGH ", " RTM_GETNEIGH -Add, remove or receive information about a neighbour table -entry (e.g. an ARP entry). The message contains an +Add, remove or receive information about a neighbour table +entry (e.g. an ARP entry). +The message contains an .B ndmsg structure. @@ -322,9 +329,9 @@ structure. struct ndmsg { unsigned char ndm_family; int ndm_ifindex; /* Interface index */ - __u16 ndm_state; /* State */ + __u16 ndm_state; /* State */ __u8 ndm_flags; /* Flags */ - __u8 ndm_type; + __u8 ndm_type; }; struct nda_cacheinfo { @@ -336,7 +343,7 @@ struct nda_cacheinfo { .fi .B ndm_state -is a bitmask of the following states: +is a bitmask of the following states: .TS tab(:); @@ -388,11 +395,13 @@ then a header follows .TP .BR RTM_NEWRULE ", " RTM_DELRULE ", " RTM_GETRULE -Add, delete or retrieve a routing rule. Carries a +Add, delete or retrieve a routing rule. +Carries a .I struct rtmsg .TP .BR RTM_NEWQDISC ", " RTM_DELQDISC ", " RTM_GETQDISC -Add, remove or get a queueing discipline. The message contains a +Add, remove or get a queueing discipline. +The message contains a .I struct tcmsg and may be followed by a series of attributes. @@ -401,7 +410,7 @@ attributes. struct tcmsg { unsigned char tcm_family; int tcm_ifindex; /* interface index */ - __u32 tcm_handle; /* Qdisc handle */ + __u32 tcm_handle; /* Qdisc handle */ __u32 tcm_parent; /* Parent qdisc */ __u32 tcm_info; }; @@ -426,17 +435,18 @@ In addition various other qdisc module specific attributes are allowed. For more information see the appropriate include files. .TP .BR RTM_NEWTCLASS ", " RTM_DELTCLASS ", " RTM_GETTCLASS -Add, remove or get a traffic class. These messages contain a +Add, remove or get a traffic class. +These messages contain a .I struct tcmsg as described above. .TP .BR RTM_NEWTFILTER ", " RTM_DELTFILTER ", " RTM_GETTFILTER -Add, remove or receive information about a traffic filter. These -messages contain a +Add, remove or receive information about a traffic filter. +These messages contain a .I struct tcmsg as described above. .SH VERSIONS -.B rtnetlink +.B rtnetlink is a new feature of Linux 2.2. .SH BUGS This manual page is lacking and incomplete. diff --git a/man7/sem_overview.7 b/man7/sem_overview.7 index 1c4b1253db..6cc2ca5fef 100644 --- a/man7/sem_overview.7 +++ b/man7/sem_overview.7 @@ -11,12 +11,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -27,27 +27,27 @@ sem_overview \- Overview of POSIX semaphores POSIX semaphores allow processes and threads to synchronise their actions. A semaphore is an integer whose value is never allowed to fall below zero. -Two operations can be performed on semaphores: -increment the semaphore value by one +Two operations can be performed on semaphores: +increment the semaphore value by one .RB ( sem_post (3)); and decrement the semaphore value by one .RB ( sem_wait (3)). -If the value of a semaphore is currently zero, then a +If the value of a semaphore is currently zero, then a .BR sem_wait (3) operation will block until the value becomes greater than zero. -POSIX semaphores come in two forms: named semaphores and +POSIX semaphores come in two forms: named semaphores and unnamed semaphores. .SS Named semaphores -A named semaphore is identified by a name of the form +A named semaphore is identified by a name of the form .IR /somename . -Two processes can operate on the same named semaphore by passing +Two processes can operate on the same named semaphore by passing the same name to .BR sem_open (3). -The +The .BR sem_open (3) -function creates a new named semaphore or opens an existing +function creates a new named semaphore or opens an existing named semaphore. After the semaphore has been opened, it can be operated on using .BR sem_post (3) @@ -56,20 +56,20 @@ and When a process has finished using the semaphore, it can use .BR sem_close (3) to close the semaphore. -When all processes have finished using the semaphore, +When all processes have finished using the semaphore, it can be removed from the system using .BR sem_unlink (3). .SS Unnamed semaphores (memory-based semaphores) An unnamed semaphore does not have a name. Instead the semaphore is placed in a region of memory that -is shared between multiple threads (a +is shared between multiple threads (a .IR "thread-shared semaphore" ) -or processes (a +or processes (a .IR "process-shared semaphore" ). -A thread-shared semaphore is placed in an area of memory shared +A thread-shared semaphore is placed in an area of memory shared between by the threads of a process, for example, a global variable. -A process-shared semaphore must be placed in a shared memory region -(e.g., a System V shared memory segment created using +A process-shared semaphore must be placed in a shared memory region +(e.g., a System V shared memory segment created using .BR semget (2), or a POSIX shared memory object built created using .BR shm_open (3)). @@ -86,9 +86,9 @@ the semaphore should be destroyed using .BR sem_destroy (3). .SH LINUX SPECIFIC DETAILS .SS Versions -Prior to kernel 2.6, Linux only supported unnamed, +Prior to kernel 2.6, Linux only supported unnamed, thread-shared semaphores. -On a system with Linux 2.6 and a glibc that provides the NPTL +On a system with Linux 2.6 and a glibc that provides the NPTL threading implementation, a complete implementation of POSIX semaphores is provided. .SS Persistence @@ -102,10 +102,10 @@ Programs using the POSIX semaphores API must be compiled with to link against the real-time library, .IR librt . .SS Accessing named semaphores via the file system -On Linux, named semaphores are created in a virtual file system, +On Linux, named semaphores are created in a virtual file system, normally mounted under .IR /dev/shm , -with names of the form +with names of the form .IR \fBsem.\fPname . .SH "CONFORMING TO" POSIX.1-2001. @@ -115,8 +115,8 @@ System V semaphores .BR semop (2), etc.) are an older semaphore API. POSIX semaphores provide a simpler, and better designed interface than -System V semaphores; -on the other hand POSIX semaphores are less widely available +System V semaphores; +on the other hand POSIX semaphores are less widely available (especially on older systems) than System V semaphores. .SH EXAMPLE An example of the use of various POSIX semaphore functions is shown in diff --git a/man7/signal.7 b/man7/signal.7 index 5f3f0e6232..83a7d1be1f 100644 --- a/man7/signal.7 +++ b/man7/signal.7 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -42,9 +42,9 @@ signal \- list of available signals Linux supports both POSIX reliable signals (hereinafter "standard signals") and POSIX real-time signals. .SS "Signal Dispositions" -Each signal has a current +Each signal has a current .IR disposition , -which determines how the process behaves when it is delivered +which determines how the process behaves when it is delivered the signal. The entries in the "Action" column of the tables below specify @@ -65,55 +65,56 @@ A process can change the disposition of a signal using .BR sigaction (2) or (less portably) .BR signal (2). -Using these system calls, a process can elect one of the -following behaviours to occur on delivery of the signal: -perform the default action; ignore the signal; +Using these system calls, a process can elect one of the +following behaviours to occur on delivery of the signal: +perform the default action; ignore the signal; or catch the signal with a -.IR "signal handler" , -a programmer-defined function that is automatically invoked +.IR "signal handler" , +a programmer-defined function that is automatically invoked when the signal is delivered. The signal disposition is a per-process attribute: -in a multithreaded application, the disposition of a +in a multithreaded application, the disposition of a particular signal is the same for all threads. .SS "Signal Mask and Pending Signals" A signal may be .IR blocked , which means that it will not be delivered until it is later unblocked. Between the time when it is generated and when it is delivered -a signal is said to be +a signal is said to be .IR pending . -Each thread in a process has an independent -.IR "signal mask" , +Each thread in a process has an independent +.IR "signal mask" , which indicates the set of signals that the thread is currently blocking. A thread can manipulate its signal mask using .BR pthread_sigmask (3). -In a traditional single-threaded application, +In a traditional single-threaded application, .BR sigprocmask (2) can be used to manipulate the signal mask. A signal may be generated (and thus pending) for a process as a whole (e.g., when sent using -.BR kill (2)) -or for a specific thread (e.g., certain signals, -such as SIGSEGV and SIGFPE, generated as a -consequence of executing a specific machine-language instruction +.BR kill (2)) +or for a specific thread (e.g., certain signals, +such as SIGSEGV and SIGFPE, generated as a +consequence of executing a specific machine-language instruction are thread directed, as are signals targeted at a specific thread using .BR pthread_kill (2)). A process-directed signal may be delivered to any one of the threads that does not currently have the signal blocked. -If more than one of the threads has the signal unblocked, then the +If more than one of the threads has the signal unblocked, then the kernel chooses an arbitrary thread to which to deliver the signal. A thread can obtain the set of signals that it currently has pending using .BR sigpending (2). -This set will consist of the union of the set of pending -process-directed signals and the set of signals pending for +This set will consist of the union of the set of pending +process-directed signals and the set of signals pending for the calling thread. .SS "Standard Signals" -Linux supports the standard signals listed below. Several signal numbers +Linux supports the standard signals listed below. +Several signal numbers are architecture dependent, as indicated in the "Value" column. (Where three values are given, the first one is usually valid for alpha and sparc, the middle one for i386, ppc and sh, and @@ -154,7 +155,7 @@ and .B SIGSTOP cannot be caught, blocked, or ignored. -Next the signals not in the POSIX.1-1990 standard but described in +Next the signals not in the POSIX.1-1990 standard but described in SUSv2 and POSIX.1-2001. .TS l c c l @@ -211,7 +212,7 @@ on a sparc.) .B SIGEMT is not specified in POSIX.1-2001, but nevertheless appears -on most other Unix systems, +on most other Unix systems, where its default action is typically to terminate the process with a core dump. diff --git a/man7/socket.7 b/man7/socket.7 index ed55041976..f2683f2d87 100644 --- a/man7/socket.7 +++ b/man7/socket.7 @@ -1,7 +1,7 @@ '\" t .\" Don't change the first line, it tells man that we need tbl. .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>. -.\" and copyright (c) 1999 Matthew Wilcox. +.\" and copyright (c) 1999 Matthew Wilcox. .\" Permission is granted to distribute possibly modified copies .\" of this page provided the header is included verbatim, .\" and in case of nontrivial modification author and date @@ -13,7 +13,7 @@ .\" Modified, 27 May 2004, Michael Kerrisk <mtk-manpages@gmx.net> .\" Added notes on capability requirements .\" A few small grammar fixes -.\" +.\" .\" FIXME probably all PF_* should be AF_* in this page, since .\" POSIX only specifies the latter values. .\" @@ -25,11 +25,12 @@ socket \- Linux socket interface .br .IB mysocket " = socket(int " socket_family ", int " socket_type ", int " protocol ); .SH DESCRIPTION -This manual page describes the Linux networking socket layer user -interface. The BSD compatible sockets +This manual page describes the Linux networking socket layer user +interface. +The BSD compatible sockets are the uniform interface between the user process and the network protocol stacks in the kernel. -The protocol modules are grouped into +The protocol modules are grouped into .I protocol families like .BR PF_INET ", " PF_IPX ", " PF_PACKET @@ -39,19 +40,19 @@ like .B SOCK_STREAM or .BR SOCK_DGRAM . -See +See .BR socket (2) for more information on families and types. .SH "SOCKET LAYER FUNCTIONS" -These functions are used by the user process to send or receive packets -and to do other socket operations. +These functions are used by the user process to send or receive packets +and to do other socket operations. For more information see their respective manual pages. .BR socket (2) creates a socket, .BR connect (2) connects a socket to a remote socket address, -the +the .BR bind (2) function binds a socket to a local socket address, .BR listen (2) @@ -76,13 +77,13 @@ receive data from a socket. and .BR select (2) wait for arriving data or a readiness to send data. -In addition, the standard I/O operations like +In addition, the standard I/O operations like .BR write (2), .BR writev (2), .BR sendfile (2), .BR read (2), -and -.BR readv (2) +and +.BR readv (2) can be used to read and write data. .PP .BR getsockname (2) @@ -92,37 +93,37 @@ returns the remote socket address. .BR getsockopt (2) and .BR setsockopt (2) -are used to set or get socket layer or protocol options. +are used to set or get socket layer or protocol options. .BR ioctl (2) can be used to set or read some other options. .PP .BR close (2) is used to close a socket. .BR shutdown (2) -closes parts of a full duplex socket connection. +closes parts of a full duplex socket connection. .PP -Seeking, or calling -.BR pread (2) -or +Seeking, or calling +.BR pread (2) +or .BR pwrite (2) with a non-zero position is not supported on sockets. .PP -It is possible to do non-blocking I/O on sockets by setting the +It is possible to do non-blocking I/O on sockets by setting the .B O_NONBLOCK flag on a socket file descriptor using .BR fcntl (2). Then all operations that would block will (usually) return with -.B EAGAIN +.B EAGAIN (operation should be retried later); -.BR connect (2) -will return +.BR connect (2) +will return .B EINPROGRESS -error. +error. The user can then wait for various events via .BR poll (2) or -.BR select (2). +.BR select (2). .TS tab(:) allbox; c s s @@ -130,19 +131,19 @@ l l l. I/O events Event:Poll flag:Occurrence Read:POLLIN:T{ -New data arrived. +New data arrived. T} Read:POLLIN:T{ A connection setup has been completed (for connection-oriented sockets) T} Read:POLLHUP:T{ -A disconnection request has been initiated by the other end. +A disconnection request has been initiated by the other end. T} Read:POLLHUP:T{ -A connection is broken (only for connection-oriented protocols). +A connection is broken (only for connection-oriented protocols). When the socket is written -.B SIGPIPE +.B SIGPIPE is also sent. T} Write:POLLOUT:T{ @@ -160,46 +161,47 @@ T} Read/Write:POLLERR:An asynchronous error occurred. Read/Write:POLLHUP:The other end has shut down one direction. Exception:POLLPRI:T{ -Urgent data arrived. +Urgent data arrived. .B SIGURG is sent then. T} .\" FIXME The following is not true currently: .\" It is no I/O event when the connection -.\" is broken from the local end using +.\" is broken from the local end using .\" .BR shutdown (2) -.\" or +.\" or .\" .BR close (2). .TE .PP -An alternative to +An alternative to .BR poll () and .BR select () is to let the kernel inform the application about events via a .B SIGIO -signal. For that the +signal. +For that the .B FASYNC flag must be set on a socket file descriptor via .BR fcntl (2) -and a valid signal handler for +and a valid signal handler for .B SIGIO -must be installed via -.BR sigaction (2). +must be installed via +.BR sigaction (2). See the .I SIGNALS discussion below. .SH "SOCKET OPTIONS" These socket options can be set by using .BR setsockopt (2) -and read with +and read with .BR getsockopt (2) -with the socket level set to -.B SOL_SOCKET +with the socket level set to +.B SOL_SOCKET for all sockets: -.\" SO_ACCEPTCONN is in POSIX.1-2001, and its origin is explained in +.\" SO_ACCEPTCONN is in POSIX.1-2001, and its origin is explained in .\" W R Stevens, UNPv1 .TP .B SO_ACCEPTCONN @@ -209,69 +211,78 @@ to accept connections with The value 0 indicates that this is not a listening socket, the value 1 indicates that this is a listening socket. Can only be read -with -.BR getsockopt (). +with +.BR getsockopt (). .TP .B SO_BINDTODEVICE Bind this socket to a particular device like \(lqeth0\(rq, -as specified in the passed interface name. If the +as specified in the passed interface name. +If the name is an empty string or the option length is zero, the socket device -binding is removed. The passed option is a variable-length null terminated -interface name string with the maximum size of +binding is removed. +The passed option is a variable-length null terminated +interface name string with the maximum size of .BR IFNAMSIZ . If a socket is bound to an interface, -only packets received from that particular interface are processed by the -socket. Note that this only works for some socket types, particularly +only packets received from that particular interface are processed by the +socket. +Note that this only works for some socket types, particularly .B AF_INET -sockets. It is not supported for packet sockets (use normal +sockets. +It is not supported for packet sockets (use normal .BR bind (8) there). .TP .B SO_BROADCAST -Set or get the broadcast flag. When enabled, datagram sockets -receive packets sent to a broadcast address and they are allowed to send +Set or get the broadcast flag. +When enabled, datagram sockets +receive packets sent to a broadcast address and they are allowed to send packets to a broadcast address. This option has no effect on stream-oriented sockets. .TP .B SO_BSDCOMPAT -Enable BSD bug-to-bug compatibility. +Enable BSD bug-to-bug compatibility. This is used by the UDP protocol module in Linux 2.0 and 2.2. If enabled ICMP errors received for a UDP socket will not be passed -to the user program. +to the user program. In later kernel versions, support for this option has been phased out: Linux 2.4 silently ignores it, and Linux 2.6 generates a kernel warning (printk()) if a program uses this option. -Linux 2.0 also enabled BSD bug-to-bug compatibility +Linux 2.0 also enabled BSD bug-to-bug compatibility options (random header changing, skipping of the broadcast flag) for raw -sockets with this option, but that was removed in Linux 2.2. +sockets with this option, but that was removed in Linux 2.2. .TP -.B SO_DEBUG -Enable socket debugging. Only allowed for processes with the +.B SO_DEBUG +Enable socket debugging. +Only allowed for processes with the .B CAP_NET_ADMIN capability or an effective user ID of 0. .TP .B SO_ERROR -Get and clear the pending socket error. Only valid as a +Get and clear the pending socket error. +Only valid as a .BR getsockopt (). -Expects an integer. +Expects an integer. .TP .B SO_DONTROUTE Don't send via a gateway, only send to directly connected hosts. -The same effect can be achieved by setting the +The same effect can be achieved by setting the .B MSG_DONTROUTE -flag on a socket +flag on a socket .BR send (2) -operation. Expects an integer boolean flag. +operation. +Expects an integer boolean flag. .TP .B SO_KEEPALIVE -Enable sending of keep-alive messages on connection-oriented sockets. -Expects an integer boolean flag. +Enable sending of keep-alive messages on connection-oriented sockets. +Expects an integer boolean flag. .TP .B SO_LINGER -Sets or gets the -.B SO_LINGER -option. The argument is a -.I linger +Sets or gets the +.B SO_LINGER +option. +The argument is a +.I linger structure. .sp .in +0.25i @@ -283,99 +294,101 @@ struct linger { .fi .in -0.25i .IP -When enabled, a +When enabled, a .BR close (2) or .BR shutdown (2) will not return until all queued messages for the socket have been -successfully sent or the linger timeout has been reached. Otherwise, +successfully sent or the linger timeout has been reached. +Otherwise, the call returns immediately and the closing is done in the background. When the socket is closed as part of .BR exit (2), it always lingers in the background. .TP .B SO_OOBINLINE -If this option is enabled, -out-of-band data is directly placed into the receive data stream. -Otherwise out-of-band data is only passed when the -.B MSG_OOB -flag is set during receiving. +If this option is enabled, +out-of-band data is directly placed into the receive data stream. +Otherwise out-of-band data is only passed when the +.B MSG_OOB +flag is set during receiving. .\" don't document it because it can do too much harm. .\".B SO_NO_CHECK .TP .B SO_PASSCRED Enable or disable the receiving of the .B SCM_CREDENTIALS -control message. For more information see -.BR unix (7). +control message. +For more information see +.BR unix (7). .TP .B SO_PEERCRED -Return the credentials of the foreign process connected to this socket. +Return the credentials of the foreign process connected to this socket. This is only possible for connected -.B PF_UNIX +.B PF_UNIX stream sockets and -.B PF_UNIX +.B PF_UNIX stream and datagram socket pairs created using -.BR socketpair (2); -see -.BR unix (7). +.BR socketpair (2); +see +.BR unix (7). The returned credentials are those that were in effect at the time of the call to .BR connect (2) or .BR socketpair (2). Argument is a -.I ucred -structure. -Only valid as a +.I ucred +structure. +Only valid as a .BR getsockopt (). .TP .B SO_PRIORITY -Set the protocol-defined priority for all packets to be sent on +Set the protocol-defined priority for all packets to be sent on this socket. -Linux uses this value to order the networking queues: -packets with a higher priority may be processed first depending -on the selected device queueing discipline. +Linux uses this value to order the networking queues: +packets with a higher priority may be processed first depending +on the selected device queueing discipline. For .BR ip (7), -this also sets the IP type-of-service (TOS) field for outgoing packets. +this also sets the IP type-of-service (TOS) field for outgoing packets. Setting a priority outside the range 0 to 6 requires the .B CAP_NET_ADMIN capability. .TP .B SO_RCVBUF -Sets or gets the maximum socket receive buffer in bytes. -The kernel doubles this value (to allow space for bookkeeping overhead) +Sets or gets the maximum socket receive buffer in bytes. +The kernel doubles this value (to allow space for bookkeeping overhead) when it is set using .\" Most (all?) other implementations do not do this -- MTK, Dec 05 .BR setsockopt (), and this doubled value is returned by .BR getsockopt (). -The default value is set by the -.B rmem_default -sysctl and the maximum allowed value is set by the +The default value is set by the +.B rmem_default +sysctl and the maximum allowed value is set by the .B rmem_max -sysctl. +sysctl. The minimum (doubled) value for this option is 256. .TP .BR SO_RCVBUFFORCE " (since Linux 2.6.14") Using this socket option, a privileged .RB ( CAP_NET_ADMIN ) -process can perform the same task as +process can perform the same task as .BR SO_RCVBUF , -but the +but the .B rmem_max limit can be overridden. .TP .BR SO_RCVLOWAT " and " SO_SNDLOWAT Specify the minimum number of bytes in the buffer until the socket layer -will pass the data to the protocol -.RB ( SO_SNDLOWAT ) -or the user on receiving +will pass the data to the protocol +.RB ( SO_SNDLOWAT ) +or the user on receiving .RB ( SO_RCVLOWAT ). These two values are initialised to 1. .B SO_SNDLOWAT -is not changeable on Linux +is not changeable on Linux .RB ( setsockopt fails with the error .BR ENOPROTOOPT ). @@ -390,7 +403,7 @@ system calls currently do not respect the .B SO_RCVLOWAT setting on Linux, and mark a socket readable when even a single byte of data is available. -A subsequent read from the socket will block until +A subsequent read from the socket will block until .BR SO_RCVLOWAT bytes are available. .\" See http://marc.theaimsgroup.com/?l=linux-kernel&m=111049368106984&w=2 @@ -415,9 +428,10 @@ If the timeout is set to zero (the default) then the operation will never timeout. .TP .B SO_REUSEADDR -Indicates that the rules used in validating addresses supplied in a -.BR bind (2) -call should allow reuse of local addresses. For +Indicates that the rules used in validating addresses supplied in a +.BR bind (2) +call should allow reuse of local addresses. +For .B PF_INET sockets this means that a socket may bind, except when there @@ -427,39 +441,39 @@ When the listening socket is bound to with a specific port then it is not possible to bind to this port for any local address. .TP -.B SO_SNDBUF -Sets or gets the maximum socket send buffer in bytes. -The kernel doubles this value (to allow space for bookkeeping overhead) +.B SO_SNDBUF +Sets or gets the maximum socket send buffer in bytes. +The kernel doubles this value (to allow space for bookkeeping overhead) when it is set using .\" Most (all?) other implementations do not do this -- MTK, Dec 05 .BR setsockopt (), and this doubled value is returned by .BR getsockopt (). -The default value is set by the -.B wmem_default -sysctl and the maximum allowed value is set by the +The default value is set by the +.B wmem_default +sysctl and the maximum allowed value is set by the .B wmem_max -sysctl. +sysctl. The minimum (doubled) value for this option is 2048. .TP .BR SO_SNDBUFFORCE " (since Linux 2.6.14") Using this socket option, a privileged .RB ( CAP_NET_ADMIN ) -process can perform the same task as +process can perform the same task as .BR SO_SNDBUF , -but the +but the .B wmem_max limit can be overridden. .TP .B SO_TIMESTAMP Enable or disable the receiving of the .B SO_TIMESTAMP -control message. +control message. The timestamp control message is sent with level .B SOL_SOCKET -and the -.I cmsg_data -field is a +and the +.I cmsg_data +field is a .I "struct timeval" indicating the reception time of the last packet passed to the user in this call. @@ -468,33 +482,34 @@ See for details on control messages. .TP .B SO_TYPE -Gets the socket type as an integer (like -.BR SOCK_STREAM ). +Gets the socket type as an integer (like +.BR SOCK_STREAM ). Can only be read -with -.BR getsockopt (). +with +.BR getsockopt (). .SH SIGNALS When writing onto a connection-oriented socket that has been shut down -(by the local or the remote end) +(by the local or the remote end) .B SIGPIPE -is sent to the writing process and +is sent to the writing process and .B EPIPE -is returned. +is returned. The signal is not sent when the write call specified the -.B MSG_NOSIGNAL +.B MSG_NOSIGNAL flag. .PP -When requested with the -.B FIOSETOWN +When requested with the +.B FIOSETOWN .BR fcntl () -or -.B SIOCSPGRP +or +.B SIOCSPGRP .BR ioctl (), -.B SIGIO -is sent when an I/O event occurs. It is possible to use +.B SIGIO +is sent when an I/O event occurs. +It is possible to use .BR poll (2) -or +or .BR select (2) in the signal handler to find out which socket the event occurred on. An alternative (in Linux 2.2) is to set a realtime signal using the @@ -503,57 +518,57 @@ An alternative (in Linux 2.2) is to set a realtime signal using the the handler of the real time signal will be called with the file descriptor in the .I si_fd -field of its +field of its .IR siginfo_t . -See +See .BR fcntl (2) for more information. .PP -Under some circumstances (e.g. multiple processes accessing a +Under some circumstances (e.g. multiple processes accessing a single socket), the condition that caused the .B SIGIO may have already disappeared when the process reacts to the signal. -If this happens, the process should wait again because Linux +If this happens, the process should wait again because Linux will resend the signal later. .\" .SH ANCILLARY MESSAGES .SH SYSCTLS -The core socket networking sysctls can be accessed using the -.I /proc/sys/net/core/* -files or with the -.BR sysctl (2) -interface. +The core socket networking sysctls can be accessed using the +.I /proc/sys/net/core/* +files or with the +.BR sysctl (2) +interface. .TP .B rmem_default contains the default setting in bytes of the socket receive buffer. .TP .B rmem_max contains the maximum socket receive buffer size in bytes which a user may -set by using the +set by using the .B SO_RCVBUF -socket option. +socket option. .TP .B wmem_default contains the default setting in bytes of the socket send buffer. .TP .B wmem_max contains the maximum socket send buffer size in bytes which a user may -set by using the +set by using the .B SO_SNDBUF -socket option. +socket option. .TP -.BR message_cost " and " message_burst +.BR message_cost " and " message_burst configure the token bucket filter used to load limit warning messages caused by external network events. .TP -.B netdev_max_backlog +.B netdev_max_backlog Maximum number of packets in the global input queue. .TP .B optmem_max -Maximum length of ancillary data and user control data like the iovecs -per socket. +Maximum length of ancillary data and user control data like the iovecs +per socket. .\" netdev_fastroute is not documented because it is experimental .SH IOCTLS -These operations can be accessed using +These operations can be accessed using .BR ioctl (2): .in +0.25i @@ -563,40 +578,41 @@ These operations can be accessed using .in -0.25i .TP .B SIOCGSTAMP -Return a -.I struct timeval -with the receive timestamp of the last packet passed to the user. -This is useful for accurate round trip time measurements. -See -.BR setitimer (2) -for a description of +Return a +.I struct timeval +with the receive timestamp of the last packet passed to the user. +This is useful for accurate round trip time measurements. +See +.BR setitimer (2) +for a description of .IR "struct timeval" . .\" This ioctl should only be used if the socket option .B SO_TIMESTAMP -is not set on the socket. +is not set on the socket. Otherwise, it returns the timestamp of the last packet that was received while .B SO_TIMESTAMP was not set, or it fails if no such packet has been received, -(i.e., -.BR ioctl () -returns \-1 with -.I errno -set to +(i.e., +.BR ioctl () +returns \-1 with +.I errno +set to .BR ENOENT ). .TP .BR SIOCSPGRP -Set the process or process group to send +Set the process or process group to send .B SIGIO -or +or .B SIGURG -signals +signals to when an asynchronous I/O operation has finished or urgent data is available. -The argument is a pointer to a -.BR pid_t . -If the argument is positive, send the signals to that process. If the +The argument is a pointer to a +.BR pid_t . +If the argument is positive, send the signals to that process. +If the argument is negative, send the signals to the process group with the ID of the absolute value of the argument. The process may only choose itself or its own process group to receive @@ -607,35 +623,35 @@ capability or an effective UID of 0. .B FIOASYNC Change the .B O_ASYNC -flag to enable or disable asynchronous I/O mode of the socket. +flag to enable or disable asynchronous I/O mode of the socket. Asynchronous I/O mode means that the -.B SIGIO -signal or the signal set with +.B SIGIO +signal or the signal set with .B F_SETSIG is raised when a new I/O event occurs. .IP -Argument is an integer boolean flag. +Argument is an integer boolean flag. .\" .TP .BR SIOCGPGRP Get the current process or process group that receives -.B SIGIO -or +.B SIGIO +or .B SIGURG -signals, +signals, or 0 -when none is set. +when none is set. .PP Valid .BR fcntl () operations: .TP -.BR FIOGETOWN -The same as the SIOCGPGRP +.BR FIOGETOWN +The same as the SIOCGPGRP .BR ioctl (). .TP .BR FIOSETOWN -The same as the SIOCSPGRP +The same as the SIOCSPGRP .BR ioctl (). .SH NOTES Linux assumes that half of the send/receive buffer is used for internal @@ -643,33 +659,35 @@ kernel structures; thus the sysctls are twice what can be observed on the wire. Linux will only allow port re-use with the SO_REUSEADDR option -when this option was set both in the previous program that performed a -.BR bind () +when this option was set both in the previous program that performed a +.BR bind () to the port and in the program that wants to re-use the port. This differs from some implementations (e.g., FreeBSD) where only the later program needs to set the SO_REUSEADDR option. Typically this difference is invisible, since, for example, a server program is designed to always set this option. .SH BUGS -The -.B CONFIG_FILTER -socket options -.B SO_ATTACH_FILTER -and -.B SO_DETACH_FILTER -are -not documented. The suggested interface to use them is via the libpcap +The +.B CONFIG_FILTER +socket options +.B SO_ATTACH_FILTER +and +.B SO_DETACH_FILTER +are +not documented. +The suggested interface to use them is via the libpcap library. .SH VERSIONS -.B SO_BINDTODEVICE -was introduced in Linux 2.0.30. -.B SO_PASSCRED +.B SO_BINDTODEVICE +was introduced in Linux 2.0.30. +.B SO_PASSCRED is new in Linux 2.2. The sysctls are new in Linux 2.2. .B SO_RCVTIMEO and .B SO_SNDTIMEO -are supported since Linux 2.3.41. Earlier, timeouts were fixed to +are supported since Linux 2.3.41. +Earlier, timeouts were fixed to a protocol specific setting, and could not be read or written. .\" .SH AUTHORS .\" This man page was written by Andi Kleen. diff --git a/man7/standards.7 b/man7/standards.7 index 1ee8d76ff7..80149e2dda 100644 --- a/man7/standards.7 +++ b/man7/standards.7 @@ -1,5 +1,5 @@ .\" Copyright (c) 2006, Michael Kerrisk <mtk-manpages@gmx.net> -.\" includes some material by other authors that was formerly +.\" includes some material by other authors that was formerly .\" in intro.2. .\" .\" This is free documentation; you can redistribute it and/or @@ -26,7 +26,7 @@ .SH NAME Standards \- C and UNIX Standards .SH DESCRIPTION -The +The .B "CONFORMING TO" section that appears in many manual pages identifies various standards to which the documented interface conforms. @@ -34,10 +34,10 @@ The following list briefly describes these standards. .TP .B V7 Version 7, the ancestral UNIX from Bell Labs. -.TP +.TP .B 4.2BSD This is an implementation standard defined by the 4.2 release -of the +of the .IR "Berkeley Software Distribution", released by the University of California at Berkeley. This was the first Berkeley release that contained a TCP/IP @@ -46,10 +46,10 @@ stack and the sockets API. .sp Earlier major BSD releases included \fI3BSD\fP (1980), \fI4BSD\fP (1980), and \fI4.1BSD\fP (1981). -.TP +.TP .B 4.3BSD The successor to 4.2BSD, released in 1986. -.TP +.TP .B 4.4BSD The successor to 4.3BSD, released in 1993. This was the last major Berkeley release. @@ -57,21 +57,21 @@ This was the last major Berkeley release. .B System V This is an implementation standard defined by AT&T's milestone 1983 release of its commercial System V (five) release. -The previous major AT&T release was +The previous major AT&T release was .IR "System III" , released in 1981. .TP .B System V release 2 (SVr2) This was the next System V release, made in 1985. The SVr2 was formally described in the -.IR "System V Interface Definition version 1" +.IR "System V Interface Definition version 1" .RI ( "SVID 1" ) published in 1985. .TP .B System V release 3 (SVr3) This was the successor to SVr2, released in 1986. This release was formally described in the -.IR "System V Interface Definition version 2" +.IR "System V Interface Definition version 2" .RI ( "SVID 2" ). .TP .B System V release 4 (SVr4) @@ -80,48 +80,48 @@ This version of System V is described in the "Programmer's Reference Manual: Operating System API (Intel processors)" (Prentice-Hall 1992, ISBN 0-13-951294-2) This release was formally described in the -.IR "System V Interface Definition version 3" +.IR "System V Interface Definition version 3" .RI ( "SVID 3" ), and is considered the definitive System V release. .TP .B SVID 4 System V Interface Definition version 4, issued in 1995. Available online at http://www.sco.com/developers/devspecs/ . -.TP -.B C89 -This was the first C language standard, ratified by ANSI -(American National Standards Institute) in 1989 +.TP +.B C89 +This was the first C language standard, ratified by ANSI +(American National Standards Institute) in 1989 .RI ( X3.159-1989 ). -Sometimes this is known as -.IR "ANSI C" , +Sometimes this is known as +.IR "ANSI C" , but since C99 is also an ANSI standard, this term is ambiguous. -This standard was also ratified by -ISO (International Standards Organization) in 1990 +This standard was also ratified by +ISO (International Standards Organization) in 1990 .RI ( "ISO/IEC 9899:1990" ), -and is thus occasionally referred to as +and is thus occasionally referred to as .IR "ISO C90" . .TP .B C99 -This revision of the C language standard was ratified by ISO in 1999 +This revision of the C language standard was ratified by ISO in 1999 .RI ( "ISO/IEC 9899:1999" ). .TP .B POSIX.1-1990 "Portable Operating System Interface for Computing Environments". IEEE 1003.1-1990 part 1, ratified by ISO in 1990 .RI ( "ISO/IEC 9945-1:1990" ). -Further information can be found +Further information can be found in Donald Lewine's "POSIX Programmer's Guide" (O'Reilly & Associates, Inc., 1991, ISBN 0-937175-73-0). The term "POSIX" was coined by Richard Stallman. -.TP +.TP .B POSIX.2 -IEEE Std 1003.2-1992, +IEEE Std 1003.2-1992, describing commands and utilities, ratified by ISO in 1993 .RI ( "ISO/IEC 9945-2:1993" ). .TP .BR POSIX.1b " (formerly known as \fIPOSIX.4\fP)" -IEEE Std 1003.1b-1993 +IEEE Std 1003.1b-1993 describing real-time facilities for portable operating systems, ratified by ISO in 1996 .RI ( "ISO/IEC 9945-1:1996" ). @@ -158,13 +158,13 @@ A revision of the X/Open Portability Guide, released in 1992. A 1994 revision of XPG4. This is also referred to as .IR "Spec 1170" , -where 1170 referred to the number of interfaces +where 1170 referred to the number of interfaces defined by this standard. .TP .B SUS (SUSv1) Single UNIX Specification. This was a repackaging of XPG4v2 and other X/Open standards -(X/Open Curses Issue 4 version 2, +(X/Open Curses Issue 4 version 2, X/Open Networking Service (XNS) Issue 4). Systems conforming to this standard can be branded .IR "UNIX 95" . @@ -180,22 +180,22 @@ See also http://www.UNIX-systems.org/version2/ .) .TP .B POSIX.1-2001, SUSv3 -This was a 2001 revision and consolidation of the -POSIX.1, POSIX.2, and SUS standards into a single document, +This was a 2001 revision and consolidation of the +POSIX.1, POSIX.2, and SUS standards into a single document, conducted under the auspices of the Austin group -(http://www.opengroup.org/austin/ .) -The standard is available online at -http://www.unix-systems.org/version3/ , -and the interfaces that it describes are also available in the Linux +(http://www.opengroup.org/austin/ .) +The standard is available online at +http://www.unix-systems.org/version3/ , +and the interfaces that it describes are also available in the Linux manual pages package under sections 1p and 3p (e.g., "man 3p open"). .sp -The standard defines two levels of conformance: +The standard defines two levels of conformance: .IR "POSIX conformance" , -which is a baseline set of interfaces required of a conforming system; +which is a baseline set of interfaces required of a conforming system; and -.IR "XSI Conformance", +.IR "XSI Conformance", which additionally mandates a set of interfaces -(the "XSI extension") which are only optional for POSIX conformance. +(the "XSI extension") which are only optional for POSIX conformance. XSI-conformant systems can be branded .IR "UNIX 03" . (XSI conformance constitutes the @@ -208,7 +208,7 @@ The POSIX.1-2001 document is broken into four parts: Definitions, terms and concepts, header file specifications. .sp .BR XSH : -Specifications of functions (i.e., system calls and library +Specifications of functions (i.e., system calls and library functions in actual implementations). .sp .BR XCU : @@ -222,11 +222,11 @@ POSIX.1-2001 is aligned with C99, so that all of the library functions standardised in C99 are also standardised in POSIX.1-1001. .sp -Two Technical Corrigenda (minor fixes and improvements) +Two Technical Corrigenda (minor fixes and improvements) of the original 2001 standard have occurred: -TC1 in 2003 (referred to as -.IR POSIX.1-2003 ), -and TC2 in 2004 (referred to as +TC1 in 2003 (referred to as +.IR POSIX.1-2003 ), +and TC2 in 2004 (referred to as .IR POSIX.1-2004 ). .SH "SEE ALSO" .BR feature_test_macros (7) diff --git a/man7/suffixes.7 b/man7/suffixes.7 index 9fd42395bb..d5dbfff206 100644 --- a/man7/suffixes.7 +++ b/man7/suffixes.7 @@ -9,7 +9,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -17,7 +17,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -36,16 +36,17 @@ suffixes \- list of file suffixes .SH DESCRIPTION It is customary to indicate the contents of a file with the file suffix, -which consists of a period, followed by one or more letters. Many -standard utilities, such as compilers, use this to recognize the type of -file they are dealing with. The +which consists of a period, followed by one or more letters. +Many standard utilities, such as compilers, use this to recognize the type of +file they are dealing with. +The .BR make (1) utility is driven by rules based on file suffix. .PP Following is a list of suffixes which are likely to be found on a Linux system. .PP -.TS +.TS l | l _ | _ lI | l . diff --git a/man7/svipc.7 b/man7/svipc.7 index 1aeca8fefb..5f3e80ad62 100644 --- a/man7/svipc.7 +++ b/man7/svipc.7 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,13 +16,13 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" -.\" FIXME There is now duplication of some of the information +.\" FIXME There is now duplication of some of the information .\" below in semctl.2, msgctl.2, and shmctl.2 -- MTK, Nov 04 -.TH SVIPC 7 1993-11-01 "Linux 0.99.13" "Linux Programmer's Manual" +.TH SVIPC 7 1993-11-01 "Linux 0.99.13" "Linux Programmer's Manual" .SH NAME svipc \- System V interprocess communication mechanisms .SH SYNOPSIS @@ -56,15 +56,15 @@ structure, defined by the system header file, includes the following members: .sp .B - uid_t cuid; + uid_t cuid; /* creator user ID */ .br .B - gid_t cgid; + gid_t cgid; /* creator group ID */ .br .B - uid_t uid; + uid_t uid; /* owner user ID */ .br .B diff --git a/man7/tcp.7 b/man7/tcp.7 index 82d5fdf5c2..1adfaba4dc 100644 --- a/man7/tcp.7 +++ b/man7/tcp.7 @@ -7,12 +7,12 @@ .\" 2.4 Updates by Nivedita Singhvi 4/20/02 <nivedita@us.ibm.com>. .\" Modified, 2004-11-11, Michael Kerrisk and Andries Brouwer .\" Updated details of interaction of TCP_CORK and TCP_NODELAY. -.\" +.\" .\" FIXME 2.6.17-rc1 adds the following /proc files, which need to be .\" documented: tcp_mtu_probing, tcp_base_mss, and .\" tcp_workaround_signed_windows .\" -.TH TCP 7 2005-06-15 "Linux Man Page" "Linux Programmer's Manual" +.TH TCP 7 2005-06-15 "Linux Man Page" "Linux Programmer's Manual" .SH NAME tcp \- TCP protocol .SH SYNOPSIS @@ -22,141 +22,153 @@ tcp \- TCP protocol .br .B #include <netinet/tcp.h> .br -.B tcp_socket = socket(PF_INET, SOCK_STREAM, 0); +.B tcp_socket = socket(PF_INET, SOCK_STREAM, 0); .SH DESCRIPTION This is an implementation of the TCP protocol defined in RFC\ 793, RFC\ 1122 and RFC\ 2001 with the NewReno and SACK -extensions. It provides a reliable, stream-oriented, +extensions. +It provides a reliable, stream-oriented, full-duplex connection between two sockets on top of .BR ip (7), for both v4 and v6 versions. TCP guarantees that the data arrives in order and retransmits lost packets. -It generates and checks a per-packet checksum to catch +It generates and checks a per-packet checksum to catch transmission errors. TCP does not preserve record boundaries. A newly created TCP socket has no remote or local address and is not -fully specified. To create an outgoing TCP connection use +fully specified. +To create an outgoing TCP connection use .BR connect (2) to establish a connection to another TCP socket. To receive new incoming connections, first -.BR bind (2) -the socket to a local address and port and then call +.BR bind (2) +the socket to a local address and port and then call .BR listen (2) -to put the socket into the listening state. After that a new -socket for each incoming connection can be accepted +to put the socket into the listening state. +After that a new +socket for each incoming connection can be accepted using .BR accept (2). A socket which has had .BR accept () -or +or .BR connect () successfully called on it is fully specified and may -transmit data. Data cannot be transmitted on listening or +transmit data. +Data cannot be transmitted on listening or not yet connected sockets. Linux supports RFC\ 1323 TCP high performance -extensions. These include Protection Against Wrapped -Sequence Numbers (PAWS), Window Scaling and -Timestamps. Window scaling allows the use -of large (> 64K) TCP windows in order to support links with high -latency or bandwidth. To make use of them, the send and -receive buffer sizes must be increased. +extensions. +These include Protection Against Wrapped +Sequence Numbers (PAWS), Window Scaling and +Timestamps. +Window scaling allows the use +of large (> 64K) TCP windows in order to support links with high +latency or bandwidth. +To make use of them, the send and +receive buffer sizes must be increased. They can be set globally with the .B net.ipv4.tcp_wmem and .B net.ipv4.tcp_rmem -sysctl variables, or on individual sockets by using the -.B SO_SNDBUF -and -.B SO_RCVBUF -socket options with the +sysctl variables, or on individual sockets by using the +.B SO_SNDBUF +and +.B SO_RCVBUF +socket options with the .BR setsockopt (2) call. The maximum sizes for socket buffers declared via the .B SO_SNDBUF -and -.B SO_RCVBUF +and +.B SO_RCVBUF mechanisms are limited by the global .B net.core.rmem_max and .B net.core.wmem_max -sysctls. Note that TCP actually allocates twice the size of +sysctls. +Note that TCP actually allocates twice the size of the buffer requested in the .BR setsockopt (2) -call, and so a succeeding -.BR getsockopt (2) +call, and so a succeeding +.BR getsockopt (2) call will not return the same size of buffer as requested -in the -.BR setsockopt (2) -call. +in the +.BR setsockopt (2) +call. TCP uses the extra space for administrative purposes and internal kernel structures, and the sysctl variables reflect the -larger sizes compared to the actual TCP windows. +larger sizes compared to the actual TCP windows. On individual connections, the socket buffer size must be set prior to the .BR listen () -or +or .BR connect () -calls in order to have it take effect. See +calls in order to have it take effect. +See .BR socket (7) -for more information. -.PP -TCP supports urgent data. Urgent data is used to signal the +for more information. +.PP +TCP supports urgent data. +Urgent data is used to signal the receiver that some important message is part of the data stream and that it should be processed as soon as possible. To send urgent data specify the .B MSG_OOB -option to +option to .BR send (2). When urgent data is received, the kernel sends a .B SIGURG -signal to the process or process group that has been set as the +signal to the process or process group that has been set as the socket "owner" using the .B SIOCSPGRP -or -.B FIOSETOWN +or +.B FIOSETOWN ioctls (or the POSIX.1-2001-specified .BR fcntl (2) .B F_SETOWN operation). -When the +When the .B SO_OOBINLINE socket option is enabled, urgent data is put into the normal data stream (a program can test for its location using the .B SIOCATMARK -ioctl described below), +ioctl described below), otherwise it can be only received when the .B MSG_OOB -flag is set for +flag is set for .BR recv (2) or -.BR recvmsg (2). +.BR recvmsg (2). Linux 2.4 introduced a number of changes for improved throughput and scaling, as well as enhanced functionality. Some of these features include support for zero-copy -.BR sendfile (2), +.BR sendfile (2), Explicit Congestion Notification, new management of TIME_WAIT sockets, keep-alive socket options and support for Duplicate SACK extensions. .SH "ADDRESS FORMATS" -TCP is built on top of IP (see +TCP is built on top of IP (see .BR ip (7)). The address formats defined by .BR ip (7) -apply to TCP. TCP only supports point-to-point +apply to TCP. +TCP only supports point-to-point communication; broadcasting and multicasting are not supported. .SH SYSCTLS -These variables can be accessed by the -.I /proc/sys/net/ipv4/* -files or with the +These variables can be accessed by the +.I /proc/sys/net/ipv4/* +files or with the .BR sysctl (2) -interface. In addition, most IP sysctls also apply to TCP; see -.BR ip (7). +interface. +In addition, most IP sysctls also apply to TCP; see +.BR ip (7). Variables described as .I Boolean take an integer value, with a non-zero value ("true") meaning that @@ -176,11 +188,13 @@ meaning that the option is disabled. Enable resetting connections if the listening service is too slow and unable to keep up and accept them. It means that if overflow occurred due -to a burst, the connection will recover. Enable this option +to a burst, the connection will recover. +Enable this option .I only if you are really sure that the listening daemon -cannot be tuned to accept connections faster. Enabling this -option can harm the clients of your server. +cannot be tuned to accept connections faster. +Enabling this +option can harm the clients of your server. .TP .BR tcp_adv_win_scale " (integer; default: 2)" Count buffering overhead as bytes/2^tcp_adv_win_scale @@ -188,23 +202,27 @@ Count buffering overhead as bytes/2^tcp_adv_win_scale if it is <= 0. The socket receive buffer space is shared between the -application and kernel. TCP maintains part of the buffer as +application and kernel. +TCP maintains part of the buffer as the TCP window, this is the size of the receive window -advertised to the other end. The rest of the space is used +advertised to the other end. +The rest of the space is used as the "application" buffer, used to isolate the network -from scheduling and application latencies. The -.BR tcp_adv_win_scale +from scheduling and application latencies. +The +.BR tcp_adv_win_scale default value of 2 implies that the space used for the application buffer is one fourth that of the -total. -.TP +total. +.TP .BR tcp_app_win " (integer; default: 31)" This variable defines how many bytes of the TCP window are reserved for buffering overhead. A maximum of (window/2^tcp_app_win, mss) bytes in the window -are reserved for the application buffer. A value of 0 +are reserved for the application buffer. +A value of 0 implies that no amount is reserved. .\" .\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt @@ -213,29 +231,34 @@ implies that no amount is reserved. Enable BIC TCP congestion control algorithm. BIC-TCP is a sender-side only change that ensures a linear RTT fairness under large windows while offering both scalability and -bounded TCP-friendliness. The protocol combines two schemes -called additive increase and binary search increase. When the +bounded TCP-friendliness. +The protocol combines two schemes +called additive increase and binary search increase. +When the congestion window is large, additive increase with a large increment ensures linear RTT fairness as well as good -scalability. Under small congestion windows, binary search +scalability. +Under small congestion windows, binary search increase provides TCP friendliness. .\" .\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt .TP .BR tcp_bic_low_window " (integer; default: 14)" Sets the threshold window (in packets) where BIC TCP starts to -adjust the congestion window. Below this threshold BIC TCP behaves +adjust the congestion window. +Below this threshold BIC TCP behaves the same as the default TCP Reno. .\" .\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt .TP .BR tcp_bic_fast_convergence " (Boolean; default: enabled)" Forces BIC TCP to more quickly respond to changes in congestion -window. Allows two flows sharing the same connection to converge +window. +Allows two flows sharing the same connection to converge more rapidly. .TP .BR tcp_dsack " (Boolean; default: enabled)" -Enable RFC\ 2883 TCP Duplicate SACK support. +Enable RFC\ 2883 TCP Duplicate SACK support. .TP .BR tcp_ecn " (Boolean; default: disabled)" Enable RFC\ 2884 Explicit Congestion Notification. @@ -248,16 +271,18 @@ Enable TCP Forward Acknowledgement support. .TP .BR tcp_fin_timeout " (integer; default: 60)" This specifies how many seconds to wait for a final FIN packet before the -socket is forcibly closed. This is strictly a violation of +socket is forcibly closed. +This is strictly a violation of the TCP specification, but required to prevent -denial-of-service attacks. +denial-of-service attacks. In Linux 2.2, the default value was 180. .\" .\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt .TP .BR tcp_frto " (Boolean; default: disabled)" Enables F-RTO, an enhanced recovery algorithm for TCP retransmission -timeouts. It is particularly beneficial in wireless environments +timeouts. +It is particularly beneficial in wireless environments where packet loss is typically due to random radio interference rather than intermediate router congestion. .TP @@ -265,21 +290,22 @@ rather than intermediate router congestion. The number of seconds between TCP keep-alive probes. .TP .BR tcp_keepalive_probes " (integer; default: 9)" -The maximum number of TCP keep-alive probes to send +The maximum number of TCP keep-alive probes to send before giving up and killing the connection if no response is obtained from the other end. .TP .BR tcp_keepalive_time " (integer; default: 7200)" The number of seconds a connection needs to be idle -before TCP begins sending out keep-alive probes. -Keep-alives are only sent when the -.B SO_KEEPALIVE -socket option is enabled. The default value is 7200 seconds -(2 hours). An idle connection is terminated after +before TCP begins sending out keep-alive probes. +Keep-alives are only sent when the +.B SO_KEEPALIVE +socket option is enabled. +The default value is 7200 seconds (2 hours). +An idle connection is terminated after approximately an additional 11 minutes (9 probes an interval of 75 seconds apart) when keep-alive is enabled. -Note that underlying connection tracking mechanisms and +Note that underlying connection tracking mechanisms and application timeouts may be much shorter. .\" .\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt @@ -293,24 +319,29 @@ changed would be a Beowulf compute cluster. .TP .BR tcp_max_orphans " (integer; default: see below)" The maximum number of orphaned (not attached to any user file -handle) TCP sockets allowed in the system. When this number +handle) TCP sockets allowed in the system. +When this number is exceeded, the orphaned connection is reset and a warning -is printed. This limit exists only to prevent simple denial-of-service -attacks. Lowering this limit is not recommended. Network -conditions might require you to increase the number of +is printed. +This limit exists only to prevent simple denial-of-service attacks. +Lowering this limit is not recommended. +Network conditions might require you to increase the number of orphans allowed, but note that each orphan can eat up to ~64K -of unswappable memory. The default initial value is set -equal to the kernel parameter NR_FILE. This initial default -is adjusted depending on the memory in the system. +of unswappable memory. +The default initial value is set +equal to the kernel parameter NR_FILE. +This initial default is adjusted depending on the memory in the system. .TP .BR tcp_max_syn_backlog " (integer; default: see below)" The maximum number of queued connection requests which have -still not received an acknowledgement from the connecting -client. If this number is exceeded, the kernel will begin -dropping requests. The default value of 256 is increased to +still not received an acknowledgement from the connecting client. +If this number is exceeded, the kernel will begin +dropping requests. +The default value of 256 is increased to 1024 when the memory present in the system is adequate or greater (>= 128Mb), and reduced to 128 for those systems with -very low memory (<= 32Mb). It is recommended that if this +very low memory (<= 32Mb). +It is recommended that if this needs to be increased above 1024, TCP_SYNQ_HSIZE in include/net/tcp.h be modified to keep TCP_SYNQ_HSIZE*16<=tcp_max_syn_backlog, and the kernel be @@ -318,38 +349,43 @@ recompiled. .TP .BR tcp_max_tw_buckets " (integer; default: see below)" The maximum number of sockets in TIME_WAIT state allowed in -the system. This limit exists only to prevent simple denial-of-service -attacks. The default value of NR_FILE*2 is adjusted -depending on the memory in the system. If this number is +the system. +This limit exists only to prevent simple denial-of-service +attacks. +The default value of NR_FILE*2 is adjusted +depending on the memory in the system. +If this number is exceeded, the socket is closed and a warning is printed. -.TP +.TP .BR tcp_mem -This is a vector of 3 integers: [low, pressure, high]. These -bounds are used by TCP to track its memory usage. The +This is a vector of 3 integers: [low, pressure, high]. +These bounds are used by TCP to track its memory usage. +The defaults are calculated at boot time from the amount of available memory. -(TCP can only use +(TCP can only use .I "low memory" for this, which is limited to around 900 megabytes on 32-bit systems. 64-bit systems do not suffer this limitation.) -.I low +.I low - TCP doesn't regulate its memory allocation when the number of pages it has allocated globally is below this number. .I pressure - when the amount of memory allocated by TCP -exceeds this number of pages, TCP moderates its memory -consumption. This memory pressure state is exited +exceeds this number of pages, TCP moderates its memory consumption. +This memory pressure state is exited once the number of pages allocated falls below -the -.I low +the +.I low mark. .I high - the maximum number of pages, globally, that TCP -will allocate. This value overrides any other limits -imposed by the kernel. +will allocate. +This value overrides any other limits +imposed by the kernel. .TP .BR tcp_orphan_retries " (integer; default: 8)" The maximum number of attempts made to probe the other @@ -364,68 +400,78 @@ minimize unnecessary back off and retransmits provoked by reordering of packets on a connection. .TP .BR tcp_retrans_collapse " (Boolean; default: enabled)" -Try to send full-sized packets during retransmit. +Try to send full-sized packets during retransmit. .TP .BR tcp_retries1 " (integer; default: 3)" The number of times TCP will attempt to retransmit a packet on an established connection normally, without the extra effort of getting the network -layers involved. Once we exceed this number of +layers involved. +Once we exceed this number of retransmits, we first have the network layer update the route if possible before each new retransmit. The default is the RFC specified minimum of 3. .TP .BR tcp_retries2 " (integer; default: 15)" The maximum number of times a TCP packet is retransmitted -in established state before giving up. The default +in established state before giving up. +The default value is 15, which corresponds to a duration of approximately between 13 to 30 minutes, depending -on the retransmission timeout. The RFC\ 1122 specified +on the retransmission timeout. +The RFC\ 1122 specified minimum limit of 100 seconds is typically deemed too short. .TP .BR tcp_rfc1337 " (Boolean; default: disabled)" Enable TCP behaviour conformant with RFC\ 1337. When disabled, -if a RST is received in TIME_WAIT state, we close +if a RST is received in TIME_WAIT state, we close the socket immediately without waiting for the end -of the TIME_WAIT period. +of the TIME_WAIT period. .TP -.BR tcp_rmem +.BR tcp_rmem This is a vector of 3 integers: [min, default, -max]. These parameters are used by TCP to regulate receive -buffer sizes. TCP dynamically adjusts the size of the +max]. +These parameters are used by TCP to regulate receive +buffer sizes. +TCP dynamically adjusts the size of the receive buffer from the defaults listed below, in the range of these sysctl variables, depending on memory available in the system. .I min -- minimum size of the receive buffer used by each TCP -socket. The default value is 4K, and is lowered to -PAGE_SIZE bytes in low-memory systems. This value +- minimum size of the receive buffer used by each TCP socket. +The default value is 4K, and is lowered to +PAGE_SIZE bytes in low-memory systems. +This value is used to ensure that in memory pressure mode, -allocations below this size will still succeed. This is not +allocations below this size will still succeed. +This is not used to bound the size of the receive buffer declared using .B SO_RCVBUF -on a socket. +on a socket. .I default - the default size of the receive buffer for a TCP socket. This value overwrites the initial default buffer size from -the generic global +the generic global .B net.core.rmem_default -defined for all protocols. The default value is 87380 -bytes, and is lowered to 43689 in low-memory systems. If -larger receive buffer sizes are desired, this value should -be increased (to affect all sockets). To employ large TCP +defined for all protocols. +The default value is 87380 +bytes, and is lowered to 43689 in low-memory systems. +If larger receive buffer sizes are desired, this value should +be increased (to affect all sockets). +To employ large TCP windows, the -.B net.ipv4.tcp_window_scaling +.B net.ipv4.tcp_window_scaling must be enabled (default). .I max - the maximum size of the receive buffer used by -each TCP socket. This value does not override the global +each TCP socket. +This value does not override the global .BR net.core.rmem_max . This is not used to limit the size of the receive buffer declared using @@ -435,7 +481,7 @@ The default value of 87380*2 bytes is lowered to 87380 in low-memory systems. .TP .BR tcp_sack " (Boolean; default: enabled)" -Enable RFC\ 2018 TCP Selective Acknowledgements. +Enable RFC\ 2018 TCP Selective Acknowledgements. .TP .BR tcp_stdurg " (Boolean; default: disabled)" If this option is enabled, then use the RFC\ 1122 interpretation @@ -445,7 +491,7 @@ of the TCP urgent-pointer field. .\" resolution of this ambiguity (unfortunately the "wrong" one). According to this interpretation, the urgent pointer points to the last byte of urgent data. -If this option is disabled, then use the BSD-compatible interpretation of +If this option is disabled, then use the BSD-compatible interpretation of the urgent pointer: the urgent pointer points to the first byte after the urgent data. Enabling this option may lead to interoperability problems. @@ -456,17 +502,23 @@ for a passive TCP connection will be retransmitted. This number should not be higher than 255. .TP .BR tcp_syncookies " (Boolean)" -Enable TCP syncookies. The kernel must be compiled with +Enable TCP syncookies. +The kernel must be compiled with .BR CONFIG_SYN_COOKIES . Send out syncookies when the syn backlog queue of a socket -overflows. The syncookies feature attempts to protect a -socket from a SYN flood attack. This should be used as a -last resort, if at all. This is a violation of the TCP +overflows. +The syncookies feature attempts to protect a +socket from a SYN flood attack. +This should be used as a +last resort, if at all. +This is a violation of the TCP protocol, and conflicts with other areas of TCP such as TCP -extensions. It can cause problems for clients and relays. +extensions. +It can cause problems for clients and relays. It is not recommended as a tuning mechanism for heavily loaded servers to help with overloaded or misconfigured -conditions. For recommended alternatives see +conditions. +For recommended alternatives see .BR tcp_max_syn_backlog , .BR tcp_synack_retries , and @@ -474,8 +526,10 @@ and .TP .BR tcp_syn_retries " (integer; default: 5)" The maximum number of times initial SYNs for an active TCP -connection attempt will be retransmitted. This value should -not be higher than 255. The default value is 5, which +connection attempt will be retransmitted. +This value should +not be higher than 255. +The default value is 5, which corresponds to approximately 180 seconds. .TP .BR tcp_timestamps " (Boolean; default: enabled)" @@ -485,7 +539,7 @@ Enable RFC\ 1323 TCP timestamps. Enable fast recycling of TIME-WAIT sockets. Enabling this option is not recommended since this causes problems when working -with NAT (Network Address Translation). +with NAT (Network Address Translation). .\" .\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt .TP @@ -500,11 +554,13 @@ Enable RFC\ 1323 TCP window scaling. This feature allows the use of a large window (> 64K) on a TCP connection, should the other end support it. Normally, the 16 bit window length field in the TCP header -limits the window size to less than 64K bytes. If larger +limits the window size to less than 64K bytes. +If larger windows are desired, applications can increase the size of their socket buffers and the window scaling option will be -employed. If -.BR tcp_window_scaling +employed. +If +.BR tcp_window_scaling is disabled, TCP will not negotiate the use of window scaling with the other end during connection setup. .\" @@ -513,9 +569,11 @@ scaling with the other end during connection setup. .BR tcp_vegas_cong_avoid " (Boolean; default: disabled)" Enable TCP Vegas congestion avoidance algorithm. TCP Vegas is a sender-side only change to TCP that anticipates -the onset of congestion by estimating the bandwidth. TCP Vegas +the onset of congestion by estimating the bandwidth. +TCP Vegas adjusts the sending rate by modifying the congestion -window. TCP Vegas should provide less packet loss, but it is +window. +TCP Vegas should provide less packet loss, but it is not as aggressive as TCP Reno. .\" .\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt @@ -524,17 +582,19 @@ not as aggressive as TCP Reno. Enable TCP Westwood+ congestion control algorithm. TCP Westwood+ is a sender-side only modification of the TCP Reno protocol stack that optimizes the performance of TCP congestion -control. It is based on end-to-end bandwidth estimation to set +control. +It is based on end-to-end bandwidth estimation to set congestion window and slow start threshold after a congestion -episode. Using this estimation, TCP Westwood+ adaptively sets a +episode. +Using this estimation, TCP Westwood+ adaptively sets a slow start threshold and a congestion window which takes into account the bandwidth used at the time congestion is experienced. TCP Westwood+ significantly increases fairness with respect to TCP Reno in wired networks and throughput over wireless links. .TP .BR tcp_wmem -This is a vector of 3 integers: [min, default, max]. These -parameters are used by TCP to regulate send buffer sizes. +This is a vector of 3 integers: [min, default, max]. +These parameters are used by TCP to regulate send buffer sizes. TCP dynamically adjusts the size of the send buffer from the default values listed below, in the range of these sysctl variables, depending on memory available. @@ -543,7 +603,8 @@ variables, depending on memory available. - minimum size of the send buffer used by each TCP socket. The default value is 4K bytes. This value is used to ensure that in memory pressure mode, -allocations below this size will still succeed. This is not +allocations below this size will still succeed. +This is not used to bound the size of the send buffer declared using .B SO_SNDBUF @@ -554,46 +615,50 @@ on a socket. This value overwrites the initial default buffer size from the generic global .B net.core.wmem_default -defined for all protocols. The default value is 16K bytes. +defined for all protocols. +The default value is 16K bytes. If larger send buffer sizes are desired, this value -should be increased (to affect all sockets). To employ -large TCP windows, the sysctl variable +should be increased (to affect all sockets). +To employ large TCP windows, the sysctl variable .B net.ipv4.tcp_window_scaling must be enabled (default). .I max - the maximum size of the send buffer used by -each TCP socket. This value does not override the global +each TCP socket. +This value does not override the global .BR net.core.wmem_max . This is not used to limit the size of the send buffer declared using .B SO_SNDBUF on a socket. -The default value is 128K bytes. It is lowered to 64K +The default value is 128K bytes. +It is lowered to 64K depending on the memory available in the system. .SH "SOCKET OPTIONS" To set or get a TCP socket option, call .BR getsockopt (2) to read or .BR setsockopt (2) -to write the option with the option level argument set to +to write the option with the option level argument set to .BR IPPROTO_TCP . .\" or SOL_TCP on Linux In addition, -most -.B IPPROTO_IP -socket options are valid on TCP sockets. For more -information see +most +.B IPPROTO_IP +socket options are valid on TCP sockets. +For more information see .BR ip (7). .\" FIXME Document TCP_CONGESTION (new in 2.6.13) .TP .B TCP_CORK -If set, don't send out partial frames. All queued +If set, don't send out partial frames. +All queued partial frames are sent when the option is cleared again. This is useful for prepending headers before calling .BR sendfile (2), or for throughput optimization. -As currently implemented, there is a 200 millisecond ceiling on the time +As currently implemented, there is a 200 millisecond ceiling on the time for which output is corked by .BR TCP_CORK . If this ceiling is reached, then queued data is automatically transmitted. @@ -606,27 +671,30 @@ portable. .TP .B TCP_DEFER_ACCEPT Allows a listener to be awakened only when data arrives on -the socket. Takes an integer value (seconds), this can +the socket. +Takes an integer value (seconds), this can bound the maximum number of attempts TCP will make to -complete the connection. This option should not be used in +complete the connection. +This option should not be used in code intended to be portable. .TP .B TCP_INFO -Used to collect information about this socket. The kernel -returns a \fIstruct tcp_info\fP as defined in the file -/usr/include/linux/tcp.h. This option should not be used in -code intended to be portable. +Used to collect information about this socket. +The kernel returns a \fIstruct tcp_info\fP as defined in the file +/usr/include/linux/tcp.h. +This option should not be used in code intended to be portable. .TP .B TCP_KEEPCNT The maximum number of keepalive probes TCP should send -before dropping the connection. This option should not be +before dropping the connection. +This option should not be used in code intended to be portable. .TP .B TCP_KEEPIDLE The time (in seconds) the connection needs to remain idle before TCP starts sending keepalive probes, if the socket -option SO_KEEPALIVE has been set on this socket. This -option should not be used in code intended to be portable. +option SO_KEEPALIVE has been set on this socket. +This option should not be used in code intended to be portable. .TP .B TCP_KEEPINTVL The time (in seconds) between individual keepalive probes. @@ -634,33 +702,37 @@ This option should not be used in code intended to be portable. .TP .B TCP_LINGER2 -The lifetime of orphaned FIN_WAIT2 state sockets. This -option can be used to override the system wide sysctl +The lifetime of orphaned FIN_WAIT2 state sockets. +This option can be used to override the system wide sysctl .B tcp_fin_timeout -on this socket. This is not to be confused with the +on this socket. +This is not to be confused with the .BR socket (7) -level option +level option .BR SO_LINGER . This option should not be used in code intended to be portable. .TP .B TCP_MAXSEG -The maximum segment size for outgoing TCP packets. If this -option is set before connection establishment, it also +The maximum segment size for outgoing TCP packets. +If this option is set before connection establishment, it also changes the MSS value announced to the other end in the -initial packet. Values greater than the (eventual) -interface MTU have no effect. TCP will also impose +initial packet. +Values greater than the (eventual) interface MTU have no effect. +TCP will also impose its minimum and maximum bounds over the value provided. .TP .B TCP_NODELAY -If set, disable the Nagle algorithm. This means that segments +If set, disable the Nagle algorithm. +This means that segments are always sent as soon as possible, even if there is only a -small amount of data. When not set, data is buffered until there +small amount of data. +When not set, data is buffered until there is a sufficient amount to send out, thereby avoiding the frequent sending of small packets, which results in poor utilization of the network. This option is overridden by -.BR TCP_CORK ; +.BR TCP_CORK ; however, setting this option forces an explicit flush of pending output, even if .B TCP_CORK @@ -668,9 +740,11 @@ is currently set. .TP .B TCP_QUICKACK Enable quickack mode if set or disable quickack -mode if cleared. In quickack mode, acks are sent +mode if cleared. +In quickack mode, acks are sent immediately, rather than delayed if needed in accordance -to normal TCP operation. This flag is not permanent, +to normal TCP operation. +This flag is not permanent, it only enables a switch to or from quickack mode. Subsequent operation of the TCP protocol will once again enter/leave quickack mode depending on @@ -681,13 +755,14 @@ portable. .TP .B TCP_SYNCNT Set the number of SYN retransmits that TCP should send before -aborting the attempt to connect. It cannot exceed 255. +aborting the attempt to connect. +It cannot exceed 255. This option should not be used in code intended to be portable. .TP .B TCP_WINDOW_CLAMP -Bound the size of the advertised window to this value. The -kernel imposes a minimum size of SOCK_MIN_RCVBUF/2. +Bound the size of the advertised window to this value. +The kernel imposes a minimum size of SOCK_MIN_RCVBUF/2. This option should not be used in code intended to be portable. .SH IOCTLS @@ -713,19 +788,19 @@ The socket must not be in LISTEN state, otherwise an error (EINVAL) is returned. .TP .B SIOCATMARK -Returns true (i.e., +Returns true (i.e., .I value is non-zero) if the inbound data stream is at the urgent mark. .sp -If the -.BR SO_OOBINLINE -socket option is set, and +If the +.BR SO_OOBINLINE +socket option is set, and .B SIOCATMARK returns true, then the next read from the socket will return the urgent data. -If the -.BR SO_OOBINLINE -socket option is not set, and +If the +.BR SO_OOBINLINE +socket option is not set, and .B SIOCATMARK returns true, then the next read from the socket will return the bytes following @@ -741,7 +816,7 @@ If an application is informed of the presence of urgent data via argument) or through delivery of a .B SIGURG signal, -then it can advance up to the mark using a loop which repeatedly tests +then it can advance up to the mark using a loop which repeatedly tests .B SIOCATMARK and performs a read (requesting any number of bytes) as long as .B SIOCATMARK @@ -752,32 +827,36 @@ Returns the amount of unsent data in the socket send queue. The socket must not be in LISTEN state, otherwise an error (EINVAL) is returned. .SH "ERROR HANDLING" -When a network error occurs, TCP tries to resend the -packet. If it doesn't succeed after some time, either -.B ETIMEDOUT +When a network error occurs, TCP tries to resend the packet. +If it doesn't succeed after some time, either +.B ETIMEDOUT or the last received error on this connection is reported. .PP Some applications require a quicker error notification. This can be enabled with the -.B IPPROTO_IP -level -.B IP_RECVERR -socket option. When this option is enabled, all incoming -errors are immediately passed to the user program. Use this +.B IPPROTO_IP +level +.B IP_RECVERR +socket option. +When this option is enabled, all incoming +errors are immediately passed to the user program. +Use this option with care \(em it makes TCP less tolerant to routing changes and other normal network conditions. .SH NOTES -TCP has no real out-of-band data; it has urgent data. In -Linux this means if the other end sends newer out-of-band +TCP has no real out-of-band data; it has urgent data. +In Linux this means if the other end sends newer out-of-band data the older urgent data is inserted as normal data into the stream (even when .B SO_OOBINLINE -is not set). This differs from BSD-based stacks. +is not set). +This differs from BSD-based stacks. .PP Linux uses the BSD compatible interpretation of the urgent -pointer field by default. This violates RFC\ 1122, but is -required for interoperability with other stacks. It can be -changed by the +pointer field by default. +This violates RFC\ 1122, but is +required for interoperability with other stacks. +It can be changed by the .B tcp_stdurg sysctl. .SH ERRORS @@ -792,34 +871,34 @@ some time. .TP .B EAFNOTSUPPORT Passed socket address type in -.I sin_family -was not +.I sin_family +was not .BR AF_INET . .PP Any errors defined for .BR ip (7) or the generic socket layer may also be returned for TCP. .SH BUGS -Not all errors are documented. +Not all errors are documented. .br IPv6 is not described. .\" Only a single Linux kernel version is described .\" Info for 2.2 was lost. Should be added again, .\" or put into a separate page. .SH VERSIONS -Support for Explicit Congestion Notification, zero-copy -.BR sendfile (), +Support for Explicit Congestion Notification, zero-copy +.BR sendfile (), reordering support and some SACK extensions (DSACK) were introduced in 2.4. -Support for forward acknowledgement (FACK), TIME_WAIT recycling, +Support for forward acknowledgement (FACK), TIME_WAIT recycling, per connection keepalive socket options and sysctls were introduced in 2.3. -The default values and descriptions for the sysctl variables +The default values and descriptions for the sysctl variables given above are applicable for the 2.4 kernel. .SH AUTHORS -This man page was originally written by Andi Kleen. -It was updated for 2.4 by Nivedita Singhvi with input from +This man page was originally written by Andi Kleen. +It was updated for 2.4 by Nivedita Singhvi with input from Alexey Kuznetsov's Documentation/networking/ip-sysctls.txt document. .SH "SEE ALSO" @@ -838,7 +917,7 @@ document. .sp RFC\ 793 for the TCP specification. .br -RFC\ 1122 for the TCP requirements and a description +RFC\ 1122 for the TCP requirements and a description of the Nagle algorithm. .br RFC\ 1323 for TCP timestamp and window scaling options. diff --git a/man7/termio.7 b/man7/termio.7 index 42dfcfe704..42def74f09 100644 --- a/man7/termio.7 +++ b/man7/termio.7 @@ -25,7 +25,7 @@ termio \- the System V terminal driver interface .SH DESCRIPTION .B termio is the name of the old System V terminal driver interface. -This interface defined a +This interface defined a .I termio structure used to store terminal settings, and a range of .BR ioctl (2) @@ -36,7 +36,7 @@ The interface is now obsolete: POSIX.1-1990 standardized a modified version of this interface, under the name .BR termios . -The POSIX.1 data structure differs slightly from the +The POSIX.1 data structure differs slightly from the System V version, and POSIX.1 defined a suite of functions to replace the various .BR ioctl () diff --git a/man7/time.7 b/man7/time.7 index 38e671a8a7..68a5e287ff 100644 --- a/man7/time.7 +++ b/man7/time.7 @@ -24,14 +24,14 @@ time \- overview of time .SS "Real time and process time" .I "Real time" is defined as time measured from some fixed point, -either from a standard point in the past +either from a standard point in the past (see the description of the Epoch and calendar time below), or from some point (e.g., the start) in the life of a process .RI ( "elapsed time" ). .I "Process time" is defined as the amount of CPU time used by a process. -This is sometimes divided into +This is sometimes divided into .I user and .I system @@ -41,7 +41,7 @@ System CPU time is the time spent by the kernel executing in system mode on behalf of the process (e.g., executing system calls). The .BR time (1) -command can be used to determine the amount of CPU time consumed +command can be used to determine the amount of CPU time consumed during the execution of a program. A program can determine the amount of CPU time it has consumed using .BR times (2), @@ -56,10 +56,10 @@ For further details, see and .BR hwclock (8). .SS "The Software Clock, HZ, and Jiffies" -The accuracy of many system calls and timestamps is limited by +The accuracy of many system calls and timestamps is limited by the resolution of the .IR "software clock" , -a clock maintained by the kernel which measures time in +a clock maintained by the kernel which measures time in .IR jiffies . The size of a jiffy is determined by the value of the kernel constant .IR HZ . @@ -67,52 +67,52 @@ The value of .I HZ varies across kernel versions and hardware platforms. On x86 the situation is as follows: -on kernels up to and including 2.4.x, HZ was 100, +on kernels up to and including 2.4.x, HZ was 100, giving a jiffy value of 0.01 seconds; starting with 2.6.0, HZ was raised to 1000, giving a jiffy of 0.001 seconds; since kernel 2.6.13, the HZ value is a kernel configuration parameter and can be 100, 250 (the default) or 1000, yielding a jiffies value of, respectively, 0.01, 0.004, or 0.001 seconds. -Since kernel 2.6.20, a further frequency is available: -300, a number that divides evenly for the common video +Since kernel 2.6.20, a further frequency is available: +300, a number that divides evenly for the common video frame rates (PAL, 25 HZ; NTSC, 30 HZ). .SS "The Epoch" Unix systems represent time in seconds since the .IR Epoch , which is defined as 0:00:00 UTC on the morning of 1 January 1970. -A program can determine the +A program can determine the .IR "calendar time" -using +using .BR gettimeofday (2), which returns time (in seconds and microseconds) that have -elapsed since the Epoch; +elapsed since the Epoch; .BR time (2) -provides similar information, but only with accuracy to the +provides similar information, but only with accuracy to the nearest second. The system time can be changed using .BR settimeofday (2). .SS "Broken-down time" Certain library functions use a structure of -type +type .I tm -to represent +to represent .IR "broken-down time" , -which stores time value separated out into distinct components +which stores time value separated out into distinct components (year, month, day, hour, minute, second, etc.). This structure is described in .BR ctime (3), -which also describes functions that convert between calendar time and +which also describes functions that convert between calendar time and broken-down time. -Functions for converting between broken-down time and printable +Functions for converting between broken-down time and printable string representations of the time are described in .BR ctime (3), .BR strftime (3), and .BR strptime (3). .SS "Sleeping and Setting Timers" -Various system calls and functions allow a program to sleep -(suspend execution) for a specified period of time; see +Various system calls and functions allow a program to sleep +(suspend execution) for a specified period of time; see .BR nanosleep (2) and .BR sleep (3). diff --git a/man7/udp.7 b/man7/udp.7 index 0830b57c0a..a436b57e79 100644 --- a/man7/udp.7 +++ b/man7/udp.7 @@ -5,7 +5,7 @@ .\" of the modification is added to the header. .\" $Id: udp.7,v 1.7 2000/01/22 01:55:05 freitag Exp $ .\" -.TH UDP 7 1998-10-02 "Linux Man Page" "Linux Programmer's Manual" +.TH UDP 7 1998-10-02 "Linux Man Page" "Linux Programmer's Manual" .SH NAME udp \- User Datagram Protocol for IPv4 .SH SYNOPSIS @@ -13,29 +13,30 @@ udp \- User Datagram Protocol for IPv4 .br .B #include <netinet/in.h> .br -.B udp_socket = socket(PF_INET, SOCK_DGRAM, 0); +.B udp_socket = socket(PF_INET, SOCK_DGRAM, 0); .SH DESCRIPTION -This is an implementation of the User Datagram Protocol -described in RFC\ 768. +This is an implementation of the User Datagram Protocol +described in RFC\ 768. It implements a connectionless, unreliable datagram packet service. -Packets may be reordered or duplicated before they arrive. UDP -generates and checks checksums to catch transmission errors. +Packets may be reordered or duplicated before they arrive. +UDP generates and checks checksums to catch transmission errors. -When a UDP socket is created, +When a UDP socket is created, its local and remote addresses are unspecified. -Datagrams can be sent immediately using +Datagrams can be sent immediately using .BR sendto (2) or .BR sendmsg (2) -with a valid destination address as an argument. When -.BR connect (2) -is called on the socket the default destination address is set and -datagrams can now be sent using +with a valid destination address as an argument. +When +.BR connect (2) +is called on the socket the default destination address is set and +datagrams can now be sent using .BR send (2) -or +or .BR write (2) without specifying an destination address. -It is still possible to send to other destinations by passing an +It is still possible to send to other destinations by passing an address to .BR sendto (2) or @@ -49,77 +50,79 @@ a free local port out of the range defined by and bind the socket to .IR INADDR_ANY . -All receive operations return only one packet. -When the packet is smaller than the passed buffer only that much +All receive operations return only one packet. +When the packet is smaller than the passed buffer only that much data is returned, when it is bigger the packet is truncated and the .B MSG_TRUNC flag is set. .I MSG_WAITALL is not supported. -IP options may be sent or received using the socket options described in +IP options may be sent or received using the socket options described in .BR ip (7). They are only processed by the kernel when the appropriate sysctl -is enabled (but still passed to the user even when it is turned off). +is enabled (but still passed to the user even when it is turned off). See .BR ip (7). -When the +When the .B MSG_DONTROUTE -flag is set on sending the destination address must refer to an local -interface address and the packet is only sent to that interface. +flag is set on sending the destination address must refer to an local +interface address and the packet is only sent to that interface. -By default Linux UDP does path MTU (Maximum Transmission Unit) discovery. +By default Linux UDP does path MTU (Maximum Transmission Unit) discovery. This means the kernel will keep track of the MTU to a specific target IP address and return .I EMSGSIZE -when a UDP packet write exceeds it. -When this happens the application should decrease the packet size. +when a UDP packet write exceeds it. +When this happens the application should decrease the packet size. Path MTU discovery can be also turned off using the .B IP_MTU_DISCOVER -socket option or the +socket option or the .B ip_no_pmtu_disc -sysctl, see -.BR ip(7) -for details. +sysctl, see +.BR ip(7) +for details. When turned off UDP will fragment outgoing UDP packets -that exceed the interface MTU. +that exceed the interface MTU. However disabling it is not recommended for performance and reliability reasons. .SH "ADDRESS FORMAT" -UDP uses the IPv4 -.B sockaddr_in -address format described in -.BR ip (7). +UDP uses the IPv4 +.B sockaddr_in +address format described in +.BR ip (7). .SH "ERROR HANDLING" -All fatal errors will be passed to the user as an error return even -when the socket is not connected. This includes asynchronous errors -received from the network. You may get an error for an earlier packet +All fatal errors will be passed to the user as an error return even +when the socket is not connected. +This includes asynchronous errors +received from the network. +You may get an error for an earlier packet that was sent on the same socket. This behaviour differs from many other BSD socket implementations which don't pass any errors unless the socket is connected. -Linux's behaviour is mandated by +Linux's behaviour is mandated by .BR RFC\ 1122 . -For compatibility with legacy code in Linux 2.0 and 2.2 +For compatibility with legacy code in Linux 2.0 and 2.2 it was possible to set the -.B SO_BSDCOMPAT -SOL_SOCKET option to receive remote errors only when the socket has been +.B SO_BSDCOMPAT +SOL_SOCKET option to receive remote errors only when the socket has been connected (except for .B EPROTO and .BR EMSGSIZE ). Locally generated errors are always passed. -Support for this socket option was removed in later kernels; see +Support for this socket option was removed in later kernels; see .BR socket (7) for further information. -When the +When the .B IP_RECVERR option is enabled all errors are stored in the socket error queue and can be received by .BR recvmsg (2) -with the +with the .B MSG_ERRQUEUE flag set. .SH "SOCKET OPTIONS" @@ -127,7 +130,7 @@ To set or get a UDP socket option, call .BR getsockopt (2) to read or .BR setsockopt (2) -to write the option with the option level argument set to +to write the option with the option level argument set to .BR IPPROTO_UDP . .TP .BR UDP_CORK " (since Linux 2.5.44)" @@ -150,12 +153,12 @@ The correct syntax is: .RE .TP .BR FIONREAD " (" SIOCINQ ) -Gets a pointer to an integer as argument. -Returns the size of the next pending datagram in the integer in bytes, +Gets a pointer to an integer as argument. +Returns the size of the next pending datagram in the integer in bytes, or 0 when no datagram is pending. .TP .BR TIOCOUTQ " (" SIOCOUTQ ) -Returns the number of data bytes in the local send queue. +Returns the number of data bytes in the local send queue. Only supported with Linux 2.4 and above. .PP In addition all ioctls documented in @@ -164,14 +167,14 @@ and .BR socket (7) are supported. .SH ERRORS -All errors documented for +All errors documented for .BR socket (7) -or +or .BR ip (7) -may be returned by a send or receive on a UDP socket. +may be returned by a send or receive on a UDP socket. .B ECONNREFUSED -No receiver was associated with the destination address. +No receiver was associated with the destination address. This might be caused by a previous packet sent over the socket. .SH VERSIONS IP_RECVERR is a new feature in Linux 2.2. diff --git a/man7/unicode.7 b/man7/unicode.7 index ead23a80be..cb12af6847 100644 --- a/man7/unicode.7 +++ b/man7/unicode.7 @@ -35,25 +35,29 @@ The international standard .B ISO 10646 defines the .BR "Universal Character Set (UCS)" . -UCS contains all characters of all other character set standards. It -also guarantees +UCS contains all characters of all other character set standards. +It also guarantees .BR "round-trip compatibility" , i.e., conversion tables can be built such that no information is lost when a string is converted from any other encoding to UCS and back. UCS contains the characters required to represent practically all -known languages. This includes not only the Latin, Greek, Cyrillic, +known languages. +This includes not only the Latin, Greek, Cyrillic, Hebrew, Arabic, Armenian, and Georgian scripts, but also Chinese, Japanese and Korean Han ideographs as well as scripts such as Hiragana, Katakana, Hangul, Devanagari, Bengali, Gurmukhi, Gujarati, Oriya, Tamil, Telugu, Kannada, Malayalam, Thai, Lao, Khmer, Bopomofo, Tibetan, Runic, Ethiopic, Canadian Syllabics, Cherokee, Mongolian, -Ogham, Myanmar, Sinhala, Thaana, Yi, and others. For scripts not yet +Ogham, Myanmar, Sinhala, Thaana, Yi, and others. +For scripts not yet covered, research on how to best encode them for computer usage is -still going on and they will be added eventually. This might +still going on and they will be added eventually. +This might eventually include not only Hieroglyphs and various historic Indo-European languages, but even some selected artistic scripts such -as Tengwar, Cirth, and Klingon. UCS also covers a large number of +as Tengwar, Cirth, and Klingon. +UCS also covers a large number of graphical, typographical, mathematical and scientific symbols, including those provided by TeX, Postscript, APL, MS-DOS, MS-Windows, Macintosh, OCR fonts, as well as many word processing and publishing @@ -69,20 +73,25 @@ made up of 256 8-bit .I rows with 256 .I column -positions, one for each character. Part 1 of the standard +positions, one for each character. +Part 1 of the standard .RB ( "ISO 10646-1" ) defines the first 65534 code positions (0x0000 to 0xfffd), which form the .IR "Basic Multilingual Plane (BMP)" , -that is plane 0 in group 0. Part 2 of the standard +that is plane 0 in group 0. +Part 2 of the standard .RB ( "ISO 10646-2" ) adds characters to group 0 outside the BMP in several .I "supplementary planes" -in the range 0x10000 to 0x10ffff. There are no plans to add characters +in the range 0x10000 to 0x10ffff. +There are no plans to add characters beyond 0x10ffff to the standard, therefore of the entire code space, only a small fraction of group 0 will ever be actually used in the -foreseeable future. The BMP contains all characters found in the -commonly used other character sets. The supplemental planes added by +foreseeable future. +The BMP contains all characters found in the +commonly used other character sets. +The supplemental planes added by ISO 10646-2 cover only more exotic characters for special scientific, dictionary printing, publishing industry, higher-level protocol and enthusiast needs. @@ -111,12 +120,14 @@ Some code points in .B UCS have been assigned to .IR "combining characters" . -These are similar to the non-spacing accent keys on a typewriter. A -combining character just adds an accent to the previous character. The -most important accented characters have codes of their own in UCS, +These are similar to the non-spacing accent keys on a typewriter. +A combining character just adds an accent to the previous character. +The most important accented characters have codes of their own in UCS, however, the combining character mechanism allows us to add accents -and other diacritical marks to any character. The combining characters -always follow the character which they modify. For example, the German +and other diacritical marks to any character. +The combining characters +always follow the character which they modify. +For example, the German character Umlaut-A ("Latin capital letter A with diaeresis") can either be represented by the precomposed UCS code 0x00c4, or alternatively as the combination of a normal "Latin capital letter A" @@ -132,7 +143,7 @@ combining characters, ISO 10646-1 specifies the following three of UCS: .TP 0.9i Level 1 -Combining characters and +Combining characters and .B Hangul Jamo (a variant encoding of the Korean script, where a Hangul syllable glyph is coded as a triplet or pair of vovel/consonant codes) are not @@ -156,16 +167,19 @@ contains exactly the .B UCS Basic Multilingual Plane at implementation level 3, as described in ISO 10646-1:2000. .B Unicode 3.1 -added the supplemental planes of ISO 10646-2. The Unicode standard and +added the supplemental planes of ISO 10646-2. +The Unicode standard and technical reports published by the Unicode Consortium provide much additional information on the semantics and recommended usages of -various characters. They provide guidelines and algorithms for +various characters. +They provide guidelines and algorithms for editing, sorting, comparing, normalizing, converting and displaying Unicode strings. .SH "UNICODE UNDER LINUX" Under GNU/Linux, the C type .B wchar_t -is a signed 32-bit integer type. Its values are always interpreted +is a signed 32-bit integer type. +Its values are always interpreted by the C library as .B UCS code values (in all locales), a convention that is signaled by the GNU @@ -177,7 +191,8 @@ UCS/Unicode can be used just like ASCII in input/output streams, terminal communication, plaintext files, filenames, and environment variables in the ASCII compatible .B UTF-8 -multi-byte encoding. To signal the use of UTF-8 as the character +multi-byte encoding. +To signal the use of UTF-8 as the character encoding to all applications, a suitable .B locale has to be selected via environment variables (e.g., @@ -185,8 +200,8 @@ has to be selected via environment variables (e.g., .PP The .B nl_langinfo(CODESET) -function returns the name of the selected encoding. Library functions -such as +function returns the name of the selected encoding. +Library functions such as .BR wctomb (3) and .BR mbsrtowcs (3) @@ -199,7 +214,8 @@ tells, how many positions (0\(en2) the cursor is advanced by the output of a character. .PP Under Linux, in general only the BMP at implementation level 1 should -be used at the moment. Up to two combining characters per base +be used at the moment. +Up to two combining characters per base character for certain scripts (in particular Thai) are also supported by some UTF-8 terminal emulators and ISO 10646 fonts (level 2), but in general precomposed characters should be preferred where available @@ -209,11 +225,13 @@ general precomposed characters should be preferred where available In the .BR BMP , the range 0xe000 to 0xf8ff will never be assigned to any characters by -the standard and is reserved for private usage. For the Linux +the standard and is reserved for private usage. +For the Linux community, this private area has been subdivided further into the range 0xe000 to 0xefff which can be used individually by any end-user and the Linux zone in the range 0xf000 to 0xf8ff where extensions are -coordinated among all Linux users. The registry of the characters +coordinated among all Linux users. +The registry of the characters assigned to the Linux zone is currently maintained by H. Peter Anvin <Peter.Anvin@linux.org>. .SH LITERATURE @@ -237,7 +255,8 @@ Reading, MA, 2000, ISBN 0-201-61633-5. S. Harbison, G. Steele. C: A Reference Manual. Fourth edition, Prentice Hall, Englewood Cliffs, 1995, ISBN 0-13-326224-3. -A good reference book about the C programming language. The fourth +A good reference book about the C programming language. +The fourth edition covers the 1994 Amendment 1 to the ISO C 90 standard, which adds a large number of new C library functions for handling wide and multi-byte character encodings, but it does not yet cover ISO C 99, @@ -271,13 +290,15 @@ When this man page was last revised, the GNU C Library support for locales was mature and XFree86 support was in an advanced state, but work on making applications (most notably editors) suitable for use in .B UTF-8 -locales was still fully in progress. Current general +locales was still fully in progress. +Current general .B UCS support under Linux usually provides for CJK double-width characters and sometimes even simple overstriking combining characters, but usually does not include support for scripts with right-to-left writing direction or ligature substitution requirements such as -Hebrew, Arabic, or the Indic scripts. These scripts are currently only +Hebrew, Arabic, or the Indic scripts. +These scripts are currently only supported in certain GUI applications (HTML viewers, word processors) with sophisticated text rendering engines. .SH AUTHOR diff --git a/man7/units.7 b/man7/units.7 index d332bd250c..43b7c3a10b 100644 --- a/man7/units.7 +++ b/man7/units.7 @@ -9,7 +9,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -17,7 +17,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -65,7 +65,8 @@ http://physics.nist.gov/cuu/Units/prefixes.html .RE .SS Binary prefixes The binary prefixes resemble the decimal ones, but have an additional 'i' -(and "Ki" starts with a capital 'K'). The names are formed by taking the +(and "Ki" starts with a capital 'K'). +The names are formed by taking the first syllable of the names of the decimal prefix with roughly the same size, followed by "bi" for "binary". .RS @@ -95,7 +96,8 @@ capitalized to indicate binary-ness. At first that didn't matter too much, since memory modules and disks came in sizes that were powers of two, so everyone knew that in such contexts "kilobyte" and "megabyte" meant -1024 and 1048576 bytes, respectively. What originally was a +1024 and 1048576 bytes, respectively. +What originally was a sloppy use of the prefixes "kilo" and "mega" started to become regarded as the "real true meaning" when computers were involved. But then disk technology changed, and disk sizes became arbitrary numbers. @@ -104,14 +106,16 @@ standard, namely k=1000, M=1000k, G=1000M. The situation was messy: in the 14k4 modems, k=1000; in the 1.44MB .\" also common: 14.4k modem -diskettes, M=1024000; etc. In 1998 the IEC approved the standard +diskettes, M=1024000; etc. +In 1998 the IEC approved the standard that defines the binary prefixes given above, enabling people to be precise and unambiguous. Thus, today, MB = 1000000B and MiB = 1048576B. In the free software world programs are slowly -being changed to conform. When the Linux kernel boots and says +being changed to conform. +When the Linux kernel boots and says .RS .nf diff --git a/man7/unix.7 b/man7/unix.7 index 05b0b6affd..0d17fe96f0 100644 --- a/man7/unix.7 +++ b/man7/unix.7 @@ -9,9 +9,9 @@ .\" Modified, 2004-05-27, Michael Kerrisk, <mtk-manpages@gmx.net> .\" Added SOCK_SEQPACKET .\" -.TH UNIX 7 2004-05-27 "Linux Man Page" "Linux Programmer's Manual" +.TH UNIX 7 2004-05-27 "Linux Man Page" "Linux Programmer's Manual" .SH NAME -unix, PF_UNIX, AF_UNIX, PF_LOCAL, AF_LOCAL \- Sockets for local +unix, PF_UNIX, AF_UNIX, PF_LOCAL, AF_LOCAL \- Sockets for local interprocess communication .SH SYNOPSIS .B #include <sys/socket.h> @@ -27,9 +27,10 @@ The (also known as .BR PF_LOCAL ) socket family is used to communicate between processes on the same machine -efficiently. Unix sockets can be either anonymous (created by +efficiently. +Unix sockets can be either anonymous (created by .BR socketpair (2)) -or associated with a file of type socket. +or associated with a file of type socket. Linux also supports an abstract namespace which is independent of the file system. @@ -43,21 +44,23 @@ sockets are always reliable and don't reorder datagrams); and (since kernel 2.6.4) .BR SOCK_SEQPACKET , for a connection-oriented socket that preserves message boundaries -and delivers messages in the order that they were sent. +and delivers messages in the order that they were sent. -Unix sockets support passing file descriptors or process credentials +Unix sockets support passing file descriptors or process credentials to other processes using ancillary data. .SH "ADDRESS FORMAT" -A Unix address is defined as a filename in the filesystem or -as a unique string in the abstract namespace. Sockets created by +A Unix address is defined as a filename in the filesystem or +as a unique string in the abstract namespace. +Sockets created by .BR socketpair (2) -are anonymous. For non-anonymous sockets the target address can be set +are anonymous. +For non-anonymous sockets the target address can be set using -.BR connect (2). +.BR connect (2). The local address can be set using -.BR bind (2). +.BR bind (2). When a socket is connected and it doesn't already have a local address a -unique address in the abstract namespace will be generated automatically. +unique address in the abstract namespace will be generated automatically. .in +0.25i .nf @@ -70,41 +73,41 @@ struct sockaddr_un { .fi .in -0.25i -.B sun_family +.B sun_family always contains .BR AF_UNIX . .B sun_path contains the zero-terminated pathname of the socket in the file system. -If +If .B sun_path -starts with a null byte (''\0'), +starts with a null byte (''\0'), then it refers to the abstract namespace maintained by the Unix protocol module. -The socket's address in this namespace is given by the rest of the +The socket's address in this namespace is given by the rest of the bytes in .BR sun_path . Note that names in the abstract namespace are not zero-terminated. .SH "SOCKET OPTIONS" -For historical reasons these socket options are specified with a +For historical reasons these socket options are specified with a SOL_SOCKET type even though they are PF_UNIX specific. -They can be set with +They can be set with .BR setsockopt (2) -and read with +and read with .BR getsockopt (2) by specifying SOL_SOCKET as the socket family. .TP .B SO_PASSCRED -Enables the receiving of the credentials of the sending process -ancillary message. +Enables the receiving of the credentials of the sending process +ancillary message. When this option is set and the socket is not yet connected a unique name in the abstract namespace will be generated automatically. -Expects an integer boolean flag. +Expects an integer boolean flag. .SH "(UN)SUPPORTED FEATURES" -The following paragraphs describe domain-specific details and +The following paragraphs describe domain-specific details and unsupported features of the sockets API for Unix domain sockets on Linux. -Unix domain sockets do not support the transmission of -out-of-band data (the +Unix domain sockets do not support the transmission of +out-of-band data (the .B MSG_OOB flag for .BR send (2) @@ -133,69 +136,72 @@ Ancillary data is sent and received using and .BR recvmsg (2). For historical reasons the ancillary message types listed below -are specified with a SOL_SOCKET type even though they are PF_UNIX +are specified with a SOL_SOCKET type even though they are PF_UNIX specific. To send them set the .B cmsg_level -field of the struct +field of the struct .B cmsghdr -to SOL_SOCKET and the -.B cmsg_type -field to the type. For more information see -.BR cmsg (3). +to SOL_SOCKET and the +.B cmsg_type +field to the type. +For more information see +.BR cmsg (3). .TP .B SCM_RIGHTS -Send or receive a set of open file descriptors from another process. +Send or receive a set of open file descriptors from another process. The data portion contains an integer array of the file descriptors. The passed file descriptors behave as though they have been created with .BR dup (2). .TP .B SCM_CREDENTIALS -Send or receive Unix credentials. This can be used for authentication. -The credentials are passed as a +Send or receive Unix credentials. +This can be used for authentication. +The credentials are passed as a .I struct ucred ancillary message. .in +0.25i .nf struct ucred { - pid_t pid; /* process ID of the sending process */ - uid_t uid; /* user ID of the sending process */ - gid_t gid; /* group ID of the sending process */ + pid_t pid; /* process ID of the sending process */ + uid_t uid; /* user ID of the sending process */ + gid_t gid; /* group ID of the sending process */ }; .fi .in -0.25i - + The credentials which the sender specifies are checked by the kernel. -A process with effective user ID 0 is allowed to specify values that do -not match its own. +A process with effective user ID 0 is allowed to specify values that do +not match its own. The sender must specify its own process ID (unless it has the capability .BR CAP_SYS_ADMIN ), its user ID, effective user ID, or saved set-user-ID (unless it has .BR CAP_SETUID ), -and its group ID, effective group ID, or saved set-group-ID +and its group ID, effective group ID, or saved set-group-ID (unless it has .BR CAP_SETGID ). To receive a .I struct ucred message the -.B SO_PASSCRED +.B SO_PASSCRED option must be enabled on the socket. .SH VERSIONS -.B SCM_CREDENTIALS +.B SCM_CREDENTIALS and the abstract namespace were introduced with Linux 2.2 and should not be used in portable programs. (Some BSD-derived systems also support credential passing, but the implementation details differ.) .SH NOTES In the Linux implementation, sockets which are visible in the -filesystem honour the permissions of the directory they are in. Their -owner, group and their permissions can be changed. +filesystem honour the permissions of the directory they are in. +Their owner, group and their permissions can be changed. Creation of a new socket will fail if the process does not have write and search (execute) permission on the directory the socket is created in. Connecting to the socket object requires read/write permission. This behavior differs from many BSD-derived systems which -ignore permissions for Unix sockets. Portable programs should not rely on +ignore permissions for Unix sockets. +Portable programs should not rely on this feature for security. Binding to a socket with a filename creates a socket @@ -203,14 +209,14 @@ in the file system that must be deleted by the caller when it is no longer needed (using .BR unlink (2)). The usual Unix close-behind semantics apply; the socket can be unlinked -at any time and will be finally removed from the file system when the last +at any time and will be finally removed from the file system when the last reference to it is closed. To pass file descriptors or credentials over a SOCK_STREAM, you need to send or receive at least one byte of non-ancillary data in the same -.BR sendmsg () +.BR sendmsg () or -.BR recvmsg () +.BR recvmsg () call. Unix domain stream sockets do not support the notion of out-of-band data. @@ -221,18 +227,20 @@ Out of memory. .TP .B ECONNREFUSED .BR connect (2) -called with a socket object that isn't listening. This can happen when +called with a socket object that isn't listening. +This can happen when the remote socket does not exist or the filename is not a socket. .TP .B EINVAL -Invalid argument passed. A common cause is the missing setting of AF_UNIX -in the -.I sun_type -field of passed addresses or the socket being in an +Invalid argument passed. +A common cause is the missing setting of AF_UNIX +in the +.I sun_type +field of passed addresses or the socket being in an invalid state for the applied operation. .TP .B EOPNOTSUPP -Stream operation called on non-stream oriented socket or tried to +Stream operation called on non-stream oriented socket or tried to use the out-of-band data option. .TP .B EPROTONOSUPPORT @@ -240,14 +248,14 @@ Passed protocol is not PF_UNIX. .TP .B ESOCKTNOSUPPORT Unknown socket type. -.TP +.TP .B EPROTOTYPE Remote socket does not match the local socket type (SOCK_DGRAM vs. SOCK_STREAM) .TP .B EADDRINUSE -Selected local address is already taken or filesystem socket -object already exists. +Selected local address is already taken or filesystem socket +object already exists. .TP .B EISCONN .BR connect (2) @@ -261,9 +269,11 @@ Socket operation needs a target address, but the socket is not connected. Remote socket was unexpectedly closed. .TP .B EPIPE -Remote socket was closed on a stream socket. If enabled, a -.B SIGPIPE -is sent as well. This can be avoided by passing the +Remote socket was closed on a stream socket. +If enabled, a +.B SIGPIPE +is sent as well. +This can be avoided by passing the .B MSG_NOSIGNAL flag to .BR sendmsg (2) @@ -277,9 +287,9 @@ User memory address was not valid. The sender passed invalid credentials in the .IR "struct ucred" . .PP -Other errors can be generated by the generic socket layer or -by the filesystem while generating a filesystem socket object. See -the appropriate manual pages for more information. +Other errors can be generated by the generic socket layer or +by the filesystem while generating a filesystem socket object. +See the appropriate manual pages for more information. .SH "SEE ALSO" .BR recvmsg (2), .BR sendmsg (2), diff --git a/man7/uri.7 b/man7/uri.7 index 6aca5d977e..2ecb1b38fa 100644 --- a/man7/uri.7 +++ b/man7/uri.7 @@ -9,7 +9,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -17,7 +17,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -194,7 +194,8 @@ which case the delimiting "/" is also optional and the gophertype defaults to "1". .PP .I selector -is the Gopher selector string. In the Gopher protocol, +is the Gopher selector string. +In the Gopher protocol, Gopher selector strings are a sequence of octets which may contain any octets except 09 hexadecimal (US-ASCII HT or tab), 0A hexadecimal (US-ASCII character LF), and 0D (US-ASCII character CR). @@ -236,7 +237,8 @@ presence of the "@" character. .RI telnet:// ip_server / .PP The Telnet URL scheme is used to designate interactive text services that -may be accessed by the Telnet protocol. The final "/" character may be omitted. +may be accessed by the Telnet protocol. +The final "/" character may be omitted. The default port is 23. An example is <telnet://melvyl.ucop.edu/>. .SS "file \- Normal file" @@ -263,7 +265,8 @@ and .PP The second format (e.g., <file:/etc/passwd>) is a correct format for referring to -a local file. However, older standards did not permit this format, +a local file. +However, older standards did not permit this format, and some programs don't recognize this as a URI. A more portable syntax is to use an empty string as the server name, e.g., <file:///etc/passwd>; this form does the same thing @@ -353,7 +356,7 @@ The components of this URL are: .IP hostport 12 the LDAP server to query, written as a hostname optionally followed by a colon and the port number. -The default LDAP port is TCP port 389. +The default LDAP port is TCP port 389. If empty, the client determines which the LDAP server to use. .IP dn the LDAP Distinguished Name, which identifies @@ -364,15 +367,17 @@ RFC\ 2253 section 3). .IP attributes a comma-separated list of attributes to be returned; -see RFC\ 2251 section 4.1.5. +see RFC\ 2251 section 4.1.5. If omitted, all attributes should be returned. .IP scope specifies the scope of the search, which can be one of "base" (for a base object search), "one" (for a one-level search), -or "sub" (for a subtree search). If scope is omitted, "base" is assumed. +or "sub" (for a subtree search). +If scope is omitted, "base" is assumed. .IP filter specifies the search filter (subset of entries -to return). If omitted, all entries should be returned. +to return). +If omitted, all entries should be returned. See .UR http://www.ietf.org/rfc/rfc2254.txt RFC\ 2254 @@ -381,7 +386,8 @@ section 4. .IP extensions a comma-separated list of type=value pairs, where the =value portion may be omitted for options not -requiring it. An extension prefixed with a '!' is critical +requiring it. +An extension prefixed with a '!' is critical (must be supported to be valid), otherwise it's non-critical (optional). .PP LDAP queries are easiest to explain by example. @@ -463,7 +469,8 @@ All other characters must be escaped. An escaped octet is encoded as a character triplet, consisting of the percent character "%" followed by the two hexadecimal digits representing the octet code (you can use upper or lower case letters -for the hexadecimal digits). For example, a blank space must be escaped +for the hexadecimal digits). +For example, a blank space must be escaped as "%20", a tab character as "%09", and the "&" as "%26". Because the percent "%" character always has the reserved purpose of being the escape indicator, it must be escaped as "%25". @@ -509,7 +516,7 @@ is preferred practice in Great Britain and hackers worldwide Jargon File's section on Hacker Writing Style, .IR http://www.fwi.uva.nl/~mes/jargon/h/HackerWritingStyle.html , for more information). -Older documents suggested inserting the prefix "URL:" +Older documents suggested inserting the prefix "URL:" just before the URI, but this form has never caught on. .PP The URI syntax was designed to be unambiguous. @@ -574,7 +581,8 @@ Efforts to aid this convergence are encouraged. .PP A URI does not in itself pose a security threat. There is no general guarantee that a URL, which at one time -located a given resource, will continue to do so. Nor is there any +located a given resource, will continue to do so. +Nor is there any guarantee that a URL will not locate a different resource at some later point in time; such a guarantee can only be obtained from the person(s) controlling that namespace and the @@ -583,13 +591,16 @@ resource in question. It is sometimes possible to construct a URL such that an attempt to perform a seemingly harmless operation, such as the retrieval of an entity associated with the resource, will in fact -cause a possibly damaging remote operation to occur. The unsafe URL +cause a possibly damaging remote operation to occur. +The unsafe URL is typically constructed by specifying a port number other than that -reserved for the network protocol in question. The client -unwittingly contacts a site that is in fact running a different -protocol. The content of the URL contains instructions that, when +reserved for the network protocol in question. +The client unwittingly contacts a site that is in fact +running a different protocol. +The content of the URL contains instructions that, when interpreted according to this other protocol, cause an unexpected -operation. An example has been the use of a gopher URL to cause an +operation. +An example has been the use of a gopher URL to cause an unintended or impersonating message to be sent via a SMTP server. .PP Caution should be used when using any URL that specifies a port @@ -598,14 +609,15 @@ a number within the reserved space. .PP Care should be taken when a URI contains escaped delimiters for a given protocol (for example, CR and LF characters for telnet -protocols) that these are not unescaped before transmission. This -might violate the protocol, but avoids the potential for such +protocols) that these are not unescaped before transmission. +This might violate the protocol, but avoids the potential for such characters to be used to simulate an extra operation or parameter in that protocol, which might lead to an unexpected and possibly harmful remote operation to be performed. .PP It is clearly unwise to use a URI that contains a password which is -intended to be secret. In particular, the use of a password within +intended to be secret. +In particular, the use of a password within the 'userinfo' component of a URI is strongly recommended against except in those rare cases where the 'password' parameter is intended to be public. .SH "CONFORMING TO" diff --git a/man7/utf-8.7 b/man7/utf-8.7 index e978f96166..f6ff53da90 100644 --- a/man7/utf-8.7 +++ b/man7/utf-8.7 @@ -33,20 +33,22 @@ UTF-8 \- an ASCII compatible multi-byte Unicode encoding .SH DESCRIPTION The .B Unicode 3.0 -character set occupies a 16-bit code space. The most obvious +character set occupies a 16-bit code space. +The most obvious Unicode encoding (known as .BR UCS-2 ) -consists of a sequence of 16-bit words. Such strings can contain as +consists of a sequence of 16-bit words. +Such strings can contain as parts of many 16-bit characters bytes like '\\0' or '/' which have a special meaning in filenames and other C library function parameters. In addition, the majority of UNIX tools expects ASCII files and can't -read 16-bit words as characters without major modifications. For these -reasons, +read 16-bit words as characters without major modifications. +For these reasons, .B UCS-2 is not a suitable external encoding of .B Unicode -in filenames, text files, environment variables, etc. The -.BR "ISO 10646 Universal Character Set (UCS)" , +in filenames, text files, environment variables, etc. +The .BR "ISO 10646 Universal Character Set (UCS)" , a superset of Unicode, occupies even a 31-bit code space and the obvious .B UCS-4 encoding for it (a sequence of 32-bit words) has the same problems. @@ -61,8 +63,8 @@ does not have these problems and is the common way in which .B Unicode is used on Unix-style operating systems. .SH PROPERTIES -The -.B UTF-8 +The +.B UTF-8 encoding has the following nice properties: .TP 0.2i * @@ -70,8 +72,9 @@ encoding has the following nice properties: characters 0x00000000 to 0x0000007f (the classic .B US-ASCII characters) are encoded simply as bytes 0x00 to 0x7f (ASCII -compatibility). This means that files and strings which contain only -7-bit ASCII characters have the same encoding under both +compatibility). +This means that files and strings which contain only +7-bit ASCII characters have the same encoding under both .B ASCII and .BR UTF-8 . @@ -90,7 +93,7 @@ The lexicographic sorting order of strings is preserved. .TP * -All possible 2^31 UCS codes can be encoded using +All possible 2^31 UCS codes can be encoded using .BR UTF-8 . .TP * @@ -98,12 +101,14 @@ The bytes 0xfe and 0xff are never used in the .B UTF-8 encoding. .TP -* +* The first byte of a multi-byte sequence which represents a single non-ASCII .B UCS character is always in the range 0xc0 to 0xfd and indicates how long -this multi-byte sequence is. All further bytes in a multi-byte sequence -are in the range 0x80 to 0xbf. This allows easy resynchronization and +this multi-byte sequence is. +All further bytes in a multi-byte sequence +are in the range 0x80 to 0xbf. +This allows easy resynchronization and makes the encoding stateless and robust against missing bytes. .TP * @@ -116,14 +121,14 @@ standard specifies no characters above 0x10ffff, so Unicode characters can only be up to four bytes long in .BR UTF-8 . .SH ENCODING -The following byte sequences are used to represent a character. The -sequence to be used depends on the UCS code number of the character: +The following byte sequences are used to represent a character. +The sequence to be used depends on the UCS code number of the character: .TP 0.4i 0x00000000 \- 0x0000007F: .RI 0 xxxxxxx .TP 0x00000080 \- 0x000007FF: -.RI 110 xxxxx +.RI 110 xxxxx .RI 10 xxxxxx .TP 0x00000800 \- 0x0000FFFF: @@ -155,7 +160,8 @@ sequence to be used depends on the UCS code number of the character: The .I xxx bit positions are filled with the bits of the character code number in -binary representation. Only the shortest possible multi-byte sequence +binary representation. +Only the shortest possible multi-byte sequence which can represent the code number of the character can be used. .PP The @@ -181,7 +187,7 @@ encoded as: 11100010 10001001 10100000 = 0xe2 0x89 0xa0 .RE .SH "APPLICATION NOTES" -Users have to select a +Users have to select a .B UTF-8 locale, for example with .PP @@ -189,7 +195,7 @@ locale, for example with export LANG=en_GB.UTF-8 .RE .PP -in order to activate the +in order to activate the .B UTF-8 support in applications. .PP @@ -206,12 +212,12 @@ and programmers can then test the expression strcmp(nl_langinfo(CODESET), "UTF-8") == 0 .RE .PP -to determine whether a +to determine whether a .B UTF-8 locale has been selected and whether therefore all plaintext standard input and output, terminal communication, plaintext file content, filenames and environment -variables are encoded in +variables are encoded in .BR UTF-8 . .PP Programmers accustomed to single-byte encodings such as @@ -221,16 +227,18 @@ or have to be aware that two assumptions made so far are no longer valid in .B UTF-8 -locales. Firstly, a single byte does not necessarily correspond any -more to a single character. Secondly, since modern terminal emulators -in +locales. +Firstly, a single byte does not necessarily correspond any +more to a single character. +Secondly, since modern terminal emulators +in .B UTF-8 mode also support Chinese, Japanese, and Korean .B double-width characters as well as non-spacing .BR "combining characters" , outputting a single character does not necessarily advance the cursor -by one position as it did in +by one position as it did in .BR ASCII . Library functions such as .BR mbsrtowcs (3) @@ -243,9 +251,11 @@ The official ESC sequence to switch from an encoding scheme (as used for instance by VT100 terminals) to .B UTF-8 is ESC % G -("\\x1b%G"). The corresponding return sequence from +("\\x1b%G"). +The corresponding return sequence from .B UTF-8 -to ISO 2022 is ESC % @ ("\\x1b%@"). Other ISO 2022 sequences (such as +to ISO 2022 is ESC % @ ("\\x1b%@"). +Other ISO 2022 sequences (such as for switching the G0 and G1 sets) are not applicable in UTF-8 mode. .PP It can be hoped that in the foreseeable future, @@ -259,13 +269,14 @@ leading to a significantly richer environment for handling plain text. .SH SECURITY The .BR Unicode " and " UCS -standards require that producers of +standards require that producers of .B UTF-8 shall use the shortest form possible, e.g., producing a two-byte sequence with first byte 0xc0 is non-conforming. .B Unicode 3.1 has added the requirement that conforming programs must not accept -non-shortest forms in their input. This is for security reasons: if +non-shortest forms in their input. +This is for security reasons: if user input is checked for possible security violations, a program might check only for the .B ASCII diff --git a/man7/x25.7 b/man7/x25.7 index 6bc4a8c337..7df617a910 100644 --- a/man7/x25.7 +++ b/man7/x25.7 @@ -1,42 +1,47 @@ -.\" This man page is Copyright (C) 1998 Heiner Eisen. +.\" This man page is Copyright (C) 1998 Heiner Eisen. .\" Permission is granted to distribute possibly modified copies .\" of this page provided the header is included verbatim, .\" and in case of nontrivial modification author and date .\" of the modification is added to the header. .\" $Id: x25.7,v 1.4 1999/05/18 10:35:12 freitag Exp $ -.TH X25 7 1998-12-01 "Linux Man Page" "Linux Programmer's Manual" +.TH X25 7 1998-12-01 "Linux Man Page" "Linux Programmer's Manual" .SH NAME -x25, PF_X25 \- ITU-T X.25 / ISO-8208 protocol interface. +x25, PF_X25 \- ITU-T X.25 / ISO-8208 protocol interface. .SH SYNOPSIS .B #include <sys/socket.h> .br .B #include <linux/x25.h> .sp -.B x25_socket = socket(PF_X25, SOCK_SEQPACKET, 0); +.B x25_socket = socket(PF_X25, SOCK_SEQPACKET, 0); .SH DESCRIPTION X25 sockets provide an interface to the X.25 packet layer protocol. This allows applications to communicate over a public X.25 data network as standardised by International Telecommunication Union's recommendation X.25 -(X.25 DTE-DCE mode). X25 sockets can also be used for communication +(X.25 DTE-DCE mode). +X25 sockets can also be used for communication without an intermediate X.25 network (X.25 DTE-DTE mode) as described in ISO-8208. .PP -Message boundaries are preserved \(em a -.BR read (2) +Message boundaries are preserved \(em a +.BR read (2) from a socket will retrieve the same chunk of data as output with the corresponding -.BR write (2) -to the peer socket. When necessary, the kernel takes care +.BR write (2) +to the peer socket. +When necessary, the kernel takes care of segmenting and re-assembling long messages by means of -the X.25 M-bit. There is no hard-coded upper limit for the -message size. However, re-assembling of a long message might fail if +the X.25 M-bit. +There is no hard-coded upper limit for the +message size. +However, re-assembling of a long message might fail if there is a temporary lack of system resources or when other constraints -(such as socket memory or buffer size limits) become effective. If that +(such as socket memory or buffer size limits) become effective. +If that occurs, the X.25 connection will be reset. .SH "SOCKET ADDRESSES" -The -.B AF_X25 +The +.B AF_X25 socket address family uses the .I struct sockaddr_x25 for representing network addresses as defined in ITU-T @@ -53,7 +58,7 @@ struct sockaddr_x25 { .PP .I sx25_addr contains a char array -.I x25_addr[] +.I x25_addr[] to be interpreted as a null-terminated string. .I sx25_addr.x25_addr[] consists of up to 15 (not counting the terminating 0) ASCII @@ -62,43 +67,50 @@ Only the decimal digit characters from `0' to `9' are allowed. .SH "SOCKET OPTIONS" The following X.25 specific socket options can be set by using .BR setsockopt (2) -and read with +and read with .BR getsockopt (2) -with the level parameter set to +with the level parameter set to .BR SOL_X25 . .TP .B X25_QBITINCL Controls whether the X.25 Q-bit (Qualified Data Bit) is accessible by the -user. It expects an integer argument. If set to 0 (default), +user. +It expects an integer argument. +If set to 0 (default), the Q-bit is never set for outgoing packets and the Q-bit of incoming -packets is ignored. If set to 1, an additional first byte is prepended -to each message read from or written to the socket. For data read from +packets is ignored. +If set to 1, an additional first byte is prepended +to each message read from or written to the socket. +For data read from the socket, a 0 first byte indicates that the Q-bits of the corresponding -incoming data packets were not set. A first byte with value 1 indicates +incoming data packets were not set. +A first byte with value 1 indicates that the Q-bit of the corresponding incoming data packets was set. If the first byte of the data written to the socket is 1 the Q-bit of the -corresponding outgoing data packets will be set. If the first byte is 0 +corresponding outgoing data packets will be set. +If the first byte is 0 the Q-bit will not be set. .SH BUGS -Plenty, as the X.25 PLP implementation is +Plenty, as the X.25 PLP implementation is .BR CONFIG_EXPERIMENTAL . .PP This man page is incomplete. .PP There is no dedicated application programmer's header file yet; -you need to include the kernel header file +you need to include the kernel header file .IR <linux/x25.h> . -.B CONFIG_EXPERIMENTAL +.B CONFIG_EXPERIMENTAL might also imply that future versions of the -interface are not binary compatible. +interface are not binary compatible. .PP -X.25 N-Reset events are not propagated to the user process yet. Thus, -if a reset occurred, data might be lost without notice. +X.25 N-Reset events are not propagated to the user process yet. +Thus, +if a reset occurred, data might be lost without notice. .SH "SEE ALSO" .BR socket (2), .BR socket (7) .PP -Jonathan Simon Naylor: +Jonathan Simon Naylor: \(lqThe Re-Analysis and Re-Implementation of X.25.\(rq The URL is .RS |