Intro(ADMP)

Intro -- introduction to special files and protocols

Syntax

#include  <sys/socket.h>

#include  <netinet/in.h>

#include  <net/if.h>

#include  <netinet/ip_str.h>

#include  <net/strioc.h>

Description

This section describes various special files and protocols that refer to specific STREAMS TCP/IP networking protocol drivers. Features common to a set of protocols are documented as a protocol family.

Protocol family entries

A protocol family provides basic services to the protocol implementation to allow it to function within a specific network environment. These services may include packet fragmentation and reassembly, routing, addressing, and basic transport. A protocol family may support multiple methods of addressing, though the current protocol implementations do not. A protocol family is normally comprised of a number of protocols, one per socket(SSC) type. It is not required that a protocol family support all socket types. A protocol family may contain multiple protocols supporting the same socket abstraction.

A protocol supports one of the socket abstractions detailed in socket(SSC). A specific protocol may be accessed by creating a socket of the appropriate type and protocol family, by requesting the protocol explicitly when creating a socket, by executing the appropriate TLI/XTI primitives, or by opening the associated STREAMS device.

Protocol entries

The system currently supports the Internet protocols. Raw socket interfaces are provided to the IP protocol layer of the Internet, to the ICMP protocol, and to the IGMP protocol. Consult ip(ADMP), icmp(ADMP), and igmp(ADMP) for more information.

Addressing

Associated with each protocol family is an address format. All network addresses adhere to a general structure, called a sockaddr, shown here:

       struct sockaddr {
           u_short sa_family;
           char    sa_data[14];
       };

However, each protocol imposes finer and more specific structure, generally renaming the variant. See the appropriate protocol manual page for more details.

The following address values for sa_family are known to the system:

   #define    AF_INET      2    /* internetwork: UDP, TCP, etc. */
   #define    AF_LINK     18    /* data-link layer (ARP) */
   #define    AF_UNIX      1    /* UNIX domain */

Routing

The system provides some packet routing facilities. The kernel maintains a routing information database, which is used in selecting the appropriate network interface when transmitting packets.

A user process (or possibly multiple co-operating processes) maintains this database by sending messages over a special kind of stream. This supplants fixed size ioctl(S) used in earlier releases.

This facility is described in route(ADMP).

Socket ioctls

The ioctl call on a socket has the general form:

   ioctl(file_descriptor,code,arg)

The following ioctl command codes have significance for the socket layer only:

SIOCPROTO

Enter a socket type into the kernel protocol switch table. The arguments used to create the socket used by this ioctl may be zero. The new socket type is downloaded by setting arg to a pointer to a specification block with the following structure:

struct socknewproto {
        int        family; /* address family (AF_INET, etc.) */
        int        type;   /* protocol type (SOCK_STREAM, etc.) */
        int        proto;  /* per family proto number */
        dev_t      dev;    /* major/minor to use (must be a clone) */
        int        flags;  /* protosw flags */
};

The flags currently supported are specified in the <sys/protosw.h> header file as:

#define PR_ATOMIC       0x01    /* exchange atomic messages only */
#define PR_ADDR         0x02    /* addresses given with messages */
#define PR_CONNREQUIRED 0x04    /* connection required by protocol */
#define PR_RIGHTS       0x10    /* passes capabilities */
#define PR_BINDPROTO    0x20    /* pass protocol */

SIOCXPROTO

Purge the protocol switch table. The arguments used to create the socket used by this ioctl may be zero.

SIOCSPGRP

Set the process group for a socket to enable signaling (SIGUSR1) of that process group when out-of-band data arrives. The argument, arg, is a pointer to an int and, if positive, is treated as a process ID; otherwise, (if negative) is treated as a process group ID.

SIOCGPGRP

Get the process group ID associated with a particular socket. If the value returned to the int location pointed to by arg is negative, it should be interpreted as a process group ID; otherwise, it should be interpreted as a process ID.

SIOCCATMARK

