IP(4)               Linux Programmer's Manual               IP(4)

NAME
       ip - Linux IPv4 protocol implementation

SYNOPSIS
       #include <sys/socket.h>
       #include <net/netinet.h>

       tcp_socket = socket(PF_INET, SOCK_STREAM, 0);
       raw_socket = socket(PF_INET, SOCK_RAW, protocol);
       udp_socket = socket(PF_INET, SOCK_DGRAM, protocol);

DESCRIPTION
       Linux implements the IPv4 protocol described in RFC791 and
       RFC1122.  ip contains a level 2  multicasting  implementa-
       tion comforming to RFC1112.  It also contains an IP router
       including a packet filter.

       The protocol is implemented in the kernel on the basis  of
       a  BSD  compatible socket interface.  For more information
       on sockets, see socket(4).

       An IP socket is created by calling the socket(2)  function
       with  a PF_INET socket family argument. Valid socket types
       are SOCK_STREAM to open a  tcp(4)  socket,  SOCK_DGRAM  to
       open  a  udp(4)  socket, or SOCK_RAW to open a raw socket.
       protocol is the  IP  protocol  in  the  IP  header  to  be
       received  or  sent.  For  TCP  and  UDP  sockets,  only 0,
       IPPROTO_TCP , or IPPROTO_UDP are valid. For  SOCK_RAW  you
       may  specify  a  valid IANA IP protocol defined in RFC1700
       assigned numbers.

       Raw sockets may only be opened by a process with effective
       user id 0 or when the process has the CAP_NET_RAW capabil-
       ity.

       When a process wants to receive new  incoming  packets  or
       connections,  it  should  be  bound  to  a local interface
       address using bind(2).  When INADDR_ANY  is  specified  it
       will  bind  to any local interface.  A bound TCP socket is
       unavailable  for  some  time  after  closing,  unless  the
       SO_REUSEADDR flag is set.

ADDRESS FORMAT
       An  IP socket address is defined as a combination of an IP
       interface address and a port number.

              struct sockaddr_in {
                  sa_family_t sin_family;/* address family: AF_INET */
                  u_int16_t   sin_port; /* port in network byte order */
                  struct in_addr  sin_addr;/* internet address */
              };

              /* Internet address. */
              struct in_addr {
                  u_int32_t s_addr; /* IPv4 address in network byte order */
              };

       sin_family is always set to AF_INET.  This is required; in
       Linux  2.2  most  networking  functions return EINVAL when
       this setting is missing.  sin_port contains  the  port  in
       network byte order. The port numbers below 1024 are called
       reserved ports.  Only processes with the effective user id
       0 or the CAP_NET_BIND_SERVICE attribute set may bind(2) to
       these sockets. Note that the raw IPv4 protocol as such has
       no  concept of a port, they are only implemented by higher
       protocols like tcp(4) and udp(4).

       sin_addr is the host address.  The addr member  of  struct
       in_addr  contains  the  host  interface address in network
       order.   in_addr  should  be  only  accessed   using   the
       inet_aton(3), inet_addr(3), inet_makeaddr(3) library func-
       tions or directly with the name resolver  (see  gethostby-
       name(3) ). IPv4 addresses are divided into unicast, broad-
       cast and multicast addresses. Unicast addresses specify  a
       single  interface  of  a host, broadcast addresses specify
       all host on a network and multicast addresses address  all
       hosts   in  a  multicast  group.  Datagrams  to  broadcast
       addresses are only passed to  the  user  when  the  socket
       broadcast  flag  is  set.   To send datagrams to broadcast
       addresses it has to be set too.  Connection oriented sock-
       ets are only allowed to use unicast addresses.

       Note  that  the  address and the port are always stored in
       network order, this particulary means  that  you  need  to
       call  htons(3)  on  the number that is assigned to a port.
       All address/port manipulation functions  in  the  standard
       library automatically convert to network order.

