LFS-LADVISE(1)

NAME
lfs-ladvise - give file access advices or hints to server.

SYNOPSIS
lfs ladvise [--advice|-a ADVICE] [--background|-b] [--start|-s START [kMGT]] {[--end|-e END [kMGT]] | [--length|-l LENGTH [kMGT]]} {[--mode|-m MODE] | [--unset|-u]} FILE ...

DESCRIPTION
Give file access advices or hints to Lustre server side, usually OSS. This lfs command is similar to the Linux fadvise64(2) system call and posix_fadvise(2), except it can forward the hints from Lustre clients to remote servers.

OPTIONS

-a, --advice=ADVICE
    Give advice or hint of type ADVICE Advice types are:

willread
    to prefetch data into server cache

dontneed
    to cleanup data cache on server

lockahead
    to request a lock on a specified extent of a file

locknoexpand
    to disable server side lock expansion for a file

-b, --background
    Enable the advices to be sent and handled asynchronously.

-s, --start=START_OFFSET
    File range starts from START_OFFSET.

-e, --end=END_OFFSET
    File range ends at (not including) END_OFFSET. This option may not be specified at the same time as the -l option.

-l, --length=LENGTH
    File range has length of LENGTH. This option may not be specified at the same time as the -e option.

-m, --mode=MODE
    Specify the lock MODE. This option is only valid with lockahead advice. Valid modes are: READ, WRITE

-u, --unset=UNSET
    Unset the previous advice. Currently only valid with locknoexpand advice.

NOTES
Typically, lfs ladvise forwards the advice to Lustre servers without guaranteeing how and when servers will react to the advice. Actions may or may not be triggered when the advices are received, depending on the type of the advice, whether the backing filesystem type supports that advice, as well as the real-time decision of the affected server-side components.

A typical usage of ladvise is to enable applications and users with external knowledge to intervene in server-side cache management. For example, if a group of different clients are doing small random reads of a file, prefetching pages into OSS cache with big linear reads before the random IO is a net benefit. Fetching that data into each client cache with fadvise() may not be a benefit if any individual client only reads a subset of the file.

The main difference between Linux fadvise() system call and ladvise is that fadvise() is only a client side mechanism that does not pass the advice to the filesystem, while ladvise can send advices or hints to Lustre server sides.

EXAMPLES
Gives the OST(s) holding the first 1GB of mnt/lustre/file1 a hint that the first 1GB of that file will be read soon:
        # lfs ladvise -a willread -s 0 -e 1024M /mnt/lustre/file1

Gives the OST(s) holding the first 1GB of /mnt/lustre/file1 a hint that the first 1GB of file will not be read in the near future, thus the OST(s) could clear the cache of that file in the memory:
        # lfs ladvise -a dontneed -s 0 -e 1G /mnt/lustre/file1

Request a read lock on the first 1 MiB of /mnt/lustre/file1:
        # lfs ladvise -a lockahead -s 0 -e 1048576 -m READ /mnt/lustre/file1
Request a write lock on the first 4KiB of /mnt/lustre/file1:
        # lfs ladvise -a lockahead -s 0 -e 4096 -m WRITE ./file1
Set disable lock expansion on ./file1:
        # lfs ladvise -a locknoexpand ./file1
Unset disable lock expansion on ./file1:
        # lfs ladvise -a locknoexpand -u ./file1

AVAILABILITY
The lfs ladvise command is part of the lustre(7) filesystem package since release 2.9.0

SEE ALSO
lfs(1), fadvise64(2), posix_fadvise(2), llapi_ladvise(3), lustre(7)