findfiles

findfiles finds file system objects in a UNIX-like environment and lists them in time (of last modification and/or access) order. It's been tested on on Linux, AIX and Cygwin - but, hey, it's a C program - so it'll probably run on nearly everything.

But we already have find for that, right? Correct, but findfiles has more of a time focus and adheres more closely to the traditional UNIX philosophy of "do one thing and do it well".

Simple findfiles Examples

findfiles always lists the objects in time sorted order. Here are some common use cases:
  1. List all the files in the /app directory tree that were modified less than 30 seconds ago:
    findfiles -fr -m -30s /app
  2. List all the files in the Videos directory tree for files named '*.mpg' or "*.mp4' modified less than 2 weeks ago (newer) and also the files in the Photos directory tree named '*.jpg' or "*.jpeg' modified more than 1 month ago (older), all case insensitive, in verbose mode with a reverse sort order:
    findfiles -vfr -iR -p '\.mp[g4]$' -m -2W Videos -p '\.jpg$|\.jpeg$' -m +1M Photos
  3. List all the files in the /dblogs and /var/log directories modified later (newer) than lastlogfile was:
    findfiles -f -M lastlogfile /dblogs /var/log

findfiles classifies file system objects as one of these three types: (regular) files, directories, and "other" (e.g., pipes, block specials, symbolic links, etc.)

The findfiles Usage Message

