home *** CD-ROM | disk | FTP | other *** search
/ The CDPD Public Domain Collection for CDTV 4 / CDPD_IV.bin / networking / tcpip / amitcp-2.2 / doc / protocols.doc < prev    next >
Text File  |  1994-06-29  |  36KB  |  807 lines
  1. TABLE OF CONTENTS
  2.  
  3. protocols/arp
  4. protocols/icmp
  5. protocols/if
  6. protocols/inet
  7. protocols/ip
  8. protocols/lo
  9. protocols/routing
  10. protocols/tcp
  11. protocols/udp
  12. protocols/arp                                                    protocols/arp
  13.  
  14.    NAME
  15.        arp - Address Resolution Protocol
  16.  
  17.    CONFIG
  18.        Any SANA-II device driver using ARP
  19.  
  20.    SYNOPSIS
  21.        #include <sys/socket.h>
  22.        #include <net/if_arp.h>
  23.        #include <netinet/in.h>
  24.  
  25.        s = socket(AF_INET, SOCK_DGRAM, 0);
  26.  
  27.    DESCRIPTION
  28.        ARP is a protocol used to dynamically map between Internet
  29.        Protocol (IP) and hardware addresses. It can be used by most
  30.        the SANA-II network interface drivers. The current
  31.        implementation supports only Internet Protocol (and is tested
  32.        only with Ethernet).  However, ARP is not limited to only that
  33.        combination.
  34.  
  35.        ARP caches IP-to-hardware address mappings. When an interface
  36.        requests a mapping for an address not in the cache, ARP queues
  37.        the message which requires the mapping and broadcasts a
  38.        message on the associated network requesting the address
  39.        mapping. If a response is provided, the new mapping is cached
  40.        and any pending message is transmitted. ARP will queue at most
  41.        one packet while waiting for a mapping request to be responded
  42.        to; only the most recently transmitted packet is kept.
  43.  
  44.        The address mapping caches are separate for each interface. The
  45.        amount of mappings in the cache may be specified with an
  46.        IoctlSocket() request. 
  47.  
  48.        To facilitate communications with systems which do not use ARP,
  49.        IoctlSocket() requests are provided to enter and delete entries
  50.        in the IP-to-Ethernet tables.
  51.  
  52.    USAGE
  53.        #include <sys/ioctl.h>
  54.        #include <sys/socket.h>
  55.        #include <net/if.h>
  56.        #include <net/if_arp.h>
  57.  
  58.        struct arpreq arpreq;
  59.  
  60.        IoctlSocket(s, SIOCSARP, (caddr_t)&arpreq);
  61.        IoctlSocket(s, SIOCGARP, (caddr_t)&arpreq);
  62.        IoctlSocket(s, SIOCDARP, (caddr_t)&arpreq);
  63.  
  64.        These three IoctlSocket()s take the same structure as an argument.
  65.        SIOCSARP sets an ARP entry, SIOCGARP gets an ARP entry, and SIOCDARP
  66.        deletes an ARP entry. These IoctlSocket() requests may be applied to
  67.        any socket descriptor (s). The arpreq structure contains:
  68.  
  69.        /* Maximum number of octets in protocol/hw address */
  70.        #define MAXADDRARP  16 
  71.  
  72.        /*
  73.         * ARP ioctl request. 
  74.         */
  75.        struct arpreq {
  76.                struct  sockaddr arp_pa;  /* protocol address */
  77.                struct  {                 /* hardware address */
  78.                  u_char sa_len;         /* actual length + 2 */
  79.                  u_char sa_family;             
  80.                  char   sa_data[MAXADDRARP];           
  81.                }  arp_ha;              
  82.                int     arp_flags;                   /* flags */
  83.        };
  84.  
  85.        /*  arp_flags and at_flags field values */
  86.        #define ATF_INUSE       0x01          /* entry in use */
  87.        #define ATF_COM         0x02       /* completed entry */
  88.        #define ATF_PERM        0x04       /* permanent entry */
  89.        #define ATF_PUBL        0x08         /* publish entry */
  90.  
  91.  
  92.        The interface whose ARP table is manipulated is specified by
  93.        arp_pa sockaddr. The address family for the arp_pa sockaddr
  94.        must be AF_INET; for the arp_ha sockaddr it must be AF_UNSPEC.
  95.        The length of arp_ha must match the length of used hardware
  96.        address. Maximum length for the hardware address is MAXADDRARP
  97.        bytes. The only flag bits which may be written are ATF_PERM
  98.        and ATF_PUBL. ATF_PERM makes the entry permanent if the
  99.        IoctlSocket() call succeeds. ATF_PUBL specifies that the ARP
  100.        code should respond to ARP requests for the indicated host
  101.        coming from other machines.  This allows a host to act as an
  102.        ARP server which may be useful in convincing an ARP-only
  103.        machine to talk to a non-ARP machine.
  104.  
  105.    UNSUPPORTED IN AmiTCP/IP
  106.  
  107.    AmiTCP/IP EXTENSIONS
  108.        There is an extension to the standard BSD4.4 ARP ioctl interface to
  109.        access the contents of the whole ARP mapping cache. (In the BSD4.4
  110.        the static ARP table is accessed via the /dev/kmem.) The SIOCGARPT
  111.        ioctl takes the following arptabreq structure as an argument:
  112.  
  113.        /* 
  114.         * An AmiTCP/IP specific ARP table ioctl request
  115.         */
  116.        struct arptabreq {
  117.                struct arpreq atr_arpreq;  /* To identify the interface */
  118.                long   atr_size;          /* # of elements in atr_table */
  119.                long   atr_inuse;               /* # of elements in use */
  120.                struct arpreq *atr_table;
  121.        };
  122.  
  123.        The atr_arpreq specifies the used interface. The hardware address
  124.        for the interface is returned in the arp_ha field of atr_arpreq
  125.        structure.
  126.        
  127.        The SIOCGARPT ioctl reads at most atr_size entries from the cache
  128.        into the user supplied buffer atr_table, if it is not NULL. Actual
  129.        amount of returned entries is returned in atr_size. The current
  130.        amount of cached mappings is returned in the atr_inuse.
  131.        
  132.        The SIOCGARPT ioctl has following usage:
  133.  
  134.        struct arpreq cache[N];
  135.        struct arptabreq arptab = { N, 0, cache };
  136.  
  137.        IoctlSocket(s, SIOCGARPT, (caddr_t)&arptabreq);
  138.  
  139.    DIAGNOSTICS
  140.        ARP watches passively for hosts impersonating the local host
  141.        (that  is,  a  host which responds to an ARP mapping request
  142.        for the local host's address).
  143.  
  144.        "duplicate IP address a.b.c.d!!"
  145.        "sent from hardware address: %x:%x:...:%x:%x"
  146.  
  147.        ARP  has  discovered  another host on the local network
  148.        which responds to mapping requests for its own Internet
  149.        address.
  150.  
  151.    BUGS
  152.        The ARP is tested only with Ethernet. Other network hardware may
  153.        require special ifconfig configuration.
  154.  
  155.    SEE ALSO
  156.        inet, netutil/arp, netutil/ifconfig, <net/if_arp.h>
  157.  
  158.        Plummer, Dave, ``An  Ethernet  Address  Resolution  Protocol
  159.        -or-  Converting Network Protocol Addresses to 48.bit Ether-
  160.        net Addresses for Transmission on Ethernet  Hardware,''  RFC
  161.        826,  Network  Information  Center, SRI International, Menlo
  162.        Park, Calif., November 1982. (Sun 800-1059-10)
  163.  
  164. protocols/icmp                                                  protocols/icmp
  165.  
  166.    NAME
  167.        icmp - Internet Control Message Protocol
  168.    
  169.    SYNOPSIS
  170.        #include <sys/socket.h>
  171.        #include <netinet/in.h>
  172.    
  173.        int
  174.        socket(AF_INET, SOCK_RAW, proto)
  175.    
  176.    DESCRIPTION
  177.        ICMP is the error and control message protocol used by IP and the
  178.        Internet protocol family.  It may be accessed through a ``raw
  179.        socket'' for network monitoring and diagnostic functions.  The proto
  180.        parameter to the socket call to create an ICMP socket is obtained
  181.        from getprotobyname().  ICMP sockets are connectionless, and are
  182.        normally used with the sendto() and recvfrom() calls, though the
  183.        connect() call may also be used to fix the destination for future
  184.        packets (in which case the recv() and send() socket library calls
  185.        may be used).
  186.  
  187.        Outgoing packets automatically have an IP header prepended to them
  188.        (based on the destination address).  Incoming packets are received
  189.        with the IP header and options intact.
  190.    
  191.    DIAGNOSTICS
  192.        A socket operation may fail with one of the following errors
  193.        returned:
  194.    
  195.        [EISCONN]        when trying to establish a connection on a socket
  196.                         which already has one, or when trying to send a
  197.                         datagram with the destination address specified and
  198.                         the socket is already connected;
  199.    
  200.        [ENOTCONN]       when trying to send a datagram, but no destination
  201.                         address is specified, and the socket hasn't been
  202.                         connected;
  203.    
  204.        [ENOBUFS]        when the system runs out of memory for an internal
  205.                         data structure;
  206.    
  207.        [EADDRNOTAVAIL]  when an attempt is made to create a socket with a
  208.                         network address for which no network interface
  209.                         exists.
  210.    
  211.    SEE ALSO
  212.        bsdsocket.library/send(),  bsdsocket.library/recv(), inet,  ip
  213.    
  214.    HISTORY
  215.        The icmp protocol is originally from 4.3BSD.
  216.  
  217. protocols/if                                                      protocols/if
  218.  
  219.    NAME
  220.        if - Network Interface to SANA-II devices
  221.  
  222.    DESCRIPTION
  223.        Each network interface in the AmiTCP/IP corresponds to a path
  224.        through which messages may be sent and received.  A network
  225.        interface usually has a SANA-II device driver associated with it,
  226.        though the loopback interface, "lo", do not. The network interface
  227.        in the AmiTCP/IP (sana_softc) is superset of the BSD Unix network
  228.        interface.
  229.  
  230.        When the network interface is first time referenced, AmiTCP/IP tries
  231.        to open the corresponding SANA-II device driver. If successful, a
  232.        software interface to the SANA-II device is created. The "network/"
  233.        prefix is added to the SANA-II device name, if needed. Once the
  234.        interface has acquired its address, it is expected to install a
  235.        routing table entry so that messages can be routed through it.
  236.  
  237.        The SANA-II interfaces must be configured before they will allow
  238.        traffic to flow through them. It is done after the interface is
  239.        assigned a protocol address with a SIOCSIFADDR ioctl. Some
  240.        interfaces may use the protocol address or a part of it as their
  241.        hardware address. On interfaces where the network-link layer address
  242.        mapping is static, only the network number is taken from the ioctl;
  243.        the remainder is found in a hardware specific manner. On interfaces
  244.        which provide dynamic network-link layer address mapping facilities
  245.        (for example, Ethernets or Arcnets using ARP), the entire address
  246.        specified in the ioctl is used.
  247.  
  248.        The following ioctl calls may be used to manipulate network
  249.        interfaces. Unless specified otherwise, the request takes an ifreq
  250.        structure as its parameter. This structure has the form
  251.  
  252.        struct ifreq {
  253.          char ifr_name[IFNAMSIZ]; /* interface name (eg. "slip.device/0")*/
  254.          union {
  255.            struct sockaddr ifru_addr;
  256.            struct sockaddr ifru_dstaddr;
  257.            short           ifru_flags;
  258.          } ifr_ifru;
  259.        #define ifr_addr    ifr_ifru.ifru_addr                 /* address */
  260.        #define ifr_dstaddr ifr_ifru.ifru_dstaddr   /* end of p-to-p link */
  261.        #define ifr_flags   ifr_ifru.ifru_flags                  /* flags */
  262.        };
  263.  
  264.        SIOCSIFADDR      Set interface address. Following the address
  265.                         assignment, the ``initialization'' routine for
  266.                         the interface is called.
  267.  
  268.        SIOCGIFADDR      Get interface address.
  269.  
  270.        SIOCSIFDSTADDR   Set point to point address for interface.
  271.  
  272.        SIOCGIFDSTADDR   Get point to point address for interface.
  273.  
  274.        SIOCSIFFLAGS     Set interface flags field. If the interface is
  275.                         marked down, any processes currently routing
  276.                         packets through the interface are notified.
  277.  
  278.        SIOCGIFFLAGS     Get interface flags.
  279.  
  280.        SIOCGIFCONF      Get interface configuration list. This request
  281.                         takes an ifconf structure (see below) as a
  282.                         value-result parameter. The ifc_len field should be
  283.                         initially set to the size of the buffer pointed to
  284.                         by ifc_buf. On return it will contain the length,
  285.                         in bytes, of the configuration list.
  286.  
  287.        /*
  288.         * Structure used in SIOCGIFCONF request.
  289.         * Used to retrieve interface configuration
  290.         * for machine (useful for programs which
  291.         * must know all networks accessible).
  292.         */
  293.        struct ifconf {
  294.          int  ifc_len;                      /* size of associated buffer */
  295.          union {
  296.            caddr_t       ifcu_buf;
  297.            struct ifreq *ifcu_req;
  298.          } ifc_ifcu;
  299.        #define ifc_buf ifc_ifcu.ifcu_buf               /* buffer address */
  300.        #define ifc_req ifc_ifcu.ifcu_req /* array of structures returned */
  301.        };
  302.  
  303.  
  304.    UNSUPPORTED IN AmiTCP/IP
  305.        These standard BSD ioctl codes are not currently supported:
  306.  
  307.        SIOCADDMULTI     Enable a multicast address for the interface. 
  308.  
  309.        SIOCDELMULTI     Disable a previously set multicast address.
  310.  
  311.        SIOCSPROMISC     Toggle promiscuous mode.
  312.  
  313.    AmiTCP/IP EXTENSIONS
  314.        The following ioctls are used to configure protocol and hardware
  315.        specific properties of a sana_softc interface. They are used in the
  316.        AmiTCP/IP only.
  317.  
  318.        SIOCSSANATAGS    Set SANA-II specific properties with a tag list.
  319.  
  320.        SIOCGSANATAGS    Get SANA-II specific properties into a
  321.                         wiretype_parameters structure and a user tag list.
  322.  
  323.        struct wiretype_parameters
  324.        {
  325.          ULONG  wiretype;               /* the wiretype of the interface */
  326.          WORD   flags;                                      /* iff_flags */
  327.          struct TagItem *tags;                 /* tag list user provides */
  328.        };
  329.        
  330.    SEE ALSO
  331.        arp, lo, netutil/arp, netutil/ifconfig, <sys/ioctl.h>, <net/if.h>, 
  332.        <net/sana2tags.h>
  333.  
  334. protocols/inet                                                  protocols/inet
  335.  
  336.    NAME
  337.        inet - Internet protocol family
  338.    
  339.    SYNOPSIS
  340.        #include <sys/types.h>
  341.        #include <netinet/in.h>
  342.    
  343.    DESCRIPTION
  344.        The Internet protocol family implements a collection of protocols
  345.        which are centered around the Internet Protocol (IP) and which share
  346.        a common address format.  The Internet family provides protocol
  347.        support for the SOCK_STREAM, SOCK_DGRAM, and SOCK_RAW socket types.
  348.    
  349.    PROTOCOLS
  350.        The Internet protocol family is comprised of the Internet Protocol
  351.        (IP), the Address Resolution Protocol (ARP), the Internet Control
  352.        Message Protocol (ICMP), the Transmission Control Protocol (TCP),
  353.        and the User Datagram Protocol (UDP).
  354.    
  355.        TCP is used to support the SOCK_STREAM abstraction while UDP is used
  356.        to support the SOCK_DGRAM abstraction; (SEE ALSO tcp, SEE ALSO udp).
  357.        A raw interface to IP is available by creating an Internet socket of
  358.        type SOCK_RAW; (SEE ALSO ip).  ICMP is used by the kernel to handle
  359.        and report errors in protocol processing.  It is also accessible to
  360.        user programs; (SEE ALSO icmp).  ARP is used to translate 32-bit IP
  361.        addresses into varying length hardware addresses; (SEE ALSO arp).
  362.    
  363.        The 32-bit IP address is divided into network number and host number
  364.        parts.  It is frequency-encoded; the most significant bit is zero in
  365.        Class A addresses, in which the high-order 8 bits are the network
  366.        number.  Class B addresses have their high order two bits set to 10
  367.        and use the highorder 16 bits as the network number field.  Class C
  368.        addresses have a 24-bit network number part of which the high order
  369.        three bits are 110.  Sites with a cluster of local networks may
  370.        chose to use a single network number for the cluster; this is done
  371.        by using subnet addressing.  The local (host) portion of the address
  372.        is further subdivided into subnet number and host number parts.
  373.        Within a subnet, each subnet appears to be an individual network;
  374.        externally, the entire cluster appears to be a single, uniform
  375.        network requiring only a single routing entry.  Subnet addressing is
  376.        enabled and examined by the following ioctl commands on a datagram
  377.        socket in the Internet domain; they have the same form as the
  378.        SIOCIFADDR (SEE ALSO if) command.
  379.    
  380.        SIOCSIFNETMASK      Set interface network mask.  The network mask
  381.                            defines the network part of the address; if it
  382.                            contains more of the address than the address
  383.                            type would indicate, then subnets are in use.
  384.    
  385.        SIOCGIFNETMASK      Get interface network mask.
  386.    
  387.    ADDRESSING
  388.        IP addresses are four byte quantities, stored in network byte order
  389.        (the native Amiga byte order)
  390.    
  391.        Sockets in the Internet protocol family  use  the  following
  392.        addressing structure:
  393.             struct sockaddr_in {
  394.                  short     sin_family;
  395.                  u_short   sin_port;
  396.                  struct    in_addr sin_addr;
  397.                  char sin_zero[8];
  398.             };
  399.    
  400.        Functions in bsdsocket.library are provided to manipulate structures
  401.        of this form.
  402.    
  403.        The sin_addr field of the sockaddr_in structure specifies a local or
  404.        remote IP address.  Each network interface has its own unique IP
  405.        address.  The special value INADDR_ANY may be used in this field to
  406.        effect "wildcard" matching.  Given in a bind() call, this value
  407.        leaves the local IP address of the socket unspecified, so that the
  408.        socket will receive connections or messages directed at any of the
  409.        valid IP addresses of the system.  This can prove useful when a
  410.        process neither knows nor cares what the local IP address is or when
  411.        a process wishes to receive requests using all of its network
  412.        interfaces.  The sockaddr_in structure given in the bind() call must
  413.        specify an in_addr value of either IPADDR_ANY or one of the system's
  414.        valid IP addresses.  Requests to bind any other address will elicit
  415.        the error EADDRNOTAVAIL. When a connect() call is made for a socket
  416.        that has a wildcard local address, the system sets the sin_addr
  417.        field of the socket to the IP address of the network interface that
  418.        the packets for that connection are routed via.
  419.    
  420.        The sin_port field of the sockaddr_in structure specifies a port
  421.        number used by TCP or UDP. The local port address specified in a
  422.        bind() call is restricted to be greater than IPPORT_RESERVED
  423.        (defined in <netinet/in.h>) unless the creating process is running
  424.        as the super-user, providing a space of protected port numbers.  In
  425.        addition, the local port address must not be in use by any socket of
  426.        same address family and type.  Requests to bind sockets to port
  427.        numbers being used by other sockets return the error EADDRINUSE.  If
  428.        the local port address is specified as 0, then the system picks a
  429.        unique port address greater than IPPORT_RESERVED.  A unique local
  430.        port address is also picked when a socket which is not bound is used
  431.        in a connect() or send() call.  This allows programs which do not
  432.        care which local port number is used to set up TCP connections by
  433.        sim- ply calling socket() and then connect(), and to send UDP
  434.        datagrams with a socket() call followed by a send() call.
  435.    
  436.        Although this implementation restricts sockets to unique local port
  437.        numbers, TCP allows multiple simultaneous connections involving the
  438.        same local port number so long as the remote IP addresses or port
  439.        numbers are different for each connection.  Programs may explicitly
  440.        override the socket restriction by setting the SO_REUSEADDR socket
  441.        option with setsockopt (see getsockopt()).
  442.    
  443.    SEE ALSO
  444.        bsdsocket.library/bind(), bsdsocket.library/connect(),
  445.        bsdsocket.library/getsockopt(), bsdsocket.library/IoctlSocket(),
  446.        bsdsocket.library/send(), bsdsocket.library/socket(),
  447.        bsdsocket.library/gethostent(), bsdsocket.library/getnetent(),
  448.        bsdsocket.library/getprotoent(), bsdsocket.library/getservent(),
  449.        bsdsocket.library/inet_addr(), arp, icmp, ip, tcp, udp
  450.    
  451.        Network Information Center, DDN Protocol Handbook (3 vols.),
  452.        Network  Information  Center, SRI International, Menlo Park,
  453.        Calif., 1985.
  454.        A AmiTCP/IP Interprocess Communication Primer
  455.    
  456.    WARNING
  457.        The Internet protocol support is subject to change as the Internet
  458.        protocols develop.  Users should not depend on details of the
  459.        current implementation, but rather the services exported.
  460.  
  461. protocols/ip                                                      protocols/ip
  462.  
  463.    NAME
  464.        ip - Internet Protocol
  465.    
  466.    SYNOPSIS
  467.        #include <sys/socket.h>
  468.        #include <netinet/in.h>
  469.    
  470.        int
  471.        socket(AF_INET, SOCK_RAW, proto)
  472.    
  473.    DESCRIPTION
  474.        IP is the transport layer protocol used by the Internet protocol
  475.        family.  Options may be set at the IP level when using higher-level
  476.        protocols that are based on IP (such as TCP and UDP). It may also be
  477.        accessed through a ``raw socket'' when developing new protocols, or
  478.        special purpose applica- tions.
  479.    
  480.        A single generic option is supported at the IP level, IP_OPTIONS,
  481.        that may be used to provide IP options to be transmitted in the IP
  482.        header of each outgoing packet.  Options are set with setsockopt()
  483.        and examined with getsockopt().  The format of IP options to be sent
  484.        is that specified by the IP protocol specification, with one
  485.        exception: the list of addresses for Source Route options must
  486.        include the first-hop gateway at the beginning of the list of
  487.        gateways.  The first-hop gateway address will be extracted from the
  488.        option list and the size adjusted accordingly before use.  IP
  489.        options may be used with any socket type in the Internet family.
  490.    
  491.        Raw IP sockets are connectionless, and are normally used with the
  492.        sendto and recvfrom calls, though the connect() call may also be
  493.        used to fix the destination for future packets (in which case the
  494.        recv() and send() system calls may be used).
  495.    
  496.        If proto is 0, the default protocol IPPROTO_RAW is used for outgoing
  497.        packets, and only incoming packets destined for that protocol are
  498.        received.  If proto is non-zero, that protocol number will be used
  499.        on outgoing packets and to filter incoming packets.
  500.    
  501.        Outgoing packets automatically have an IP header prepended to them
  502.        (based on the destination address and the protocol number the socket
  503.        is created with).  Incoming packets are received with IP header and
  504.        options intact.
  505.    
  506.    DIAGNOSTICS
  507.        A socket operation may fail with one of the following errors
  508.        returned:
  509.    
  510.        [EISCONN]        when trying to establish a connection on a socket
  511.                         which already has one, or when trying to send a
  512.                         datagram with the destination address specified and
  513.                         the socket is already connected;
  514.    
  515.        [ENOTCONN]       when trying to send a datagram, but no destination
  516.                         address is specified, and the socket hasn't been
  517.                         connected;
  518.    
  519.        [ENOBUFS]        when the system runs out of memory for an internal
  520.                         data structure;
  521.    
  522.        [EADDRNOTAVAIL]  when an attempt is made to create a socket with a
  523.                         network address for which no network interface
  524.                         exists.
  525.    
  526.        The following errors specific to IP may occur when setting or
  527.        getting IP options:
  528.    
  529.        [EINVAL]         An unknown socket option name was given.
  530.    
  531.        [EINVAL]         The IP option field was improperly formed; an
  532.                         option field was shorter than the minimum value or
  533.                         longer than the option buffer provided.
  534.    
  535.    SEE ALSO
  536.        bsdsocket.library/getsockopt(), bsdsocket.library/send(),
  537.        bsdsocket.library/recv(), icmp, inet
  538.  
  539.    HISTORY
  540.        The ip protocol appeared in 4.2BSD.
  541.  
  542. protocols/lo                                                      protocols/lo
  543.  
  544.    NAME
  545.        lo - Software Loopback Network Interface
  546.  
  547.    SYNOPSIS
  548.        pseudo-device
  549.        loop
  550.  
  551.    DESCRIPTION
  552.        The loop interface is a software loopback mechanism which may be
  553.        used for performance analysis, software testing, and/or local
  554.        communication.  There is no SANA-II interface associated with lo.
  555.        As with other network interfaces, the loopback interface must have
  556.        network addresses assigned for each address family with which it is
  557.        to be used.  These addresses may be set or changed with the
  558.        SIOCSIFADDR ioctl. The loopback interface should be the last
  559.        interface configured, as protocols may use the order of
  560.        configuration as an indication of priority.  The loopback should
  561.        never be configured first unless no hardware interfaces exist.
  562.  
  563.    DIAGNOSTICS
  564.        "lo%d: can't handle af%d."
  565.        The interface was handed a message with ad- dresses formatted in an
  566.        unsuitable address family; the packet was dropped.
  567.  
  568.    SEE ALSO
  569.        inet, if, netutil/ifconfig
  570.  
  571.    BUGS 
  572.        Older BSD Unix systems enabled the loopback interface
  573.        automatically, using a nonstandard Internet address (127.1).  Use
  574.        of that address is now discouraged; a reserved host address for the
  575.        local network should be used instead.
  576.  
  577. protocols/routing                                            protocols/routing
  578.  
  579.    NAME
  580.        routing - system supporting for local network packet routing
  581.    
  582.    DESCRIPTION
  583.        The network facilities provided general packet routing,
  584.        leaving routing table maintenance to applications processes.
  585.    
  586.        A simple set of data structures comprise a ``routing table''
  587.        used in selecting the appropriate network interface when
  588.        transmitting packets.  This table contains a single entry for
  589.        each route to a specific network or host.  A user process, the
  590.        routing daemon, maintains this data base with the aid of two
  591.        socket specific ioctl commands, SIOCADDRT and SIOCDELRT.
  592.        The commands allow the addition and deletion of a single
  593.        routing table entry, respectively.  Routing table
  594.        manipulations may only be carried out by super-user.
  595.    
  596.        A routing table entry has the following form, as defined  in
  597.        <net/route.h>:
  598.             struct rtentry {
  599.                  u_long    rt_hash;
  600.                  struct    sockaddr rt_dst;
  601.                  struct    sockaddr rt_gateway;
  602.                  short     rt_flags;
  603.                  short     rt_refcnt;
  604.                  u_long    rt_use;
  605.                  struct    ifnet *rt_ifp;
  606.             };
  607.        with rt_flags defined from:
  608.          #define   RTF_UP         0x1              /* route usable */
  609.          #define   RTF_GATEWAY    0x2  /* destination is a gateway */
  610.          #define   RTF_HOST  0x4     /* host entry (net otherwise) */
  611.    
  612.        Routing table entries come in three flavors: for a specific
  613.        host, for all hosts on a specific network, for any destination
  614.        not matched by entries of the first two types (a wildcard
  615.        route).  When the system is booted, each network interface
  616.        autoconfigured installs a routing table entry when it wishes
  617.        to have packets sent through it.  Normally the interface
  618.        specifies the route through it is a ``direct'' connection to
  619.        the destination host or network.  If the route is direct, the
  620.        transport layer of a protocol family usually requests the
  621.        packet be sent to the same host specified in the packet.
  622.        Otherwise, the interface may be requested to address the
  623.        packet to an entity different from the eventual recipient
  624.        (that is, the packet is forwarded).
  625.    
  626.        Routing table entries installed by a user process may not
  627.        specify the hash, reference count, use, or interface fields;
  628.        these are filled in by the routing routines.  If a route is in
  629.        use when it is deleted (rt_refcnt is non-zero), the resources
  630.        associated with it will not be reclaimed until all references
  631.        to it are removed.
  632.    
  633.        The routing code returns EEXIST if requested to duplicate an
  634.        existing entry, ESRCH if requested to delete a non-existent
  635.        entry, or ENOBUFS if insufficient resources were available to
  636.        install a new route.
  637.    
  638.        The rt_use field contains the number of packets sent along the
  639.        route.  This value is used to select among multiple routes to
  640.        the same destination.  When multiple routes to the same
  641.        destination exist, the least used route is selected.
  642.    
  643.        A wildcard routing entry is specified with a zero destination
  644.        address value.  Wildcard routes are used only when the system
  645.        fails to find a route to the destination host and network.
  646.        The combination of wildcard routes and routing redirects can
  647.        provide an economical mechanism for routing traffic.
  648.    
  649.    SEE ALSO
  650.        bsdsocket.library/IoctlSocket(), netutil/route
  651.    
  652. protocols/tcp                                                    protocols/tcp
  653.  
  654.    NAME
  655.        tcp - Internet Transmission Control Protocol
  656.    
  657.    SYNOPSIS
  658.        #include <sys/socket.h>
  659.        #include <netinet/in.h>
  660.    
  661.        int
  662.        socket(AF_INET, SOCK_STREAM, 0)
  663.    
  664.    DESCRIPTION
  665.        The TCP protocol provides reliable, flow-controlled, two-way
  666.        transmission of data.  It is a byte-stream protocol used to support
  667.        the SOCK_STREAM abstraction.  TCP uses the standard Internet address
  668.        format and, in addition, provides a per-host collection of ``port
  669.        addresses''. Thus, each address is composed of an Internet address
  670.        specifying the host and network, with a specific TCP port on the
  671.        host identifying the peer entity.
  672.    
  673.        Sockets utilizing the tcp protocol are either ``active'' or
  674.        ``passive''.  Active sockets initiate connections to passive
  675.        sockets.  By default TCP sockets are created active; to create a
  676.        passive socket the listen() bsdsocket.library function call must be
  677.        used after binding the socket with the bind() bsdsocket.library
  678.        function call.  Only passive sockets may use the accept() call to
  679.        accept incoming connections.  Only active sockets may use the
  680.        connect() call to initiate connections.
  681.    
  682.        Passive sockets may ``underspecify'' their location to match
  683.        incoming connection requests from multiple networks.  This
  684.        technique, termed ``wildcard addressing'', allows a single server to
  685.        provide service to clients on multiple networks.  To create a socket
  686.        which listens on all networks, the Internet address INADDR_ANY must
  687.        be bound.  The TCP port may still be specified at this time; if the
  688.        port is not specified the bsdsocket.library function will assign
  689.        one.  Once a connection has been established the socket's address is
  690.        fixed by the peer entity's location.  The address assigned the
  691.        socket is the address associated with the network interface through
  692.        which packets are being transmitted and received.  Normally this
  693.        address corresponds to the peer entity's network.
  694.    
  695.        TCP supports one socket option which is set with setsockopt() and
  696.        tested with getsockopt().  Under most circumstances, TCP sends data
  697.        when it is presented; when outstanding data has not yet been
  698.        acknowledged, it gathers small amounts of output to be sent in a
  699.        single packet once an acknowledgement is received.  For a small
  700.        number of clients, such as X Window System functions that
  701.        send a stream of mouse events which receive no replies, this
  702.        packetization may cause significant delays.  Therefore, TCP provides
  703.        a boolean option, TCP_NODELAY (from <netinet/tcp.h>, to defeat this
  704.        algorithm.  The option level for the setsockopt call is the protocol
  705.        number for TCP, available from getprotobyname().
  706.    
  707.        Options at the IP transport level may be used with TCP; SEE ALSO ip.
  708.        Incoming connection requests that are source-routed are noted, and
  709.        the reverse source route is used in responding.
  710.    
  711.    DIAGNOSTICS
  712.        A socket operation may fail with one of the following errors
  713.        returned:
  714.    
  715.        [EISCONN]        when trying to establish a connection on a socket
  716.                         which already has one;
  717.    
  718.        [ENOBUFS]        when the AmiTCP/IP runs out of memory for an internal
  719.                         data structure;
  720.    
  721.        [ETIMEDOUT]      when a connection was dropped due to excessive
  722.                         retransmissions;
  723.    
  724.        [ECONNRESET]     when the remote peer forces the connection to be
  725.                         closed;
  726.    
  727.        [ECONNREFUSED]   when the remote peer actively refuses connection
  728.                         establishment (usually because no process is
  729.                         listening to the port);
  730.    
  731.        [EADDRINUSE]     when an attempt is made to create a socket with a
  732.                         port which has already been allocated;
  733.    
  734.        [EADDRNOTAVAIL]  when an attempt is made to create a socket with a
  735.                         network address for which no network interface
  736.                         exists.
  737.    
  738.    SEE ALSO 
  739.        bsdsocket.library/getsockopt(), bsdsocket.library/socket(),
  740.        bsdsocket.library/bind(), bsdsocket.library/listen(),
  741.        bsdsocket.library/accept(), bsdsocket.library/connect(), inet,
  742.        ip, <sys/socket.h>, <netinet/tcp.h>, <netinet/in.h>
  743.    
  744.    HISTORY
  745.        The tcp protocol stack appeared in 4.2BSD.
  746.  
  747. protocols/udp                                                    protocols/udp
  748.  
  749.    NAME
  750.        udp - Internet User Datagram Protocol
  751.    
  752.    SYNOPSIS
  753.        #include <sys/socket.h>
  754.        #include <netinet/in.h>
  755.    
  756.        int
  757.        socket(AF_INET, SOCK_DGRAM, 0)
  758.    
  759.    DESCRIPTION
  760.        UDP is a simple, unreliable datagram protocol which is used to
  761.        support the SOCK_DGRAM abstraction for the Internet protocol family.
  762.        UDP sockets are connectionless, and are normally used with the
  763.        sendto() and recvfrom() calls, though the connect() call may also be
  764.        used to fix the destination for future packets (in which case the
  765.        recv() and send() function calls may be used).
  766.    
  767.        UDP address formats are identical to those used by TCP. In
  768.        particular UDP provides a port identifier in addition to the normal
  769.        Internet address format.  Note that the UDP port space is separate
  770.        from the TCP port space (i.e. a UDP port may not be ``connected'' to
  771.        a TCP port). In addition broadcast packets may be sent (assuming the
  772.        underlying network supports this) by using a reserved ``broadcast
  773.        address''; this address is network interface dependent.
  774.    
  775.        Options at the IP transport level may be used with UDP; SEE ALSO ip.
  776.    
  777.    DIAGNOSTICS
  778.        A socket operation may fail with one of the following errors
  779.        returned:
  780.    
  781.        [EISCONN]        when trying to establish a connection on a socket
  782.                         which already has one, or when trying to send a
  783.                         datagram with the destination address specified and
  784.                         the socket is already connected;
  785.    
  786.        [ENOTCONN]       when trying to send a datagram, but no destination
  787.                         address is specified, and the socket hasn't been
  788.                         connected;
  789.    
  790.        [ENOBUFS]        when the system runs out of memory for an
  791.                         internal data structure;
  792.    
  793.        [EADDRINUSE]     when an attempt is made to create a socket with a
  794.                         port which has already been allocated;
  795.    
  796.        [EADDRNOTAVAIL]  when an attempt is made to create a socket with a
  797.                         network address for which no network interface
  798.                         exists.
  799.    
  800.    SEE ALSO
  801.        bsdsocket.library/getsockopt(), bsdsocket.library/recv(),
  802.        bsdsocket.library/send(), bsdsocket.library/socket(), inet, ip
  803.    
  804.    HISTORY
  805.        The udp protocol appeared in 4.2BSD.
  806.  
  807.