usr.sbin/clog/clog.8

   1 .\" Copyright (c) 2001
   2 .\"     Jeffrey D. Wheelhouse.  All rights reserved.
   3 .\"
   4 .\" This code was originally developed by Jeff Wheelhouse (jdw@wwwi.com).
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY JEFF WHEELHOUSE ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN
  18 .\" NO EVENT SHALL JEFF WHEELHOUSE BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING BUT NOT
  20 .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
  21 .\" OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  22 .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  23 .\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  24 .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .\" $Id: clog.8,v 1.2 2001/10/02 04:41:21 jdw Exp $
  27 .\" $DragonFly: src/usr.sbin/clog/clog.8,v 1.1 2004/10/30 20:26:46 dillon Exp $
  28 .\"
  29 .Dd October 1, 2001
  30 .Dt CLOG 8
  31 .Os BSD 4
  32 .Sh NAME
  33 .Nm clog
  34 .Nd "display or initialize a circular system log"
  35 .Sh SYNOPSIS
  36 .Nm
  37 .Op Fl f
  38 .Op Fl i Fl s Ar size
  39 .Ar logfile
  40 .Sh DESCRIPTION
  41 .Nm Clog
  42 displays or initializes a circular log file.
  43 .Pp
  44 The options are as follows:
  45 .Bl -tag -width indent
  46 .It Fl f
  47 Display the contents of the circular logfile
  48 .Ar logfile ,
  49 then go into a loop waiting for
  50 new material to arrive.  This is essentially the same as using the
  51 .Fl f
  52 option of the
  53 .Xr tail 1
  54 command on a standard syslog file.
  55 .It Fl i
  56 Initialize
  57 .Ar logfile
  58 rather than reading it.  This option requires the
  59 .Fl s
  60 option.  If
  61 .Ar logfile
  62 already exists, it will be truncated and recreated by this command.
  63 .It Fl s
  64 This option specifies the size in bytes of the circular logfile that should
  65 be created.  This option requires the
  66 .Fl i
  67 option.
  68 .El
  69 .Sh ABOUT CIRCULAR LOGFILES
  70 The
  71 .Nm
  72 command supports circular logfiles for
  73 .Xr syslogd 8 .
  74 A circular logfile differs from a standard syslog file in that is has a fixed
  75 size.  It does not grow, and does not need to be rotated.  When
  76 .Xr syslogd 8
  77 reaches the end of a circular logfile, it simply begins again at the beginning,
  78 overwriting the oldest data.  The circular logfile also contains information
  79 allowing
  80 .Nm
  81 to establish what parts of the file are valid, and in what order they should
  82 be displayed.
  83 .Pp
  84 Circular logfiles are primarily useful for their ability to control the amount
  85 of storage devoted to logfiles.  This may be valuable when storage space is
  86 at a premium or when the consequences of running out of storage space are
  87 unacceptable.  Circular logfiles can safely be used on a memory disk (see
  88 .Xr md 4 ).
  89 .Pp
  90 Circular logfiles are also useful to catch messages that are generated rapidly
  91 but soon lose relevance, such as messages logged at debug priority.
  92
  93 .Sh SEE ALSO
  94 .Xr syslogd 8 ,
  95 .Xr syslog.conf 5
  96 .Sh HISTORY
  97 The
  98 .Nm
  99 command was written for FreeBSD 4.3 but is not yet part of a BSD distribution.