Man page - cmsg_data(3)

Packages contains this manual

Available languages:

en fr pl ja

Manual

CMSG

名 前
書 式
説 明
準 拠
注 意
例
関 連 項 目
こ の 文 書 に つ い て

名 前

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 );

説 明

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

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

cmsghdr 構 造 体 は 以 下 の よ う に 定 義 さ れ て い る 。

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[]; */
};

The sequence of cmsghdr structures should never be accessed directly. Instead, use only the following macros:

*

CMSG_FIRSTHDR () returns a pointer to the first cmsghdr in the ancillary data buffer associated with the passed msghdr . It returns NULL if there isn’t enough space for a cmsghdr in the buffer.

*

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

When initializing a buffer that will contain a series of cmsghdr structures (e.g., to be sent with sendmsg (2)), that buffer should first be zero-initialized to ensure the correct operation of CMSG_NXTHDR ().

*

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

*

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

*

CMSG_DATA () returns a pointer to the data portion of a cmsghdr . 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 memcpy (3) to copy data to or from a suitably declared object.

*

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

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

準 拠

This ancillary data model conforms to the POSIX.1g draft, 4.4BSD-Lite, the IPv6 advanced API described in RFC 2292 and SUSv2. CMSG_FIRSTHDR (), CMSG_NXTHDR (), and CMSG_DATA () are specified in POSIX.1-2008. CMSG_SPACE () and CMSG_LEN () will be included in the next POSIX release (Issue 8).

CMSG_ALIGN () is a Linux extension.

注 意

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

In Linux, CMSG_LEN (), CMSG_DATA (), and CMSG_ALIGN () 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.

例

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

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 */
}

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

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));

関 連 項 目

recvmsg (2), sendmsg (2)

RFC 2292

こ の 文 書 に つ い て

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