[ Previous | Next | Contents | Home | Search ]
AIX Version 4.3 Kernel and Subsystems Technical Reference, Volume 1

uwritec Kernel Service

Purpose

Retrieves a character from a buffer described by a uio structure.

Syntax

#include <sys/types.h>
#include <sys/errno.h>
#include <sys/uio.h>
int uwritec (uiop)
struct uio *uiop;

Parameter

uiop Points to a uio structure describing the buffer from which to read a character.

Description

The uwritec kernel service reads a character from a buffer described by a uio structure. Device driver top half routines, especially character device drivers, frequently use the uwritec kernel service to transfer data out of a user area. The uio_resid and uio_iovcnt fields in the uio structure must be greater than 0 or an error is returned.

The uio_segflg field in the uio structure indicates whether the data is being read out of a user- or kernel-data area. This field also indicates whether the caller requires cross-memory operations and has provided the required cross-memory descriptors. The values for this flag are defined in the /usr/include/sys/uio.h file.

If the data is successfully read, the following fields in the uio structure are updated:

uio_iov Specifies the address of the current iovec element to use.
uio_xmem Specifies the address of the current xmem element to use (used for cross-memory copy).
uio_iovcnt Specifies the number of remaining iovec elements.
uio_iovdcnt Specifies the number of iovec elements already processed.
uio_offset Specifies the character offset on the device to which data is written.
uio_resid Specifies the total number of characters remaining in the data area described by the uio structure.
iov_base Specifies the address of the next available character in the data area described by the current iovec element.
iov_len Specifies the length of the remaining data in the buffer described by the current iovec element.

Execution Environment

The uwritec kernel service can be called from the process environment only.

Return Values

Upon successful completion, the uwritec service returns the character it was sent to retrieve.

-1 Indicates that the buffer is empty or the user location is not valid for one of these three reasons:
  • The uio_segflg field indicates user space and the base address (iov_base field) points to a location outside of the user address space.
  • The user does not have sufficient authority to access the location.
  • An I/O error occurred while the location was being accessed.

Implementation Specifics

The uwritec kernel service is part of Base Operating System (BOS) Runtime.

Related Information

The uiomove kernel service, uphysio kernel service, ureadc kernel service.

[ Previous | Next | Contents | Home | Search ]