directio(3c)

1directio(3C)             Standard C Library Functions             directio(3C)
2
3
4

NAME

6       directio - provide advice to file system
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <sys/fcntl.h>
11
12       int directio(int fildes, int advice);
13
14

DESCRIPTION

16       The  directio()  function  provides  advice  to  the  system  about the
17       expected behavior of the application when accessing  the  data  in  the
18       file  associated  with the open file descriptor fildes. The system uses
19       this information to help optimize accesses  to  the  file's  data.  The
20       directio()  function has no effect on the semantics of the other opera‐
21       tions on the data, though it may affect the performance of other opera‐
22       tions.
23
24
25       The  advice  argument  is  kept per file; the last caller of directio()
26       sets the advice for all applications using  the  file  associated  with
27       fildes.
28
29
30       Values for advice are defined in <sys/fcntl.h>.
31
32       DIRECTIO_OFF    Applications  get  the  default  system  behavior  when
33                       accessing file data.
34
35                       When an application reads data from a file, the data is
36                       first  cached in system memory and then copied into the
37                       application's  buffer  (see  read(2)).  If  the  system
38                       detects  that  the  application is reading sequentially
39                       from a  file,  the  system  will  asynchronously  "read
40                       ahead"  from the file into system memory so the data is
41                       immediately available for the next read(2) operation.
42
43                       When an application writes data into a file,  the  data
44                       is  first cached in system memory and is written to the
45                       device at a later time (see write(2)).  When  possible,
46                       the system increases the performance of write(2) opera‐
47                       tions by cacheing the data in memory pages. The data is
48                       copied  into  system  memory and the write(2) operation
49                       returns immediately to the  application.  The  data  is
50                       later written asynchronously to the device. When possi‐
51                       ble, the cached data is "clustered" into  large  chunks
52                       and written to the device in a single write operation.
53
54                       The  system behavior for  DIRECTIO_OFF can change with‐
55                       out notice.
56
57
58       DIRECTIO_ON     The system behaves as though  the  application  is  not
59                       going  to  reuse  the  file data in the near future. In
60                       other words, the file data is not cached  in  the  sys‐
61                       tem's memory pages.
62
63                       When possible, data is read or written directly between
64                       the application's memory and the device when  the  data
65                       is  accessed with read(2) and write(2) operations. When
66                       such transfers are not possible,  the  system  switches
67                       back  to the default behavior, but just for that opera‐
68                       tion. In general, the transfer  is  possible  when  the
69                       application's  buffer  is aligned on a two-byte (short)
70                       boundary, the offset into the file is on a device  sec‐
71                       tor boundary, and the size of the operation is a multi‐
72                       ple of device sectors.
73
74                       This advisory is ignored while the file associated with
75                       fildes is mapped (see mmap(2)).
76
77                       The system behavior for  DIRECTIO_ON can change without
78                       notice.
79
80

RETURN VALUES

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

ERRORS

86       The directio() function will fail if:
87
88       EBADF     The fildes argument is not a valid open file descriptor.
89
90
91       ENOTTY    The fildes argument is not associated with a file system that
92                 accepts advisory functions.
93
94
95       EINVAL    The value in advice is invalid.
96
97

USAGE

99       Small sequential I/O generally performs best with  DIRECTIO_OFF.
100
101
102       Large sequential I/O generally performs best with  DIRECTIO_ON,  except
103       when a file is sparse or is being extended and is opened with O_SYNC or
104       O_DSYNC (see  open(2)).
105
106
107       The directio() function is supported for the NFS and  UFS  file  system
108       types (see fstyp(1M)).
109

ATTRIBUTES

111       See attributes(5) for descriptions of the following attributes:
112
113
114
115
116       ┌─────────────────────────────┬─────────────────────────────┐
117       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
118       ├─────────────────────────────┼─────────────────────────────┤
119       │MT-Level                     │MT-Safe                      │
120       └─────────────────────────────┴─────────────────────────────┘
121

WARNINGS

127       Switching between  DIRECTIO_OFF and  DIRECTIO_ON can  slow  the  system
128       because  each  switch  to  DIRECTIO_ON might entail flushing the file's
129       data from the system's memory.
130
131
132
133SunOS 5.11                        9 Apr 2003                      directio(3C)