1 .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
2 .\" Permission is granted to distribute possibly modified copies
3 .\" of this page provided the header is included verbatim,
4 .\" and in case of nontrivial modification author and date
5 .\" of the modification is added to the header.
6 .\" $Id: cmsg.3,v 1.3 2001/01/14 05:30:39 hanataka Exp $
8 .\" Japanese Version Copyright (c) 1999 Shouichi Saito
9 .\" all rights reserved.
10 .\" Translated Mon Jul 26 21:58:26 JST 1999
11 .\" by Shouichi Saito <ss236rx@ymg.urban.ne.jp>
12 .\" Proofed Tue Aug 17 1999 by NAKANO Takeo <nakano@apm.seikei.ac.jp>
14 .TH CMSG 3 2008-11-20 "Linux" "Linux Programmer's Manual"
16 .\"O CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- Access ancillary data
17 CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- Êä½õ¥Ç¡¼¥¿¤Ë¥¢¥¯¥»¥¹¤¹¤ë¡£
19 .B #include <sys/socket.h>
21 .BI "struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *" msgh );
23 .BI "struct cmsghdr *CMSG_NXTHDR(struct msghdr *" msgh ", struct cmsghdr *" cmsg );
25 .BI "size_t CMSG_ALIGN(size_t " length );
27 .BI "size_t CMSG_SPACE(size_t " length );
29 .BI "size_t CMSG_LEN(size_t " length );
31 .BI "unsigned char *CMSG_DATA(struct cmsghdr *" cmsg );
35 socklen_t cmsg_len; /* data byte count, including header */
36 int cmsg_level; /* originating protocol */
37 int cmsg_type; /* protocol-specific type */
38 /* followed by unsigned char cmsg_data[]; */
42 .\"O These macros are used to create and access control messages (also called
43 .\"O ancillary data) that are not a part of the socket payload.
44 ¤³¤ì¤é¤Î¥Þ¥¯¥í¤ÏÀ©¸æ¥á¥Ã¥»¡¼¥¸
45 (Êä½õ¥Ç¡¼¥¿ (ancillary data) ¤È¤â¸Æ¤Ð¤ì¤ë) ¤òºî¤ê¡¢
46 ¤½¤ì¤Ë¥¢¥¯¥»¥¹¤¹¤ë¤¿¤á¤Ë»È¤ï¤ì¤ë¡£
47 À©¸æ¥á¥Ã¥»¡¼¥¸¤Ï¥½¥±¥Ã¥È¤Ë¤Î¤ë¥Ç¡¼¥¿¤Ç¤Ï¤Ê¤¤¡£
48 .\"O This control information may
49 .\"O include the interface the packet was received on, various rarely used header
50 .\"O fields, an extended error description, a set of file descriptors or UNIX
52 .\"O For instance, control messages can be used to send
53 .\"O additional header fields such as IP options.
54 ¤³¤ÎÀ©¸æ¾ðÊó¤Ï¡¢ÅþÃ夷¤¿¥Ñ¥±¥Ã¥È¤Ø¤Î¥¤¥ó¥¿¡¼¥Õ¥§¥¤¥¹¡¢ÍÍ¡¹¤Ê¤¢¤Þ¤ê
55 »È¤ï¤ì¤Ê¤¤¥Ø¥Ã¥À¡¼¥Õ¥£¡¼¥ë¥É¡¢¥¨¥é¡¼µ½Ò¤Î³ÈÄ¥¡¢¥Õ¥¡¥¤¥ë¥Ç¥¹¥¯¥ê
56 ¥×¥¿¤Î½¸¹ç¤ä¡¢UNIX¤Ë¤ª¤±¤ë¿®Íê¾ðÊó (credential) ¤ò´Þ¤ó¤Ç¤¤¤ë¡£
57 À©¸æ¥á¥Ã¥»¡¼¥¸¤Ï¡¢Î㤨¤Ð IP ¥ª¥×¥·¥ç¥ó¤Î¤è¤¦¤ÊÄɲåإåÀ¡¼¥Õ¥£¡¼¥ë¥É¤ò
58 Á÷¤ë¤Î¤Ë»È¤¦»ö¤¬¤Ç¤¤ë¡£
59 .\"O Ancillary data is sent by calling
61 .\"O and received by calling
63 .\"O See their manual pages for more information.
68 ¤ò¸Æ¤Ó½Ð¤·¤Æ¼õ¤±¼è¤ë¡£
69 ¾ÜºÙ¤Ï¤½¤ì¤é¤Î¥Þ¥Ë¥å¥¢¥ë¥Ú¡¼¥¸¤ò»²¾È¡£
71 .\"O Ancillary data is a sequence of
72 .\"O .I struct cmsghdr
73 .\"O structures with appended data.
74 .\"O This sequence should only be accessed
75 .\"O using the macros described in this manual page and never directly.
78 ¹½Â¤ÂΤΥ·¡¼¥±¥ó¥¹¤ËÄɲåǡ¼¥¿¤¬Éղ䵤줿¤â¤Î¤Ç¤¢¤ë¡£
79 ¤³¤Î¥·¡¼¥±¥ó¥¹¤Ë¤Ï¤³¤Î¥Þ¥Ë¥å¥¢¥ë¥Ú¡¼¥¸¤Ë½ñ¤«¤ì¤Æ¤¤¤ë
80 ¥Þ¥¯¥í¤ò»È¤Ã¤Æ¥¢¥¯¥»¥¹¤¹¤Ù¤¤Ç¡¢Ä¾ÀÜ¥¢¥¯¥»¥¹¤¹¤Ù¤¤Ç¤Ï¤Ê¤¤¡£
81 .\"O See the specific protocol man pages for the available control message types.
82 »ÈÍѲÄǽ¤ÊÀ©¸æ¥á¥Ã¥»¡¼¥¸¤Î¥¿¥¤¥×¤Ë¤Ä¤¤¤Æ¤Ï¡¢
83 ¤½¤ì¤¾¤ì¤Î¥×¥í¥È¥³¥ë¤Î¥Þ¥Ë¥å¥¢¥ë¥Ú¡¼¥¸¤ò»²¾È¤Î¤³¤È¡£
84 .\"O The maximum ancillary buffer size allowed per socket can be set using
85 .\"O .IR /proc/sys/net/core/optmem_max ;
88 ÀܳËè¤ÎºÇÂçÊä½õÍѥХåե¡¥µ¥¤¥º¤Ï
89 .I /proc/sys/net/core/optmem_max
94 .\"O .BR CMSG_FIRSTHDR ()
95 .\"O returns a pointer to the first
98 .\"O data buffer associated with the passed
103 ¤Ë´ØÏ¢¤·¤¿Êä½õ¥Ç¡¼¥¿¥Ð¥Ã¥Õ¥¡Ãæ¤Î¡¢ºÇ½é¤Î
107 .\"O .BR CMSG_NXTHDR ()
108 .\"O returns the next valid
110 .\"O after the passed
118 .\"O It returns NULL when there isn't enough space left in the buffer.
119 ¥Ð¥Ã¥Õ¥¡¤Ë½½Ê¬¤Ê¶õ¤¤¬Ìµ¤¤¾ì¹ç¡¢NULL ¤òÊÖ¤¹¡£
121 .\"O .BR CMSG_ALIGN (),
122 .\"O given a length, returns it including the required alignment.
124 .\"O constant expression.
126 ¤ËŤµ¤òÍ¿¤¨¤ë¤È¡¢É¬Íפʥ¢¥é¥¤¥ó¥á¥ó¥È¤ò²ÃÌ£¤·¤¿Ä¹¤µ¤òÊÖ¤·¤Æ¤¯¤ë¡£
129 .\"O .BR CMSG_SPACE ()
130 .\"O returns the number of bytes an ancillary element with payload of the
131 .\"O passed data length occupies.
132 .\"O This is a constant expression.
134 ¤Ï¡¢Í¿¤¨¤¿¥Ç¡¼¥¿Ä¹¤¬Àê¤á¤ë¤Î¤ËɬÍפÊÊä½õÍ×ÁÇ (ancillary element) ¤Î
135 ¥Ð¥¤¥È¿ô¤òÊÖ¤¹¡£¤³¤ì¤ÏÄê¿ô¼°¤Ç¤¢¤ë¡£
137 .\"O .BR CMSG_DATA ()
138 .\"O returns a pointer to the data portion of a
143 ¤Î¥Ç¡¼¥¿Éôʬ¤Ø¤Î¥Ý¥¤¥ó¥¿¤òÊÖ¤¹¡£
146 .\"O returns the value to store in the
150 .\"O structure, taking into account any necessary
152 .\"O It takes the data length as an argument.
153 .\"O This is a constant
160 ¥á¥ó¥Ð¤Ë¥Ç¡¼¥¿¤ò³ÊǼ¤¹¤ëºÝ¤ËɬÍפÊÃͤòÊÖ¤¹¡£¥¢¥é¥¤¥ó¥á¥ó¥È¤â¹Íθ¤ËÆþ¤ì
162 °ú¿ô¤È¤·¤Æ¥Ç¡¼¥¿Ä¹¤ò¤È¤ë¡£¤³¤ì¤ÏÄê¿ô¼°¤Ç¤¢¤ë¡£
164 .\"O To create ancillary data, first initialize the
165 .\"O .I msg_controllen
168 .\"O with the length of the control message buffer.
170 .\"O .BR CMSG_FIRSTHDR ()
173 .\"O to get the first control message and
174 .\"O .BR CMSG_NEXTHDR ()
175 .\"O to get all subsequent ones.
176 Êä½õ¥Ç¡¼¥¿¤òºî¤ë¤¿¤á¤Ë¤ÏºÇ½é¤Ë
180 ¤ò¡¢À©¸æ¥á¥Ã¥»¡¼¥¸¥Ð¥Ã¥Õ¥¡¤ÎŤµ¤Ç½é´ü²½¤¹¤ë¡£
184 ¤ËÍѤ¤¤ë¤ÈºÇ½é¤ÎÀ©¸æ¥á¥Ã¥»¡¼¥¸¤¬ÆÀ¤é¤ì¡¢
186 ¤ò»È¤¦¤È¼¡¤ÎÀ©¸æ¥á¥Ã¥»¡¼¥¸¤¬ÆÀ¤é¤ì¤ë¡£
187 .\"O In each control message, initialize
190 .\"O .BR CMSG_LEN ()),
193 .\"O header fields, and the data portion using
194 .\"O .BR CMSG_DATA ().
195 ¤½¤ì¤¾¤ì¤ÎÀ©¸æ¥á¥Ã¥»¡¼¥¸¤Ç¤Ï¡¢
202 ¥Ø¥Ã¥À¡¼¥Õ¥£¡¼¥ë¥É¡¢¤½¤·¤Æ¥Ç¡¼¥¿Éôʬ¤ËÂФ·¤Æ¤â
204 ¤ò»È¤Ã¤Æ½é´ü²½¤ò¤¹¤ë¡£
206 .\"O .I msg_controllen
209 .\"O should be set to the sum of the
210 .\"O .BR CMSG_SPACE ()
211 .\"O of the length of
212 .\"O all control messages in the buffer.
213 .\"O For more information on the
216 .\"O .BR recvmsg (2).
221 ¥Õ¥£¡¼¥ë¥É¤Ë¡¢¥Ð¥Ã¥Õ¥¡Ãæ¤ÎÀ©¸æ¥á¥Ã¥»¡¼¥¸¤ÎŤµ¤Î
223 ¤Î¹ç·×¤¬¥»¥Ã¥È¤µ¤ì¤ë¡£
229 .\"O When the control message buffer is too short to store all messages, the
231 .\"O flag is set in the
235 À©¸æ¥á¥Ã¥»¡¼¥¸¥Ð¥Ã¥Õ¥¡¤¬Á´¤Æ¤Î¥á¥Ã¥»¡¼¥¸¤òǼ¤á¤ë¤Î¤Ë¤Ïû¤¹¤®¤ë¾ì¹ç¡¢
241 ¥Õ¥é¥°¤¬¥»¥Ã¥È¤µ¤ì¤ë¡£
242 .\"O .SH "CONFORMING TO"
244 .\"O This ancillary data model conforms to the POSIX.1g draft, 4.4BSD-Lite,
245 .\"O the IPv6 advanced API described in RFC\ 2292 and the SUSv2.
246 .\"O .BR CMSG_ALIGN ()
247 .\"O is a Linux extension.
248 ¤³¤ÎÊä½õ¥Ç¡¼¥¿¥â¥Ç¥ë¤Ï¡¢POSIX.1g draft, 4.4BSD-Lite, RFC\ 2292 ¤Ë
249 µ½Ò¤µ¤ì¤Æ¤¤¤ë IPv6 advanced API, ¤½¤·¤Æ SUSv2
252 ¤Ï Linux ¤Î³ÈÄ¥¤Ç¤¢¤ë¡£
254 .\"O For portability, ancillary data should be accessed only using the macros
256 °Ü¿¢À¤Î¤¿¤á¤Ë¡¢Êä½õ¥Ç¡¼¥¿¤Ø¤Î¥¢¥¯¥»¥¹¤Ë¤Ï¡¢
257 ¤³¤³¤Ç½Ò¤Ù¤é¤ì¤Æ¤¤¤ë¥Þ¥¯¥í¤ò»È¤¦¤À¤±¤Ë¤¹¤Ù¤¤Ç¤¢¤ë¡£
259 .\"O is a Linux extension and should be not used in portable programs.
260 ¤Ï Linux ¤Ç¤Î³ÈÄ¥¤Ç¤¢¤ê¡¢°Ü¿¢À¤ò¹Í¤¨¤¿¥×¥í¥°¥é¥à¤Ç¤Ï»È¤¦¤Ù¤¤Ç¤Ï¤Ê¤¤¡£
263 .\"O .BR CMSG_LEN (),
264 .\"O .BR CMSG_DATA (),
266 .\"O .BR CMSG_ALIGN ()
267 .\"O are constant expressions (assuming their argument is constant);
268 .\"O this could be used to declare the size of global
270 .\"O This may be not portable, however.
275 ¤ÏÄê¿ô¼°¤Ç¤¢¤ë (¤½¤ì¤é¤Î°ú¿ô¤¬Äê¿ô¤È¤ß¤Ê¤µ¤ì¤ë)¡£
276 ¤³¤Î¤³¤È¤Ï¡¢Âç°èÊÑ¿ô¤Î¥µ¥¤¥º¤òÀë¸À¤¹¤ë¤Î¤Ë»È¤¨¤ë¡£
277 ¤·¤«¤·°Ü¿¢À¤Ï¤Ê¤¯¤Ê¤ë¤À¤í¤¦¡£
279 .\"O This code looks for the
281 .\"O option in a received ancillary buffer:
282 ¼¡¤Î¥³¡¼¥É¤Ï¡¢¼õ¤±¼è¤Ã¤¿Êä½õ¥Ð¥Ã¥Õ¥¡¤«¤é
284 ¥ª¥×¥·¥ç¥ó¤òõ¤¹¤â¤Î¤Ç¤¢¤ë¡£
289 struct cmsghdr *cmsg;
293 /* Receive auxiliary data in msgh */
294 for (cmsg = CMSG_FIRSTHDR(&msgh); cmsg != NULL;
295 cmsg = CMSG_NXTHDR(&msgh,cmsg)) {
296 if (cmsg\->cmsg_level == IPPROTO_IP
297 && cmsg\->cmsg_type == IP_TTL) {
298 ttlptr = (int *) CMSG_DATA(cmsg);
299 received_ttl = *ttlptr;
305 * Error: IP_TTL not enabled or small buffer
312 .\"O The code below passes an array of file descriptors over a
313 .\"O UNIX domain socket using
314 .\"O .BR SCM_RIGHTS :
317 ¤ò»È¤¤¡¢¥Õ¥¡¥¤¥ë¥Ç¥¹¥¯¥ê¥×¥¿¤ÎÇÛÎó¤ò
318 UNIX ¥É¥á¥¤¥ó¥½¥±¥Ã¥È¤òÄ̤·¤ÆÁ÷¤ë¤â¤Î¤Ç¤¢¤ë¡£
322 struct msghdr msg = {0};
323 struct cmsghdr *cmsg;
324 int myfds[NUM_FD]; /* Contains the file descriptors to pass. */
325 char buf[CMSG_SPACE(sizeof myfds)]; /* ancillary data buffer */
328 msg.msg_control = buf;
329 msg.msg_controllen = sizeof buf;
330 cmsg = CMSG_FIRSTHDR(&msg);
331 cmsg\->cmsg_level = SOL_SOCKET;
332 cmsg\->cmsg_type = SCM_RIGHTS;
333 cmsg\->cmsg_len = CMSG_LEN(sizeof(int) * NUM_FD);
334 /* Initialize the payload: */
335 fdptr = (int *) CMSG_DATA(cmsg);
336 memcpy(fdptr, myfds, NUM_FD * sizeof(int));
337 /* Sum of the length of all control messages in the buffer: */
338 msg.msg_controllen = cmsg\->cmsg_len;