LAN(4) LAN(4)
NAME
lan - network I/O card access information
SYNOPSIS
#include <netio.h>
int ioctl ( fildes,request,arg );
int request;
int arg;
struct fis *arg;
HP-UX COMPATIBILITY
Level: HP-UX/OPTIONAL
Origin: HP
DESCRIPTION
For the remainder of this document, IEEE802 refers to the
IEEE802.2/IEEE802.3 specification.
The networking terminology used in the remainder of the
discussion is defined as follows:
Packet refers to user data with specific
Ethernet*/IEEE802 header information attached. The
header contains the target node's network station
address (destination address), the transmitting node's
network station address (source address), the user's
logged-in addresses (see LOG_TYPE_FIELD and LOG_SSAP
below) and specifically for IEEE802, length, dsap and
control fields (explained later).
Network station address or address, for the
Ethernet*/IEEE802 device is a 6-byte binary value read
from/written into arg.value.s for ioctl commands. For
example, the ASCII form "0x00DD00020A50" has the 6-byte
binary representation "\000\335\000\002\012\120." See
net_aton(3N) for utilities to convert between the ASCII
and binary forms of a network station address.
Multicast refers to destination addresses normally used
to send data to more than one node on a network. See
ADD_MULTICAST below. A multicast address is signified
by setting the least significant bit of the first (high
order) byte of the address (e.g. "0x00DD0002AD00" is
unique, "0x01DD0002AD00" is multicast).
A broadcast address is a reserved (all bits on)
multicast address normally used to send data to ALL
nodes on a network.
Ethernet*/IEEE802 device files indicate the drivers for the
Hewlett-Packard - 1 - (printed 7/16/86)
LAN(4) LAN(4)
Ethernet*/IEEE802 cards. There should be one device file
for each Ethernet*/IEEE802 card connected to a system. For
those network I/O cards which support both Ethernet* and
IEEE802 simultaneously, there should be two device files,
one for each protocol.
To create an Ethernet*/IEEE802 device file, the super-user
must use the mknod command:
mknod devicefilename c major minor
The major number indicates the protocol driver to be used.
The possible values are:
Protocol Computer Interface Major Number
Ethernet* Series 500 2285A LAN Unit 34
IEEE802 Series 500 2285A LAN Unit 40
Ethernet* Series 500 27125A LAN Card 38
IEEE802 Series 500 27125A LAN Card 39
Ethernet* Series 200 or 300 98643A LAN Card 19
IEEE802 Series 200 or 300 98643A LAN Card 18
The minor number indicates the select code of the interface
card. This is encoded in the format:
0xss0000 where ss is the select code of the Interface card
(or of the HP-IB card for 2285A Interface Units).
After creating the device file, the super-user is encouraged
to limit read/write access to the driver, because
uncontrolled access could lead to throughput degradation and
even more serious problems. The suggested access is owner-
only read/write (chmod 600 devicefilename).
A user with the proper access rights can open, close and
read status information from an Ethernet*/IEEE802 device
connected to an active network environment. After executing
required NETCTRL setup operations (explained below), the
user can read from and write to the device. The super-user
can send additional NETCTRL control information to the
device.
The maximum number of bytes that can be transferred per read
or write call is 1500 for Ethernet* and 1497 for IEEE802.
Requests to write more than the maximum number of bytes will
fail. Due to hardware limitations, the minimum packet size
is 46 data bytes for Ethernet* and 43 data bytes for IEEE802
(i.e. 64 bytes total for both header and data). Any write
requests of less than the minimum number of bytes will be
padded with undefined characters. A read issued to an
Hewlett-Packard - 2 - (printed 7/16/86)
LAN(4) LAN(4)
IEEE802 device file automatically strips these undefined
characters. A read issued to an Ethernet device file does
not. If a received packet is too large for a buffer on a
posted read, the packet is truncated to fit.
The behavior of Ethernet*/IEEE802 device file descriptors
across fork/exec calls is similar to the behavior of other
file descriptors across these calls.
The user is cautioned that multiple processes sharing a file
descriptor can interfere with each other, especially with
respect to the commands LOG_READ_TIMEOUT, LOG_READ_CACHE and
LOG_DEST_ADDR, which are described below.
The user is cautioned that the network driver does not
guarantee data delivery; on a successful write, the only
guarantee is that the data have been queued for transmission
by the network I/O card. Likewise, there is no guarantee
that once transmitted, data are received by the target node.
The desired degree of reliability must be coded into the
user program.
For an Ethernet*/IEEE802 device, ioctl uses these
parameters:
fildes File descriptor of the Ethernet*/IEEE802
device, which has been opened in read/write
mode. The only applicable option is O_NDELAY.
The effects of O_NDELAY are explained under
the discussion on LOG_READ_TIMEOUT.
e.g. fildes=open("/dev/lan", O_RDWR);
e.g. fildes=open("/dev/lan", O_RDWR|O_NDELAY);
request Specifies whether a control or status function
is to be executed. The valid request values
are:
NETCTRL Write control information to the device.
NETSTAT Read statistics/status information from
the device.
arg Address of the (fis) data structure.
Arg.reqtype contains the command to be
executed. Each reqtype has a corresponding
set of subcommands. The command descriptions
are detailed below.
The following NETCTRL arg.reqtype arguments control the
read/write activities of the network device on a per file
descriptor basis:
Hewlett-Packard - 3 - (printed 7/16/86)
LAN(4) LAN(4)
LOG_TYPE_FIELD
NOTE: This command is restricted to the Ethernet*
protocol, and corresponds to the type field of the
Ethernet* header. When co-existing on a multi-
vendor network or catenet, the user should contact
Xerox for authorization to use a given type field.
See LOG_DSAP and LOG_SSAP below for the
corresponding IEEE802 commands.
Before read and write operations are allowed, a
user must log a type field with the driver. This
type field is the effective user address for the
network connection being established, and must be
unique among all open network connections, or an
error results. Only one type field may be declared
per (open) file descriptor; once logged, it cannot
be changed.
The format of the type field required by ioctl is
an integer in the range 0..65535 for those devices
supporting only Ethernet*, and 2049..65535 for
those devices supporting both Ethernet* and IEEE802
simultaneously.
LOG_TYPE_FIELD is the first call made in
establishing a network connection; the call will
fail if memory needed to log the type field is
unavailable.
The device header prepended to the user data by the
driver on each write call will contain this type
field. Read calls will return the data portion of
only those packets whose type field in the device
header matches the logged type field.
The following type fields are reserved by Hewlett-
Packard Company for its network operations: 0x8005,
0x0800, 0x0805.
The following parameters must be set prior to
calling ioctl:
arg.vtype = INTEGERTYPE;
arg.value.i = <type field>, range 0..65535
(2049..65535);
LOG_SSAP
NOTE: This command applies only to the IEEE802
protocol.
Before read and write operations are allowed, a
user must log a source sap, or ssap, with the
driver. This value is the effective user address
Hewlett-Packard - 4 - (printed 7/16/86)
LAN(4) LAN(4)
for the network connection being established, and
must be unique among all open network connections,
or an error results. Only one ssap may be declared
per (open) file descriptor; once logged, it cannot
be changed.
The format of the ssap required by ioctl is an even
integer in the range 2..254.
LOG_SSAP is the first call made in establishing a
network connection; the call will fail if memory
needed to log the ssap is unavailable.
LOG_SSAP sets the destination sap (dsap) value to
the ssap value; under normal circumstances, dsap
and ssap should remain equal.
The following sap values are reserved by Hewlett-
Packard Company for its network operations: 0x06,
0xFC.
The device header prepended to the user data by the
driver on each write call will contain this
ssap(dsap). Read calls return the data portion of
only those received packets whose dsap value in the
device header matches the logged ssap value.
The following parameters must be set prior to
calling ioctl:
arg.vtype = INTEGERTYPE;
arg.value.i = <source sap>, even integer in
the range 2..254;
LOG_DSAP
NOTE: This command applies only to the IEEE802
protocol.
LOG_DSAP can be called to change the default
destination sap (dsap) value set up by LOG_SSAP.
The dsap value can be changed any time after the
LOG_SSAP call and can be changed any number of
times.
The format of the dsap required by ioctl is an
integer in the range 0..255.
The device header prepended to the user data by the
driver on each write call will contain this dsap.
The following parameters must be set prior to
calling ioctl :
arg.vtype = INTEGERTYPE;
Hewlett-Packard - 5 - (printed 7/16/86)
LAN(4) LAN(4)
arg.value.i = <destination sap>, integer in
the range 0..255;
LOG_DEST_ADDR
Before write operations are allowed, a user must
log a destination address with the driver. This
address is the network station address of the
remote Ethernet*/IEEE802 device which is to receive
the data. LOG_DEST_ADDR can be called any time
after the LOG_TYPE_FIELD/LOG_SSAP call and can be
called any number of times.
A header prepended to the user data on each write
call will contain this destination address.
The following parameters must be set prior to
calling ioctl:
arg.vtype = <length of arg.value.s>; /* 6 */
arg.value.s = <destination address>;
LOG_READ_TIMEOUT
The default (0) timeout value blocks a user process
executing a read until data are available (see
LOG_TYPE_FIELD). A positive timeout value causes
the read to fail after the specified time has
elapsed, if no data are available. A negative
timeout value is treated as the default (0)
timeout. If the O_NDELAY flag is set, the timeout
mechanism is overridden and zero (bytes read) is
returned immediately if no data are available.
This command is called after logging a user-address
(LOG_TYPE_FIELD, LOG_DSAP).
NOTE: Due to race conditions caused by asynchronous
interrupts, the accuracy of the timer is guaranteed
only to the extent that it will not timeout sooner
than the given value.
The following parameters must be set prior to
calling ioctl:
arg.vtype = INTEGERTYPE;
arg.value.i = <timeout value in milliseconds>;
LOG_READ_CACHE
By default, only one packet received on an (open)
file descriptor is cached, pending a read to the
file descriptor. Subsequent packets received for
that file descriptor are discarded. A one-packet
cache is suitable for request/reply protocols. For
other protocols, up to 4 additional packets can be
cached, pending read calls. A request for
Hewlett-Packard - 6 - (printed 7/16/86)
LAN(4) LAN(4)
additional packets which would result in more than
4 additional packets being cached is truncated to
4. This command will fail if requested memory is
unavailable, or if called prior to logging a user-
address (LOG_SSAP, LOG_TYPE_FIELD).
The following parameters must be set prior to
calling ioctl:
arg.vtype = INTEGERTYPE;
arg.value.i = <additional packets to cache>;
LOG_CONTROL
NOTE: This command applies only to the IEEE802
protocol.
The super-user can override the default unnumbered
information (UI) control field of the IEEE802
header by using the following values:
The UI value is used for normal
communications.
When using the XID control field, any data
written to the network device are ignored; an
XID request packet is transmitted instead, and
any response is returned via the read
intrinsic.
When using the TEST control field, any data
written to the network device cause a TEST
packet containing the data to be transmitted;
any response is returned via the read
intrinsic.
This command is called after logging a destination
sap (LOG_DSAP).
The following parameters, defined in netio.h, must
be set prior to calling ioctl:
arg.vtype = INTEGERTYPE;
arg.value.i = UI_CONTROL;
XID_CONTROL;
TEST_CONTROL;
The following are global super-user-only NETCTRL arg.reqtype
arguments which affect the Ethernet*/IEEE802 device itself,
as opposed to a particular open file descriptor associated
with the device.
RESET_INTERFACE
Resets the Ethernet*/IEEE802 device, forcing a
complete hardware self-test. No parameters are
necessary. The current multicast state is
retained.
Hewlett-Packard - 7 - (printed 7/16/86)
LAN(4) LAN(4)
NOTE: A reset may destroy any currently active
network connections at the local node.
ADD_MULTICAST
Adds a multicast address to the device's list of
accepted multicast addresses. A received packet is
discarded if its multicast address is not in the
current list of accepted multicast addresses. A
multicast address list can contain up to 16
addresses.
The broadcast address is not handled as a typical
multicast address and is documented below under
ENABLE_BROADCAST/DISABLE_BROADCAST.
NOTE: On a Series 500 computer, the card may lose
packets when adding to the multicast list.
The following parameters must be set prior to
calling ioctl:
arg.vtype = <length of arg.value.s>; /* 6 */
arg.value.s = <multicast address>;
DELETE_MULTICAST
NOTE: Deletion of any HP-special multicast address
may prove catastrophic to an active HP network. The
HP multicast addresses are: 0x090009000001,
0x090009000002.
Removes a specified multicast address from the
current list of accepted multicast addresses.
The following parameters must be set prior to
calling ioctl:
arg.vtype = <length of arg.value.s>; /* 6 */
arg.value.s = <multicast address>;
ENABLE_BROADCAST
Allows broadcast packets to be received by the
network device. No parameters are needed.
DISABLE_BROADCAST
NOTE: The super-user is cautioned that the use of
this command may be catastrophic to an active HP
network.
Disallows broadcast packets from being received by
the network device. No parameters are needed.
The following NETCTRL control commands reset specified
statistics kept by the Ethernet*/IEEE802 device. No
parameters are needed for these.
Hewlett-Packard - 8 - (printed 7/16/86)
LAN(4) LAN(4)
RX_FRAME_COUNT
Set to zero the count of packets received without
error.
TX_FRAME_COUNT
Set to zero the count of packets transmitted
without error.
UNTRANS_FRAMES
Set to zero the count of packets that could not be
transmitted due to error.
UNDEL_RX_FRAMES
Set to zero the count of received but undeliverable
packets.
NOTE: Series 500 computers with 2285A LAN Units
combine the statistic UNKNOWN_PROTOCOL with the
UNDEL_RX_FRAMES errors.
RX_BAD_CRC_FRAMES
Set to zero the count of packets received with a
bad cyclical redundancy check (CRC).
COLLISIONS
Set to zero the count of transmit collisions. This
statistic is kept by Series 200 and 300 computers
and Series 500 computers with 2285A LAN Units only.
RESET_STATISTICS
Set to zero all statistics counters.
The following NETCTRL statistics are not kept on Series 500
computers with the 2285A LAN Unit.
DEFERRED
Set to zero the count of transmit packets for which
the card had to defer to other network traffic
before transmitting.
ONE_COLLISION
Set to zero the count of transmit packets for which
the card had to retransit exactly one time due to a
collision.
MORE_COLLISIONS
Set to zero the count of transmit packets for which
the card had to transmit between 2 and 15 times due
to collisions.
EXCESS_RETRIES
Hewlett-Packard - 9 - (printed 7/16/86)
LAN(4) LAN(4)
Set to zero the count of transmit packets that
could not be transmitted due to excessive
collisions (16 or more).
LATE_COLLISIONS
Set to zero the count of transmit packets for which
the card detected a late collision.
CARRIER_LOST
Set to zero the count of transmit packets that
failed due to loss of the carrier during
transmission.
NO_HEARTBEAT
Set to zero the count of transmit packets for which
no heartbeat was detected.
ALIGNMENT_ERRORS
Set to zero the count of received packets that were
misaligned and had a bad cyclic redundancy check
(CRC).
NOTE: These packets are also counted in the
RX_BAD_CRC_FRAMES count.
MISSED_FRAMES
Set to zero the count of times that the card missed
packet(s) due to lack of resources.
BAD_CONTROL_FIELD
Set to zero the count of IEEE802 packets received
with invalid control field values.
UNKNOWN_PROTOCOL
Set to zero the count of packets dropped because
the type field or dsap field referenced an unknown
protocol.
The following NETCTRL statistics are only kept by Series 500
computers with the 27125A LAN Card.
RX_XID
Set to zero the count of XID requests received.
RX_TEST
Set to zero the count of TEST requests received.
RX_SPECIAL_DROPPED
Set to zero the count of XID and TEST requests that
were received but not responded to due to lack of
resources.
Hewlett-Packard - 10 - (printed 7/16/86)
LAN(4) LAN(4)
RX_ERRORS
Set to zero the count of packets received with some
error.
NO_TX_SPACE
Set to zero the count of times that the card
exhausted its transmit buffer space.
LITTLE_RX_SPACE
Set to zero the count of times that the card had
little or no receive buffer space available.
ILLEGAL_FRAME_SIZE
Set to zero the count of packets seen by the card
that were illegal in size.
If request is NETSTAT, statistics are returned. The value
returned is the value since the last counter reset. This
value applies to the device as opposed to an open file
descriptor associated with the device. The result is
returned in arg.value in the appropriate field for its type,
which is designated by arg.vtype. The values for arg.vtype
are:
- INTEGERTYPE
- FLOATTYPE
- any non-negative value up to and including 100,
which indicates the length of the string in
arg.value.s. The string can contain nulls.
NOTE: Except where noted below, the result is of type
INTEGERTYPE and is contained in arg.value.i.
The valid arg.reqtype arguments for a NETSTAT request are:
FRAME_HEADER
Return the Ethernet*/IEEE802 device header
associated with the previous read call.
For Ethernet*, arg.vtype is 14, and arg.value.s
holds the following information:
s[0]..s[5] holds the destination address,
as determined by the sender;
this address could be the local
Ethernet* device's network
station address, or a
multicast/broadcast address;
Hewlett-Packard - 11 - (printed 7/16/86)
LAN(4) LAN(4)
s[6]..s[11] holds the network station
address of the sender's
Ethernet* device (i.e. source
address);
s[12]..s[13] holds the type field (user's
address) as a 16-bit unsigned
integer.
For IEEE802, arg.vtype is 17, and arg.value.s holds
the following information:
s[0]..s[5] holds the destination address,
as determined by the sender;
this address could be the local
IEEE802 device's network station
address, or a
multicast/broadcast address;
s[6]..s[11] holds the network station
address of the sender's IEEE802
device (i.e. source address);
s[12]..s[13] holds the received packet's
length, including 3 bytes for
the ssap/dsap and the control
field;
s[14] holds the destination sap value;
s[15] holds the source sap value;
s[16] holds the control field value.
LOCAL_ADDRESS
Return the address of the local Ethernet*/IEEE802
device in arg.value.s. For those devices
supporting Ethernet* and IEEE802 simultaneously,
the Ethernet* and IEEE802 addresses are identical.
Arg.vtype is 6 (length of arg.value.s). Any byte
of the address may be NULL.
DEVICE_STATUS
Return the current status of the Ethernet*/IEEE802
device. Possible return values are INACTIVE,
INITIALIZING, ACTIVE and FAILED.
RX_FRAME_COUNT
Return the number of packets received without
error.
TX_FRAME_COUNT
Hewlett-Packard - 12 - (printed 7/16/86)
LAN(4) LAN(4)
Return the number of packets transmitted without
error.
UNDEL_RX_FRAMES
Return the number of undeliverable packets
received.
UNTRANS_FRAMES
Return the number of packets that could not be
transmitted due to an error.
RX_BAD_CRC_FRAMES
Return the number of packets received with a bad
cyclical redundancy check (CRC).
COLLISIONS
Return the number of transmit attempts which were
retransmitted due to collision(s).
The following NETSTAT statistics are not kept on Series 500
computers with the 2285A LAN Unit.
MULTICAST_ADDRESSES
Return the current number of accepted multicast
addresses.
DEFERRED
Return the number of transmit packets for which the
card had to defer to other network traffic before
transmitting.
ONE_COLLISION
Return the number of transmit packets that had to
be retransmitted exactly once due to a collision.
MORE_COLLISIONS
Return the number of transmit packets that had to
be transmitted between 2 and 15 times due to
collisions.
EXCESS_RETRIES
Return the number of packets that were not
transmitted due to excessive collisions (16 or
more).
LATE_COLLISIONS
Return the number of transmit packets for which the
card detected a late collision.
Hewlett-Packard - 13 - (printed 7/16/86)
LAN(4) LAN(4)
CARRIER_LOST
Return the number of transmit packets that failed
due to loss of the carrier during transmission.
NO_HEARTBEAT
Return the number of transmit packets for which no
heartbeat was detected.
ALIGNMENT_ERRORS
Return the number of received packets that were
misaligned and had a bad cyclic redundancy check
(CRC).
NOTE: These packets are also reflected in the
RX_BAD_CRC_FRAMES count.
MISSED_FRAMES
Return the number of times that the card missed
packet(s) due to lack of resources.
BAD_CONTROL_FIELD
Return the number of IEEE802 packets received with
an invalid control field.
UNKNOWN_PROTOCOL
Return the number of packets dropped because the
type field or dsap field referenced an invalid
protocol.
The following NETSTAT statistics are only kept by the Series
500 computers with the 27125A LAN Card.
RX_XID
Return the number of XID request packets received.
RX_TEST
Return the number of TEST request packets received.
RX_SPECIAL_DROPPED
Return the number of XID and TEST requests received
but not responded to due to lack of resources.
RX_ERRORS
Return the number of packets received with some
error.
NO_TX_SPACE
Return the number of times that the card exhausted
its transmit buffer space.
LITTLE_RX_SPACE
Hewlett-Packard - 14 - (printed 7/16/86)
LAN(4) LAN(4)
Return the number of times that the card had little
or no receive buffer space available.
TDR Return the last TDR result generated by the network
chip on the card.
ILLEGAL_FRAME_SIZE
Return the number of packets seen by the card that
were illegal in size.
SEE ALSO
close(2), fcntl(2), ioctl(2), ncontrol(1), npowerup(1),
nstatus(1), open(2), read(2), write(2), net_aton(3N).
DIAGNOSTICS
If an error occurs, the error value is given in errno.
[EIO] Read/write failure (includes timeout
conditions).
[EPERM] A non-super-user attempted to call a
super-user-only command.
[ENOMEM] One of the following:
Memory requested by LOG_READ_CACHE is
unavailable.
Memory requested by LOG_TYPE_FIELD is
unavailable.
Memory requested by LOG_SSAP is
unavailable.
Memory requested by a write call is
unavailable.
[EBUSY] An attempt was made to log a user-level
address that is already in use.
[EFBIG] An attempt was made to write more than the
maximum bytes or a negative number of
bytes. (Series 500 only.)
[ENXIO] One of the following:
Read/write call preceded a LOG_TYPE_FIELD
or LOG_SSAP call.
Write call preceded a LOG_DEST_ADDR call.
[EINVAL] One of the following:
An attempt was made to write more than the
maximum bytes or a negative number of
bytes. (Series 200 and 300 only.)
Hewlett-Packard - 15 - (printed 7/16/86)
LAN(4) LAN(4)
LOG_READ_CACHE call preceded a LOG_SSAP or
LOG_TYPE_FIELD call.
LOG_READ_TIMEOUT call preceded a LOG_SSAP
or LOG_TYPE_FIELD call.
LOG_DSAP call preceded a LOG_SSAP call.
LOG_DEST_ADDR call preceded a LOG_SSAP or
LOG_TYPE_FIELD call.
LOG_CONTROL call preceded a LOG_SSAP call.
LOG_TYPE_FIELD call was sent to an IEEE802
device.
LOG_SSAP/LOG_DSAP/LOG_CONTROL call was sent
to an Ethernet* device.
An attempt was made to change a type_field
or ssap (user-level address).
Improper address format in an ioctl call
involving an address.
Address was/was not in the list of accepted
addresses in a call to ADD_MULTICAST/
DELETE_MULTICAST. Already 16 multicast
addresses.
Timeout value passed to LOG_READ_TIMEOUT
was too large.
Unknown arg.reqtype.
Incorrect arg.vtype.
Fildes does not specify an active network
I/O device.
The result of a FRAME_HEADER call is undefined if there
has been no previous read.
HARDWARE DEPENDENCIES
SERIES 200 and 300:
The networking code must be active before access to the
driver is allowed. An attempt to use the above calls
when the network has not been powered up results in an
[ENXIO] error.
SERIES 500:
Hewlett-Packard - 16 - (printed 7/16/86)
LAN(4) LAN(4)
User-level access to the 2285A Interface device is
limited to its supported statistics.
The COLLISIONS statistic is not kept by the Series 500
computers with 27125A LAN cards.
Series 500 computers with the 2285A LAN Unit include
UNKNOWN_PROTOCOL errors in the UNDEL_RX_FRAMES count.
* Ethernet is a trademark of Xerox corporation.
Hewlett-Packard - 17 - (printed 7/16/86)