X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?a=blobdiff_plain;f=doc%2Fpod%2Ffastrm.pod;fp=doc%2Fpod%2Ffastrm.pod;h=0000000000000000000000000000000000000000;hb=b7a32e2d73e3ab1add8208d3e157f7269a31ef4d;hp=8f99c587984300e9d9f790f29b84c2e03a064cd8;hpb=ac902a8299ff4469b356836f431ead31c3377377;p=innduct.git diff --git a/doc/pod/fastrm.pod b/doc/pod/fastrm.pod deleted file mode 100644 index 8f99c58..0000000 --- a/doc/pod/fastrm.pod +++ /dev/null @@ -1,190 +0,0 @@ -=head1 NAME - -fastrm - Quickly remove a list of files - -=head1 SYNOPSIS - -B [B<-de>] [B<-u>|B<-u>I] [B<-s>|B<-s>I] [B<-c>|B<-c>I] -I - -=head1 DESCRIPTION - -B 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 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 as given on the command line. The -I parameter must be a simple absolute pathname (it must -not contain multiple consecutive slashes or references to the special -directories C<.> or C<..>). - -B 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 -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 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 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 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 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 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 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 -is last in a pipeline after a preceding sort(1) command, ensuring that -B will fail if the sort fails. - -=item B<-c>I - -Controls when B calls chdir(2). If the number of files to be -unlinked from a given directory is at least I, then B 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 parameter is -optional; if just B<-c> is given, B<-c1> is assumed, which will cause -B to always chdir before calling unlink(2). The default is -B<-c3>. Use B<-c0> to prevent B from ever using chdir(2). - -=item B<-s>I - -When B<-s> is given and the number of files to remove in a directory is -greater than I, rather than remove files in the order given, B -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 parameter is optional; if -just B<-s> is given, B<-s5> is assumed. - -When this option is in effect, B 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 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 - -Specifying this option promises that there are no symbolic links in the -directory tree from which files are being removed. This allows B -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 will use at most I levels of C<..> -segments to construct paths. I is optional; if just B<-u> is given, -B<-u1> is assumed. - -This optimization is off by default. - -=back - -B also accepts B<-a> and B<-r> options, which do nothing at all -except allow you to say C, C, or C. These happen to often be convenient sets of options to use. - -=head1 EXIT STATUS - -B 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 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. - -=head1 WARNINGS - -B 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 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 outside of INN as a -general fast file removal program. - -=head1 HISTORY - -B was originally written by kre@munnari.oz.au. This manual page -rewritten in POD by Russ Allbery for InterNetNews. - -$Id: fastrm.pod 7422 2005-10-09 04:46:53Z eagle $ - -=head1 SEE ALSO - -expirerm(8) - -=cut