X-Git-Url: https://git.whamcloud.com/?a=blobdiff_plain;f=lustre%2Fdoc%2Flfs-ladvise.1;h=c6a1f0523c1142e6d79ac1e5bff0cb93b74f4015;hb=1148c1f738c388428a9c8f0a5bb6870eac0b1cf9;hp=295658bb81b6f3d90e2465ee8e2f2429e3d02fa5;hpb=f756979d9730333394037f127e75f43910174622;p=fs%2Flustre-release.git

diff --git a/lustre/doc/lfs-ladvise.1 b/lustre/doc/lfs-ladvise.1
index 295658b..c6a1f05 100644
--- a/lustre/doc/lfs-ladvise.1
+++ b/lustre/doc/lfs-ladvise.1
@@ -6,12 +6,16 @@ lfs ladvise \- give file access advices or hints to server.
 .B lfs ladvise [--advice|-a ADVICE ] [--background|-b]
         \fB[--start|-s START[kMGT]]
         \fB{[--end|-e END[kMGT]] | [--length|-l LENGTH[kMGT]]}
+        \fB{[--mode|-m MODE] | [--unset|-u]}
         \fB<FILE> ...\fR
 .br
 .SH DESCRIPTION
 Give file access advices or hints to Lustre server side, usually OSS. This lfs
-utility is simlar to Linux fadvise() system call, except it can forward the
-advices from Lustre clients to servers.
+command is simlar to the Linux
+.BR fadvise64 (2)
+system call and
+.BR posix_fadvise (2),
+except it can forward the hints from Lustre clients to remote servers.
 .SH OPTIONS
 .TP
 \fB\-a\fR, \fB\-\-advice\fR=\fIADVICE\fR
@@ -19,6 +23,11 @@ Give advice or hint of type \fIADVICE\fR. Advice types are:
 .RS 1.2i
 .TP
 \fBwillread\fR to prefetch data into server cache
+.TP
+\fBdontneed\fR to cleanup data cache on server
+.TP
+\fBlockahead\fR to request a lock on a specified extent of a file
+\fBlocknoexpand\fR to disable server side lock expansion for a file
 .RE
 .TP
 \fB\-b\fR, \fB\-\-background
@@ -34,20 +43,29 @@ This option may not be specified at the same time as the -l option.
 \fB\-l\fR, \fB\-\-length\fR=\fILENGTH\fR
 File range has length of \fILENGTH\fR. This option may not be specified at the
 same time as the -e option.
+.TP
+\fB\-m\fR, \fB\-\-mode\fR=\fIMODE\fR
+Specify the lock \fIMODE\fR. This option is only valid with lockahead
+advice.  Valid modes are: READ, WRITE
+.TP
+\fB\-u\fR, \fB\-\-unset\fR=\fIUNSET\fR
+Unset the previous advice.  Currently only valid with locknoexpand advice.
 .SH NOTE
 .PP
-Typically, the "lfs ladvise" forwards the advice to Lustre servers without
-guaranteeing what and when servers will react to the advice. Actions may or
-may not triggered when the advices are recieved, depending on the type of the
-advice as well as the real-time decision of the affected server-side
-components.
+Typically,
+.B 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 recieved, 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
-bunch of different clients are doing small random reads of a file, prefetching
+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 all that data into each client cache with fadvise() may not
-be, due to much more data being sent to the client.
+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
@@ -55,13 +73,27 @@ filesystem, while ladvise can send advices or hints to Lustre server sides.
 
 .SH EXAMPLES
 .TP
-.B $ lfs ladvise -a willread -s 0 -e 1048576000 /mnt/lustre/file1
+.B $ lfs ladvise -a willread -s 0 -e 1024M /mnt/lustre/file1
+This gives the OST(s) holding the first 1GB of \fB/mnt/lustre/file1\fR a hint
+that the first 1GB of that file will be read soon.
+.TP
+.B $ lfs ladvise -a dontneed -s 0 -e 1G /mnt/lustre/file1
 This gives the OST(s) holding the first 1GB of \fB/mnt/lustre/file1\fR a hint
-that the first 1GB of the file will be read soon.
+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.
+.B $ lfs ladvise -a lockahead -s 0 -e 1048576 -m READ /mnt/lustre/file1
+Request a read lock on the first 1 MiB of /mnt/lustre/file1.
+.B $ $ lfs ladvise -a lockahead -s 0 -e 4096 -m WRITE ./file1
+Request a write lock on the first 4KiB of /mnt/lustre/file1.
+.B $ $ lfs ladvise -a locknoexpand ./file1
+Set disable lock expansion on ./file1
+.B $ $ lfs ladvise -a locknoexpand -u ./file1
+Unset disable lock expansion on ./file1
 .SH AVAILABILITY
 The lfs ladvise command is part of the Lustre filesystem.
 .SH SEE ALSO
 .BR lfs (1),
-.BR fadvise (2),
+.BR fadvise64 (2),
+.BR posix_fadvise (2),
 .BR llapi_ladvise (3),
 .BR lustre (7)