pkg://lfu-3.1-5.alpha.rpm:192180/usr/man/man1/lfu.1  info  downloads

.TH LFU 1 "Version 3.1.5" Local
.if 'yes'yes' .ds Am a
.SH NAME
lfu \- copy directory hierarchies
.SH SYNOPSIS
.B lfu
[
.B \-\*(AmcflmoprsvACHSV
]
[
.B \-d
.I domain
]
[
.B \-D
.I symbol=value
]
[
.B \-I
.I directory
]
[
.B \-e
.I program
]
.if 'yes'yes' \{[
.B \-X
.I options
] \}
.B \-P
.I preprocessor
]
[
.I program-file
]
.I source
.I dest

.SH DESCRIPTION
.B lfu
recursively deletes files from the destination directory and copies
files from the source directory, as necessary, to make the destination
directory into a faithful copy of the source.
If a \fIprogram\fP is specified, then the instructions in the program
can change the copying process, for example by specifying exactly
which files are to be copied, or how the status of the destination
files should differ from the status of the corresponding source files.
The \fIprogram-file\fP may be specified as "\fB-\fP" to read a
program from the standard input.
.LP
The source and destination may also be symbolic links to
directories, and the status of the source and destination directories
themselves is never changed.

.SH PROGRAMS
Program instructions can either be specified directly
on the command line, using the \fB-e\fP option, or in a file.
If a program file is specified, then the file is first passed through
the C preprocessor.
Different systems support different C preprocessors and a
list is searched to find the most suitable.
Preprocessor syntax may vary between the different implementations,
and some have certain restrictions; for example, \fB/lib/cpp\fP under
\s-1HP/UX\s+1, does not accept input from stdin, since it requires
several passes.
The \fB-V\fP option shows the preprocessor being used and the list of
preprocessors can be specified with the \fB-P\fP option.
.PP
Program statements have one of the following forms :-
.IP "" 5
.I ACTION
;
.br
{
.I STATEMENT; ...
}
.br
.I CONDITION
.I STATEMENT
.br
.I CONDITION
.I STATEMENT
else
.I STATEMENT
.br
.LP
The statements are evaluated in order for every file encountered and
the resulting actions are applied to the file.
The results of any action on a directory are inherited by the
descendants of the directory; for example, specifying that the mode of
a directory should be changed, will also cause the mode of all the
descendants to be changed (unless another \fBchmod\fP action is
specified on the descendants themselves).
.LP
A set of default actions may be specified by including a
statement of the following form.
These actions are evaluated once only (at the start)
and the results are inherited by all files processed, unless
explicitly overridden.
.IP "" 5
.B default
{
.I ACTION; ...
}
.br
.LP
Some actions represent global defaults and are only allowed within a
\fBdefault\fB statement.
.LP
Filenames and other literals need not be quoted unless they contain
reserved characters, in which case they can be quoted with
double quotes. Double quotes can be included in strings by
preceeding them with a backslash.
Dangling \fBelse\fP statements bind to the nearest \fBif\fP.
.LP
A \fIsubstitute-filename\fP may be specified for some conditions and actions.
This allows files from different directories to be tested, or used as
the source of symbolic links.
A substitute file specification has one of the forms :-
.IP "" 5
.I PREFIX
.br
.I PREFIX
=
.I PATHNAME
.br
.LP
If the name of the current source file begins with the specified
\fIprefix\fP, then  the prefix is replaced with the specified
\fIpathname\fP to form the name of the substitute file.
If the \fIprefix\fP is not specified, the the name of the root source
directory (as specified on the command line) is used.

