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 .\"
  28 .Dd May 6, 2006
  29 .Dt CLOG 8
  30 .Os
  31 .Sh NAME
  32 .Nm clog
  33 .Nd display or initialize a circular system log
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Op Fl f
  37 .Op Fl i Fl s Ar size
  38 .Ar logfile
  39 .Sh DESCRIPTION
  40 .Nm
  41 displays or initializes a circular log file.
  42 .Pp
  43 The options are as follows:
  44 .Bl -tag -width indent
  45 .It Fl f
  46 Display the contents of the circular logfile
  47 .Ar logfile ,
  48 then go into a loop waiting for new material to arrive.
  49 This is essentially the same as using the
  50 .Fl f
  51 option of the
  52 .Xr tail 1
  53 command on a standard syslog file.
  54 .It Fl i
  55 Initialize
  56 .Ar logfile
  57 rather than reading it.
  58 This option requires the
  59 .Fl s
  60 option.
  61 If
  62 .Ar logfile
  63 already exists, it will be truncated and recreated by this command.
  64 .It Fl s
  65 This option specifies the size in bytes of the circular logfile that should
  66 be created.
  67 This option requires the
  68 .Fl i
  69 option.
  70 .El
  71 .Sh ABOUT CIRCULAR LOGFILES
  72 The
  73 .Nm
  74 command supports circular logfiles for
  75 .Xr syslogd 8 .
  76 A circular logfile differs from a standard syslog file in that is has a fixed
  77 size.
  78 It does not grow, and does not need to be rotated.
  79 When
  80 .Xr syslogd 8
  81 reaches the end of a circular logfile, it simply begins again at the beginning,
  82 overwriting the oldest data.
  83 The circular logfile also contains information allowing
  84 .Nm
  85 to establish what parts of the file are valid, and in what order they should
  86 be displayed.
  87 .Pp
  88 Circular logfiles are primarily useful for their ability to control the amount
  89 of storage devoted to logfiles.
  90 This may be valuable when storage space is at a premium or when the
  91 consequences of running out of storage space are unacceptable.
  92 Circular logfiles can safely be used on a memory disk (see
  93 .Xr md 4 ) .
  94 .Pp
  95 Circular logfiles are also useful to catch messages that are generated rapidly
  96 but soon lose relevance, such as messages logged at debug priority.
  97 .Sh SEE ALSO
  98 .Xr syslog.conf 5 ,
  99 .Xr syslogd 8
 100 .Sh HISTORY
 101 The
 102 .Nm
 103 command was written for
 104 .Fx 4.3
 105 and was imported into
 106 .Dx 1.1 .