.\" $Id: purge.man,v 8.14 2012/09/05 23:21:50 ksb Exp $
.\" by Kevin Braunsdorf
.\" $Compile: Display%h
.\" $Display: ${groff-groff} -Tascii -tbl -man %f | ${PAGER:-less}
.\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man8/purge.8
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]8/purge.8*
.TH PURGE 8 LOCAL
.SH NAME
purge - remove outdated backup copies of installed programs
.SH SYNOPSIS
.ds PN "purge
\fI\*(PN\fP [\fB\-ASnv\fP] [\fB\-d\fP\~\fIdays\fP] [\fB\-u\fP\~\fIuser\fP] [\fIdirs\fP|\fIfiles\fP]
.br
\fI\*(PN\fP \fB-h\fP
.br
\fI\*(PN\fP \fB-V\fP
.br
.SH DESCRIPTION
.PP
\fIPurge\fP removes backup files that are more than \fIdays\fP old from
OLD directories created by \fBinstall\fP(1l).  \fIPurge\fP locates the
OLD directories by recursively descending \fIdirs\fP selecting directories
named \*(lqOLD\*(rq that the invoker owns.
.PP
\fIPurge\fP does not remove backup files with multiple hard links if it
cannot find all the links.
This is an indication that a product was installed without
regard for multiple names (\fBinstall\fP warns the installer in
such cases, but the error message may have been inadvertently ignored).
\fIPurge\fP directs the maintainer to run \fBinstck\fP(8l)
to correct any such problems.
.PP
In the case where a single target file has been \fBinstall\fPed so
many times that the backup files are an issue the \fIfiles\fP parameter
may be specified as the target file's path.  In this case \fI\*(PN\fP
only removes likely backups of each of those files.  Actually \fIfiles\fP
and \fIdirs\fP may be intermixed.
.PP
In another corner case \fI\*(PN\fP may read \fIstdin\fP for a list
of \fIdirs\fP, this is deprecated in favor of using \fBxapply\fP or
\fBxargs\fP to process the stream.
.\" with a dir of dash
.SH OPTIONS
.TP
.nf
\fB\-A\fP
.fi
Allow OLD directories owned by any user to be searched for out-of-date
backup files.  This is usually not a good idea on a home directory
partition, as nieve customers my name a directory \*(lqOLD\*(rq.
.TP
.nf
\fB\-d\fP \fIdays\fP
.fi
Days to keep backup files (default 14).
Older versions of \fI\*(PN\fP
expected this parameter in place of \fIdirs\fP, which was a botch.
.TP
.nf
\fB\-h\fP
.fi
Print a help message.
.TP
.nf
\fB\-n\fP
.fi
Do not really execute commands, output what would be done (see \fB\-v\fP).
.TP
.nf
\fB\-S\fP
.fi
Run as if we are the superuser.
In combination with \fB\-n\fP this allows a system administrator to
see what \fI\*(PN\fP would do when run as root.
.TP
.nf
\fB\-u\fP \fIuser\fP
.fi
OLD directories may (also) be owned by this user.
.TP
.nf
\fB\-v\fP
.fi
Be verbose by showing approximate actions as shell commands.
.TP
.nf
\fB\-V\fP
.fi
Show version information.

.SH EXAMPLES
.TP
.nf
\fI\*(PN\fP \-v \-d7 $HOME/bin
.fi
Remove any backup files from my bin which are older than one week.
.TP
.nf
\fI\*(PN\fP \-Sn /bin/OLD
.fi
Show which files \fI\*(PN\fP would remove from /bin's OLD directory.
.TP
.nf
\fI\*(PN\fP \-u news \-u uucp \-u adm \-u lp /
.fi
When run as root, cleanse all system OLD directories on this machine.
.TP
.nf
\fI\*(PN\fP \-Sn /bin/OLD
.fi
Show which files \fI\*(PN\fP would remove from /bin's OLD directory.
.TP
.nf
\fI\*(PN\fP \-Sn \-d0 /etc/group
.fi
Show all files \fI\*(PN\fP would remove as backups of \fB/etc/group\fP.
.TP
.nf
\fI\*(PN\fP \-V
.fi
Output \fI\*(PN\fP's version information, eg.:
.sp 1
.nf
\*(PN: $\&Id: purge.c,v 8.10 2012/02/15 16:25:00 ksb Exp $
\*(PN: default superuser login name: root
\*(PN: backup directory name: OLD
\*(PN: valid backup directory owner: root
.fi
.SH BUGS
.PP
\fIPurge\fP does not cross mount points.
.PP
This version of \fI\*(PN\fP is slightly incompatible with the shell script.
.PP
The code to process backups for a single target could removed files
of another target in some cases, but it much safer than \fBrm\fP with
a star-based glob expression.  Any backup file must match by name, mode,
and not exist as a potential target file.
.PP
There is no way to safely remove an OLD directory, as one might race
with a running copy of \fBinstall\fP, \fBinstallus\fP or \fBvinst\fP,
or fail to remove multiply linked or busy files.
This is a close as we can get:
.RS
.nf
\fI\*(PN\fP \-d0 $OLD
rmdir $OLD
.fi
.RE

.SH AUTHOR
David L Stevens, Purdue UNIX Group (original script version)
.br
Kevin Braunsdorf, Purdue UNIX Group, purge at ksb.npcguild.orgSPAMfix
.SH "SEE ALSO"
.hlm 0
install(1l), instck(8l), rm(1), sh(1), installus(1l), vinst(1l)