.SH CONDITIONS
The following conditions are available.
These may be combined by the operators \fB&\fP, \fB|\fP,
\fB!\fP and \fB()\fP with the usual meaning and precedence.
Conditions are evaluated in order, so it is usually better to include
less costly conditions (such as ownership tests) before more
complicated conditions (such as those involving regular expressions).
.LP
Where the condition involves testing the status of a file then, by
default, the test is performed on the source file, if it exists,
otherwise it is performed on the destination file.
All conditions except \fBname\fP and \fBpath\fP allow a substitute
filename to be specified by including a substitute file specification,
in square brackets, immediately after the keyword.
If the file does not exist, then the condition \fBtype=missing\fP will
be true.
.TP
\fBaccess>\fP\fIage\fP (or \fBaccess=\fP\fIage\fP, or \fBaccess<\fP\fIage\fP)
.br
True if the time since the file was last accessed is greater
than (or equal to, or less than) \fIage\fP.
The \fIage\fP should be a number, optionally followed (without a space)
by \fBmins\fP, \fBhrs\fP, \fBdays\fP or \fBwks\fP (default minutes).
A filename can also be supplied for \fIage\fP, in which case the age
of the file is compared with the age of the specified file.
.TP
\fBexists\fP
.br
This condition is equivalent to \fBtype!=missing\fP.
.TP
\fBage>\fP\fIage\fP (or \fBage=\fP\fIage\fP, or \fBage<\fP\fIage\fP)
.br
True if the age (based on last modified time) of the file is greater
than (or equal to, or less than) \fIage\fP.
The \fIage\fP should be a number, optionally followed (without a space)
by \fBmins\fP, \fBhrs\fP, \fBdays\fP or \fBwks\fP (default minutes).
A filename can also be supplied for \fIage\fP, in which case the age
of the file is compared with the age of the specified file.
.TP
\fBmode=\fP\fImode\fP
.br
The \fImode\fP specification has the form \fBoug+rwxs\fP or
\fBoug-rwxs\fP, where any combination of \fBoug\fP and \fBrwxs\fP
may be specified.
This expression evaluates to true if the file has the specified mode
bits enabled (\fB+\fP), or disabled (\fB-\fP).
More than one \fImode\fP specification may be given by separating them
with commas (no spaces).
.TP
\fBname=@\fP\fIlist\fP
.br
The file \fIlist\fP should be a list of filenames, with one filename
per line (not regular expressions).
This expression evaluates to \fBtrue\fP if the name of the file is
contained in the list.
The \fIlist\fP may contain comment lines beginning with \fB#\fP.
.TP
\fBname=\fP\fIregexp\fP
.br
Evaluates to \fBtrue\fP if the name of the file matches the the
regular expression \fIregexp\fP (see \s-1REGULAR EXPRESSION SYNTAX\s+1).
Note that this is simply the name of the file, rather than the full
pathname.
.TP
\fBowner=@/\fP\fIpathname\fP
.br
\fIPathname\fP should specify the name of a file containing a list of
usernames, with one username per line.
This condition evaluates to \fBtrue\fP if the owner of the file is
a member of the list.
.TP
\fBowner=@\fP\fInetgroup\fP
.br
Evaluates to \fBtrue\fP if the owner of the file is a member of
the \fInetgroup\fP.
If the netgroup entry for the owner has a domain component specified,
then the match is only true if this domain matches the current domain.
By default, the current domain is set from the default NIS domain, but
it can be overridden with the \fB-d\fP option.
.TP
\fBowner=\fP\fIuser\fP
.br
Evaluates to \fBtrue\fP if \fIuser\fP is the owner of the file.
\fIuser\fP may be a user name, or a numeric user id.
.TP
\fBpath=@\fP\fIlist\fP
.br
The file \fIlist\fP should be a list of pathnames, with one pathname
per line (not regular expressions).
This expression evaluates to \fBtrue\fP if the pathname of the file is
contained in the list.
Note that the pathname is relative to the source directory specified
on the command line (without a leading /).
The \fIlist\fP may contain comment lines beginning with \fB#\fP.
.TP
\fBreboot\fP
.br
This condition evaluates to \fBTrue\fP if the system has been rebooted
since the file was last modified.
This can be useful for purging a filesystem of .\s-1BUSY\s+1 files
(see \fBkeep\fP) after a system has been rebooted.
.TP
\fBpath=\fP\fIregexp\fP
.br
Evaluates to \fBtrue\fP if the pathname of the file matches the the
regular expression \fIregexp\fP (see \s-1REGULAR EXPRESSION SYNTAX\s+1).
Note that the pathname is relative to the source directory specified
on the command line (without a leading /).
.TP
\fBsize>\fP\fIsize\fP (or \fBsize=\fP\fIsize\fP, or \fBsize<\fP\fIsize\fP)
.br
True if the size of the file is greater
than (or equal to, or less than) \fIsize\fP.
The \fIsize\fP should be a number, optionally followed (without a space)
by \fBk\fP (Kb), \fBb\fP (blocks), or \fBm\fP (Mb) (default in bytes).
A filename can also be supplied for \fIsize\fP, in which case the size
of the file is compared with the size of the specified file.
.TP
\fBtype=\fP\fIfiletype\fP
.br
True if the type of the file is \fIfiletype\fP, where \fIfiletype\fP
is one of \fBdir\fP, \fBfile\fP, \fBbdev\fP, \fBcdev\fP, \fBsock\fP,
\fBpipe\fP, \fBlink\fP or \fBmissing\fP.

