LU-10810 clio: SEEK_HOLE/SEEK_DATA on client side

[fs/lustre-release.git] / lustre / doc / lfs-find.1

diff --git a/lustre/doc/lfs-find.1 b/lustre/doc/lfs-find.1
index 4486b92..063f6d9 100644 (file)
--- a/lustre/doc/lfs-find.1
+++ b/lustre/doc/lfs-find.1
@@ -5,21 +5,28 @@ lfs-find \- Lustre client utility to list files with specific attributes
 .B lfs find \fR<\fIdirectory\fR|\fIfilename \fR...>
       [[\fB!\fR] \fB--atime\fR|\fB-A\fR [\fB-+\fR]\fIn[smhdwy]\fR]
 [[\fB!\fR] \fB--blocks\fR|\fB-b\fR [\fB+-\fR]\fIn\fR]
 .B lfs find \fR<\fIdirectory\fR|\fIfilename \fR...>
       [[\fB!\fR] \fB--atime\fR|\fB-A\fR [\fB-+\fR]\fIn[smhdwy]\fR]
 [[\fB!\fR] \fB--blocks\fR|\fB-b\fR [\fB+-\fR]\fIn\fR]

+      [[\fB!\fR] \fB--btime\fR|\fB--Btime\fR|\fB-B\fR [\fB+-\fR]\fIn[smhdwy]\fR]

       [[\fB!\fR] \fB--ctime\fR|\fB-C\fR [\fB+-\fR]\fIn[smhdwy]\fR]
       [[\fB!\fR] \fB--component-count|\fB--comp-count\fR [\fB+-\fR]\fIn\fR]
       [[\fB!\fR] \fB--component-end|\fB--comp-end\fR|\fB-E\fR [\fB+-\fR]\fIn\fR[\fBKMGTPE\fR]]
       [[\fB!\fR] \fB--component-flags|\fB--comp-flags\fR <[^]\fIflag\fB,\fR...>]
       [[\fB!\fR] \fB--component-start|\fB--comp-start\fR [\fB+-\fR]\fIn\fR[\fBKMGTPE\fR]]
       [[\fB!\fR] \fB--ctime\fR|\fB-C\fR [\fB+-\fR]\fIn[smhdwy]\fR]
       [[\fB!\fR] \fB--component-count|\fB--comp-count\fR [\fB+-\fR]\fIn\fR]
       [[\fB!\fR] \fB--component-end|\fB--comp-end\fR|\fB-E\fR [\fB+-\fR]\fIn\fR[\fBKMGTPE\fR]]
       [[\fB!\fR] \fB--component-flags|\fB--comp-flags\fR <[^]\fIflag\fB,\fR...>]
       [[\fB!\fR] \fB--component-start|\fB--comp-start\fR [\fB+-\fR]\fIn\fR[\fBKMGTPE\fR]]

+      [[\fB!\fR] \fB--extension-size|\fB-z\fR [\fB+-\fR]\fIn\fR[\fBKMG\fR]]

       [[\fB!\fR] \fB--gid\fR|\fB-g\fR|\fB--group\fR|\fB-G\fR <\fIgname\fR>|<\fIgid\fR>]
       [[\fB!\fR] \fB--layout\fR|\fB-L mdt\fR,\fBraid0\fR,\fBreleased\fR]
       [[\fB!\fR] \fB--gid\fR|\fB-g\fR|\fB--group\fR|\fB-G\fR <\fIgname\fR>|<\fIgid\fR>]
       [[\fB!\fR] \fB--layout\fR|\fB-L mdt\fR,\fBraid0\fR,\fBreleased\fR]

