asio(2)                                                   asio(2)



NAME
     asioread, asiowrite - provide an asynchronous I/O facility

SYNOPSIS
     #include <sys/types.h>
     #include <sys/asio.h>

     int asioread (fildes, buf, nbytes, offset, asiop)
     int fildes;
     char *buf;
     int nbytes;
     off_t offset;
     struct asiostat *asiop;

     int asiowrite (fildes, buf, nbytes, offset, asiop)
     int fildes;
     char *buf;
     int nbytes;
     off_t offset;
     struct asiostat *asiop;

DESCRIPTION
     asioread and asiowrite implement new versions of the read
     and write system calls as part of an asynchronous I/O
     facility.  Both of these calls work like their counterparts
     read and write except for differences noted here.

     The data is transferred to or from the file beginning at the
     position in the file given by offset.  The value of the file
     pointer is not changed by either call.  Outstanding
     asynchronous requests may be initiated and completed in any
     order.

     Both calls use the following structure:

        struct asiostat
        {
           int  asio_error;      /* errno if an error occurred */
           int  asio_count;      /* transfer count; always set even on errors */
           char asio_status;     /* State of request.  ASIOCLEAR, ASIOACTIVE, */
                                 /* ASIODONE, or ASIODONESYNC                 */
           char asio_notifysig;  /* signal to send when I/O is done */
        }

     If the I/O request cannot be queued -1 is returned, errno is
     set to indicate the error (see ``Status Messages and
     Values''), and the asiostat structure remains unchanged.
     For example, if an asynchronous I/O request cannot be queued
     due to resource limitations, -1 is returned and errno is set
     to EAGAIN.  If the request is successfully queued, 0 is
     returned and the asio_status member of asiostat is set to
     ASIOACTIVE.  Values for asio_error and asio_count aren't



March 1993                                                      1

asio(2)                                                   asio(2)



     defined until asio_status is set to ASIODONE or ASIODONESYNC
     upon completion of the request.

     A completion status of ASIODONESYNC means that the request
     completed before the system call returned.  This situation
     can occur when the I/O is done to or from a kernel buffer.
     The completion status ASIOCLEAR is provided for applications
     that wish to be retentive about the value of asio_status or
     that don't want to check the return value of the system call
     before checking asio_status.  Most applications need not
     distinguish between the two completion statuses beyond
     checking for both types when handling completions.

     The asio_notifysig member of the asiostat structure
     determines whether or not the process receives a signal when
     the I/O is complete.  The value of asio_notifysig is a
     signal that is sent upon I/O completion.  If the value of
     asio_notifysig is 0, no signal is sent.  Undefined signal
     values cause a SIGABRT to be sent instead of the supplied
     value.

     More than one I/O request may be completed for each signal
     sent.  This means that the number of signals received may be
     less than the number of requests successfully initiated.
     Accordingly, an application that blocks while waiting for a
     notification signal should always poll each of its active
     asiostat structures whenever it receives a notification
     signal.  It should not attempt to block once for each
     outstanding I/O request.

     The transfer count is meaningful even if there was an error
     because some amount of data may have been transferred before
     the error occurred.

STATUS MESSAGES AND VALUES
     The asioread and asiowrite system calls return 0 on success
     or -1 if an error occurs.

     Upon an error, errno is set to one of the following values:

     EACCES
          The number of active requests per process would have
          exceeded the system-defined limit.

     EAGAIN
          The system does not have enough memory available to
          queue the request.

     EBADF
          The file descriptor is invalid or an attempt was made
          to read (or write) and the file was not open for
          reading (or writing).



2                                                      March 1993

asio(2)                                                   asio(2)



     EFAULT
          The address specified by asiop is outside the caller's
          valid address space.

     EINVAL
          The transfer count in nbytes is less than 0.

     ESRCH
          There are no active asynchronous I/O daemons.

SEE ALSO
     asiowait(2), read(2), write(2)











































March 1993                                                      3