aioread man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

aioread(3scl)							 aioread(3scl)

       aioread - issue an asynchronous read operation

       SCL Miscellaneous Library (, libsolmisc.a)

       #include <sys/asynch.h>

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

       Specifies  the object to which the I/O operation is applied Points to a
       location from which data is read Specifies amount of data  to  transfer
       (bytes) Specifies the offset at which to start the I/O operation Speci‐
       fies the relative position of the offset Pointer to aio_result_t struc‐
       ture in which the asynchronous return value is stored

       The  aioread() function initiates an asynchronous read operation to the
       object specified by the fildes parameter, to  retrieve  bufs  bytes  of
       data into the buffer pointed to by bufp.

       If  the	object	is capable of seeking, the I/O operation starts at the
       position specified with the whence and offset  parameters.  These  have
       the same meaning as with the lseek(2) function. The seek pointer is not
       updated as a result of the I/O operation.

       The result of the completed operation is	 stored	 in  the  aio_result_t
       structure  pointed  to  by the resultp parameter. The aio_return member
       stores the return status of the read operation, and the aio_errno  mem‐
       ber  stores the corresponding errno value. The aio_return member can be
       set to AIO_INPROGRESS prior to calling this function, and  I/O  comple‐
       tion can be detected by polling this member for a change in value.

       It  is  unsafe to access the application I/O buffer (specified with the
       bufp parameter) until the operation is known to have completed.

       Notification of I/O completion can be achieved synchronously  or	 asyn‐
       chronously.   The  former  uses	the  aiowait(3scl) function which will
       cause the thread to wait for an I/O operation to complete. Asynchronous
       notification  is	 enabled  by  installing  a SIGIO signal handler, thus
       causing I/O completion to raise a SIGIO signal. The handler is expected
       to  call the aiowait() function in order to dequeue the completed asyn‐
       chronous operations.  Notification  of  multiple	 completed  operations
       needs  to  be handled, as multiple SIGIO signals are not queued. There‐
       fore the handler should call the	 aiowait()  function  with  a  timeout
       value of 0 to effect polling for a completed request.

       The  result  buffer specified by the resultp parameter can only be used
       by one I/O operation at a time. The result buffer  must	be  "released"
       for reuse by calling the aiowait(3scl) or aiocancel(3scl) functions.

       This  function  is implemented by creating an additional thread to per‐
       form the I/O operation asynchronously by calling the pread(2) function.
       Consequently, there are a number of differences that application devel‐
       opers should be aware of:

       Some error values are returned differently. The Solaris	implementation
       of  this function returns certain errors immediately and therefore does
       not initiate the I/O operation. An example is  EBADF,  returned	if  an
       invalid	file  descriptor is specified. The SCL implementation does not
       detect this problem until the I/O operation is issued by	 the  separate
       I/O  thread,  therefore	the call to aioread() has apparantly been suc‐
       cessful. However, the EBADF error will be reported asynchronously - the
       error code will be written to the result structure. Therefore, applica‐
       tions must ensure that the result structure is tested  for  errors  and
       that  those  errors  may be different to those expected on Solaris.  On
       Tru64 UNIX, it is possible for pread() to be interrupted by  a  signal,
       and  thus  complete  with an error (return value of -1 and errno set to
       EINTR). This means that, unlike Solaris, the asynchronous I/O operation
       could  terminate is such a way. Applications may need to change to pre‐
       vent this by handling EINTR or blocking expected signals while the  I/O
       operation  is  in progress.  The aio_result_t structure defined for the
       SCL implementation is significantly different  from  that  of  Solaris.
       Applications  that  make	 assumptions  about the size of this structure
       should be altered. The two members defined on Solaris are  still	 valid
       for  the SCL variant.  Any defined aio_result_t structures must be ini‐
       tialized to contain zeros before first being used.  On Solaris,	appli‐
       cations	that  use the aioread() function are required to link with the
       libaio library to resolve the function reference. SCL places this func‐
       tion  within  the  libsolmisc  shared  and  static  libraries, thus the
       library option on the build command should be  changed  from  -laio  to
       -lsolmisc.  Tru64  UNIX	already	 supplies a libaio that implements the
       POSIX asynchronous I/O functionality.  There is no "hard" limit to  the
       number  of  asynchronous	 operations that can be outstanding at any one
       time. In practise, the limit is set as the number of threads  that  the
       operating  system  allows a process to create. For applications that do
       not wish to reach this limit (and thereby potentially cause the process
       to hang), ensure that the number of outstanding I/O operations does not
       exceed MAXASYNCHIO.

       Function aioread() returns 0 if successful, otherwise  -1.  The	return
       status  reflects	 the  success of initiating the I/O operation, not the
       completion of it, which is reported in the result structure pointed  to
       by the resultp parameter.

       The  SCL implementation of this function may cause errors to occur that
       could not occur on Solaris. Such errors are written to the  SCL	error‐
       log. In this case the errno reflecting the actual error is mapped to an
       errno that is valid and expected on Solaris. This means	that  applica‐
       tions  testing  for  a  specific set of errors will continue to work as

       The aioread() function can set errno to one of  the  following  values:
       The  maximum  number  of	 outstanding  asynchronous  requests  has been
       exceeded, caused by creating the maximum number	of  threads  permitted
       for  the	 process.  The result structure is currently in use by an out‐
       standing I/O request.

	      An internal implementation error	occurred.  Refer  to  the  SCL
	      errorlog	 for   additional   information	  Insufficient	memory
	      resources available

       When the I/O operation has completed, the result	 structure  aio_return
       member  value  will contain the value returned by the pread() function,
       and the aio_errno member value will be the corresponding	 errno	value.
       Refer to the pread() man page for possible values and meanings.

       Functions: aiocancel(3scl), aiowait(3scl), aiowrite(3scl), pread(2)

       File: scl_error_log(4scl)

       Manual: Solaris Compatibility Library User's Guide


List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net