Manual Pages for UNIX Operating System command usage for man aiowrite

Standard C Library Functions                          aioread(3C)



NAME
     aioread, aiowrite - read or write  asynchronous  I/O  opera-
     tions

SYNOPSIS
     #include 
     #include 

     int aioread(int fildes, char *bufp, int bufs, off_t offset,
          int whence, aio_result_t *resultp);


     int aiowrite(int fildes, const char *bufp, int bufs, off_t offset,
          int whence, aio_result_t *resultp);


DESCRIPTION
     The aioread() function initiates  one  asynchronous  read(2)
     and returns control to the calling program. The read contin-
     ues concurrently with other  activity  of  the  process.  An
     attempt  is  made to read bufs bytes of data from the object
     referenced by the descriptor fildes into the buffer  pointed
     to by bufp.


     The aiowrite() function initiates one asynchronous  write(2)
     and  returns  control to the calling program. The write con-
     tinues concurrently with other activity of the  process.  An
     attempt  is made to write bufs bytes of data from the buffer
     pointed to by bufp to the object referenced by the  descrip-
     tor fildes.


     On objects capable of seeking, the I/O operation  starts  at
     the  position  specified by whence and offset. These parame-
     ters have the same meaning as the  corresponding  parameters
     to the llseek(2) function. On objects not capable of seeking
     the I/O operation always start from the current position and
     the  parameters  whence  and  offset  are  ignored. The seek
     pointer for objects capable of seeking  is  not  updated  by
     aioread()  or aiowrite(). Sequential asynchronous operations
     on these devices must be managed by  the  application  using
     the whence and offset parameters.


     The result of the asynchronous operation is  stored  in  the
     structure pointed to by resultp:

       int aio_return;          /* return value of read() or write() */
       int aio_errno;          /* value of errno for read() or write() */





SunOS 5.11           Last change: 5 Feb 2008                    1






Standard C Library Functions                          aioread(3C)



     Upon  completion  of  the  operation  both  aio_return   and
     aio_errno  are  set  to reflect the result of the operation.
     Since AIO_INPROGRESS is not a value used by the system,  the
     client   can  detect  a  change  in  state  by  initializing
     aio_return to this value.


     The application-supplied buffer bufp should  not  be  refer-
     enced  by the application until after the operation has com-
     pleted. While the operation is in progress, this  buffer  is
     in use by the operating system.


     Notification  of  the  completion  of  an  asynchronous  I/O
     operation   can   be   obtained  synchronously  through  the
     aiowait(3C) function, or asynchronously by installing a sig-
     nal handler for the SIGIO signal.  Asynchronous notification
     is accomplished by sending the process a SIGIO signal. If  a
     signal  handler is not installed for the SIGIO signal, asyn-
     chronous notification is  disabled.  The  delivery  of  this
     instance  of  the  SIGIO signal is reliable in that a signal
     delivered while the handler is executing is not lost. If the
     client  ensures that aiowait() returns nothing (using a pol-
     ling timeout) before returning from the signal  handler,  no
     asynchronous I/O notifications are lost. The aiowait() func-
     tion is the only way to dequeue  an  asynchronous  notifica-
     tion.  The SIGIO signal can have several meanings simultane-
     ously. For example, it can signify that  a  descriptor  gen-
     erated   SIGIO  and  an  asynchronous  operation  completed.
     Further,  issuing  an  asynchronous   request   successfully
     guarantees that space exists to queue the completion notifi-
     cation.


     The close(2), exit(2) and execve(2)) functions  block  until
     all  pending  asynchronous I/O operations can be canceled by
     the system.


     It is an error to use the same result buffer  in  more  than
     one outstanding request. These structures can be reused only
     after the system has completed the operation.

RETURN VALUES
     Upon successful completion,  aioread() and aiowrite() return
     0.  Upon failure, aioread() and aiowrite() return -1 and set
     errno to indicate the error.

ERRORS
     The aioread() and aiowrite() functions will fail if:





SunOS 5.11           Last change: 5 Feb 2008                    2






Standard C Library Functions                          aioread(3C)



     EAGAIN    The number of asynchronous requests that the  sys-
               tem can handle at any one time has been exceeded


     EBADF     The fildes argument is not a valid file descriptor
               open for reading.


     EFAULT    At least one of  bufp  or  resultp  points  to  an
               address  outside the address space of the request-
               ing process. This condition is  reported  only  if
               detected by the application process.


     EINVAL    The resultp argument is currently being used by an
               outstanding asynchronous request.


     EINVAL    The offset argument is not a valid offset for this
               file system type.


     ENOMEM    Memory  resources  are  unavailable  to   initiate
               request.


USAGE
     The aioread() and  aiowrite()  functions  have  transitional
     interfaces for 64-bit file offsets.  See lf64(5).

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | Safe                        |
    |_____________________________|_____________________________|


SEE ALSO
     close(2), execve(2), exit(2), llseek(2), lseek(2),  open(2),
     read(2),   write(2),   aiocancel(3C),   aiowait(3C),  attri-
     butes(5), lf64(5)








SunOS 5.11           Last change: 5 Feb 2008                    3