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