LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity

environ.7, epoll.7, feature_test_macros.7, futex.7, ip.7, ipv6.7, locale.7, man-pages.7, man.7, math_error.7, netdevice.7, netlink.7, packet.7, raw.7, rtld-audit.7, rtnetlink.7, sock_diag.7, socket.7, tcp.7, udp.7, udplite.7, unix.7, uri.7, vdso.7: Formatting fix: replace blank lines with .PP/.IP 

Blank lines shouldn't generally appear in *roff source (other
than in code examples), since they create large vertical
spaces between text blocks.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk 2017-08-16 03:01:48 +02:00
parent eabf3ae555
commit 5711c04f8f
24 changed files with 387 additions and 387 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
man7/environ.7
View File

@ -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

10
man7/epoll.7
View File

@ -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

62
man7/feature_test_macros.7
View File

@ -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

2
man7/futex.7
View File

@ -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

40
man7/ip.7
View File

@ -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.

8
man7/ipv6.7
View File

@ -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).

2
man7/locale.7
View File

@ -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),

116
man7/man-pages.7
View File

@ -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

2
man7/man.7
View File

@ -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

18
man7/math_error.7
View File

@ -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"

18
man7/netdevice.7
View File

@ -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

48
man7/netlink.7
View File

@ -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"

60
man7/packet.7
View File

@ -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.

36
man7/raw.7
View File

@ -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

34
man7/rtld-audit.7
View File

@ -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.

42
man7/rtnetlink.7
View File

@ -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

2
man7/sock_diag.7
View File

@ -164,7 +164,7 @@ Supported values are:
.RS 12
1 <<
.B TCP_ESTABLISHED
.PP
1 <<
.B TCP_LISTEN
.RE

64
man7/socket.7
View File

@ -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

52
man7/tcp.7
View File

@ -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)

16
man7/udp.7
View File

@ -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.

18
man7/udplite.7
View File

@ -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

60
man7/unix.7
View File

@ -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

2
man7/uri.7
View File

@ -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

46
man7/vdso.7
View File

@ -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