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