]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>. |
2297bf0e | 2 | .\" |
00acdba1 | 3 | .\" %%%LICENSE_START(VERBATIM_ONE_PARA) |
fea681da MK |
4 | .\" Permission is granted to distribute possibly modified copies |
5 | .\" of this page provided the header is included verbatim, | |
6 | .\" and in case of nontrivial modification author and date | |
7 | .\" of the modification is added to the header. | |
8ff7380d | 8 | .\" %%%LICENSE_END |
a781c7d0 | 9 | .\" |
fea681da | 10 | .\" $Id: cmsg.3,v 1.8 2000/12/20 18:10:31 ak Exp $ |
4b8c67d9 | 11 | .TH CMSG 3 2017-09-15 "Linux" "Linux Programmer's Manual" |
fea681da | 12 | .SH NAME |
f68512e9 | 13 | CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- access ancillary data |
fea681da | 14 | .SH SYNOPSIS |
d91b7522 | 15 | .nf |
fea681da | 16 | .B #include <sys/socket.h> |
fea681da | 17 | .BI "struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *" msgh ); |
d91b7522 MK |
18 | .BI "struct cmsghdr *CMSG_NXTHDR(struct msghdr *" msgh " , |
19 | .BR " struct cmsghdr *" cmsg ); | |
fea681da | 20 | .BI "size_t CMSG_ALIGN(size_t " length ); |
fea681da | 21 | .BI "size_t CMSG_SPACE(size_t " length ); |
fea681da | 22 | .BI "size_t CMSG_LEN(size_t " length ); |
c13182ef | 23 | .BI "unsigned char *CMSG_DATA(struct cmsghdr *" cmsg ); |
d91b7522 | 24 | .fi |
fea681da MK |
25 | .SH DESCRIPTION |
26 | These macros are used to create and access control messages (also called | |
27 | ancillary data) that are not a part of the socket payload. | |
c13182ef MK |
28 | This control information may |
29 | include the interface the packet was received on, various rarely used header | |
e78f6e73 | 30 | fields, an extended error description, a set of file descriptors, or UNIX |
c13182ef MK |
31 | credentials. |
32 | For instance, control messages can be used to send | |
33 | additional header fields such as IP options. | |
34 | Ancillary data is sent by calling | |
fea681da MK |
35 | .BR sendmsg (2) |
36 | and received by calling | |
37 | .BR recvmsg (2). | |
c13182ef | 38 | See their manual pages for more information. |
fea681da | 39 | .PP |
c13182ef | 40 | Ancillary data is a sequence of |
9910d338 | 41 | .I cmsghdr |
c13182ef | 42 | structures with appended data. |
c13182ef | 43 | See the specific protocol man pages for the available control message types. |
5a2ff571 MK |
44 | The maximum ancillary buffer size allowed per socket can be set using |
45 | .IR /proc/sys/net/core/optmem_max ; | |
46 | see | |
c13182ef | 47 | .BR socket (7). |
fea681da | 48 | .PP |
9910d338 MK |
49 | The |
50 | .I cmsghdr | |
51 | structure is defined as follows: | |
52 | .PP | |
53 | .in +4n | |
54 | .EX | |
55 | struct cmsghdr { | |
56 | size_t cmsg_len; /* Data byte count, including header | |
57 | (type is socklen_t in POSIX) */ | |
58 | int cmsg_level; /* Originating protocol */ | |
59 | int cmsg_type; /* Protocol-specific type */ | |
60 | /* followed by | |
61 | unsigned char cmsg_data[]; */ | |
62 | }; | |
63 | .EE | |
64 | .in | |
65 | .PP | |
66 | The sequence of | |
67 | .I cmsghdr | |
68 | structures should never be accessed directly. | |
69 | Instead, use only the following macros: | |
70 | .IP * 3 | |
e511ffb6 | 71 | .BR CMSG_FIRSTHDR () |
c13182ef | 72 | returns a pointer to the first |
f19a0f03 | 73 | .I cmsghdr |
fea681da | 74 | in the ancillary |
c13182ef | 75 | data buffer associated with the passed |
f19a0f03 | 76 | .IR msghdr . |
f565c3ee MK |
77 | It returns NULL if there isn't enough space for a |
78 | .I cmsghdr | |
79 | in the buffer. | |
9910d338 | 80 | .IP * |
e511ffb6 | 81 | .BR CMSG_NXTHDR () |
c13182ef | 82 | returns the next valid |
f19a0f03 | 83 | .I cmsghdr |
c13182ef | 84 | after the passed |
f19a0f03 | 85 | .IR cmsghdr . |
8478ee02 | 86 | It returns NULL when there isn't enough space left in the buffer. |
ca16e00d MK |
87 | .IP |
88 | When initializing a buffer that will contain a series of | |
89 | .I cmsghdr | |
90 | structures (e.g., to be sent with | |
91 | .BR sendmsg (2)), | |
92 | that buffer should first be zero-initialized | |
93 | to ensure the correct operation of | |
94 | .BR CMSG_NXTHDR (). | |
9910d338 | 95 | .IP * |
e511ffb6 | 96 | .BR CMSG_ALIGN (), |
c13182ef MK |
97 | given a length, returns it including the required alignment. |
98 | This is a | |
fea681da | 99 | constant expression. |
9910d338 | 100 | .IP * |
e511ffb6 | 101 | .BR CMSG_SPACE () |
c13182ef MK |
102 | returns the number of bytes an ancillary element with payload of the |
103 | passed data length occupies. | |
35478399 | 104 | This is a constant expression. |
9910d338 | 105 | .IP * |
e69ecf93 | 106 | .BR CMSG_DATA () |
c13182ef | 107 | returns a pointer to the data portion of a |
f19a0f03 | 108 | .IR cmsghdr . |
9910d338 | 109 | .IP * |
e69ecf93 | 110 | .BR CMSG_LEN () |
c13182ef | 111 | returns the value to store in the |
fea681da | 112 | .I cmsg_len |
c13182ef | 113 | member of the |
f19a0f03 | 114 | .I cmsghdr |
fea681da | 115 | structure, taking into account any necessary |
c13182ef MK |
116 | alignment. |
117 | It takes the data length as an argument. | |
118 | This is a constant | |
119 | expression. | |
fea681da | 120 | .PP |
c13182ef | 121 | To create ancillary data, first initialize the |
fea681da | 122 | .I msg_controllen |
c13182ef | 123 | member of the |
f19a0f03 | 124 | .I msghdr |
c13182ef MK |
125 | with the length of the control message buffer. |
126 | Use | |
e511ffb6 | 127 | .BR CMSG_FIRSTHDR () |
c13182ef | 128 | on the |
f19a0f03 | 129 | .I msghdr |
fea681da | 130 | to get the first control message and |
a60823e2 | 131 | .BR CMSG_NXTHDR () |
fea681da MK |
132 | to get all subsequent ones. |
133 | In each control message, initialize | |
134 | .I cmsg_len | |
c13182ef | 135 | (with |