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. 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 . 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 100.Fn socket AF_INET SOCK_DGRAM IPPROTO_ICMP 101.Pp 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 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 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 204.Xr recv 2 , 205.Xr send 2 , 206.Xr inet 4 , 207.Xr intro 4 , 208.Xr ip 4 209.Sh HISTORY 210The 211.Nm 212protocol appeared in 213.Bx 4.3 . 214