NAME
fadvise() — file advisory information
SYNOPSIS
#include <sys/fcntl.h>
#include <sys/fadvise.h>
int fadvise(
int fad_fd,
off_t fad_offset,
size_t fad_len,
enum fadv_hints fad_advice,
fad_extparms_t *fad_extparms
);
Parameters
- fad_fd
The open file descriptor to which the fadvise operation applies.
- fad_offset
The beginning of the specified range as a positive, byte offset.
- fad_len
The length of the specified range in bytes.
- fad_advice
Specifies advice to be applied to range (see
fadvise(5)).
- fad_extparms
Pointer to an array of
fad_extparms_t
(see
fadvise(5)).
DESCRIPTION
The
fadvise()
function is used to advise the system about the expected behavior of
the application with respect to the data in the file associated with the
open file descriptor,
fad_fd,
starting at
fad_offset
and continuing for
fad_len
bytes. The specified range need not currently exist in the file.
If
fad_len
is zero, all data following
fad_offset
is specified.
The interpretation of the
fad_offset
and
fad_len
parameters are conditional in that they are ignored in the case of a non-null
fad_extparms
argument. If non-null, the
fad_extparms
argument is used as a pointer to an extended parameter list of type
fad_extparms_t
(see
fadvise(5)).
The extended parameter list allows an application to batch hints over
multiple ranges in one call. The
fad_count
items are processed in list order where, in the case of overlapping ranges,
entries lower on the list of hints take precedence.
It should be noted that the effect of all hints is cumulative for a given
file object. All hints will be removed on processing the last close of the
file object.
The
fad_advice
parameter is used to convey the hint to be applied to the data and may be
one of the following values:
- FADV_CCNUMA
The cc-numa related policies are to be used by VM for physical memory
locality when allocating memory for file I/O. This attribute
applies to the entire file only.
Either one of the following policies can be combined with the
FADV_CCNUMA
command (for further reference see fadvise(5):
- FADV_VM_MEM_INTERLEAVED
Policy specifying that memory for the file will be allocated
from interleaved memory. Interleaved memory is memory allocated
from several locality domains and then striped together. It
should be used if equal-cost allocations are needed.
- FADV_VM_MEM_FIRST_TOUCH
Policy specifying that memory for the file will be allocated
from the locality of the calling CPU. Fast when memory is
available from the closest locality otherwise search by
distance for available memory to allocate.
- FADV_DONTNEED
Specifies that the application will expect that it will not
access the specified range of data in the near future.
- FADV_LARGEPAGE_HINT
The application prefers that large pages be used
by VM in allocating memory for file I/O.
The preferred page size is passed in the
fad_pgsize
alias (see
fadvise(5)).
The page size specified in the
fad_pgsize
alias will be rounded down to the
supported large page size in the system.
If no hint is specified, then
the page size specified in the tunable
vps_pagesize
will be used.
- FADV_NOREUSE
Specifies that the application will expect to access the specified range
of data once and then not reuse it thereafter.
- FADV_NORMAL
Specifies that the application has no advice to give on its behavior
with respect to the specified data. It is the default characteristic
if no advice is given for an open file.
- FADV_RANDOM
Specifies that the application will expect to access the specified
specified range of data in a random order.
- FADV_SEQUENTIAL
Specifies that the application expects to access the specified range of data
sequentially from the lower offsets to higher offsets.
- FADV_SYNC_NONE
No pages associated with given
fd
should be sync'd by VM.
- FADV_SYNC_RDWR
Sets paging policies used by the VM syncer for a
fd
when selecting pages
for page out. This policy indicates that pages associated with file i/o
should be sync'd in a time interval designated by
the
fad_synctime
alias (see
fadvise(5)).
This is default behavior with time interval
set by VM.
- FADV_WILLNEED
Specifies that the application will expect to access the specified
range of data in the near future.
These values will be defined in
<sys/fadvise.h>.
RETURN VALUE
- 0
Successful completion.
- -1
Failure.
errno
is set to indicate the error.
ERRORS
If the
fadvise()
service fails,
errno
is set to one of the following values:
- EBADF
The
fd
argument is not a valid file descriptor.
- EINVAL
The value of
fad_advice
or one of the other input values has been found to be invalid.
- ENOSYS
A designated hint is not supported by the underlying file object.
- ENOTTY
The fadvise operation is not supported by the underlying file system.
- ESPIPE
The
fd
argument is associated with a pipe or FIFO.
If an error is detected while processing a given
fad_advice
hint, an error number will be returned indicating the related error
(see
errno.h).
The error number value, therefore, is independent of
the error numbers listed above.
EXAMPLES
int fd, ret;
struct fad_extparms *my_fad_extparms;
struct fad_parms *fad_plistp;
/*
* Advise the system that we're sequentially accessing the
* 64KB range and will not be re-using the data.
*/
fd = open (argv[1], O_RDONLY|O_CREAT, 0777);
my_fad_extparms = calloc(1, sizeof(int) + 2 * sizeof(struct fad_parms));
my_fad_extparms->fad_count = 2;
/* Initialize the two fad_parms entries. */
fad_plistp = &my_fad_extparms->fad_plist[0];
/* Hint that we're doing sequential access. */
fad_plistp->fad_advice = FADV_SEQUENTIAL;
fad_plistp->FAD_OFFSET = 0;
fad_plistp->FAD_LEN = 65536; /* first 64k range */
fad_plistp++;
/* Advise that we won't re-use the data. */
fad_plistp->fad_advice = FADV_NOREUSE;
fad_plistp->FAD_OFFSET = 0;
fad_plistp->FAD_LEN = 65536; /* first 64k range */
ret = fadvise (fd, 0, 0, 0, my_fad_extparms);
if (ret == -1)
printf ("fadvise() failure errno %d\n", errno);
AUTHOR
fadvise()
was derived by HP from the IEEE POSIX 1003.1-2001 Standard.
STANDARDS CONFORMANCE
fadvise(): POSIX.1 (2001)