SOCKET OPTIONS
       IP supports some protocol specific socket options that can
       be set with setsockopt(2) and read by getsockopt(2).   The
       socket option level for IP is SOL_IP

       IP_OPTIONS
              Sets  or  get  the IP options to be sent with every
              packet from  this  socket.   The  arguments  are  a
              pointer  to  a  memory buffer contained the options
              and the option  length.   Setsockopt  sets  the  IP
              options  associated  with a socket.  Maximum option
              size for IPv4 is  40  bytes.  See  RFC791  for  the
              allowed   options.   When  the  initial  connection
              request packet for a SOCK_STREAM socket contains IP
              options  the  outgoing IP options will be automati-
              cally set to  the  received  options  with  routing
              headers reversed.  Thus, outgoing packets will echo
              the received options then.  After the connection is
              established  incoming  packets  are  not allowed to
              change  options  anymore.  The  processing  of  all
              incoming  source  routing  options  can be disabled
              using the accept_source_route sysctl, which is  off
              by default.  For datagram sockets IP options can be
              only set by the local user. getsockopt returns  the
              current send IP options.

       IP_PKTINFO
              Pass a IP_PKTINFO ancillary message that contains a
              pktinfo structure that  supplies  some  information
              about  the  incoming  packet.  This  only works for
              datagram oriented sockets.

              struct in_pktinfo
              {
                  unsigned int ipi_ifindex;   /* Interface index */
                  struct in_addr  ipi_spec_dst;/* Routing destination address */
                  struct in_addr  ipi_addr;   /* Header Destination address */
              };

              ipi_ifindex is  the  index  of  the  interface  the
              packet  was  received on.  The ipi_spec_dst address
              is the RFC specified destination  address  and  may
              differ  from  ipi_addr  when  the  packet  contains
              source routing options.

              If IP_PKTINFO is passed to sendmsg(2) then the out-
              going packet will be sent over the interface speci-
              fied in ipi_ifindex with  the  destination  address
              set to ipi_spec_dst

       IP_RECVTOS
              If  enabled  the IP_TOS ancillary message is passed
              with incomming packets. It contains a byte with the
              Type  of  Service/Precedence  field  of  the packet
              header as a byte.  Expects a boolean integer  flag.

       IP_RECVTTL
              Set  or  read a flag to pass a IP_RECVTTL ancillary
              message that contains the time to live field of the
              received  packet  as  a  byte.  Not  supported  for
              SOCK_STREAM sockets.

       IP_RECVOPTS
              Pass all incoming IP  options  to  the  user  in  a
              IP_OPTIONS  control message. The routing header and
              other options are already filled in for  the  local
              host. Not supported for SOCK_STREAM sockets.

       IP_RETOPTS
              Identical  to  IP_RECVOPTS  but  returns raw unpro-
              cessed options  with  timestamp  and  route  record
              options not filled in for this hop.

       IP_TOS Set or receive the Type-Of-Service (TOS) field that
              is sent with every IP packet originating from  this
              socket.  It  is  used  to prioritize packets on the
              network.  TOS is a byte. There  are  some  standard
              TOS   flags  defined:  IPTOS_LOWDELAY  to  minimize
              delays for interactive traffic, IPTOS_THROUGHPUT to
              optimize  throughput, IPTOS_RELIABILITY to optimize
              for reliability, IPTOS_MINCOST should be  used  for
              "filler  data" where slow transmission doesn't mat-
              ter.  At most one of these TOS values can be speci-
              fied.  Other bits are invalid and shall be cleared.
              Linux per default  sends  IPTOS_LOWDELAY  datagrams
              first,  but the exact behaviour depends on the con-
              figured queueing discipline.   Some  high  priority
              levels  may  require  an effective user id 0 or the
              CAP_NET_ADMIN attribute set.  The priority can also
              be  set  in  a  protocol  independent  way  by  the
              (SOL_SOCKET,  SO_PRIORITY)   socket   option   (see
              socket(4) ).

       IP_TTL Set  or  receive  the  time to live field for every
              outgoing IP packet.

       IP_HDRINCL
              If enabled the user supplies his own ip  header  in
              front  of  the  user  data. Only valid for SOCK_RAW
              sockets. See raw(4) for more information. When this
              flag  is  enabled  the  values  set  by IP_OPTIONS,
              IP_TTL, IP_TOS are ignored.

              IP_RECVERR Enable extended reliable  error  message
              passing.   When  enabled  on  a datagram socket all
              generated errors will be  queued  in  a  per-socket
              error  queue.  When  the  user  gets an error (by a
              error return of a socket operation) then the errors
              can  be  received  by  calling  recvmsg(2) with the
              MSG_ERRQUEUE flag set. The sock_extended_err struc-
              ture  describing  the  error  will  be  passed in a
              ancillary message with the type IP_RECVERR and  the
              level  SOL_IP.   This  is useful for reliable error
              handling on unconnected sockets.  The received data
              portion  of  the  error  queue  contains  the error
              packet.

              IP uses the sock_extended_err structure as follows:
              ee_origin   set  to  SO_EE_ORIGIN_ICMP  for  errors
              received as an ICMP packet,  or  SO_EE_ORIGIN_LOCAL
              for  locally generated errors.  ee_type and ee_code
              are set from the type and code fields of  the  ICMP
              header.   ee_info  contains  the discovered MTU for
              EMSGSIZE errors.  ee_data is  currently  not  used.
              When  the error originated from the network, all IP
              options (IP_OPTIONS, IP_TTL, etc.) enabled  on  the
              socket and contained in the error packet are passed
              as control messages.  The  payload  of  the  packet
              causing the error is returned as normal data.

              On   SOCK_STREAM  TCP  sockets,  IP_RECVERR  has  a
              slightly different semantic.  Instead  of  queueing
              the  errors reliably, it passes all incoming errors
              immediately to the user. This might be  useful  for
              very  short-lived  TCP  connection  that need quick
              error handling. Use this option with care: it makes
              TCP  unreliable by not allowing it to recover prop-
              erly from routing shifts and  other  normal  condi-
              tions.    Note   that   TCP  has  no  error  queue;
              MSG_ERRQUEUE is not invalid on SOCK_STREAM sockets.
              All errors are passed by return value only.

              For  raw sockets, IP_RECVERR enables passing of all
              received ICMP errors to the  application.  This  is
              turned off by default for compatibility.

              It  sets  or  receives  an  integer  boolean  flag.
              IP_RECVERR defaults to off.

       IP_PMTU_DISCOVER
              Sets or receives the Path MTU Discovery setting for
              a socket. When enabled, Linux will perform Path MTU
              Discovery as defined in RFC1191 on this socket. The
              system-wide    default   is   controlled   by   the
              ip_no_pmtu_disc sysctl for SOCK_STREAM sockets, and
              disabled  on  all others. The user can retrieve the
              path  MTU  using  the  IP_MTU  or  the   IP_RECVERR
              options.

              +-------------------------+--------------------------------+
              |Path MTU discovery flags | Meaning                        |
              +-------------------------+--------------------------------+
              |IP_PMTUDISC_WANT         | Use per-route settings.        |
              +-------------------------+--------------------------------+
              |IP_PMTUDISC_DONT         | Never do Path MTU Discovery.   |
              +-------------------------+--------------------------------+
              |IP_PMTUDISC_DO           | Always do Path MTU Discovery.  |
              +-------------------------+--------------------------------+

              When PMTU discovery is enabled the kernel automati-
              cally keeps track of the path MTU. For TCP  sockets
              the  outgoing packets are automatically sized based
              on the path MTU, for datagram oriented sockets  the
              user  has  to size the datagrams appropiately. When
              it is enabled the  kernel  rejects  packets  bigger
              than  the  path MTU with EMSGSIZE raw(4) and udp(4)
              for more information.

       IP_MTU Retrieve the current known path MTU of the  current
              socket.   Only  valid when the socket has been con-
              nected. Returns an integer. Only valid  as  a  get-
              sockopt(2).

       IP_ROUTER_ALERT
              Pass all forwarded packets with the IP Router Alert
              option set to this socket. Only valid for raw sock-
              ets.  This  is useful, for instance, for user space
              RSVP daemons. Expects an integer argument.

       IP_MULTICAST_TTL
              Set or reads the  time-to-live  value  of  outgoing
              multicast  packets  for  this  socket.  It  is very
              important for multicast packets to set the smallest
              TTL  possible.   The  default is 1 which means that
              multicast packets don't  leave  the  local  network
              unless  the  user  program  explicitly requests it.
              Argument is an integer.

       IP_MULTICAST_LOOP
              Sets or reads a boolean  integer  argument  whether
              sent multicast packets should be looped back to the
              local sockets.

       IP_ADD_MEMBERSHIP
              Join  a  multicast  group.  Argument  is  a  struct
              ip_mreqn structure.

              struct ip_mreqn
              {
                  struct in_addr  imr_multiaddr;/* IP multicast group address */
                  struct in_addr  imr_address;/* IP address of local interface */
                  int             imr_ifindex;/* interface index */
              };

              imr_multiaddr contains the address of the multicast
              group the application wants to join or  leave.   It
              must  be a valid multicast address.  imr_address is
              the address of the local interface with  which  the
              system  should  join  the multicast group; if it is
              equal to INADDR_ANY  an  appropriate  interface  is
              chosen by the system.  imr_ifindex is the interface
              index of the interface that should  join/leave  the
              imr_multiaddr  group,  or  0 to indicate any inter-
              face.

              For compatibility, the  old  ip_mreq  structure  is
              still  supported.  It differs from ip_mreqn only by
              not including the imr_ifindex field. Only valid  as
              a setsockopt(2).

       IP_DROP_MEMBERSHIP
              Leave a multicast group. Argument is an ip_mreqn or
              ip_mreq structure similar to IP_ADD_MEMBERSHIP.

       IP_MULTICAST_IF
              Set the local device for a multicast socket.  Argu-
              ment is an ip_mreqn or ip_mreq structure similar to
              IP_ADD_MEMBERSHIP.

              When an invalid socket option  is  passed,  ENOPRO-
              TOOPT is returned.

