writex Subroutine Interface for Data Link Control (DLC) Devices

AIX Version 4.3 Communications Technical Reference, Volume 1

writex Subroutine Interface for Data Link Control (DLC) Devices

Purpose

Allows application data to be sent using a file descriptor.

Syntax

#include <sys/gdlextcb.h>
#include <sys/uio.h>

int writex (fildes, buf, len, ext)
char *buf;
int ext;
int fildes, len;

Description

Four types of data can be sent to generic data link control (GDLC). Network data can be sent to a service access point (SAP), while normal, Exchange Identification (XID) or datagram data can be sent to a link station (LS). Data is transferred using the uiomove kernel service between the application user space and kernel communications I/O buffers (mbufs). All data must fit into a single packet for each write subroutine. The generic data link control does not separate the user's write data area into multiple transmit packets. A maximum write data size is passed back to the user at DLC_ENABLE_SAP completion and at DLC_START_LS completion for this purpose. See DLC_SAPE_RES and DLC_STAS_RES for further information.

Normally, GDLC can immediately satisfy a write subroutine by completing the data link headers and sending the transmit packet down to the device handler. In some cases, however, transmit packets can be blocked by the particular protocol's flow control or by a resource outage. GDLC reacts to this differently, based on the system blocked or nonblocked file status flags. These are set for each channel using the O_NDELAY and O_NONBLOCK values passed on open or fcntl subroutines with the F_SETFD parameter.

GDLC only looks at the uio_fmode field on each write subroutine to determine whether the operation is blocked or nonblocked. Nonblocked writes that cannot get enough resources to queue the data return an error indication. Blocked write subroutines put the calling process to sleep until the resources free up or an error occurs.

Note: GDLC does not support nonblocked transmit users based on resource availability using the selwakeup subroutine. Internal resources such as communications I/O buffers and control block locks are very dynamic. Any write subroutines that fail with errors (such as EAGAIN or ENOMEM) should be retried at the user's discretion.

Parameters

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 writex subroutine. "write Subroutine Extended Parameters for DLC" provides more information on this parameter.

Return Values

Upon successful completion, this service returns the number of bytes that were written into a communications packet from the user data area.

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

EAGAIN	Indicates insufficient resources to satisfy the write. For example, the routine was unable to obtain a necessary lock. The user can try again later.
EBADF	Indicates a bad file number.
EINTR	Indicates that a signal interrupted the subroutine before it completed successfully.
EINVAL	Indicates an invalid value, such as too much data for a single packet.
EIO	Indicates that an I/O error has occurred, such as loss of the port.
ENOMEM	Indicates insufficient resources to satisfy the write operation. For example, a lack of communications memory buffers (mbufs). The user can try again later.

Implementation Specifics

Each GDLC supports the writex subroutine interface via its dlcwrite entry point. This subroutine may be called from the process environment only.

Related Information

The fcntl subroutine, open subroutine, writex subroutine.

The uiomove kernel service.

Parameter Blocks by ioctl Operation for DLC.

readx Subroutine Interface for DLC Devices, write Subroutine Extended Parameters for DLC.

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