Debian Codegraph @

upstream/debian-unstable/man2/IP_RECVERR.2const

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .TH IP_RECVERR 2const 2025-11-25 "Linux man-pages 6.18"
6 .SH NAME
7 IP_RECVERR
8 \-
9 extended reliable error message passing
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .BR "#include <netinet/in.h>" " /* Definition of " IP* " constants */"
16 .B #include <sys/socket.h>
17 .P
18 .BI int\~setsockopt(int\~ sockfd ,\~IPPROTO_IP,\~IP_RECVERR,
19 .BI " const\~int\~*" enable ,\~sizeof(int));
20 .BI int\~getsockopt(int\~ sockfd ,\~IPPROTO_IP,\~IP_RECVERR,
21 .BI " int\~*" enabled ,\~sizeof(int));
22 .fi
23 .P
24 .EX
25 struct sock_extended_err {
26 uint32_t ee_errno; /* error number */
27 uint8_t ee_origin; /* where the error originated */
28 uint8_t ee_type; /* type */
29 uint8_t ee_code; /* code */
30 uint8_t ee_pad;
31 uint32_t ee_info; /* additional information */
32 uint32_t ee_data; /* other data */
33 /* More data may follow */
34 };
35 .EE
36 .P
37 .nf
38 #define SO_EE_ORIGIN_NONE 0
39 #define SO_EE_ORIGIN_LOCAL 1
40 #define SO_EE_ORIGIN_ICMP 2
41 #define SO_EE_ORIGIN_ICMP6 3
42 .P
43 .B struct\~sockaddr\~*SO_EE_OFFENDER(struct\~sock_extended_err\~*);
44 .SH DESCRIPTION
45 Enable extended reliable error message passing
46 (default: disabled).
47 .P
48 When enabled on a datagram socket,
49 all generated errors will be queued in a per-socket error queue.
50 When the user receives an error from a socket operation,
51 the errors can be received by calling
52 .BR recvmsg (2)
53 with the
54 .B MSG_ERRQUEUE
55 flag set.
56 The
57 .I sock_extended_err
58 structure describing the error
59 will be passed in an ancillary message
60 with the type
61 .B IP_RECVERR
62 and the level
63 .BR IPPROTO_IP .
64 .\" or SOL_IP on Linux
65 This is useful for reliable error handling on unconnected sockets.
66 The received data portion of the error queue contains the error packet.
67 .P
68 The
69 .B IP_RECVERR
70 control message contains a
71 .I sock_extended_err
72 structure.
73 .TP
74 .I .ee_errno
75 contains the
76 .I errno
77 number of the queued error.
78 .TP
79 .I .ee_origin
80 is the origin code of where the error originated.
81 .P
82 The other fields are protocol-specific.
83 .P
84 The macro
85 .BR SO_EE_OFFENDER ()
86 returns a pointer to the address of the network object
87 where the error originated from
88 given a pointer to the ancillary message.
89 If this address is not known,
90 the
91 .I .sa_family
92 member of the
93 .I sockaddr
94 contains
95 .B AF_UNSPEC
96 and the other fields of the
97 .I sockaddr
98 are undefined.
99 .P
100 IP uses the
101 .I sock_extended_err
102 structure as follows:
103 .IP \[bu] 3
104 .I .ee_origin
105 is set to
106 .B SO_EE_ORIGIN_ICMP
107 for errors received as an ICMP packet,
108 or
109 .B SO_EE_ORIGIN_LOCAL
110 for locally generated errors.
111 Unknown values should be ignored.
112 .IP \[bu]
113 .I .ee_type
114 and
115 .I .ee_code
116 are set from the type and code fields of the ICMP header.
117 .IP \[bu]
118 .I .ee_info
119 contains the discovered MTU for
120 .B EMSGSIZE
121 errors.
122 .IP \[bu]
123 The message also contains the
124 .I sockaddr_in
125 of the node caused that the error,
126 which can be accessed with the
127 .BR SO_EE_OFFENDER ()
128 macro.
129 .P
130 The
131 .I .sin_family
132 field of the
133 .BR SO_EE_OFFENDER ()
134 address is
135 .B AF_UNSPEC
136 when the source was unknown.
137 When the error originated from the network, all IP options
138 .RB ( IP_OPTIONS (2const),
139 .BR IP_TTL (2const),
140 etc.) enabled on the socket and contained in the
141 error packet are passed as control messages.
142 The payload of the packet causing the error is returned as normal payload.
143 .\" FIXME . Is it a good idea to document that? It is a dubious feature.
144 .\" On
145 .\" .B SOCK_STREAM
146 .\" sockets,
147 .\" .B IP_RECVERR
148 .\" has slightly different semantics. Instead of
149 .\" saving the errors for the next timeout, it passes all incoming
150 .\" errors immediately to the user.
151 .\" This might be useful for very short-lived TCP connections which
152 .\" need fast error handling. Use this option with care:
153 .\" it makes TCP unreliable
154 .\" by not allowing it to recover properly from routing
155 .\" shifts and other normal
156 .\" conditions and breaks the protocol specification.
157 .P
158 TCP has no error queue;
159 .B MSG_ERRQUEUE
160 is not permitted on
161 .B SOCK_STREAM
162 sockets.
163 .B IP_RECVERR
164 is valid for TCP,
165 but all errors are returned by socket function return or
166 .B SO_ERROR
167 only.
168 .P
169 For raw sockets,
170 .B IP_RECVERR
171 enables passing of all received ICMP errors to the
172 application, otherwise errors are reported only on connected sockets
173 .SH ERRORS
174 See
175 .BR IPPROTO_IP (2const).
176 See
177 .BR setsockopt (2).
178 See
179 .BR ip (7).
180 .SH STANDARDS
181 Linux.
182 .SH HISTORY
183 Linux 2.2.
184 .\" Precisely: since Linux 2.1.15
185 .SH SEE ALSO
186 .BR IPPROTO_IP (2const),
187 .BR setsockopt (2),
188 .BR ip (7)