Provided by: manpages-ja-dev_0.5.0.0.20210215+dfsg-1_all bug

名前

       CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR - 補助データにアクセスする。

書式

       #include <sys/socket.h>

       struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *msgh);
       struct cmsghdr *CMSG_NXTHDR(struct msghdr *msgh, struct cmsghdr *cmsg);
       size_t CMSG_ALIGN(size_t length);
       size_t CMSG_SPACE(size_t length);
       size_t CMSG_LEN(size_t length);
       unsigned char *CMSG_DATA(struct cmsghdr *cmsg);

       struct cmsghdr {
           socklen_t cmsg_len;    /* data byte count, including header */
           int       cmsg_level;  /* originating protocol */
           int       cmsg_type;   /* protocol-specific type */
           /* followed by unsigned char cmsg_data[]; */
       };

説明

       これらのマクロは制御メッセージ (補助データ (ancillary data) とも呼ばれる) を作り、 それにアクセスするため
       に使われる。 制御メッセージはソケットにのるデータではない。  この制御情報は、到着したパケットへのインター
       フェイス、様々なあまり     使われないヘッダーフィールド、エラー記述の拡張、ファイルデスクリ    プタの集合
       や、UNIXにおける信頼情報 (credential) を含んでいる。 制御メッセージは、例えば  IP  オプションのような追加
       ヘッダーフィールドを 送るのに使う事ができる。 補助データは、 sendmsg(2) を呼び出して送り、 recvmsg(2)  を
       呼び出して受け取る。 詳細はそれらのマニュアルページを参照。

       補助データは struct cmsghdr 構造体のシーケンスに追加データが付加されたものである。 このシーケンスにはこの
       マニュアルページに書かれている  マクロを使ってアクセスすべきで、直接アクセスすべきではない。 使用可能な制
       御メッセージのタイプについては、 それぞれのプロトコルのマニュアルページを参照のこと。  接続毎の最大補助用
       バッファーサイズは /proc/sys/net/core/optmem_max を使って設定できる。 socket(7)  を参照。

       CMSG_FIRSTHDR()   は、渡した msghdr に関連した補助データバッファー中の、最初の cmsghdr へのポインターを返
       す。

       CMSG_NXTHDR()  は、渡した cmsghdr の次にくる (有効な)   cmsghdr  を返す。  バッファーに十分な空きが無い場
       合、NULL を返す。

       CMSG_ALIGN()  に長さを与えると、必要なアラインメントを加味した長さを返してくる。 これは定数式である。

       CMSG_SPACE()   は、与えたデータ長が占めるのに必要な補助要素 (ancillary element) の バイト数を返す。これは
       定数式である。

       CMSG_DATA()  は、 cmsghdr のデータ部分へのポインターを返す。

       CMSG_LEN()  は、 cmsghdr 構造体の cmsg_len メンバにデータを格納する際に必要な値を返す。アラインメントも考
       慮に入れ られる。 引数としてデータ長をとる。これは定数式である。

       補助データを作るためには最初に  msghdr のメンバー msg_controllen を、制御メッセージバッファーの長さで初期
       化する。 CMSG_FIRSTHDR()  を msghdr に用いると最初の制御メッセージが得られ、 CMSG_NXTHDR() を使うと次の制
       御メッセージが得られる。 それぞれの制御メッセージでは、 cmsg_len を初期化する (CMSG_LEN()  を使う)。 その
       他の cmsghdr ヘッダーフィールド、そしてデータ部分に対しても  CMSG_DATA()   を使って初期化をする。  最後に
       msghdrmsg_controllen フィールドに、バッファー中の制御メッセージの長さの CMSG_SPACE() の合計がセットさ
       れる。 msghdr についての詳細は recvmsg(2)  を参照。

       制御メッセージバッファーが全てのメッセージを納めるのには短すぎる場合、  msghdrmsg_flags  メンバーに
       MSG_CTRUNC フラグがセットされる。

準拠

       この補助データモデルは、POSIX.1g draft, 4.4BSD-Lite, RFC 2292 に 記述されている IPv6 advanced API, そして
       SUSv2 に準拠している。 CMSG_ALIGN()  は Linux の拡張である。

注意

       移植性のために、補助データへのアクセスには、             ここで述べられているマクロだけを使うべきである。
       CMSG_ALIGN()  は Linux での拡張であり、移植性を考えたプログラムでは使うべきではない。

       Linux  では CMSG_LEN(), CMSG_DATA(), CMSG_ALIGN()  は定数式である (それらの引数が定数とみなされる)。 この
       ことは、大域変数のサイズを宣言するのに使える。 しかし移植性はなくなるだろう。

       次のコードは、受け取った補助バッファーから IP_TTL オプションを探すものである。

           struct msghdr msgh;
           struct cmsghdr *cmsg;
           int *ttlptr;
           int received_ttl;

           /* Receive auxiliary data in msgh */
           for (cmsg = CMSG_FIRSTHDR(&msgh); cmsg != NULL;
                   cmsg = CMSG_NXTHDR(&msgh,cmsg)) {
               if (cmsg->cmsg_level == IPPROTO_IP
                       && cmsg->cmsg_type == IP_TTL) {
                   ttlptr = (int *) CMSG_DATA(cmsg);
                   received_ttl = *ttlptr;
                   break;
               }
           }
           if (cmsg == NULL) {
               /*
                * Error: IP_TTL not enabled or small buffer
                * or I/O error.
                */
           }

       以下のコードは、 SCM_RIGHTS を使い、ファイルディスクリプターの配列を UNIX  ドメインソケットを通して送るも
       のである。

           struct msghdr msg = {0};
           struct cmsghdr *cmsg;
           int myfds[NUM_FD]; /* Contains the file descriptors to pass. */
           union {
               /* ancillary data buffer, wrapped in a union in order to ensure it is
                  suitably aligned */
               char buf[CMSG_SPACE(sizeof myfds)];
               struct cmsghdr align;
           } u;
           int *fdptr;

           msg.msg_control = u.buf;
           msg.msg_controllen = sizeof u.buf;
           cmsg = CMSG_FIRSTHDR(&msg);
           cmsg->cmsg_level = SOL_SOCKET;
           cmsg->cmsg_type = SCM_RIGHTS;
           cmsg->cmsg_len = CMSG_LEN(sizeof(int) * NUM_FD);
           /* Initialize the payload: */
           fdptr = (int *) CMSG_DATA(cmsg);
           memcpy(fdptr, myfds, NUM_FD * sizeof(int));
           /* Sum of the length of all control messages in the buffer: */
           msg.msg_controllen = cmsg->cmsg_len;

関連項目

       recvmsg(2), sendmsg(2)

       RFC 2292

この文書について

       この man ページは Linux man-pages プロジェクトのリリース 3.79 の一部 である。プロジェクトの説明とバグ報告
       に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。