-[\fB--maxdepth\fR|\fB-D\fI n\fR]
-      [[\fB!\fR] \fB--mdt\fR|\fB--mdt-index\fR|\fB-m\fR <\fIuuid\fR|\fIindex\fR,...>]
+      [[\fB!\fR] \fB--foreign\fR [<\fItype\fR>]]
+[[\fB!\fR] \fB--gid\fR|\fB-g\fR|\fB--group\fR|\fB-G\fR <\fIgname\fR>|<\fIgid\fR>]
+      [[\fB!\fR] \fB--layout\fR|\fB-L mdt\fR,\fBraid0\fR,\fBreleased\fR]
+[\fB--lazy\fR]
+      [\fB--maxdepth\fR|\fB-D\fI n\fR]
+[[\fB!\fR] \fB--mdt\fR|\fB--mdt-index\fR|\fB-m\fR <\fIuuid\fR|\fIindex\fR,...>]

       [[\fB!\fR] \fB--mdt-count\fR|\fB-T\fR [\fB+-\fR]\fIn\fR]
 [[\fB!\fR] \fB--mdt-hash\fR|\fB-H <\fIhashtype\fR>]
       [[\fB!\fR] \fB--mirror-count|\fB-N\fR [\fB+-\fR]\fIn\fR]
 [[\fB!\fR] \fB--mirror-state\fR <[^]\fIstate\fR>]
       [[\fB!\fR] \fB--mtime\fR|\fB-M\fR [\fB-+\fR]\fIn[smhdwy]\fR]
 [[\fB!\fR] \fB--name\fR|\fB-n <\fIpattern\fR>]
       [[\fB!\fR] \fB--mdt-count\fR|\fB-T\fR [\fB+-\fR]\fIn\fR]
 [[\fB!\fR] \fB--mdt-hash\fR|\fB-H <\fIhashtype\fR>]
       [[\fB!\fR] \fB--mirror-count|\fB-N\fR [\fB+-\fR]\fIn\fR]
 [[\fB!\fR] \fB--mirror-state\fR <[^]\fIstate\fR>]
       [[\fB!\fR] \fB--mtime\fR|\fB-M\fR [\fB-+\fR]\fIn[smhdwy]\fR]
 [[\fB!\fR] \fB--name\fR|\fB-n <\fIpattern\fR>]

+      [[\fB!\fR] \fB--newer\fR[\fBXY\fR] <\fIreference\fR>]

       [[\fB!\fR] \fB--ost\fR|\fB-O\fR <\fIindex\fR,...>]
 [[\fB!\fR] \fB--pool\fR <\fIpool\fR>]
 [\fB--print\fR|\fB-P\fR]
       [[\fB!\fR] \fB--ost\fR|\fB-O\fR <\fIindex\fR,...>]
 [[\fB!\fR] \fB--pool\fR <\fIpool\fR>]
 [\fB--print\fR|\fB-P\fR]


@@ -47,9 +54,9 @@ OST and MDT location, and composite layout attributes.
 .BR --atime | -A
 File was last accessed \fIn\fR*24 hours ago (if no units are given),
 or \fIn\fR*\fBs\fReconds, \fBm\fRinutes, \fBh\fRours, \fBd\fRays,
 .BR --atime | -A
 File was last accessed \fIn\fR*24 hours ago (if no units are given),
 or \fIn\fR*\fBs\fReconds, \fBm\fRinutes, \fBh\fRours, \fBd\fRays,

-\fBw\fReeks, or \fBy\fRears ago within a margin of error of 24h,
-or smaller if a unit is specified.  Multiple units can be specified,
-for example \fB8h20m\fR is equivalent to \fB500m\fR.  If multipe units
+\fBw\fReeks, or \fBy\fRears ago within a margin of error of 24h
+if no unit is specified.  Multiple units can be specified,
+for example \fB8h20m\fR is equivalent to \fB500m\fR.  If multiple units

 are specified, the margin of error is based on the smallest unit used, so
 .B -atime 3d
 has a margin of error of one day, while
 are specified, the margin of error is based on the smallest unit used, so
 .B -atime 3d
 has a margin of error of one day, while


