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.
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;
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 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.
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 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():
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 OR ing 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 OR ed) to value.i.
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.
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.
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.
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().
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 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:
• 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.
[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:
• 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)).
• 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:
• An attempt was made to write() or read() a negative number of bytes.
• An attempt was made to open() with bad oflag value.
• LOG_DSAP call preceded a LOG_SSAP call.
• LOG_TYPE_FIELD call was sent to an IEEE 802.3 device.
• LOG_SSAP, LOG_DSAP, LOG_CONTROL, or RX_XID , RX_TEST, RX_SPECIAL_DROPPED, BAD_CONTROL_FIELD calls were sent to an Ethernet device.
• An attempt was made to log a user address and the SSAP or TYPE was out of range.
• An attempt was made to change a type_field or SSAP (user-level address).
• Improper address format in an ioctl() call involving an address.
• An ADD_MULTICAST call was attempted but the supplied address was already in the list.
• An ADD_MULTICAST call was attempted but 16 multicast addresses were already logged (list full).
• A DELETE_MULTICAST call was attempted but the supplied address was not in the list.
• A DELETE_MULTICAST call was attempted but no multicast addresses have been logged (list empty).
• An ADD_MULTICAST or DELETE_MULTICAST call was attempted but the multicast bit was not set in address operand.
• Timeout value passed to LOG_READ_TIMEOUT was negative.
• Unknown arg.reqtype.
• Incorrect arg.vtype.
• fildes does not specify an active network I/O device.
• 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
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 — HP-UX Release 9.0: August 1992