draft/man3/cmsg.3

   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 $
   7 .\"
   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>
  13 .\"
  14 .TH CMSG 3 2008-11-20 "Linux" "Linux Programmer's Manual"
  15 .SH Ì¾Á°
  16 .\"O CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- Access ancillary data
  17 CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- Êä½õ¥Ç¡¼¥¿¤Ë¥¢¥¯¥»¥¹¤¹¤ë¡£
  18 .SH ½ñ¼°
  19 .B #include <sys/socket.h>
  20 .sp
  21 .BI "struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *" msgh );
  22 .br
  23 .BI "struct cmsghdr *CMSG_NXTHDR(struct msghdr *" msgh ", struct cmsghdr *" cmsg );
  24 .br
  25 .BI "size_t CMSG_ALIGN(size_t " length );
  26 .br
  27 .BI "size_t CMSG_SPACE(size_t " length );
  28 .br
  29 .BI "size_t CMSG_LEN(size_t " length );
  30 .br
  31 .BI "unsigned char *CMSG_DATA(struct cmsghdr *" cmsg );
  32 .sp
  33 .nf
  34 struct cmsghdr {
  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[]; */
  39 };
  40 .fi
  41 .SH ÀâÌÀ
  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
  51 .\"O credentials.
  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
  60 .\"O .BR sendmsg (2)
  61 .\"O and received by calling
  62 .\"O .BR recvmsg (2).
  63 .\"O See their manual pages for more information.
  64 Êä½õ¥Ç¡¼¥¿¤Ï¡¢
  65 .BR sendmsg (2)
  66 ¤ò¸Æ¤Ó½Ð¤·¤ÆÁ÷¤ê¡¢
  67 .BR recvmsg (2)
  68 ¤ò¸Æ¤Ó½Ð¤·¤Æ¼õ¤±¼è¤ë¡£
  69 ¾ÜºÙ¤Ï¤½¤ì¤é¤Î¥Þ¥Ë¥å¥¢¥ë¥Ú¡¼¥¸¤ò»²¾È¡£
  70 .PP
  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.
  76 Êä½õ¥Ç¡¼¥¿¤Ï
  77 .I struct cmsghdr
  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 ;
  86 .\"O see
  87 .\"O .BR socket (7).
  88 ÀÜÂ³Ëè¤ÎºÇÂçÊä½õÍÑ¥Ð¥Ã¥Õ¥¡¥µ¥¤¥º¤Ï
  89 .I /proc/sys/net/core/optmem_max
  90 ¤ò»È¤Ã¤ÆÀßÄê¤Ç¤¤ë¡£
  91 .BR socket (7)
  92 ¤ò»²¾È¡£
  93 .PP
  94 .\"O .BR CMSG_FIRSTHDR ()
  95 .\"O returns a pointer to the first
  96 .\"O .I cmsghdr
  97 .\"O in the ancillary
  98 .\"O data buffer associated with the passed
  99 .\"O .IR msghdr .
 100 .BR CMSG_FIRSTHDR ()
 101 ¤Ï¡¢ÅÏ¤·¤¿
 102 .I msghdr
 103 ¤Ë´ØÏ¢¤·¤¿Êä½õ¥Ç¡¼¥¿¥Ð¥Ã¥Õ¥¡Ãæ¤Î¡¢ºÇ½é¤Î
 104 .I cmsghdr
 105 ¤Ø¤Î¥Ý¥¤¥ó¥¿¤òÊÖ¤¹¡£
 106 .PP
 107 .\"O .BR CMSG_NXTHDR ()
 108 .\"O returns the next valid
 109 .\"O .I cmsghdr
 110 .\"O after the passed
 111 .\"O .IR cmsghdr .
 112 .BR CMSG_NXTHDR ()
 113 ¤Ï¡¢ÅÏ¤·¤¿
 114 .I cmsghdr
 115 ¤Î¼¡¤Ë¤¯¤ë (Í¸ú¤Ê)
 116 .I cmsghdr
 117 ¤òÊÖ¤¹¡£
 118 .\"O It returns NULL when there isn't enough space left in the buffer.
 119 ¥Ð¥Ã¥Õ¥¡¤Ë½½Ê¬¤Ê¶õ¤¤¬Ìµ¤¤¾ì¹ç¡¢NULL ¤òÊÖ¤¹¡£
 120 .PP
 121 .\"O .BR CMSG_ALIGN (),
 122 .\"O given a length, returns it including the required alignment.
 123 .\"O This is a
 124 .\"O constant expression.
 125 .BR CMSG_ALIGN ()
 126 ¤ËÄ¹¤µ¤òÍ¿¤¨¤ë¤È¡¢É¬Í×¤Ê¥¢¥é¥¤¥ó¥á¥ó¥È¤ò²ÃÌ£¤·¤¿Ä¹¤µ¤òÊÖ¤·¤Æ¤¯¤ë¡£
 127 ¤³¤ì¤ÏÄê¿ô¼°¤Ç¤¢¤ë¡£
 128 .PP
 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.
 133 .BR CMSG_SPACE ()
 134 ¤Ï¡¢Í¿¤¨¤¿¥Ç¡¼¥¿Ä¹¤¬Àê¤á¤ë¤Î¤ËÉ¬Í×¤ÊÊä½õÍ×ÁÇ (ancillary element) ¤Î
 135 ¥Ð¥¤¥È¿ô¤òÊÖ¤¹¡£¤³¤ì¤ÏÄê¿ô¼°¤Ç¤¢¤ë¡£
 136 .PP
 137 .\"O .BR CMSG_DATA ()
 138 .\"O returns a pointer to the data portion of a
 139 .\"O .IR cmsghdr .
 140 .BR CMSG_DATA ()
 141 ¤Ï¡¢
 142 .I cmsghdr
 143 ¤Î¥Ç¡¼¥¿ÉôÊ¬¤Ø¤Î¥Ý¥¤¥ó¥¿¤òÊÖ¤¹¡£
 144 .PP
 145 .\"O .BR CMSG_LEN ()
 146 .\"O returns the value to store in the
 147 .\"O .I cmsg_len
 148 .\"O member of the
 149 .\"O .I cmsghdr
 150 .\"O structure, taking into account any necessary
 151 .\"O alignment.
 152 .\"O It takes the data length as an argument.
 153 .\"O This is a constant
 154 .\"O expression.
 155 .BR CMSG_LEN ()
 156 ¤Ï¡¢
 157 .I cmsghdr
 158 ¹½Â¤ÂÎ¤Î
 159 .I cmsg_len
 160 ¥á¥ó¥Ð¤Ë¥Ç¡¼¥¿¤ò³ÊÇ¼¤¹¤ëºÝ¤ËÉ¬Í×¤ÊÃÍ¤òÊÖ¤¹¡£¥¢¥é¥¤¥ó¥á¥ó¥È¤â¹ÍÎ¸¤ËÆþ¤ì
 161 ¤é¤ì¤ë¡£
 162 °ú¿ô¤È¤·¤Æ¥Ç¡¼¥¿Ä¹¤ò¤È¤ë¡£¤³¤ì¤ÏÄê¿ô¼°¤Ç¤¢¤ë¡£
 163 .PP
 164 .\"O To create ancillary data, first initialize the
 165 .\"O .I msg_controllen
 166 .\"O member of the
 167 .\"O .I msghdr
 168 .\"O with the length of the control message buffer.
 169 .\"O Use
 170 .\"O .BR CMSG_FIRSTHDR ()
 171 .\"O on the
 172 .\"O .I msghdr
 173 .\"O to get the first control message and
 174 .\"O .BR CMSG_NXTHDR ()
 175 .\"O to get all subsequent ones.
 176 Êä½õ¥Ç¡¼¥¿¤òºî¤ë¤¿¤á¤Ë¤ÏºÇ½é¤Ë
 177 .I msghdr
 178 ¤Î¥á¥ó¥Ð¡¼
 179 .I msg_controllen
 180 ¤ò¡¢À©¸æ¥á¥Ã¥»¡¼¥¸¥Ð¥Ã¥Õ¥¡¤ÎÄ¹¤µ¤Ç½é´ü²½¤¹¤ë¡£
 181 .BR CMSG_FIRSTHDR ()
 182 ¤ò
 183 .I msghdr
 184 ¤ËÍÑ¤¤¤ë¤ÈºÇ½é¤ÎÀ©¸æ¥á¥Ã¥»¡¼¥¸¤¬ÆÀ¤é¤ì¡¢
 185 .BR CMSG_NXTHDR ()
 186 ¤ò»È¤¦¤È¼¡¤ÎÀ©¸æ¥á¥Ã¥»¡¼¥¸¤¬ÆÀ¤é¤ì¤ë¡£
 187 .\"O In each control message, initialize
 188 .\"O .I cmsg_len
 189 .\"O (with
 190 .\"O .BR CMSG_LEN ()),
 191 .\"O the other
 192 .\"O .I cmsghdr
 193 .\"O header fields, and the data portion using
 194 .\"O .BR CMSG_DATA ().
 195 ¤½¤ì¤¾¤ì¤ÎÀ©¸æ¥á¥Ã¥»¡¼¥¸¤Ç¤Ï¡¢
 196 .I cmsg_len
 197 ¤ò½é´ü²½¤¹¤ë
 198 .RB ( CMSG_LEN ()
 199 ¤ò»È¤¦)¡£
 200 ¤½¤ÎÂ¾¤Î
 201 .I cmsghdr
 202 ¥Ø¥Ã¥À¡¼¥Õ¥£¡¼¥ë¥É¡¢¤½¤·¤Æ¥Ç¡¼¥¿ÉôÊ¬¤ËÂÐ¤·¤Æ¤â
 203 .BR CMSG_DATA ()
 204 ¤ò»È¤Ã¤Æ½é´ü²½¤ò¤¹¤ë¡£
 205 .\"O Finally, the
 206 .\"O .I msg_controllen
 207 .\"O field of the
 208 .\"O .I msghdr
 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
 214 .\"O .IR msghdr ,
 215 .\"O see
 216 .\"O .BR recvmsg (2).
 217 ºÇ¸å¤Ë
 218 .I msghdr
 219 ¤Î
 220 .I msg_controllen
 221 ¥Õ¥£¡¼¥ë¥É¤Ë¡¢¥Ð¥Ã¥Õ¥¡Ãæ¤ÎÀ©¸æ¥á¥Ã¥»¡¼¥¸¤ÎÄ¹¤µ¤Î
 222 .BR CMSG_SPACE ()
 223 ¤Î¹ç·×¤¬¥»¥Ã¥È¤µ¤ì¤ë¡£
 224 .I msghdr
 225 ¤Ë¤Ä¤¤¤Æ¤Î¾ÜºÙ¤Ï
 226 .BR recvmsg (2)
 227 ¤ò»²¾È¡£
 228 .PP
 229 .\"O When the control message buffer is too short to store all messages, the
 230 .\"O .B MSG_CTRUNC
 231 .\"O flag is set in the
 232 .\"O .I msg_flags
 233 .\"O member of the
 234 .\"O .IR msghdr .
 235 À©¸æ¥á¥Ã¥»¡¼¥¸¥Ð¥Ã¥Õ¥¡¤¬Á´¤Æ¤Î¥á¥Ã¥»¡¼¥¸¤òÇ¼¤á¤ë¤Î¤Ë¤ÏÃ»¤¹¤®¤ë¾ì¹ç¡¢
 236 .I msghdr
 237 ¤Î
 238 .I msg_flags
 239 ¥á¥ó¥Ð¡¼¤Ë
 240 .B MSG_CTRUNC
 241 ¥Õ¥é¥°¤¬¥»¥Ã¥È¤µ¤ì¤ë¡£
 242 .\"O .SH "CONFORMING TO"
 243 .SH ½àµò
 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
 250 ¤Ë½àµò¤·¤Æ¤¤¤ë¡£
 251 .BR CMSG_ALIGN ()
 252 ¤Ï Linux ¤Î³ÈÄ¥¤Ç¤¢¤ë¡£
 253 .SH Ãí°Õ
 254 .\"O For portability, ancillary data should be accessed only using the macros
 255 .\"O described here.
 256 °Ü¿¢À¤Î¤¿¤á¤Ë¡¢Êä½õ¥Ç¡¼¥¿¤Ø¤Î¥¢¥¯¥»¥¹¤Ë¤Ï¡¢
 257 ¤³¤³¤Ç½Ò¤Ù¤é¤ì¤Æ¤¤¤ë¥Þ¥¯¥í¤ò»È¤¦¤À¤±¤Ë¤¹¤Ù¤¤Ç¤¢¤ë¡£
 258 .BR CMSG_ALIGN ()
 259 .\"O is a Linux extension and should be not used in portable programs.
 260 ¤Ï Linux ¤Ç¤Î³ÈÄ¥¤Ç¤¢¤ê¡¢°Ü¿¢À¤ò¹Í¤¨¤¿¥×¥í¥°¥é¥à¤Ç¤Ï»È¤¦¤Ù¤¤Ç¤Ï¤Ê¤¤¡£
 261 .PP
 262 .\"O In Linux,
 263 .\"O .BR CMSG_LEN (),
 264 .\"O .BR CMSG_DATA (),
 265 .\"O and
 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
 269 .\"O variables.
 270 .\"O This may be not portable, however.
 271 Linux ¤Ç¤Ï
 272 .BR CMSG_LEN (),
 273 .BR CMSG_DATA (),
 274 .BR CMSG_ALIGN ()
 275 ¤ÏÄê¿ô¼°¤Ç¤¢¤ë (¤½¤ì¤é¤Î°ú¿ô¤¬Äê¿ô¤È¤ß¤Ê¤µ¤ì¤ë)¡£
 276 ¤³¤Î¤³¤È¤Ï¡¢Âç°èÊÑ¿ô¤Î¥µ¥¤¥º¤òÀë¸À¤¹¤ë¤Î¤Ë»È¤¨¤ë¡£
 277 ¤·¤«¤·°Ü¿¢À¤Ï¤Ê¤¯¤Ê¤ë¤À¤í¤¦¡£
 278 .SH Îã
 279 .\"O This code looks for the
 280 .\"O .B IP_TTL
 281 .\"O option in a received ancillary buffer:
 282 ¼¡¤Î¥³¡¼¥É¤Ï¡¢¼õ¤±¼è¤Ã¤¿Êä½õ¥Ð¥Ã¥Õ¥¡¤«¤é
 283 .B IP_TTL
 284 ¥ª¥×¥·¥ç¥ó¤òÃµ¤¹¤â¤Î¤Ç¤¢¤ë¡£
 285 .PP
 286 .in +4n
 287 .nf
 288 struct msghdr msgh;
 289 struct cmsghdr *cmsg;
 290 int *ttlptr;
 291 int received_ttl;
 292
 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;
 300         break;
 301     }
 302 }
 303 if (cmsg == NULL) {
 304     /*
 305      * Error: IP_TTL not enabled or small buffer
 306      * or I/O error.
 307      */
 308 }
 309 .fi
 310 .in
 311 .PP
 312 .\"O The code below passes an array of file descriptors over a
 313 .\"O UNIX domain socket using
 314 .\"O .BR SCM_RIGHTS :
 315 °Ê²¼¤Î¥³¡¼¥É¤Ï¡¢
 316 .B SCM_RIGHTS
 317 ¤ò»È¤¤¡¢¥Õ¥¡¥¤¥ë¥Ç¥¹¥¯¥ê¥×¥¿¤ÎÇÛÎó¤ò
 318 UNIX ¥É¥á¥¤¥ó¥½¥±¥Ã¥È¤òÄÌ¤·¤ÆÁ÷¤ë¤â¤Î¤Ç¤¢¤ë¡£
 319 .PP
 320 .in +4n
 321 .nf
 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 */
 326 int *fdptr;
 327
 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;
 339 .fi
 340 .in
 341 .SH ´ØÏ¢¹àÌÜ
 342 .BR recvmsg (2),
 343 .BR sendmsg (2)
 344 .PP
 345 RFC\ 2292