NAME

awrite − asynchronous write on a file

SYNOPSIS

id = awrite (fildes, buf, nbyte, reqid, status, bytecnt)
int fildes;
char ∗buf;
unsigned nbyte;
int reqid;
int ∗status;
int ∗bytecnt

DESCRIPTION

awrite attempts to write nbyte bytes from the buffer pointed to by buf to the open file associated with the file descriptor fildes.  awrite returns control to its caller before the I/O operation completes.  While the I/O operation is in progress, the caller must not reference the buffer. 

Reqid is a user-supplied identifier which may be used to wait for the I/O operation to complete (see await(2)).  If reqid is specified as −1, the system will select an identifier.  Otherwise, reqid must be between 0 and 31 inclusive. 

If status is not zero, the value EINPROGRESS is stored in ∗status until the I/O operation completes.  At that time, it is updated with the operation’s final completion status (a value other than EINPROGRESS).  Status may be specified as zero if the completion status is not of interest. 

If bytecnt is not zero, the number of bytes actually written is stored in ∗bytecnt when the I/O operation completes.  This number may be less than the number of bytes requested if there is insufficient room (e.g., the ulimit (see ulimit(2)) or the physical end of a medium).  Only as many bytes as there is room for will be written.  For example, suppose there is space for 20 bytes more in a file before reaching a limit.  A write request of 512 bytes will actually write only 20 bytes.  The next write of a non-zero number of bytes will give a failure return (except as noted below).  Bytecnt may be specified as zero if the number of bytes actually written is not of interest. 

The SIGIO signal is sent to the calling process when the I/O operation completes. 

On devices capable of seeking, the actual writing of data proceeds from the position in the file indicated by the file pointer.  Upon initiation of the write operation, the file pointer is incremented by nbyte.  On devices incapable of seeking, writing always takes place starting at the current position.  The value of a file pointer associated with such a device is undefined. 

If the O_APPEND flag of the file status flags is set, the file pointer will be set to the end of the file prior to each write. 

For awrite operations on regular disk files, the system will indicate completion either when the data reaches the system cache or when it is written to disk.  The choice is made during the open(2) call:

If the O_AFLUSH bit is set in the mode word, completion is indicated when the data gets to disk. 

If O_AFLUSH is not set, completion is indicated when data gets to the cache. 

Note that an awrite(2) to a regular disk file without O_AFLUSH is functionally equivalent to a write(2) call.  Since the awrite involves more overhead, it is recommended that it be used only in conjunction with the O_AFLUSH bit. 

When attempting to write a file that has been opened in direct mode (i.e. O_DIRECT is set) the buffer pointed to by buf must be 4-byte aligned.  Additionally nbyte must be a multiple of 4 bytes and less than the maximum physical transfer size of the machine (see the CX/UX Programmer’s Guide for details).  Lastly, the file pointer associated with fildes must be aligned to a multiple of the disk block size (1024 bytes).  For maximum performance, applications are advised to segregate high-use data and O_DIRECT I/O buffers into separate pages. 

If the file being written is a pipe (or FIFO) and the O_NDELAY flag of the file flag word is set, then a write to a full pipe (or FIFO) will result in zero bytes being written.  Otherwise (O_NDELAY clear), writes to a full pipe (or FIFO) will block until space becomes available. 

RETURN VALUE

Upon successful completion an identifier is returned (if reqid was not specified as −1 the returned identifier is reqid).  Otherwise, −1 is returned and errno is set to indicate the error. 

ERRORS

awrite will fail and the file pointer will remain unchanged if one or more of the following are true:

­[EBADF] Fildes is not a valid file descriptor open for writing. 

­[EPIPE and SIGPIPE signal] An attempt was made to write to a pipe that is not open for reading by any process. 

­[EFBIG] An attempt was made to write a file that exceeds the process’s file size limit or the maximum file size (see ulimit(2)). 

­[EFAULT] Buf, status, or bytecnt points outside the process’s allocated address space. 

­[EINVAL] Reqid is not −1 and reqid is less than 0 or larger than 31. 

­[EINVAL] Reqid is not −1 and an asynchronous I/O operation is already in progress for reqid. 

­[EINVAL] Reqid is −1 and the maximum number of asynchronous I/O operations for the process (32) are pending. 

­[EINTR] A signal was caught during the system call. 

­[EAREQ] No asynchronous request blocks were available to queue the I/O request. 

­[ENOBUFS] There are not enough disk cache buffers available to handle this request. 

­[EINVAL] O_DIRECT was set and either buf was not 4-byte aligned, nbyte was not a multiple of 4 bytes, nbyte was greater than the maximum physical transfer size of the machine, or the file pointer was not aligned to a multiple of the disk block size. 

SEE ALSO

acancel(2), await(2), aread(2), creat(2), dup(2), fcntl(2), ioctl(2), open(2), pipe(2), read(2), signal(2), and write(2). 
CX/UX Programmer’s Guide. 

CX/UX Programmer’s Reference Manual