]> git.saurik.com Git - apple/xnu.git/blob - bsd/man/man4/icmp.4
xnu-7195.101.1.tar.gz
[apple/xnu.git] / bsd / man / man4 / icmp.4
1 .\" $NetBSD: icmp.4,v 1.3 1994/11/30 16:22:14 jtc Exp $
2 .\"
3 .\" Copyright (c) 1986, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. All advertising materials mentioning features or use of this software
15 .\" must display the following acknowledgement:
16 .\" This product includes software developed by the University of
17 .\" California, Berkeley and its contributors.
18 .\" 4. Neither the name of the University nor the names of its contributors
19 .\" may be used to endorse or promote products derived from this software
20 .\" without specific prior written permission.
21 .\"
22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" SUCH DAMAGE.
33 .\"
34 .\" @(#)icmp.4 8.1 (Berkeley) 6/5/93
35 .\"
36 .Dd June 19, 2002
37 .Dt ICMP 4
38 .Os BSD 4.3
39 .Sh NAME
40 .Nm icmp
41 .Nd Internet Control Message Protocol
42 .Sh SYNOPSIS
43 .Fd #include <sys/socket.h>
44 .Fd #include <netinet/in.h>
45 .Ft int
46 .Fn socket AF_INET SOCK_RAW proto
47 .Sh DESCRIPTION
48 .Tn ICMP
49 is the error and control message protocol used
50 by
51 .Tn IP
52 and the Internet protocol family. It may be accessed
53 through a
54 .Dq raw socket
55 for network monitoring
56 and diagnostic functions.
57 The
58 .Fa proto
59 parameter to the socket call to create an
60 .Tn ICMP
61 socket
62 is obtained from
63 .Xr getprotobyname 3 .
64 .Tn ICMP
65 sockets are connectionless,
66 and are normally used with the
67 .Xr sendto
68 and
69 .Xr recvfrom
70 calls, though the
71 .Xr connect 2
72 call may also be used to fix the destination for future
73 packets (in which case the
74 .Xr read 2
75 or
76 .Xr recv 2
77 and
78 .Xr write 2
79 or
80 .Xr send 2
81 system calls may be used).
82 .Pp
83 Outgoing packets automatically have an
84 .Tn IP
85 header prepended to
86 them (based on the destination address).
87 Incoming packets are received with the
88 .Tn IP
89 header and options intact.
90 Note that the ip_off and ip_len fields are in host byte order.
91 For more information about the IP header structure, see
92 .Xr ip 4 .
93 .Ss "Non-privileged ICMP"
94 .Pp
95 .Tn ICMP
96 sockets can be opened with the
97 .Dv SOCK_DGRAM
98 socket type without requiring root privileges. The synopsis is the following:
99 .Pp
100 .Fn socket AF_INET SOCK_DGRAM IPPROTO_ICMP
101 .Pp
102 Datagram oriented
103 .Tn ICMP
104 sockets offer a subset of the functionality available to raw
105 .Tn ICMP
106 sockets. Only
107 .Tn IMCP
108 request messages of the following types can be sent:
109 ICMP_ECHO, ICMP_TSTAMP or ICMP_MASKREQ.
110 The code field must be the value zero (0).
111 The minimal length of an
112 .Tn ICMP
113 message request is eight (8) octets.
114 .Pp
115 The advantage of using datagram oriented
116 .Tn ICMP
117 sockets is that even a non-privileged process can use
118 .Tn ICMP
119 echo requests to gauge the quality of the connectivity to a host,
120 or to receive
121 .Tn ICMP
122 destination unreachable message for path MTU discovery, or to receive
123 time exceeded messages for traceroute.
124 .Pp
125 The following
126 .Tn IP
127 level option can be used with datagram oriented
128 .Tn ICMP
129 sockets:
130 .Bl -column ip_opts -offset 4n
131 .It IP_OPTIONS
132 .It IP_HDRINCL
133 .It IP_TOS
134 .It IP_TTL
135 .It IP_RECVOPTS
136 .It IP_RECVRETOPTS
137 .It IP_RECVDSTADDR
138 .It IP_RETOPTS
139 .It IP_MULTICAST_IF
140 .It IP_MULTICAST_TTL
141 .It IP_MULTICAST_LOOP
142 .It IP_ADD_MEMBERSHIP
143 .It IP_DROP_MEMBERSHIP
144 .It IP_MULTICAST_VIF
145 .It IP_PORTRANGE
146 .It IP_RECVIF
147 .It IP_IPSEC_POLICY
148 .It IP_STRIPHDR
149 .El
150 .Pp
151 When the
152 .Tn IP
153 option IP_HDRINCL is used, the provided
154 .Tn IP
155 header must obey the following rules:
156 .Bl -column ip_opts -offset 4n
157 .It ip_v Ta Must be IPVERSION (4);
158 .It ip_hl Ta Between 5 and 10 (inclusive);
159 .It ip_tos Ta Any value;
160 .It ip_len Ta Must be the total length of IP datagram (IP header + ICMP message);
161 .It ip_id Ta Must be zero, will be automatically set;
162 .It ip_off Ta Must be zero, will be automatically set;
163 .It ip_ttl Ta Any value;
164 .It ip_p Ta Must be IPPROTO_IP;
165 .It ip_sum Ta Value ignored, will be automatically set;
166 .It ip_src Ta Must be an
167 .Tn IP
168 address currently assigned to one of the local interface or INADDR_ANY;
169 .It ip_dst Ta Any address;
170 .It ip_opts Ta Any option.
171 .El
172 .Pp
173 The maximum length of a IMCP message that can be sent is controlled
174 by the sysctl
175 variable net.inet.raw.maxdgram.
176 .Sh DIAGNOSTICS
177 A socket operation may fail with one of the following errors returned:
178 .Bl -tag -width [EADDRNOTAVAIL]
179 .It Bq Er EISCONN
180 when trying to establish a connection on a socket which
181 already has one, or when trying to send a datagram with the destination
182 address specified and the socket is already connected;
183 .It Bq Er ENOTCONN
184 when trying to send a datagram, but
185 no destination address is specified, and the socket hasn't been
186 connected;
187 .It Bq Er ENOBUFS
188 when the system runs out of memory for
189 an internal data structure;
190 .It Bq Er EADDRNOTAVAIL
191 when an attempt is made to create a
192 socket with a network address for which no network interface
193 exists;
194 .It Bq Er EINVAL
195 when an invalid value is used with
196 .Tn IMCP
197 datagram socket for a field of the
198 .Tn IP
199 or
200 .Tn ICMP
201 header.
202 .El
203 .Sh SEE ALSO
204 .Xr recv 2 ,
205 .Xr send 2 ,
206 .Xr inet 4 ,
207 .Xr intro 4 ,
208 .Xr ip 4
209 .Sh HISTORY
210 The
211 .Nm
212 protocol appeared in
213 .Bx 4.3 .