HPUX lan[7]
lan(7) lan(7)
NAME
lan - network I/O card access information
DESCRIPTION
This manual entry explains how to access the LAN device driver at
Layer 2 (Data Link Layer) of the OSI architecture. The LAN device
driver controls the Ethernet/IEEE 802.3 LAN interface card at Layer 1
(Physical Layer).
Link Level Access is intended for use by knowledgeable network users
only. Refer to the LLA Programmer's Guide for complete programming
details.
System Calls
The following system calls are used to access the driver that controls
the IEEE 802.3/Ethernet interface card:
open() Opens the device file associated with the driver.
The only applicable option flags are the delay
flag, O_NDELAY, the read only flag, O_RDONLY, and
the read/write flag, O_RDWR. If O_NDELAY is set
and no data is available, a read() call returns
immediately. If you want to use only the NETSTAT
commands, specify the O_RDONLY flag. Otherwise,
the O_RDWR flag must be specified. These flags
are defined in the header <sys/fcntl.h>.
close() Closes a network device file.
read() Reads data from the network. The maximum number
of bytes that can be transferred per read() call
is 1500 for Ethernet and 1497 for IEEE 802.3.
Read operations may block (if O_NDELAY was not
specified in open) if system resources are not
immediately available to perform the operation.
Blocked read operations terminate upon delivery of
signals to the calling process.
Read and write operations can only address a
single packet of data appropriate for the protocol
being used.
write() Writes data out to the network. The maximum
number of bytes that can be transferred per
write() call is 1500 for Ethernet and 1497 for
IEEE 802.3.
Hewlett-Packard Company - 1 - HP-UX Release 9.0: August 1992
lan(7) lan(7)
Write operations never block, returning instead an
error indicating the type of resource limitation
that prevents performing the operation (see for
specific details).
Read and write operations can only address a
single packet of data appropriate for the protocol
being used.
select() Used before read() and write() calls to help an
application synchronize its I/O operations.
select() is supported for read and write
operations, but it is not supported for
exceptional conditions.
ioctl() Used to construct, inspect, and control the
network environment in which the application
operates. All applications must use the ioctl()
call to configure source and destination addresses
before data can be sent or received using read()
and write() calls. The ioctl() syntax used for
these operations is as follows:
#include <netio.h>
ioctl (fildes,request,arg);
int fildes,request;
struct fis *arg;
Parameters in the calling sequence are:
fildes The file descriptor of the
successfully opened Ethernet/IEEE
802.3 device.
request Specifies which type of command to
perform. This parameter must be
either NETSTAT or NETCTRL.
arg Address of the fis data structure.
The fis data structure contains
information necessary to perform a
specific NETCTRL or NETSTAT
command. The arg parameter must be
set to the address of a fis
structure before an ioctl() call is
made. The type of information
stored in arg is:
struct fis { int reqtype;
int vtype;
Hewlett-Packard Company - 2 - HP-UX Release 9.0: August 1992
lan(7) lan(7)
union { float f;
int i;
unsigned char s[100];
} value;
};
where:
reqtype contains the name of
the NETCTRL or
NETSTAT command to
be executed.
vtype identifies the type
of the value in the
value union. If
vtype = INTEGERTYPE,
the value is in
value.i. If vtype =
FLOATTYPE, the value
is in value.f. If
vtype = a non-
negative integer,
the value is a
character string in
value.s. This
integer also
specifies the length
of the string. The
vtype parameter must
only be specified
for NETCTRL
commands.
NETCTRL and NETSTAT Commands
NETCTRL commands are used to set up device-specific parameters prior
to read and write operations, and to reset the network I/O card and
its statistical registers. There are two types of NETCTRL commands:
those that affect the network I/O cards and those that affect a
particular connection to the network I/O card.
NETSTAT commands are used to obtain device-dependent status and
statistical information.
Station Management NETCTRL Commands
The following NETCTRL arg.reqtype arguments control the read/write
activities of the network device on a per-file-descriptor basis:
LOG_TYPE_FIELD
This command is restricted to the Ethernet protocol, and
corresponds to the type field of the Ethernet header. When
Hewlett-Packard Company - 3 - HP-UX Release 9.0: August 1992
lan(7) lan(7)
co-existing on a multi-vendor network, the user should
contact Xerox Corporation for authorization to use a given
type field. See LOG_DSAP and LOG_SSAP below for the
corresponding IEEE 802.3 commands.
Before performing read() and write() operations, a type
field must be logged 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 on the same interface card or an error results.
Only one type field can 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 2048..65535.
LOG_TYPE_FIELD is the first call made in establishing a
network connection. The call fails if memory needed to log
the type field is unavailable.
The device header prefixed to the user data by the driver on
each write() call contains this type field. read() calls
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 addresses: 2048,
2053, 2054, 32773. Any attempt to log these types fails,
returning EBUSY to the calling process.
Other specifically reserved addresses include 4096 through
4111. These types are reserved for use by Berkeley Trailer
Protocols.
The following parameters must be set prior to calling
ioctl():
arg.vtype = INTEGERTYPE;
arg.value.i = type field ;
LOG_SSAP
This command applies only to the IEEE 802.3 protocol.
Before performing read() and write() operations, a source
service access point (SSAP) must be logged with the driver.
This value is the effective user address for the network
connection being established, and must be unique among all
open network connections on the same interface card or an
error results. Only one SSAP can be declared per (open)
file descriptor. Once logged, it cannot be changed.
Hewlett-Packard Company - 4 - HP-UX Release 9.0: August 1992
lan(7) lan(7)
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 fails if memory needed to log the SSAP
is unavailable.
LOG_SSAP sets the destination service access point (DSAP)
value to the SSAP value. Under normal circumstances, DSAP
and SSAP should remain equal.
The following SSAP values are reserved addresses: 6, 252,
248. An attempt to log these SSAPS fail with EBUSY returned
to the calling process.
The device header inserted in front of the user data by the
driver on each write() call contains 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 = SSAP;
LOG_DSAP
This command applies only to the IEEE 802.3 protocol.
LOG_DSAP can be called to change the default 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..254.
The device header inserted in front of the user data by the
driver on each write() call contains this DSAP.
The following parameters must be set prior to calling
ioctl() :
arg.vtype = INTEGERTYPE;
arg.value.i = DSAP ;
LOG_DEST_ADDR
Before performing write() operations, a destination address
must be logged with the driver. This address is the network
station address of the remote Ethernet/IEEE 802.3 device
Hewlett-Packard Company - 5 - HP-UX Release 9.0: August 1992
lan(7) lan(7)
that is to receive the data. LOG_DEST_ADDR commands can be
issued any time but must be specified prior to attempting a
write. LOG_DEST_ADDR commands can be issued any number of
times during a LLA connection.
A header inserted in front of the user data on each write()
call contains this destination address .
The following parameters must be set prior to calling
ioctl():
arg.vtype = 6;
arg.value.s = destination address ;
LOG_READ_TIMEOUT
The default (0) timeout value blocks a user process
executing a read() until data is available (see
LOG_TYPE_FIELD). A positive timeout value causes the read()
to fail after the specified time has elapsed if no data is
available. A negative timeout value fails with EINVAL
returned. If the O_NDELAY flag is set, the timeout
mechanism is overridden and the error, EWOULDBLOCK, is
returned to the calling process.
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 assigned value.
The following parameters must be set prior to calling
ioctl():
arg.vtype = INTEGERTYPE;
arg.value.i = read timeout value in milliseconds ;
LOG_READ_CACHE
By default, only one packet received for an active type
field or DSAP is cached, pending a read() to the associated
file descriptor. Subsequent packets received for that file
descriptor are discarded. This one-packet cache is suitable
for request/reply protocols, but may not be suitable for
applications that communicate with more than one host or
where windowing protocols are used. LOG_READ_CACHE can be
used to increase the the receive cache buffer to a total of
16 packets for a normal user and a total of 64 packets for a
user with appropriate privileges. Any request for
additional packet caching that would result in a cache size
greater than the above limits is truncated to the
appropriate limit. The following parameters must be set
prior to calling ioctl():
Hewlett-Packard Company - 6 - HP-UX Release 9.0: August 1992
lan(7) lan(7)
arg.vtype = INTEGERTYPE;
arg.value.i = additional packets to cache ;
LOG_CONTROL
This command applies only to the IEEE 802.3 protocol and
conforms to its specification. Refer to the IEEE 802.3
specification for detailed information about the UI, XID,
and TEST control fields mentioned below.
This command requires appropriate privileges.
The Unnumbered Information (UI) control field of the IEEE
802.3 header is the default used for normal communication.
This default can be overridden with XID_CONTROL or
TEST_CONTROL. When using either the XID or TEST control
field, any data written to the network device is ignored; an
XID or TEST request packet is transmitted instead, and any
response from other network nodes is returned via the read()
call.
Prior to calling ioctl() , the arg.vtype parameter must be
set to INTEGERTYPE; the arg.value.i parameter must be set to
UI_CONTROL, XID_CONTROL, or TEST_CONTROL.
LLA_SIGNAL_MASK
This request allows the user to specify which defined LAN
events can generate a SIGIO signal to the process which
configured it. Currently, the LAN events which can generate
SIGIO are receipt of packet on LLA connection and inbound
queue overflow for LLA connection. Mask values can be
derived by ORing one or more of the following LAN events
into the value.i operand:
LLA_PKT_RECV
is used when the process is to be signaled every
time a packet is successfully queued for
subsequent reading. If the queue is full and the
packet must be discarded, no signal is generated.
Also, if the process is blocked on a read to the
LLA connection, no signal will be generated
because this would interfere with the current
read.
LLA_Q_OVERFLOW
is used when the process is to be signaled every
time a packet must be discarded as a result of
inbound queue overflow.
To eliminate signal generation completely,
LLA_NO_SIGNAL should be assigned (not ORed) to
value.i.
Hewlett-Packard Company - 7 - HP-UX Release 9.0: August 1992
lan(7) lan(7)
Be careful when combining mask values because
receipt of a signal does not convey which event
occurred. Note also that the driver signals only
that process which last configured the
LLA_SIGNAL_MASK. Processes that share file
descriptors can potentially interfere with the
intended use of LLA SIGIO.
Prior to calling ioctl() , the arg.vtype parameter
must be set to INTEGERTYPE; the arg.value.i
parameter must be set to either LLA_NO_SIGNAL or a
combination of LLA_PKT_RECV, and LLA_Q_OVERFLOW.
Device Control NETCTRL Commands
The following are global NETCTRL arg.reqtype arguments that
affect the Ethernet/IEEE 802.3 device itself, as opposed to a
particular open file descriptor associated with the device, and
are accessible only to users with appropriate privileges.
RESET_INTERFACE
Resets the Ethernet/IEEE 802.3 device, forcing a
complete hardware self-test. All statistical counters
are reset to zero. No parameters are necessary. The
current multicast state is retained.
A reset can drop packets or impair any currently active
network connection to the local computer.
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 is a 48-bit value with the least significant bit
of the first octet set to indicate a group address. 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.
The following parameters must be set prior to calling
ioctl():
arg.vtype = 6;
arg.value.s = multicast address ;
DELETE_MULTICAST
Removes a specified multicast address from the current
list of accepted multicast addresses.
Hewlett-Packard Company - 8 - HP-UX Release 9.0: August 1992
lan(7) lan(7)
The following parameters must be set prior to calling
ioctl():
arg.vtype = 6;
arg.value.s = multicast address ;
Deletion of any HP-special multicast address may prove
catastrophic to an active HP network. The HP multicast
addresses are: 0x090009000001, 0x090009000002.
ENABLE_BROADCAST
Allows broadcast packets to be received by the network
device. No parameters are needed.
DISABLE_BROADCAST
Disallows broadcast packets from being received by the
network device. No parameters are needed.
Users with appropriate privileges are cautioned that use
of this command may be catastrophic to an active HP
network.
Reset and Read Statistics Commands
The following commands are provided to collect and reset
interface statistics and can be used as NETCTRL or NETCTRL
ioctl() commands. All of the NETCTRL commands require
appropriate privileges. When request equals NETCTRL and
arg.reqtype equals RESET_STATISTICS, all interface statistics
counters are reset to zero. When request equals NETSTAT, the
current value of the statistic specified in arg.reqtype is
returned. The following section assumes that the specified
request is NETSTAT.
RX_FRAME_COUNT Returns the number of packets received
without error.
TX_FRAME_COUNT Returns the number of packets
transmitted without error.
UNTRANS_FRAMES Returns the number of packets that, due
to some error, could not be transmitted.
UNDEL_RX_FRAMES Returns the number of packets which were
received, but due to some error, could
not be delivered to an appropriate
network connection.
RX_BAD_CRC_FRAMES Returns the number of packets received
with a bad CRC.
Hewlett-Packard Company - 9 - HP-UX Release 9.0: August 1992
lan(7) lan(7)
COLLISIONS Returns the number of transmit attempts
that were retransmitted due to
collisons.
RESET_STATISTICS Not applicable.
DEFERRED Returns the number of packets that had
to defer before transmission.
ONE_COLLISION Returns the number of transmissions
completed with one collision.
MORE_COLLISIONS Returns the number of transmissions
completed with more than one collision.
EXCESS_RETRIES Returns the number of packets that were
not transmitted due to an excessive
number of retries (16 or more).
LATE_COLLISIONS Returns the number of transmit packets
for which the card detected a late
collision.
CARRIER_LOST Returns the number of transmit packets
that failed due to the loss of the
carrier. This is a hardware-dependent
statistic that indicates problems with
the Medium Attachment Unit (MAU)
cabling.
NO_HEARTBEAT Returns the number of transmit packets
for which no heartbeat was detected.
This is a hardware-dependent statistic
that indicates problems with the Medium
Attachment Unit (MAU) cabling.
ALIGNMENT_ERRORS Returns the number of packets received
with an alignment error and a bad CRC.
These packets are also counted in the
RX_BAD_CRC_FRAMES count.
MISSED_FRAMES Returns the number of times that the
card missed packets due to lack of
resources.
BAD_CONTROL_FIELD Returns the number of IEEE 802.3 packets
received with an invalid control field.
UNKNOWN_PROTOCOL Returns the number of packets dropped
because the type field or DSAP
referenced an unknown protocol.
Hewlett-Packard Company - 10 - HP-UX Release 9.0: August 1992
lan(7) lan(7)
RX_XID Returns the number of IEEE 802.3 XID
packets that were received.
Refer to the discussion of the
LOG_CONTROL command earlier on this
reference page for more information
about XID packets.
RX_TEST Returns the number of IEEE 802.3 TEST
packets that were received.
RX_SPECIAL_DROPPED Returns the number of IEEE 802.3 XID or
TEST packets that were received but not
responded to due to lack of space on the
outbound queue.
NO_TX_SPACE Returns the number of times that the
card exhuasted its transmit buffer
space. This statistic is kept by Series
800 systems only.
LITTLE_RX_SPACE Returns the number of times the card had
one or no buffers to accept incoming
packets. This statistic is kept by
Series 800 systems only.
ILLEGAL_FRAME_SIZE Returns the number of times the card
received and discarded packets that were
illegal in size (greater than 1514
bytes). This statistic is kept by
Series 800 systems only.
TDR Returns the time (in bit times) from
when a frame started to transmit until a
collision occurred. This statistic can
be useful for grossly determining where
on the cable a problem is located. This
statistic is not updated after an
external loopback frame is transmitted.
This statistic is kept by Series 800
systems only.
The following commands are provided to collect interface
statistics, but can be only used as NETSTAT commands.
FRAME_HEADER Return the Ethernet/IEEE 802.3 device
header associated with the previous
read() call. The result of a
FRAME_HEADER call is undefined if there
has been no previous read().
Hewlett-Packard Company - 11 - HP-UX Release 9.0: August 1992
lan(7) lan(7)
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;
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 IEEE 802.3, 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 IEEE
802.3 device's network station
address or a multicast/broadcast
address.
s[6]..s[11] holds the network station address of
the sender's IEEE 802.3 device (i.e.
source address).
s[12]..s[13] holds the received packet's length,
including data, 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 Returns the address of the local
Ethernet/IEEE 802.3 device in
arg.value.s. arg.vtype is 6 (length of
arg.value.s). Any byte of the address
can be NULL.
DEVICE_STATUS Returns the current status of the
Ethernet/IEEE 802.3 device. Possible
Hewlett-Packard Company - 12 - HP-UX Release 9.0: August 1992
lan(7) lan(7)
return values are INACTIVE,
INITIALIZING, ACTIVE and FAILED.
MULTICAST_ADDRESSES Returns the current number of accepted
multicast addresses in arg.value.i.
MULTICAST_ADDR_LIST Returns the current list of accepted
multicast addresses in arg.value.s. The
value specified in arg.vtype.s
represents the number of bytes used for
the contiguous address list in
arg.value.s. Each address is six bytes
long. The maximum number of bytes that
can be returned is 96.
DIAGNOSTICS
If an error occurs, the error value is given in errno.
[EIO] read()/write() failure (includes timeout
conditions).
[EPERM] A user attempted to call a command that requires
privileges the user does not have.
[ENOMEM] Series 300 only. One of the following:
o Memory requested by LOG_READ_CACHE is
unavailable.
o Memory requested by LOG_TYPE_FIELD is
unavailable.
o Memory requested by LOG_SSAP is unavailable.
o Memory requested by a write() call is
unavailable.
[EBADF] An attempt was made to write (or NETCTRL ioctl())
to a device that was opened with O_RDONLY
permission.
[EBUSY] An attempt was made to log a user-level address
that is already in use.
[ENXIO] One of the following:
o An attempt was made to open() LAN device
with incorrect select code (Series 300/400)
or incorrect logical unit or protocol
(Series 700/800). lanscan can be used to
display the select code (Series 300/400) or
the hardware path (Series 700/800) and the
logical unit of each LAN interface card (see
lanscan(1M)).
Hewlett-Packard Company - 13 - HP-UX Release 9.0: August 1992
lan(7) lan(7)
o The specified driver call could not complete
because the interface card was found to be
in a DEAD state. The card must be reset
before any further interface activity can
resume.
[EINTR] During a blocked read, the calling process was
delivered a software interrupt prior to receiving
a packet on its inbound queue.
[EDESTADDRREQ] read()/write() call preceded a LOG_TYPE_FIELD or
LOG_SSAP call.
write() call preceded a LOG_DEST_ADDR call.
[EMSGSIZE] An attempt was made to write() more than the
maximum bytes allowed by the selected protocol.
[EINVAL] One of the following:
o An attempt was made to write() or read() a
negative number of bytes.
o An attempt was made to open() with bad oflag
value.
o LOG_DSAP call preceded a LOG_SSAP call.
o LOG_TYPE_FIELD call was sent to an IEEE
802.3 device.
o LOG_SSAP, LOG_DSAP, LOG_CONTROL, or RX_XID ,
RX_TEST, RX_SPECIAL_DROPPED,
BAD_CONTROL_FIELD calls were sent to an
Ethernet device.
o An attempt was made to log a user address
and the SSAP or TYPE was out of range.
o An attempt was made to change a type_field
or SSAP (user-level address).
o Improper address format in an ioctl() call
involving an address.
o An ADD_MULTICAST call was attempted but the
supplied address was already in the list.
o An ADD_MULTICAST call was attempted but 16
multicast addresses were already logged
(list full).
Hewlett-Packard Company - 14 - HP-UX Release 9.0: August 1992
lan(7) lan(7)
o A DELETE_MULTICAST call was attempted but
the supplied address was not in the list.
o A DELETE_MULTICAST call was attempted but no
multicast addresses have been logged (list
empty).
o An ADD_MULTICAST or DELETE_MULTICAST call
was attempted but the multicast bit was not
set in address operand.
o Timeout value passed to LOG_READ_TIMEOUT was
negative.
o Unknown arg.reqtype.
o Incorrect arg.vtype.
o fildes does not specify an active network
I/O device.
o An attempt was made to set LLA_SIGNAL_MASK
with undefined events set in the mask
operand.
[ENOSPC] An attempt to write() a packet failed as a result
of an outbound queue overflow on the interface
card.
[ENOBUFS] An open(), read(), write(), or ioctl() call could
not get enough memory.
NOTES
The fstat() system call does not support LAN device files (see
fstat(2)). When fstat() is called on a LAN device file, the error
code [EINVAL] is returned. Use stat() instead (see stat(2)).
WARNINGS
Multiple processes sharing a file descriptor can interfere with each
other, especially with respect to the commands LOG_READ_TIMEOUT,
LOG_READ_CACHE, LOG_DEST_ADDR, and LLA_SIGNAL_MASK.
Also, the network driver does not guarantee data delivery. On a
successful write(), the only guarantee is that data has been queued
for transmission by the network I/O card. Likewise, there is no
guarantee that once transmitted, data is received by the target node.
The desired degree of reliability must be coded into the user program.
AUTHOR
lan was developed by HP
Hewlett-Packard Company - 15 - HP-UX Release 9.0: August 1992
lan(7) lan(7)
SEE ALSO
lanscan(1M), close(2), fcntl(2), ioctl(2), open(2), read(2),
select(2), signal(2), write(2), net_aton(3N).
The Ethernet, A LAN: Data Link Layer and Physical Specification,
Version 2.0, November 1982, Digital Equipment Corporation, Intel
Corporation, Xerox Corporation
CSMA/CD Access Method and Physical Specification, October 1984,
Institute of Electrical and Electronic Engineers
LLA Programmer's Guide.
DEPENDENCIES
Series 300
NO_TX_SPACE, LITTLE_RX_SPACE, TDR,RX_XID, RX_TEST, RX_SPECIAL_DROPPED,
MULTICAST_ADDR_LIST, and ILLEGAL_FRAME_SIZE statistics are not kept by
Series 300 systems.
Hewlett-Packard Company - 16 - HP-UX Release 9.0: August 1992