.\" This man page is Copyright (C) 1999 Andi Kleen . .\" .\" %%%LICENSE_START(VERBATIM_ONE_PARA) .\" Permission is granted to distribute possibly modified copies .\" of this page provided the header is included verbatim, .\" and in case of nontrivial modification author and date .\" of the modification is added to the header. .\" %%%LICENSE_END .\" .\" $Id: cmsg.3,v 1.8 2000/12/20 18:10:31 ak Exp $ .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .\" .\" Japanese Version Copyright (c) 1999 Shouichi Saito .\" all rights reserved. .\" Translated Mon Jul 26 21:58:26 JST 1999 .\" by Shouichi Saito .\" Proofed Tue Aug 17 1999 by NAKANO Takeo .\" .TH CMSG 3 2020\-11\-01 Linux "Linux Programmer's Manual" .SH 名前 CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- 補助データにアクセスする。 .SH 書式 .nf \fB#include \fP \fBstruct cmsghdr *CMSG_FIRSTHDR(struct msghdr *\fP\fImsgh\fP\fB);\fP \fBstruct cmsghdr *CMSG_NXTHDR(struct msghdr *\fP\fImsgh\fP\fB,\fP \fB struct cmsghdr *\fPcmsg\fB);\fP \fBsize_t CMSG_ALIGN(size_t \fP\fIlength\fP\fB);\fP \fBsize_t CMSG_SPACE(size_t \fP\fIlength\fP\fB);\fP \fBsize_t CMSG_LEN(size_t \fP\fIlength\fP\fB);\fP \fBunsigned char *CMSG_DATA(struct cmsghdr *\fP\fIcmsg\fP\fB);\fP .fi .SH 説明 これらのマクロは制御メッセージ (補助データ (ancillary data) とも呼ばれる) を作り、 それにアクセスするために使われる。 制御メッセージはソケットにのるデータではない。 この制御情報は、到着したパケットへのインターフェイス、様々なあまり 使われないヘッダーフィールド、エラー記述の拡張、ファイルデスクリ プタの集合や、UNIXにおける信頼情報 (credential) を含んでいる。 制御メッセージは、例えば IP オプションのような追加ヘッダーフィールドを 送るのに使う事ができる。 補助データは、 \fBsendmsg\fP(2) を呼び出して送り、 \fBrecvmsg\fP(2) を呼び出して受け取る。 詳細はそれらのマニュアルページを参照。 .PP 補助データは \fIcmsghdr\fP 構造体のシーケンスに追加データが付加されたものである。使用可能な制御メッセージのタイプについては、 それぞれのプロトコルのマニュアルページを参照のこと。接続毎の最大補助用バッファーサイズは \fI/proc/sys/net/core/optmem_max\fP を使って設定できる。 \fBsocket\fP(7) を参照。 .PP \fIcmsghdr\fP 構造体は以下のように定義されている。 .PP .in +4n .EX struct cmsghdr { size_t cmsg_len; /* Data byte count, including header (type is socklen_t in POSIX) */ int cmsg_level; /* Originating protocol */ int cmsg_type; /* Protocol\-specific type */ /* followed by unsigned char cmsg_data[]; */ }; .EE .in .PP The sequence of \fIcmsghdr\fP structures should never be accessed directly. Instead, use only the following macros: .IP * 3 \fBCMSG_FIRSTHDR\fP() returns a pointer to the first \fIcmsghdr\fP in the ancillary data buffer associated with the passed \fImsghdr\fP. It returns NULL if there isn't enough space for a \fIcmsghdr\fP in the buffer. .IP * \fBCMSG_NXTHDR\fP() は、渡した \fIcmsghdr\fP の次にくる (有効な) \fIcmsghdr\fP を返す。 バッファーに十分な空きが無い場合、NULL を返す。 .IP When initializing a buffer that will contain a series of \fIcmsghdr\fP structures (e.g., to be sent with \fBsendmsg\fP(2)), that buffer should first be zero\-initialized to ensure the correct operation of \fBCMSG_NXTHDR\fP(). .IP * \fBCMSG_ALIGN\fP() に長さを与えると、必要なアラインメントを加味した長さを返してくる。 これは定数式である。 .IP * \fBCMSG_SPACE\fP() は、与えたデータ長が占めるのに必要な補助要素 (ancillary element) の バイト数を返す。これは定数式である。 .IP * \fBCMSG_DATA\fP() returns a pointer to the data portion of a \fIcmsghdr\fP. The pointer returned cannot be assumed to be suitably aligned for accessing arbitrary payload data types. Applications should not cast it to a pointer type matching the payload, but should instead use \fBmemcpy\fP(3) to copy data to or from a suitably declared object. .IP * \fBCMSG_LEN\fP() は、 \fIcmsghdr\fP 構造体の \fIcmsg_len\fP メンバにデータを格納する際に必要な値を返す。アラインメントも考慮に入れ られる。 引数としてデータ長をとる。これは定数式である。 .PP 補助データを作るためには最初に \fImsghdr\fP のメンバー \fImsg_controllen\fP を、制御メッセージバッファーの長さで初期化する。 \fBCMSG_FIRSTHDR\fP() を \fImsghdr\fP に用いると最初の制御メッセージが得られ、 \fBCMSG_NXTHDR\fP() を使うと次の制御メッセージが得られる。 それぞれの制御メッセージでは、 \fIcmsg_len\fP を初期化する (\fBCMSG_LEN\fP() を使う)。 その他の \fIcmsghdr\fP ヘッダーフィールド、そしてデータ部分に対しても \fBCMSG_DATA\fP() を使って初期化をする。 最後に \fImsghdr\fP の \fImsg_controllen\fP フィールドに、バッファー中の制御メッセージの長さの \fBCMSG_SPACE\fP() の合計がセットされる。 \fImsghdr\fP についての詳細は \fBrecvmsg\fP(2) を参照。 .SH 準拠 .\" https://www.austingroupbugs.net/view.php?id=978#c3242 This ancillary data model conforms to the POSIX.1g draft, 4.4BSD\-Lite, the IPv6 advanced API described in RFC\ 2292 and SUSv2. \fBCMSG_FIRSTHDR\fP(), \fBCMSG_NXTHDR\fP(), and \fBCMSG_DATA\fP() are specified in POSIX.1\-2008. \fBCMSG_SPACE\fP() and \fBCMSG_LEN\fP() will be included in the next POSIX release (Issue 8). .PP \fBCMSG_ALIGN\fP() is a Linux extension. .SH 注意 移植性のために、補助データへのアクセスには、 ここで述べられているマクロだけを使うべきである。 \fBCMSG_ALIGN\fP() は Linux での拡張であり、移植性を考えたプログラムでは使うべきではない。 .PP In Linux, \fBCMSG_LEN\fP(), \fBCMSG_DATA\fP(), and \fBCMSG_ALIGN\fP() are constant expressions (assuming their argument is constant), meaning that these values can be used to declare the size of global variables. This may not be portable, however. .SH 例 次のコードは、受け取った補助バッファーから \fBIP_TTL\fP オプションを探すものである。 .PP .in +4n .EX struct msghdr msgh; struct cmsghdr *cmsg; 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) { memcpy(&receive_ttl, CMSG_DATA(cmsg), sizeof(received_ttl)); break; } } if (cmsg == NULL) { /* Error: IP_TTL not enabled or small buffer or I/O error */ } .EE .in .PP 以下のコードは、 \fBSCM_RIGHTS\fP を使い、ファイルディスクリプターの配列を UNIX ドメインソケットを通して送るものである。 .PP .in +4n .EX struct msghdr msg = { 0 }; struct cmsghdr *cmsg; int myfds[NUM_FD]; /* Contains the file descriptors to pass */ char iobuf[1]; struct iovec io = { .iov_base = iobuf, .iov_len = sizeof(iobuf) }; 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; msg.msg_iov = &io; msg.msg_iovlen = 1; 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(myfds)); memcpy(CMSG_DATA(cmsg), myfds, sizeof(myfds)); .EE .in .SH 関連項目 \fBrecvmsg\fP(2), \fBsendmsg\fP(2) .PP RFC\ 2292 .SH この文書について この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は \%https://www.kernel.org/doc/man\-pages/ に書かれている。