Used to ascertain whether or not the socket read pointer is currently at the point (mark) in the data stream where out-of-band data was sent. If a 1 is returned to the int location pointed to by arg, the next read will return data after the mark. Otherwise (assuming out-of-band data has arrived), the next read will provide data sent by the client prior to transmission of the out-of-band signal.

FIONREAD

Returns (to the int location pointed to by arg) the number of bytes currently waiting to be read on the socket.

FIONBIO

Toggles the socket into blocking/non-blocking mode. If the int location pointed to by arg contains a non-zero value, subsequent socket operations that would cause the process to block waiting on a specific event will return abnormally with errno set to EWOULDBLOCK; otherwise, the process will block.

Queue ioctls

Each STREAMS device has default queue high and low water marks, that can be changed by the super user with the INITQPARMS specification in an ioctl(S). The ioctl is done on a driver or module, with the argument being an array of structures of type:

   struct iocqp {
           ushort iqp_type;
           ushort iqp_value;
   };

iqp_value specifies the value for the queue parameter according to iqp_type, which may be one of: IQP_RQ (read queue), IQP_WQ (write queue), IQP_MUXRQ (mux read queue), IQP_MUXWQ (mux write queue), or IQP_HDRQ (stream head queue), each OR'ed with either IQP_LOWAT (value is for low water mark of queue), or IQP_HIWAT (value is for high water mark of queue).

Interface ioctls

Each network interface in a system corresponds to a path through which messages may be sent and received. A network interface usually has a hardware device associated with it, although certain interfaces such as the loopback interface, llcloop(ADMP), do not.

The following ioctl calls may be used to manipulate network interfaces. The ioctl is made on a socket (typically of type SOCK_DGRAM) in the desired ``communications domain'' (see protocols(SFF)). Unless specified otherwise, the request takes an ifreq structure as its parameter. This structure has the form

struct  ifreq {
#define IFNAMSIZ	16
        char    ifr_name[IFNAMSIZ];   /* name of interface (e.g. ec0) */
        union {
                struct  sockaddr ifru_addr;
                struct  sockaddr ifru_dstaddr;
                struct  sockaddr ifru_broadaddr;
                short   ifru_flags;
                int     ifru_metric;
                caddr_t ifru_data;
                char    ifru_enaddr[6];
                struct  onepacket ifru_onepacket;
                struct  ifperf ifru_perf;
        } ifr_ifru;
#define ifr_addr		ifr_ifru.ifru_addr		/* address */
#define ifr_dstaddr   	ifr_ifru.ifru_dstaddr	/* other end of p-to-p link */
#define ifr_broadaddr 	ifr_ifru.ifru_broadaddr	/* broadcast address */
#define ifr_flags		ifr_ifru.ifru_flags	/* flags */
#define ifr_metric		ifr_ifru.ifru_metric	/* routing metric */
#define ifr_data		ifr_ifru_ifru_data		/* for use by interface */
#define ifr_enaddr		ifr_ifru_ifru_enaddr	/* ethernet address */
#define ifr_onepacket 	ifr_ifru.ifru_onepacket	/* one-packet mode params */
#define ifr_perf      	ifr_ifru.ifru_onepacket	/* performance tuning */
};

SIOCSIFADDR

Set interface address for protocol family. Following the address assignment, the ``initialization'' routine for the interface is called.

SIOCSIFDSTADDR

Set point to point address for protocol family and interface.

SIOCSIFBRDADDR

Set broadcast address for protocol family and interface.

SIOCGIFADDR

Get interface address for protocol family.

SIOCGIFBRDADDR

Get broadcast address for protocol family and interface.

SIOCGIFDSTADDR

Get point to point address for protocol family and interface.

SIOCSIFFLAGS

Set interface flags field. If the interface is marked down, any processes currently routing packets through the interface are notified; some interfaces may be reset so that incoming packets are no longer received. When marked up again, the interface is reinitialized.

SIOCGIFFLAGS

Get interface flags.

SIOCSIFMETRIC

Set interface routing metric. The metric is used only by user-level routers.

