diff options
Diffstat (limited to 'man7')
| -rw-r--r-- | man7/environ.7 | 16 | ||||
| -rw-r--r-- | man7/epoll.7 | 10 | ||||
| -rw-r--r-- | man7/feature_test_macros.7 | 62 | ||||
| -rw-r--r-- | man7/futex.7 | 2 | ||||
| -rw-r--r-- | man7/ip.7 | 40 | ||||
| -rw-r--r-- | man7/ipv6.7 | 8 | ||||
| -rw-r--r-- | man7/locale.7 | 2 | ||||
| -rw-r--r-- | man7/man-pages.7 | 116 | ||||
| -rw-r--r-- | man7/man.7 | 2 | ||||
| -rw-r--r-- | man7/math_error.7 | 18 | ||||
| -rw-r--r-- | man7/netdevice.7 | 18 | ||||
| -rw-r--r-- | man7/netlink.7 | 48 | ||||
| -rw-r--r-- | man7/packet.7 | 60 | ||||
| -rw-r--r-- | man7/raw.7 | 36 | ||||
| -rw-r--r-- | man7/rtld-audit.7 | 34 | ||||
| -rw-r--r-- | man7/rtnetlink.7 | 42 | ||||
| -rw-r--r-- | man7/sock_diag.7 | 2 | ||||
| -rw-r--r-- | man7/socket.7 | 64 | ||||
| -rw-r--r-- | man7/tcp.7 | 52 | ||||
| -rw-r--r-- | man7/udp.7 | 16 | ||||
| -rw-r--r-- | man7/udplite.7 | 18 | ||||
| -rw-r--r-- | man7/unix.7 | 60 | ||||
| -rw-r--r-- | man7/uri.7 | 2 | ||||
| -rw-r--r-- | man7/vdso.7 | 46 |
24 files changed, 387 insertions, 387 deletions
diff --git a/man7/environ.7 b/man7/environ.7 index 9d12a883c7..69b5878d77 100644 --- a/man7/environ.7 +++ b/man7/environ.7 @@ -58,7 +58,7 @@ When a child process is created via it inherits a .I copy of its parent's environment. - +.PP By convention the strings in .I environ have the form "\fIname\fP\fB=\fP\fIvalue\fP". @@ -137,7 +137,7 @@ or by the .I setenv command if you use .BR csh (1). - +.PP The initial environment of the shell is populated in various ways, such as definitions from .IR /etc/environment @@ -150,17 +150,17 @@ In addition, various shell initialization scripts, such as the system-wide script and per-user initializations script may include commands that add variables to the shell's environment; see the manual page of your preferred shell for details. - +.PP Bourne-style shells support the syntax - +.PP NAME=value command - +.PP to create an environment variable definition only in the scope of the process that executes .IR command . Multiple variable definitions, separated by white space, may precede .IR command . - +.PP Arguments may also be placed in the environment at the point of an .BR exec (3). @@ -170,7 +170,7 @@ A C program can manipulate its environment using the functions .BR setenv (3), and .BR unsetenv (3). - +.PP Note that the behavior of many programs and library routines is influenced by the presence or value of certain environment variables. Examples include the following: @@ -246,7 +246,7 @@ 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 . - +.PP There is also the risk of name space pollution. Programs like .I make diff --git a/man7/epoll.7 b/man7/epoll.7 index fcfdeb4e5b..b8ecdef267 100644 --- a/man7/epoll.7 +++ b/man7/epoll.7 @@ -123,7 +123,7 @@ does not consume the whole buffer data, the call to done in step .B 5 might block indefinitely. - +.PP An application that employs the .B EPOLLET flag should use nonblocking file descriptors to avoid having a blocking @@ -156,7 +156,7 @@ is simply a faster .BR poll (2), and can be used wherever the latter is used since it shares the same semantics. - +.PP Since even with edge-triggered .BR epoll , multiple events can be generated upon receipt of multiple chunks of data, @@ -185,7 +185,7 @@ it is necessary to use the .BR epoll_ctl (2) .B EPOLLWAKEUP flag. - +.PP When the .B EPOLLWAKEUP flag is set in the @@ -255,7 +255,7 @@ it will continue to or .BR write (2) from where it stopped before. - +.PP .in +4n .nf #define MAX_EVENTS 10 @@ -308,7 +308,7 @@ for (;;) { } .fi .in - +.PP When used as an edge-triggered interface, for performance reasons, it is possible to add the file descriptor inside the .B epoll diff --git a/man7/feature_test_macros.7 b/man7/feature_test_macros.7 index 0766f8bdda..6add2f8be7 100644 --- a/man7/feature_test_macros.7 +++ b/man7/feature_test_macros.7 @@ -28,7 +28,7 @@ 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. - +.PP .B NOTE: In order to be effective, a feature test macro .IR "must be defined before including any header files" . @@ -36,12 +36,12 @@ This can be done either in the compilation command .RI ( "cc \-DMACRO=value" ) or by defining the macro within the source code before including any headers. - +.PP Some feature test macros are useful for creating portable applications, by preventing nonstandard definitions from being exposed. Other macros can be used to expose nonstandard definitions that are not exposed by default. - +.PP The precise effects of each of the feature test macros described below can be ascertained by inspecting the .I <features.h> @@ -108,7 +108,7 @@ Note that, as described below, so that it may not always be necessary to explicitly specify the feature test macro(s) shown in the SYNOPSIS. - +.PP In a few cases, manual pages use a shorthand for expressing the feature test macro requirements (this example from .BR readahead (2)): @@ -130,7 +130,7 @@ The paragraphs below explain how feature test macros are handled in Linux glibc 2.\fIx\fP, .I x > 0. - +.PP First, though a summary of a few details for the impatient: .IP * 3 The macros that you most likely need to use in modern source code are @@ -199,7 +199,7 @@ it is implicit that the following has the same effect: .\" The details in glibc 2.0 are simpler, but combining a .\" a description of them with the details in later glibc versions .\" would make for a complicated description. - +.PP Linux glibc understands the following feature test macros: .TP 8 .B __STRICT_ANSI__ @@ -246,7 +246,7 @@ to the POSIX.1-2008 base specification (excluding the XSI extension). Defining this obsolete macro with any value is equivalent to defining .B _POSIX_C_SOURCE with the value 1. - +.IP Since this macro is obsolete, its usage is generally not documented when discussing feature test macro requirements in the man pages. @@ -328,7 +328,7 @@ with a value of 500 or more also produces the same effect as defining Use of .BR _XOPEN_SOURCE_EXTENDED in new source code should be avoided. - +.IP Since defining .B _XOPEN_SOURCE with a value of 500 or more has the same effect as defining @@ -338,18 +338,18 @@ SYNOPSIS in man pages. .TP .BR _ISOC99_SOURCE " (since glibc 2.1.3)" Exposes declarations consistent with the ISO C99 standard. - +.IP Earlier glibc 2.1.x versions recognized an equivalent macro named .B _ISOC9X_SOURCE (because the C99 standard had not then been finalized). Although the use of this macro is obsolete, glibc continues to recognize it for backward compatibility. - +.IP Defining .B _ISOC99_SOURCE also exposes ISO C (1990) Amendment 1 ("C95") definitions. (The primary change in C95 was support for international character sets.) - +.IP Invoking the C compiler with the option .IR \-std=c99 produces the same effects as defining this macro. @@ -358,7 +358,7 @@ produces the same effects as defining this macro. Exposes declarations consistent with the ISO C11 standard. Defining this macro also enables C99 and C95 features (like .BR _ISOC99_SOURCE ). - +.IP Invoking the C compiler with the option .IR \-std=c11 produces the same effects as defining this macro. @@ -415,14 +415,14 @@ This is useful for performing I/O on large files (> 2 Gigabytes) on 32-bit systems. (Defining this macro permits correctly written programs to use large files with only a recompilation being required.) - +.IP 64-bit systems naturally permit file sizes greater than 2 Gigabytes, and on those systems this macro has no effect. .TP .BR _BSD_SOURCE " (deprecated since glibc 2.20)" Defining this macro with any value causes header files to expose BSD-derived definitions. - +.IP In glibc versions up to and including 2.18, defining this macro also causes BSD definitions to be preferred in some situations where standards conflict, unless one or more of @@ -437,7 +437,7 @@ is defined, in which case BSD definitions are disfavored. Since glibc 2.19, .B _BSD_SOURCE no longer causes BSD definitions to be preferred in case of conflicts. - +.IP Since glibc 2.20, this macro is deprecated. .\" commit c941736c92fa3a319221f65f6755659b2a5e0a20 .\" commit 498afc54dfee41d33ba519f496e96480badace8e @@ -466,7 +466,7 @@ Defining this macro with any value causes header files to expose System V-derived definitions. (SVID == System V Interface Definition; see .BR standards (7).) - +.IP Since glibc 2.20, this macro is deprecated in the same fashion as .BR _BSD_SOURCE . .TP @@ -481,12 +481,12 @@ Defining .B _DEFAULT_SOURCE without defining other individual macros or invoking the compiler in one of its "standard" modes has no effect. - +.IP The "default" definitions comprise those required by POSIX.1-2008 and ISO C99, as well as various definitions originally derived from BSD and System V. On glibc 2.19 and earlier, these defaults were approximately equivalent to explicitly defining the following: - +.IP cc \-D_BSD_SOURCE \-D_SVID_SOURCE \-D_POSIX_C_SOURCE=200809 .TP .BR _ATFILE_SOURCE " (since glibc 2.4)" @@ -516,7 +516,7 @@ with the value 700 (600 in glibc versions before 2.10; 500 in glibc versions before 2.2). In addition, various GNU-specific extensions are also exposed. - +.IP Since glibc 2.19, defining .BR _GNU_SOURCE also has the effect of implicitly defining @@ -539,7 +539,7 @@ multithreaded code. (Some C libraries may still require this.) In glibc, this macro also exposed definitions of certain reentrant functions. - +.IP However, glibc has been thread-safe by default for many years; since glibc 2.3, the only effect of defining .BR _REENTRANT @@ -547,7 +547,7 @@ has been to enable one or two of the same declarations that are also enabled by defining .BR _POSIX_C_SOURCE with a value of 199606L or greater. - +.IP .B _REENTRANT is now obsolete. In glibc 2.25 and later, defining @@ -566,7 +566,7 @@ or then defining .B _REENTRANT has no effect. - +.IP This macro is automatically defined if one compiles with .IR "cc\ \-pthread" . .TP @@ -607,7 +607,7 @@ argument when the specified flags include .BR O_CREAT . Not all problems are detected, just some common cases. .\" Look for __USE_FORTIFY_LEVEL in the header files - +.IP If .B _FORTIFY_SOURCE is set to 1, with compiler optimization level 1 @@ -630,13 +630,13 @@ some conforming programs might fail. .\" *** %n in writable segment detected *** .\" Aborted (core dumped) .\" - +.IP Some of the checks can be performed at compile time (via macros logic implemented in header files), and result in compiler warnings; other checks take place at run time, and result in a run-time error if the check fails. - +.IP Use of this macro requires compiler support, available with .BR gcc (1) since version 4.0. @@ -675,7 +675,7 @@ is explicitly defined, then and .BR _DEFAULT_SOURCE are not defined by default. - +.PP If .B _POSIX_SOURCE and @@ -738,13 +738,13 @@ POSIX.1 specifies .BR _POSIX_SOURCE , and .BR _XOPEN_SOURCE . - +.PP .B _XOPEN_SOURCE_EXTENDED was specified by XPG4v2 (aka SUSv1), but is not present in SUSv2 and later. .B _FILE_OFFSET_BITS is not specified by any standard, but is employed on some other implementations. - +.PP .BR _BSD_SOURCE , .BR _SVID_SOURCE , .BR _DEFAULT_SOURCE , @@ -762,7 +762,7 @@ 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 employ feature test macros. - +.PP According to which of the above feature test macros are defined, .I <features.h> internally defines various other macros that are checked by @@ -891,9 +891,9 @@ main(int argc, char *argv[]) .SH SEE ALSO .BR libc (7), .BR standards (7) - +.PP The section "Feature Test Macros" under .IR "info libc" . .\" But beware: the info libc document is out of date (Jul 07, mtk) - +.PP .I /usr/include/features.h diff --git a/man7/futex.7 b/man7/futex.7 index 8312c6b360..5d3e09c640 100644 --- a/man7/futex.7 +++ b/man7/futex.7 @@ -119,7 +119,7 @@ primitives; it is by no means the only one. .BR set_robust_list (2), .BR set_tid_address (2), .BR pthreads (7) - +.PP .IR "Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux" (proceedings of the Ottawa Linux Symposium 2002), futex example library, futex-*.tar.bz2 @@ -75,9 +75,9 @@ For more information on sockets, see .PP An IP socket is created using .BR socket (2): - +.PP socket(AF_INET, socket_type, protocol); - +.PP Valid socket types are .B SOCK_STREAM to open a @@ -126,7 +126,7 @@ is called on an unbound socket, the socket is automatically bound to a random free port or to a usable shared port with the local address set to .BR INADDR_ANY . - +.PP A TCP local socket address that has been bound is unavailable for some time after closing, unless the .B SO_REUSEADDR @@ -201,7 +201,7 @@ or set using the .BR inet_makeaddr (3) library functions or directly with the name resolver (see .BR gethostbyname (3)). - +.PP IPv4 addresses are divided into unicast, broadcast, and multicast addresses. Unicast addresses specify a single interface of a host, @@ -213,7 +213,7 @@ socket flag is set. In the current implementation, connection-oriented sockets are allowed to use only unicast addresses. .\" Leave a loophole for XTP @) - +.PP Note that the address and the port are always stored in network byte order. In particular, this means that you need to call @@ -221,7 +221,7 @@ In particular, this means that you need to call on the number that is assigned to a port. All address/port manipulation functions in the standard library work in network byte order. - +.PP There are several special addresses: .B INADDR_LOOPBACK (127.0.0.1) @@ -243,7 +243,7 @@ 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. - +.PP When an invalid socket option is specified, .BR getsockopt (2) and @@ -302,7 +302,7 @@ field. (The kernel determines which structure is being passed based on the size passed in .IR optlen .) - +.IP .B IP_ADD_MEMBERSHIP is valid only for .BR setsockopt (2). @@ -466,7 +466,7 @@ refer to RFC 3376. .\" Precisely: 2.1.124 Retrieve the current known path MTU of the current socket. Returns an integer. - +.IP .B IP_MTU is valid only for .BR getsockopt (2) @@ -492,7 +492,7 @@ datagrams that are bigger than the known path MTU. .B IP_PMTUDISC_WANT will fragment a datagram if needed according to the path MTU, or will set the don't-fragment flag otherwise. - +.IP The system-wide default can be toggled between .B IP_PMTUDISC_WANT and @@ -510,7 +510,7 @@ IP_PMTUDISC_DONT:Never do Path MTU Discovery. IP_PMTUDISC_DO:Always do Path MTU Discovery. IP_PMTUDISC_PROBE:Set DF but ignore Path MTU. .TE - +.sp 1 When PMTU discovery is enabled, the kernel automatically keeps track of the path MTU per destination host. When it is connected to a specific peer with @@ -526,16 +526,16 @@ the new 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. - +.IP While MTU discovery is in progress, initial packets from datagram sockets may be dropped. Applications using UDP should be aware of this and not take it into account for their packet retransmit strategy. - +.IP 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 path MTU. - +.IP To get an initial estimate of the path MTU, connect a datagram socket to the destination address using .BR connect (2) @@ -544,7 +544,7 @@ and retrieve the MTU by calling with the .B IP_MTU option. - +.IP It is possible to implement RFC 4821 MTU probing with .B SOCK_DGRAM or @@ -612,7 +612,7 @@ Argument is an integer. If enabled (argument is nonzero), the reassembly of outgoing packets is disabled in the netfilter layer. The argument is an integer. - +.IP This option is valid only for .B SOCK_RAW sockets. @@ -984,21 +984,21 @@ meaning that the option is disabled. was controlled at compile time by the .B CONFIG_IP_ALWAYS_DEFRAG option; this option is not present in 2.4.x and later] - +.IP When this boolean flag 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 reassembled (defragmented) before being processed, even if they are about to be forwarded. - +.IP Enable only if running either a firewall that is the sole link to your network or a transparent proxy; never ever use it for a normal router or host. Otherwise, fragmented communication can be disturbed if the fragments travel over different links. Defragmentation also has a large memory and CPU time cost. - +.IP This is automagically turned on when masquerading or transparent proxying are configured. .\" @@ -1234,7 +1234,7 @@ are Linux-specific. .\" IP_PASSSEC is Linux-specific .\" IP_XFRM_POLICY is Linux-specific .\" IP_IPSEC_POLICY is a nonstandard extension, also present on some BSDs - +.PP Be very careful with the .B SO_BROADCAST option \- it is not privileged in Linux. diff --git a/man7/ipv6.7 b/man7/ipv6.7 index fe6385fd94..6965696033 100644 --- a/man7/ipv6.7 +++ b/man7/ipv6.7 @@ -222,7 +222,7 @@ Argument is a pointer to a Retrieve the current known path MTU of the current socket. Valid only when the socket has been connected. Returns an integer. - +.IP .BR setsockopt (): Set the MTU to be used for the socket. The MTU is limited by the device @@ -337,13 +337,13 @@ If this flag is set to true (nonzero), then the socket is restricted to sending and receiving IPv6 packets only. In this case, an IPv4 and an IPv6 application can bind to a single port at the same time. - +.IP If this flag is set to false (zero), then the socket can be used to send and receive packets to and from an IPv6 address or an IPv4-mapped IPv6 address. - +.IP The argument is a pointer to a boolean value in an integer. - +.IP The default value for this flag is defined by the contents of the file .IR /proc/sys/net/ipv6/bindv6only . The default value for that file is 0 (false). diff --git a/man7/locale.7 b/man7/locale.7 index c47030ee29..d9cc420ace 100644 --- a/man7/locale.7 +++ b/man7/locale.7 @@ -316,7 +316,7 @@ of the GNU C library. These extensions are designed to address the problem that the traditional locale APIs do not mix well with multithreaded applications and with applications that must deal with multiple locales. - +.PP The extensions take the form of new functions for creating and manipulating locale objects .RB ( newlocale (3), diff --git a/man7/man-pages.7 b/man7/man-pages.7 index aafb5785c2..2870c2db8d 100644 --- a/man7/man-pages.7 +++ b/man7/man-pages.7 @@ -102,7 +102,7 @@ Please limit source code line length to no more than about 75 characters wherever possible. This helps avoid line-wrapping in some mail clients when patches are submitted inline. - +.PP New sentences should be started on new lines. This makes it easier to see the effect of patches, which often operate at the level of individual sentences. @@ -138,11 +138,11 @@ Dates should be written in the form YYYY-MM-DD. .TP .I source The source of the command, function, or system call. - +.IP For those few \fIman-pages\fP pages in Sections 1 and 8, probably you just want to write .IR GNU . - +.IP For system calls, just write .IR "Linux" . (An earlier practice was to write the version number @@ -150,15 +150,15 @@ of the kernel from which the manual page was being written/checked. However, this was never done consistently, and so was probably worse than including no version number. Henceforth, avoid including a version number.) - +.IP For library calls that are part of glibc or one of the other common GNU libraries, just use .IR "GNU C Library" ", " GNU , or an empty string. - +.IP For Section 4 pages, use .IR "Linux" . - +.IP In cases of doubt, just write .IR Linux ", or " GNU . .TP @@ -214,13 +214,13 @@ be especially useful for pages in Sections 4 and 5). However, before doing this, consider whether you could use the traditional headings, with some subsections (\fI.SS\fP) within those sections. - +.PP The following list elaborates on the contents of each of the above sections. .TP 14 .B NAME The name of this manual page. - +.IP See .BR man (7) for important details of the line(s) that should follow the @@ -232,7 +232,7 @@ dictates otherwise. .TP .B SYNOPSIS A brief summary of the command or function's interface. - +.IP 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 @@ -242,7 +242,7 @@ separate choices, and ellipses (\&...) can be repeated. For functions, it shows any required data declarations or .B #include directives, followed by the function declaration. - +.IP Where a feature test macro must be defined in order to obtain the declaration of a function (or a variable) from a header file, then the SYNOPSIS should indicate this, as described in @@ -251,12 +251,12 @@ then the SYNOPSIS should indicate this, as described in .TP .B CONFIGURATION Configuration details for a device. - +.IP This section normally appears only in Section 4 pages. .TP .B DESCRIPTION An explanation of what the program, function, or format does. - +.IP Discuss how it interacts with files and standard input, and what it produces on standard output or standard error. Omit internals and implementation details unless they're critical for @@ -271,7 +271,7 @@ section. .\" section (and just place an overview in the .\" .B DESCRIPTION .\" section). - +.IP When describing new behavior or new flags for a system call or library function, be careful to note the kernel or C library version @@ -292,7 +292,7 @@ who are constrained to using older kernel or C library versions .B OPTIONS A description of the command-line options accepted by a program and how they change its behavior. - +.IP This section should appear only for Section 1 and 8 manual pages. .\" .TP .\" .B USAGE @@ -301,7 +301,7 @@ This section should appear only for Section 1 and 8 manual pages. .B EXIT STATUS A list of the possible exit status values of a program and the conditions that cause these values to be returned. - +.IP This section should appear only for Section 1 and 8 manual pages. .TP .B RETURN VALUE @@ -315,7 +315,7 @@ values that may be placed in .I errno in the event of an error, along with information about the cause of the errors. - +.IP Where several different conditions produce the same error, the preferred approach is to create separate list entries (with duplicate error names) for each of the conditions. @@ -323,7 +323,7 @@ This makes the separate conditions clear, may make the list easier to read, and allows metainformation (e.g., kernel version number where the condition first became applicable) to be more easily marked for each condition. - +.IP .IR "The error list should be in alphabetical order" . .TP .B ENVIRONMENT @@ -334,7 +334,7 @@ and how they affect it. A list of the files the program or function uses, such as configuration files, startup files, and files the program directly operates on. - +.IP Give the full pathname of these files, and use the installation process to modify the directory part to match user preferences. For many programs, the default installation location is in @@ -378,7 +378,7 @@ for further details. A brief summary of the Linux kernel or glibc versions where a system call or library function appeared, or changed significantly in its operation. - +.IP As a general rule, every new interface should include a VERSIONS section in its manual page. Unfortunately, @@ -391,7 +391,7 @@ interfaces that have been added in Linux 2.4 or later (i.e., changes since kernel 2.2), and library functions that have been added to glibc since version 2.1 (i.e., changes since glibc 2.0). - +.IP The .BR syscalls (2) manual page also provides information about kernel versions @@ -400,11 +400,11 @@ in which various system calls first appeared. .B CONFORMING TO A description of any standards or conventions that relate to the function or command described by the manual page. - +.IP The preferred terms to use for the various standards are listed as headings in .BR standards (7). - +.IP For a page in Section 2 or 3, this section should note the POSIX.1 version(s) that the call conforms to, @@ -413,21 +413,21 @@ and also whether the call is specified in C99. or the SVr4 and 4.xBSD implementation standards, unless the call was specified in those standards, but isn't in the current version of POSIX.1.) - +.IP If the call is not governed by any standards but commonly exists on other systems, note them. If the call is Linux-specific, note this. - +.IP If this section consists of just a list of standards (which it commonly does), terminate the list with a period (\(aq.\(aq). .TP .B NOTES Miscellaneous notes. - +.IP For Section 2 and 3 man pages you may find it useful to include subsections (\fBSS\fP) named \fILinux Notes\fP and \fIGlibc Notes\fP. - +.IP In Section 2, use the heading .I "C library/kernel differences" to mark off notes that describe the differences (if any) between @@ -441,13 +441,13 @@ and other questionable activities. .B EXAMPLE One or more examples demonstrating how this function, file or command is used. - +.IP For details on writing example programs, see \fIExample Programs\fP below. .TP .B AUTHORS A list of authors of the documentation or program. - +.IP \fBUse of an AUTHORS section is strongly discouraged\fP. Generally, it is better not to clutter every page with a list of (over time potentially numerous) authors; @@ -459,7 +459,7 @@ an address for reporting bugs, place this under the BUGS section. .B SEE ALSO A comma-separated list of related man pages, possibly followed by other related pages or documents. - +.IP The list should be ordered by section number and then alphabetically by name. Do not terminate this list with a period. @@ -474,7 +474,7 @@ and directives. Hyphenation of individual page names can be prevented by preceding words with the string "\\%". - +.IP Given the distributed, autonomous nature of FOSS projects and their documentation, it is sometimes necessary\(emand in many cases desirable\(emthat the SEE ALSO section includes references to @@ -497,7 +497,7 @@ pronoun is acceptable. For manual pages that describe a command (typically in Sections 1 and 8), the arguments are always specified using italics, .IR "even in the SYNOPSIS section" . - +.PP The name of the command, and its options, should always be formatted in bold. .\" @@ -510,7 +510,7 @@ where the rest of the function is specified in bold: .BI " int myfunction(int " argc ", char **" argv ); .PP Variable names should, like argument names, be specified in italics. - +.PP Any reference to the subject of the current manual page should be written with the name in bold followed by a pair of parentheses in Roman (normal) font. @@ -546,7 +546,7 @@ When enumerating a list of error codes, the codes are in bold (this list usually uses the .B \&.TP macro). - +.PP Complete commands should, if long, be written as an indented line on their own, with a blank line before and after the command, for example @@ -569,7 +569,7 @@ Expressions, if not written on a separate indented line, should be specified in italics. Again, the use of nonbreaking spaces may be appropriate if the expression is inlined with normal text. - +.PP When showing example shell sessions, user input should be formatted in bold, for example .PP .in +4n @@ -596,7 +596,7 @@ The preferred way to write this in the source file is: (Including the section number in cross references lets tools like .BR man2html (1) create properly hyperlinked pages.) - +.PP Control characters should be written in bold face, with no quotes; for example, .BR ^X . @@ -606,7 +606,7 @@ Starting with release 2.59, follows American spelling conventions (previously, there was a random mix of British and American spellings); please write all new pages and patches according to these conventions. - +.PP Aside from the well-known spelling differences, there are a few other subtleties to watch for: .IP * 3 @@ -627,7 +627,7 @@ capitalize the first word in the heading, but otherwise use lowercase, except where English usage (e.g., proper nouns) or programming language requirements (e.g., identifier names) dictate otherwise. For example: - +.PP .SS Unicode under Linux .\" .SS Indentation of structure definitions, shell session logs, and so on @@ -730,7 +730,7 @@ Unixes UNIX systems Use the correct spelling and case for trademarks. The following is a list of the correct spellings of various relevant trademarks that are sometimes misspelled: - +.PP DG/UX HP-UX UNIX @@ -747,10 +747,10 @@ is the .IR "null byte", a byte with the value 0, represented in C via the character constant .IR \(aq\e0\(aq . - +.PP The preferred term for the pointer is "null pointer" or simply "NULL"; avoid writing "NULL pointer". - +.PP The preferred term for the byte is "null byte". Avoid writing "NUL", since it is too easily confused with "NULL". Avoid also the terms "zero byte" and "null character". @@ -766,17 +766,17 @@ macro pair .BR groff_man (7)). This produces proper hyperlinks that can be used in a web browser, when rendering a page with, say: - +.PP BROWSER=firefox man -H pagename .SS Use of e.g., i.e., etc., a.k.a., and similar In general, the use of abbreviations such as "e.g.", "i.e.", "etc.", "a.k.a." should be avoided, in favor of suitable full wordings ("for example", "that is", "and so on", "also known as"). - +.PP The only place where such abbreviations may be acceptable is in .I short parenthetical asides (e.g., like this one). - +.PP Always include periods in such abbreviations, as shown here. In addition, "e.g." and "i.e." should always be followed by a comma. .SS Em-dashes @@ -790,7 +790,7 @@ surrounding spaces. .SS Hyphenation of attributive compounds Compound terms should be hyphenated when used attributively (i.e., to qualify a following noun). Some examples: - +.PP 32-bit value command-line argument floating-point number @@ -803,7 +803,7 @@ after prefixes such as "multi", "non", "pre", "re", "sub", and so on. Manual pages should generally follow this rule when these prefixes are used in natural English constructions with simple suffixes. The following list gives some examples of the preferred forms: - +.PP interprocess multithreaded multiprocess @@ -824,16 +824,16 @@ The following list gives some examples of the preferred forms: subcomponent subdirectory subsystem - +.PP Hyphens should be retained when the prefixes are used in nonstandard English words, with trademarks, proper nouns, acronyms, or compound terms. Some examples: - +.PP non-ASCII non-English non-NULL non-real-time - +.PP Finally, note that "re-create" and "recreate" are two different verbs, and the former is probably what you want. .SS Real minus character @@ -841,16 +841,16 @@ Where a real minus character is required (e.g., for numbers such as \-1, or when writing options that have a leading dash, such as in .IR "ls\ \-l"), use the following form in the man page source: - +.PP \\\- - +.PP This guideline applies also to code examples. .SS Character constants To produce single quotes that render well in both ASCII and UTF-8, use the following form for character constants in the man page source: - +.PP \\(aqC\\(aq - +.PP where .I C is the quoted character. @@ -887,16 +887,16 @@ Ritchie style, with 4-space indents. (Avoid the use of TAB characters in source code!) The following command can be used to format your source code to something close to the preferred style: - +.IP indent \-npro \-kr \-i4 \-ts4 \-sob \-l72 \-ss \-nut \-psl prog.c .IP * For consistency, all example programs should terminate using either of: - +.IP exit(EXIT_SUCCESS); exit(EXIT_FAILURE); - +.IP Avoid using the following forms to terminate a program: - +.IP exit(0); exit(1); return n; @@ -906,9 +906,9 @@ program source code, mark off the source code with a subsection heading .IR "Program source" , as in: - +.IP .SS Program source - +.IP Always do this if the explanatory text includes a shell session log. .PP If you include a shell session log demonstrating the use of a program diff --git a/man7/man.7 b/man7/man.7 index 2581228d77..5eaa7d457e 100644 --- a/man7/man.7 +++ b/man7/man.7 @@ -103,7 +103,7 @@ followed by the heading name. .\" on the same line as .\" .BR \&.SH , .\" then place the heading in double quotes. - +.PP The only mandatory heading is NAME, which should be the first section and be followed on the next line by a one-line description of the program: .RS diff --git a/man7/math_error.7 b/man7/math_error.7 index 5e457f64b8..fced6e0979 100644 --- a/man7/math_error.7 +++ b/man7/math_error.7 @@ -50,7 +50,7 @@ and as outlined below) described in .BR fenv (3). - +.PP A portable program that needs to check for an error from a mathematical function should set .I errno @@ -63,7 +63,7 @@ feclearexcept(FE_ALL_EXCEPT); .fi .in before calling a mathematical function. - +.PP Upon return from the mathematical function, if .I errno is nonzero, or the following call (see @@ -87,7 +87,7 @@ fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | .\" FE_INEXACT = 0x20 .\" }; then an error occurred in the mathematical function. - +.PP The error conditions that can occur for mathematical functions are described below. .SS Domain error @@ -137,7 +137,7 @@ occurs when the magnitude of the function result means that it cannot be represented in the result type of the function. The return value of the function depends on whether the range error was an overflow or an underflow. - +.PP A floating result .I overflows if the result is finite, @@ -159,7 +159,7 @@ is set to and an "overflow" .RB ( FE_OVERFLOW ) floating-point exception is raised. - +.PP A floating result .I underflows if the result is too small to be represented in the result type. @@ -174,7 +174,7 @@ may be set to and an "overflow" .RB ( FE_UNDERFLOW ) floating-point exception may be raised. - +.PP Some functions deliver a range error if the supplied argument value, or the correct function result, would be .IR subnormal . @@ -206,7 +206,7 @@ A few functions set but don't raise an exception. A very few functions do neither. See the individual manual pages for details. - +.PP To avoid the complexities of using .I errno and @@ -237,7 +237,7 @@ mathematical functions (i.e., those declared by .IR <complex.h> ), which in general are not required to return errors by C99 and POSIX.1. - +.PP The .BR gcc (1) .I "-fno-math-errno" @@ -262,5 +262,5 @@ An error can still be tested for using .BR isgreater (3), .BR matherr (3), .BR nan (3) - +.PP .I "info libc" diff --git a/man7/netdevice.7 b/man7/netdevice.7 index a7b47e3c0c..eff29a43ee 100644 --- a/man7/netdevice.7 +++ b/man7/netdevice.7 @@ -25,14 +25,14 @@ netdevice \- low-level access to Linux network devices .SH DESCRIPTION This man page describes the sockets interface which is used to configure network devices. - +.PP 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. Most of them pass an .I ifreq structure: - +.PP .in +4n .nf struct ifreq { @@ -55,7 +55,7 @@ struct ifreq { }; .fi .in - +.PP Normally, the user specifies which device to affect by setting .I ifr_name to the name of the interface. @@ -211,7 +211,7 @@ This is a privileged operation. Get or set the interface's hardware parameters using .IR ifr_map . Setting the parameters is a privileged operation. - +.IP .in +4n .nf struct ifmap { @@ -224,7 +224,7 @@ struct ifmap { }; .fi .in - +.IP The interpretation of the ifmap structure depends on the device driver and the architecture. .TP @@ -260,7 +260,7 @@ means only addresses of the Unlike the others, this ioctl passes an .I ifconf structure: - +.IP .in +4n .nf struct ifconf { @@ -272,7 +272,7 @@ struct ifconf { }; .fi .in - +.IP If .I ifc_req is NULL, @@ -296,7 +296,7 @@ will receive the interface name, and the address. The actual number of bytes transferred is returned in .IR ifc_len . - +.IP If the size specified by .I ifc_len is insufficient to store all the addresses, @@ -312,7 +312,7 @@ set to NULL, or to retry the call with a bigger buffer whenever upon return differs by less than .I sizeof(struct ifreq) from its original value. - +.IP If an error occurs accessing the .I ifconf or diff --git a/man7/netlink.7 b/man7/netlink.7 index a13987cac6..973ab6f049 100644 --- a/man7/netlink.7 +++ b/man7/netlink.7 @@ -28,7 +28,7 @@ The internal kernel interface is not documented in this manual page. There is also an obsolete netlink interface via netlink character devices; this interface is not documented here and is provided only for backward compatibility. - +.PP Netlink is a datagram-oriented service. Both .B SOCK_RAW @@ -38,7 +38,7 @@ are valid values for .IR socket_type . However, the netlink protocol does not distinguish between datagram and raw sockets. - +.PP .I netlink_family selects the kernel module or netlink group to communicate with. The currently assigned netlink families are: @@ -152,7 +152,7 @@ macros. See .BR netlink (3) for further information. - +.PP In multipart messages (multiple .I nlmsghdr headers with associated payload in one byte stream) the first and all @@ -160,11 +160,11 @@ following headers have the .B NLM_F_MULTI flag set, except for the last header which has the type .BR NLMSG_DONE . - +.PP After each .I nlmsghdr the payload follows. - +.PP .in +4n .nf struct nlmsghdr { @@ -176,7 +176,7 @@ struct nlmsghdr { }; .fi .in - +.PP .I nlmsg_type can be one of the standard message types: .B NLMSG_NOOP @@ -187,7 +187,7 @@ message signals an error and the payload contains an structure, .B NLMSG_DONE message terminates a multipart message. - +.PP .in +4n .nf struct nlmsgerr { @@ -196,7 +196,7 @@ struct nlmsgerr { }; .fi .in - +.PP A netlink family usually specifies more message types, see the appropriate manual pages for that, for example, .BR rtnetlink (7) @@ -267,14 +267,14 @@ socket. See the .B ADDRESS FORMATS section for further information. - +.PP Both .I nlmsg_seq and .I nlmsg_pid .\" FIXME Explain more about nlmsg_seq and nlmsg_pid. are opaque to netlink core. - +.PP 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 @@ -292,7 +292,7 @@ The kernel tries to send an .B NLMSG_ERROR message for every failed packet. A user process should follow this convention too. - +.PP However, reliable transmissions from kernel to user are impossible in any case. The kernel can't send a netlink message if the socket buffer is full: @@ -313,7 +313,7 @@ can be either unicast (only sent to one peer) or sent to netlink multicast groups .RI ( nl_groups not equal 0). - +.PP .in +4n .nf struct sockaddr_nl { @@ -324,7 +324,7 @@ struct sockaddr_nl { }; .fi .in - +.PP .I nl_pid is the unicast address of netlink socket. It's always 0 if the destination is in the kernel. @@ -353,7 +353,7 @@ The kernel assigns the process ID to the first netlink socket the process opens and assigns a unique .I nl_pid to every netlink socket that the process subsequently creates. - +.PP .I nl_groups is a bit mask with every bit representing a netlink group number. Each netlink family has a set of 32 multicast groups. @@ -390,7 +390,7 @@ and .BR NETLINK_SELINUX groups allow other users to receive messages. No groups allow other users to send messages. - +.PP .SS Socket options To set or get a netlink socket option, call .BR getsockopt (2) @@ -470,7 +470,7 @@ The netlink message header is still included, so the user can guess from the sequence number which message triggered the acknowledgment. .SH VERSIONS The socket interface to netlink first appeared Linux 2.2. - +.PP Linux 2.0 supported a more primitive device-based netlink interface (which is still available as a compatibility option). This obsolete interface is not described here. @@ -490,7 +490,7 @@ netlink socket which will listen to the (network interface create/delete/up/down events) and .B RTMGRP_IPV4_IFADDR (IPv4 addresses add/delete events) multicast groups. - +.PP .in +4n .nf struct sockaddr_nl sa; @@ -503,12 +503,12 @@ fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_ROUTE); bind(fd, (struct sockaddr *) &sa, sizeof(sa)); .fi .in - +.PP The next example demonstrates how to send a netlink message to the kernel (pid 0). Note that the application must take care of message sequence numbers in order to reliably track acknowledgements. - +.PP .in +4n .nf struct nlmsghdr *nh; /* The nlmsghdr with payload to send */ @@ -527,9 +527,9 @@ nh\->nlmsg_flags |= NLM_F_ACK; sendmsg(fd, &msg, 0); .fi .in - +.PP And the last example is about reading netlink message. - +.PP .in +4n .nf int len; @@ -564,13 +564,13 @@ for (nh = (struct nlmsghdr *) buf; NLMSG_OK (nh, len); .BR capabilities (7), .BR rtnetlink (7), .BR sock_diag (7) - +.PP .UR ftp://ftp.inr.ac.ru\:/ip\-routing\:/iproute2* information about libnetlink .UE - +.PP .UR http://www.infradead.org\:/~tgr\:/libnl/ information about libnl .UE - +.PP RFC 3549 "Linux Netlink as an IP Services Protocol" diff --git a/man7/packet.7 b/man7/packet.7 index 15428a674a..adbd4dbef5 100644 --- a/man7/packet.7 +++ b/man7/packet.7 @@ -27,7 +27,7 @@ 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 on top of the physical layer. - +.PP The .I socket_type is either @@ -49,11 +49,11 @@ is set to 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. - +.PP In order to create a packet socket, a process must have the .B CAP_NET_RAW capability in the user namespace that governs its network namespace. - +.PP .B SOCK_RAW packets are passed to and from the device driver without any changes in the packet data. @@ -71,7 +71,7 @@ Some device drivers always add other headers. is similar to but not compatible with the obsolete .B AF_INET/SOCK_PACKET of Linux 2.0. - +.PP .B SOCK_DGRAM operates on a slightly higher level. The physical header is removed before the packet is passed to the user. @@ -81,7 +81,7 @@ packet socket get a suitable physical-layer header based on the information in the .I sockaddr_ll destination address before they are queued. - +.PP By default, all packets of the specified protocol type are passed to a packet socket. To get packets only from a specific interface use @@ -96,11 +96,11 @@ Fields used for binding are .IR sll_protocol , and .IR sll_ifindex . - +.PP The .BR connect (2) operation is not supported on packet sockets. - +.PP When the .B MSG_TRUNC flag is passed to @@ -114,7 +114,7 @@ even when it is longer than the buffer. The .I sockaddr_ll structure is a device-independent physical-layer address. - +.PP .in +4n .nf struct sockaddr_ll { @@ -128,7 +128,7 @@ struct sockaddr_ll { }; .fi .in - +.PP The fields of this structure are as follows: .IP * 3 .I sll_protocol @@ -203,7 +203,7 @@ drops it. They both expect a .I packet_mreq structure as argument: - +.IP .in +4n .nf struct packet_mreq { @@ -214,7 +214,7 @@ struct packet_mreq { }; .fi .in - +.IP .I mr_ifindex contains the interface index for the interface whose status should be changed. @@ -233,7 +233,7 @@ and .B PACKET_MR_ALLMULTI sets the socket up to receive all multicast packets arriving at the interface. - +.IP In addition, the traditional ioctls .BR SIOCSIFFLAGS , .BR SIOCADDMULTI , @@ -249,7 +249,7 @@ control field. The structure can be read with .BR cmsg (3). It is defined as - +.IP .in +4n .nf struct tpacket_auxdata { @@ -285,7 +285,7 @@ must have the same protocol, device settings, fanout mode and flags (see below). Packet sockets can leave a fanout group only by closing the socket. The group is deleted when the last socket is closed. - +.IP Fanout supports multiple algorithms to spread traffic between sockets, as follows: .RS @@ -402,7 +402,7 @@ ownership of the slot back to the socket by setting .I tp_status equal to .BR TP_STATUS_KERNEL . - +.IP Packet sockets implement multiple variants of the packet ring. The implementation details are described in .IR Documentation/networking/packet_mmap.txt @@ -410,7 +410,7 @@ in the Linux kernel source tree. .TP .BR PACKET_STATISTICS Retrieve packet socket statistics in the form of a structure - +.IP .in +4n .nf struct tpacket_stats { @@ -419,7 +419,7 @@ struct tpacket_stats { }; .fi .in - +.IP Receiving statistics resets the internal counters. The statistics structure differs when using a ring of variant .BR TPACKET_V3 . @@ -499,7 +499,7 @@ Argument is a .I struct timeval variable. .\" FIXME Document SIOCGSTAMPNS - +.PP In addition, all standard ioctls defined in .BR netdevice (7) and @@ -559,7 +559,7 @@ via although this covers only a subset of the .B AF_PACKET features. - +.PP The .B SOCK_DGRAM packet sockets make no attempt to create or parse the IEEE 802.2 LLC @@ -580,13 +580,13 @@ bind to instead and do the protocol multiplex yourself. The default for sending is the standard Ethernet DIX encapsulation with the protocol filled in. - +.PP Packet sockets are not subject to the input or output firewall chains. .SS Compatibility In Linux 2.0, the only way to get a packet socket was with the call: - +.PP socket(AF_INET, SOCK_PACKET, protocol) - +.PP This is still supported, but deprecated and strongly discouraged. The main difference between the two methods is that .B SOCK_PACKET @@ -594,7 +594,7 @@ uses the old .I struct sockaddr_pkt to specify an interface, which doesn't provide physical-layer independence. - +.PP .in +4n .nf struct sockaddr_pkt { @@ -604,7 +604,7 @@ struct sockaddr_pkt { }; .fi .in - +.PP .I spkt_family contains the device type, @@ -614,13 +614,13 @@ is the IEEE 802.3 protocol type as defined in and .I spkt_device is the device name as a null-terminated string, for example, eth0. - +.PP This structure is obsolete and should not be used in new code. .SH BUGS The IEEE 802.2/803.3 LLC handling could be considered as a bug. - +.PP Socket filters are not documented. - +.PP The .B MSG_TRUNC .BR recvmsg (2) @@ -639,14 +639,14 @@ packets via .BR ip (7), .BR raw (7), .BR socket (7) - +.PP RFC\ 894 for the standard IP Ethernet encapsulation. RFC\ 1700 for the IEEE 802.3 IP encapsulation. - +.PP The .I <linux/if_ether.h> include file for physical-layer protocols. - +.PP The Linux kernel source tree. .IR /Documentation/networking/filter.txt describes how to apply Berkeley Packet Filters to packet sockets. diff --git a/man7/raw.7 b/man7/raw.7 index 10c5d3342c..fa40600705 100644 --- a/man7/raw.7 +++ b/man7/raw.7 @@ -23,17 +23,17 @@ raw \- Linux IPv4 raw sockets Raw sockets allow new IPv4 protocols to be implemented in user space. A raw socket receives or sends the raw datagram not including link level headers. - +.PP The IPv4 layer generates an IP header when sending a packet unless the .B IP_HDRINCL 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. - +.PP In order to create a raw socket, a process must have the .B CAP_NET_RAW capability in the user namespace that governs its network namespace. - +.PP All packets or errors matching the .I protocol number specified @@ -44,7 +44,7 @@ see the IANA list of assigned protocol numbers at .UE and .BR getprotobyname (3). - +.PP A protocol of .B IPPROTO_RAW implies enabled @@ -77,7 +77,7 @@ When is specified, the destination address should refer to a local interface, otherwise a routing table lookup is done anyway but gatewayed routes are ignored. - +.PP If .B IP_HDRINCL isn't set, then IP header options can be set on raw sockets with @@ -85,12 +85,12 @@ isn't set, then IP header options can be set on raw sockets with see .BR ip (7) for more information. - +.PP Starting with Linux 2.2, all IP header fields and options can be set using IP socket options. This means raw sockets are usually needed only for new protocols or protocols with no user interface (like ICMP). - +.PP 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). @@ -184,7 +184,7 @@ and .B ICMP_FILTER are new in Linux 2.2. They are Linux extensions and should not be used in portable programs. - +.PP Linux 2.0 enabled some bug-to-bug compatibility with BSD in the raw socket code when the .B SO_BSDCOMPAT @@ -208,7 +208,7 @@ When turned off, raw sockets will fragment outgoing packets that exceed the interface MTU. However, disabling it is not recommended for performance and reliability reasons. - +.PP A raw socket can be bound to a specific local address using the .BR bind (2) call. @@ -217,7 +217,7 @@ In addition, a raw socket can be bound to a specific network device using .BR SO_BINDTODEVICE ; see .BR socket (7). - +.PP An .B IPPROTO_RAW socket is send only. @@ -228,28 +228,28 @@ socket with the protocol. Note that packet sockets don't reassemble IP fragments, unlike raw sockets. - +.PP 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). - +.PP Raw sockets may tap all IP protocols in Linux, even 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 implementation have limitations here. - +.PP 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. - +.PP Raw sockets are generally rather unportable and should be avoided in programs intended to be portable. - +.PP Sending on raw sockets should take the IP protocol from .IR sin_port ; this ability was lost in Linux 2.2. @@ -257,12 +257,12 @@ The workaround is to use .BR IP_HDRINCL . .SH BUGS Transparent proxy extensions are not described. - +.PP When the .B IP_HDRINCL option is set, datagrams will not be fragmented and are limited to the interface MTU. - +.PP Setting the IP protocol for sending in .I sin_port got lost in Linux 2.2. @@ -278,7 +278,7 @@ call is always used. .BR capabilities (7), .BR ip (7), .BR socket (7) - +.PP .B RFC\ 1191 for path MTU discovery. .B RFC\ 791 diff --git a/man7/rtld-audit.7 b/man7/rtld-audit.7 index 1853d32393..91719203ba 100644 --- a/man7/rtld-audit.7 +++ b/man7/rtld-audit.7 @@ -41,14 +41,14 @@ This API is very similar to the auditing interface provided by the Solaris run-time linker. The necessary constants and prototypes are defined by including .IR <link.h> . - +.PP To use this interface, the programmer creates a shared library that implements a standard set of function names. Not all of the functions need to be implemented: in most cases, if the programmer is not interested in a particular class of auditing event, then no implementation needs to be provided for the corresponding auditing function. - +.PP To employ the auditing interface, the environment variable .BR LD_AUDIT must be defined to contain a colon-separated list of shared libraries, @@ -72,7 +72,7 @@ When invoking this function, the dynamic linker passes, in the highest version of the auditing interface that the linker supports. If necessary, the auditing library can check that this version is sufficient for its requirements. - +.PP As its function result, this function should return the version of the auditing interface that this auditing library expects to use (returning @@ -224,7 +224,7 @@ The .I cookie argument is the identifier obtained from a previous invocation of .BR la_objopen (). - +.PP In the current implementation, the value returned by .BR la_objclose () is ignored. @@ -263,7 +263,7 @@ function is employed on 32-bit platforms; the .BR la_symbind64 () function is employed on 64-bit platforms. - +.PP The .I sym argument is a pointer to a structure @@ -273,12 +273,12 @@ The structure definition is shown in Among the fields of this structure, .I st_value indicates the address to which the symbol is bound. - +.PP The .I ndx argument gives the index of the symbol in the symbol table of the bound shared object. - +.PP The .I refcook argument identifies the shared object that is making the symbol reference; @@ -293,11 +293,11 @@ this is the same identifier that is provided to the .BR la_objopen () function that returned .BR LA_FLG_BINDTO . - +.PP The .I symname argument points a string containing the name of the symbol. - +.PP The .I flags argument is a bit mask that both provides information about the symbol @@ -362,10 +362,10 @@ Here is the definition for x86-32: .BI " La_i86_regs *" regs ", unsigned int *" flags , .BI " const char *" symname ", long int *" framesizep ); .fi - +.PP This function is invoked just before a PLT entry is called, between two shared objects that have been marked for binding notification. - +.PP The .IR sym , .IR ndx , @@ -375,20 +375,20 @@ and .IR symname are as for .BR la_symbind* (). - +.PP The .I regs argument points to a structure (defined in .IR <link.h> ) containing the values of registers to be used for the call to this PLT entry. - +.PP The .I flags argument points to a bit mask that conveys information about, and can be used to modify subsequent auditing of, this PLT entry, as for .BR la_symbind* (). - +.PP .\" FIXME . Is the following correct? The .IR framesizep @@ -404,7 +404,7 @@ The .BR la_pltexit () function is called only if this buffer is explicitly set to a suitable value. - +.PP The return value of .BR la_pltenter () is as for @@ -438,7 +438,7 @@ and .IR symname are as for .BR la_symbind* (). - +.PP The .I inregs argument points to a structure (defined in @@ -451,7 +451,7 @@ argument points to a structure (defined in containing return values for the call to this PLT entry. These values can be modified by the caller, and the changes will be visible to the caller of the PLT entry. - +.PP In the current GNU implementation, the return value of .BR la_pltexit () is ignored. diff --git a/man7/rtnetlink.7 b/man7/rtnetlink.7 index f102ca9cbe..3ff9a38990 100644 --- a/man7/rtnetlink.7 +++ b/man7/rtnetlink.7 @@ -41,7 +41,7 @@ for more information. .\" FIXME . ? all these macros could be moved to rtnetlink(3) .SS Routing attributes Some rtnetlink messages have optional attributes after the initial header: - +.PP .in +4n .nf struct rtattr { @@ -51,7 +51,7 @@ struct rtattr { }; .fi .in - +.PP These attributes should be manipulated using only the RTA_* macros or libnetlink, see .BR rtnetlink (3). @@ -66,7 +66,7 @@ These messages contain an structure followed by a series of .I rtattr structures. - +.IP .nf struct ifinfomsg { unsigned char ifi_family; /* AF_UNSPEC */ @@ -76,7 +76,7 @@ struct ifinfomsg { unsigned int ifi_change; /* change mask */ }; .fi - +.IP .\" FIXME Document ifinfomsg.ifi_type .I ifi_flags contains the device flags, see @@ -127,7 +127,7 @@ They contain an structure, optionally followed by .I rtattr routing attributes. - +.IP .nf struct ifaddrmsg { unsigned char ifa_family; /* Address type */ @@ -137,7 +137,7 @@ struct ifaddrmsg { int ifa_index; /* Interface index */ }; .fi - +.IP .I ifa_family is the address family type (currently .B AF_INET @@ -192,7 +192,7 @@ For the other fields, except and .IR rtm_protocol , 0 is the wildcard. - +.IP .nf struct rtmsg { unsigned char rtm_family; /* Address family of route */ @@ -245,7 +245,7 @@ RTPROT_KERNEL:by the kernel RTPROT_BOOT:during boot RTPROT_STATIC:by the administrator .TE - +.sp 1 Values larger than .B RTPROT_STATIC are not interpreted by the kernel, they are just for user information. @@ -254,7 +254,7 @@ distinguish between multiple routing daemons. See .I <linux/rtnetlink.h> for the routing daemon identifiers which are already assigned. - +.IP .I rtm_scope is the distance to the destination: .TS @@ -268,13 +268,13 @@ RT_SCOPE_LINK:route on this link RT_SCOPE_HOST:route on the local host RT_SCOPE_NOWHERE:destination doesn't exist .TE - +.sp 1 The values between .B RT_SCOPE_UNIVERSE and .B RT_SCOPE_SITE are available to the user. - +.IP The .I rtm_flags have the following meanings: @@ -287,7 +287,7 @@ T} RTM_F_CLONED:route is cloned from another route RTM_F_EQUALIZE:a multipath equalizer (not yet implemented) .TE - +.sp 1 .I rtm_table specifies the routing table .TS @@ -298,7 +298,7 @@ RT_TABLE_DEFAULT:the default table RT_TABLE_MAIN:the main table RT_TABLE_LOCAL:the local table .TE - +.sp 1 The user may assign arbitrary values between .B RT_TABLE_UNSPEC and @@ -326,7 +326,7 @@ RTA_PROTOINFO:: RTA_FLOW:: RTA_CACHEINFO:: .TE - +.sp 1 .B Fill these values in! .TP .BR RTM_NEWNEIGH ", " RTM_DELNEIGH ", " RTM_GETNEIGH @@ -335,7 +335,7 @@ entry (e.g., an ARP entry). The message contains an .I ndmsg structure. - +.IP .nf struct ndmsg { unsigned char ndm_family; @@ -352,7 +352,7 @@ struct nda_cacheinfo { __u32 ndm_refcnt; }; .fi - +.IP .I ndm_state is a bit mask of the following states: .TS @@ -367,7 +367,7 @@ NUD_FAILED:an invalid cache entry NUD_NOARP:a device with no destination cache NUD_PERMANENT:a static entry .TE - +.sp 1 Valid .I ndm_flags are: @@ -377,7 +377,7 @@ l l. NTF_PROXY:a proxy arp entry NTF_ROUTER:an IPv6 router .TE - +.sp 1 .\" FIXME . .\" document the members of the struct better The @@ -393,7 +393,7 @@ NDA_DST:a neighbor cache n/w layer destination address NDA_LLADDR:a neighbor cache link layer address NDA_CACHEINFO:cache statistics. .TE - +.sp 1 If the .I rta_type field is @@ -413,7 +413,7 @@ The message contains a .I struct tcmsg and may be followed by a series of attributes. - +.IP .nf struct tcmsg { unsigned char tcm_family; @@ -437,7 +437,7 @@ TCA_STATS:struct tc_stats:Qdisc statistics. TCA_XSTATS:qdisc-specific:Module-specific statistics. TCA_RATE:struct tc_estimator:Rate limit. .TE - +.sp 1 In addition, various other qdisc-module-specific attributes are allowed. For more information see the appropriate include files. .TP diff --git a/man7/sock_diag.7 b/man7/sock_diag.7 index f8eab86418..86257bed43 100644 --- a/man7/sock_diag.7 +++ b/man7/sock_diag.7 @@ -164,7 +164,7 @@ Supported values are: .RS 12 1 << .B TCP_ESTABLISHED - +.PP 1 << .B TCP_LISTEN .RE diff --git a/man7/socket.7 b/man7/socket.7 index f12adf2d9e..c455c1cc2c 100644 --- a/man7/socket.7 +++ b/man7/socket.7 @@ -91,7 +91,7 @@ for more information on families and types. 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. - +.PP .BR socket (2) creates a socket, .BR connect (2) @@ -252,7 +252,7 @@ the various system calls (e.g., .BR getpeername (2)), which are generic to all socket domains, to determine the domain of a particular socket address. - +.PP To allow any type of socket address to be passed to interfaces in the sockets API, the type @@ -262,7 +262,7 @@ The purpose of this type is purely to allow casting of domain-specific socket address types to a "generic" type, so as to avoid compiler warnings about type mismatches in calls to the sockets API. - +.PP In addition, the sockets API provides the data type .IR "struct sockaddr_storage". This type @@ -272,13 +272,13 @@ address structures; it is large enough and is aligned properly. IPv6 socket addresses.) The structure includes the following field, which can be used to identify the type of socket address actually stored in the structure: - +.PP .in +4n .nf sa_family_t ss_family; .fi .in - +.PP The .I sockaddr_storage structure is useful in programs that must handle socket addresses @@ -323,7 +323,7 @@ non-zero value which is less than the packet's data length, the packet will be truncated to the length returned. If the value returned by the filter is greater than or equal to the packet's data length, the packet is allowed to proceed unmodified. - +.IP The argument for .BR SO_ATTACH_FILTER is a @@ -346,13 +346,13 @@ is a file descriptor returned by the .BR bpf (2) system call and must refer to a program of type .BR BPF_PROG_TYPE_SOCKET_FILTER. - +.IP These options may be set multiple times for a given socket, each time replacing the previous filter program. The classic and extended versions may be called on the same socket, but the previous filter will always be replaced such that a socket never has more than one filter defined. - +.IP Both classic and extended BPF are explained in the kernel source file .I Documentation/networking/filter.txt .TP @@ -367,7 +367,7 @@ program which defines how packets are assigned to the sockets in the reuseport group (that is, all sockets which have .BR SO_REUSEPORT set and are using the same local address to receive packets). - +.IP The BPF program must return an index between 0 and N\-1 representing the socket which should receive the packet (where N is the number of sockets in the group). @@ -375,7 +375,7 @@ If the BPF program returns an invalid index, socket selection will fall back to the plain .BR SO_REUSEPORT mechanism. - +.IP Sockets are numbered in the order in which they are added to the group (that is, the order of .BR bind (2) @@ -387,10 +387,10 @@ When a socket is removed from a reuseport group (via .BR close (2)), the last socket in the group will be moved into the closed socket's position. - +.IP These options may be set repeatedly at any time on any socket in the group to replace the current BPF program used by all sockets in the group. - +.IP .BR SO_ATTACH_REUSEPORT_CBPF takes the same argument type as .BR SO_ATTACH_FILTER @@ -398,7 +398,7 @@ and .BR SO_ATTACH_REUSEPORT_EBPF takes the same argument type as .BR SO_ATTACH_BPF. - +.IP UDP support for this feature is available since Linux 4.5; TCP support is available since Linux 4.6. .TP @@ -420,7 +420,7 @@ sockets. It is not supported for packet sockets (use normal .BR bind (2) there). - +.IP Before Linux 3.8, this socket option could be set, but could not retrieved with .BR getsockopt (2). @@ -495,7 +495,7 @@ Expects an integer boolean flag. .\" setsockopt 70da268b569d32a9fddeea85dc18043de9d89f89 Sets or gets the CPU affinity of a socket. Expects an integer flag. - +.IP .in +4n .nf int cpu = 1; @@ -503,7 +503,7 @@ socklen_t len = sizeof(cpu); setsockopt(fd, SOL_SOCKET, SO_INCOMING_CPU, &cpu, &len); .fi .in - +.IP Because all of the packets for a single stream (i.e., all packets for the same 4-tuple) arrive on the single RX queue that is associated with a particular CPU, @@ -573,7 +573,7 @@ These filters include any set using the socket options .BR SO_ATTACH_REUSEPORT_CBPF and .BR SO_ATTACH_REUSEPORT_EPBF . - +.IP The typical use case is for a privileged process to set up a raw socket (an operation that requires the .BR CAP_NET_RAW @@ -582,7 +582,7 @@ capability), apply a restrictive filter, set the option, and then either drop its privileges or pass the socket file descriptor to an unprivileged process via a UNIX domain socket. - +.IP Once the .BR SO_LOCK_FILTER option has been enabled, attempts to change or remove the filter @@ -636,7 +636,7 @@ sockets, sets the value of the "peek offset" for the system call when used with .BR MSG_PEEK flag. - +.IP When this option is set to a negative value (it is set to \-1 for all new sockets), traditional behavior is provided: @@ -644,14 +644,14 @@ traditional behavior is provided: with the .BR MSG_PEEK flag will peek data from the front of the queue. - +.IP When the option is set to a value greater than or equal to zero, then the next peek at data queued in the socket will occur at the byte offset specified by the option value. At the same time, the "peek offset" will be incremented by the number of bytes that were peeked from the queue, so that a subsequent peek will return the next data in the queue. - +.IP If data is removed from the front of the queue via a call to .BR recv (2) (or similar) without the @@ -663,22 +663,22 @@ flag will cause the "peek offset" to be adjusted to maintain the correct relative position in the queued data, so that a subsequent peek will retrieve the data that would have been retrieved had the data not been removed. - +.IP For datagram sockets, if the "peek offset" points to the middle of a packet, the data returned will be marked with the .BR MSG_TRUNC flag. - +.IP The following example serves to illustrate the use of .BR SO_PEEK_OFF . Suppose a stream socket has the following queued input data: - +.IP aabbccddeeff .IP The following sequence of .BR recv (2) calls would have the effect noted in the comments: - +.IP .in +4n .nf int ov = 4; // Set peek offset to 4 @@ -858,7 +858,7 @@ To prevent port hijacking, all of the processes binding to the same address must have the same effective UID. This option can be employed with both TCP and UDP sockets. - +.IP For TCP sockets, this option allows .BR accept (2) load distribution in a multi-threaded server to be improved by @@ -870,7 +870,7 @@ thread that distributes connections, or having multiple threads that compete to .BR accept (2) from the same socket. - +.IP For UDP sockets, the use of this option can provide better distribution of incoming datagrams to multiple processes (or threads) as compared @@ -938,7 +938,7 @@ Increasing this value requires The default for this option is controlled by the .I /proc/sys/net/core/busy_read file. - +.IP The value in the .I /proc/sys/net/core/busy_poll file determines how long @@ -948,11 +948,11 @@ and will busy poll when they operate on sockets with .BR SO_BUSY_POLL set and no events to report are found. - +.IP In both cases, busy polling will only be done when the socket last received data from a network device that supports this option. - +.IP While busy polling may improve latency of some applications, care must be taken when using it since this will increase both CPU utilization and power usage. @@ -1037,7 +1037,7 @@ per socket. .SS Ioctls These operations can be accessed using .BR ioctl (2): - +.PP .in +4n .nf .IB error " = ioctl(" ip_socket ", " ioctl_type ", " &value_result ");" @@ -1140,7 +1140,7 @@ Linux assumes that half of the send/receive buffer is used for internal kernel structures; thus the values in the corresponding .I /proc files are twice what can be observed on the wire. - +.PP Linux will allow port reuse only with the .B SO_REUSEADDR option diff --git a/man7/tcp.7 b/man7/tcp.7 index fcfc33cc19..a4faf3ac6a 100644 --- a/man7/tcp.7 +++ b/man7/tcp.7 @@ -117,7 +117,7 @@ retransmits lost packets. It generates and checks a per-packet checksum to catch transmission errors. TCP does not preserve record boundaries. - +.PP A newly created TCP socket has no remote or local address and is not fully specified. To create an outgoing TCP connection use @@ -136,7 +136,7 @@ or .BR connect (2) successfully called on it is fully specified and may transmit data. Data cannot be transmitted on listening or not yet connected sockets. - +.PP Linux supports RFC\ 1323 TCP high performance extensions. These include Protection Against Wrapped @@ -156,7 +156,7 @@ and socket options with the .BR setsockopt (2) call. - +.PP The maximum sizes for socket buffers declared via the .B SO_SNDBUF and @@ -219,7 +219,7 @@ flag is set for .BR recv (2) or .BR recvmsg (2). - +.PP When out-of-band data is present, .BR select (2) indicates the file descriptor as having an exceptional condition and @@ -227,7 +227,7 @@ indicates the file descriptor as having an exceptional condition and indicates a .B POLLPRI event. - +.PP 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 @@ -305,7 +305,7 @@ is greater than 0; or if .I tcp_adv_win_scale is less than or equal to zero. - +.IP The socket receive buffer space is shared between the application and kernel. TCP maintains part of the buffer as @@ -364,7 +364,7 @@ but not loaded. .\" Since 2.4.0-test7 This variable defines how many bytes of the TCP window are reserved for buffering overhead. - +.IP A maximum of (\fIwindow/2^tcp_app_win\fP, mss) bytes in the window are reserved for the application buffer. A value of 0 implies that no amount is reserved. @@ -426,7 +426,7 @@ Enable RFC\ 2883 TCP Duplicate SACK support. .IR tcp_ecn " (Integer; default: see below; since Linux 2.4)" .\" Since 2.4.0-test7 Enable RFC\ 3168 Explicit Congestion Notification. - +.IP This file can have one of the following values: .RS .IP 0 @@ -480,7 +480,7 @@ It is particularly beneficial in wireless environments where packet loss is typically due to random radio interference rather than intermediate router congestion. See RFC 4138 for more details. - +.IP This file can have one of the following values: .RS .IP 0 3 @@ -553,7 +553,7 @@ 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. - +.IP Note that underlying connection tracking mechanisms and application timeouts may be much shorter. .\" @@ -591,7 +591,7 @@ 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). - +.IP Prior to Linux 2.6.20, .\" commit 72a3effaf633bcae9034b7e176bdbd78d64a71db it was recommended that if this needed to be increased above 1024, @@ -600,9 +600,9 @@ the size of the SYNACK hash table in .I include/net/tcp.h should be modified to keep - +.IP TCP_SYNQ_HSIZE * 16 <= tcp_max_syn_backlog - +.IP and the kernel should be recompiled. In Linux 2.6.20, the fixed sized @@ -774,9 +774,9 @@ This is not used to limit the size of the receive buffer declared using .B SO_RCVBUF on a socket. The default value is calculated using the formula - +.IP max(87380, min(4MB, \fItcp_mem\fP[1]*PAGE_SIZE/128)) - +.IP (On Linux 2.4, the default is 87380*2 bytes, lowered to 87380 in low-memory systems). .RE @@ -963,9 +963,9 @@ This is not used to limit the size of the send buffer declared using .B SO_SNDBUF on a socket. The default value is calculated using the formula - +.IP max(65536, min(4MB, \fItcp_mem\fP[1]*PAGE_SIZE/128)) - +.IP (On Linux 2.4, the default value is 128K bytes, lowered 64K depending on low-memory systems.) .RE @@ -1142,14 +1142,14 @@ corresponding connection and return to the application. If the option value is specified as 0, TCP will to use the system default. - +.IP Increasing user timeouts allows a TCP connection to survive extended periods without end-to-end connectivity. Decreasing user timeouts allows applications to "fail fast", if so desired. Otherwise, failure may take up to 20 minutes with the current system defaults in a normal WAN environment. - +.IP This option can be set during any state of a TCP connection, but is effective only during the synchronized states of a connection (ESTABLISHED, FIN-WAIT-1, FIN-WAIT-2, CLOSE-WAIT, CLOSING, and LAST-ACK). @@ -1159,14 +1159,14 @@ option, .B TCP_USER_TIMEOUT will override keepalive to determine when to close a connection due to keepalive failure. - +.IP The option has no effect on when TCP retransmits a packet, nor when a keepalive probe is sent. - +.IP This option, like many others, will be inherited by the socket returned by .BR accept (2), if it was set on the listening socket. - +.IP Further details on the user timeout feature can be found in RFC\ 793 and RFC\ 5482 ("TCP User Timeout Option"). .TP @@ -1192,12 +1192,12 @@ This violates RFC\ 1122, but is required for interoperability with other stacks. It can be changed via .IR /proc/sys/net/ipv4/tcp_stdurg . - +.PP It is possible to peek at out-of-band data using the .BR recv (2) .B MSG_PEEK flag. - +.PP Since version 2.4, Linux supports the use of .B MSG_TRUNC in the @@ -1250,7 +1250,7 @@ defined in Returns true (i.e., .I value is nonzero) if the inbound data stream is at the urgent mark. - +.IP If the .B SO_OOBINLINE socket option is set, and @@ -1266,7 +1266,7 @@ next read from the socket will return the bytes following the urgent data (to actually read the urgent data requires the .B recv(MSG_OOB) flag). - +.IP Note that a read never reads across the urgent mark. If an application is informed of the presence of urgent data via .BR select (2) diff --git a/man7/udp.7 b/man7/udp.7 index fdfabd594d..0e0f31da80 100644 --- a/man7/udp.7 +++ b/man7/udp.7 @@ -26,7 +26,7 @@ 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. - +.PP When a UDP socket is created, its local and remote addresses are unspecified. Datagrams can be sent immediately using @@ -55,7 +55,7 @@ a free local port out of the range defined by .I /proc/sys/net/ipv4/ip_local_port_range and bind the socket to .BR INADDR_ANY . - +.PP 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 @@ -63,7 +63,7 @@ data is returned; when it is bigger, the packet is truncated and the flag is set. .B MSG_WAITALL is not supported. - +.PP IP options may be sent or received using the socket options described in .BR ip (7). They are processed by the kernel only when the appropriate @@ -72,12 +72,12 @@ parameter is enabled (but still passed to the user even when it is turned off). See .BR ip (7). - +.PP When the .B MSG_DONTROUTE flag is set on sending, the destination address must refer to a local interface address and the packet is sent only to that interface. - +.PP 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 @@ -111,7 +111,7 @@ This behavior differs from many other BSD socket implementations which don't pass any errors unless the socket is connected. Linux's behavior is mandated by .BR RFC\ 1122 . - +.PP For compatibility with legacy code, in Linux 2.0 and 2.2 it was possible to set the .B SO_BSDCOMPAT @@ -125,7 +125,7 @@ Locally generated errors are always passed. Support for this socket option was removed in later kernels; see .BR socket (7) for further information. - +.PP When the .B IP_RECVERR option is enabled, all errors are stored in the socket error queue, @@ -257,7 +257,7 @@ is a new feature in Linux 2.2. .BR raw (7), .BR socket (7), .BR udplite (7) - +.PP RFC\ 768 for the User Datagram Protocol. .br RFC\ 1122 for the host requirements. diff --git a/man7/udplite.7 b/man7/udplite.7 index d2ed887857..0f6c68f355 100644 --- a/man7/udplite.7 +++ b/man7/udplite.7 @@ -38,19 +38,19 @@ udplite \- Lightweight User Datagram Protocol .SH DESCRIPTION This is an implementation of the Lightweight User Datagram Protocol (UDP-Lite), as described in RFC\ 3828. - +.PP UDP-Lite is an extension of UDP (RFC\ 768) to support variable-length checksums. This has advantages for some types of multimedia transport that may be able to make use of slightly damaged datagrams, rather than having them discarded by lower-layer protocols. - +.PP The variable-length checksum coverage is set via a .BR setsockopt (2) option. If this option is not set, the only difference from UDP is in using a different IP protocol identifier (IANA number 136). - +.PP The UDP-Lite implementation is a full extension of .BR udp (7)\(emthat is, it shares the same API and API behavior, and in addition @@ -77,18 +77,18 @@ socket options are valid on a UDP-Lite socket. See .BR udp (7) for more information. - +.PP The following two options are specific to UDP-Lite. .TP .BR UDPLITE_SEND_CSCOV This option sets the sender checksum coverage and takes an .I int as argument, with a checksum coverage value in the range 0..2^16-1. - +.IP A value of 0 means that the entire datagram is always covered. Values from 1-7 are illegal (RFC\ 3828, 3.1) and are rounded up to the minimum coverage of 8. - +.IP With regard to IPv6 jumbograms (RFC\ 2675), the UDP-Litev6 checksum coverage is limited to the first 2^16-1 octets, as per RFC\ 3828, 3.5. Higher values are therefore silently truncated to 2^16-1. @@ -105,7 +105,7 @@ Its function is that of a traffic filter: when enabled, it instructs the kernel to drop all packets which have a coverage .I less than the specified coverage value. - +.IP When the value of .B UDPLITE_RECV_CSCOV exceeds the actual packet coverage, incoming packets are silently dropped, @@ -148,8 +148,8 @@ Where glibc support is missing, the following definitions are needed: .BR ipv6 (7), .BR socket (7), .BR udp (7) - +.PP RFC\ 3828 for the Lightweight User Datagram Protocol (UDP-Lite). - +.PP .I Documentation/networking/udplite.txt in the Linux kernel source tree diff --git a/man7/unix.7 b/man7/unix.7 index 0204a33de2..9cc0bfe6f0 100644 --- a/man7/unix.7 +++ b/man7/unix.7 @@ -39,7 +39,7 @@ Traditionally, UNIX domain sockets can be either unnamed, or bound to a filesystem pathname (marked as being of type socket). Linux also supports an abstract namespace which is independent of the filesystem. - +.PP Valid socket types in the UNIX domain are: .BR SOCK_STREAM , for a stream-oriented socket; @@ -52,7 +52,7 @@ and (since Linux 2.6.4) for a sequenced-packet socket that is connection-oriented, preserves message boundaries, and delivers messages in the order that they were sent. - +.PP UNIX domain sockets support passing file descriptors or process credentials to other processes using ancillary data. .SS Address format @@ -76,7 +76,7 @@ field always contains On Linux .I sun_path is 108 bytes in size; see also NOTES, below. - +.PP Various systems calls (for example, .BR bind (2), .BR connect (2), @@ -92,7 +92,7 @@ Some other system calls (for example, and .BR accept (2)) return an argument of this type. - +.PP Three types of address are distinguished in the .I sockaddr_un structure: @@ -104,9 +104,9 @@ filesystem pathname using When the address of a pathname socket is returned (by one of the system calls noted above), its length is - +.IP offsetof(struct sockaddr_un, sun_path) + strlen(sun_path) + 1 - +.IP and .I sun_path contains the null-terminated pathname. @@ -176,7 +176,7 @@ The argument that describes the enclosing .I sockaddr_un structure should have a value of at least: - +.IP .nf offsetof(struct sockaddr_un, sun_path)+strlen(addr.sun_path)+1 .fi @@ -193,7 +193,7 @@ For example, some (but not all) implementations .\" is 108 bytes append a null terminator if none is present in the supplied .IR sun_path . - +.PP When coding portable applications, keep in mind that some implementations .\" HP-UX @@ -202,7 +202,7 @@ have as short as 92 bytes. .\" Modern BSDs generally have 104, Tru64 and AIX have 104, .\" Solaris and Irix have 108 - +.PP Various system calls .RB ( accept (2), .BR recvfrom (2), @@ -226,7 +226,7 @@ In the Linux implementation, pathname sockets honor the permissions of the directory they are in. Creation of a new socket will fail if the process does not have write and search (execute) permission on the directory in which the socket is created. - +.PP On Linux, connecting to a stream socket object requires write permission on that socket; sending a datagram to a datagram socket likewise @@ -236,13 +236,13 @@ on a socket file, and on some systems (e.g., older BSDs), the socket permissions are ignored. Portable programs should not rely on this feature for security. - +.PP When creating a new socket, the owner and group of the socket file are set according to the usual rules. The socket file has all permissions enabled, other than those that are turned off by the process .BR umask (2). - +.PP The owner, group, and permissions of a pathname socket can be changed (using .BR chown (2) and @@ -259,10 +259,10 @@ and changing the ownership and permissions of the object (via and .BR fchmod (2)) has no effect on the accessibility of the socket. - +.PP Abstract sockets automatically disappear when all open references to the socket are closed. - +.PP The abstract socket namespace is a nonportable Linux extension. .\" .SS Socket options @@ -308,7 +308,7 @@ The change to 5 bytes came in Linux 2.3.15.) .SS Sockets API The following paragraphs describe domain-specific details and unsupported features of the sockets API for UNIX domain sockets on Linux. - +.PP UNIX domain sockets do not support the transmission of out-of-band data (the .B MSG_OOB @@ -316,12 +316,12 @@ flag for .BR send (2) and .BR recv (2)). - +.PP The .BR send (2) .B MSG_MORE flag is not supported by UNIX domain sockets. - +.PP Before Linux 3.4, .\" commit 9f6f9af7694ede6314bed281eec74d588ba9474f the use of @@ -331,7 +331,7 @@ in the argument of .BR recv (2) was not supported by UNIX domain sockets. - +.PP The .B SO_SNDBUF socket option does have an effect for UNIX domain sockets, but the @@ -381,7 +381,7 @@ ancillary message. Thus structure is defined in .I <sys/socket.h> as follows: - +.IP .in +4n .nf struct ucred { @@ -391,14 +391,14 @@ struct ucred { }; .fi .in - +.IP Since glibc 2.8, the .B _GNU_SOURCE feature test macro must be defined (before including .I any header files) in order to obtain the definition of this structure. - +.IP 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. @@ -553,7 +553,7 @@ An in-flight file descriptor is one that has been sent using .BR sendmsg (2) but has not yet been accepted in the recipient process using .BR recvmsg (2). - +.IP This error is diagnosed since mainline Linux 4.5 (and in some earlier kernel versions where the fix has been backported). .\" commit 712f4aad406bb1ed67f3f98d04c044191f0ff593 @@ -582,7 +582,7 @@ longer needed (using The usual UNIX close-behind semantics apply; the socket can be unlinked at any time and will be finally removed from the filesystem when the last reference to it is closed. - +.PP To pass file descriptors or credentials over a .BR SOCK_STREAM , you need @@ -591,7 +591,7 @@ to send or receive at least one byte of nonancillary data in the same or .BR recvmsg (2) call. - +.PP UNIX domain stream sockets do not support the notion of out-of-band data. .\" .SH BUGS @@ -619,7 +619,7 @@ then the returned address structure .I won't have a null terminator in .IR sun_path . - +.PP In addition, some implementations .\" i.e., traditional BSD don't require a null terminator when binding a socket (the @@ -629,12 +629,12 @@ argument is used to determine the length of and when the socket address is retrieved on these implementations, there is no null terminator in .IR sun_path . - +.PP Applications that retrieve socket addresses can (portably) code to handle the possibility that there is no null terminator in .IR sun_path by respecting the fact that the number of valid bytes in the pathname is: - +.PP strnlen(addr.sun_path, addrlen \- offsetof(sockaddr_un, sun_path)) .\" The following patch to amend kernel behavior was rejected: .\" http://thread.gmane.org/gmane.linux.kernel.api/2437 @@ -646,7 +646,7 @@ by respecting the fact that the number of valid bytes in the pathname is: .\" 2012-04-18 .\" .\" FIXME . Track http://austingroupbugs.net/view.php?id=561 - +.PP Alternatively, an application can retrieve the socket address by allocating a buffer of size .I "sizeof(struct sockaddr_un)+1" @@ -658,7 +658,7 @@ as and the extra zero byte ensures that there will be a null terminator for the string returned in .IR sun_path : - +.PP .nf .in +3 void *addrp; @@ -675,7 +675,7 @@ if (getsockname(sfd, (struct sockaddr *) addrp, &addrlen)) == \-1) printf("sun_path = %s\\n", ((struct sockaddr_un *) addrp)\->sun_path); .in .fi - +.PP This sort of messiness can be avoided if it is guaranteed that the applications that .I create diff --git a/man7/uri.7 b/man7/uri.7 index 39d8760559..4329c7bfaa 100644 --- a/man7/uri.7 +++ b/man7/uri.7 @@ -708,7 +708,7 @@ tools) and invokes the right tool for any URI. .BR man2html (1), .BR mailaddr (7), .BR utf-8 (7) - +.PP .UR http://www.ietf.org\:/rfc\:/rfc2255.txt IETF RFC\ 2255 .UE diff --git a/man7/vdso.7 b/man7/vdso.7 index 863002be68..bafd181ba3 100644 --- a/man7/vdso.7 +++ b/man7/vdso.7 @@ -26,7 +26,7 @@ as the vDSO is most commonly called by the C library. This way you can code in the normal way using standard functions and the C library will take care of using any functionality that is available via the vDSO. - +.PP Why does the vDSO exist at all? There are some system calls the kernel provides that user-space code ends up using frequently, @@ -34,7 +34,7 @@ to the point that such calls can dominate overall performance. This is due both to the frequency of the call as well as the context-switch overhead that results from exiting user space and entering the kernel. - +.PP The rest of this documentation is geared toward the curious and/or C library writers rather than general developers. If you're trying to call the vDSO in your own application rather than using @@ -53,14 +53,14 @@ Rather than require the C library to figure out if this functionality is available at run time, the C library can use functions provided by the kernel in the vDSO. - +.PP Note that the terminology can be confusing. On x86 systems, the vDSO function used to determine the preferred method of making a system call is named "__kernel_vsyscall", but on x86_64, the term "vsyscall" also refers to an obsolete way to ask the kernel what time it is or what CPU the caller is on. - +.PP One frequently used system call is .BR gettimeofday (2). This system call is called both directly by user-space applications @@ -83,7 +83,7 @@ each program in the initial auxiliary vector (see via the .B AT_SYSINFO_EHDR tag. - +.PP You must not assume the vDSO is mapped at any particular location in the user's memory map. The base address will usually be randomized at run time every time a new @@ -92,7 +92,7 @@ process image is created (at time). This is done for security reasons, to prevent "return-to-libc" attacks. - +.PP For some architectures, there is also an .B AT_SYSINFO tag. @@ -108,7 +108,7 @@ and allows the C library to detect available functionality at run time when running under different kernel versions. Oftentimes the C library will do detection with the first call and then cache the result for subsequent calls. - +.PP All symbols are also versioned (using the GNU version format). This allows the kernel to update the function signature without breaking backward compatibility. @@ -117,12 +117,12 @@ return value. Thus, when looking up a symbol in the vDSO, you must always include the version to match the ABI you expect. - +.PP Typically the vDSO follows the naming convention of prefixing all symbols with "__vdso_" or "__kernel_" so as to distinguish them from other standard symbols. For example, the "gettimeofday" function is named "__vdso_gettimeofday". - +.PP You use the standard C calling conventions when calling any of these functions. No need to worry about weird register or stack behavior. @@ -131,7 +131,7 @@ No need to worry about weird register or stack behavior. When you compile the kernel, it will automatically compile and link the vDSO code for you. You will frequently find it under the architecture-specific directory: - +.PP find arch/$ARCH/ -name '*vdso*.so*' -o -name '*gate*.so*' .\" .SS vDSO names @@ -173,7 +173,7 @@ appear in the trace output. .SH ARCHITECTURE-SPECIFIC NOTES The subsections below provide architecture-specific notes on the vDSO. - +.PP Note that the vDSO that is used is based on the ABI of your user-space code and not the ABI of the kernel. Thus, for example, @@ -200,14 +200,14 @@ __vdso_clock_gettime LINUX_2.6 (exported since Linux 4.1) .in .ft P \} - +.PP .\" See linux/arch/arm/kernel/entry-armv.S .\" See linux/Documentation/arm/kernel_user_helpers.txt Additionally, the ARM port has a code page full of utility functions. Since it's just a raw page of code, there is no ELF information for doing symbol lookups or versioning. It does provide support for different versions though. - +.PP For information on this code page, it's best to refer to the kernel documentation as it's extremely detailed and covers everything you need to know: @@ -243,14 +243,14 @@ There is no provision for backward compatibility beyond sniffing raw opcodes, but as this is an embedded CPU, it can get away with things\(emsome of the object formats it runs aren't even ELF based (they're bFLT/FLAT). - +.PP For information on this code page, it's best to refer to the public documentation: .br http://docs.blackfin.uclinux.org/doku.php?id=linux\-kernel:fixed\-code .SS mips functions .\" See linux/arch/mips/vdso/vdso.ld.S - +.PP The table below lists the symbols exported by the vDSO. .if t \{\ .ft CW @@ -266,9 +266,9 @@ __kernel_clock_gettime LINUX_2.6 (exported since Linux 4.4) .in .ft P \} - +.PP .br - +.PP .SS ia64 (Itanium) functions .\" See linux/arch/ia64/kernel/gate.lds.S .\" Also linux/arch/ia64/kernel/fsys.S and linux/Documentation/ia64/fsys.txt @@ -288,7 +288,7 @@ __kernel_syscall_via_epc LINUX_2.5 .in .ft P \} - +.PP The Itanium port is somewhat tricky. In addition to the vDSO above, it also has "light-weight system calls" (also known as "fast syscalls" or "fsys"). @@ -330,12 +330,12 @@ the page to the process via the SR2 register. The permissions on the page are such that merely executing those addresses automatically executes with kernel privileges and not in user space. This is done to match the way HP-UX works. - +.PP Since it's just a raw page of code, there is no ELF information for doing symbol lookups or versioning. Simply call into the appropriate offset via the branch instruction, for example: - +.PP ble <offset>(%sr2, %r0) .if t \{\ .ft CW @@ -394,7 +394,7 @@ __kernel_sync_dicache_p5 LINUX_2.6.15 .in .ft P \} - +.PP The .B CLOCK_REALTIME_COARSE and @@ -432,7 +432,7 @@ __kernel_sync_dicache_p5 LINUX_2.6.15 .in .ft P \} - +.PP The .B CLOCK_REALTIME_COARSE and @@ -573,7 +573,7 @@ to user space, so it was reconceived as a vDSO in the current format. .BR syscalls (2), .BR getauxval (3), .BR proc (5) - +.PP The documents, examples, and source code in the Linux source code tree: .in +4n .nf |