./_Man_SunOS_4.1.3_html/html4/nit

Manual page for NIT_IF(4M)

nit_if - STREAMS NIT device interface module

CONFIG

pseudo-device snit

SYNOPSIS

#include <sys/file.h>
open("/dev/nit", mode);

DESCRIPTION

nit_if is a STREAMS pseudo-device driver that provides STREAMS access to network interfaces. It is designed to be used in conjunction with the other components of NIT (see nit.4p but can be used by itself as a raw STREAMS network interface.

nit_if is an exclusive-open device that is intended to be opened indirectly through the clone device; /dev/nit is a suitable instance of the clone device. Before the stream resulting from opening an instance of nit_if may be used to read or write packets, it must first be bound to a specific network interface, using the NIOCSBIND ioctl described below.

Read-side Behavior

nit_if copies leading prefixes of selected packets from its associated network interface and passes them up the stream. If the NI_PROMISC flag is set, it passes along all packets; otherwise it passes along only packets addressed to the underlying interface.

The amount of data copied from a given packet depends on the current snapshot length, which is set with the NIOCSSNAP ioctl described below.

Before passing each packet prefix upward, nit_if optionally prepends one or more headers, as controlled by the state of the flag bits set with the NIOCSFLAGS ioctl. The driver collects headers into M_PROTO message blocks, with the headers guaranteed to be completely contained in a single message block, whereas the packet itself goes into one or more M_DATA message blocks.

Write-side Behavior

nit_if accepts packets from the module above it in the stream and relays them to the associated network interface for transmission. Packets must be formatted with the destination address in a leading M_PROTO message block, followed by the packet itself, complete with link-level header, in a sequence of M_DATA message blocks. The destination address must be expressed as a `struct sockaddr' whose sa_family field is AF_UNSPEC and whose sa_data field is a copy of the link-level header. (See sys/socket.h for the definition of this structure.) If the packet does not conform to this format, an M_ERROR message with EINVAL will be sent upstream.

nit_if processes M_IOCTL messages as described below. Upon receiving an M_FLUSH message specifying that the write queue be flushed, nit_if does so and transfers the message to the read side of the stream. It discards all other messages.

IOCTLS

nit_if responds to the following ioctls, as defined in net/nit_if.h. It generates an M_IOCNAK message for all others, returning this message to the invoker along the read side of the stream.

SIOCGIFADDR
SIOCADDMULTI
SIOCDELMULTI: nit_if passes these ioctls on to the underlying interface's driver and returns its response in a `struct ifreq' instance, as defined in net/if.h. (See the description of this ioctl in if.4n for more details.)
NIOCBIND: This ioctl attaches the stream represented by its first argument to the network interface designated by its third argument, which should be a pointer to an ifreq structure whose ifr_name field names the desired interface. See net/if.h for the definition of this structure.
NIOCSSNAP: Set the current snapshot length to the value given in the u_long pointed to by the ioctl's final argument. nit_if interprets a snapshot length value of zero as meaning infinity, so that it will copy all selected packets in their entirety. It constrains positive snapshot lengths to be at least the length of an Ethernet header, so that it will pass at least the link-level header of all selected packets to its upstream neighbor.
NIOCGSNAP: Returns the current snapshot length for this device instance in the u_long pointed to by the ioctl's final argument.
NIOCSFLAGS: nit_if recognizes the following flag bits, which must be given in the u_long pointed to by the ioctl's final argument. This set may be augmented in future releases. All but the NI_PROMISC bit control the addition of headers that precede the packet body. These headers appear in the order given below, with the last-mentioned enabled header adjacent to the packet body.

NI_PROMISC: Requests that the underlying interface be set into promiscuous mode and that all packets that the interface receives be passed up through the stream. nit_if only honors this bit for the super-user.
NI_TIMESTAMP: Prepend to each selected packet a header containing the packet arrival time expressed as a `struct timeval'.
NI_DROPS: Prepend to each selected packet a header containing the cumulative number of packets that this instance of nit_if has dropped because of flow control requirements or resource exhaustion. The header value is expressed as a u_long. Note: it accounts only for events occurring within nit_if, and does not count packets dropped at the network interface level or by upstream modules.
NI_LEN: Prepend to each selected packet a header containing the packet's original length (including link-level header), as it was before being trimmed to the snapshot length. The header value is expressed as a u_long.

NIOCGFLAGS: Returns the current state of the flag bits for this device instance in the u_long pointed to by the ioctl's final argument.

FILES

/dev/nit: clone device instance referring to nit_if device
net/nit_if.h: header file containing definitions for the ioctls and packet headers described above.