SIOCGIFMETRIC

Get interface metric.

SIOCSIFMTU

Sets the maximum-transmission-unit size of the interface. This value indicates the largest atomic data-unit (including all protocol headers) that can be transmitted via this interface. The ifr_metric field is used to contain the MTU value.

SIOCGIFMTU

Retrieves the maximum-transmission-unit size associated with the interface. The MTU value is returned in the ifr_metric field.

SIOCGIFDEBUG

Retrieves the current debugging level associated with the interface. The level is returned in the ifr_metric field.

SIOCSIFDEBUG

Sets the debugging level of the interface. The ifr_metric field is used to contain the MTU value.

SIOCSIFTYPE

Sets the interface type to the value specified in the ifr_metric field. Valid interface types are specified in <sys/net/if_types.h>. This is performed by the system when appropriate and should never normally be issued by an application.

SIOCGIFTYPE

Retrieves the interface type of the specified interface. The value is returned in the ifr_metric field.

SIOCSIFONEP

Set one-packet mode parameters. The ifr_onepacket field of the ifreq structure is used for this request. This structure is defined as follows:

struct onepacket {
        int     spsize;         /* small packet size */
        int     spthresh;       /* small packet threshold */
};

One-packet mode is enabled by setting the IFF_ONEPACKET flag (see SIOCSIFFLAGS above). See tcp(ADMP) for an explanation of one-packet mode.

SIOCGIFONEP

Get one-packet mode parameters.

SIOCSIFPERF

Set performance tuning parameters. The ifr_perf field of the ifreq structure is used for this request. This structure is defined as follows:

struct ifperf {
        u_short     ip_recvspace;      /* recv buffering */
        u_short     ip_sendspace;      /* send buffering */
        u_short     ip_fullsize;       /* use full-size segments */
};

These values control interface-specific information that TCP will use to determine optimal window and segment sizes. They can be configured on a per-interface basis so that systems with multiple different types of interfaces do not have to be configured in such a way as to penalize faster hardware.

SIOCGIFPERF

Get performance tuning parameters.

SIOCAIFADDR

An interface may have more than one address associated with it in the internet protocol. This request provides a means to add additional addresses (or modify characteristics of the primary address if the default address for the address family is specified). Rather than making separate calls to set destination or broadcast addresses, or network masks (now an integral feature of the protocol), a separate structure is used to specify all three facets simultaneously (see below). One would use a slightly tailored version of this struct specific to each family (replacing each sockaddr by one of the family-specific types, for example, sockaddr_in).

SIOCDIFADDR

This request deletes the specified address from the list associated with an interface. It also uses the if_aliasreq structure to allow for the possibility of protocols allowing multiple masks or destination addresses, and also adopts the convention that specification of the default address means to delete the first address for the interface belonging to the address family in which the original socket was opened.

The following structure is used with SIOCAIFADDR, SIOCGIFALIAS, and SIOCDIFADDR:

/*
 * Structure used in SIOCAIFADDR/SIOCGIFALIAS/SIOCDIFADDR requests.
 */
struct ifaliasreq {
        char    ifra_name[IFNAMSIZ];   /* if name, e.g. "en0" */
        struct  sockaddr        ifra_addr;
        struct  sockaddr        ifra_broadaddr;
        struct  sockaddr        ifra_mask;
};

SIOCGIFALIAS

Get interface alias. This request takes an ifaliasreq structure as an argument. The alias about which information is desired is identified by the combination of the ifra_name and ifra_addr fields. For example, to retrieve information about the alias ``127.0.0.2'' on interface ``lo0'', ifra_name should contain the string ``lo0'' and ifra_addr should be initialized to a sockaddr_in structure whose sin_addr field contains 0x7f000002 in network-byte order. The remaining fields will be returned by the kernel.

SIOCGIFNUM

This requests an integer argument as a result-only parameter. The current number of interfaces is returned.

SIOCGIFANUM