@@ -61,6 +68,11 @@ Blocks allocated by the file is \fIn\fR Kibibytes (if no units are given),
 \fIn\fR 512-byte \fBb\fRlocks, or \fBK\fRibi-, \fBM\fRebi-, \fBG\fRibi-,
 \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-bytes if that suffix is given.
 .TP
 \fIn\fR 512-byte \fBb\fRlocks, or \fBK\fRibi-, \fBM\fRebi-, \fBG\fRibi-,
 \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-bytes if that suffix is given.
 .TP

+.BR --btime | --Btime | -B
+File was created \fIn\fR*24 hours ago, see
+--atime
+for full details and options.
+.TP

 .BR --ctime | -C
 File's status was last changed \fIn\fR*24 hours ago, see
 --atime
 .BR --ctime | -C
 File's status was last changed \fIn\fR*24 hours ago, see
 --atime


@@ -101,13 +113,22 @@ local on the network to clients.
 .BR --component-start | --comp-start
 The file has component start offset \fIn\fR (in bytes) for any component.
 .TP
 .BR --component-start | --comp-start
 The file has component start offset \fIn\fR (in bytes) for any component.
 .TP

+.BR --foreign
+File has a foreign (non-Lustre/free format) layout and is of the given
+.IR type ,
+if specified.  Presently only
+.B none
+or
+.B daos
+are defined types, though 32-bit numeric types can also be used.
+.TP

 .BR --gid | -g
 File has specified numeric group ID.
 .TP
 .BR --group | -G
 File belongs to specified group, numeric group ID allowed.
 .TP
 .BR --gid | -g
 File has specified numeric group ID.
 .TP
 .BR --group | -G
 File belongs to specified group, numeric group ID allowed.
 .TP

-.BR --layout
+.BR --layout | -L

 File has a layout of the given type, one of:
 .RS 1.2i
 .TP
 File has a layout of the given type, one of:
 .RS 1.2i
 .TP


@@ -121,6 +142,9 @@ HSM-archived files that are not resident in the filesystem.
 Files that have the first data component on an MDT.
 .RE
 .TP
 Files that have the first data component on an MDT.
 .RE
 .TP

+.BR --lazy
+Use file size and blocks from MDT, if available, to avoid extra RPCs.
+.TP

 .BR --maxdepth
 Limits find to decend at most \fIn\fR levels of directory tree.
 .TP
 .BR --maxdepth
 Limits find to decend at most \fIn\fR levels of directory tree.
 .TP


@@ -131,6 +155,10 @@ File or directory inode is located on the specified MDT(s).
 DNE striped directory uses the given filename hashing function, one of:
 .RS 1.2i
 .TP
 DNE striped directory uses the given filename hashing function, one of:
 .RS 1.2i
 .TP

+.B crush
+The CRUSH consistent hash function, added in Lustre 2.14, minimizes
+entry migration if the directory stripe count changes during migration.
+.TP

 .B fnv_1a_64
 The Fowler\-Noll\-Vo hash function, which is a simple and efficient hash.
 .TP
 .B fnv_1a_64
 The Fowler\-Noll\-Vo hash function, which is a simple and efficient hash.
 .TP


@@ -178,6 +206,47 @@ standard
 .BR glob (7)
 file name regular expressions and wildcards.
 .TP
 .BR glob (7)
 file name regular expressions and wildcards.
 .TP

