Provided by: beep_1.2.2-19_i386 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 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’ 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  follow‐
               ing 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  speci‐
               fying  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 fre‐
               quency 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 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).
        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-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 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  van‐
        ish,  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/con‐
        sole, 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.
        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.
        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 CREDITS.
 
                                  November 2006                         BEEP(1)