This requests an integer argument as a result-only parameter. The current number of non-multicast interface addresses is returned. This may be greater than the number returned by SIOCGIFNUM if interfaces with aliases (multiple logical addresses) exist. This is useful for sizing buffers to be used with the SIOCGIFCONF ioctl, since that ioctl will return a struct ifreq for every interface address.

SIOCGIFCONF

Get interface configuration list. This request takes an ifconf structure (see below) as a value-result parameter. The ifc_len field should be initially set to the size of the buffer pointed to by ifc_buf. If the SIOCGIFANUM ioctl is used to size the buffer, the size should be equal to the number returned via the SIOCGIFANUM ioctl multiplied by the size of an ifreq structure. On return it will contain the length, in bytes, of the configuration list.

/* Structure used in SIOCGIFCONF request.
 * Used to retrieve interface configuration
 * for machine (useful for programs which
 * must know all networks accessible).
 */
struct  ifconf {
        int     ifc_len;             /* size of associated buffer */
        union {
                caddr_t ifcu_buf;
                struct  ifreq *ifcu_req;
        } ifc_ifcu;
#define ifc_buf ifc_ifcu.ifcu_buf    /* buffer address */
#define ifc_req ifc_ifcu.ifcu_req    /* array of structures returned */
};

Streams ioctl interface

Socket ioctl calls can also be issued using STREAMS file descriptors. The standard strioctl structure is used, with the ic_cmd field containing the socket ioctl command code (from <sys/socket.h>) and the ic_dp field pointing to the data structure appropriate for that ioctl, for all socket ioctls except SIOCGIFCONF. For the SIOCGIFCONF ioctl, an ifconf structure is not used. Rather, the ic_dp field points to the buffer to receive the ifreq structures. For the SIOCGIFNUM and SIOCGIFANUM ioctls, ic_dp should point to an integer.

In all cases, the ic_len field should be set to the appropriate size.

TLI/XTI options management

Options may be set and retrieved in a manner similar to getsockopt(SSC) and setsockopt(SSC) using t_optmgmt(NET). Options are communicated using an options buffer, which contains a list of options. Each option consists of an option header and an option value. The opthdr structure gives the format of the option header:

   struct opthdr {
           long level;     /* protocol level affected */
           long name;      /* option to modify */
           long len;       /* length of option value (in bytes) */
   };

The option value must be a multiple of sizeof (long) bytes in length, and must immediately follow the option header. Following the option value is the header of the next option, if present.

To get the values of options, set the flags field of the t_optmgmt structure to T_CHECK. It is not necessary to set the len fields in the option headers to the expected lengths of the option values, nor is it necessary to provide space between option headers for the option values to be stored (the len fields should be set to zero and the option headers should be adjacent). A new options buffer will be formatted and returned to the user. Note that T_CHECK may have failed even if t_optmgmt returns zero. The user must check the flags field of the returned t_optmgmt structure. If this field contains T_FAILURE, one or more of the options were invalid.

To set options, set the flags field of the t_optmgmt structure to T_NEGOTIATE.

To retrieve the default values of all options, set the flags field of the t_optmgmt structure to T_DEFAULT. For this operation, no input buffer should be specified.

Obtaining RFCs

SCO TCP/IP man pages frequently cite appropriate RFCs (Requests for Comments). RFCs can be obtained from InterNIC Information Services in the following ways:

Paper copies of all RFCs are available. For more information contact info@is.internic.net or call 1-800-444-4345.
Online copies are available via FTP from ftp.ds.internic.net as rfc/rfcN.txt or rfc/rfcN.ps (N is the number of the RFC).
RFCs may be requested through electronic mail from the InterNIC's automated mail server by sending a message to mailserv@ds.internic.net . In the body of the message, indicate the RFC to be sent, for example, ``document-by-name rfcN'' (N is the number of the RFC). For PostScript RFCs, specify the extension; for example, ``document-by-name rfcN.ps''. Multiple requests can be sent in a single message by specifying each request on a separate line. The RFC Index can be requested by typing document-by-name rfc-index.