BEEP(1) BEEP(1)
NAME
beep(1,3x,3x curs_beep) - beep(1,3x,3x curs_beep) the pc speaker any number of ways
SYNOPSIS
beep(1,3x,3x curs_beep) [-f N] [-l N] [-r N] [-d N] [-D N] [-s] [-c]
beep(1,3x,3x curs_beep) [ OPTIONS ] [-n] [--new] [ OPTIONS ]
beep(1,3x,3x curs_beep) [-h] [--help]
beep(1,3x,3x curs_beep) [-v] [-V] [--version]
DESCRIPTION
beep(1,3x,3x curs_beep) allows the user to control the pc-speaker with precision, allowing
different sounds to indicate different events. While it can be run
quite happily on the command line, it's intended place of residence is
within shell/perl scripts, notifying the user when something interest-
ing occurs. Of course, it has no notion of what's interesting, but
it's real good at that notifying part.
All options have default values, meaning that just typing 'beep(1,3x,3x curs_beep)' will
work. If an option is specified more than once on the command line,
subsequent options override their predecessors. So 'beep(1,3x,3x curs_beep) -f 200 -f
300' will beep(1,3x,3x curs_beep) at 300Hz.
OPTIONS
-f N beep(1,3x,3x curs_beep) at N Hz, where 0 < N < 20000. As a general ballpark, the
regular terminal beep(1,3x,3x curs_beep) is around 750Hz. N is not, incidentally,
restricted to whole numbers.
-l N beep(1,3x,3x curs_beep) for N milliseconds.
-r N specify the number of repetitions (defaults to 1).
-d N, -D N
specify a delay of N milliseconds between repetitions. Use of
-d specifies that this delay should only occur between beeps,
that is, it should not occur after the last repetition. -D
indicates that the delay should occur after every repetition,
including the last. Normally, -d is what you want, but if(3,n), for
example, you are stringing several beep(1,3x,3x curs_beep) commands together to
play the star(1,4) wars anthem, you may want control over every
delay.
-n, --new
this option allows you to break the command line up into speci-
fying multiple beeps. Each time(1,2,n) this option is used, beep(1,3x,3x curs_beep)
starts treating all further arguments as though they were for a
new beep. So for example:
beep(1,3x,3x curs_beep) -f 1000 -n -f 2000 -n -f 1500
would produce a sequence of three beeps, the first with a fre-
quency of 1000Hz (and otherwise default values), then a second
beep(1,3x,3x curs_beep) with a frequency of 2000Hz (again, with things like delay
and reps being set(7,n,1 builtins) to their defaults), then a third beep(1,3x,3x curs_beep), at
1500Hz. This is different from specifying a -r value, since -r
repeats the same beep(1,3x,3x curs_beep) multiple times, whereas -n allows you to
specify different beeps. After a -n, the new beep(1,3x,3x curs_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 EXAMPLES section if(3,n) this managed to confuse you.
-s, -c these options put beep(1,3x,3x curs_beep) into input-processing mode. -s tells
beep(1,3x,3x curs_beep) to read(2,n,1 builtins) from stdin, and beep(1,3x,3x curs_beep) after each newline, and -c
tells it to do so after every character. In both cases, the
program will also echo(1,3x,1 builtins) the input back out to stdout, which makes
it easy to slip beep(1,3x,3x curs_beep) into a text-processing pipeline, see the
EXAMPLES section.
-h, --help
display usage info(1,5,n) and exit(3,n,1 builtins)
-v, -V, --version
display version(1,3,5) information and exit(3,n,1 builtins)
EXAMPLES
At its simplest (yet still effective)
beep(1,3x,3x curs_beep)
A more interesting standalone setup(2,8)
beep(1,3x,3x curs_beep) -f 300.7 -r 2 -d 100 -l 400
As part of a log-watching pipeline
tail -f /var/log/xferlog | grep 'passwd(1,5)' | beep(1,3x,3x curs_beep) -f 1000 -r 5 -s
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
cat file(1,n) | beep(1,3x,3x curs_beep) -c -f 400 -D 50 -l 10
A highly contrived example of -n/--new usage
beep(1,3x,3x curs_beep) -f 1000 -r 2 -n -r 5 -l 10 --new
will produce first two 1000Hz beeps, then 5 beeps at the default
tone, but only 10ms long each, followed by a third beep(1,3x,3x curs_beep) using
all the default settings (since none are specified).
IOCTL WACKINESS
Some users(1,5) will encounter a situation where beep(1,3x,3x curs_beep) dies with a complaint
from ioctl(). The reason for this, as Peter Tirsek was nice(1,2) enough to
point out to me, stems from how the kernel handles beep(1,3x,3x curs_beep)'s attempt to
poke at (for non-programmers: ioctl is a sort(1,3) of catch-all function
that lets you poke at things that have no other predefined poking-at
mechanism) the tty(1,4), which is how it beeps. The short story is, the
kernel checks that either:
- you are the superuser
- you own the current tty(1,4)
What this means is that root can always make beep(1,3x,3x curs_beep) work (to the best of
my knowledge!), and that any local user can make beep(1,3x,3x curs_beep) work, BUT a non-
root remote user cannot use beep(1,3x,3x curs_beep) in(1,8) 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(1,3x,3x curs_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.
By default beep(1,3x,3x curs_beep) is not installed with the suid bit set(7,n,1 builtins), because that
would just be zany. On the other hand, if(3,n) you do make it suid root,
all your problems with beep(1,3x,3x curs_beep) bailing on ioctl calls will magically van-
ish, which is pleasant, and the only reason not to is that any suid
program is a potential security hole. Conveniently, beep(1,3x,3x curs_beep) is very
short, so auditing it is pretty straightforward.
Decide for yourself, of course, but it looks safe to me - there's only
one buffer and fgets doesn't let it overflow, there's only one file(1,n)
opening, and while there is a potential race condition there, it's with
/dev/console. If someone can exploit this race by replacing /dev/con-
sole(4,n), you've got bigger problems. :)
So the quick, only, and likely safe solution if(3,n) beep(1,3x,3x curs_beep) is not beeping
when you want it to is (as root):
# chmod(1,2) 4755 /usr/bin/beep(1,3x,3x curs_beep)
(or wherever you put it)
The one snag is that this will give any little nitwit the ability to
run beep(1,3x,3x curs_beep) successfully - make sure this is what you want. If it isn't,
a slightly more complex fix would be something like:
# chgrp beep(1,3x,3x curs_beep) /usr/bin/beep(1,3x,3x curs_beep)
# chmod(1,2) 4750 /usr/bin/beep(1,3x,3x curs_beep)
and then add only beep-worthy users(1,5) to the 'beep(1,3x,3x curs_beep)' group.
FREQUENCY TABLE
Several people have asked for some basic help translating music notes
to frequencies. There are a lot of music notes, and several tables
online will give you translations, but here are approximate numbers for
the octave of middle C, to get you started.
Note Frequency
C 261.6
C# 277.2
D 293.7
D# 311.1
E 329.6
F 349.2
F# 370.0
G 392.0
G# 415.3
A 440.0
A# 466.2
B 493.9
C 523.2
BUGS
None that I'm aware of, though see the IOCTL WACKINESS section.
REPORTING BUGS
Report bugs to <johnath@johnath.com>
AUTHOR
This program was written by Johnathan Nightingale (johnath@johnath.com)
and is distributed under the GNU General Public License. For more con-
tributing information, check the source, and past contributors can be
found in(1,8) CREDITS.
March 2002 BEEP(1)