| 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$ |