cmsg.3: Reorganize the text somewhat (no content changes)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk 2017-08-20 12:41:32 +02:00
parent 79e1824a12
commit 9910d338e7
1 changed files with 28 additions and 18 deletions

View File

@ -26,16 +26,6 @@ CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- access ancillary data
.br
.BI "unsigned char *CMSG_DATA(struct cmsghdr *" cmsg );
.PP
.nf
struct cmsghdr {
size_t cmsg_len; /* Data byte count, including header
(type is socklen_t in POSIX) */
int cmsg_level; /* Originating protocol */
int cmsg_type; /* Protocol-specific type */
/* followed by
unsigned char cmsg_data[]; */
};
.fi
.SH DESCRIPTION
These macros are used to create and access control messages (also called
ancillary data) that are not a part of the socket payload.
@ -52,44 +42,64 @@ and received by calling
See their manual pages for more information.
.PP
Ancillary data is a sequence of
.I struct cmsghdr
.I cmsghdr
structures with appended data.
This sequence should be accessed
using only the macros described in this manual page and never directly.
See the specific protocol man pages for the available control message types.
The maximum ancillary buffer size allowed per socket can be set using
.IR /proc/sys/net/core/optmem_max ;
see
.BR socket (7).
.PP
The
.I cmsghdr
structure is defined as follows:
.PP
.in +4n
.EX
struct cmsghdr {
size_t cmsg_len; /* Data byte count, including header
(type is socklen_t in POSIX) */
int cmsg_level; /* Originating protocol */
int cmsg_type; /* Protocol-specific type */
/* followed by
unsigned char cmsg_data[]; */
};
.EE
.in
.PP
The sequence of
.I cmsghdr
structures should never be accessed directly.
Instead, use only the following macros:
.IP * 3
.BR CMSG_FIRSTHDR ()
returns a pointer to the first
.I cmsghdr
in the ancillary
data buffer associated with the passed
.IR msghdr .
.PP
.IP *
.BR CMSG_NXTHDR ()
returns the next valid
.I cmsghdr
after the passed
.IR cmsghdr .
It returns NULL when there isn't enough space left in the buffer.
.PP
.IP *
.BR CMSG_ALIGN (),
given a length, returns it including the required alignment.
This is a
constant expression.
.PP
.IP *
.BR CMSG_SPACE ()
returns the number of bytes an ancillary element with payload of the
passed data length occupies.
This is a constant expression.
.PP
.IP *
.BR CMSG_DATA ()
returns a pointer to the data portion of a
.IR cmsghdr .
.PP
.IP *
.BR CMSG_LEN ()
returns the value to store in the
.I cmsg_len