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 .Ss "Non-privileged ICMP"
  91 .Pp
  92 .Tn ICMP
  93 sockets can be opened with the
  94 .Dv SOCK_DGRAM
  95 socket type without requiring root privileges. The synopsis is the following:
  96 .Pp
  97 .Fn socket AF_INET SOCK_DGRAM IPPROTO_ICMP
  98 .Pp
  99 This can be used by non root privileged processes to send
 100 .Tn ICMP
 101 echo requests to gauge the quality of the connectivity to a host, to receive
 102 .Tn ICMP
 103 destination unreachable message for path MTU discovery, or to receveive
 104 time exceeded message for traceroute.
 105 .Pp
 106 Datagram oriented
 107 .Tn ICMP
 108 sockets offer a subset of the functionality available to raw
 109 .Tn ICMP
 110 sockets. Only
 111 .Tn IMCP
 112 request messages of the following types can be sent:
 113 ICMP_ECHO, ICMP_TSTAMP or ICMP_MASKREQ.
 114 The code field must be the value zero (0).
 115 The minimal length of an
 116 .Tn ICMP
 117 message request is eight (8) octets.
 118 .Pp
 119 The following
 120 .Tn IP
 121 level option can be used with datagram oriented
 122 .Tn ICMP
 123 sockets:
 124 .Bl -column ip_opts -offset 4n
 125 .It IP_OPTIONS
 126 .It IP_HDRINCL
 127 .It IP_TOS
 128 .It IP_TTL
 129 .It IP_RECVOPTS
 130 .It IP_RECVRETOPTS
 131 .It IP_RECVDSTADDR
 132 .It IP_RETOPTS
 133 .It IP_MULTICAST_IF
 134 .It IP_MULTICAST_TTL
 135 .It IP_MULTICAST_LOOP
 136 .It IP_ADD_MEMBERSHIP
 137 .It IP_DROP_MEMBERSHIP
 138 .It IP_MULTICAST_VIF
 139 .It IP_PORTRANGE
 140 .It IP_RECVIF
 141 .It IP_IPSEC_POLICY
 142 .It IP_STRIPHDR
 143 .El
 144 .Pp
 145 When the
 146 .Tn IP
 147 option IP_HDRINCL is used, the provided
 148 .Tn IP
 149 header must obey the following rules:
 150 .Bl -column ip_opts -offset 4n
 151 .It ip_v Ta Must be IPVERSION (4);
 152 .It ip_hl Ta Between 5 and 10 (inclusive);
 153 .It ip_tos Ta Any value;
 154 .It ip_len Ta Must be the total length of IP datagram (IP header + ICMP message);
 155 .It ip_id Ta Must be zero, will be automatically set;
 156 .It ip_off Ta Must be zero, will be automatically set;
 157 .It ip_ttl Ta Any value;
 158 .It ip_p Ta Must be IPPROTO_IP;
 159 .It ip_sum Ta Value ignored, will be automatically set;
 160 .It ip_src Ta Must be an
 161 .Tn IP
 162 address currently assigned to one of the local interface or INADDR_ANY;
 163 .It ip_dst Ta Any address;
 164 .It ip_opts Ta Any option.
 165 .El
 166 .Pp
 167 The maximum length of a IMCP message that can be sent is controlled
 168 by the sysctl
 169 variable net.inet.raw.maxdgram.
 170 .Sh DIAGNOSTICS
 171 A socket operation may fail with one of the following errors returned:
 172 .Bl -tag -width [EADDRNOTAVAIL]
 173 .It Bq Er EISCONN
 174 when trying to establish a connection on a socket which
 175 already has one, or when trying to send a datagram with the destination
 176 address specified and the socket is already connected;
 177 .It Bq Er ENOTCONN
 178 when trying to send a datagram, but
 179 no destination address is specified, and the socket hasn't been
 180 connected;
 181 .It Bq Er ENOBUFS
 182 when the system runs out of memory for
 183 an internal data structure;
 184 .It Bq Er EADDRNOTAVAIL
 185 when an attempt is made to create a
 186 socket with a network address for which no network interface
 187 exists;
 188 .It Bq Er EINVAL
 189 when an invalid value is used with
 190 .Tn IMCP
 191 datagram socket for a field of the
 192 .Tn IP
 193 or
 194 .Tn ICMP
 195 header.
 196 .El
 197 .Sh SEE ALSO
 198 .Xr send 2 ,
 199 .Xr recv 2 ,
 200 .Xr intro 4 ,
 201 .Xr inet 4 ,
 202 .Xr ip 4
 203 .Sh HISTORY
 204 The
 205 .Nm
 206 protocol appeared in
 207 .Bx 4.3 .