Man page - recv(2)

Packages contains this manual

Available languages:

en fr tr ja ru

Manual

RECV

名 前
書 式
説 明
フ ラ グ 引 数
recvfrom()
recv()
recvmsg()
返 り 値
エ ラ ー
準 拠
注 意
例
関 連 項 目
こ の 文 書 に つ い て

名 前

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 つ の シ ス テ ム コ ー ル す べ て に 共 通 の 機 能 に つ い て 説 明 し 、 シ ス テ ム コ ー ル 間 の 違 い に つ い て 説 明 す る 。

The only difference between recv () and read (2) is the presence of flags . With a zero flags argument, recv () is generally equivalent to read (2) (but see NOTES). Also, the following call

recv(sockfd, buf, len, flags);

は 以 下 と 等 価 で あ る 。

recvfrom(sockfd, buf, len, flags, NULL, NULL);

こ れ ら の 三 つ の シ ス テ ム コ ー ル は い ず れ も 、 成 功 し た 場 合 に は メ ッ セ ー ジ の 長 さ を 返 す 。 メ ッ セ ー ジ が 長 過 ぎ て 指 定 さ れ た バ ッ フ ァ ー に 入 り 切 ら な か っ た 場 合 に は 、 メ ッ セ ー ジ を 受 信 し た ソ ケ ッ ト の 種 類 に よ っ て は 余 分 の バ イ ト が 捨 て ら れ る か も し れ な い 。

ソ ケ ッ ト に 受 け 取 る メ ッ セ ー ジ が 存 在 し な か っ た 場 合 、 受 信 用 の コ ー ル は メ ッ セ ー ジ が 到 着 す る ま で 待 つ 。 た だ し 、 ソ ケ ッ ト が 非 停 止 (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 以 降 )

Enables nonblocking operation; if the operation would block, the call fails with the error EAGAIN or EWOULDBLOCK . This provides similar behavior to setting the O_NONBLOCK flag (via the fcntl (2) F_SETFL operation), but differs in that MSG_DONTWAIT is a per-call option, whereas O_NONBLOCK is a setting on the open file description (see open (2)), which will affect all threads in the calling process and as well as other processes that hold file descriptors referring to the same open file description.

MSG_ERRQUEUE (Linux 2.2 以 降 )

こ の フ ラ グ を 指 定 す る と 、 キ ュ ー に 入 れ ら れ た エ ラ ー を ソ ケ ッ ト の エ ラ ー キ ュ ー か ら 取 り だ せ る よ う に な る 。 こ の エ ラ ー は 補 助 メ ッ セ ー ジ に 組 み 込 ま れ て 渡 さ れ 、 こ の 補 助 メ ッ セ ー ジ の 種 別 は プ ロ ト コ ル に 依 存 す る (IPv4 の 場 合 は IP_RECVERR )。 ユ ー ザ ー は 十 分 な サ イ ズ の バ ッ フ ァ ー を 用 意 し な け れ ば な ら な い 。 補 助 メ ッ セ ー ジ に 関 す る よ り 詳 細 な 情 報 は cmsg (3) お よ び ip (7) を 参 照 の こ と 。 エ ラ ー の 原 因 と な っ た オ リ ジ ナ ル パ ケ ッ ト の ペ イ ロ ー ド は 、 msg_iovec 経 由 で 通 常 の デ ー タ と し て 渡 さ れ る 。 エ ラ ー を 起 こ し た デ ー タ グ ラ ム の オ リ ジ ナ ル の 宛 先 ア ド レ ス は 、 msg_name 経 由 で 参 照 で き る 。

こ の エ ラ ー は 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 以 降 )

This flag requests that the operation block until the full request is satisfied. However, the call may still return less data than requested if a signal is caught, an error or disconnect occurs, or the next data to be received is of a different type than that returned. This flag has no effect for datagram sockets.

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

補 助 デ ー タ は 、 cmsg (3) に 定 義 さ れ た マ ク ロ 経 由 で の み ア ク セ ス す べ き で あ る 。

As an example, Linux uses this ancillary data mechanism to pass extended errors, IP options, or file descriptors over UNIX domain sockets. For further information on the use of ancillary data in various socket domains, see unix (7) and ip (7).

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 は 、 こ の 場 合 に ど ち ら の エ ラ ー を 返 す こ と も 認 め て お り 、 こ れ ら 2 つ の 定 数 が 同 じ 値 を 持 つ こ と も 求 め て い な い 。 し た が っ て 、 移 植 性 が 必 要 な ア プ リ ケ ー シ ョ ン で は 、 両 方 の 可 能 性 を 確 認 す べ き で あ る 。

EBADF

引 数 sockfd が 不 正 な フ ァ イ ル デ ィ ス ク リ プ タ ー で あ る 。

ECONNREFUSED

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

EFAULT

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

EINTR

デ ー タ を 受 信 す る 前 に 、 シ グ ナ ル が 配 送 さ れ て 割 り 込 ま れ た 。 signal (7) 参 照 。

EINVAL

不 正 な 引 数 が 渡 さ れ た 。

ENOMEM

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

ENOTCONN

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

ENOTSOCK

フ ァ イ ル デ ィ ス ク リ プ タ ー sockfd が ソ ケ ッ ト を 参 照 し て い な い 。

準 拠

POSIX.1-2001, POSIX.1-2008, 4.4BSD (こ れ ら の イ ン タ ー フ ェ ー ス は 4.2BSD で 初 め て 実 装 さ れ た )

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

注 意

If a zero-length datagram is pending, read (2) and recv () with a flags argument of zero provide different behavior. In this circumstance, read (2) has no effect (the datagram remains pending), while recv () consumes the pending datagram.

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

According to POSIX.1, the msg_controllen field of the msghdr structure should be typed as socklen_t , and the msg_iovlen field should be typed as int , but glibc currently types both as 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), ip (7), ipv6 (7), socket (7), tcp (7), udp (7), unix (7)

こ の 文 書 に つ い て

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