diff options
Diffstat (limited to 'man/man2const/IP_RECVERR.2const')
| -rw-r--r-- | man/man2const/IP_RECVERR.2const | 188 |
1 files changed, 188 insertions, 0 deletions
diff --git a/man/man2const/IP_RECVERR.2const b/man/man2const/IP_RECVERR.2const new file mode 100644 index 0000000000..dba2216518 --- /dev/null +++ b/man/man2const/IP_RECVERR.2const @@ -0,0 +1,188 @@ +.\" Copyright, the authors of the Linux man-pages project +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH IP_RECVERR 2const (date) "Linux man-pages (unreleased)" +.SH NAME +IP_RECVERR +\- +extended reliable error message passing +.SH LIBRARY +Standard C library +.RI ( libc ,\~ \-lc ) +.SH SYNOPSIS +.nf +.BR "#include <netinet/in.h>" " /* Definition of " IP* " constants */" +.B #include <sys/socket.h> +.P +.BI int\~setsockopt(int\~ sockfd ,\~IPPROTO_IP,\~IP_RECVERR, +.BI " const\~int\~*" enable ,\~sizeof(int)); +.BI int\~getsockopt(int\~ sockfd ,\~IPPROTO_IP,\~IP_RECVERR, +.BI " int\~*" enabled ,\~sizeof(int)); +.fi +.P +.EX +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 */ +}; +.EE +.P +.nf +#define SO_EE_ORIGIN_NONE 0 +#define SO_EE_ORIGIN_LOCAL 1 +#define SO_EE_ORIGIN_ICMP 2 +#define SO_EE_ORIGIN_ICMP6 3 +.P +.B struct\~sockaddr\~*SO_EE_OFFENDER(struct\~sock_extended_err\~*); +.SH DESCRIPTION +Enable extended reliable error message passing +(default: disabled). +.P +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 +.BR recvmsg (2) +with the +.B MSG_ERRQUEUE +flag set. +The +.I sock_extended_err +structure describing the error +will be passed in an ancillary message +with the type +.B IP_RECVERR +and the level +.BR IPPROTO_IP . +.\" or SOL_IP on Linux +This is useful for reliable error handling on unconnected sockets. +The received data portion of the error queue contains the error packet. +.P +The +.B IP_RECVERR +control message contains a +.I sock_extended_err +structure. +.TP +.I .ee_errno +contains the +.I errno +number of the queued error. +.TP +.I .ee_origin +is the origin code of where the error originated. +.P +The other fields are protocol-specific. +.P +The macro +.BR 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 +.I .sa_family +member of the +.I sockaddr +contains +.B AF_UNSPEC +and the other fields of the +.I sockaddr +are undefined. +.P +IP uses the +.I sock_extended_err +structure as follows: +.IP \[bu] 3 +.I .ee_origin +is set to +.B SO_EE_ORIGIN_ICMP +for errors received as an ICMP packet, +or +.B SO_EE_ORIGIN_LOCAL +for locally generated errors. +Unknown values should be ignored. +.IP \[bu] +.I .ee_type +and +.I .ee_code +are set from the type and code fields of the ICMP header. +.IP \[bu] +.I .ee_info +contains the discovered MTU for +.B EMSGSIZE +errors. +.IP \[bu] +The message also contains the +.I sockaddr_in +of the node caused that the error, +which can be accessed with the +.BR SO_EE_OFFENDER () +macro. +.P +The +.I .sin_family +field of the +.BR SO_EE_OFFENDER () +address is +.B AF_UNSPEC +when the source was unknown. +When the error originated from the network, all IP options +.RB ( IP_OPTIONS (2const), +.BR 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. +.\" FIXME . Is it a good idea to document that? It is a dubious feature. +.\" On +.\" .B SOCK_STREAM +.\" sockets, +.\" .B IP_RECVERR +.\" has slightly different semantics. Instead of +.\" saving the errors for the next timeout, it passes all incoming +.\" errors immediately to the user. +.\" This might be useful for very short-lived TCP connections which +.\" need fast error handling. Use this option with care: +.\" it makes TCP unreliable +.\" by not allowing it to recover properly from routing +.\" shifts and other normal +.\" conditions and breaks the protocol specification. +.P +TCP has no error queue; +.B MSG_ERRQUEUE +is not permitted on +.B SOCK_STREAM +sockets. +.B IP_RECVERR +is valid for TCP, +but all errors are returned by socket function return or +.B SO_ERROR +only. +.P +For raw sockets, +.B IP_RECVERR +enables passing of all received ICMP errors to the +application, otherwise errors are reported only on connected sockets +.SH ERRORS +See +.BR IPPROTO_IP (2const). +See +.BR setsockopt (2). +See +.BR ip (7). +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.2. +.\" Precisely: since Linux 2.1.15 +.SH SEE ALSO +.BR IPPROTO_IP (2const), +.BR setsockopt (2), +.BR ip (7) |