]>
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 $ |
45186a5d | 11 | .TH CMSG 3 2021-03-22 "Linux man-pages (unreleased)" |
fea681da | 12 | .SH NAME |
f68512e9 | 13 | CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- access ancillary data |
b813014f AC |
14 | .SH LIBRARY |
15 | Standard C library | |
16 | .RI ( libc ", " \-lc ) | |
fea681da | 17 | .SH SYNOPSIS |
d91b7522 | 18 | .nf |
fea681da | 19 | .B #include <sys/socket.h> |
15d65653 | 20 | .PP |
fea681da | 21 | .BI "struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *" msgh ); |
9bfc9cb1 | 22 | .BI "struct cmsghdr *CMSG_NXTHDR(struct msghdr *" msgh , |
d91b7522 | 23 | .BR " struct cmsghdr *" cmsg ); |
fea681da | 24 | .BI "size_t CMSG_ALIGN(size_t " length ); |
fea681da | 25 | .BI "size_t CMSG_SPACE(size_t " length ); |
fea681da | 26 | .BI "size_t CMSG_LEN(size_t " length ); |
c13182ef | 27 | .BI "unsigned char *CMSG_DATA(struct cmsghdr *" cmsg ); |
d91b7522 | 28 | .fi |
fea681da MK |
29 | .SH DESCRIPTION |
30 | These macros are used to create and access control messages (also called | |
31 | ancillary data) that are not a part of the socket payload. | |
c13182ef MK |
32 | This control information may |
33 | include the interface the packet was received on, various rarely used header | |
e78f6e73 | 34 | fields, an extended error description, a set of file descriptors, or UNIX |
c13182ef MK |
35 | credentials. |
36 | For instance, control messages can be used to send | |
37 | additional header fields such as IP options. | |
38 | Ancillary data is sent by calling | |
fea681da MK |
39 | .BR sendmsg (2) |
40 | and received by calling | |
41 | .BR recvmsg (2). | |
c13182ef | 42 | See their manual pages for more information. |
fea681da | 43 | .PP |
c13182ef | 44 | Ancillary data is a sequence of |
9910d338 | 45 | .I cmsghdr |
c13182ef | 46 | structures with appended data. |
c13182ef | 47 | See the specific protocol man pages for the available control message types. |
5a2ff571 MK |
48 | The maximum ancillary buffer size allowed per socket can be set using |
49 | .IR /proc/sys/net/core/optmem_max ; | |
50 | see | |
c13182ef | 51 | .BR socket (7). |
fea681da | 52 | .PP |
9910d338 MK |
53 | The |
54 | .I cmsghdr | |
55 | structure is defined as follows: | |
56 | .PP | |
57 | .in +4n | |
58 | .EX | |
59 | struct cmsghdr { | |
60 | size_t cmsg_len; /* Data byte count, including header | |
61 | (type is socklen_t in POSIX) */ | |
62 | int cmsg_level; /* Originating protocol */ | |
d064d41a | 63 | int cmsg_type; /* Protocol\-specific type */ |
9910d338 MK |
64 | /* followed by |
65 | unsigned char cmsg_data[]; */ | |
66 | }; | |
67 | .EE | |
68 | .in | |
69 | .PP | |
70 | The sequence of | |
71 | .I cmsghdr | |
72 | structures should never be accessed directly. | |
73 | Instead, use only the following macros: | |
74 | .IP * 3 | |
e511ffb6 | 75 | .BR CMSG_FIRSTHDR () |
c13182ef | 76 | returns a pointer to the first |
f19a0f03 | 77 | .I cmsghdr |
fea681da | 78 | in the ancillary |
c13182ef | 79 | data buffer associated with the passed |
f19a0f03 | 80 | .IR msghdr . |
f565c3ee MK |
81 | It returns NULL if there isn't enough space for a |
82 | .I cmsghdr | |
83 | in the buffer. | |
9910d338 | 84 | .IP * |
e511ffb6 | 85 | .BR CMSG_NXTHDR () |
c13182ef | 86 | returns the next valid |
f19a0f03 | 87 | .I cmsghdr |
c13182ef | 88 | after the passed |
f19a0f03 | 89 | .IR cmsghdr . |
8478ee02 | 90 | It returns NULL when there isn't enough space left in the buffer. |
ca16e00d MK |
91 | .IP |
92 | When initializing a buffer that will contain a series of | |
93 | .I cmsghdr | |
94 | structures (e.g., to be sent with | |
95 | .BR sendmsg (2)), | |
96 | that buffer should first be zero-initialized | |
97 | to ensure the correct operation of | |
98 | .BR CMSG_NXTHDR (). | |
9910d338 | 99 | .IP * |
e511ffb6 | 100 | .BR CMSG_ALIGN (), |
c13182ef MK |
101 | given a length, returns it including the required alignment. |
102 | This is a | |
fea681da | 103 | constant expression. |
9910d338 | 104 | .IP * |
e511ffb6 | 105 | .BR CMSG_SPACE () |
c13182ef MK |
106 | returns the number of bytes an ancillary element with payload of the |
107 | passed data length occupies. | |
35478399 | 108 | This is a constant expression. |
9910d338 | 109 | .IP * |
e69ecf93 | 110 | .BR CMSG_DATA () |
c13182ef | 111 | returns a pointer to the data portion of a |
f19a0f03 | 112 | .IR cmsghdr . |
36d25246 RF |
113 | The pointer returned cannot be assumed to be suitably aligned for |
114 | accessing arbitrary payload data types. | |
115 | Applications should not cast it to a pointer type matching the payload, | |
116 | but should instead use | |
117 | .BR memcpy (3) | |
118 | to copy data to or from a suitably declared object. | |
9910d338 | 119 | .IP * |
e69ecf93 | 120 | .BR CMSG_LEN () |
c13182ef | 121 | returns the value to store in the |
fea681da | 122 | .I cmsg_len |
c13182ef | 123 | member of the |
f19a0f03 | 124 | .I cmsghdr |
fea681da | 125 | structure, taking into account any necessary |
c13182ef MK |
126 | alignment. |
127 | It takes the data length as an argument. | |
128 | This is a constant | |
129 | expression. | |
fea681da | 130 | .PP |
c13182ef | 131 | To create ancillary data, first initialize the |
fea681da | 132 | .I msg_controllen |
c13182ef | 133 | member of the |
f19a0f03 | 134 | .I msghdr |
c13182ef MK |
135 | with the length of the control message buffer. |
136 | Use | |
e511ffb6 | 137 | .BR CMSG_FIRSTHDR () |
c13182ef | 138 | on the |
f19a0f03 | 139 | .I msghdr |
fea681da | 140 | to get the first control message and |
a60823e2 | 141 | .BR CMSG_NXTHDR () |
fea681da MK |
142 | to get all subsequent ones. |
143 | In each control message, initialize | |
144 | .I cmsg_len | |
c13182ef | 145 | (with |