fadvise(2)

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)