posix_fadvise(2)

NAME

posix_fadvise(), posix_fadvise64() — file advisory information

SYNOPSIS

#include <sys/fcntl.h> 

int posix_fadvise( 
int fd,
off_t offset,
off_t len,
int advice
); 

int posix_fadvise64( 
int fd,
off_t offset,
off_t len,
int advice
); 

Parameters

fd: The open file descriptor to which the fadvise operation applies.
offset: The begining of the specified range as a positive, byte offset.
len: The length of the specified range in bytes.
advice: Specifies advice to be applied to range.

DESCRIPTION

The posix_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, fd, starting at offset and continuing for len bytes. The specified range need not currently exist in the file. If len is zero, all data following offset is specified.

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 posix_fadvise64() function may be used for large file access by a 32-bit application built with _FILE_OFFSET_BITS set to 64.

The advice parameter is used to convey the hint to be applied to the data and may be one of the following values:

POSIX_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.
POSIX_FADV_SEQUENTIAL: Specifies that the application expects to access the specified range of data sequentially from the lower offsets to higher offsets.
POSIX_FADV_RANDOM: Specifies that the application will expect to access the specified specified range of data in a random order.
POSIX_FADV_WILLNEED: Specifies that the application will expect to access the specified range of data in the near future.
POSIX_FADV_DONTNEED: Specifies that the application will expect that it will not access the specified range of data in the near future.
POSIX_FADV_NOREUSE: Specifies that the application will expect to access the specified range of data once and then not reuse it thereafter.

These values will be defined in <sys/fcntl.h>.

RETURN VALUE

0: Successful completion.
-1: Failure. errno is set to indicate the error.

ERRORS

If the posix_fadvise() service fails, errno is set to one of the following values:

EBADF: The fd argument is not a valid file descriptor.
ESPIPE: The fd argument is associated with a pipe or FIFO.
ENOTTY: The posix_fadvise operation is not supported by the underlying file system.
EINVAL: The value of 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.

EXAMPLES

int fd, ret; 

/* 
 * 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); 
  

  
ret = posix_fadvise (fd, 0, 0, 0, FADV_SEQUENTIAL); 
  
if (ret == -1) { 
    printf ("fadvise() failure errno %d\n", errno); 
    exit; 
} 
  
ret = posix_fadvise (fd, 0, 0, 0, FADV_NOREUSE); 
  
if (ret == -1) 
    printf ("fadvise() failure errno %d\n", errno); 
    exit; 
} 

AUTHOR

posix_fadvise() was derived by HP from the IEEE POSIX 1003.1-2001 Standard.

STANDARDS CONFORMANCE

posix_fadvise(): POSIX.1 (2001)