932fdefd |
1 | \cfg{man-identity}{beep}{1}{2006-02-15}{Simon Tatham}{Simon Tatham} |
2 | |
92dccb8d |
3 | \define{dash} \u2013{-} |
4 | |
932fdefd |
5 | \title Man page for \c{beep} |
6 | |
7 | \U NAME |
8 | |
92dccb8d |
9 | \c{beep} \dash produce a beeping noise, by any available method |
932fdefd |
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 | |
2bdf083b |
85 | \cw{beep} is free software, distributed under the MIT licence. Type |
86 | \cw{beep --licence} to see the full licence text. |
932fdefd |
87 | |
88 | \versionid $Id$ |