+.BR --newer [ XY "] " \fIreference
+Succeeds if timestamp \fIX\fR of the file being considered is newer
+than timestamp \fIY\fR of the file
+.IR reference .
+The letters \fIX\fR and \fIY\fR can be any of the following letters:
+
+.TS
+ll
+ll
+ll
+ll
+llw(2i).
+a       The access time of the file \fIreference\fR
+b|B     The birth time of the file \fIreference\fR
+c       The inode status change time of \fIreference\fR
+m       The modification time of the file \fIreference\fR
+t       \fIreference\fR is interpreted directly as a time
+.TE
+
+Some combinations are invalid; for example, it is invalid for
+.I X
+to be
+.IR t .
+Specifying
+.B -newer
+is equivalent to
+.BR -newermm .
+When
+.IR reference
+is interpreted directly as a time, currently it must be in one of the
+following formats: "%Y-%m-%d %H:%M:%S", "%Y-%m-%d %H:%M", "%Y-%m-%d",
+"%H:%M:%S", "%H:%M", to represent year, month, day, hour, minute, seconds,
+with unspecified times at the start of that minute or day, unspecified dates
+being "today", and "@%s" or "%s" the seconds since the Unix epoch (see
+.BR strftime (3)
+for details of the time formats).  Otherwise, it will report an error.
+If you try to use the birth time of a reference file, and the birth
+time cannot be determined, a fatal error message results.  If you
+specify a test which refers to the birth time of files being examined,
+this test will fail for any files where the birth time is unknown.
+.TP

 .BR --ost | -O
 File has an object on the specified OST(s).  The OST names can be specified
 using the whole OST target name, or just the OST index number. If multiple
 .BR --ost | -O
 File has an object on the specified OST(s).  The OST names can be specified
 using the whole OST target name, or just the OST index number. If multiple


@@ -191,7 +260,6 @@ and replacement using
 Layout was created with the specified
 .I pool
 name.  For composite files, this may match the pool of any component.
 Layout was created with the specified
 .I pool
 name.  For composite files, this may match the pool of any component.

-.TP

 .BR --print | -P
 Prints the file or directory name to standard output if it matches
 all specified parameters, one file per line with a trailing linefeed.
 .BR --print | -P
 Prints the file or directory name to standard output if it matches
 all specified parameters, one file per line with a trailing linefeed.


@@ -228,7 +296,13 @@ are multiple OSTs that are being replaced.
 Stripe size is \fIn\fR bytes, or \fBK\fRibi-, \fBM\fRebi-,
 \fBG\fRibi-, \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-abytes if a
 suffix is given.  For composite files, this matches the stripe
 Stripe size is \fIn\fR bytes, or \fBK\fRibi-, \fBM\fRebi-,
 \fBG\fRibi-, \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-abytes if a
 suffix is given.  For composite files, this matches the stripe

-size of the last initialized component.
+size of the last initialized non-extension component.
+.TP
+.BR --extension-size | --ext-size | -z
+Extension size is \fIn\fR bytes, or \fBK\fRibi-, \fBM\fRebi-,
+\fBG\fRibi-, \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-abytes if a
+suffix is given.  For composite files, this matches the extension
+size of any extension component.

 .TP
 .BR --type | -t
 File has type: \fBb\fRlock, \fBc\fRharacter, \fBd\fRirectory,
 .TP
 .BR --type | -t
 File has type: \fBb\fRlock, \fBc\fRharacter, \fBd\fRirectory,


@@ -290,6 +364,11 @@ Recursively list all mirrored files that have more than 2 mirrors.
 .TP
 .B $ lfs find ! --mirror-state=ro /mnt/lustre
 Recursively list all out-of-sync mirrored files.
 .TP
 .B $ lfs find ! --mirror-state=ro /mnt/lustre
 Recursively list all out-of-sync mirrored files.

+.TP
+.B $ lfs find ! --foreign=daos /mnt/lustre
+Recursively list all but foreign files/dirs of
+.B daos
+type.

 .SH BUGS
 The
 .B lfs find
 .SH BUGS
 The
 .B lfs find


@@ -309,5 +388,5 @@ command is part of the Lustre filesystem.
 .BR lfs-getdirstripe (1),
 .BR lfs-migrate (1),
 .BR lfs_migrate (1),
 .BR lfs-getdirstripe (1),
 .BR lfs-migrate (1),
 .BR lfs_migrate (1),

-.BR lustre (7)
+.BR lustre (7),

 .BR xargs (1)
 .BR xargs (1)