.\" Copyright (c) 2001
.\"	Jeffrey D. Wheelhouse.  All rights reserved.
.\"
.\" This code was originally developed by Jeff Wheelhouse (jdw@wwwi.com).
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY JEFF WHEELHOUSE ``AS IS'' AND ANY EXPRESS OR 
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN
.\" NO EVENT SHALL JEFF WHEELHOUSE BE LIABLE FOR ANY DIRECT, INDIRECT, 
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
.\" OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 
.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 
.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $Id: clog.8,v 1.2 2001/10/02 04:41:21 jdw Exp $
.\" $DragonFly: src/usr.sbin/clog/clog.8,v 1.2 2004/12/26 12:37:08 swildner Exp $
.\"
.Dd October 1, 2001
.Dt CLOG 8
.Os BSD 4
.Sh NAME
.Nm clog
.Nd "display or initialize a circular system log"
.Sh SYNOPSIS
.Nm
.Op Fl f
.Op Fl i Fl s Ar size
.Ar logfile
.Sh DESCRIPTION
.Nm Clog
displays or initializes a circular log file.
.Pp
The options are as follows:
.Bl -tag -width indent
.It Fl f
Display the contents of the circular logfile
.Ar logfile ,
then go into a loop waiting for
new material to arrive.  This is essentially the same as using the
.Fl f
option of the 
.Xr tail 1
command on a standard syslog file.
.It Fl i
Initialize 
.Ar logfile
rather than reading it.  This option requires the 
.Fl s
option.  If 
.Ar logfile
already exists, it will be truncated and recreated by this command.
.It Fl s
This option specifies the size in bytes of the circular logfile that should 
be created.  This option requires the
.Fl i
option.
.El
.Sh ABOUT CIRCULAR LOGFILES
The
.Nm
command supports circular logfiles for 
.Xr syslogd 8 .
A circular logfile differs from a standard syslog file in that is has a fixed
size.  It does not grow, and does not need to be rotated.  When 
.Xr syslogd 8 
reaches the end of a circular logfile, it simply begins again at the beginning,
overwriting the oldest data.  The circular logfile also contains information 
allowing 
.Nm
to establish what parts of the file are valid, and in what order they should
be displayed.
.Pp
Circular logfiles are primarily useful for their ability to control the amount
of storage devoted to logfiles.  This may be valuable when storage space is 
at a premium or when the consequences of running out of storage space are 
unacceptable.  Circular logfiles can safely be used on a memory disk (see
.Xr md 4 ).
.Pp
Circular logfiles are also useful to catch messages that are generated rapidly
but soon lose relevance, such as messages logged at debug priority.
.Sh SEE ALSO
.Xr syslogd 8 ,
.Xr syslog.conf 5
.Sh HISTORY
The
.Nm
command was written for FreeBSD 4.3 but is not yet part of a BSD distribution.