See toward the bottom of the findfiles usage message for more examples of how to use it:
$ findfiles usage (version 3.3.0): findfiles [OPTION]... [target|-t target]... [OPTION]... [target|-t target]... Some OPTIONs require arguments - these are: age : a relative age value followed by a time unit (eg, '3D') ERE : a POSIX-style Extended Regular Expression (pattern) path : the pathname of a reference object (file, directory, etc.) target : the pathname of an object (file, directory, etc.) to search time : an absolute date/time stamp value (eg, '20210630_121530.5') OPTIONs - can be toggled on/off (parsed left to right): -d|--directories : directories (default off) -f|--files : regular files (default off) -o|--others : other files (default off) -r|--recursive : recursive - traverse file trees (default off) -i|--ignore-case : case insensitive pattern match - use before -p|-P|-x|-X (default off) -L|--symlinks : follow symbolic Links (default off) OPTIONs requiring an argument (parsed left to right): -p|--pattern ERE : (re)initialize name search to include objects matching this ERE -P|--and-pattern ERE : extend name search to include objects also matching this ERE (logical and) -x|--exclude ERE : (re)initialize name search to exclude objects matching this ERE -X|--and-exclude ERE : extend name search to exclude objects also matching this ERE (logical and) -t|--target target_path : target path (no default) -D|--depth maximum_recursion_depth : maximum recursion traversal depth/level (default 256) -V|--variable=value : for <FF_variable>=<value> Ages are relative to start time; '-3D' & '3D' both set target time to 3 days before start time -a|--acc-info [-|+]access_age : - for newer/=, [+] for older/= access ages (no default) -m|--mod-info [-|+]modification_age : - for newer/=, [+] for older/= mod ages (default 0s: any time) Times are absolute; eg, '-20211231_153000' & '20211231_153000' (using locale's timezone) -a|--acc-info [-|+]access_time : - for older/=, [+] for newer/= access times (no default) -m|--mod-info [-|+]modification_time : - for older/=, [+] for newer/= mod times (no default) Reference times are absolute; eg: '-/tmp/f' & '/tmp/f' -A|--acc-ref [-|+]acc_ref_path : - for older, [+] for newer access times (no default) -M|--mod-ref [-|+]mod_ref_path : - for older, [+] for newer mod times (no default) Flags - are 'global' options (and can NOT be toggled by setting multiple times): -h|--human-1024 : display object sizes in 'human readable' form (eg, '1.00kiB') -H|--human-1000 : display object sizes in 'human readable' form (eg, '1.02kB') -n|--nanoseconds : in verbose mode, display the maximum resolution of the OS/FS - up to ns -s|--seconds : display file ages in seconds (default D_hh:mm:ss) -u|--units : display units: s for seconds, B for Bytes (default off) -R|--reverse : Reverse the (time) order of the output (default off) -T|--types : Display the type of each file/directory/other (default off) Verbosity: (May be specified more than once for additional information) -v|--verbose : also display modification time, age & size(B) (default 0[off]) Time units: Y: Years M: Months W: Weeks D: Days h: hours m: minutes s: seconds Note: Specify Y & M with integer values. W, D, h, m & s can also take floating point values Examples of command line arguments (parsed left to right): -f /tmp # files in /tmp of any age, including future dates! -vfn -m -1M /tmp # files in /tmp modified <= 1 month ago, verbose output with ns -f -p '\.ant$' -m 1D /tmp # files in /tmp ending in '.ant' modified >= 1 day ago -fip a /tmp -ip b /var # files named /tmp/*a*, /tmp/*A* and /var/*b* -rfa -3h src # files in the src tree accessed <= 3 hours ago -dRp ^yes -X no . # directories in . named yes* unless named *no* - reverse sort -rfM -/etc/hosts /lib # files in the /lib tree modified before /etc/hosts was -vfm -3h / /tmp -fda 1h /var # files in / and /tmp modified <= 3 hours ago, and directories # (but NOT files) in /var accessed >= 1h ago, verbose output -f -m -20201231_010203.5 . # files in . modified at or before 20201231_010203.5 findfiles Copyright (C) 2016-2024 James S. Crook This program comes with ABSOLUTELY NO WARRANTY. This is free software, and you are welcome to redistribute it under certain conditions. This program is licensed under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version (see <http://www.gnu.org/licenses/>).

Both findfiles and find?

Some findfiles Examples

  1. View the all the files in the /tmp tree modified in the last 10 seconds and in the /var/log tree accessed in the last 2 minutes - least recent files first:
    $ view $(findfiles -Rfr -m -10s /tmp -a -2m /var/log)
  2. Remove all files in the /tmp and /var/tmp trees that were last modified 1 year ago or more. (Obviously you shouldn't do this if you have files that might still be required after a year!)
    $ rm $(findfiles -fr -m +1Y /tmp /var/tmp)
  3. No access or modification times have been specified, so the default value ('-m 0s') means all possible modification times (including future times) and the default patter ('-p ".*"') meaning all patterns.
    $ findfiles -vf . 20160510_101641 0D_00:15:11 30 ./barfoo 20160510_101638 0D_00:15:14 30 ./foobar 20160510_101633 0D_00:15:19 30 ./bar 20160510_101630 0D_00:15:22 30 ./foo
  4. Same as the above example, but with reverse sort ('-R'), times displayed in seconds ('-s'), and units (both 's' and 'B') displayed with the units option ('-u'):
    $ findfiles -vfRsu . 20160510_101630 922s 30B ./foo 20160510_101633 919s 30B ./bar 20160510_101638 914s 30B ./foobar 20160510_101641 911s 30B ./barfoo
  5. Find all files in the current directory modified <= 6 months ago. A verbosity of >= 2 shows the start time information (i:) line:
    $ findfiles -vvf -m -6M . i: start time: 1640998800.000000000s ~= Sat Jan 01 12:00:00 2022 AEDT +1100 i: target time: 1625101200.000000000s ~= Thu Jul 01 11:00:00 2021 AEST +1000 i: 184.00000D ~= 15897600.000000000s last modified after (newer than) target time ('6M') i: start time: 1640998800.000000000s ~= Sat Jan 01 12:00:00 2022 AEDT +1100 20211130_073158 32D_04:28:01 310972 ./bar

    Note the hour difference (12 vs 11 hours) and the time zone change (AEDT vs AEST) when looking back 6 months. DST was in effect when findfiles was started ("now", Jan 1 2022), but DST was not in effect 6 months earlier (the target time, in July 1 2021). Note: southern hemisphere!

    A verbosity of >= 2 when using time of last modification and/or access also shows the target time(s) and the last modified/accessed time(s) newer/older than (in s.ns) information (i:) lines.

  6. The same as the example above, but this time with the display nanoseconds ('-n') flag as well:
    $ findfiles -vvfn -m -6M . i: target time: 1621232728.280166380s ~= Mon May 17 16:25:28 2021 AEST +1000 i: 184.00000D ~= 15897600.000000000s last modified after (newer than) target time ('6M') i: start time: 1637130328.280166380s ~= Wed Nov 17 17:25:28 2021 AEDT +1100 20211117_172324.610878747 0D_00:02:03.669287633 1278 ./bar
  7. The same as the previous example, but this time the timezone environment variable TZ has been set to UTC. Note that no daylight savings time (DST) time is in effect and so the hour and timezone values are unchanged:
    $ TZ=UTC findfiles -vvfn -m -6M . i: target time: 1621232828.669657758s ~= Mon May 17 06:27:08 2021 UTC +0000 i: 184.00000D ~= 15897600.000000000s last modified after (newer than) target time ('6M') i: start time: 1637130428.669657758s ~= Wed Nov 17 06:27:08 2021 UTC +0000 20211117_062324.610878747 0D_00:03:44.058779011 1278 ./bar
  8. Info line (i:) dates in other locales (languages) - French, in this case:
    $ TZ=UTC LANG=fr_FR.UTF-8 findfiles -vvfn -m -6M . i: target time: 1621233081.829776341s ~= lun. mai 17 06:31:21 2021 UTC +0000 i: 184.00000D ~= 15897600.000000000s last modified after (newer than) target time ('6M') i: start time: 1637130681.829776341s ~= mer. nov. 17 06:31:21 2021 UTC +0000 20211117_062324.610878747 0D_00:07:57.218897594 1278 ./bar
  9. As of version 3, one may specify absolute timestamps as access (-a) and modification (-m) values:

    In this case, find files with a last modification ('-m') timestamp before (hence '-') a particular time:
    $ findfiles -vvf -m -20211010_150000 ~ i: target time: 1633838400.000000000s ~= Sun Oct 10 15:00:00 2021 AEDT +1100 i: 42.77967D ~= 3696164.536318348s last modified before (older than) target time ('20211010_150000') i: start time: 1637534564.536318348s ~= Mon Nov 22 09:42:44 2021 AEDT +1100 20211006_200750 46D_13:34:53 77 ./foo 20200515_110242 555D_21:40:01 1284848 ./foobar 20141008_235309 2601D_09:49:35 193 ./foofoo

    In this case, find files with a last access ('-a') timestamp after (hence without '-') a particular time:
    $ findfiles -vvf -a 20210103_143000.5 ~ i: target time: 1609644600.500000000s ~= Sun Jan 03 14:30:00 2021 AEDT +1100 i: 322.80560D ~= 27890403.413378634s last accessed after (newer than) target time ('20210103_143000.5') i: start time: 1637535003.913378634s ~= Mon Nov 22 09:50:03 2021 AEDT +1100 20211122_070659 0D_02:43:04 523 ./bar 20211110_091036 12D_00:39:27 9273 ./barfoo 20211008_095333 44D_23:56:30 2795 ./barbar
  10. As of version 3, -L/--symlinks: follow symbolic links - à la find and other *NIX utilities.
    $ findfiles -vfr -L symlink
  11. As of version 3.0.1, -x/--exclude patterns. Essentially, this is (boolean) not -p/--pattern.
    $ findfiles -vfr -m -30s -x '^\.journal$' /var/log
  12. As of version 3.1.1:

    The -h/--help command line option has been retired. However, invoking findfiles with no arguments displays the usage text (see above).

    Object sizes may now be displayed in 'human readable' format. To display object sizes in kiB, MiB, etc., use the -h|--human-1024 option:
    $ findfiles -vfh -p '.iso$' . 20221227_115311 73D_02:32:45 2.23GiB ./Fedora-KDE-Live-x86_64-37-1.7.iso

    To display object sizes in kB, MB, etc., use the -H|--human-1000 option:
    $ findfiles -vfH -p '.iso$' . 20221227_115311 73D_02:32:49 2.39GB ./Fedora-KDE-Live-x86_64-37-1.7.iso

    Each time a -p|--pattern or -x|--exclude option is invoked, the 'search buffer' is (re)initialized. In this example, find all files starting with 'passwd' in /etc, as well as all files not containing 'key' in /etc/ssh.
    $ findfiles -fp ^passwd /etc -x key /etc/ssh

    One may create more complicated ERE combinations by invoking '-P|--and-pattern' and/or '-X|--and-exclude'. These 'accumulate' (logical and operation) - they are parsed left to right. In this example, find all files in Dir1 starting with 'dev', except any that contain the pattern 'old', and the same for Dir2, except files containing 'nope' in Dir2 are also excluded.
    $ findfiles -fp ^dev -X old Dir1 -X nope Dirs
  13. As of version 3.3.0, the object "type" can be displayed with the -T/--types option. The object types are: Fil, Dir, Sln, Blk, Chr, FIF, Soc, and Oth(er).
    $ findfiles -fdoT /mnt /etc/passwd Fil /etc/passwd Dir /mnt

    Verbose mode added.
    $ findfiles -vfdo --types /mnt /etc/passwd /bin 20231222_115434 19D_19:55:40 3068 Fil /etc/passwd 20230721_100000 173D_20:50:14 7 Sln /bin 20230721_100000 173D_20:50:14 4096 Dir /mnt

More Advanced findfiles Examples

Warning: Be very careful when using the FF_ environment variables! Poor choices may elicit unfortunate results!
  1. Display objects' timestamps in different formats with the FF_DATETIMEFORMAT environment variable. In this example use ISO 8601 time format (in UTC/GMT):
    $ TZ=UTC FF_DATETIMEFORMAT='%04d-%02d-%02dT%02d:%02d:%02dZ' findfiles -vf -m -6M . 2017-12-15T12:01:24Z 87D_11:58:48 2675 ./bar
  2. A verbosity of >= 3 also shows objects' timestamps (since 'the Epoch') and ages (since start time), both in s.ns :
    $ TZ=UTC FF_DATETIMEFORMAT='%04d-%02d-%02dT%02d:%02d:%02dZ' findfiles -vvvvf -m -6M . i: target time: 1621233588.206924091s ~= Mon May 17 06:39:48 2021 UTC +0000 i: 184.00000D ~= 15897600.000000000s last modified after (newer than) target time ('6M') i: start time: 1637131188.206924091s ~= Wed Nov 17 06:39:48 2021 UTC +0000 1637017546.888209896 = 2021-11-15T23:05:46Z 113641.318714195 = 1D_07:34:01 15459 ./bar i: FF_AGEFORMAT='%7ldD_%02ld:%02ld:%02ld' # default i: FF_DATETIMEFORMAT='%04d-%02d-%02dT%02d:%02d:%02dZ' # default='%04d%02d%02d_%02d%02d%02d' i: FF_INFODATETIMEFORMAT='%a %b %d %H:%M:%S %Y %Z %z' # default i: FF_STARTTIME='Now' # default i: FF_TIMESTAMPFORMAT='%Y%m%d_%H%M%S' # default

    Note for the example above: a verbosity of >=4 shows the environment variables that can be configured - their current and default values. This is displayed after the file output.

  3. Set the age format with environment variable FF_AGEFORMAT:
    $ TZ=UTC FF_DATETIMEFORMAT='%04d-%02d-%02dT%02d:%02d:%02dZ' FF_AGEFORMAT='%7ld Days, %02ld hours, %02ld minutes, %02ld seconds' findfiles -vvf -m -6M . i: target time: 1505260813.333995833s ~= Wed 13 Sep 2017 00:00:13 UTC i: 181.00000D ~= 15638400.000000000s last modified after (newer than) target time ('6M') i: start time: 1520899213.333995833s ~= Tue 13 Mar 2018 00:00:13 UTC 2017-12-15T12:01:24Z 87 Days, 11 hours, 58 minutes, 48 seconds 2675 ./bar
  4. As of version 3, all of the FF_... environment variables may also be set as command line arguments - FF_DATETIMEFORMAT and FF_AGEFORMAT, in this case:
    $ TZ=UTC findfiles -V FF_DATETIMEFORMAT='%04d/%02d/%02d-%02d:%02d:%02d' -V FF_AGEFORMAT='%ld days, %02ld:%02ld:%02ld' -vvvvf -m -6M . i: target time: 1621636554.017067274s ~= Fri May 21 22:35:54 2021 UTC +0000 i: 184.00000D ~= 15897600.000000000s last modified after (newer than) target time ('6M') i: start time: 1637534154.017067274s ~= Sun Nov 21 22:35:54 2021 UTC +0000 1637351057.375464374 = 2021/11/19-19:44:17 183096.641602900 = 2 days, 02:51:36 92546 ./foo i: FF_AGEFORMAT='%ld days, %02ld:%02ld:%02ld' # default='%7ldD_%02ld:%02ld:%02ld' i: FF_DATETIMEFORMAT='%04d/%02d/%02d-%02d:%02d:%02d' # default='%04d%02d%02d_%02d%02d%02d' i: FF_INFODATETIMEFORMAT='%a %b %d %H:%M:%S %Y %Z %z' # default i: FF_STARTTIME='Now' # default i: FF_TIMESTAMPFORMAT='%Y%m%d_%H%M%S' # default

Notes

  1. The output of findfiles is time focused - time of last access and/or last modification. Even if there is no time specified on the command line, the output is sorted by time.
  2. The default sort order is newest first (decreasing).
  3. findfiles parses (and processes) command line arguments (targets and options) in left to right (L-R) order.
  4. Some command line options are flags that can be toggled on/off (parsed L-R).
  5. Some command line options require parameters that can be set and reset (parsed L-R).
  6. Some command line options are global - they cannot be toggled on/off.
  7. --long-options are supported, but getopt_long was not used because of the L-R requirement. As a result, "--" does not work (i.e., not the way getopt_long handles it).
  8. As of version 2, findfiles uses the 'nanosecond' timestamp information (in addition to the seconds information) to determine objects' ages and their sort order. However, findfiles reads objects' access and modification times from the file system via OS calls. These values will almost certainly not be accurate to the nanosecond, only to the resolution the file system (and/or OS) provides.
  9. findfiles calculates an object's age by subtracting that object's last modification (or access) time from the start time (normally 'now' - the time findfiles was started). Both seconds and 'nanoseconds' for both of these times are used to determine this time difference - the object's age. 'Nanoseconds' may be displayed (with the '-n' option). If they are not, only the seconds value is displayed. That is, the age values are not rounded to the nearest second.
  10. If findfiles is instructed to find some objects based on last modification time and others based on last access time, the output will be sorted based whichever time (last access or last modification) was requested for each object.
  11. Integer or floating point number(s) of weeks, days, hours, minutes or seconds may be specified.
  12. Only integer numbers of years and months may be specified because years and months vary in length.
  13. As with any command (even find), be extremely careful when calling rm or mv, e.g.: rm $(findfiles -fr -m 1Y /tmp /var/tmp) ! findfiles might not return any files, so rm would have no argument!
  14. Under certain circumstances, findfiles reports negative (modification and/or access) age(s) for objects. When findfiles starts, the first thing it does is record its start time. It takes a finite amount of time to traverse the target(s). The more objects to be traversed, the longer it takes to check them all. Any target object that's modified and/or accessed after this start time will therefore be reported as having a negative age. This is very likely to occur when searching very large trees containing objects that are modified/accessed frequently. For example, running findfiles with a target of '/' (the entire file system) will likely report objects with negative ages in /proc and /sys. So don't be alarmed if you observe this.
  15. Informational output lines (starting with 'i:') go to stderr, so it's a trivial matter to separate them from the file list output, which goes to stdout.
  16. It's not possible to change the order of the values displayed using FF_DATETIMEFORMAT and/or FF_AGEFORMAT. For example, one may not switch the order of day and month. (See printf for further information on formatting.) Also, use all the values - do not omit any.
  17. The values of FF_INFODATETIMEFORMAT may be set within the constraints of strftime. (Not all values must be used, and the order is arbitrary.)
  18. The values of FF_TIMESTAMPFORMAT may be set within the constraints of strptime. (Not all values must be used, and the order is arbitrary.)
  19. findfiles uses 24 hour time everywhere except in the informational ('i:') output lines - e.g., if LANG is en_US.UTF8. (YOSJ staff use 24 hour time whenever it's available!)
  20. The FF_STARTTIME environment variable is intended primarily for testing and debugging. Note: FF_STARTTIME must always be entered in the format YYYYMMDD_HHMMSS[.ns]. I.e., FF_TIMESTAMPFORMAT is not used for start times.
  21. As of version 3, these are the new features that break backward compatibility:
    • Long options '--acc-age' is now '--acc-info' and '--mod-age' is now '--mod-info'.
    • findfiles now treats symbolic links the same way many other *NIX commands do (eg, find). (Before, they were always treated as symbolic links - they were never followed.)
    • The required format for FF_STARTTIME is now YYYYMMDD_HHMMSS[.ns] (FF_TIMESTAMPFORMAT is not used), and it respects the local timezone - eg, TZ. (Before, it was s[.ns] since the Epoch using UTC.) Note: This feature is only meant for testing findfiles.
    And these are version 3 features that do not break backward compatibility:
    • Absolute target times may now be specified (i.e., with '-a' and '-m' arguments). The default format is 'YYYYMMDD_HHMMSS[.ns]'. One may enter timestamps in a different format by setting FF_TIMESTAMPFORMAT. For example, when using -V -FF_TIMESTAMPFORMAT=%H%M, one could specify absolute timestamps using only hour and minute values (e.g., '-m -2355'). All values that are not specified are populated using the values of the time findfiles' start time. Note: absolute timestamps must always end in a digit or a decimal point ('.'). Before, access (-a) and modification (-m) times were only set relatively (to the starttime), eg, '10D' or '-30s'.
    • FF_... values can now be set on the command line (as well as set as environment variables). Note: CLI values overwrite environment variables if the same variable is set both ways.

Version 1.x.x - 1 second time resolution

Version 1.x.x info can be found here: findfiles v1.x.x.