]>
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 MK |
14 | .SH SYNOPSIS |
15 | .B #include <sys/socket.h> | |
68e4db0a | 16 | .PP |
fea681da MK |
17 | .BI "struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *" msgh ); |
18 | .br | |
19 | .BI "struct cmsghdr *CMSG_NXTHDR(struct msghdr *" msgh ", struct cmsghdr *" cmsg ); | |
20 | .br | |
21 | .BI "size_t CMSG_ALIGN(size_t " length ); | |
22 | .br | |
23 | .BI "size_t CMSG_SPACE(size_t " length ); | |
24 | .br | |
25 | .BI "size_t CMSG_LEN(size_t " length ); | |
26 | .br | |
c13182ef | 27 | .BI "unsigned char *CMSG_DATA(struct cmsghdr *" cmsg ); |
68e4db0a | 28 | .PP |
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 | |
008f1ecc | 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 */ | |
63 | int cmsg_type; /* Protocol-specific type */ | |
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 . |
9910d338 | 81 | .IP * |
e511ffb6 | 82 | .BR CMSG_NXTHDR () |
c13182ef | 83 | returns the next valid |
f19a0f03 | 84 | .I cmsghdr |
c13182ef | 85 | after the passed |
f19a0f03 | 86 | .IR cmsghdr . |
8478ee02 | 87 | It returns NULL when there isn't enough space left in the buffer. |
9910d338 | 88 | .IP * |
e511ffb6 | 89 | .BR CMSG_ALIGN (), |
c13182ef MK |
90 | given a length, returns it including the required alignment. |
91 | This is a | |
fea681da | 92 | constant expression. |
9910d338 | 93 | .IP * |
e511ffb6 | 94 | .BR CMSG_SPACE () |
c13182ef MK |
95 | returns the number of bytes an ancillary element with payload of the |
96 | passed data length occupies. | |
35478399 | 97 | This is a constant expression. |
9910d338 | 98 | .IP * |
e69ecf93 | 99 | .BR CMSG_DATA () |
c13182ef | 100 | returns a pointer to the data portion of a |
f19a0f03 | 101 | .IR cmsghdr . |
9910d338 | 102 | .IP * |
e69ecf93 | 103 | .BR CMSG_LEN () |
c13182ef | 104 | returns the value to store in the |
fea681da | 105 | .I cmsg_len |
c13182ef | 106 | member of the |
f19a0f03 | 107 | .I cmsghdr |
fea681da | 108 | structure, taking into account any necessary |
c13182ef MK |
109 | alignment. |
110 | It takes the data length as an argument. | |
111 | This is a constant | |
112 | expression. | |
fea681da | 113 | .PP |
c13182ef | 114 | To create ancillary data, first initialize the |
fea681da | 115 | .I msg_controllen |
c13182ef | 116 | member of the |
f19a0f03 | 117 | .I msghdr |
c13182ef MK |
118 | with the length of the control message buffer. |
119 | Use | |
e511ffb6 | 120 | .BR CMSG_FIRSTHDR () |
c13182ef | 121 | on the |
f19a0f03 | 122 | .I msghdr |
fea681da | 123 | to get the first control message and |
a60823e2 | 124 | .BR CMSG_NXTHDR () |
fea681da MK |
125 | to get all subsequent ones. |
126 | In each control message, initialize | |
127 | .I cmsg_len | |
c13182ef | 128 | (with |