.\" Copyright (C) 1999  Stanislav Shalunov.
.\" http://www.internet2.edu/~shalunov/
.\" See stmpclean.c for copyright notice and legal conditions.
.\"
.\"	$Id: stmpclean.8,v 1.6 2003/03/21 21:44:09 shalunov Exp $
.\"
.Dd August 1999
.Dt STMPCLEAN 8
.Os
.Sh NAME
.Nm stmpclean
.Nd remove old files from a world-writable directory
.Sh SYNOPSIS
.Nm stmpclean
.Op Fl "t<timespec>"
.Op Fl "v"
.Ar dir1
.Op "dir2 ..."
.Sh DESCRIPTION
The
.Nm
utility removes old files (and old empty directories) from the
specified directory.  It'll be typically used to clean directories
such as ``/tmp'' where old files tend to accumulate.
.Pp
The
.Nm
utility never removes files or directories owned by root.  It is a
feature, not a bug.
Great care is taken while descending into the directory, and the
operation is secure.
Anything that's not a directory, regular file, or symbolic link is
also left alone (because programs like
.Xr screen 1
create sockets and FIFOs under /tmp and expect them to be long-lived;
we accomodate this practice).
Unlike floating around Perl scripts that do the same task
.Nm
never forks and consumes limited amount of memory (these Perl scripts
easily turn into forking bombs when someone creates a lot a
directories under ``/tmp'').  If your system is attacked and the
attacker creates an extremely deep file hierarchy,
.Nm
won't add to the problem by crashing your system trying to remove it.
But it won't help you in fighting the attack, either, because it
descends only to a limited depth (currently, 30 levels).  If
.Nm
determines a race condition it'll log the situation (you can look for
the word ``RACE'' in log files) and exit with a failure.
.Pp
So,
.Nm
will clean temporary directories for you fine when there are no
attacks, and, when there is an attack,
.Nm
won't make the situation worse (in particular, it cannot be tricked
into removing files outside specified directories or consume unlimited
amount of resources).
.Pp
The following option is available:
.Bl -tag -width flag
.It Fl "t<timespec>"
The time specification that follows the
.Fl t
flag specifies how old a file or a directory has to be before it will
be removed.  It can be a string like `1w' (one week) or `4d5h' (four
days plus five hours) or `2m3s' (two minutes plus three seconds).  The
default is `3d' (three days).
.It Fl "v"
Be verbose: list each file deleted.
.El
.Pp
The
.Nm
utility exits 0 on success, and >0 if an error occurs.
.Sh EXAMPLES
The
.Nm
utility will typically be run nightly from
.Xr cron 8
as
.Bl -tag -width example
.It Li "stmpclean /tmp /var/tmp"
.El
.Pp
In FreeBSD
.Nm
invokation should be placed into the file
.Pa /etc/periodic/daily/110.clean-tmps .
In other versions of BSD it should go into the
.Pa /etc/daily
script.
In Linux, check if you have
.Pa /etc/periodic ,
and if not, you can just run it from cron; usually you'd have to edit
.Pa /etc/crontab .
.Sh SEE ALSO
.Xr cron 8
.Sh BUGS
When
.Nm
removes a file from a directory, modification time of the directory
changes and it looks new to
.Nm
when it examines it later (if the directory became empty).  Thus,
removing a deep hierarchy can take some time.  Notice that this only
delays removal of some empty directories.