debian/beep.1.diff

   1 --- beep.1.orig 2009-03-24 19:02:59.000000000 +0100
   2 +++ beep.1      2009-03-24 19:04:30.000000000 +0100
   3 @@ -1,12 +1,12 @@
   4 -.TH BEEP 1 "March 2002"
   5 +.TH BEEP 1 "July 2008"
   6  .SH NAME
   7  beep \- beep the pc speaker any number of ways
   8  .SH SYNOPSIS
   9  .B beep
  10 -[\-f N] [\-l N] [\-r N] [\-d N] [\-D N] [\-s] [\-c]
  11 +[\-\-verbose | \-\-debug] [\-e device | \-\-device device] [\-f N] [\-l N] [\-r N] [\-d N] [\-D N] [\-s] [\-c]
  12  .HP
  13  .B beep
  14 -[ OPTIONS ] [-n] [--new] [ OPTIONS ]
  15 +[ OPTIONS ] [\-n] [\-\-new] [ OPTIONS ]
  16  .HP
  17  .B beep
  18  [\-h] [\-\-help]
  19 @@ -20,6 +20,15 @@
  20  All options have default values, meaning that just typing '\fBbeep\fR' will work.  If an option is specified more than once on the command line, subsequent options override their predecessors.  So '\fBbeep\fR \-f 200 \-f 300' will beep at 300Hz.
  21  .SH OPTIONS
  22  .TP
  23 +\fB\-\-verbose\fR, \fB\-\-debug\fR
  24 +enable debug output. This option prints a line like the following before each
  25 +beep:
  26 +
  27 +[DEBUG] 5 times 200 ms beeps (100 delay between, 0 delay after) @ 1000.00 Hz
  28 +.TP
  29 +\fB\-e\fR device, \fB\-\-device\fR device
  30 +use device as event device. If the switch isn't used, /dev/tty0 and /dev/vc/0 are tried in turn.
  31 +.TP
  32  \fB\-f\fR N
  33  beep at N Hz, where 0 < N < 20000.  As a general ballpark, the regular terminal beep is around 750Hz.  N is not, incidentally, restricted to whole numbers.
  34  .TP
  35 @@ -35,12 +44,12 @@
  36  \fB\-n\fR, \fB\-\-new\fR
  37  this option allows you to break the command line up into specifying multiple beeps.  Each time this option is used, beep starts treating all further arguments as though they were for a new beep.  So for example:
  38
  39 -\fBbeep\fR -f 1000 -n -f 2000 -n -f 1500
  40 +\fBbeep\fR \-f 1000 \-n \-f 2000 \-n \-f 1500
  41
  42 -would produce a sequence of three beeps, the first with a frequency of 1000Hz (and otherwise default values), then a second beep with a frequency of 2000Hz (again, with things like delay and reps being set to their defaults), then a third beep, at 1500Hz.  This is different from specifying a -r value, since -r repeats the same beep multiple times, whereas -n allows you to specify different beeps.  After a -n, the new beep is created with all the default values, and any of these can be specified without altering values for preceeding (or later) beeps.  See the \fBEXAMPLES\fR section if this managed to confuse you.
  43 +would produce a sequence of three beeps, the first with a frequency of 1000Hz (and otherwise default values), then a second beep with a frequency of 2000Hz (again, with things like delay and reps being set to their defaults), then a third beep, at 1500Hz.  This is different from specifying a \-r value, since \-r repeats the same beep multiple times, whereas \-n allows you to specify different beeps.  After a \-n, the new beep is created with all the default values, and any of these can be specified without altering values for preceding (or later) beeps.  See the \fBEXAMPLES\fR section if this managed to confuse you.
  44  .TP
  45  \fB\-s\fR, \fB\-c\fR
  46 -these options put \fBbeep\fR into input-processing mode.  -s tells \fBbeep\fR to read from stdin, and beep after each newline, and -c tells it to do so after every character.  In both cases, the program will also echo the input back out to stdout, which makes it easy to slip \fBbeep\fR into a text-processing pipeline, see the \fBEXAMPLES\fR section.
  47 +these options put \fBbeep\fR into input-processing mode.  \-s tells \fBbeep\fR to read from stdin, and beep after each newline, and \-c tells it to do so after every character.  In both cases, the program will also echo the input back out to stdout, which makes it easy to slip \fBbeep\fR into a text-processing pipeline, see the \fBEXAMPLES\fR section.
  48  .TP
  49  \fB\-h\fR, \fB\-\-help\fR
  50  display usage info and exit
  51 @@ -55,20 +64,22 @@
  52  .TP
  53  A more interesting standalone setup
  54
  55 -\fBbeep\fR -f 300.7 -r 2 -d 100 -l 400
  56 +\fBbeep\fR \-f 300.7 \-r 2 \-d 100 \-l 400
  57  .TP
  58  As part of a log-watching pipeline
  59
  60 -tail -f /var/log/xferlog | grep 'passwd' | \fBbeep\fR -f 1000 -r 5 -s
  61 +tail \-f /var/log/xferlog | grep \-\-line\-buffered passwd | \\
  62 +.br
  63 +\fBbeep\fR \-f 1000 \-r 5 \-s
  64  .TP
  65 -When using -c mode, I recommend using a short -D, and a shorter -l, so that the beeps don't blur together.  Something like this will get you a cheesy 1970's style beep-as-you-type-each-letter effect
  66 +When using \-c mode, I recommend using a short \-D, and a shorter \-l, so that the beeps don't blur together.  Something like this will get you a cheesy 1970's style beep-as-you-type-each-letter effect
  67
  68 -cat file | \fBbeep\fR -c -f 400 -D 50 -l 10
  69 +cat file | \fBbeep\fR \-c \-f 400 \-D 50 \-l 10
  70
  71  .TP
  72 -A highly contrived example of -n/--new usage
  73 +A highly contrived example of \-n/\-\-new usage
  74
  75 -\fBbeep\fR -f 1000 -r 2 -n -r 5 -l 10 --new
  76 +\fBbeep\fR \-f 1000 \-r 2 \-n \-r 5 \-l 10 \-\-new
  77
  78  will produce first two 1000Hz beeps, then 5 beeps at the default tone, but only 10ms long each, followed by a third beep using all the default settings (since none are specified).
  79  .PP See also the \fBFREQUENCY TABLE\fR below.
  80 @@ -81,7 +92,7 @@
  81  .PP
  82  - you own the current tty
  83  .PP
  84 -What this means is that root can always make beep work (to the best of my knowledge!), and that any local user can make beep work, BUT a non-root remote user cannot use beep in it's natural state.  What's worse, an xterm, or other x-session counts, as far as the kernel is concerned, as 'remote', so beep won't work from a non-priviledged xterm either.  I had originally chalked this up to a bug, but there's actually nothing I can do about it, and it really is a Good Thing that the kernel does things this way.  There is also a solution.
  85 +What this means is that root can always make beep work (to the best of my knowledge!), and that any local user can make beep work, BUT a non-root remote user cannot use beep in it's natural state.  What's worse, an xterm, or other x-session counts, as far as the kernel is concerned, as 'remote', so beep won't work from a non-privileged xterm either.  I had originally chalked this up to a bug, but there's actually nothing I can do about it, and it really is a Good Thing that the kernel does things this way.  There is also a solution.
  86  .PP
  87  By default beep is not installed with the suid bit set, because that would just be zany.  On the other hand, if you do make it suid root, all your problems with beep bailing on ioctl calls will magically vanish, which is pleasant, and the only reason not to is that any suid program is a potential security hole.  Conveniently, beep is very short, so auditing it is pretty straightforward.
  88  .PP