IP_RECVERR(2const)

NAME

IP_RECVERR - extended reliable error message passing

LIBRARY

Standard C library (libc, -lc)

SYNOPSIS

#include <netinet/in.h>  /* Definition of IP* constants */
#include <sys/socket.h>

int setsockopt(int sockfd, IPPROTO_IP, IP_RECVERR,
               const int *enable, sizeof(int));
int getsockopt(int sockfd, IPPROTO_IP, IP_RECVERR,
               int *enabled, sizeof(int));

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;
    uint32_t  ee_info;    /* additional information */
    uint32_t  ee_data;    /* other data */
    /* More data may follow */
};

#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 sockaddr *SO_EE_OFFENDER(struct sock_extended_err *);

DESCRIPTION

Enable extended reliable error message passing (default: disabled).

When enabled on a datagram socket, all generated errors will be queued in a per-socket error queue. When the user receives an error from a socket operation, the errors can be received by calling recvmsg(2) with the MSG_ERRQUEUE flag set. The sock_extended_err structure describing the error will be passed in an ancillary message with the type IP_RECVERR and the level IPPROTO_IP. This is useful for reliable error handling on unconnected sockets. The received data portion of the error queue contains the error packet.

The IP_RECVERR control message contains a sock_extended_err structure.

.ee_errno: contains the errno number of the queued error.
.ee_origin: is the origin code of where the error originated.

The other fields are protocol-specific.

The macro SO_EE_OFFENDER() returns a pointer to the address of the network object where the error originated from given a pointer to the ancillary message. If this address is not known, the .sa_family member of the sockaddr contains AF_UNSPEC and the other fields of the sockaddr are undefined.

IP uses the sock_extended_err structure as follows:

•: .ee_origin is set to SO_EE_ORIGIN_ICMP for errors received as an ICMP packet, or SO_EE_ORIGIN_LOCAL for locally generated errors. Unknown values should be ignored.
•: .ee_type and .ee_code are set from the type and code fields of the ICMP header.
•: .ee_info contains the discovered MTU for EMSGSIZE errors.
•: The message also contains the sockaddr_in of the node caused that the error, which can be accessed with the SO_EE_OFFENDER() macro.

The .sin_family field of the SO_EE_OFFENDER() address is AF_UNSPEC when the source was unknown. When the error originated from the network, all IP options (IP_OPTIONS(2const), IP_TTL(2const), etc.) enabled on the socket and contained in the error packet are passed as control messages. The payload of the packet causing the error is returned as normal payload.

TCP has no error queue; MSG_ERRQUEUE is not permitted on SOCK_STREAM sockets. IP_RECVERR is valid for TCP, but all errors are returned by socket function return or SO_ERROR only.

For raw sockets, IP_RECVERR enables passing of all received ICMP errors to the application, otherwise errors are reported only on connected sockets

ERRORS

See IPPROTO_IP(2const). See setsockopt(2). See ip(7).

STANDARDS

Linux.

HISTORY

Linux 2.2.