Manpages

名 前

recv, recvfrom, recvmsg − ソ ケ ッ ト か ら メ ッ セ ー ジ を 受 け 取 る

書 式

#include <sys/types.h>
#include <sys/socket.h>

ssize_t recv(int sockfd, void *buf, size_t len, int flags);

ssize_t recvfrom(int sockfd, void *buf, size_t len, int flags,
struct sockaddr *src_addr, socklen_t *addrlen);

ssize_t recvmsg(int sockfd, struct msghdr *msg, int flags);

説 明

recv(), recvfrom(), recvmsg() コ ー ル は 、 ソ ケ ッ ト か ら メ ッ セ ー ジ を 受 け 取 る の に 使 用 さ れ る 。 こ れ ら は コ ネ ク シ ョ ン レ ス 型 の ソ ケ ッ ト に も 接 続 指 向 (connection−oriened) 型 の ソ ケ ッ ト に も 使 用 で き る 。 こ の ペ ー ジ で は 、 ま ず こ れ ら 3 つ の シ ス テ ム コ ー ル す べ て に 共 通 の 機 能 に つ い て 説 明 し 、 シ ス テ ム コ ー ル 間 の 違 い に つ い て 説 明 す る 。 こ れ ら の 三 つ の シ ス テ ム コ ー ル は い ず れ も 、 成 功 し た 場 合 に は メ ッ セ ー ジ の 長 さ を 返 す 。 メ ッ セ ー ジ が 長 過 ぎ て 指 定 さ れ た バ ッ フ ァ ー に 入 り 切 ら な か っ た 場 合 に は 、 メ ッ セ ー ジ を 受 信 し た ソ ケ ッ ト の 種 類 に よ っ て は 余 分 の バ イ ト が 捨 て ら れ る か も し れ な い 。 ソ ケ ッ ト に 受 け 取 る メ ッ セ ー ジ が 存 在 し な か っ た 場 合 、 受 信 用 の コ ー ル は メ ッ セ ー ジ が 到 着 す る ま で 待 つ 。 た だ し 、 ソ ケ ッ ト が 非 停 止 (nonblocking) に 設 定 さ れ て い た 場 合 (fcntl(2) を 参 照 ) は −1 を 返 し 、 外 部 変 数 errno に EAGAIN か EWOULDBLOCK を 設 定 す る 。 こ れ ら の 受 信 用 の コ ー ル は 、 受 信 し た デ ー タ の サ イ ズ が 要 求 し た サ イ ズ に 達 す る ま で 待 つ の で は な く 、 何 ら か の デ ー タ を 受 信 す る と 復 帰 す る (受 信 さ れ る デ ー タ の 最 大 サ イ ズ は 要 求 し た サ イ ズ で あ る )。 ア プ リ ケ ー シ ョ ン は select(2), poll(2), epoll(7) を 使 っ て 、 ソ ケ ッ ト に さ ら に デ ー タ が 到 着 し て い る か を 判 定 す る こ と が で き る 。 フ ラ グ 引 き 数
flags 引 き 数 に は 、 以 下 の 値 を 1つ 以 上 、 ビ ッ ト 単 位 の 論 理 和 を 取 っ た も の を 指 定 す る :
MSG_CMSG_CLOEXEC (recvmsg() の み ; Linux 2.6.23)

(unix(7) で 説 明 さ れ て い る ) SCM_RIGHTS 操 作 を 使 っ て UNIX ド メ イ ン の フ ァ イ ル デ ィ ス ク リ プ タ ー 経 由 で 受 信 し た フ ァ イ ル デ ィ ス ク リ プ タ ー に つ い て close−on−exec フ ラ グ を セ ッ ト す る 。 こ の フ ラ グ は 、 open(2) の O_CLOEXEC フ ラ グ と 同 じ 理 由 で 有 用 で あ る 。

