]> git.saurik.com Git - apple/xnu.git/blame - bsd/man/man4/icmp.4
xnu-1504.15.3.tar.gz
[apple/xnu.git] / bsd / man / man4 / icmp.4
CommitLineData
9bccf70c
A
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
49is the error and control message protocol used
50by
51.Tn IP
52and the Internet protocol family. It may be accessed
53through a
54.Dq raw socket
55for network monitoring
56and diagnostic functions.
57The
58.Fa proto
59parameter to the socket call to create an
60.Tn ICMP
61socket
62is obtained from
63.Xr getprotobyname 3 .
64.Tn ICMP
65sockets are connectionless,
66and are normally used with the
67.Xr sendto
68and
69.Xr recvfrom
70calls, though the
71.Xr connect 2
72call may also be used to fix the destination for future
73packets (in which case the
74.Xr read 2
75or
76.Xr recv 2
77and
78.Xr write 2
79or
80.Xr send 2
81system calls may be used).
82.Pp
83Outgoing packets automatically have an
84.Tn IP
85header prepended to
86them (based on the destination address).
87Incoming packets are received with the
88.Tn IP
89header and options intact.
2d21ac55
A
90Note that the ip_off and ip_len fields are in host byte order.
91For more information about the IP header structure, see
92.Xr ip 4 .
9bccf70c
A
93.Ss "Non-privileged ICMP"
94.Pp
95.Tn ICMP
96sockets can be opened with the
97.Dv SOCK_DGRAM
98socket type without requiring root privileges. The synopsis is the following:
99.Pp
55e303ae 100.Fn socket AF_INET SOCK_DGRAM IPPROTO_ICMP
9bccf70c 101.Pp
9bccf70c
A
102Datagram oriented
103.Tn ICMP
104sockets offer a subset of the functionality available to raw
105.Tn ICMP
106sockets. Only
107.Tn IMCP
108request messages of the following types can be sent:
109ICMP_ECHO, ICMP_TSTAMP or ICMP_MASKREQ.
110The code field must be the value zero (0).
111The minimal length of an
112.Tn ICMP
113message request is eight (8) octets.
114.Pp
2d21ac55
A
115The advantage of using datagram oriented
116.Tn ICMP
117sockets is that even a non-privileged process can use
118.Tn ICMP
119echo requests to gauge the quality of the connectivity to a host,
120or to receive
121.Tn ICMP
122destination unreachable message for path MTU discovery, or to receive
123time exceeded messages for traceroute.
124.Pp
9bccf70c
A
125The following
126.Tn IP
127level option can be used with datagram oriented
128.Tn ICMP
129sockets:
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
151When the
152.Tn IP
153option IP_HDRINCL is used, the provided
154.Tn IP
155header 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
168address 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
173The maximum length of a IMCP message that can be sent is controlled
174by the sysctl
175variable net.inet.raw.maxdgram.
176.Sh DIAGNOSTICS
177A socket operation may fail with one of the following errors returned:
178.Bl -tag -width [EADDRNOTAVAIL]
179.It Bq Er EISCONN
180when trying to establish a connection on a socket which
181already has one, or when trying to send a datagram with the destination
182address specified and the socket is already connected;
183.It Bq Er ENOTCONN
184when trying to send a datagram, but
185no destination address is specified, and the socket hasn't been
186connected;
187.It Bq Er ENOBUFS
188when the system runs out of memory for
189an internal data structure;
190.It Bq Er EADDRNOTAVAIL
191when an attempt is made to create a
192socket with a network address for which no network interface
193exists;
194.It Bq Er EINVAL
195when an invalid value is used with
196.Tn IMCP
197datagram socket for a field of the
198.Tn IP
199or
200.Tn ICMP
201header.
202.El
203.Sh SEE ALSO
9bccf70c 204.Xr recv 2 ,
2d21ac55 205.Xr send 2 ,
9bccf70c 206.Xr inet 4 ,
2d21ac55 207.Xr intro 4 ,
9bccf70c
A
208.Xr ip 4
209.Sh HISTORY
210The
211.Nm
212protocol appeared in
213.Bx 4.3 .