dlcread Entry Point of the GDLC Device Manager

Purpose

Reads receive data from generic data link control (GDLC).

Syntax

#include <sys/device.h>
#include <sys/gdlextcb.h>
int dlcread (devno, uiop, chan, ext)
Note: The dlc prefix is replaced with the three-digit prefix for the specific GDLC device manager being read.

Description

The dlcread entry point is called when a user application program invokes the readx subroutine. Kernel users do not call an fp_read kernel service. All receive data is returned to the user in the same order as received. The type of data that was read is indicated, as well as the service access point (SAP) and link station (LS) identifiers.

The following fields in the uio and iov structures are used to control the read-data transfer operation:

Field Description
uio_iov Points to an iovec structure.
uio_iovcnt Indicates the number of elements in the iovec structure. This must be set to a value of 1. Vectored read operations are not supported.
uio_offset Indicates the file offset established by a previous fp_lseek kernel service. This field is ignored by GDLC.
uio_segflag Indicates whether the data area is in application or kernel space. This is set to the UIO_USERSPACE value by the file I/O subsystem to indicate application space.
uio_fmode Contains the value of the file mode set with the open applications subroutine to GDLC.
uio_resid Specifies initially the total byte count of the receive data area. GDLC decrements this count for each packet byte received using the uiomove kernel service.
iovec structure Contains the starting address and length of the received data.
iov_base Specifies where GDLC writes the address of the received data. This field is a variable in the iovec structure.
iov_len Contains the byte length of the data. This field is a variable in the iovec structure.

Each GDLC supports the dlcread entry point as its switch table entry for the readx subroutine. The file system calls this entry point from the process environment only.

Parameters

Item Description
devno Indicates major and minor device numbers. This is a dev_t device number that specifies both the major and minor device numbers of the GDLC device manager. One dev_t device number exists for each type of GDLC, such as Ethernet, Token-Ring, or SDLC.
uiop Points to the uio structure containing the read parameters.
chan Specifies the channel ID assigned by GDLC in the dlcmpx routine at open time.
ext Specifies the extended subroutine parameter. This is a pointer to the extended I/O structure. The argument to this parameter must always be in the application space.

Return Values

Successful read operations and those truncated due to limited user data space each return a value of 0 (zero). If more data is received from the media than will fit into the application data area, the DLC_OFLO value indicator is set in the command extension area (dlc_io_ext) to indicate that the read is truncated. All excess data is lost.

The following return values are defined in the /usr/include/sys/errno.h file:

Value Description
EBADF Indicates a bad file number.
EINTR Indicates that a signal interrupted the routine before it received data.
EINVAL Indicates an invalid value.
ENOMEM Indicates insufficient resources to satisfy the read operation.