MSG_DONTWAIT (Linux 2.2 以 降 ) 非 停 止 (nonblocking) 操 作 を 有 効 に す る 。 操 作 が 停 止 す る よ う な 場 合 に エ ラ ー EAGAIN か EWOULDBLOCK で 呼 び 出 し が 失 敗 す る (fcntl(2) の F_SETFL で O_NONBLOCK フ ラ グ を 指 定 す る こ と に よ っ て も 有 効 に で き る )。
MSG_ERRQUEUE (Linux 2.2 以 降 ) こ の フ ラ グ を 指 定 す る と 、 キ ュ ー に 入 れ ら れ た エ ラ ー を ソ ケ ッ ト の エ ラ ー キ ュ ー か ら 取 り だ せ る よ う に な る 。 こ の エ ラ ー は 補 助 メ ッ セ ー ジ に 組 み 込 ま れ て 渡 さ れ 、 こ の 補 助 メ ッ セ ー ジ の 種 別 は プ ロ ト コ ル に 依 存 す る (IPv4 の 場 合 は IP_RECVERR)。 ユ ー ザ ー は 十 分 な サ イ ズ の バ ッ フ ァ ー を 用 意 し な け れ ば な ら な い 。 補 助 メ ッ セ ー ジ に 関 す る よ り 詳 細 な 情 報 は cmsg(3) お よ び ip(7) を 参 照 の こ と 。 エ ラ ー の 原 因 と な っ た オ リ ジ ナ ル パ ケ ッ ト の ペ イ ロ ー ド は 、 msg_iovec 経 由 で 通 常 の デ ー タ と し て 渡 さ れ る 。 エ ラ ー を 起 こ し た デ ー タ グ ラ ム の オ リ ジ ナ ル の 宛 先 ア ド レ ス は 、 msg_name 経 由 で 参 照 で き る 。 ロ ー カ ル な エ ラ ー の 場 合 は ア ド レ ス は 渡 さ れ な い (こ れ は cmsghdr の cmsg_len メ ン バ ー で チ ェ ッ ク で き る )。 受 信 エ ラ ー の 場 合 は MSG_ERRQUIE が msghdr に セ ッ ト さ れ る 。 エ ラ ー が 渡 さ れ た 後 に は 、 キ ュ ー に 入 っ て い る 次 の エ ラ ー に 基 い て 、 処 理 待 ち の ソ ケ ッ ト エ ラ ー が 再 生 成 さ れ 、 次 の ソ ケ ッ ト 操 作 の 際 に 渡 さ れ る 。 こ の エ ラ ー は sock_extended_err 構 造 体 で 提 供 さ れ る :

#define SO_EE_ORIGIN_NONE 0
#define SO_EE_ORIGIN_LOCAL 1
#define SO_EE_ORIGIN_ICMP 2
#define SO_EE_ORIGIN_ICMP6 3

struct sock_extended_err
{
uint32_t ee_errno; /* error number */
uint8_t ee_origin; /* where the error originated */
uint8_t ee_type; /* type */
uint8_t ee_code; /* code */
uint8_t ee_pad; /* padding */
uint32_t ee_info; /* additional information */
uint32_t ee_data; /* other data */
/* More data may follow */ };

struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *);

