Technical Reference: Communications, Volume 1

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.

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:

`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.

Parameters

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. See the "read Subroutine Extended Parameters for DLC" for more information on this parameter.

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:

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.

Implementation Specifics

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.

Related Information

The open subroutine, readx subroutine.

The ddread device entry point.

The dlcmpx entry point of the GDLC device manager, dlcwrite entry point of the GDLC device manager.

The fp_lseek kernel service, fp_read kernel service, uiomove kernel service.

read Subroutine Extended Parameters for DLC.

Generic Data Link Control (GDLC) Environment Overview in AIX 5L Version 5.1 Communications Programming Concepts.