---

   recvmsg - принимает сообщение из сокета

---

Ошибка передаётся в виде структуры 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;   /* номер ошибки */
    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 *);

MSG_OOB Этот флаг запрашивает приём внеполосных данных, которые в противном случае не были бы получены в обычном потоке данных. Некоторые протоколы помещают данные повышенной срочности в начало очереди с обычными данными, и поэтому этот флаг не может использоваться с такими протоколами.

MSG_PEEK Этот флаг заставляет выбрать данные из начала очереди приёма, но не удалять их оттуда. Таким образом, последующий вызов вернёт те же самые данные.

MSG_TRUNC (начиная с Linux 2.2) Для «сырых» данных (AF_PACKET), дейтаграмм Интернета (начиная с Linux 2.4.27/2.6.8), netlink (начиная с Linux 2.6.22) и дейтаграмм UNIX (начиная с Linux 3.4) возвращает реальную длину пакета или дейтаграммы, даже если она была больше, чем предоставленный буфер.

Описание использования с потоковым сокетами Интернета смотрите в tcp(7).

MSG_WAITALL (начиная с Linux 2.2) Этим флагом включается блокирование операции до полной обработки запроса. Однако, этот вызов всё равно может вернуть меньше данных, чем было запрошено, если был пойман сигнал, произошла ошибка или разрыв соединения, или если начали поступать данные другого типа, не того, который был сначала.

recvfrom()

Если значение src_addr не равно NULL, и в нижележащем протоколе используется адрес источника сообщения, то адрес источника помещается в буфер, указанный в src_addr. В этом случае addrlen является аргументом-результатом. Перед вызовом ему должно быть присвоено значение длины буфера, связанного с src_addr. При возврате addrlen обновляется и содержит действительный размер адреса источника. Возвращаемый адрес обрезается, если предоставленный буфер слишком мал; в этом случае addrlen будет содержать значение большее, чем указывалось в вызове.

Если вызывающему адрес источника не нужен, то значение src_addr и addrlen должно быть равно NULL.

recv()

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

recvmsg()

struct iovec {                    /* массив элементов приёма/передачи */
    void  *iov_base;              /* начальный адрес */
    size_t iov_len;               /* количество передаваемых байт */
};
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 {
    socklen_t     cmsg_len;     /* количество байт данных, включая hdr */
    int           cmsg_level;   /* изначальный протокол */
    int           cmsg_type;    /* тип, зависящий от протокола */
/* дальше следует
    unsigned char cmsg_data[]; */
};

К вспомогательным данным нужно обращаться только с помощью макросов, определённых в cmsg(3).

Например, этот механизм вспомогательных данных используется в Linux для передачи расширенных ошибок, флагов IP и файловых дескрипторов через доменные сокеты Unix.

При возврате из recvmsg() устанавливается значение поля msg_flags в msghdr. Оно может содержать несколько флагов:

MSG_EOR означает конец записи: возвращённые данные заканчивают запись (обычно используется вместе с сокетами типа SOCK_SEQPACKET).

MSG_TRUNC означает, что хвостовая часть датаграммы была отброшена, потому что датаграмма была больше, чем предоставленный буфер.

MSG_CTRUNC означает, что часть управляющих данных была отброшена из-за недостатка места в буфере вспомогательных данных.

MSG_OOB возвращается для индикации получения внеполосных данных.

MSG_ERRQUEUE означает, что были получены не данные, а расширенное сообщение об ошибке из очереди ошибок сокета.

---

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

Когда ответная сторона потока выполняет корректное отключение (shutdown), то возвращается 0 (обычный возврат «конец файла»).

В датаграмных сокетах некоторых доменов (например, доменах UNIX и Internet) разрешены датаграммы нулевой длины. При получении такой датаграммы возвращается значение 0.

Также значение 0 может возвращаться, если запрошенное количество принимаемых байт из потокового сокета равно 0.

---

ОШИБКИ

EAGAIN или EWOULDBLOCK Сокет помечен как неблокируемый, а операция приёма привела бы к блокировке, или установлено время ожидания данных и это время истекло до получения данных. Согласно POSIX.1 в этом случае может возвращаться любая ошибка и не требуется, чтобы эти константы имели одинаковое значение, поэтому переносимое приложение должно проверить оба случая.

EBADF Аргумент sockfd содержит неверный файловый дескриптор.

ECONNREFUSED Удалённый узел отказался устанавливать сетевое соединение (обычно потому, что там не работает запрошенная служба).

EFAULT Указатель на приёмный буфер указывает вне адресного пространства процесса.

EINTR Приём данных был прерван сигналом, а данные ещё не были доступны; см. signal(7).

EINVAL Передан неверный аргумент.

ENOMEM Не удалось выдели память для recvmsg().

ENOTCONN Сокет, связанный с протоколом, ориентированным на соединение, не был соединён (см. connect(2) и accept(2)).

ENOTSOCK Файловый дескриптор sockfd указывает не на каталог.

---

СООТВЕТСТВИЕ СТАНДАРТАМ

В POSIX.1 описаны только флаги MSG_OOB, MSG_PEEK и MSG_WAITALL.

---

ЗАМЕЧАНИЯ

В соответствие с POSIX.1 поле msg_controllen структуры msghdr должно иметь тип socklen_t, но в настоящее время в glibc оно имеет тип size_t.

В recvmmsg(2) можно найти информацию о специальном системном вызове Linux, который можно использовать для приёма нескольких датаграмм за один вызов.

---

ПРИМЕР