ee_errno に は キ ュ ー に 入 れ ら れ た エ ラ ー の errno が 入 っ て い る 。 ee_origin に は エ ラ ー が 発 生 し た 場 所 の オ リ ジ ン コ ー ド (origin code) が 入 っ て い る 。 他 の フ ィ ー ル ド は プ ロ ト コ ル 依 存 で あ る 。 SO_EE_OFFENDER マ ク ロ は 、 こ の 補 助 的 な メ ッ セ ー ジ を 引 き 数 に 取 っ て 、 エ ラ ー の 発 生 し た ネ ッ ト ワ ー ク オ ブ ジ ェ ク ト の ア ド レ ス へ の ポ イ ン タ ー を 返 す 。 ア ド レ ス が 不 明 の 場 合 に は 、 sockaddr の sa_family メ ン バ ー が AF_UNSPEC に な っ て い る 。 sockaddr の 他 の フ ィ ー ル ド は 不 定 で あ る 。 エ ラ ー の 発 生 し た パ ケ ッ ト の ペ イ ロ ー ド は 通 常 の デ ー タ と し て 渡 さ れ る 。 ロ ー カ ル な エ ラ ー の 場 合 は ア ド レ ス は 渡 さ れ な い (こ れ は cmsghdr の cmsg_len メ ン バ ー で チ ェ ッ ク で き る )。 受 信 エ ラ ー の 場 合 は MSG_ERRQUIE が msghdr に セ ッ ト さ れ る 。 エ ラ ー が 渡 さ れ た 後 に は 、 キ ュ ー に 入 っ て い る 次 の エ ラ ー に 基 い て 、 処 理 待 ち の ソ ケ ッ ト エ ラ ー が 再 生 成 さ れ 、 次 の ソ ケ ッ ト 操 作 の 際 に 渡 さ れ る 。

MSG_OOB こ の フ ラ グ は 、 通 常 の デ ー タ ス ト リ ー ム で は 受 信 で き な い 帯 域 外 (out−of−band) デ ー タ の 受 信 を 要 求 す る 。 プ ロ ト コ ル に よ っ て は 、 通 常 の デ ー タ キ ュ ー の 先 頭 に 速 達 デ ー タ を 置 く も の が あ る が 、 そ の よ う な プ ロ ト コ ル で は こ の フ ラ グ は 使 用 で き な い 。
MSG_PEEK こ の フ ラ グ を 指 定 す る と 、 受 信 キ ュ ー の 最 初 の デ ー タ を 返 す と き 、 キ ュ ー か ら デ ー タ を 削 除 し な い 。 し た が っ て 、 こ の 後 で も う 一 度 受 信 コ ー ル を 呼 び 出 す と 、 同 じ デ ー タ が 返 る こ と に な る 。
MSG_TRUNC (Linux 2.2 以 降 )

raw ソ ケ ッ ト (AF_PACKET)、 Internet datagram ソ ケ ッ ト (Linux 2.4.27/2.6.8 以 降 )、 netlink (Linux 2.6.22 以 降 ) ソ ケ ッ ト 、 UNIX datagram ソ ケ ッ ト (Linux 3.4 以 降 ) の 場 合 、 パ ケ ッ ト や デ ー タ グ ラ ム の 長 さ が 渡 し た バ ッ フ ァ ー よ り も 長 か っ た 場 合 に も 、 パ ケ ッ ト や デ ー タ グ ラ ム の 実 際 の 長 さ を 返 す 。

Internet ス ト リ ー ム ソ ケ ッ ト で の 利 用 に つ い て は tcp(7) を 参 照 。

MSG_WAITALL (Linux 2.2 以 降 ) こ の フ ラ グ は 、 要 求 し た 量 い っ ぱ い の デ ー タ が 到 着 す る ま で 、 操 作 を 停 止 (block) す る よ う 要 求 す る 。 但 し 、 シ グ ナ ル を 受 信 し た り 、 エ ラ ー や 切 断 (disconnect) が 発 生 し た り 、 次 に 受 信 さ れ る デ ー タ が 異 な る 型 だ っ た り し た 場 合 に は 、 要 求 し た 量 よ り デ ー タ が 少 な く て も 返 る こ と が あ る 。

recvfrom()
recvfrom() は 受 信 し た メ ッ セ ー ジ を バ ッ フ ァ ー buf に 格 納 す る 。 呼 び 出 し 元 は バ ッ フ ァ ー サ イ ズ を len で 指 定 し な け れ ば な ら な い 。