.SH ACTIONS
The following actions set the basic type of the file update.
Specifying one type, overrides the others:
.TP
\fBupdate\fP
.br
This is the default action.
The destination file is deleted, copied and status changed as
necessary to make it match the source.
Note that the contents of the file are not examined, and the
file will only be copied if the destination does not exist, or if
the destination is older than the source.
.TP
\fBignore\fP
.br
If this action is specified, files are simply ignored. ie. they are
never deleted from the destination, or copied from the source, nor do
they have their status changed in any way.
.TP
\fBpreserve\fP
.br
This action is similar to \fBupdate\fP except that destination files
with no corresponding source file are not deleted.
.TP
\fBdelete\fP
.br
If this action is specified, then the destination is simply deleted
and never updated from the source.
.LP
The following actions specify additional independent options.
These options can be disabled by using a tilde followed by
the action keyword.
.TP
\fBauto\fP \fIdir-list\fP
.br
Normally, lfu will not reliably traverse automount points because the
subdirectories will not be visible in the directory unless they have
recently been automounted.
If the \fBauto\fP action is specified, then the the given list of
subdirectories will be processed, in preference to reading the
subdirectory list from the directory itself.
The \fIdir-list\fP specification has the form \fBsrc-list/dst-list\fP 
where \fBsrc-list\fP and \fBdst-list\fP are comma separated lists of
automounted subdirectories on the source and destination filesystems
respectively.
Either of the two lists may be empty in which case the corresponding
directory is assumed not to be automounted.
This action is never inherited and an implicit \fBfollow\fP action is
performed on the subdirectories themselves.
A non-fatal error occurs for any any specified subdirectories which do
not exist; this prevents the destination filesystem from being
completely deleted when an automount fails on the source filesystem.
.if 'yes'yes' \{.TP
\fBcache\fP \fIpriority\fP
.br
This specifies that the object is to be \fIcached\fP (see \s-1CACHING\s+1).
The optional numeric \fIpriority\fP is used to increase the cache
precedence of the object. \}
.if 'yes'yes' \{.TP
\fBcachefile\fP \fIname\fP
.br
This sets the name of the file used to store cache priorities between
successive runs (See \s-1CACHING\s+1).
The default name is based on the name of the destination filesystem
and stored in the directory \fB/var/tmp\fP.
The \fBmtime\fP of the file is important and is used as the timestamp
for the last update.
This action is a global option and must appear inside a \fBdefault\fP
statement. \}
.if 'yes'yes' \{.TP
\fBcachefill\fP
.br
This sets the \fIcachefill\fP cache parameter (See \s-1CACHING\s+1).
This action is a global option and must appear inside a \fBdefault\fP
statement. \}
.if 'yes'yes' \{.TP
\fBcacheminsize\fP \fIsize\fP
.br
This sets the \fIcacheminsize\fP cache parameter (See \s-1CACHING\s+1).
This action is a global option and must appear inside a \fBdefault\fP
statement. \}
.if 'yes'yes' \{.TP
\fBcacheminvalue\fP \fIlevel\fP
.br
This sets the \fIcacheminvalue\fP cache parameter (See \s-1CACHING\s+1).
This action is a global option and must appear inside a \fBdefault\fP
statement. \}
.TP
\fBcdf\fP
.br
If the current object is a directory (or an \s-1HP/UX CDF\s+1) then this
action specifies that any \s-1HP/UX CDF\s+1s found in the directory (and by
inheritance in any descendants) should be copied completely, rather
than simply copying the current context.
Notice that specifying this action for an object will \fInot\fP cause
the object itself to be copied if it is a \s-1CDF\s+1 - this is because the
evaluation of the condition on the entire \s-1CDF\s+1 may be different from
the evaluation on an individual context.
.TP
\fBchgrp\fP \fIgroup\fP
.br
Change the group of the destination file to \fIgroup\fP.
.TP
\fBchmod\fP \fImode\fP
.br
Change the permissions on a file when it is updated.
The \fImode\fP specification has the form \fBoug+rwxs\fP or
\fBoug-rwxs\fP, where any combination of \fBoug\fP and \fBrwxs\fP
may be specified.
More than one \fImode\fP specification may be given by separating them
with commas.
.TP
\fBchown\fP \fIowner\fP
.br
Change the owner of the destination file to \fIowner\fP.
.TP
\fBcompress\fP
.br
This action causes lfu to attempt to create holes in any file. This
can reduce the size of any files containing significant blocks of
zeros (eg. a file which originally had holes, but had been filled in
by the ordinary \fBcp\fP command).
.TP
\fBerror\fP \fImessage\fP
.br
Any attempt to update or delete a file with this action specified
will generate an error with the specified message.
An implicit \fBignore\fP action is performed on the file.
.TP
\fBexec\fP \fIcommand\fP
.br
If the file is modified, then schedule the shell \fIcommand\fP
for execution at the end of the job.
The command may include the variable \fB$F\fP which will be
substituted with the name of the current file.
If exactly the same command is scheduled several times, it is executed
only once.
.TP
\fBfill\fP
.br
Normally lfu attempts to recognise files with "holes" in them and 
duplicate the holes when updating files. (A file is assumed to
have holes if the number of occupied disk blocks is less than would
be expected from the size of the file). This action inhibits the
duplication of the holes.
.TP
\fBfollow\fP
.br
If this action is applied to a symbolic link, then the link will 
become "transparent" and lfu will behave as if the link had been
replaced by the object at which it is pointing.
.TP
\fBforce\fP
.br
If \fBupdate\fP or \fBpreserve\fP are specified, ignore the ages of
the files and force the source file to be copied onto the destination.
.TP
\fBinherit\fP
.br
This action is enabled by default.
It means that actions assigned to a directory are inherited as
the default actions for all descendants.
If it often useful to disable this feature, for example when setting
\fBfollow\fP on an individual directory.
.TP
\fBkeep\fP
.br
If this action is specified, the file will be renamed with an
extension of .\s-1BUSY\s+1.nnn whenever it would normally be deleted.
This is useful when updating binaries that are liable to be in use
at the time of the update.
\s-1HP/UX\s+1 (and possibly other systems) generate an \s-1ETXTBSY\s+1
error when attempting to delete the text of a running binary.
If this happens, then lfu performs a \fBkeep\fP action by default.
.TP
\fBlink\fI
.br
If this option is specified, then rather than copying directories
to the destination, they are symbolically linked.
By default, files are copied, but linking can be specified with the
\fBshadow\fP action.
.TP
\fBlog\fP
.br
Log any changes to this file.
Changes to file attributes are only reported when the file itself is not
changed.
Changes to directory \fBmtime\fPs are never reported since these occur
whenever a directory entry is deleted or created.
.TP
\fBlogall\fP
.br
Log the results of any examination of this file, even if there are no
changes.
.TP
\fBnewer\fP
.br
By default, an error occurs and the destination file is not
overwritten if the destination file is strictly newer than the source
file.
This action suppresses the error message and overwrites a newer
destination file with the older source file.
.TP
\fBnewtime\fP
.br
Do not reset the modification time of the destination file to match the
source file.
.TP
\fBnoidcheck\fP
.br
This action inhibits the changing of the destination uid/gid to match
the source uid/gid.
.TP
\fBnomount\fP
.br
This action prevents lfu from descending below mount points in the
source directory.
An implicit \fBignore\fP action is performed for any object below a
directory which has a different device number from its parent.
The \fBnomount\fP action is a global option and cannot occur within a
conditional or compound statement.
.TP
\fBshadow\fP
.br
If this option is specified, then rather than copying files
to the destination, they are symbolically linked.
By default, directories are replicated, but linking can be specified with the
\fBlink\fP action.
.TP
\fBsource \fP\fIsubstitute\fP
.br
If this action is specified, then any links created by the shadow or
link commands will point to the specified substitute file, rather than
the corresponding source file.
.TP
\fBstats\fP
.br
Statistics will be collected for all objects with this action
specified.
After performing the update, lfu prints a table on the standard output.
For each owner, the total disk space used and the total number of
files are listed, both before and after the update operation.
User names will be prefixed with a "+" or "-" if the update has
generated an increase or decrease in the amount of disk space for that
user.
The disk space is rounded up to the nearest 1Mb.
.if 'yes'yes' \{.br
If the program contains any cache actions, then cache statistics are
also printed.
For each user, the number of cache links and files is shown.
Cache files which have been accessed since the last update are considered
cache \fIhits\fP, and cache links which have been accessed since
the last update are considered \fImisses\fP; these are used to compute
a cache \fIhit-rate\fP. \}
.TP
\fBwarn\fP \fImessage\fP
.br
Any attempt to update or delete a file with this action specified
will generate an warning with the specified message.
Unlike the \fBerror\fP action, a \fBwarn\fP does not prevent the
update (or delete) from taking place.
Warning messages are only printed if they are enabled with the
\fB-w\fP option.

