]>
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 $ |
97986708 | 11 | .TH CMSG 3 2016-03-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 | 29 | .nf |
fea681da | 30 | struct cmsghdr { |
1893b648 MK |
31 | size_t cmsg_len; /* Data byte count, including header |
32 | (type is socklen_t in POSIX) */ | |
4ecc4f79 MK |
33 | int cmsg_level; /* Originating protocol */ |
34 | int cmsg_type; /* Protocol-specific type */ | |
35 | /* followed by | |
36 | unsigned char cmsg_data[]; */ | |
fea681da | 37 | }; |
fea681da MK |
38 | .fi |
39 | .SH DESCRIPTION | |
40 | These macros are used to create and access control messages (also called | |
41 | ancillary data) that are not a part of the socket payload. | |
c13182ef MK |
42 | This control information may |
43 | include the interface the packet was received on, various rarely used header | |
008f1ecc | 44 | fields, an extended error description, a set of file descriptors or UNIX |
c13182ef MK |
45 | credentials. |
46 | For instance, control messages can be used to send | |
47 | additional header fields such as IP options. | |
48 | Ancillary data is sent by calling | |
fea681da MK |
49 | .BR sendmsg (2) |
50 | and received by calling | |
51 | .BR recvmsg (2). | |
c13182ef | 52 | See their manual pages for more information. |
fea681da | 53 | .PP |
c13182ef MK |
54 | Ancillary data is a sequence of |
55 | .I struct cmsghdr | |
56 | structures with appended data. | |
33a0ccb2 MK |
57 | This sequence should be accessed |
58 | using only the macros described in this manual page and never directly. | |
c13182ef | 59 | See the specific protocol man pages for the available control message types. |
5a2ff571 MK |
60 | The maximum ancillary buffer size allowed per socket can be set using |
61 | .IR /proc/sys/net/core/optmem_max ; | |
62 | see | |
c13182ef | 63 | .BR socket (7). |
fea681da | 64 | .PP |
e511ffb6 | 65 | .BR CMSG_FIRSTHDR () |
c13182ef | 66 | returns a pointer to the first |
f19a0f03 | 67 | .I cmsghdr |
fea681da | 68 | in the ancillary |
c13182ef | 69 | data buffer associated with the passed |
f19a0f03 | 70 | .IR msghdr . |
fea681da | 71 | .PP |
e511ffb6 | 72 | .BR CMSG_NXTHDR () |
c13182ef | 73 | returns the next valid |
f19a0f03 | 74 | .I cmsghdr |
c13182ef | 75 | after the passed |
f19a0f03 | 76 | .IR cmsghdr . |
8478ee02 | 77 | It returns NULL when there isn't enough space left in the buffer. |
fea681da | 78 | .PP |
e511ffb6 | 79 | .BR CMSG_ALIGN (), |
c13182ef MK |
80 | given a length, returns it including the required alignment. |
81 | This is a | |
fea681da MK |
82 | constant expression. |
83 | .PP | |
e511ffb6 | 84 | .BR CMSG_SPACE () |
c13182ef MK |
85 | returns the number of bytes an ancillary element with payload of the |
86 | passed data length occupies. | |
35478399 | 87 | This is a constant expression. |
fea681da | 88 | .PP |
e69ecf93 | 89 | .BR CMSG_DATA () |
c13182ef | 90 | returns a pointer to the data portion of a |
f19a0f03 | 91 | .IR cmsghdr . |
fea681da | 92 | .PP |
e69ecf93 | 93 | .BR CMSG_LEN () |
c13182ef | 94 | returns the value to store in the |
fea681da | 95 | .I cmsg_len |
c13182ef | 96 | member of the |
f19a0f03 | 97 | .I cmsghdr |
fea681da | 98 | structure, taking into account any necessary |
c13182ef MK |
99 | alignment. |
100 | It takes the data length as an argument. | |
101 | This is a constant | |
102 | expression. | |
fea681da | 103 | .PP |
c13182ef | 104 | To create ancillary data, first initialize the |
fea681da | 105 | .I msg_controllen |
c13182ef | 106 | member of the |
f19a0f03 | 107 | .I msghdr |
c13182ef MK |
108 | with the length of the control message buffer. |
109 | Use | |
e511ffb6 | 110 | .BR CMSG_FIRSTHDR () |
c13182ef | 111 | on the |
f19a0f03 | 112 | .I msghdr |
fea681da | 113 | to get the first control message and |
a60823e2 | 114 | .BR CMSG_NXTHDR () |
fea681da MK |
115 | to get all subsequent ones. |
116 | In each control message, initialize | |
117 | .I cmsg_len | |
c13182ef | 118 | (with |