Provided by: beep_1.3-3_amd64 bug

NAME

       beep - beep the pc speaker any number of ways

SYNOPSIS

       beep  [--verbose  | --debug] [-e device | --device device] [-f N] [-l N] [-r N] [-d N] [-D
       N] [-s] [-c]

       beep [ OPTIONS ] [-n] [--new] [ OPTIONS ]

       beep [-h] [--help]

       beep [-v] [-V] [--version]

DESCRIPTION

       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 interesting 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' will work.  If an  option
       is  specified  more  than  once  on  the  command  line, subsequent options override their
       predecessors.  So 'beep -f 200 -f 300' will beep at 300Hz.

OPTIONS

       --verbose, --debug
              enable debug output. This option prints a line like the following before each beep:

              [DEBUG] 5 times 200 ms beeps (100 delay between, 0 delay after) @ 1000.00 Hz

       -e device, --device device
              use device as event device. If the switch isn't used, /dev/tty0 and  /dev/vc/0  are
              tried in turn.

       -f N   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.

       -l N   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, for example, you are
              stringing several beep commands together to play the star wars anthem, you may want
              control over every delay.

       -n, --new
              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:

              beep -f 1000 -n -f 2000 -n -f 1500

              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 EXAMPLES
              section if this managed to confuse you.

       -s, -c these options put beep into input-processing mode.  -s  tells  beep  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 beep into a text-processing pipeline, see the EXAMPLES section.

       -h, --help
              display usage info and exit

       -v, -V, --version
              display version information and exit

EXAMPLES

       At its simplest (yet still effective)

              beep

       A more interesting standalone setup

              beep -f 300.7 -r 2 -d 100 -l 400

       As part of a log-watching pipeline

              tail -f /var/log/xferlog | grep --line-buffered passwd | \
              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 | beep -c -f 400 -D 50 -l 10

       A highly contrived example of -n/--new usage

              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 using all the default settings (since none
              are specified).

IOCTL WACKINESS

       Some  users will encounter a situation where beep dies with a complaint from ioctl().  The
       reason for this, as Peter Tirsek was nice enough to point out to me, stems  from  how  the
       kernel  handles  beep's attempt to poke at (for non-programmers: ioctl is a sort of catch-
       all function that lets you  poke  at  things  that  have  no  other  predefined  poking-at
       mechanism)  the  tty,  which  is how it beeps.  The short story is, the kernel checks that
       either:

       - you are the superuser

       - you own the current tty

       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.

       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.

       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  opening,  and  while  there  is  a
       potential  race condition there, it's with /dev/console.  If someone can exploit this race
       by replacing /dev/console, you've got bigger problems.  :)

       So the quick, only, and likely safe solution if beep is not beeping when you want it to is
       (as root):

       # chmod 4755 /usr/bin/beep

       (or wherever you put it)

       The one snag is that this will give any little nitwit the ability to run beep successfully
       - make sure this is what you want.  If it isn't, a slightly  more  complex  fix  would  be
       something like:

       # chgrp beep /usr/bin/beep

       # chmod 4750 /usr/bin/beep

       and then add only beep-worthy users to the '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  contributing  information,  check  the
       source, and past contributors can be found in CREDITS.

                                            July 2008                                     BEEP(1)