src_addr が NULL 以 外 で 、 下 層 の プ ロ ト コ ル か ら メ ッ セ ー ジ の 送 信 元 ア ド レ ス が 分 か る 場 合 、 こ の 送 信 元 ア ド レ ス が src_addr が 指 す バ ッ フ ァ ー に 格 納 さ れ る 。 こ の 場 合 、 addrlen は 入 出 力 両 用 の 引 き 数 と な る 。 呼 び 出 し 前 に 、 呼 び 出 し 元 は src_addr に 割 り 当 て た バ ッ フ ァ ー の 大 き さ で 初 期 化 し て お く べ き で あ る 。 返 っ て く る 時 に は 、 addrlen は 送 信 元 ア ド レ ス の 実 際 の 大 き さ に 変 更 さ れ る 。 渡 さ れ た バ ッ フ ァ ー が 小 さ 過 ぎ る 場 合 に は 、 返 さ れ る ア ド レ ス の 末 尾 は 切 り 詰 め ら れ る 。 こ の 場 合 に は 、 addrlen で は 、 呼 び 出 し 時 に 渡 さ れ た 値 よ り も 大 き な 値 が 返 さ れ る 。 呼 び 出 し 元 が 送 信 元 ア ド レ ス を 必 要 と し な い 場 合 は 、 src_addr と addrlen に は NULL を 指 定 す べ き で あ る 。

recv()
recv() コ ー ル は 通 常 接 続 済 み の (connected) ソ ケ ッ ト に 対 し て の み 使 用 さ れ る (connect(2) 参 照 )。 次 の 呼 び 出 し と 等 価 で あ る 。

recvfrom(fd, buf, len, flags, NULL, 0));

recvmsg()
recvmsg() コ ー ル は 、 直 接 渡 す 引 き 数 の 数 を 減 ら す た め に msghdr 構 造 体 を 使 用 す る 。 こ の 構 造 体 は <sys/socket.h> で 以 下 の よ う に 定 義 さ れ て い る :

struct iovec { /* Scatter/gather array items */
void *iov_base; /* Starting address */
size_t iov_len; /* Number of bytes to transfer */ };

struct msghdr {
void *msg_name; /* 追 加 の ア ド レ ス */
socklen_t msg_namelen; /* ア ド レ ス の サ イ ズ */
struct iovec *msg_iov; /* scatter/gather 配 列 */
size_t msg_iovlen; /* msg_iov の 要 素 数 */
void *msg_control; /* 補 助 デ ー タ (後 述 ) */
size_t msg_controllen; /* 補 助 デ ー タ バ ッ フ ァ ー 長 */
int msg_flags; /* 受 信 メ ッ セ ー ジ の フ ラ グ */ }; フ ィ ー ル ド msg_name は 、 ソ ケ ッ ト が 接 続 さ れ て い な い 場 合 に 送 信 元 ア ド レ ス を 返 す の に 使 用 さ れ る バ ッ フ ァ ー を 指 す 。 こ の バ ッ フ ァ ー は 呼 び 出 し 元 が 確 保 す る 。 呼 び 出 し 元 は 呼 び 出 し 前 に msg_namelen に こ の バ ッ フ ァ ー の 大 き さ を 設 定 し な け れ ば な ら な い 。 呼 び 出 し が 成 功 し た 場 合 、 呼 び 出 し か ら 返 っ て 来 た 際 に は msg_namelen に は 返 さ れ る ア ド レ ス の 長 さ が 入 っ て い る 。 ア プ リ ケ ー シ ョ ン が 送 信 元 ア ド レ ス を 知 る 必 要 が な い 場 合 に は 、 msg_name に NULL を 指 定 す る こ と が で き る 。

msg_iov と msg_iovlen フ ィ ー ル ド は scatter−gather 用 の 場 所 を 指 定 す る 。 readv(2) に 説 明 が あ る 。

