mdw@git.distorted.org.uk Git - sgt/utils/blob - beep/beep.but

   1 \cfg{man-identity}{beep}{1}{2006-02-15}{Simon Tatham}{Simon Tatham}
   2
   3 \define{dash} \u2013{-}
   4
   5 \title Man page for \c{beep}
   6
   7 \U NAME
   8
   9 \c{beep} \dash produce a beeping noise, by any available method
  10
  11 \U SYNOPSIS
  12
  13 \c beep [ -v ] [ -X | -T | -S ]
  14 \e bbbb   bb     bb   bb   bb
  15
  16 \U DESCRIPTION
  17
  18 \c{beep} is a command-line utility for making a computer go beep.
  19
  20 Under normal circumstances, you should be able to use it just by
  21 typing \cq{beep}, with no options.
  22
  23 The traditional method of producing a beep in a shell script is to
  24 write an ASCII BEL (\cw{\\007}) character to standard output, by
  25 means of a shell command such as \cq{echo -ne '\\007'}. This only
  26 works if the calling shell's standard output is currently directed
  27 to a terminal device of some sort; if not, the beep will produce no
  28 sound and might even cause unwanted corruption in whatever file the
  29 output is directed to.
  30
  31 There are other ways to cause a beeping noise. A slightly more
  32 reliable method is to open \cw{/dev/tty} and send your BEL character
  33 there. This is robust against I/O redirection, but still fails in
  34 the case where the shell script wishing to generate a beep does not
  35 \e{have} a controlling terminal, for example because it is run from
  36 an X window manager.
  37
  38 A third approach is to connect to your X display and send it a bell
  39 command. This does not depend on a Unix terminal device, but does
  40 (of course) require an X display.
  41
  42 The \c{beep} command supports all these methods of generating a
  43 beep, and will try them in order until one works. Its order of
  44 preference is to use the X server, then to fall back to
  45 \cw{/dev/tty}, and if all else fails it will simply write a BEL to
  46 its standard output.
  47
  48 \U OPTIONS
  49
  50 \dt \cw{-X}
  51
  52 \dd Restricts \c{beep} to only using the X server to generate its
  53 beep. If there is no X server available, no beep will be generated
  54 and \c{beep} will return failure.
  55
  56 \dt \cw{-T}
  57
  58 \dd Restricts \c{beep} to only using \cw{/dev/tty} to generate its
  59 beep. If \cw{/dev/tty} cannot be opened or written to, no beep will
  60 be generated and \c{beep} will return failure.
  61
  62 \dt \cw{-S}
  63
  64 \dd Restricts \c{beep} to only using standard output to generate its
  65 beep. If its standard output cannot be written to, no beep will be
  66 generated and \c{beep} will return failure.
  67
  68 \dt \cw{-v}
  69
  70 \dd Causes \c{beep} to log everything it did even if it succeeds. By
  71 default, error messages will only be output if none of the available
  72 beep methods succeeded.
  73
  74 \U EXIT STATUS
  75
  76 \c{beep} will return a success (0) status if it thinks it
  77 successfully beeped, and failure (1) otherwise.
  78
  79 \U BUGS
  80
  81 None known at present.
  82
  83 \U LICENCE
  84
  85 \cw{beep} is free software, distributed under the MIT licence. Type
  86 \cw{beep --licence} to see the full licence text.
  87
  88 \versionid $Id$