+++ /dev/null
-=head1 NAME
-
-fastrm - Quickly remove a list of files
-
-=head1 SYNOPSIS
-
-B<fastrm> [B<-de>] [B<-u>|B<-u>I<N>] [B<-s>|B<-s>I<M>] [B<-c>|B<-c>I<I>]
-I<base-directory>
-
-=head1 DESCRIPTION
-
-B<fastrm> reads a list of either file names or storage API tokens, one per
-line, from its standard input and removes them. Storage API tokens are
-removed via the SMcancel() interface. B<fastrm> does not delete files
-safely or with an eye to security, but rather cuts every corner it can to
-delete files as fast as it can. It should therefore never be run on
-publically writable directories, or in any other environment where a
-hostile party may control the directory structure in which it is working.
-
-If a file name is not an absolute path name, it is considered to be
-relative to I<base-directory> as given on the command line. The
-I<base-directory> parameter must be a simple absolute pathname (it must
-not contain multiple consecutive slashes or references to the special
-directories C<.> or C<..>).
-
-B<fastrm> is designed to be faster than the typical C<| xargs rm> pipeline
-when given a sorted list of file names as input. For example, B<fastrm>
-will usually chdir(2) into a directory before removing files from it,
-meaning that if its input is sorted, most names passed to unlink(2) will
-be simple names. This can substantially reduce the operating system
-overhead from directory lookups.
-
-B<fastrm> assumes that its input is valid and that it is safe to call
-unlink(2) on every file name it is given. As a safety measure, however,
-B<fastrm> when running as root will check with stat(2) that a file name
-doesn't specify a directory before removing it. (In some operating
-systems, root is allowed to unlink directories, even directories which
-aren't empty, which can cause file system corruption.)
-
-The input to B<fastrm> should always be sorted -- or even better be in the
-order file names are output by find(1) -- if speed is an issue and the
-input isn't solely storage API tokens. (It deals fine with unsorted
-input, but is unlikely to be any faster in that case than a simple C<xargs
-rm> command.) Sorting may even slightly speed up the removal of storage
-API tokens due to caching effects, since sorting will tend to keep all of
-the tokens from a particular storage method together.
-
-Various additional optimizations for removing files can be turned on
-and/or tuned with options (see below). Which options will be most
-effective depends heavily on the underlying structure of the file system,
-the way in which directories are stored and searched, and similar, often
-underdocumented, operating system implementation details. The more
-sophisticated the underlying operating system and file system, the more
-likely that it will already perform the equivalent of these optimizations
-internally.
-
-=head1 OPTIONS
-
-=over 4
-
-=item B<-d>
-
-Don't remove any files. Instead, print a list of the files that would be
-removed to standard output. Each line contains either the current
-directory of B<fastrm> at the time it would do the unlink and the relative
-path name it would pass to unlink(2) as two fields separated by whitespace
-and a C</>, the absolute path name (as a single field) that would be
-passed to unlink(2), or the string C<Token> and the storage API token that
-would be removed.
-
-=item B<-e>
-
-Treat an empty input file as an error. This is most useful when B<fastrm>
-is last in a pipeline after a preceding sort(1) command, ensuring that
-B<fastrm> will fail if the sort fails.
-
-=item B<-c>I<I>
-
-Controls when B<fastrm> calls chdir(2). If the number of files to be
-unlinked from a given directory is at least I<I>, then B<fastrm> will
-change to that directory before unlinking those files. Otherwise, it will
-use either the absolute path names or a path name relative to the current
-directory (whichever is likely more efficient). The I<I> parameter is
-optional; if just B<-c> is given, B<-c1> is assumed, which will cause
-B<fastrm> to always chdir before calling unlink(2). The default is
-B<-c3>. Use B<-c0> to prevent B<fastrm> from ever using chdir(2).
-
-=item B<-s>I<M>
-
-When B<-s> is given and the number of files to remove in a directory is
-greater than I<M>, rather than remove files in the order given, B<fastrm>
-will open the directory and read it, unlinking files in the order that
-they appear in the directory. On systems with a per-process directory
-cache or that use a linear search to find files in a directory, this
-should make directory lookups faster. The I<M> parameter is optional; if
-just B<-s> is given, B<-s5> is assumed.
-
-When this option is in effect, B<fastrm> won't attempt to remove files
-that it doesn't see in the directory, possibly significantly speeding it
-up if most of the files to be removed have already been deleted. However,
-using this option requires B<fastrm> to do more internal work and it also
-assumes that the order of directory listings is stable in the presence of
-calls to unlink(2) between calls to readdir(3). This may be a dangerous
-assumption with some sophisticated file systems (and in general this
-option is only useful with file systems that use unindexed linear searches
-to find files in directories or when most of the files to be removed have
-already been deleted).
-
-This optimization is off by default.
-
-=item B<-u>I<N>
-
-Specifying this option promises that there are no symbolic links in the
-directory tree from which files are being removed. This allows B<fastrm>
-to make an additional optimization to its calls to chdir(2), constructing
-a relative path using C<../..> and the like to pass to chdir(2) rather
-than always using absolute paths. Since this reduces the number of
-directory lookups needed with deeply nested directory structures (such as
-that typically created by traditional news spool storage), it can be a
-significant optimization, but it breaks horribly in the presence of
-symbolic links to directories.
-
-When B<-u> is given, B<fastrm> will use at most I<N> levels of C<..>
-segments to construct paths. I<N> is optional; if just B<-u> is given,
-B<-u1> is assumed.
-
-This optimization is off by default.
-
-=back
-
-B<fastrm> also accepts B<-a> and B<-r> options, which do nothing at all
-except allow you to say C<fastrm -usa>, C<fastrm -ussr>, or C<fastrm
--user>. These happen to often be convenient sets of options to use.
-
-=head1 EXIT STATUS
-
-B<fastrm> exits with a status of zero if there were no problems, and an
-exit status of 1 if something went wrong. Attempting to remove a file
-that does not exist is not considered a problem.
-
-=head1 EXAMPLES
-
-B<fastrm> is typically invoked by INN via expirerm(8) using a command
-like:
-
- fastrm -e /usr/local/news/spool/articles < expire.list
-
-To enable all optimizations and see the affect on the order of removal
-caused by B<-s>, use:
-
- fastrm -d -s -e -u ~news/spool/articles < expire.list
-
-If your file system has indexed directory lookups, but you have a deeply
-nested directory structure, you may want to use a set of flags like:
-
- fastrm -e -u3 ~news/spool/articles < expire.list
-
-to strongly prefer relative paths but not to use readdir(2) to order the
-calls to unlink(2).
-
-You may want to edit expirerm(8) to change the flags passed to B<fastrm>.
-
-=head1 WARNINGS
-
-B<fastrm> cuts corners and does not worry about security, so it does not
-use chdir(2) safely and could be tricked into removing files other than
-those that were intended if run on a specially constructed file tree or a
-file tree that is being modified while it is running. It should therefore
-never be used with world-writable directories or any other directory that
-might be controlled or modified by an attacker.
-
-=head1 NOTES
-
-B<fastrm> defers opening the storage subsystem or attempting to parse any
-INN configuration files until it encounters a token in the list of files
-to remove. It's therefore possible to use B<fastrm> outside of INN as a
-general fast file removal program.
-
-=head1 HISTORY
-
-B<fastrm> was originally written by kre@munnari.oz.au. This manual page
-rewritten in POD by Russ Allbery <rra@stanford.edu> for InterNetNews.
-
-$Id: fastrm.pod 7422 2005-10-09 04:46:53Z eagle $
-
-=head1 SEE ALSO
-
-expirerm(8)
-
-=cut
~ian / innduct.git / blobdiff