doc/bubblegum.man

   1 .\" Copyright (C) 2002  Ben Kibbey <bjk@arbornet.org>
   2 .\"
   3 .\" This program is free software; you can redistribute it and/or modify
   4 .\" it under the terms of the GNU General Public License as published by
   5 .\" the Free Software Foundation; either version 2 of the License, or
   6 .\" (at your option) any later version.
   7 .\"
   8 .\" This program is distributed in the hope that it will be useful,
   9 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11 .\" GNU General Public License for more details.
  12 .\"
  13 .\" You should have received a copy of the GNU General Public License
  14 .\" along with this program; if not, write to the Free Software
  15 .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  16 .
  17 .Dd October 08, 2002
  18 .Os
  19 .Dt BUBBLEGUM 8
  20 .
  21 .Sh NAME
  22 .
  23 .Nm bubblegum
  24 .Nd watch files for changes
  25 .
  26 .Sh SYNOPSIS
  27 .
  28 .Nm bubblegum
  29 .Op Fl hvksq
  30 .Fl MAamcE
  31 .Op Fl l Ar logfile
  32 .Op Fl Xo 0|1|2 Xc
  33 .Oo
  34 .Op Fl e Ar command
  35 .Op Fl r Ar count | Fl t Ar count
  36 .Oc
  37 .Op Fl n Ar niceness
  38 .Op Fl i Ar seconds
  39 .Op Fl p Ar pidfile
  40 .Ar
  41 |
  42 .Fl f Ar filelist
  43 .
  44 .Sh DESCRIPTION
  45 .
  46 .Nm bubblegum
  47 is a daemon which watches a files access, modification and inode change times
  48 via
  49 .Fn stat
  50 and can also check MD5 checksums if
  51 .Em libmd
  52 is available at compile-time. Filenames obtained from a file list via the
  53 .Fl f
  54 option or from the command line are relative to the current directory unless
  55 they begin with a
  56 .Sq \&/ .
  57 .Pp
  58 If a file specified on the command line or in a file list is a directory and
  59 ends with a
  60 .Sq \&/ ,
  61 then the directory will be recursed having all files and subdirectories added
  62 to the list of files to watch. Note that this will modify the access time of
  63 the directories when loading or reloading a file list or on startup.
  64 .
  65 .Pp
  66 The following command line options are available:
  67 .
  68 .Bl -tag -width
  69 .It Fl f Ar filename
  70 Obtain a list of files to watch, one per line, from
  71 .Ar filename .
  72 .It Fl n Ar level
  73 The priority or niceness level,
  74 .Ar \&-20
  75 through
  76 .Ar 20 ,
  77 of the daemon process and executed commands. Only the superuser can set a
  78 priority lower than the parent process.
  79 .It Fl i Ar seconds
  80 Interval in seconds to wait between file checks. Must be greater than zero.
  81 The default is
  82 .Ar 1 .
  83 .It Fl a
  84 Check the acces time of the file.
  85 .It Fl m
  86 Check the modification time of the file.
  87 .It Fl c
  88 Check the inode change time of the file.
  89 .It Fl M
  90 Check the MD5 checksum of the file. The files checksum is updated after
  91 detecting a change. The files modification time is used as the time
  92 difference. Note that both MD5 and access time checking
  93 .Fl a
  94 cannot be specified because MD5 checking modifies the access time. Also note
  95 that this option increases CPU overhead significantly, escpecially with a
  96 short time interval and lots of files. This option is only available if
  97 compiled with
  98 .Em libmd
  99 support.
 100 .It Fl E
 101 Check for errors when accessing the file via
 102 .Fn stat
 103 or
 104 .Fn MD5File .
 105 .It Fl A
 106 Check everything except MD5 checksums. This option is a shortcut for
 107 specifying
 108 .Fl amcE .
 109 .It Fl e Ar command
 110 Execute a command via
 111 .Fn execvp
 112 after detecting a file change. Any arguments to
 113 .Ar command
 114 which contain spaces must be enclosed in double quotes
 115 .Sq \&"
 116 to keep the
 117 argument list sane. To include a double quote or backslash character in an
 118 argument itself, precede it with a backslash
 119 .Sq \e
 120 character. See
 121 .Sx EXPANSIONS
 122 below for special character expansions.
 123 .It Fl r Ar count
 124 Maximum number of times to run
 125 .Ar command
 126 for each file. A setting of
 127 .Ar 0
 128 will run
 129 .Ar command
 130 an infinite number of times. The default is
 131 .Ar 1 .
 132 .It Fl t Ar count
 133 Total number of times to run
 134 .Ar command
 135 for all files.
 136 This option overrides
 137 .Fl r .
 138 .It Fl l Ar logfile
 139 Log changes to the specified
 140 .Ar logfile .
 141 The default is
 142 .Pa ~/bubblegum.log .
 143 See
 144 .Sx ENVIRONMENT
 145 and
 146 .Sx FILES ,
 147 below.
 148 .It Fl Xo 0|1|2 Xc
 149 Logging level.
 150 .Fl Xo 0 Xc
 151 will disable file logging.
 152 .Fl Xo 1 Xc
 153 will log only the first change of each file.
 154 .Fl Xo 2 Xc
 155 will log all changes of all files up to an error if error checking is enabled.
 156 If the error changes, then the error is logged. If the error disappears, then
 157 logging for that file continues as normal. The default is
 158 .Fl Xo 2 Xc .
 159 .It Fl s
 160 Enable logging to
 161 .Xr syslogd 8
 162 and disable file logging. Note that the logging level still applies.
 163 .It Fl k
 164 If a file is a symbolic link, check the link itself, not the file the link
 165 follows.
 166 .It Fl p Ar pidfile
 167 An alternate process id file to use. The default is
 168 .Pa ~/bubblegum.pid .
 169 See
 170 .Sx ENVIRONMENT
 171 and
 172 .Sx FILES ,
 173 below.
 174 .It Fl q
 175 Terminate an already running daemon.
 176 .It Fl h
 177 Program help text.
 178 .It Fl v
 179 Version and copyright information.
 180 .El
 181 .
 182 .Sh "EXPANSIONS"
 183 When specifying a command with the
 184 .Fl e
 185 command line option, special character expansions are available to show
 186 information about a files change. The following expansions are available and
 187 each should be enclosed in double quotes
 188 .Sq \&"
 189 to keep the argument list sane
 190 (see
 191 .Sx EXAMPLES ,
 192 below):
 193 .Pp
 194 .Bl -tag -compact -width \&%\&%
 195 .It Cm \&%f
 196 Full path of the filename.
 197 .It Cm \&%F
 198 The type of file:
 199 .Em DIRECTORY ,
 200 .Em FIFO ,
 201 .Em LINK ,
 202 .Em CHARACTER ,
 203 .Em REGULAR ,
 204 .Em BLOCK
 205 or
 206 .Em SOCKET .
 207 .It Cm \&%m
 208 File permission mode in octal.
 209 .It Cm \&%t
 210 Time stamp of the latest change.
 211 .It Cm \&%b
 212 Time of the last change.
 213 .It Cm \&%d
 214 Time stamp of when the change was detected.
 215 .It Cm \&%i
 216 Time difference of the latest and last change in
 217 .Em type:days:hours:minutes:seconds
 218 format where
 219 .Em type
 220 is one of
 221 .Em A ,
 222 .Em M
 223 or
 224 .Em C
 225 for access, modification or inode change time respectively.
 226 .It Cm \&%s
 227 Daemon status.
 228 .It Cm \&%p
 229 Daemon process id.
 230 .It Cm \&%c
 231 A comma separated list of changes:
 232 .Em ATIME ,
 233 .Em MTIME ,
 234 .Em CTIME ,
 235 .Em MD5
 236 or
 237 .Em ERROR .
 238 .It Cm \&%y
 239 A comma separated list change types, if available. The recognized
 240 change types are:
 241 .Em IDEV ,
 242 .Em INODE ,
 243 .Em HLINK ,
 244 .Em USER ,
 245 .Em GROUP ,
 246 .Em PERM
 247 and
 248 .Em SIZE .
 249 If no change type is available then a single
 250 .Sq \&-
 251 is used. See
 252 .Xr stat 2
 253 for definitions of the change types.
 254 .It Cm \&%e
 255 If an error occurs while accessing the file with
 256 .Fn stat
 257 or
 258 .Fn MD5File
 259 and error checking has been enabled with the
 260 .Fl E
 261 command line option, then this is expanded to the error string via
 262 .Fn strerror .
 263 Otherwise it holds a single
 264 .Sq \&-
 265 character.
 266 .It Cm \&%r
 267 The number of times
 268 .Ar command
 269 has been run for the current file and the total number of times
 270 allowed specified with the
 271 .Fl r
 272 or
 273 .Fl t
 274 command line options.
 275 .It Cm \&%\&%
 276 A regular
 277 .Sq \&%
 278 character.
 279 .El
 280 .
 281 .Sh "SIGNALS"
 282 .Bl -tag -compact -width SIGTERM
 283 .It SIGALRM
 284 Force the current timer to expire causing the next file check.
 285 .It SIGHUP
 286 Reload the file list specified with the
 287 .Fl f
 288 command line option keeping the original changed bits and command runs for
 289 existing files.
 290 .It SIGUSR1
 291 Reset only the changed bits for all files.
 292 .It SIGUSR2
 293 Reset changed bits and command runs for all files.
 294 .It SIGTERM
 295 Terminate the daemon.
 296 .El
 297 .
 298 .Sh ENVIRONMENT
 299 .Bl -tag -width BUBBLEGUM_LOG -compact
 300 .It Ev BUBBLEGUM_LOG
 301 Logging file. Command line option
 302 .Fl l
 303 will override this variable.
 304 .It Ev BUBBLEGUM_PID
 305 Process id file. Command line option
 306 .Fl p
 307 will override this variable.
 308 .El
 309 .
 310 .Sh FILES
 311 .Bl -tag -compact -width ~/bubblegum.log
 312 .It Pa ~/bubblegum.log
 313 Default logging file.
 314 .It Pa ~/bubblegum.pid
 315 Default process id file.
 316 .El
 317 .
 318 .Sh EXAMPLES
 319 .Dl \&% bubblegum \&-e \&'script.sh \&"\&%f\&" \&"\&%c\%" \&"\&%y\&"\&' \&-As \&-f filelist
 320 .
 321 .Sh SEE ALSO
 322 .Xr stat 2 ,
 323 .Xr MD5File 3 ,
 324 .Xr setpriority 2 ,
 325 .Xr fork 2 ,
 326 .Xr select 2 ,
 327 .Xr syslogd 8 ,
 328 .Xr execvp 3
 329 .
 330 .Sh AUTHORS
 331 .
 332 .An "Ben Kibbey" Aq bjk@arbornet.org