msg_control フ ィ ー ル ド は msg_controllen の 長 さ を 持 ち 、 他 の プ ロ ト コ ル 制 御 メ ッ セ ー ジ や 種 々 の 補 助 デ ー タ の た め の バ ッ フ ァ ー へ の ポ イ ン タ ー で あ る 。 recvmsg() を 呼 ぶ 際 に は 、 msg_controllen に msg_control の バ ッ フ ァ ー の 長 さ を 入 れ て お く 必 要 が あ る 。 コ ー ル が 成 功 し て 返 っ た 場 合 、 制 御 メ ッ セ ー ジ 列 の 長 さ が 入 っ て い る 。 メ ッ セ ー ジ の 形 式 は 以 下 の 通 り :

struct cmsghdr {
socklen_t cmsg_len; /* data byte count, including hdr */
int cmsg_level; /* originating protocol */
int cmsg_type; /* protocol−specific type */
/* followed by
unsigned char cmsg_data[]; */ }; 補 助 デ ー タ は 、 cmsg(3) に 定 義 さ れ た マ ク ロ 経 由 で の み ア ク セ ス す べ き で あ る 。 例 を あ げ る と 、 Linux は こ の 補 助 デ ー タ の メ カ ニ ズ ム を 、 UNIX ド メ イ ン ソ ケ ッ ト 上 で の 拡 張 エ ラ ー や IP オ プ シ ョ ン 、 フ ァ イ ル デ ィ ス ク リ プ タ ー の 受 け 渡 し に 利 用 し て い る 。

msghdr の msg_flags フ ィ ー ル ド は recvmsg() か ら の リ タ ー ン 時 に 設 定 さ れ る 。 こ こ に は い く つ か の フ ラ グ が 入 る 。
MSG_EOR こ れ は レ コ ー ド の 終 り (end−of−record) を 示 し 、 返 さ れ た デ ー タ が 完 全 な レ コ ー ド で あ る こ と を 示 す (一 般 的 に は SOCK_SEQPACKET 型 の ソ ケ ッ ト で 使 用 さ れ る )。
MSG_TRUNC デ ー タ グ ラ ム が 与 え ら れ た バ ッ フ ァ ー よ り 大 き か っ た た め に 、 デ ー タ グ ラ ム の は み 出 し た 部 分 が 捨 て ら れ た こ と を 示 す 。
MSG_CTRUNC 補 助 デ ー タ の た め の バ ッ フ ァ ー が 不 足 し た た め に 、 制 御 デ ー タ の 一 部 が 捨 て ら れ た こ と を 示 す 。
MSG_OOB 速 達 デ ー タ や 帯 域 外 デ ー タ を 受 信 し た こ と を 示 す 。
MSG_ERRQUEUE デ ー タ は 受 信 し な か っ た が ソ ケ ッ ト の エ ラ ー キ ュ ー か ら 拡 張 エ ラ ー を 受 信 し た こ と を 示 す 。

返 り 値

こ れ ら の コ ー ル は 受 信 し た バ イ ト 数 を 返 す 。 エ ラ ー の 場 合 は −1 を 返 し 、 errno に エ ラ ー を 示 す 値 を 設 定 す る 。 ス ト リ ー ム ソ ケ ッ ト の 接 続 相 手 が 正 し く シ ャ ッ ト ダ ウ ン を 実 行 し た 場 合 は 、 返 り 値 は 0 (昔 な が ら の "end−of−file" の 戻 り 値 ) と な る 。 い く つ か の ド メ イ ン の デ ー タ グ ラ ム ソ ケ ッ ト (UNIX ド メ イ ン や イ ン タ ー ネ ッ ト ド メ イ ン な ど ) で は 、 長 さ 0 の デ ー タ グ ラ ム が 送 信 で き る 。 こ の よ う な デ ー タ グ ラ ム を 受 信 し た 場 合 、 返 り 値 は 0 と な る 。 ス ト リ ー ム ソ ケ ッ ト に 対 す る 受 信 要 求 バ イ ト 数 が 0 だ っ た 場 合 も 、 値 0 が 返 さ れ る 。

