Manpages

名 前

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() を 使 っ て 初 期 化 を す る 。 最 後 に msghdr の msg_controllen フ ィ ー ル ド に 、 バ ッ フ ァ ー 中 の 制 御 メ ッ セ ー ジ の 長 さ の CMSG_SPACE() の 合 計 が セ ッ ト さ れ る 。 msghdr に つ い て の 詳 細 は recvmsg(2) を 参 照 。 制 御 メ ッ セ ー ジ バ ッ フ ァ ー が 全 て の メ ッ セ ー ジ を 納 め る の に は 短 す ぎ る 場 合 、 msghdr の msg_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/ に 書 か れ て い る 。