.if 'yes'yes' \{.SH "CACHING"
The \fBcache\fP action specifies that a source file should be copied
onto the destination as long as there is room on the filesystem.
If the filesystem is full, then an implicit \fBlink\fP action is
performed instead.
.PP
Normally, some, but not all, of the specified cache files will fit
onto the destination.
In this case the files to be copied are chosen in order of
\fIcache-value\fP which is computed as follows:-
.IP \(bu 3
Each time lfu is run, the \fBatime\fP of each file is examined to
determine whether or not it has been accessed since the last run.
This information is recorded in a file for the most recent 19 runs,
and the \fIusage\fP is the number of times (out of 19) for which a
file access occurred.
.IP \(bu 3
The file comparison is then based on:-
.IP " " 5
\fIcache-value\fP = 10 * \fIusage\fP + \fIpriority\fP
.IP " " 3
Where \fIpriority\fP is the value specified in the \fBcache\fP action
(default=0, max=999).
.PP
If lfu is run nightly, for example, then the following properties hold:-
.IP \(bu 3
By default, precedence is given to those files accessed on most of the
previous 19 days.
.IP \(bu 3
Files with a priority of less than 10 are given precedence over files
with a lower priority only when the files have been accessed the same
number of times.
.IP \(bu 3
Files with a priority of 30 are given equal precedence with files that
have been accessed on three occasions more often.
.IP \(bu 3
Files with a priority of greater than 200 are always given precedence
over files with a precedence of 0.
.PP
If two files have the same cache value, then the most recently
accessed is given precedence.
If the most recent access is also the same, then smaller files are
given precedence.
.PP
The following parameters also affect the behaviour of the cache and
can be modified with the corresponding actions:
.TP
\fBcacheminsize\fP
.br
This specifies a filesize.
Files of smaller than this size are always copied, rather than being
linked.
The filesize can be specified in Mb (m), Kb (k) or blocks (b) (default
is blocks). 
The default value is 3 blocks, and this is the recommended minimum
since the symbolic links themselves occupy 2 blocks on many filesystems.
.TP
\fBcacheminvalue\fP
.br
Files with a smaller cache value than \fBcacheminvalue\fP are never
automatically converted from links to copies.
The default value is 15, which implies that files are only brought
into the cache if they have been accessed more than once.
.TP
\fBcachefill\fP
.br
If this parameter is set then an attempt is made to convert as many
links as possible into files.
This produces an unstable situation which can cause files to be deleted
and recreated on successive runs, even if the source filesystem has not changed.
\fBcachefill\fP is disabled by default.
.PP
Caching is only applied to regular files.
The actions \fBkeep\fP, \fBfollow\fP, \fBfill\fP and \fBforce\fP can
interfere with the caching action and caching is disabled for any file
which has one of these actions specified.
\}
.SH "REGULAR EXPRESSION SYNTAX"
The regular expression matching is performed by the public domain
\fBregexp\fP implementation from Henry Spencer of Toronto.
This is compatible with Unix V8 \fIregexp(3)\fP syntax, as follows.
Note that '\e' is the escape character both for \fBlfu\fP strings and
for regular expressions, so that two '\e' characters are necessary to
include regular expression meta characters as a literal.
.PP
A regular expression is zero or more \fIbranches\fR, separated by `|'.
It matches anything that matches one of the branches.
.PP
A branch is zero or more \fIpieces\fR, concatenated.
It matches a match for the first, followed by a match for the second, etc.
.PP
A piece is an \fIatom\fR possibly followed by `*', `+', or `?'.
An atom followed by `*' matches a sequence of 0 or more matches of the atom.
An atom followed by `+' matches a sequence of 1 or more matches of the atom.
An atom followed by `?' matches a match of the atom, or the null string.
.PP
An atom is a regular expression in parentheses (matching a match for the
regular expression), a \fIrange\fR (see below), `.'
(matching any single character), `^' (matching the null string at the
beginning of the input string), `$' (matching the null string at the
end of the input string), a `\e' followed by a single character (matching
that character), or a single character with no other significance
(matching that character).
.PP
A \fIrange\fR is a sequence of characters enclosed in `[]'.
It normally matches any single character from the sequence.
If the sequence begins with `^',
it matches any single character \fInot\fR from the rest of the sequence.
If two characters in the sequence are separated by `\-', this is shorthand
for the full list of ASCII characters between them
(e.g. `[0-9]' matches any decimal digit).
To include a literal `]' in the sequence, make it the first character
(following a possible `^').
To include a literal `\-', make it the first or last character.

.SH COMMAND LINE OPTIONS
The following command line options are available:
.if 'yes'yes' \{.TP
\fB-a\fP
This option disables the communication with the \fBamd\fP
automounter that is performed by default when determining full
pathnames for the source and destination. \}
.if 'yes'yes' \{.TP
\fB-A\fP \fIdirectory\fP
.br
Use \fIdirectory\fP for holding information on usage of cached files
between sucessive runs.
The default is \fB/var/tmp\fP. \}
.TP
\fB-c\fP
This option starts a monitor program which displays the progress of
the update (see below).
.TP
\fB-C\fP
By default, lfu reads and compares the contents of all symbolic links
when deciding whether to update them.
This is only strictly necessary when some files that were previously
being copied are changed to being linked, or visa-versa (in all other
cases, the modification time of the link gives an accurate indication
of which links need updating).
The \fB-C\fP option disables the comparison of link contents which
improves the speed of the update slightly and avoids changing the last
access time of the link.
.TP
\fB-d\fP \fIdomain\fP
Use \fIdomain\fP as the current domain name, rather than the default
NIS domain name.
.TP
\fB-D\fP \fIsymbol\fP=\fIvalue\fP
This option is passed to the C preprocessor, so that the \fIsymbol\fP
is assigned the specified \fIvalue\fP.
.TP
\fB-e\fP \fIstatements\fP
Include \fIstatements\fP in the program to be executed.
More than one \fB-e\fP option may be specified, in which case, they
are executed in order, before the statements in the program file (if any).
.TP
\fB-f\fP
This option is equivalent to the program "\fBforce;\fP".
.TP
\fB-H\fP
This option is equivalent to the program "\fBcdf;\fP".
.TP
\fB-I\fP \fIdirectory\fP
This option is passed to the C preprocessor, so that the given
\fIdirectory\fP is searched for any files specified in
\fB#include\fP directives.
.TP
\fB-l\fP
This option is equivalent to the program "\fBshadow;\fP".
.TP
\fB-m\fP
This option is equivalent to the program "\fBnomount\fP".
.TP
\fB-o\fP
If \fImy_user\fP and \fImy_group\fP are the effective user and
effective group of the current process, then this option is
equivalent to the program
.br
.RS
.IP
"\fBchown\fP \fImy_user\fP\fB; chgrp\fP \fImy_group\fP\fB;\fP"
.RE
.TP
\fB-p\fP
This option is equivalent to the program "\fBpreserve;\fP".
.TP
\fB-P\fP \fIpreprocessor\fP
This option specifies a colon-separated list of preprocessors.
The source program will be preprocessed by the first found program in
the list.
Arguments can be supplied for a preprocessor by separating them with
commas.
The default list is:-
/usr/lib/cpp:/lib/cpp:/usr/local/lib/gcc/gcc-cpp:/bin/cc,-E:/bin/cat
.TP
\fB-r\fP
By default, lfu only reports the first error that it encounters
involving access permissions, since whenever one permission error
occurs, it is likely that there will be many similar ones.
This option forces reporting of all access permission errors.
.TP
\fB-s\fP
This option is equivalent to the program "\fBstats;\fP".
.TP
\fB-S\fP
This options causes lfu to print information about the runtime and
memory usage.
.TP
\fB-v\fP
This option is equivalent to the program "\fBlog;\fP".
.TP
\fB-V\fP
Print version number and exit immediately.
.TP
\fB-w\fP
Print warning messages.
.if 'yes'yes' \{.TP
\fB-X\fP \fIoptions\fP
This option is only available if \fBlfu\fP has been compiled with the
.SM -DDEBUG
flag.
The \fIoptions\fP specify a comma-separated list of debugging flags
as follows:-
.RS .5i
.IP \fBage\fP 8
Print ages of files being compared with any \fBage\fP condition.
.IP \fBcache\fP 8
Print cache debugging statements.
.IP \fBinput\fP 8
Print program file.
This is useful to see the effect of the preprocessor on the input file.
.IP \fBline\fP 8
Print the source line number of the generating statement with each log
message.
.IP \fBparse\fP 8
Exit after parsing the input file, without performing the update.
.IP \fBpath\fP 8
Print substitute pathnames.
.IP \fBscan\fP 8
Print each token recognised by the program scanner.
.RE 0 \}

.SH EXIT STATUS
.IP 0 3
No errors.
.IP 1 3
Fatal error detected.
.IP 2 3
Non-fatal errors detected.
.IP 3 3
Program interrupted.

.SH THE MONITOR
\fBlfu\fP can pass information on the files being processed to a separate
monitor program, enabling the progress of the update to be monitored.
.if 'yes'yes' \{
The default monitor is \fB/usr/local/lib/xlfumon\fP which is an
X-based program that requires lfu to be running with a valid
\s-1\fBDISPLAY\fP\s+1 variable.
\fBxlfumon\fP is constructed with the Athena Widget set and accepts the
standard toolkit resource specifications.
The resource name is \fBlfu\fP and the class name is \fBLfu\fP.
.LP
A different monitor program can be specified by setting the
environment variable \s-1\fBLFUMON\fP\s+1.
No alternative monitors are currently available, but the protocol used
to communicate with the monitor program is described in the source for
xlfumon.
.LP
\fBxlfumon\fP opens a window which shows the file currently being
examined, and the following actions are provided by buttons:-
.TP
\fBFast/Slow\fP
.br
The display updates continuously showing all files processed, or
updates just once per second.
The default value of \fBFast\fP, can be changed by setting
the X resource \fBFast\fP to \fBFalse\fP.
.TP
\fBShow All/Show Changes\fP
.br
The display shows all files visited or just those files which are
being changed.
The default value of \fBShow All\fP can be changed by setting
the X resource \fBAll\fP to \fBFalse\fP.
.TP
\fBClose\fP
.br
Terminate the monitor, but continue with the update.
.TP
\fBQuit\fP
.br
Abort the update.
.LP
A running total of files visited (including both source and destination
files) is shown, as well as a running total of any errors encountered.
.LP
Iconifying the monitor will suspend output of monitor information and
may increase the speed of the update. \}
.LP
A monitor can be started on an existing lfu process by sending a
\s-1\fBSIGUSR1\fP\s+1 signal to the process (usually kill -30, or
kill -16 on HP/UX).

.SH EXAMPLES
Copy the source to the destination, omitting all files owned by root,
unless they are in the list contained in the file \fBrootfiles\fP,
in which case they are copied and the suid bit is set.
.IP
.KS
\fBowner=root { name=@rootfiles chmod u+s; else delete; }\fP
.br
.KE
.LP
Copy the source to the destination logging all changes.
Delete files owned by members of the netgroup \fBstudents\fP without
logging.
Link files owned by \fBtex\fP to the corresponding files in the
directory \fB/home/tex\fP.
Mail the system manager if any of the files owned by root are changed.
If any of the files in the list \fBdaemons\fP need to be deleted,
rename the existing copies, rather than deleting them.
Keep any existing busy files created within the last week.
.IP
.KS
\fBdefault { log; }\fP
.br
\fBowner=@students { delete; ~log; }\fP
.br
\fBelse owner=tex { link; shadow; source /home/tex; }\fP
.br
\fBelse owner=root exec "echo $F updated |mail sysman";\fP
.br
\fBname=@daemons keep;\fP
.br
\fBname=.*\e.BUSY\e..* & age<1wks preserve;\fP
.KE

.SH FILES
.TP
\fB/usr/local/lib/xlfumon\fP
.br
The monitor program.
.if 'yes'yes' \{.TP
\fB/var/tmp/lfu-cache.\fP\fIfile-system\fP
.br
The cache history for the specified \fIfile-system\fP. \}

.SH BUGS
The \fBatime\fP for symbolic links cannot be correctly duplicated
because there appears to be no way of resetting this value for a
symbolic link.  Symbolic links are created with a current \fBatime\fP,
exactly as if a \fBnewtime\fP action had been specified.  Changing the
mode of an existing symbolic link and (on some systems) the ownership
is not possible either, although it would be possible to delete and
recreate the link with the correct attributes.  In the current
version, the attributes are simply not changed and a warning message
is generated.
.LP
Normally lfu attempts to recognise files which are hard linked in the
source and duplicate the links in the destination.
In one particular case, if a file is deleted in the source and
replaced with a hard link to another file which has not changed,
then lfu will fail to see the change.
An error message is generated stating that not all links to the file
could be found and the situation can be corrected by touching
the file and re-running.
.if '@HAVE_CACHE'yes' \{Caching of files which are hard-linked is also
difficult and non-optimal. \}
.LP
If an NFS client has a file open, the kernel will recognize attempts
to delete the file \fIfrom the same client only\fP.
In this case the file gets renamed to ".nfsxxxxxxx" and it may be
useful to avoid deleting these files, or perhaps only delete them
if they are older than a certain age.
The NFS protocol is not capable of recognizing attempts to delete
files which are open on a different machine.
.if 'yes'yes' \{If the destination filesystem is NFS mounted, then
the attribute caching in many implementations can also cause
difficulties when using the \fBcache\fP action. \}
.LP
\s-1HP/UX CDF\s+1s cannot be reliably identified in all cases and a
few obscure configurations will generate an error message indicating
that a particular object may be an unidentifiable \s-1CDF\s+1, or
cannot be copied.
Attempts to manipulate \s-1CDF\s+1s on non-\s-1HP\s+1 filesystems (eg.
over \s-1NFS\s+1) can also generate strange error conditions, and
should normally be avoided by using \fB~cdf\fP on the root of any NFS
filesystems when \fBcdf\fP is specified for a root \s-1HP/UX\s+1 filesystem.
.LP
Some filesystems (eg. \s-1HP/UX\s+1) use units other than 512 bytes
(eg. 1K) when returning filesizes in blocks.
Since there appears to be no way of determining the units for any
particular file, the statistics will be wrong when the -s option is
used on any such filesystem.
Some systems (eg. SGI) have no st_blocks field in the stat structure.
This means that there is no way of finding the actual disk space used by
sparse files.
In this case, sparse files may cause problems when caching and will
produce misleading statistics.
.LP
The monitor program uses signals to communicate with the running lfu
program and will occasionally cause an "interrupted system call" error
on some platforms.
.SH COPYRIGHT
.nf
Copyright (c) 1992 by the University of Edinburgh
Laboratory for the Foundations of Computer Science
Department of Computer Science
Written by Paul Anderson.
.fi
.LP
Permission is granted to anyone to use this software for any
purpose on any computer system, and to redistribute it freely,
subject to the following restrictions:
.IP \(bu 3
The University of Edinburgh makes no representations about the
suitability of this software for any purpose.  It is
provided "as is" without express or implied warranty.
.IP \(bu 3
The origin of this software must not be misrepresented, either by
explicit claim or by omission, and this copyright notice must appear in
all copies of the software. Altered versions must be plainly marked
as such, and must not be misrepresented as being the original software.
.IP \(bu 3
The name of the University of Edinburgh must not be used in
advertising or publicity pertaining to distribution of the software
without specific, written prior permission.