readx Subroutine Interface for Data Link Control (DLC) Devices

Purpose

Allows receive application data to be read using a file descriptor.

Syntax

#include <sys/gdlextcb.h>
#include <sys/uio.h>
int readx (fildes, buf, len, ext)

Description

The receive queue for this application user is interrogated for any pending data. The oldest data packet is copied to user space, with the type of data, the link station correlator, and the service access point (SAP) correlator written to the extension area. When attempting to read an empty receive data queue, the default action is to delay until data is available. If the O_NDELAY or O_NONBLOCK flags are specified in the open subroutine, the readx subroutine returns immediately to the caller.

Data is transferred using the uiomove kernel service between the user space and kernel communications memory buffers (mbufs). A complete receive packet must fit into the user's read data area. Generic data link control (GDLC) does not break up received packets into multiple user data areas.

Each GDLC supports the readx subroutine interface via its dlcread entry point. This subroutine can be called from the process environment only.

Parameters

Item Description
fildes Specifies the file descriptor returned from the open subroutine.
buf Points to the user data area.
len Contains the byte count of the user data area.
ext Specifies the extended subroutine parameter. This is a pointer to the dlc_io_ext extended I/O structure for the readx subroutine.
Note: It is the user's responsibility to set the ext parameter area to 0 (zero) before issuing the readx subroutine to insure valid entries when no data is available.

Return Values

Upon successful completion, the readx subroutine returns the number of bytes read and placed into the application data area. If more data is received from the media than will fit into the application data area, the DLC_OFLO flag is set in the dlc_io_ext command extension area to indicate that the read is truncated. All excess data is lost.

If no data is available and the application user has specified the O_NDELAY or O_NONBLOCK flags at open time, a 0 (zero) is returned.

If an error occurs, a value of -1 is returned with one of the following error numbers available using the errno global variable, as defined in the /usr/include/sys/errno.h file:

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