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