ethernet(7) ethernet(7)
NAME
Ethernet - raw Ethernet I/O operations
SYNOPSIS
#include <net/rif.h>
DESCRIPTION
Ethernet I/O transactions are typically made by the standard
networking software using TCP/IP and related protocols. The
interface described below allows programmers to directly
access the Ethernet device driver, submitting packets to or
receiving packets from the interface without processing by
any of the protocol routines.
Raw Ethernet I/O is available on any of the standard Night
Hawk Series Ethernet hardware interfaces. Communications
can be done on the same interfaces that are used for Inter-
net transactions and at the same time if there is no con-
flict as to where the received data is to be sent. Access
to the raw Ethernet interfaces is restricted to processes
having an effective user-id of zero (root).
The raw Ethernet interface supports standard Ethernet mes-
sage formats, IEEE 802.3 message formats, and IEEE 802.2
Logical Link Control formats. The mode used is selected by
the type of open(2) call and through use of ioctl(2) parame-
ters.
DEVICE NAMES
The physical interface to which the process wishes to con-
nect must be specified on the open(2) call. Each interface
has two entry points; one for standard raw Ethernet and the
other for IEEE 802.2 Logical Link Control formatting. Dev-
ice names are of the form /dev/xxn and /dev/xxnllc. The xx
value is the interface name; it corresponds to the interface
name which is displayed when the system is initializing.
Standard names are as follows:
ex Excelan
ie ISE daughter card
eg Eagle
The n value is the interface number, 0 for the first, 1 for
the second, etc. The 'llc' version of the name is used when
IEEE 802.2 LLC formatting is desired.
CONFIGURATION
Special device files needed to utilize raw Ethernet I/O by
device name are installed on the system by running the MAK-
EDEV script in the
/dev
directory for the appropriate interface, as shown below.
Page 1 CX/UX Administrator's Reference
ethernet(7) ethernet(7)
cd /dev
MAKEDEV ex0 ex1 eg0 eg1 ... ie0
I/O COMMANDS
Standard I/O commands are used with raw Ethernet I/O as
listed below.
open
The interface name described above is used on the open call.
The flags value can be set to O_NDELAY or O_NONBLOCK to
indicate that non-blocking I/O is to be done. The open will
fail if the specified interface does not exist [ENOENT or
ENXIO] or was not found during system initialization. The
same or multiple processes may have the same raw Ethernet
device open simultaneously. Each open file descriptor will
have its own set of raw options (set by ioctl commands) and
can be sending and receiving at the same time.
close
The file descriptor is closed. Any messages not yet read
are discarded. If this is the last process using the
hardware interface, a command is issued to cause it to stop
reception.
read
Each read command will return at most one Ethernet message.
When the call is issued and there is a message available,
the message is returned immediately. The data begins with
the 14-byte Ethernet header including source and destination
station addresses. If a message is longer than the speci-
fied read count, the excess is discarded. The number of
bytes copied into the user buffer is returned on the call.
If no data is available when the call is made, the process
is suspended unless the device has been opened in non-
blocking mode. Non-blocking mode reads may return [EWOULD-
BLOCK], [EAGAIN], or 0 depending upon the way in which non-
blocking was specified.
write
The buffer passed by the user must contain the 14-byte Eth-
ernet header with valid destination and source addresses.
The user must ensure that the buffer length does not exceed
the maximum transmission unit size for the interface;
failure to do so may return the [EMSGSIZE] error code. If
there are too many untransmitted requests queued at the phy-
sical interface driver, the calling process may receive an
[ENOBUFS] error. In this case, the request should be resub-
mitted after a short delay.
Page 2 CX/UX Administrator's Reference
ethernet(7) ethernet(7)
select
The select() call can be used to check for the presence of a
message to be read by specifying the appropriate values for
the readfds. The writefds value can be used to ensure that
the system is not out of internal mbuf structures. readfds
and writefds are parameters to the select() call containing
file descriptors and are explained in that manual-page.
ioctl
The following ioctl commands are applicable to the raw Eth-
ernet interface:
FIOASYNC Set or clear asynchronous I/O functionality on
the file descriptor. If the field pointed to
by arg is zero, synchronous mode is used. This
is also the default mode. In this mode the
process will not receive any special notifica-
tion when there is data available to read.
If the field referred to by arg is nonzero, the
asynchronous I/O mode is set. In this mode the
process or process group will receive notifica-
tion by means of a SIGIO signal when there is
data available to read. When a process is
blocked on a select(2), SIGIO will also result
when sufficient mbufs are available to change
from the unwritable state to being writable.
FIONBIO Set or clear non-blocking I/O functionality on
the file descriptor. If the field pointed to
by arg is set to zero, the file descriptor is
set to blocking I/O mode. This is the default
unless the open() call specified non-blocking.
If the field referred to by arg contains a
nonzero value, the socket non-blocking mode
will be set. Read or write calls which cannot
complete immediately will return a -1 with
errno set to [EAGAIN].
FIONREAD Return the number of bytes of data available to
be read on the file descriptor. The result is
returned in the field referred to by arg.
The next few ioctl commands use an ifreq structure to pass
or return information regarding network addresses. The
ifreq structure is defined in <net/if.h> as follows:
Page 3 CX/UX Administrator's Reference
ethernet(7) ethernet(7)
struct ifreq {
char ifrname[16]; /* name of interface (e.g. ex0) */
union {
struct sockaddr ifruaddr;
struct sockaddr ifrudstaddr;
struct sockaddr ifrubroadaddr;
short ifruflags;
int ifrumetric;
caddrt ifrudata;
} ifrifru;
}
#define ifraddr ifrifru.ifruaddr /* address */
#define ifrbroadaddr ifrifru.ifrubroadaddr /* address */
The ifr_name field contains the interface name. The size
of this field is the maximum size of an interface name,
and it consists of a null-terminated ASCII string. The
null byte is counted as part of the size of the name. The
ifr_flags field provides information on the state of a
network interface by inclusive ORing of zero or more of
the following flags located in <net/if.h>:
IFF_UP 0x1 /* Check a single bit to know if interface is up */
IFF_BROADCAST 0x2 /* Broadcast address valid */
IFF_FDDI 0x4 /* Indicates an FDDI network interface */
IFF_LOOPBACK 0x8 /* Interface associated with loop-back network */
IFF_POINTTOPOINT 0x10 /* Interface is point-to-point link */
IFF_NOTRAILERS 0x20 /* Avoid use of trailers */
IFF_RUNNING 0x40 /* Interface associated with functional network device */
IFF_NOARP 0x80 /* No address resolution protocol */
IFF_PROMISC 0x100 /* Reserved: Receive all packets */
IFF_ALLMULTI 0x200 /* Reserved: Receive all multicast packets */
IFF_IP8022 0x800 /* Internet Packets use 802.2 LLC formatting */
The following ioctl commands use an arg which is a pointer
to an ifreq structure:
SIOCGIFFLAGS Get the interface flags associated with a
particular network interface. The ifr_name
field of the ifreq structure referenced by
arg should be set to the desired interface
name. Upon successful completion, the system
will return the flags for the interface in
the ifr_ifru.ifru_flags field.
SIOCSIFFLAGS Set the interface flags associated with a
particular network interface. The ifr_name
field of the ifreq structure referenced by
arg should be initialized by the calling pro-
gram for the desired interface as well as the
flags to be set in the ifr_ifru.ifru_flags
field. Upon successful completion, the
Page 4 CX/UX Administrator's Reference
ethernet(7) ethernet(7)
system will set the flags for the interface.
If the interface was previously up (IFF_UP
set) and is requested to be marked down
(IFF_UP not set) then the hardware interface
is disabled so long as there are no processes
currently having an open raw Ethernet connec-
tion to the device.
SIOCGETETADDR Get the hardware interface receive address.
The ifr_name field is not required. The 6-
byte Ethernet hardware receive address
currently in use by the interface attached to
the specified file descriptor is returned in
the ifr_ifru.ifru_addr.sa_data field.
SIOCGETFEADDR Get the hardware interface factory address.
The ifr_name field is not required. The 6-
byte Ethernet factory-set hardware receive
address for the interface attached to the
specified file descriptor is returned in the
ifr_ifru.ifru_addr.sa_data field.
SIOCSETETADDR Set the hardware interface receive address.
The ifr_name field is not required. The 6-
byte Ethernet hardware receive address for
the interface attached to the specified file
descriptor is set to the first six bytes in
the ifr_ifru.ifru_addr.sa_data field.
The remaining ioctl commands use individual data structures
unique to the command as listed below:
REIOSETMCAST Set multicast address. The arg value points
to a 6-byte array containing a valid multi-
cast address to be set into the hardware
interface. If the specified address is
already set as a multicast address, the [EAD-
DRINUSE] error will be returned. If the
interface's multicast address table is full,
[ENOMEM] is returned.
REIOCLRMCAST Clear multicast address. The arg value
points to a 6-byte array containing a previ-
ously set multicast address. The entry is
cleared from the table and removed from the
hardware interface. If the specified value
is not a currently active multicast address,
no error is returned. If all six bytes are
set to 0xff, then the entire multicast
address table for the interface is cleared.
REIOGETMCAST Get multicast address table. The arg value
Page 5 CX/UX Administrator's Reference
ethernet(7) ethernet(7)
points to a reiomcast structure defined in
<net/if.h> as follows:
struct reiomcast {
int size;
unsigned char data[96];
}
Upon return, each currently enabled multicast
address will be placed in consecutive 6-byte
positions in data, and size will be set to
the number of valid bytes returned in the
array.
REIOSETTYPE Enable reception of raw Ethernet messages and
specify which are to be received. This com-
mand is used to select which of the messages
being received on the interface opened by the
file descriptor are to be passed back to the
calling program. Until it is issued, no data
is received. arg points to a reioopt struc-
ture defined in <net/rif.h> as follows:
struct reioopt {
int opt; /* options word */
int lowtype; /* lower bound of types */
int hitype; /* upper bound of types */
}
#define REIO8023 0x01 /* accept all 802.3 packets */
#define REIOCLR 0x02 /* clear types table */
#define REIOPROMIS 0x04 /* place interface in promiscuous mode */
The types used with this command are the 2-
byte Ethernet message types which immediately
follow the 6-byte source station address in
the Ethernet header, or they are the Ethernet
type fields in the SNAP header when using
IEEE 802.2 Logical Link Control formatted
messages.
For each call containing valid type(s), those
type(s) are appended to the list of message
types being received by the particular file
descriptor. However, if REIO_CLR is set, the
existing table is first cleared before set-
ting the types specified in the current com-
mand. If low_type is set to -1, then all
message types are to be received by the
current interface. A single type is speci-
fied by having that type set in low_type with
hi_type set to zero. A range of types is
specified with the lower bound in low_type
and the upper value in hi_type. The [EBUSY]
error is returned if an attempt is made to
receive a type already being received by
Page 6 CX/UX Administrator's Reference
ethernet(7) ethernet(7)
another file descriptor. This error is also
returned when an attempt is made to receive
all messages and the Internet protocol is
currently active.
The REIO_8023 bit in the options word can be
set to request that all IEEE 802.3 formatted
messages be received on the current file
descriptor. This condition is cleared when a
command is issued without this bit set.
The REIO_PROMIS bit in the options word can
be set to have the hardware interface placed
in promiscuous mode; that is, it will
receive all traffic on the Ethernet wire
regardless of the destination address of the
message. This condition is cleared by issu-
ing this same ioctl command without the
REIO_PROMIS bit.
RLIOSETADDR Enable reception of raw IEEE 802.2 LLC for-
matted Ethernet messages and specify which
are to be received. This command is used to
select which of the messages being received
on the interface opened by the file descrip-
tor are to be passed back to the calling pro-
gram. Until it is issued, no data is
received. The file descriptor must have been
opened on the llc version of the interface.
arg points to a rlioopt structure defined in
<net/rif.h> as follows:
struct rlioopt {
int opt; /* options word */
unsigned char filler[3];
unsigned char addr; /* 802.2 LLC address */
}
#define RLIOCLR 0x02 /* clear address table */
#define RLIONOINET 0x08 /* don't inc IP msgs */
The addresses used with this command are the
IEEE 802.2 LLC DSAPs (Destination Service
Access Points) which are contained in the
802.2 LLC header following the Ethernet
header.
For each call containing valid addr(s), those
addr(s) are appended to the list of DSAP
addresses being received by the particular
file descriptor. However, if RLIO_CLR is set,
the existing table is first cleared before
setting the addresses specified in the
current command. If addr is set to 255, then
Page 7 CX/UX Administrator's Reference
ethernet(7) ethernet(7)
all DSAP addresses are to be received by the
current interface. A single DSAP address is
specified by having that address set in addr.
The [EBUSY] error is returned if an attempt
is made to receive an address already being
received by another file descriptor. This
error is also returned when an attempt is
made to receive all addresses and the Inter-
net protocol is currently active.
The RLIO_NO_INET bit in the options word can
be set to exclude address 170 on a call which
is requested all DSAP addresses. 170 is used
for the SNAP protocol, a sub-protocol used
when Internet utilizes IEEE 802.2. This con-
dition is cleared when a command is issued
without this bit set.
FILES
/dev/ex0, /dev/ex0llc
/dev/ie0, /dev/ie0llc
/dev/eg0, /dev/eg0llc
SEE ALSO
close(2), fcntl(2), ioctl(2), open(2), read(2), select(2),
write(2) in the CX/UX Programmer's Reference Manual.
CX/UX Programmer's Guide.
Page 8 CX/UX Administrator's Reference