manual/LDP_man-pages/release/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 CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- 補助データにアクセスする。
  17 .SH 書式
  18 .B #include <sys/socket.h>
  19 .sp
  20 .BI "struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *" msgh );
  21 .br
  22 .BI "struct cmsghdr *CMSG_NXTHDR(struct msghdr *" msgh ", struct cmsghdr *" cmsg );
  23 .br
  24 .BI "size_t CMSG_ALIGN(size_t " length );
  25 .br
  26 .BI "size_t CMSG_SPACE(size_t " length );
  27 .br
  28 .BI "size_t CMSG_LEN(size_t " length );
  29 .br
  30 .BI "unsigned char *CMSG_DATA(struct cmsghdr *" cmsg );
  31 .sp
  32 .nf
  33 struct cmsghdr {
  34     socklen_t cmsg_len;    /* data byte count, including header */
  35     int       cmsg_level;  /* originating protocol */
  36     int       cmsg_type;   /* protocol-specific type */
  37     /* followed by unsigned char cmsg_data[]; */
  38 };
  39 .fi
  40 .SH 説明
  41 これらのマクロは制御メッセージ
  42 (補助データ (ancillary data) とも呼ばれる) を作り、
  43 それにアクセスするために使われる。
  44 制御メッセージはソケットにのるデータではない。
  45 この制御情報は、到着したパケットへのインターフェイス、様々なあまり
  46 使われないヘッダーフィールド、エラー記述の拡張、ファイルデスクリ
  47 プタの集合や、UNIXにおける信頼情報 (credential) を含んでいる。
  48 制御メッセージは、例えば IP オプションのような追加ヘッダーフィールドを
  49 送るのに使う事ができる。
  50 補助データは、
  51 .BR sendmsg (2)
  52 を呼び出して送り、
  53 .BR recvmsg (2)
  54 を呼び出して受け取る。
  55 詳細はそれらのマニュアルページを参照。
  56 .PP
  57 補助データは
  58 .I struct cmsghdr
  59 構造体のシーケンスに追加データが付加されたものである。
  60 このシーケンスにはこのマニュアルページに書かれている
  61 マクロを使ってアクセスすべきで、直接アクセスすべきではない。
  62 使用可能な制御メッセージのタイプについては、
  63 それぞれのプロトコルのマニュアルページを参照のこと。
  64 接続毎の最大補助用バッファサイズは
  65 .I /proc/sys/net/core/optmem_max
  66 を使って設定できる。
  67 .BR socket (7)
  68 を参照。
  69 .PP
  70 .BR CMSG_FIRSTHDR ()
  71 は、渡した
  72 .I msghdr
  73 に関連した補助データバッファ中の、最初の
  74 .I cmsghdr
  75 へのポインタを返す。
  76 .PP
  77 .BR CMSG_NXTHDR ()
  78 は、渡した
  79 .I cmsghdr
  80 の次にくる (有効な)
  81 .I cmsghdr
  82 を返す。
  83 バッファに十分な空きが無い場合、NULL を返す。
  84 .PP
  85 .BR CMSG_ALIGN ()
  86 に長さを与えると、必要なアラインメントを加味した長さを返してくる。
  87 これは定数式である。
  88 .PP
  89 .BR CMSG_SPACE ()
  90 は、与えたデータ長が占めるのに必要な補助要素 (ancillary element) の
  91 バイト数を返す。これは定数式である。
  92 .PP
  93 .BR CMSG_DATA ()
  94 は、
  95 .I cmsghdr
  96 のデータ部分へのポインタを返す。
  97 .PP
  98 .BR CMSG_LEN ()
  99 は、
 100 .I cmsghdr
 101 構造体の
 102 .I cmsg_len
 103 メンバにデータを格納する際に必要な値を返す。アラインメントも考慮に入れ
 104 られる。
 105 引数としてデータ長をとる。これは定数式である。
 106 .PP
 107 補助データを作るためには最初に
 108 .I msghdr
 109 のメンバー
 110 .I msg_controllen
 111 を、制御メッセージバッファの長さで初期化する。
 112 .BR CMSG_FIRSTHDR ()
 113 を
 114 .I msghdr
 115 に用いると最初の制御メッセージが得られ、
 116 .BR CMSG_NXTHDR ()
 117 を使うと次の制御メッセージが得られる。
 118 それぞれの制御メッセージでは、
 119 .I cmsg_len
 120 を初期化する
 121 .RB ( CMSG_LEN ()
 122 を使う)。
 123 その他の
 124 .I cmsghdr
 125 ヘッダーフィールド、そしてデータ部分に対しても
 126 .BR CMSG_DATA ()
 127 を使って初期化をする。
 128 最後に
 129 .I msghdr
 130 の
 131 .I msg_controllen
 132 フィールドに、バッファ中の制御メッセージの長さの
 133 .BR CMSG_SPACE ()
 134 の合計がセットされる。
 135 .I msghdr
 136 についての詳細は
 137 .BR recvmsg (2)
 138 を参照。
 139 .PP
 140 制御メッセージバッファが全てのメッセージを納めるのには短すぎる場合、
 141 .I msghdr
 142 の
 143 .I msg_flags
 144 メンバーに
 145 .B MSG_CTRUNC
 146 フラグがセットされる。
 147 .SH 準拠
 148 この補助データモデルは、POSIX.1g draft, 4.4BSD-Lite, RFC\ 2292 に
 149 記述されている IPv6 advanced API, そして SUSv2
 150 に準拠している。
 151 .BR CMSG_ALIGN ()
 152 は Linux の拡張である。
 153 .SH 注意
 154 移植性のために、補助データへのアクセスには、
 155 ここで述べられているマクロを使うだけにすべきである。
 156 .BR CMSG_ALIGN ()
 157 は Linux での拡張であり、移植性を考えたプログラムでは使うべきではない。
 158 .PP
 159 Linux では
 160 .BR CMSG_LEN (),
 161 .BR CMSG_DATA (),
 162 .BR CMSG_ALIGN ()
 163 は定数式である (それらの引数が定数とみなされる)。
 164 このことは、大域変数のサイズを宣言するのに使える。
 165 しかし移植性はなくなるだろう。
 166 .SH 例
 167 次のコードは、受け取った補助バッファから
 168 .B IP_TTL
 169 オプションを探すものである。
 170 .PP
 171 .in +4n
 172 .nf
 173 struct msghdr msgh;
 174 struct cmsghdr *cmsg;
 175 int *ttlptr;
 176 int received_ttl;
 177
 178 /* Receive auxiliary data in msgh */
 179 for (cmsg = CMSG_FIRSTHDR(&msgh); cmsg != NULL;
 180         cmsg = CMSG_NXTHDR(&msgh,cmsg)) {
 181     if (cmsg\->cmsg_level == IPPROTO_IP
 182             && cmsg\->cmsg_type == IP_TTL) {
 183         ttlptr = (int *) CMSG_DATA(cmsg);
 184         received_ttl = *ttlptr;
 185         break;
 186     }
 187 }
 188 if (cmsg == NULL) {
 189     /*
 190      * Error: IP_TTL not enabled or small buffer
 191      * or I/O error.
 192      */
 193 }
 194 .fi
 195 .in
 196 .PP
 197 以下のコードは、
 198 .B SCM_RIGHTS
 199 を使い、ファイルデスクリプタの配列を
 200 UNIX ドメインソケットを通して送るものである。
 201 .PP
 202 .in +4n
 203 .nf
 204 struct msghdr msg = {0};
 205 struct cmsghdr *cmsg;
 206 int myfds[NUM_FD]; /* Contains the file descriptors to pass. */
 207 char buf[CMSG_SPACE(sizeof myfds)];  /* ancillary data buffer */
 208 int *fdptr;
 209
 210 msg.msg_control = buf;
 211 msg.msg_controllen = sizeof buf;
 212 cmsg = CMSG_FIRSTHDR(&msg);
 213 cmsg\->cmsg_level = SOL_SOCKET;
 214 cmsg\->cmsg_type = SCM_RIGHTS;
 215 cmsg\->cmsg_len = CMSG_LEN(sizeof(int) * NUM_FD);
 216 /* Initialize the payload: */
 217 fdptr = (int *) CMSG_DATA(cmsg);
 218 memcpy(fdptr, myfds, NUM_FD * sizeof(int));
 219 /* Sum of the length of all control messages in the buffer: */
 220 msg.msg_controllen = cmsg\->cmsg_len;
 221 .fi
 222 .in
 223 .SH 関連項目
 224 .BR recvmsg (2),
 225 .BR sendmsg (2)
 226 .PP
 227 RFC\ 2292