release/man3/cmsg.3

   1 .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM_ONE_PARA)
   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.
   8 .\" %%%LICENSE_END
   9 .\"
  10 .\" $Id: cmsg.3,v 1.8 2000/12/20 18:10:31 ak Exp $
  11 .\"*******************************************************************
  12 .\"
  13 .\" This file was generated with po4a. Translate the source file.
  14 .\"
  15 .\"*******************************************************************
  16 .TH CMSG 3 2008\-11\-20 Linux "Linux Programmer's Manual"
  17 .SH 名前
  18 CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- 補助データにアクセスする。
  19 .SH 書式
  20 \fB#include <sys/socket.h>\fP
  21 .sp
  22 \fBstruct cmsghdr *CMSG_FIRSTHDR(struct msghdr *\fP\fImsgh\fP\fB);\fP
  23 .br
  24 \fBstruct cmsghdr *CMSG_NXTHDR(struct msghdr *\fP\fImsgh\fP\fB, struct cmsghdr
  25 *\fP\fIcmsg\fP\fB);\fP
  26 .br
  27 \fBsize_t CMSG_ALIGN(size_t \fP\fIlength\fP\fB);\fP
  28 .br
  29 \fBsize_t CMSG_SPACE(size_t \fP\fIlength\fP\fB);\fP
  30 .br
  31 \fBsize_t CMSG_LEN(size_t \fP\fIlength\fP\fB);\fP
  32 .br
  33 \fBunsigned char *CMSG_DATA(struct cmsghdr *\fP\fIcmsg\fP\fB);\fP
  34 .sp
  35 .nf
  36 struct cmsghdr {
  37     socklen_t cmsg_len;    /* data byte count, including header */
  38     int       cmsg_level;  /* originating protocol */
  39     int       cmsg_type;   /* protocol\-specific type */
  40     /* followed by unsigned char cmsg_data[]; */
  41 };
  42 .fi
  43 .SH 説明
  44 これらのマクロは制御メッセージ (補助データ (ancillary data) とも呼ばれる) を作り、 それにアクセスするために使われる。
  45 制御メッセージはソケットにのるデータではない。 この制御情報は、到着したパケットへのインターフェイス、様々なあまり
  46 使われないヘッダーフィールド、エラー記述の拡張、ファイルデスクリ プタの集合や、UNIXにおける信頼情報 (credential) を含んでいる。
  47 制御メッセージは、例えば IP オプションのような追加ヘッダーフィールドを 送るのに使う事ができる。 補助データは、 \fBsendmsg\fP(2)
  48 を呼び出して送り、 \fBrecvmsg\fP(2)  を呼び出して受け取る。 詳細はそれらのマニュアルページを参照。
  49 .PP
  50 補助データは \fIstruct cmsghdr\fP 構造体のシーケンスに追加データが付加されたものである。
  51 このシーケンスにはこのマニュアルページに書かれている マクロを使ってアクセスすべきで、直接アクセスすべきではない。
  52 使用可能な制御メッセージのタイプについては、 それぞれのプロトコルのマニュアルページを参照のこと。 接続毎の最大補助用バッファサイズは
  53 \fI/proc/sys/net/core/optmem_max\fP を使って設定できる。 \fBsocket\fP(7)  を参照。
  54 .PP
  55 \fBCMSG_FIRSTHDR\fP()  は、渡した \fImsghdr\fP に関連した補助データバッファ中の、最初の \fIcmsghdr\fP
  56 へのポインタを返す。
  57 .PP
  58 \fBCMSG_NXTHDR\fP()  は、渡した \fIcmsghdr\fP の次にくる (有効な)  \fIcmsghdr\fP を返す。
  59 バッファに十分な空きが無い場合、NULL を返す。
  60 .PP
  61 \fBCMSG_ALIGN\fP()  に長さを与えると、必要なアラインメントを加味した長さを返してくる。 これは定数式である。
  62 .PP
  63 \fBCMSG_SPACE\fP()  は、与えたデータ長が占めるのに必要な補助要素 (ancillary element) の
  64 バイト数を返す。これは定数式である。
  65 .PP
  66 \fBCMSG_DATA\fP()  は、 \fIcmsghdr\fP のデータ部分へのポインタを返す。
  67 .PP
  68 \fBCMSG_LEN\fP()  は、 \fIcmsghdr\fP 構造体の \fIcmsg_len\fP
  69 メンバにデータを格納する際に必要な値を返す。アラインメントも考慮に入れ られる。 引数としてデータ長をとる。これは定数式である。
  70 .PP
  71 補助データを作るためには最初に \fImsghdr\fP のメンバー \fImsg_controllen\fP を、制御メッセージバッファの長さで初期化する。
  72 \fBCMSG_FIRSTHDR\fP()  を \fImsghdr\fP に用いると最初の制御メッセージが得られ、 \fBCMSG_NXTHDR\fP()
  73 を使うと次の制御メッセージが得られる。 それぞれの制御メッセージでは、 \fIcmsg_len\fP を初期化する (\fBCMSG_LEN\fP()  を使う)。
  74 その他の \fIcmsghdr\fP ヘッダーフィールド、そしてデータ部分に対しても \fBCMSG_DATA\fP()  を使って初期化をする。 最後に
  75 \fImsghdr\fP の \fImsg_controllen\fP フィールドに、バッファ中の制御メッセージの長さの \fBCMSG_SPACE\fP()
  76 の合計がセットされる。 \fImsghdr\fP についての詳細は \fBrecvmsg\fP(2)  を参照。
  77 .PP
  78 制御メッセージバッファが全てのメッセージを納めるのには短すぎる場合、 \fImsghdr\fP の \fImsg_flags\fP メンバーに
  79 \fBMSG_CTRUNC\fP フラグがセットされる。
  80 .SH 準拠
  81 この補助データモデルは、POSIX.1g draft, 4.4BSD\-Lite, RFC\ 2292 に 記述されている IPv6 advanced
  82 API, そして SUSv2 に準拠している。 \fBCMSG_ALIGN\fP()  は Linux の拡張である。
  83 .SH 注意
  84 移植性のために、補助データへのアクセスには、 ここで述べられているマクロだけを使うべきである。 \fBCMSG_ALIGN\fP()  は Linux
  85 での拡張であり、移植性を考えたプログラムでは使うべきではない。
  86 .PP
  87 Linux では \fBCMSG_LEN\fP(), \fBCMSG_DATA\fP(), \fBCMSG_ALIGN\fP()  は定数式である
  88 (それらの引数が定数とみなされる)。 このことは、大域変数のサイズを宣言するのに使える。 しかし移植性はなくなるだろう。
  89 .SH 例
  90 次のコードは、受け取った補助バッファから \fBIP_TTL\fP オプションを探すものである。
  91 .PP
  92 .in +4n
  93 .nf
  94 struct msghdr msgh;
  95 struct cmsghdr *cmsg;
  96 int *ttlptr;
  97 int received_ttl;
  98
  99 /* Receive auxiliary data in msgh */
 100 for (cmsg = CMSG_FIRSTHDR(&msgh); cmsg != NULL;
 101         cmsg = CMSG_NXTHDR(&msgh,cmsg)) {
 102     if (cmsg\->cmsg_level == IPPROTO_IP
 103             && cmsg\->cmsg_type == IP_TTL) {
 104         ttlptr = (int *) CMSG_DATA(cmsg);
 105         received_ttl = *ttlptr;
 106         break;
 107     }
 108 }
 109 if (cmsg == NULL) {
 110     /*
 111      * Error: IP_TTL not enabled or small buffer
 112      * or I/O error.
 113      */
 114 }
 115 .fi
 116 .in
 117 .PP
 118 以下のコードは、 \fBSCM_RIGHTS\fP を使い、ファイルデスクリプタの配列を UNIX ドメインソケットを通して送るものである。
 119 .PP
 120 .in +4n
 121 .nf
 122 struct msghdr msg = {0};
 123 struct cmsghdr *cmsg;
 124 int myfds[NUM_FD]; /* Contains the file descriptors to pass. */
 125 char buf[CMSG_SPACE(sizeof myfds)];  /* ancillary data buffer */
 126 int *fdptr;
 127
 128 msg.msg_control = buf;
 129 msg.msg_controllen = sizeof buf;
 130 cmsg = CMSG_FIRSTHDR(&msg);
 131 cmsg\->cmsg_level = SOL_SOCKET;
 132 cmsg\->cmsg_type = SCM_RIGHTS;
 133 cmsg\->cmsg_len = CMSG_LEN(sizeof(int) * NUM_FD);
 134 /* Initialize the payload: */
 135 fdptr = (int *) CMSG_DATA(cmsg);
 136 memcpy(fdptr, myfds, NUM_FD * sizeof(int));
 137 /* Sum of the length of all control messages in the buffer: */
 138 msg.msg_controllen = cmsg\->cmsg_len;
 139 .fi
 140 .in
 141 .SH 関連項目
 142 \fBrecvmsg\fP(2), \fBsendmsg\fP(2)
 143 .PP
 144 RFC\ 2292
 145 .SH この文書について
 146 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.53 の一部
 147 である。プロジェクトの説明とバグ報告に関する情報は
 148 http://www.kernel.org/doc/man\-pages/ に書かれている。