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