932fdefd |
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 | |
2bdf083b |
83 | \cw{beep} is free software, distributed under the MIT licence. Type |
84 | \cw{beep --licence} to see the full licence text. |
932fdefd |
85 | |
86 | \versionid $Id$ |