| recv(2) | System Calls Manual | recv(2) |
recv, recvfrom, recvmsg - принимает сообщение из сокета
Standard C library (libc, -lc)
#include <sys/socket.h>
ssize_t recv(int sockfd, void buf[.len], size_t len,
int flags);
ssize_t recvfrom(int sockfd, void buf[restrict .len], size_t len,
int flags,
struct sockaddr *_Nullable restrict src_addr,
socklen_t *_Nullable restrict addrlen);
ssize_t recvmsg(int sockfd, struct msghdr *msg, int flags);
Системные вызовы recv(), recvfrom() и recvmsg() используются для получения сообщений из сокета. Они могут использоваться для получения данных, независимо от того, является ли сокет ориентированным на соединения или нет. В этой странице сперва описаны общие свойства всех трёх системных вызовов, а затем описываются различия между ними.
Вызов recv() отличается от read(2) только наличием аргумента flags. Если значение flags равно нулю, то вызов recv() эквивалентен read(2) (но смотрите ЗАМЕЧАНИЯ). Также, вызов
recv(sockfd, buf, len, flags);
эквивалентен
recvfrom(sockfd, buf, len, flags, NULL, NULL);
При успешном выполнении все три вызова возвращают длину сообщения. Если сообщение слишком длинное и не поместилось в предоставленный буфер, лишние байты могут быть отброшены, в зависимости от типа сокета, на котором принимаются сообщения.
If no messages are available at the socket, the receive calls wait for a message to arrive, unless the socket is nonblocking (see fcntl(2)), in which case the value -1 is returned and errno is set to EAGAIN or EWOULDBLOCK. The receive calls normally return any data available, up to the requested amount, rather than waiting for receipt of the full amount requested.
Для определения появления новых данных в сокете приложение может использовать select(2), poll(2) или epoll(7).
Аргумент flags формируется с помощью объединения логической операцией ИЛИ одного или более следующих значений:
#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; /* номер ошибки */
uint8_t ee_origin; /* источник её происхождения */
uint8_t ee_type; /* тип */
uint8_t ee_code; /* код */
uint8_t ee_pad; /* заполнение для выравнивания */
uint32_t ee_info; /* дополнительная информация */
uint32_t ee_data; /* прочие данные */
/* далее могут содержаться ещё данные */
};
struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *);
Вызов recvfrom() помещает принятое сообщение в буфер buf. Вызывающий должен указать размер буфера в len.
Если значение src_addr не равно NULL, и в нижележащем протоколе используется адрес источника сообщения, то адрес источника помещается в буфер, указанный в src_addr. В этом случае addrlen является аргументом-результатом. Перед вызовом ему должно быть присвоено значение длины буфера, связанного с src_addr. При возврате addrlen обновляется и содержит действительный размер адреса источника. Возвращаемый адрес обрезается, если предоставленный буфер слишком мал; в этом случае addrlen будет содержать значение большее, чем указывалось в вызове.
Если вызывающему адрес источника не нужен, то значение src_addr и addrlen должно быть равно NULL.
Вызов recv(), обычно, используется только на соединённом сокете (смотрите connect(2)). Он идентичен вызову:
recvfrom(fd, buf, len, flags, NULL, 0);
Для минимизации количества передаваемых аргументов в вызов recvmsg() используется структура msghdr. Она определена в <sys/socket.h> следующим образом:
struct msghdr {
void *msg_name; /* необязательный адрес */
socklen_t msg_namelen; /* размер адреса */
struct iovec *msg_iov; /* массив приёма/передачи */
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 описываются место приёма/передачи, обсуждаемые в readv(2).
Поле msg_control длиной msg_controllen указывает на буфер для других сообщений, связанных с управлением протоколом или на буфер для разнообразных вспомогательных данных. При вызове recvmsg() в поле msg_controllen должен указываться размер доступного буфера, чей адрес передан в msg_control; при успешном выполнении вызова в этом параметре будет находиться длина последовательности контрольных сообщений.
Сообщения имеют следующий вид:
struct cmsghdr {
size_t cmsg_len; /* счетчик байтов данных с заголовком
(тип — socklen_t в POSIX) */
int cmsg_level; /* начальный протокол */
int cmsg_type; /* тип, зависящий от протокола */
/* после
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).
При возврате из recvmsg() устанавливается значение поля msg_flags в msghdr. Оно может содержать несколько флагов:
Эти вызовы возвращают количество принятых байт или -1, если произошла ошибка. В случае ошибки в errno записывается код ошибки.
Когда ответная сторона потока выполняет корректное отключение (shutdown), то возвращается 0 (обычный возврат «конец файла»).
В датаграмных сокетах некоторых доменов (например, доменах UNIX и Internet) разрешены датаграммы нулевой длины. При получении такой датаграммы возвращается значение 0.
Также значение 0 может возвращаться, если запрошенное количество принимаемых байт из потокового сокета равно 0.
Здесь представлено несколько стандартных ошибок, возвращаемых с уровня сокетов. Могут также появиться другие ошибки, возвращаемые из соответствующих протокольных модулей; их описание находится в соответствующих справочных страницах.
POSIX.1-2001, POSIX.1-2008, 4.4BSD (эти интерфейсы впервые появились в 4.2BSD).
В POSIX.1 описаны только флаги MSG_OOB, MSG_PEEK и MSG_WAITALL.
Если ожидает дейтаграмма нулевой длины, то read(2) и recv() с нулевым аргументом flags работают по-разному. В этом случае read(2) ничего не делает (дейтаграмма продолжает ждать), а recv() обрабатывает ожидающую дейтаграмму.
Тип 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)
Русский перевод этой страницы руководства был сделан aereiae <aereiae@gmail.com>, Azamat Hackimov <azamat.hackimov@gmail.com>, Dmitriy S. Seregin <dseregin@59.ru>, Katrin Kutepova <blackkatelv@gmail.com>, Lockal <lockalsash@gmail.com>, Yuri Kozlov <yuray@komyakino.ru>, Баринов Владимир и Иван Павлов <pavia00@gmail.com>
Этот перевод является бесплатной документацией; прочитайте Стандартную общественную лицензию GNU версии 3 или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ.
Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на man-pages-ru-talks@lists.sourceforge.net.
| 3 декабря 2022 г. | Linux man-pages 6.03 |