lustre/doc/lfs-ladvise.1

   1 .TH LFS-LADVISE 1 2015-11-30 "Lustre" "Lustre Utilities"
   2 .SH NAME
   3 lfs ladvise \- give file access advices or hints to server.
   4 .SH SYNOPSIS
   5 .br
   6 .B lfs ladvise [--advice|-a ADVICE ] [--background|-b]
   7         \fB[--start|-s START[kMGT]]
   8         \fB{[--end|-e END[kMGT]] | [--length|-l LENGTH[kMGT]]}
   9         \fB<FILE> ...\fR
  10 .br
  11 .SH DESCRIPTION
  12 Give file access advices or hints to Lustre server side, usually OSS. This lfs
  13 utility is simlar to Linux fadvise() system call, except it can forward the
  14 advices from Lustre clients to servers.
  15 .SH OPTIONS
  16 .TP
  17 \fB\-a\fR, \fB\-\-advice\fR=\fIADVICE\fR
  18 Give advice or hint of type \fIADVICE\fR. Advice types are:
  19 .RS 1.2i
  20 .TP
  21 \fBwillread\fR to prefetch data into server cache
  22 .TP
  23 \fBdontneed\fR to cleanup data cache on server
  24 .RE
  25 .TP
  26 \fB\-b\fR, \fB\-\-background
  27 Enable the advices to be sent and handled asynchronously.
  28 .TP
  29 \fB\-s\fR, \fB\-\-start\fR=\fISTART_OFFSET\fR
  30 File range starts from \fISTART_OFFSET\fR.
  31 .TP
  32 \fB\-e\fR, \fB\-\-end\fR=\fIEND_OFFSET\fR
  33 File range ends at (not including) \fIEND_OFFSET\fR.
  34 This option may not be specified at the same time as the -l option.
  35 .TP
  36 \fB\-l\fR, \fB\-\-length\fR=\fILENGTH\fR
  37 File range has length of \fILENGTH\fR. This option may not be specified at the
  38 same time as the -e option.
  39 .SH NOTE
  40 .PP
  41 Typically, the "lfs ladvise" forwards the advice to Lustre servers without
  42 guaranteeing what and when servers will react to the advice. Actions may or
  43 may not triggered when the advices are recieved, depending on the type of the
  44 advice as well as the real-time decision of the affected server-side
  45 components.
  46
  47 A typical usage of ladvise is to enable applications and users with external
  48 knowledge to intervene in server-side cache management. For example, if a
  49 bunch of different clients are doing small random reads of a file, prefetching
  50 pages into OSS cache with big linear reads before the random IO is a net
  51 benefit. Fetching all that data into each client cache with fadvise() may not
  52 be, due to much more data being sent to the client.
  53
  54 The main difference between Linux fadvise() system call and ladvise is that
  55 fadvise() is only a client side mechanism that does not pass the advice to the
  56 filesystem, while ladvise can send advices or hints to Lustre server sides.
  57
  58 .SH EXAMPLES
  59 .TP
  60 .B $ lfs ladvise -a willread -s 0 -e 1048576000 /mnt/lustre/file1
  61 This gives the OST(s) holding the first 1GB of \fB/mnt/lustre/file1\fR a hint
  62 that the first 1GB of the file will be read soon.
  63 .TP
  64 .B $ lfs ladvise -a dontneed -s 0 -e 1048576000 /mnt/lustre/file1
  65 This gives the OST(s) holding the first 1GB of \fB/mnt/lustre/file1\fR a hint
  66 that the first 1GB of file will not be read in the near future, thus the OST(s)
  67 could clear the cache of the file in the memory.
  68 .SH AVAILABILITY
  69 The lfs ladvise command is part of the Lustre filesystem.
  70 .SH SEE ALSO
  71 .BR lfs (1),
  72 .BR fadvise (2),
  73 .BR llapi_ladvise (3),
  74 .BR lustre (7)