Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > F

fadvise(2)

HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

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)

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.