Commit | Line | Data |
---|---|---|
f35cac8e | 1 | .\" Copyright (c) 1980, 1990 The Regents of the University of California. |
ca3a0045 | 2 | .\" All rights reserved. |
ea733718 | 3 | .\" |
af359dea C |
4 | .\" Redistribution and use in source and binary forms, with or without |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
12 | .\" 3. All advertising materials mentioning features or use of this software | |
13 | .\" must display the following acknowledgement: | |
14 | .\" This product includes software developed by the University of | |
15 | .\" California, Berkeley and its contributors. | |
16 | .\" 4. Neither the name of the University nor the names of its contributors | |
17 | .\" may be used to endorse or promote products derived from this software | |
18 | .\" without specific prior written permission. | |
ca3a0045 | 19 | .\" |
af359dea C |
20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
30 | .\" SUCH DAMAGE. | |
ea733718 | 31 | .\" |
af359dea C |
32 | .\" @(#)error.1 6.7 (Berkeley) 7/24/91 |
33 | .\" | |
34 | .Dd July 24, 1991 | |
f35cac8e CL |
35 | .Dt ERROR 1 |
36 | .Os BSD 4 | |
37 | .Sh NAME | |
38 | .Nm error | |
39 | .Nd analyze and disperse compiler error messages | |
40 | .Sh SYNOPSIS | |
41 | .Nm error | |
42 | .Op Fl n | |
43 | .Op Fl s | |
44 | .Op Fl q | |
45 | .Op Fl v | |
46 | .Op Fl t Ar suffixlist | |
47 | .Op Fl I Ar ignorefile | |
48 | .Op name | |
49 | .Sh DESCRIPTION | |
50 | .Nm Error | |
ea733718 KM |
51 | analyzes and optionally disperses the diagnostic error messages |
52 | produced by a number of compilers and language processors to the source | |
53 | file and line where the errors occurred. It can replace the painful, | |
54 | traditional methods of scribbling abbreviations of errors on paper, and | |
55 | permits error messages and source code to be viewed simultaneously | |
56 | without machinations of multiple windows in a screen editor. | |
f35cac8e CL |
57 | .Pp |
58 | Options are: | |
af359dea C |
59 | .Bl -tag -width Ds |
60 | .It Fl n | |
f35cac8e CL |
61 | Do |
62 | .Em not | |
63 | touch any files; all error messages are sent to the | |
64 | standard output. | |
af359dea | 65 | .It Fl q |
f35cac8e CL |
66 | The user is |
67 | .Ar queried | |
68 | whether s/he wants to touch the file. | |
69 | A ``y'' or ``n'' to the question is necessary to continue. | |
70 | Absence of the | |
71 | .Fl q | |
72 | option implies that all referenced files | |
73 | (except those referring to discarded error messages) | |
74 | are to be touched. | |
af359dea | 75 | .It Fl v |
f35cac8e CL |
76 | After all files have been touched, |
77 | overlay the visual editor | |
af359dea | 78 | .Xr \&vi 1 |
f35cac8e CL |
79 | with it set up to edit all files touched, |
80 | and positioned in the first touched file at the first error. | |
81 | If | |
af359dea | 82 | .Xr \&vi 1 |
f35cac8e | 83 | can't be found, try |
af359dea | 84 | .Xr \&ex 1 |
f35cac8e | 85 | or |
af359dea | 86 | .Xr \&ed 1 |
f35cac8e | 87 | from standard places. |
af359dea | 88 | .It Fl t |
f35cac8e CL |
89 | Take the following argument as a suffix list. |
90 | Files whose suffixes do not appear in the suffix list are not touched. | |
91 | The suffix list is dot separated, and ``*'' wildcards work. | |
92 | Thus the suffix list: | |
93 | .Pp | |
94 | .Dl ".c.y.foo*.h" | |
95 | .Pp | |
96 | allows | |
97 | .Nm error | |
98 | to touch files ending with ``.c'', ``.y'', ``.foo*'' and ``.y''. | |
af359dea | 99 | .It Fl s |
f35cac8e CL |
100 | Print out |
101 | .Em statistics | |
102 | regarding the error categorization. | |
103 | Not too useful. | |
af359dea | 104 | .El |
f35cac8e CL |
105 | .Pp |
106 | .Nm Error | |
ea733718 | 107 | looks at the error messages, |
f35cac8e CL |
108 | either from the specified file |
109 | .Ar name | |
ea733718 KM |
110 | or from the standard input, |
111 | and attempts to determine which | |
112 | language processor produced each error message, | |
113 | determines the source file and line number to which the error message refers, | |
114 | determines if the error message is to be ignored or not, | |
115 | and inserts the (possibly slightly modified) error message into | |
62f70816 | 116 | the source file as a comment on the line preceding to which the |
ea733718 KM |
117 | line the error message refers. |
118 | Error messages which can't be categorized by language processor | |
119 | or content are not inserted into any file, | |
120 | but are sent to the standard output. | |
f35cac8e | 121 | .Nm Error |
ea733718 | 122 | touches source files only after all input has been read. |
f35cac8e CL |
123 | .Pp |
124 | .Nm Error | |
ea733718 KM |
125 | is intended to be run |
126 | with its standard input | |
127 | connected via a pipe to the error message source. | |
128 | Some language processors put error messages on their standard error file; | |
129 | others put their messages on the standard output. | |
130 | Hence, both error sources should be piped together into | |
f35cac8e CL |
131 | .Nm error . |
132 | For example, when using the | |
133 | .Xr csh 1 | |
134 | syntax, | |
135 | .Pp | |
5325ced3 | 136 | .Dl make \-s lint \&| error \-q \-v |
f35cac8e | 137 | .Pp |
ea733718 KM |
138 | will analyze all the error messages produced |
139 | by whatever programs | |
f35cac8e | 140 | .Xr make 1 |
ea733718 | 141 | runs when making lint. |
f35cac8e CL |
142 | .Pp |
143 | .Nm Error | |
ea733718 | 144 | knows about the error messages produced by: |
f35cac8e | 145 | .Xr make 1 , |
af359dea | 146 | .Xr \&cc 1 , |
f35cac8e CL |
147 | .Xr cpp 1 , |
148 | .Xr ccom 1 , | |
af359dea C |
149 | .Xr \&as 1 , |
150 | .Xr \&ld 1 , | |
f35cac8e | 151 | .Xr lint 1 , |
af359dea C |
152 | .Xr \&pi 1 , |
153 | .Xr \&pc 1 , | |
f35cac8e | 154 | .Xr f77 1 , |
ea733718 | 155 | and |
f35cac8e CL |
156 | .Em DEC Western Research Modula\-2 . |
157 | .Nm Error | |
ea733718 KM |
158 | knows a standard format for error messages produced by |
159 | the language processors, | |
160 | so is sensitive to changes in these formats. | |
f35cac8e CL |
161 | For all languages except |
162 | .Em Pascal , | |
ea733718 KM |
163 | error messages are restricted to be on one line. |
164 | Some error messages refer to more than one line in more than | |
165 | one files; | |
f35cac8e | 166 | .Nm error |
ea733718 KM |
167 | will duplicate the error message and insert it at |
168 | all of the places referenced. | |
f35cac8e CL |
169 | .Pp |
170 | .Nm Error | |
ea733718 | 171 | will do one of six things with error messages. |
af359dea C |
172 | .Bl -tag -width Em synchronize |
173 | .It Em synchronize | |
ea733718 KM |
174 | Some language processors produce short errors describing |
175 | which file it is processing. | |
f35cac8e | 176 | .Nm Error |
ea733718 KM |
177 | uses these to determine the file name for languages that |
178 | don't include the file name in each error message. | |
179 | These synchronization messages are consumed entirely by | |
f35cac8e | 180 | .Nm error . |
af359dea | 181 | .It Em discard |
ea733718 | 182 | Error messages from |
f35cac8e | 183 | .Xr lint 1 |
ea733718 | 184 | that refer to one of the two |
f35cac8e | 185 | .Xr lint 1 |
ea733718 | 186 | libraries, |
f35cac8e | 187 | .Pa /usr/libdata/lint/llib-lc |
ea733718 | 188 | and |
f35cac8e | 189 | .Pa /usr/libdata/lint/llib-port |
ea733718 KM |
190 | are discarded, |
191 | to prevent accidently touching these libraries. | |
192 | Again, these error messages are consumed entirely by | |
f35cac8e | 193 | .Nm error . |
af359dea | 194 | .It Em nullify |
ea733718 | 195 | Error messages from |
f35cac8e | 196 | .Xr lint 1 |
ea733718 KM |
197 | can be nullified if they refer to a specific function, |
198 | which is known to generate diagnostics which are not interesting. | |
199 | Nullified error messages are not inserted into the source file, | |
200 | but are written to the standard output. | |
201 | The names of functions to ignore are taken from | |
202 | either the file named | |
f35cac8e CL |
203 | .Pa .errorrc |
204 | in the users's home directory, | |
ea733718 | 205 | or from the file named by the |
f35cac8e | 206 | .Fl I |
ea733718 KM |
207 | option. |
208 | If the file does not exist, | |
209 | no error messages are nullified. | |
210 | If the file does exist, there must be one function | |
211 | name per line. | |
af359dea | 212 | .It Em not file specific |
ea733718 KM |
213 | Error messages that can't be intuited are grouped together, |
214 | and written to the standard output before any files are touched. | |
215 | They will not be inserted into any source file. | |
af359dea | 216 | .It Em file specific |
ea733718 KM |
217 | Error message that refer to a specific file, |
218 | but to no specific line, | |
219 | are written to the standard output when | |
220 | that file is touched. | |
af359dea | 221 | .It Em true errors |
ea733718 KM |
222 | Error messages that can be intuited are candidates for |
223 | insertion into the file to which they refer. | |
af359dea | 224 | .El |
f35cac8e | 225 | .Pp |
ea733718 KM |
226 | Only true error messages are candidates for inserting into |
227 | the file they refer to. | |
228 | Other error messages are consumed entirely by | |
f35cac8e | 229 | .Nm error |
ea733718 | 230 | or are written to the standard output. |
f35cac8e | 231 | .Nm Error |
ea733718 | 232 | inserts the error messages into the source file on the line |
62f70816 | 233 | preceding the line the language processor found in error. |
ea733718 KM |
234 | Each error message is turned into a one line comment for the |
235 | language, | |
236 | and is internally flagged | |
237 | with the string ``###'' at | |
238 | the beginning of the error, | |
239 | and ``%%%'' at the end of the error. | |
240 | This makes pattern searching for errors easier with an editor, | |
241 | and allows the messages to be easily removed. | |
242 | In addition, each error message contains the source line number | |
243 | for the line the message refers to. | |
244 | A reasonably formatted source program can be recompiled | |
245 | with the error messages still in it, | |
246 | without having the error messages themselves cause future errors. | |
247 | For poorly formatted source programs in free format languages, | |
248 | such as C or Pascal, | |
249 | it is possible to insert a comment into another comment, | |
250 | which can wreak havoc with a future compilation. | |
62f70816 KM |
251 | To avoid this, programs with comments and source |
252 | on the same line should be formatted | |
253 | so that language statements appear before comments. | |
f35cac8e CL |
254 | .Pp |
255 | .Nm Error | |
ea733718 KM |
256 | catches interrupt and terminate signals, |
257 | and if in the insertion phase, | |
258 | will orderly terminate what it is doing. | |
f35cac8e | 259 | .Sh FILES |
af359dea C |
260 | .Bl -tag -width ~/.errorrc -compact |
261 | .It Pa ~/.errorrc | |
f35cac8e CL |
262 | function names to ignore for |
263 | .Xr lint 1 | |
264 | error messages | |
af359dea | 265 | .It Pa /dev/tty |
f35cac8e | 266 | user's teletype |
af359dea | 267 | .El |
f35cac8e | 268 | .Sh HISTORY |
af359dea C |
269 | The |
270 | .Nm error | |
271 | command | |
272 | appeared in | |
273 | .Bx 4.0 . | |
f35cac8e | 274 | .Sh AUTHOR |
ea733718 | 275 | Robert Henry |
f35cac8e CL |
276 | .Sh BUGS |
277 | .Pp | |
ea733718 | 278 | Opens the teletype directly to do user querying. |
f35cac8e | 279 | .Pp |
ea733718 KM |
280 | Source files with links make a new copy of the file with |
281 | only one link to it. | |
f35cac8e | 282 | .Pp |
ea733718 | 283 | Changing a language processor's format of error messages |
f35cac8e CL |
284 | may cause |
285 | .Nm error | |
ea733718 | 286 | to not understand the error message. |
f35cac8e CL |
287 | .Pp |
288 | .Nm Error , | |
ea733718 KM |
289 | since it is purely mechanical, |
290 | will not filter out subsequent errors caused by `floodgating' | |
291 | initiated by one syntactically trivial error. | |
292 | Humans are still much better at discarding these related errors. | |
f35cac8e | 293 | .Pp |
ea733718 | 294 | Pascal error messages belong after the lines affected |
f35cac8e | 295 | (error puts them before). The alignment of the `\\' marking |
ea733718 | 296 | the point of error is also disturbed by |
f35cac8e CL |
297 | .Nm error . |
298 | .Pp | |
299 | .Nm Error | |
af359dea C |
300 | was designed for work on |
301 | .Tn CRT Ns 's | |
302 | at reasonably high speed. | |
ea733718 KM |
303 | It is less pleasant on slow speed terminals, and has never been |
304 | used on hardcopy terminals. |