directio(3C)

NAME

     directio - provide advice to file system

SYNOPSIS

     #include <sys/types.h>
     #include <sys/fcntl.h>

     int directio(int fildes, int advice);

DESCRIPTION

     The directio() function provides advice to the system  about
     the  expected behavior of the application when accessing the
     data in the file associated with the  open  file  descriptor
     fildes.  The  system  uses this information to help optimize
     accesses to the file's data.  The directio() function has no
     effect on the semantics of the other operations on the data,
     though it may affect the performance of other operations.

     The advice argument is kept per file;  the  last  caller  of
     directio()  sets  the  advice for all applications using the
     file associated with fildes.

     Values for advice are defined in <sys/fcntl.h>.

     DIRECTIO_OFF
           Applications get  the  default  system  behavior  when
           accessing file data.

           When an application reads data from a file,  the  data
           is  first cached in system memory and then copied into
           the application's buffer (see read(2)). If the  system
           detects  that  the application is reading sequentially
           from a file,  the  system  will  asynchronously  "read
           ahead" from the file into system memory so the data is
           immediately available for the next read(2) operation.

           When an application writes data into a file, the  data
           is first cached in system memory and is written to the
           device at a later time (see write(2)). When  possible,
           the  system  increases  the  performance  of  write(2)
           operations by cacheing the data in memory  pages.  The
           data  is  copied  into  system memory and the write(2)
           operation returns immediately to the application.  The
           data  is  later  written asynchronously to the device.
           When possible, the cached  data  is  "clustered"  into
           large  chunks  and  written  to the device in a single
           write operation.

           The  system  behavior  for   DIRECTIO_OFF  can  change
           without notice.

     DIRECTIO_ON
           The system behaves as though the  application  is  not
           going  to  reuse  the file data in the near future. In
           other words, the  file  data  is  not  cached  in  the
           system's memory pages.

           When  possible,  data  is  read  or  written  directly
           between  the  application's memory and the device when
           the data is accessed with read(2) and write(2)  opera-
           tions.  When such transfers are not possible, the sys-
           tem switches back to the default  behavior,  but  just
           for  that operation.  In general, the transfer is pos-
           sible when the application's buffer is  aligned  on  a
           two-byte (short) boundary, the offset into the file is
           on a device sector  boundary,  and  the  size  of  the
           operation is a multiple of device sectors.

           This advisory is ignored  while  the  file  associated
           with fildes is mapped (see mmap(2)).

           The  system  behavior  for   DIRECTIO_ON  can   change
           without notice.

RETURN VALUES

     Upon successful completion, directio() returns 0. Otherwise,
     it returns -1 and sets errno to indicate the error.

ERRORS

     The directio() function will fail if:

     EBADF The fildes argument is not a valid open file  descrip-
           tor.

     ENOTTY
           The fildes argument is not associated with a file sys-
           tem that accepts advisory functions.

     EINVAL
           The value in advice is invalid.

USAGE

     Small  sequential   I/O   generally   performs   best   with
     DIRECTIO_OFF.

     Large  sequential   I/O   generally   performs   best   with
     DIRECTIO_ON,  except  when  a  file  is  sparse  or is being
     extended  and  is  opened  with  O_SYNC  or   O_DSYNC   (see
     open(2)).

     The directio() function is supported for the ufs file system
     type (see fstyp(1M)).

ATTRIBUTES

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

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

SEE ALSO

     fstyp(1M),  mmap(2),  open(2),  read(2),  write(2),   attri-
     butes(5), fcntl(3HEAD)

WARNINGS

     Switching between  DIRECTIO_OFF and   DIRECTIO_ON  can  slow
     the  system  because each switch to DIRECTIO_ON might entail
     flushing the file's data from the system's memory.