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 .