SYSCTLS
       The IP protocol supports the sysctl interface to configure
       some global options. The sysctls can be accessed by  read-
       ing or writing the /proc/sys/net/ipv4/* files or using the
       sysctl(2) interface.

       ip_default_ttl
              Set the  default  time-to-live  value  of  outgoing
              packets.  This  can  be changed per socket with the
              IP_TTL option.

       ip_forward
              Enable IP forwarding with a boolean flag.  IP  for-
              warding can be also set on a per interface basis.

       ip_dynaddr
              Enable  dynamic  socket address rewriting on inter-
              face address change.  This  is  useful  for  dialup
              interface with changing IP addresses.

       ip_autoconfig
              Not documented.

       ip_local_port_range
              Contains two integers that define the default local
              port range allocated to sockets. Allocation  starts
              with the first number and ends with the second num-
              ber.

       ip_no_pmtu_disc
              If enabled, don't do Path  MTU  Discovery  for  TCP
              sockets  by default. Path MTU discovery may fail if
              misconfigured firewalls (that drop all  ICMP  pack-
              ets) or misconfigured interfaces (e.g., a point-to-
              point link where the both ends don't agree  on  the
              MTU)  are on the path. It is better to fix the bro-
              ken routers on the path than to turn off  Path  MTU
              Discovery  globally,  because not doing it incurs a
              high cost to the network.

       ipfrag_high_thresh and ipfrag_low_thresh
              If  the  amount  of  queued  IP  fragments  reaches
              ipfrag_high_thresh,  the  queue  is  pruned down to
              ipfrag_low_thresh.  Contains an  integer  with  the
              number of bytes.

IOCTLS
       These  ioctls can be accessed using ioctl(2).  The correct
       syntax is:

              error = ioctl(ip_socket, ioctl_type, value_ptr);

       SIOCGSTAMP
              Return a struct timeval with the receive  timestamp
              of the last packet passed to the user. This is use-
              ful for accurate round trip time measurements.  See
              setitimer(2) for a description of struct timeval.

       FIOCSETOWN and SIOCSPGRP
              Set  the  process  or process group (negative value
              passed with a process  group  id  of  the  absolute
              value)  to  send SIGIO or SIGURG signals to when an
              asynchronous I/O operation has finished  or  urgent
              data is available.  Argument is a pid_t.  Only pro-
              cesses with effective user id 0 may set this  value
              to  an  arbitrary process/group id; all others only
              to processes/groups with a matching effective group
              id or user id.

       FIOASYNC
              Set  a  flag to enable or disable asynchronous mode
              of the socket. Asynchronous mode means  that  SIGIO
              is raised when a new I/O event occurs.

              See  socket(4)  for  a  description of the valid IO
              events.

       FIOCGETOWN and SIOCGPGRP
              Get the  current  process  or  process  group  that
              receive  SIGIO or SIGURG signals, or 0 when none is
              set. Argument is a pid_t.

       The ioctls to  configure  firewalling  are  documented  in
       ipfw(4) from the ipchains package.

       Ioctls   to   configure   generic  device  parameters  are
       described in netdevice(4).

NOTES
       Be very careful with the SO_BROADCAST option - it  is  not
       privileged  in  Linux.  It is easy to overload the network
       with careless broadcasts. For new application protocols it
       is  better  to use a multicast group instead of broadcast-
       ing. Broadcasting is discouraged.

       Some other BSD sockets  implementations  provide  IP_RCVD-
       STADDR and IP_RECVIF socket options to get the destination
       address and the interface of received datagrams. Linux has
       the more general IP_PKTINFO for the same task.

ERRORS
       ENOTCONN
               The  operation  is  only  defined  on  a connected
               socket, but the socket wasn't connected.

       EINVAL  Invalid argument passed.

       EMSGSIZE
               Datagram is bigger than an MTU on the path and  it
               cannot be fragmented.

       EACCES  The user tried to execute an operation without the
               necessary permissions. These include sending to  a
               broadcast  address  without  having  the broadcast
               flag set, trying to modify the  firewall  settings
               without  effective  user id 0 or CAP_NET_ADMIN, or
               trying to bind to a reserved port  without  effec-
               tive user id 0 or CAP_NET_BIND_SERVICE.

       EADDRINUSE
               Tried to bind to an address already in use.

       ENOMEM and ENOBUFS
               Not enough memory available.

       ENOPROTOOPT and EOPNOTSUPP
               Invalid socket option passed.

       EPERM   User doesn't have permission to set high priority,
               change  configuration,  or  send  signals  to  the
               requested process or group,

       EADDRNOTAVAIL
               A  non-existent  interface  was  requested  or the
               requested source address was not local.

       EAGAIN  Operation on a non-blocking socket would block.

       ESOCKTNOSUPPORT
               The socket is not configured or an unknown  socket
               type was requested.

       EISCONN connect(2)  was  called  on  an  already connected
               socket.

       EALREADY
               An connection operation on a  non-blocking  socket
               is already in progress.

       ECONNABORTED
               A connection was closed during an accept(2).

       EPIPE   The  connection  was  unexpectedly  closed or shut
               down by the other end.

       ENOENT  SIOCGSTAMP was called on a socket where no  packet
               arrived.

       EHOSTUNREACH
               No  routing  table  entry  matches the destination
               address.

       ENODEV  Network device not available  or  not  capable  of
               sending IP.

       ENOPKG  A kernel subsystem was not configured.

       Other errors may be generated by the underlying protocols;
       see tcp(4), raw(4), udp(4) or the generic socket layer.

VERSIONS
       IP_PKTINFO,    IP_MTU,    IP_PMTU_DISCOVER,    IP_PKTINFO,
       IP_RECVERR,  and  IP_ROUTER_ALERT are new options in Linux
       2.2.

       struct ip_mreqn is new in Linux 2.2.  Linux 2.0 only  sup-
       ported ip_mreq.

       The sysctls were introduced with Linux 2.2.

COMPATIBILITY
       For   compatibility   with   Linux   2.0,   the   obsolete
       socket(PF_INET, SOCK_RAW, protocol) syntax is  still  sup-
       ported  to open a packet(4) socket. This is deprecated and
       should be replaced by socket(PF_PACKET,  SOCK_RAW,  proto-
       col)  instead.  The main difference is the new sockaddr_ll
       address  structure  for  generic  link  layer  information
       instead of the old sockaddr_pkt.

BUGS
       There are too many inconsistent error values.

       The  ioctls to configure IP-specific interface options and
       ARP tables are not described.

AUTHORS
       This man page was written by Andi Kleen.

SEE ALSO
       sendmsg(2),  recvmsg(2),  socket(4),  netlink(4),  tcp(4),
       udp(4), raw(4), ipfw(4)

       RFC791, RFC1122, RFC1812

Linux Man Page             24 Dec 1998                          1