エ ラ ー

こ れ ら は ソ ケ ッ ト 層 で 発 生 す る 一 般 的 な エ ラ ー で あ る 。 他 の エ ラ ー が 下 層 の プ ロ ト コ ル モ ジ ュ ー ル で 生 成 さ れ 、 返 さ れ る か も し れ な い 。 そ れ ら の マ ニ ュ ア ル を 参 照 す る こ と 。

EAGAIN ま た は EWOULDBLOCK ソ ケ ッ ト が 非 停 止 (nonblocking) に 設 定 さ れ て い て 受 信 操 作 が 停 止 す る よ う な 状 況 に な っ た か 、 受 信 に 時 間 切 れ (timeout) が 設 定 さ れ て い て デ ー タ を 受 信 す る 前 に 時 間 切 れ に な っ た 。 POSIX.1−2001 は 、 こ の 場 合 に ど ち ら の エ ラ ー を 返 す こ と も 認 め て お り 、 こ れ ら 2 つ の 定 数 が 同 じ 値 を 持 つ こ と も 求 め て い な い 。 し た が っ て 、 移 植 性 が 必 要 な ア プ リ ケ ー シ ョ ン で は 、 両 方 の 可 能 性 を 確 認 す べ き で あ る 。

EBADF 引 き 数

sockfd が 不 正 な デ ィ ス ク リ プ タ ー で あ る 。

ECONNREFUSED リ モ ー ト の ホ ス ト で ネ ッ ト ワ ー ク 接 続 が 拒 否 さ れ た (よ く あ る 理 由 と し て は 、 要 求 し た サ ー ビ ス が 起 動 さ れ て い な い な ど が あ る )。

EFAULT 受 信 バ ッ フ ァ ー へ の ポ イ ン タ ー が プ ロ セ ス の ア ド レ ス 空 間 外 を 指 し て い る 。

EINTR デ ー タ を 受 信 す る 前 に 、 シ グ ナ ル が 配 送 さ れ て 割 り 込 ま れ た 。

signal(7) 参 照 。

EINVAL 不 正 な 引 き 数 が 渡 さ れ た 。

ENOMEM

recvmsg() の た め の メ モ リ ー が 確 保 で き な か っ た 。

ENOTCONN ソ ケ ッ ト に 接 続 指 向 プ ロ ト コ ル が 割 り 当 て ら れ て お り 、 ま だ 接 続 さ れ て い な い (connect(2) と accept(2) を 参 照 の こ と )。
ENOTSOCK 引 き 数 sockfd が ソ ケ ッ ト を 参 照 し て い な い 。

準 拠

4.4BSD (こ れ ら の 関 数 は 4.2BSD で 現 わ れ た ), POSIX.1−2001。

POSIX.1−2001 で は 、 MSG_OOB, MSG_PEEK, MSG_WAITALL フ ラ グ だ け が 記 載 さ れ て い る 。

注 意

socklen_t 型 は POSIX で 発 案 さ れ た 。 accept(2) も 参 照 。

POSIX.1−2001 で は 、 構 造 体 msghdr の フ ィ ー ル ド msg_controllen は socklen_t 型 で あ る べ き だ と さ れ て い る が 、 現 在 の glibc で は size_t 型 で あ る 。

recvmmsg(2) に は 、 一 度 の 呼 び 出 し で の 複 数 の デ ー タ グ ラ ム に 使 用 で き る Linux 固 有 の シ ス テ ム コ ー ル に 関 す る 情 報 が 書 か れ て い る 。

例

recvfrom() の 利 用 例 が getaddrinfo(3) に 記 載 さ れ て い る 。

関 連 項 目

fcntl(2), getsockopt(2), read(2), recvmmsg(2), select(2), shutdown(2), socket(2), cmsg(3), sockatmark(3), socket(7)

こ の 文 書 に つ い て

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