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{[--mode|-m MODE] | [--unset|-u]}
  10         \fB<FILE> ...\fR
  11 .br
  12 .SH DESCRIPTION
  13 Give file access advices or hints to Lustre server side, usually OSS. This lfs
  14 command is simlar to the Linux
  15 .BR fadvise64 (2)
  16 system call and
  17 .BR posix_fadvise (2),
  18 except it can forward the hints from Lustre clients to remote servers.
  19 .SH OPTIONS
  20 .TP
  21 \fB\-a\fR, \fB\-\-advice\fR=\fIADVICE\fR
  22 Give advice or hint of type \fIADVICE\fR. Advice types are:
  23 .RS 1.2i
  24 .TP
  25 \fBwillread\fR to prefetch data into server cache
  26 .TP
  27 \fBdontneed\fR to cleanup data cache on server
  28 .TP
  29 \fBlockahead\fR to request a lock on a specified extent of a file
  30 \fBlocknoexpand\fR to disable server side lock expansion for a file
  31 .RE
  32 .TP
  33 \fB\-b\fR, \fB\-\-background
  34 Enable the advices to be sent and handled asynchronously.
  35 .TP
  36 \fB\-s\fR, \fB\-\-start\fR=\fISTART_OFFSET\fR
  37 File range starts from \fISTART_OFFSET\fR.
  38 .TP
  39 \fB\-e\fR, \fB\-\-end\fR=\fIEND_OFFSET\fR
  40 File range ends at (not including) \fIEND_OFFSET\fR.
  41 This option may not be specified at the same time as the -l option.
  42 .TP
  43 \fB\-l\fR, \fB\-\-length\fR=\fILENGTH\fR
  44 File range has length of \fILENGTH\fR. This option may not be specified at the
  45 same time as the -e option.
  46 .TP
  47 \fB\-m\fR, \fB\-\-mode\fR=\fIMODE\fR
  48 Specify the lock \fIMODE\fR. This option is only valid with lockahead
  49 advice.  Valid modes are: READ, WRITE
  50 .TP
  51 \fB\-u\fR, \fB\-\-unset\fR=\fIUNSET\fR
  52 Unset the previous advice.  Currently only valid with locknoexpand advice.
  53 .SH NOTE
  54 .PP
  55 Typically,
  56 .B lfs ladvise
  57 forwards the advice to Lustre servers without
  58 guaranteeing how and when servers will react to the advice. Actions may or
  59 may not be triggered when the advices are recieved, depending on the type of
  60 the advice, whether the backing filesystem type supports that advice, as well
  61 as the real-time decision of the affected server-side components.
  62
  63 A typical usage of ladvise is to enable applications and users with external
  64 knowledge to intervene in server-side cache management. For example, if a
  65 group of different clients are doing small random reads of a file, prefetching
  66 pages into OSS cache with big linear reads before the random IO is a net
  67 benefit. Fetching that data into each client cache with fadvise() may not
  68 be a benefit if any individual client only reads a subset of the file.
  69
  70 The main difference between Linux fadvise() system call and ladvise is that
  71 fadvise() is only a client side mechanism that does not pass the advice to the
  72 filesystem, while ladvise can send advices or hints to Lustre server sides.
  73
  74 .SH EXAMPLES
  75 .TP
  76 .B $ lfs ladvise -a willread -s 0 -e 1024M /mnt/lustre/file1
  77 This gives the OST(s) holding the first 1GB of \fB/mnt/lustre/file1\fR a hint
  78 that the first 1GB of that file will be read soon.
  79 .TP
  80 .B $ lfs ladvise -a dontneed -s 0 -e 1G /mnt/lustre/file1
  81 This gives the OST(s) holding the first 1GB of \fB/mnt/lustre/file1\fR a hint
  82 that the first 1GB of file will not be read in the near future, thus the OST(s)
  83 could clear the cache of that file in the memory.
  84 .B $ lfs ladvise -a lockahead -s 0 -e 1048576 -m READ /mnt/lustre/file1
  85 Request a read lock on the first 1 MiB of /mnt/lustre/file1.
  86 .B $ $ lfs ladvise -a lockahead -s 0 -e 4096 -m WRITE ./file1
  87 Request a write lock on the first 4KiB of /mnt/lustre/file1.
  88 .B $ $ lfs ladvise -a locknoexpand ./file1
  89 Set disable lock expansion on ./file1
  90 .B $ $ lfs ladvise -a locknoexpand -u ./file1
  91 Unset disable lock expansion on ./file1
  92 .SH AVAILABILITY
  93 The lfs ladvise command is part of the Lustre filesystem.
  94 .SH SEE ALSO
  95 .BR lfs (1),
  96 .BR fadvise64 (2),
  97 .BR posix_fadvise (2),
  98 .BR llapi_ladvise (3),
  99 .BR lustre (7)