From efa710523b85467dd0a9a964cdc82ac12fccd95e Mon Sep 17 00:00:00 2001 From: Vitaliy Kuznetsov Date: Mon, 9 Oct 2023 14:05:31 +0200 Subject: [PATCH] EX-8344 lipe: Update manual page This small patch expands the explanations for some commands with information from the development files. Adds one "todo-list.md" file instead of different files with similar information. Test-Parameters: trivial Signed-off-by: Vitaliy Kuznetsov Change-Id: I0a3ebda49525d62cd6ca398f12601e588dc2dd42 Reviewed-on: https://review.whamcloud.com/c/ex/lustre-release/+/52589 Tested-by: jenkins Tested-by: Maloo Reviewed-by: Colin Faber Reviewed-by: Alexandre Ioffe Reviewed-by: Andreas Dilger --- lipe/man/lipe_find3.1 | 45 +++- lipe/src/lipe_find3/NOTES | 145 ------------- lipe/src/lipe_find3/find-actions.txt | 360 ------------------------------- lipe/src/lipe_find3/find-tests.txt | 184 ---------------- lipe/src/lipe_find3/lipe-find3-notes.txt | 65 ------ lipe/src/lipe_find3/todo-list.md | 171 +++++++++++++++ 6 files changed, 206 insertions(+), 764 deletions(-) delete mode 100644 lipe/src/lipe_find3/NOTES delete mode 100644 lipe/src/lipe_find3/find-actions.txt delete mode 100644 lipe/src/lipe_find3/find-tests.txt delete mode 100644 lipe/src/lipe_find3/lipe-find3-notes.txt create mode 100644 lipe/src/lipe_find3/todo-list.md diff --git a/lipe/man/lipe_find3.1 b/lipe/man/lipe_find3.1 index 2909e66..3446110 100644 --- a/lipe/man/lipe_find3.1 +++ b/lipe/man/lipe_find3.1 @@ -1,4 +1,4 @@ -.TH LIPE_FIND3 "1" "March 2022" "lipe_find3 (lipe) 2.22_121_g2a0cb43-1" "User Commands" +.TH LIPE_FIND3 "1" "September 2023" "lipe_find3 (lipe) 2.22_121_g2a0cb43-1" "User Commands" .SH NAME lipe_find3 \- manual page for lipe_find3 (lipe) 2.22_121_g2a0cb43-1 .SH SYNOPSIS @@ -32,7 +32,8 @@ list available JSON attribute names and exit use COUNT scaninng threads (default 4) .TP \fB\-\-warnings\fR=\fIWARN_TYPE\fR -enable additional warning diagnostic. Available warning type: get-attr - warning is reported when getting file attribute fails +enable additional warning diagnostic. Available warning type: get-attr - warning +is reported when getting file attribute fails .TP \fB\-h\fR, \fB\-\-help\fR display this help text and exit @@ -213,7 +214,8 @@ The last instantiated component of file has \fIn\fR stripes. File has an xattr with name \fBequal\fR to \fIname\fR. .IP "\-xattr-match \fIname\fR \fIvalue\fR" -File has an xattr whose name and value matches the shell patterns \fIname\fR and \fIvalue\fR. +File has an xattr whose name and value matches the shell patterns \fIname\fR +and \fIvalue\fR. .SH ACTIONS .IP "\-exec \fIcommand\fR ;" @@ -222,13 +224,24 @@ arguments to find are taken to be arguments to the command until an argument consisting of ';' is encountered. The string '{}' is replaced by the absolute path of the first hardlink of the current file being processed everywhere it occurs in the arguments to the -command. Regardless of the command, this requires a locally mounted -client for the FS to which the device belongs. See \fBfind\fP(1) for more -information. +command. Both of these constructions might need to be escaped (with a `\') or +quoted to protect them from expansion by the shell. Regardless of the command, +this requires a locally mounted client for the FS to which the device belongs. +See \fBfind\fP(1) for more information. .IP "\-exec \fIcommand\fR +" -Like \fB\-exec\fP but the command line is built by appending each -selected file name at the end. See \fBfind\fP(1) for more information. +This variant of the \fB\-exec\fP action runs the specified command on the +selected files, but the command line is built by appending each selected file +name at the end; the total number of invocations of the command will be much +less than the number of matched files. The command line is built in much the +same way that xargs builds its command lines. Only one instance of `{}' is +allowed within the command, and (when find is being invoked from a shell) it +should be quoted (for example, '{}') to protect it from interpretation by shells. +The command is executed in the starting directory. If any invocation with +the `+' form returns a non-zero value as exit status, then find returns a +non-zero exit status. If find encounters an error, this can sometimes cause an +immediate exit, so some pending commands may not be run at all. This variant +of \fB\-exec\fP always returns true. .IP "\-print\-file\-fid" Print the current file FID when scanning an MDT, and the FID of the @@ -253,10 +266,18 @@ relative to the root of the filesystem. Also requires a locally mounted client. .IP "\-print" -Alias for "\-print\-relative\-path". +True; print the full file name on the standard output, followed by a newline. +If you are piping the output of find into another program and there is the +faintest possibility that the files which you are searching for might +contain a newline, then you should seriously consider using the \fB\-print0\fP +option instead of \fB\-print\fP. .IP "\-print0" -Like \fB\-print\fP but use a null character instead of a newline. +True; print the full file name on the standard output, followed by a null +character (instead of the newline character that \fB\-print\fP uses). +This allows file names that contain newlines or other types of white space +to be correctly interpreted by programs that process the find output. +This option corresponds to the -0 option of xargs. .IP "\-fprint \fIfile\fR" Like \fB\-print\fP but print to \fIfile\fR instead of stdout. If @@ -308,6 +329,10 @@ client mount. This removes \fBall\fP hard links to a file. Note that a non empty directory cannot be removed by FID and that even when all the files in a directory would be removed in a scan they may not be removed by the time the directory is encountered. +Use of -delete automatically turns on the `-depth' option. +Warnings: Because -delete implies -depth, you cannot use -prune and -delete +together. When paired with -ignore_readdir_race, errors from the -delete action +are ignored if the file has disappeared since the directory was read. .IP "\-collect-fsize-stats \fIreport_name\fR" Collect statistics about file size, and create file with report. diff --git a/lipe/src/lipe_find3/NOTES b/lipe/src/lipe_find3/NOTES deleted file mode 100644 index 043e182..0000000 --- a/lipe/src/lipe_find3/NOTES +++ /dev/null @@ -1,145 +0,0 @@ -TODO "{fid}" in exec? -TODO dev, rdev -TODO -empty -TODO Check that system* is MT safe. -TODO dynamic-wind and MT. -TODO scm exceptions generate errors with no progname prefix. -TODO scanning and encryption -TODO xargs batch limits needed? -TODO symlinks need readlink in lipe_scan3 - -TODO fprintf - \a \b \f \n \r \t \v \0 \\ - \OOO => \xXX - - Field widths and precisions can be specified as with the - `printf' C function. Please note that many of the fields are - printed as %s rather than %d, and this may mean that flags - don't work as you might expect. This also means that the `-' - flag does work (it forces fields to be left-aligned). - - Flags #, 0, -, ' ', + - - '#' flag - - \c Stop printing from this format immediately and flush the output. - - NI A `\' character followed by any other character is treated as an ordinary character, so they both are printed. - A '\' followed by and other char is invalid. - - + Date and time, separated by `+', for example `2004-04-28+22:22:05.0'. - This is a GNU extension. The time is given in the current timezone - (which may be affected by setting the TZ environment variable). The - seconds field includes a fractional part. - - - %% a literal percent sign - %a atime in ctime() format - %Ak (k is @ or a strftime directive) - - %b block count - %c ctime in ctime() format - %Ck ... -NI %d File's depth in the directory tree; 0 means the file is a starting-point. -NI %D %D The device number on which the file exists (st_dev in decimal) - %f File's name with any leading directories removed (only the last element) -NI %F Type of the filesystem the file is on; this value can be used for -fstype. - %g File's group name, or numeric group ID if group has no name. - %G numeric gid - - %h Leading directories of file's name (all but the last - element). If the file name contains no slashes (since it is - in the current directory) the %h specifier expands to `.'. - - (call-with-relative-path dirname) - -?? %H Starting-point under which file was found. - - (client-mount-point) - - %i ino decimal - - %k disk space used in 1KB blocks. (rounded up) -DEFER %l symlink target or empty string if not symlink - - %m File's permission bits (in octal). This option uses the - `traditional' numbers which most Unix implementations use, - but if your particular implementation uses an unusual - ordering of octal permissions bits, you will see a dif‐ - ference between the actual value of the file's mode and the - output of %m. Normally you will want to have a leading - zero on this number, and to do this, you should use the # - flag (as in, for example, `%#m'). - - k:~# find /mnt/lustre -name f0 -printf '%m\n' - 644 - k:~# find /mnt/lustre -name f0 -printf '%#m\n' - 0644 - k:~# find /mnt/lustre -name f0 -printf '%03m\n' - 644 - k:~# find /mnt/lustre -name f0 -printf '%06m\n' - 000644 - k:~# find /mnt/lustre -name f0 -printf '%02m\n' - 644 - - %M File's permissions (in symbolic form, as for ls) - %n Number of hard links to file. - %p File's name. - - # find /mnt/lustre -name f9 -printf '%p\n' - /mnt/lustre/sanity/f9 - # cd /mnt/lustre && find . -name f9 -printf '%p\n' - ./sanity/f9 - - %P File's name with the name of the starting-point under which it was found removed - - k:~# find /mnt/lustre -name f9 -printf '%P\n' - sanity/f9 - k:~# cd /mnt/lustre && find . -name f9 -printf '%P\n' - sanity/f9 - - (relative-path) - - %S File's sparseness. This is calculated as (BLOCKSIZE*st_blocks / st_size). - The exact value you will get for an ordinary file of a certain length is - system-dependent. However, normally sparse files will have values less than - 1.0, and files which use indirect blocks may have a value which is greater - than 1.0. In general the number of blocks used by a file is file system de‐ - pendent. The value used for BLOCKSIZE is system-dependent, but is usually - 512 bytes. If the file size is zero, the value printed is undefined. On - systems which lack support for st_blocks, a file's sparseness is assumed to - be 1.0. - - size == 0 => sparseness = 1 - - -Extensions - %{fid} FID as string w/o braces - %{device-name} "fs0a42-MDT0007" - %{device-path} "/dev/mapper/mds1_flakey" - %{client-mount-path} - -TODO Regex: - Try compling the regex first for error messages. - -By default, Guile supports POSIX extended regular expressions. That -means that the characters ‘(’, ‘)’, ‘+’ and ‘?’ are special, and must -be escaped if you wish to match the literal characters and there is no -support for “non-greedy” variants of ‘*’, ‘+’ or ‘?’. - -regexp/icase -regexp/basic -regexp/extended - -(define %LEC:regex-42 (make-regexp pattern regexp/basic regexp/extended)) - -pattern flags - -(define %LEC:match-fname-107 - (let* ((%LEC:match-fname-108 - (lambda (str) - (fnmatch? ,pattern str ,flags)))) - (lambda () (any %LEC:match-fname-108 (paths))))) - -regexp/icase -(use-modules (ice-9 regex)) diff --git a/lipe/src/lipe_find3/find-actions.txt b/lipe/src/lipe_find3/find-actions.txt deleted file mode 100644 index 98df9b5..0000000 --- a/lipe/src/lipe_find3/find-actions.txt +++ /dev/null @@ -1,360 +0,0 @@ -DONE - -delete - Delete files; true if removal succeeded. If the removal failed, an error message - is issued. If -delete fails, find's exit status will be nonzero (when it eventu‐ - ally exits). Use of -delete automatically turns on the `-depth' option. - - Warnings: Don't forget that the find command line is evaluated as an expression, so - putting -delete first will make find try to delete everything below the starting - points you specified. When testing a find command line that you later intend to - - use with -delete, you should explicitly specify -depth in order to avoid later sur‐ - prises. Because -delete implies -depth, you cannot usefully use -prune and -delete - together. - - Together with the -ignore_readdir_race option, find will ignore errors of the - -delete action in the case the file has disappeared since the parent directory was - read: it will not output an error diagnostic, and the return code of the -delete - action will be true. - - -exec command ; - Execute command; true if 0 status is returned. All following arguments to find are - taken to be arguments to the command until an argument consisting of `;' is encoun‐ - tered. The string `{}' is replaced by the current file name being processed every‐ - where it occurs in the arguments to the command, not just in arguments where it is - alone, as in some versions of find. Both of these constructions might need to be - escaped (with a `\') or quoted to protect them from expansion by the shell. See - the EXAMPLES section for examples of the use of the -exec option. The specified - command is run once for each matched file. The command is executed in the starting - directory. There are unavoidable security problems surrounding use of the -exec - action; you should use the -execdir option instead. - - -exec command {} + - This variant of the -exec action runs the specified command on the selected files, - but the command line is built by appending each selected file name at the end; the - total number of invocations of the command will be much less than the number of - matched files. The command line is built in much the same way that xargs builds - its command lines. Only one instance of `{}' is allowed within the command, and - (when find is being invoked from a shell) it should be quoted (for example, '{}') - to protect it from interpretation by shells. The command is executed in the start‐ - ing directory. If any invocation with the `+' form returns a non-zero value as - exit status, then find returns a non-zero exit status. If find encounters an er‐ - ror, this can sometimes cause an immediate exit, so some pending commands may not - be run at all. This variant of -exec always returns true. - - -fprint file - True; print the full file name into file file. If file does not exist when find is - run, it is created; if it does exist, it is truncated. The file names `/dev/std‐ - out' and `/dev/stderr' are handled specially; they refer to the standard output and - standard error output, respectively. The output file is always created, even if - the predicate is never matched. See the UNUSUAL FILENAMES section for information - about how unusual characters in filenames are handled. - - -fprint0 file - True; like -print0 but write to file like -fprint. The output file is always cre‐ - ated, even if the predicate is never matched. See the UNUSUAL FILENAMES section - for information about how unusual characters in filenames are handled. - - -fprintf file format - True; like -printf but write to file like -fprint. The output file is always cre‐ - ated, even if the predicate is never matched. See the UNUSUAL FILENAMES section - for information about how unusual characters in filenames are handled. - - -print True; print the full file name on the standard output, followed by a newline. If - you are piping the output of find into another program and there is the faintest - possibility that the files which you are searching for might contain a newline, - then you should seriously consider using the -print0 option instead of -print. See - the UNUSUAL FILENAMES section for information about how unusual characters in file‐ - names are handled. - - -print0 - True; print the full file name on the standard output, followed by a null character - (instead of the newline character that -print uses). This allows file names that - contain newlines or other types of white space to be correctly interpreted by pro‐ - grams that process the find output. This option corresponds to the -0 option of - xargs. - -PARTIALLY DONE - -printf - Not all format directives are implemented. Search for - LF3_EMIT_U(). Format width and precision is only - partially implemented. - - -printf format - True; print format on the standard output, interpreting `\' escapes and `%' direc‐ - tives. Field widths and precisions can be specified as with the `printf' C func‐ - tion. Please note that many of the fields are printed as %s rather than %d, and - this may mean that flags don't work as you might expect. This also means that the - `-' flag does work (it forces fields to be left-aligned). Unlike -print, -printf - does not add a newline at the end of the string. The escapes and directives are: - - \a Alarm bell. - - \b Backspace. - - \c Stop printing from this format immediately and flush the output. - - \f Form feed. - - \n Newline. - - \r Carriage return. - - \t Horizontal tab. - - \v Vertical tab. - - \0 ASCII NUL. - - \\ A literal backslash (`\'). - - \NNN The character whose ASCII code is NNN (octal). - - A `\' character followed by any other character is treated as an ordinary charac‐ - ter, so they both are printed. - - %% A literal percent sign. - - %a File's last access time in the format returned by the C `ctime' function. - - %Ak File's last access time in the format specified by k, which is either `@' or - a directive for the C `strftime' function. The possible values for k are - listed below; some of them might not be available on all systems, due to - differences in `strftime' between systems. - - @ seconds since Jan. 1, 1970, 00:00 GMT, with fractional part. - - Time fields: - - H hour (00..23) - - I hour (01..12) - - k hour ( 0..23) - - l hour ( 1..12) - - M minute (00..59) - - p locale's AM or PM - - r time, 12-hour (hh:mm:ss [AP]M) - - S Second (00.00 .. 61.00). There is a fractional part. - - T time, 24-hour (hh:mm:ss.xxxxxxxxxx) - - + Date and time, separated by `+', for example `2004-04-28+22:22:05.0'. - This is a GNU extension. The time is given in the current timezone - (which may be affected by setting the TZ environment variable). The - seconds field includes a fractional part. - - X locale's time representation (H:M:S). The seconds field includes a - fractional part. - - Z time zone (e.g., EDT), or nothing if no time zone is determinable - - Date fields: - - a locale's abbreviated weekday name (Sun..Sat) - - A locale's full weekday name, variable length (Sunday..Saturday) - - b locale's abbreviated month name (Jan..Dec) - - B locale's full month name, variable length (January..December) - - c locale's date and time (Sat Nov 04 12:02:33 EST 1989). The format is - the same as for ctime(3) and so to preserve compatibility with that - format, there is no fractional part in the seconds field. - - d day of month (01..31) - - D date (mm/dd/yy) - - h same as b - - j day of year (001..366) - - m month (01..12) - - U week number of year with Sunday as first day of week (00..53) - - w day of week (0..6) - - W week number of year with Monday as first day of week (00..53) - - x locale's date representation (mm/dd/yy) - - y last two digits of year (00..99) - - Y year (1970...) - - %b The amount of disk space used for this file in 512-byte blocks. Since disk - space is allocated in multiples of the filesystem block size this is usually - greater than %s/512, but it can also be smaller if the file is a sparse - file. - - %c File's last status change time in the format returned by the C `ctime' func‐ - tion. - - %Ck File's last status change time in the format specified by k, which is the - same as for %A. - - %d File's depth in the directory tree; 0 means the file is a starting-point. - - %D The device number on which the file exists (the st_dev field of struct - stat), in decimal. - - %f File's name with any leading directories removed (only the last element). - - %F Type of the filesystem the file is on; this value can be used for -fstype. - - %g File's group name, or numeric group ID if the group has no name. - - %G File's numeric group ID. - - %h Leading directories of file's name (all but the last element). If the file - name contains no slashes (since it is in the current directory) the %h spec‐ - ifier expands to `.'. - - %H Starting-point under which file was found. - - %i File's inode number (in decimal). - - %k The amount of disk space used for this file in 1 KB blocks. Since disk - space is allocated in multiples of the filesystem block size this is usually - greater than %s/1024, but it can also be smaller if the file is a sparse - file. - - %l Object of symbolic link (empty string if file is not a symbolic link). - - %m File's permission bits (in octal). This option uses the `traditional' num‐ - bers which most Unix implementations use, but if your particular implementa‐ - tion uses an unusual ordering of octal permissions bits, you will see a dif‐ - ference between the actual value of the file's mode and the output of %m. - Normally you will want to have a leading zero on this number, and to do - this, you should use the # flag (as in, for example, `%#m'). - - %M File's permissions (in symbolic form, as for ls). This directive is sup‐ - ported in findutils 4.2.5 and later. - - %n Number of hard links to file. - - %p File's name. - - %P File's name with the name of the starting-point under which it was found re‐ - moved. - - %s File's size in bytes. - - %S File's sparseness. This is calculated as (BLOCKSIZE*st_blocks / st_size). - The exact value you will get for an ordinary file of a certain length is - system-dependent. However, normally sparse files will have values less than - 1.0, and files which use indirect blocks may have a value which is greater - than 1.0. In general the number of blocks used by a file is file system de‐ - pendent. The value used for BLOCKSIZE is system-dependent, but is usually - 512 bytes. If the file size is zero, the value printed is undefined. On - systems which lack support for st_blocks, a file's sparseness is assumed to - be 1.0. - - %t File's last modification time in the format returned by the C `ctime' func‐ - tion. - - %Tk File's last modification time in the format specified by k, which is the - same as for %A. - - %u File's user name, or numeric user ID if the user has no name. - - %U File's numeric user ID. - - %y File's type (like in ls -l), U=unknown type (shouldn't happen) - - %Y File's type (like %y), plus follow symlinks: `L'=loop, `N'=nonexistent, `?' - for any other error when determining the type of the symlink target. - - %Z (SELinux only) file's security context. - - %{ %[ %( - Reserved for future use. - - A `%' character followed by any other character is discarded, but the other charac‐ - ter is printed (don't rely on this, as further format characters may be intro‐ - duced). A `%' at the end of the format argument causes undefined behaviour since - there is no following character. In some locales, it may hide your door keys, - while in others it may remove the final page from the novel you are reading. - - The %m and %d directives support the # , 0 and + flags, but the other directives do - not, even if they print numbers. Numeric directives that do not support these - flags include G, U, b, D, k and n. The `-' format flag is supported and changes - the alignment of a field from right-justified (which is the default) to left-justi‐ - fied. - - See the UNUSUAL FILENAMES section for information about how unusual characters in - filenames are handled. - - -quit Exit immediately. No child processes will be left running, but no more paths spec‐ - ified on the command line will be processed. For example, find /tmp/foo /tmp/bar - -print -quit will print only /tmp/foo. Any command lines which have been built up - with -execdir ... {} + will be invoked before find exits. The exit status may or - may not be zero, depending on whether an error has already occurred. - -DEFERRED - -execdir command ; - - -execdir command {} + - Like -exec, but the specified command is run from the subdirectory containing the - matched file, which is not normally the directory in which you started find. As - with -exec, the {} should be quoted if find is being invoked from a shell. This a - much more secure method for invoking commands, as it avoids race conditions during - resolution of the paths to the matched files. As with the -exec action, the `+' - form of -execdir will build a command line to process more than one matched file, - but any given invocation of command will only list files that exist in the same - subdirectory. If you use this option, you must ensure that your $PATH environment - variable does not reference `.'; otherwise, an attacker can run any commands they - like by leaving an appropriately-named file in a directory in which you will run - -execdir. The same applies to having entries in $PATH which are empty or which are - not absolute directory names. If any invocation with the `+' form returns a non- - zero value as exit status, then find returns a non-zero exit status. If find en‐ - counters an error, this can sometimes cause an immediate exit, so some pending com‐ - mands may not be run at all. The result of the action depends on whether the + or - the ; variant is being used; -execdir command {} + always returns true, while -ex‐ - ecdir command {} ; returns true only if command returns 0. - - -fls file - True; like -ls but write to file like -fprint. The output file is always created, - even if the predicate is never matched. See the UNUSUAL FILENAMES section for in‐ - formation about how unusual characters in filenames are handled. - - -ls True; list current file in ls -dils format on standard output. The block counts - are of 1 KB blocks, unless the environment variable POSIXLY_CORRECT is set, in - which case 512-byte blocks are used. See the UNUSUAL FILENAMES section for infor‐ - mation about how unusual characters in filenames are handled. - - -ok command ; - Like -exec but ask the user first. If the user agrees, run the command. Otherwise - just return false. If the command is run, its standard input is redirected from - /dev/null. - - The response to the prompt is matched against a pair of regular expressions to de‐ - termine if it is an affirmative or negative response. This regular expression is - obtained from the system if the `POSIXLY_CORRECT' environment variable is set, or - otherwise from find's message translations. If the system has no suitable defini‐ - tion, find's own definition will be used. In either case, the interpretation of - the regular expression itself will be affected by the environment variables - 'LC_CTYPE' (character classes) and 'LC_COLLATE' (character ranges and equivalence - classes). - - -okdir command ; - Like -execdir but ask the user first in the same way as for -ok. If the user does - not agree, just return false. If the command is run, its standard input is redi‐ - rected from /dev/null. - -WON'T DO - -prune True; if the file is a directory, do not descend into it. If -depth is given, then - -prune has no effect. Because -delete implies -depth, you cannot usefully use - -prune and -delete together. - For example, to skip the directory `src/emacs' and all files and directories un‐ - der it, and print the names of the other files found, do something like this: - find . -path ./src/emacs -prune -o -print - diff --git a/lipe/src/lipe_find3/find-tests.txt b/lipe/src/lipe_find3/find-tests.txt deleted file mode 100644 index dbc2fa4..0000000 --- a/lipe/src/lipe_find3/find-tests.txt +++ /dev/null @@ -1,184 +0,0 @@ -DONE - -amin - -atime - -cmin - -ctime - -false - -gid - -inum - -links - -mmin - -mtime - -size Based on '(size)' which is based on ?. Needs clarificaiton. - -true - -type - -uid - - -user string or UID but no [+-] prefix on either. - -group ... - - # ls -ld /mnt/lustre/sanity - drwxr-xr-x 2 sanity sanity 4096 Oct 20 11:01 /mnt/lustre/sanity - # find /mnt/lustre -user sanity - /mnt/lustre/sanity - # find /mnt/lustre -user +sanity - find: ‘+sanity’ is not the name of a known user - # find /mnt/lustre -user -sanity - find: ‘-sanity’ is not the name of a known user - # id sanity - uid=500(sanity) gid=500(sanity) groups=500(sanity) - # find /mnt/lustre -user +500 - find: ‘+500’ is not the name of a known user - # find /mnt/lustre -user -500 - find: ‘-500’ is not the name of a known user - # find /mnt/lustre -user 500 - /mnt/lustre/sanity - - -iname pattern - Like -name, but the match is case insensitive. For example, the patterns `fo*' and - `F??' match the file names `Foo', `FOO', `foo', `fOo', etc. The pattern `*foo*` - will also match a file called '.foobar'. - - -ipath pattern - Like -path. but the match is case insensitive. - - -name pattern - Base of file name (the path with the leading directories removed) matches shell - pattern pattern. Because the leading directories are removed, the file names - considered for a match with -name will never include a slash, so `-name a/b' will - never match anything (you probably need to use -path instead). A warning is issued - if you try to do this, unless the environment variable POSIXLY_CORRECT is set. The - metacharacters (`*', `?', and `[]') match a `.' at the start of the base name (this - is a change in findutils-4.2.2; see section STANDARDS CONFORMANCE below). To ig‐ - nore a directory and the files under it, use -prune rather than checking every file - in the tree; see an example in the description of that action. Braces are not - recognised as being special, despite the fact that some shells including Bash imbue - braces with a special meaning in shell patterns. The filename matching is per‐ - formed with the use of the fnmatch(3) library function. Don't forget to enclose - the pattern in quotes in order to protect it from expansion by the shell. - - -path pattern - File name matches shell pattern pattern. The metacharacters do not treat `/' or - `.' specially; so, for example, - find . -path "./sr*sc" - will print an entry for a directory called `./src/misc' (if one exists). To ignore - a whole directory tree, use -prune rather than checking every file in the tree. - Note that the pattern match test applies to the whole file name, starting from one - of the start points named on the command line. It would only make sense to use an - absolute path name here if the relevant start point is also an absolute path. This - means that this command will never match anything: - find bar -path /foo/bar/myfile -print - Find compares the -path argument with the concatenation of a directory name and the - base name of the file it's examining. Since the concatenation will never end with - a slash, -path arguments ending in a slash will match nothing (except perhaps a - start point specified on the command line). The predicate -path is also supported - by HP-UX find and is part of the POSIX 2008 standard. - -TODO - -perm mode - File's permission bits are exactly mode (octal or symbolic). Since an exact match - is required, if you want to use this form for symbolic modes, you may have to spec‐ - ify a rather complex mode string. For example `-perm g=w' will only match files - which have mode 0020 (that is, ones for which group write permission is the only - permission set). It is more likely that you will want to use the `/' or `-' forms, - for example `-perm -g=w', which matches any file with group write permission. See - the EXAMPLES section for some illustrative examples. - - -perm -mode - All of the permission bits mode are set for the file. Symbolic modes are accepted - in this form, and this is usually the way in which you would want to use them. You - must specify `u', `g' or `o' if you use a symbolic mode. See the EXAMPLES section - for some illustrative examples. - - -perm /mode - Any of the permission bits mode are set for the file. Symbolic modes are accepted - in this form. You must specify `u', `g' or `o' if you use a symbolic mode. See - the EXAMPLES section for some illustrative examples. If no permission bits in mode - are set, this test matches any file (the idea here is to be consistent with the be‐ - haviour of -perm -000). - - -fstype - - -used n - File was last accessed n days after its status was last changed. - - -iregex pattern - Like -regex, but the match is case insensitive. - - -regex pattern - File name matches regular expression pattern. This is a match on the whole path, - not a search. For example, to match a file named `./fubar3', you can use the regu‐ - lar expression `.*bar.' or `.*b.*3', but not `f.*r3'. The regular expressions un‐ - derstood by find are by default Emacs Regular Expressions (except that `.' matches - newline), but this can be changed with the -regextype option. - -DEFERRED -empty - File is empty and is either a regular file or a directory. - - How to handle this for striped directories (parents and substripes)? - - -DEFERRED: Things that depend on a reference user or (access()): - -executable - Matches files which are executable and directories - which are searchable (in a file name resolution sense) - by the current user. This takes into account access - control lists and other permissions artefacts which - the -perm test ignores. This test makes use of the - access(2) system call, and so can be fooled by NFS - servers which do UID mapping (or root-squashing), - since many systems implement access(2) in the client's - kernel and so cannot make use of the UID mapping - information held on the server. Because this test is - based only on the result of the access(2) system call, - there is no guarantee that a file for which this test - succeeds can actually be executed. - -readable - ... - -writable - ... - -DEFERRED - -nogroup - No group corresponds to file's numeric group ID. - - -nouser - No user corresponds to file's numeric user ID. - - Read passwd file, get uids build an alist - - (define %LEC:nouser? - (let* ((%LEC:uid-list '(uid1 uid2 ...)) - (%LEC:nouser-uid-alist (map (lambda (uid) (cons uid #f)) %LEC:uid-list)) - (%LEC:nouser-uid-table (alist->hashv-table %LEC:nouser-uid-alist))) - (lambda () - (hashv-ref %LEC:nouser-uid-table (uid) #t)))) - - -DEFERRED (Need a way to read non-fast symlinks in scanner) - -lname pattern - File is a symbolic link whose contents match shell pattern pattern. The metachar‐ - acters do not treat `/' or `.' specially. If the -L option or the -follow option - is in effect, this test returns false unless the symbolic link is broken. - - -ilname pattern - Like -lname, but the match is case insensitive. If the -L option or the -follow - option is in effect, this test returns false unless the symbolic link is broken. - - -xtype c - The same as -type unless the file is a symbolic link. For symbolic links: if the - -H or -P option was specified, true if the file is a link to a file of type c; if - the -L option has been given, true if c is `l'. In other words, for symbolic - links, -xtype checks the type of the file that -type does not check. - -DEFERRED: - -context pattern - (SELinux only) Security context of the file matches glob pattern. - -WON'T DO: - Things that depend on a reference file. - -anewer - -cnewer - -mnewer - -newer - -samefile diff --git a/lipe/src/lipe_find3/lipe-find3-notes.txt b/lipe/src/lipe_find3/lipe-find3-notes.txt deleted file mode 100644 index fd30ee6..0000000 --- a/lipe/src/lipe_find3/lipe-find3-notes.txt +++ /dev/null @@ -1,65 +0,0 @@ -Usage lipe_find3 [OPTION...] DEVICE EXPRESSION - -See lipe_find3 --help for options. - -Some tests and actions require a client mount. By default -lipe_find3/lipe_scan3 will try to find a Lustre client mount based on -the fsname stored in the device. It should just work. Or fail clearly -if the test/action required a client mount. Expression parsing and -precedence should match find (with implicit -and). - -By default we use 4 scanning threads. - -Here is what we support now. Numeric arguments (N) support +/- prefix -like find. - -Tests: - -amin N - -atime N # With optional d, h, m, s unit (for example -atime 7d) - -mmin ... - -mtime ... - -cmin ... - -ctime ... - -gid N - -group G # numeric or symbolic group - -iname # case insensitive fnmatch of basename - -inum # MDT/OST inode number for test/expert use. - -links N # Link count - -name # fnmatch of basename - -path # fnmatch of path - -perm MODE # 0644 or [ugoa][+=-][rwx],... See find(1). FIXME support 'Xst'. - -perm -MODE # ... - -perm /MODE # ... - -pool POOL # file has LOV component with pool == POOL. - -projid N - -size N # TODO Clarify SoM strictness. - -type T # file type is any of comma separated list of [bcdpfls] - -uid N - -user # numeric or symbolic user - -Actions: - -delete - -print - -print0 - -print-file-fid - -print-self-fid - -print-absolute-path - -print-relative-path - -print-json # TODO specifying attrs, listing supported attrs. - -quit - -fprint FILE - -fprint0 FILE - -printf FORMAT # precision and field width are detected but not implemented - -fprintf FILE FORMAT - -exec ... \; - -exec ... + - -Operators: - \( \) - \! - -not - , - -and - -a - -or - -o diff --git a/lipe/src/lipe_find3/todo-list.md b/lipe/src/lipe_find3/todo-list.md new file mode 100644 index 0000000..03a09f1 --- /dev/null +++ b/lipe/src/lipe_find3/todo-list.md @@ -0,0 +1,171 @@ +# TODO and deferred functionality + +This file is intended for developers and describes functionality that needs to +be implemented, which has been delayed and which has been abandoned. + +## TODO Functionality + +### -execdir command (deferred) + +### -execdir command {} + (deferred) + +Like `-exec`, but runs from the subdirectory with the matched file, not usually +where you started find. Quoting `{}` is advised if invoked from a shell. This +method is more secure, avoiding race conditions. The `+` form of `-execdir` +processes multiple files. But commands list files in the same subdirectory. +Ensure your `$PATH` doesn't reference `.` Attackers could exploit an +aptly-named file for `-execdir`. This holds for `$PATH` entries that are empty +or not absolute. If `+' form returns non-zero, find does too. Errors might cause +immediate exit. The result varies with the + or; variant`-execdir command {} +` +always returns true, while`-execdir command {}; returns true if command exits +with 0. + +### -fls file (deferred) + +`True`; like `-ls` but write to file like `-fprint`. The output file is always +created, even if the predicate is never matched. See the *UNUSUAL FILENAMES* +section for information about how unusual characters in filenames are handled. + +### -ls (deferred) + +`True`; list current file in `ls -dils` format on standard output. The block +counts are of 1 KB blocks, unless the environment variable `POSIXLY_CORRECT` is +set, in which case 512-byte blocks are used. See the *UNUSUAL FILENAMES* section +for information about how unusual characters in filenames are handled. + +### -ok command (deferred) + +Like `-exec`, but runs from the subdirectory with the matched file, not usually +where you started find. Quoting `{}` is advised if invoked from a shell. This +method is more secure, avoiding race conditions. The `+` form of `-execdir` +processes multiple files. Commands list files in the same subdirectory. Ensure +your `$PATH` doesn't reference `.`. Attackers could exploit an aptly-named file +for `-execdir`. This applies to `$PATH` entries that are empty or not absolute. +If the `+` form returns non-zero, find does too. Errors may cause immediate exit. +The outcome depends on the + or; form.`-execdir command {} +`always returns true, +while`-execdir command {} ;` is true if command exits with 0. + +### -okdir command (deferred) + +Like `-execdir` but prompts the user similarly to `-ok`. If the user disagrees, +it returns false. When the command is executed, its standard input redirects +from `/dev/null`. + +### -perm mode + +`-perm mode`: File's permission bits are exactly mode (octal or symbolic). Since +an exact match is required, if you want to use this form for symbolic modes, you +may have to specify a complex mode string. For example `-perm g=w` will only +match files with mode 0020 (group write permission only). It's more likely you +will use the `/` or `-` forms, like `-perm -g=w`, which matches any file with +group write permission. Refer to the EXAMPLES section for more examples. + +#### -perm -mode + +All of the permission bits mode are set for the file. Symbolic modes are accepted +in this form. This is usually the way you'd want to use them. You must specify +`u`, `g` or `o` if you use a symbolic mode. Refer to the EXAMPLES section for +examples. + +### -perm /mode + +`-perm /mode`: Any of the permission bits mode are set for the file. Symbolic +modes are accepted in this form. You must specify `u`, `g` or `o`if using a +symbolic mode. Refer to the EXAMPLES section for examples. If no bits in mode +are set, this test matches any file, consistent with `-perm -000`. + +### -fstype + +### -used n + +`-used n`: File was last accessed n days after its status was last changed. + +### -iregex pattern + +`-iregex pattern`: Similar to `-regex`, but the match is case insensitive. + +### -regex pattern + +`-regex pattern`: File name matches the regular expression pattern. This matches +the entire path, not a search. For instance, to match `./fubar3`, you can use +`.*bar.` or `.*b.*3`, but not `f.*r3`. By default, find understands Emacs Regular +Expressions, but can be changed with the `-regextype` option. + +### -empty (deferred) + +`-empty`: The file is empty and is either a regular file or a directory. Handling +for striped directories (parents and substripes) is yet to be determined. + +### Reference-dependent (deferred) + +`-executable`: Matches executable files and directories that are searchable by +the current user. It considers ACLs and other permissions, which `-perm` doesn't. +This test uses the access(2) call and might be affected by NFS servers with UID +mapping. The outcome is based only on the access(2) system call. + +`-readable`: ... + +`-writable`: ... + +### -nogroup + +No group matches the file's numeric group ID. + +### -nouser + +No user matches the file's numeric user ID. + +### -context pattern (deferred) + +(SELinux only) Security context of the file matches glob pattern. + +### Non-fast symlink reading (deferred) + +#### -lname pattern + +File is a symbolic link whose contents match shell pattern pattern. The +metacharacters do not treat `/` or `.` specially. If the `-L` option or the +`-follow` option is in effect, this test returns false unless the symbolic link +is broken. + +#### -ilname pattern + +Like `-lname`, but the match is case insensitive. If the `-L` option or the +`-follow` option is in effect, this test returns false unless the symbolic link +is broken. + +#### -xtype c + +The same as `-type` unless the file is a symbolic link. For symbolic links: if +the `-H` or `-P` option was specified, true if the file is a link to a file of +type c; if the `-L` option has been given, true if c is `l`. In other words, +for symbolic links, `-xtype` checks the type of the file that `-type` does not +check. + +### Other TODOs + +TODO "{fid}" in exec? +TODO dev, rdev +TODO Check that system* is MT safe. +TODO dynamic-wind and MT. +TODO scm exceptions generate errors with no progname prefix. +TODO scanning and encryption +TODO xargs batch limits needed? +TODO symlinks need readlink in lipe_scan3 + +## Won't do + +### -prune (won't do) + +`True`; if the file is a directory, it won't descend into it. If `-depth` is +given, `-prune` is ineffective. As `-delete` implies `-depth`, combining +`-prune` and `-delete` isn't productive. For instance, to omit the directory +`src/emacs` and all under it while printing other files + +### Things that depend on a reference file + +-anewer +-cnewer +-mnewer +-newer +-samefile -- 1.8.3.1