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 | .\" | |
5 | .\" @(#)error.1 4.1 (Berkeley) %G% | |
6 | .\" | |
7 | .TH ERROR 1 | |
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 | |
46 | the source file as a comment on the line preceeding to which the | |
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, | |
101 | .I pc | |
102 | and | |
103 | .I f77. | |
104 | .I Error | |
105 | knows a standard format for error messages produced by | |
106 | the language processors, | |
107 | so is sensitive to changes in these formats. | |
108 | For all languages except | |
109 | .I Pascal, | |
110 | error messages are restricted to be on one line. | |
111 | Some error messages refer to more than one line in more than | |
112 | one files; | |
113 | .I error | |
114 | will duplicate the error message and insert it at | |
115 | all of the places referenced. | |
116 | .PP | |
117 | .I Error | |
118 | will do one of six things with error messages. | |
119 | .TP 10 | |
120 | .I synchronize | |
121 | Some language processors produce short errors describing | |
122 | which file it is processing. | |
123 | .I Error | |
124 | uses these to determine the file name for languages that | |
125 | don't include the file name in each error message. | |
126 | These synchronization messages are consumed entirely by | |
127 | .I error. | |
128 | .TP 10 | |
129 | .I discard | |
130 | Error messages from | |
131 | .I lint | |
132 | that refer to one of the two | |
133 | .I lint | |
134 | libraries, | |
135 | .I /usr/lib/llib-lc | |
136 | and | |
137 | .I /usr/lib/llib-port | |
138 | are discarded, | |
139 | to prevent accidently touching these libraries. | |
140 | Again, these error messages are consumed entirely by | |
141 | .I error. | |
142 | .TP 10 | |
143 | .I nullify | |
144 | Error messages from | |
145 | .I lint | |
146 | can be nullified if they refer to a specific function, | |
147 | which is known to generate diagnostics which are not interesting. | |
148 | Nullified error messages are not inserted into the source file, | |
149 | but are written to the standard output. | |
150 | The names of functions to ignore are taken from | |
151 | either the file named | |
152 | .I .errorrc | |
153 | in the users's home directory, | |
154 | or from the file named by the | |
155 | .B \-I | |
156 | option. | |
157 | If the file does not exist, | |
158 | no error messages are nullified. | |
159 | If the file does exist, there must be one function | |
160 | name per line. | |
161 | .TP 10 | |
162 | .I not file specific | |
163 | Error messages that can't be intuited are grouped together, | |
164 | and written to the standard output before any files are touched. | |
165 | They will not be inserted into any source file. | |
166 | .TP 10 | |
167 | .I file specific | |
168 | Error message that refer to a specific file, | |
169 | but to no specific line, | |
170 | are written to the standard output when | |
171 | that file is touched. | |
172 | .TP 10 | |
173 | .I true errors | |
174 | Error messages that can be intuited are candidates for | |
175 | insertion into the file to which they refer. | |
176 | .PP | |
177 | Only true error messages are candidates for inserting into | |
178 | the file they refer to. | |
179 | Other error messages are consumed entirely by | |
180 | .I error | |
181 | or are written to the standard output. | |
182 | .I Error | |
183 | inserts the error messages into the source file on the line | |
184 | preceeding the line the language processor found in error. | |
185 | Each error message is turned into a one line comment for the | |
186 | language, | |
187 | and is internally flagged | |
188 | with the string ``###'' at | |
189 | the beginning of the error, | |
190 | and ``%%%'' at the end of the error. | |
191 | This makes pattern searching for errors easier with an editor, | |
192 | and allows the messages to be easily removed. | |
193 | In addition, each error message contains the source line number | |
194 | for the line the message refers to. | |
195 | A reasonably formatted source program can be recompiled | |
196 | with the error messages still in it, | |
197 | without having the error messages themselves cause future errors. | |
198 | For poorly formatted source programs in free format languages, | |
199 | such as C or Pascal, | |
200 | it is possible to insert a comment into another comment, | |
201 | which can wreak havoc with a future compilation. | |
202 | To avoid this, format the source program so there are no | |
203 | language statements on the same line as the end of a comment. | |
204 | .PP | |
205 | Options available with | |
206 | .I error | |
207 | are: | |
208 | .TP 5 | |
209 | .B \-n | |
210 | Do | |
211 | .I not | |
212 | touch any files; all error messages are sent to the | |
213 | standard output. | |
214 | .TP 5 | |
215 | .B \-q | |
216 | The user is | |
217 | .I queried | |
218 | whether s/he wants to touch the file. | |
219 | A ``y'' or ``n'' to the question is necessary to continue. | |
220 | Absence of the | |
221 | .B \-q | |
222 | option implies that all referenced files | |
223 | (except those refering to discarded error messages) | |
224 | are to be touched. | |
225 | .TP 5 | |
226 | .B \-v | |
227 | After all files have been touched, | |
228 | overlay the visual editor | |
229 | .I vi | |
230 | with it set up to edit all files touched, | |
231 | and positioned in the first touched file at the first error. | |
232 | If | |
233 | .I vi | |
234 | can't be found, try | |
235 | .I ex | |
236 | or | |
237 | .I ed | |
238 | from standard places. | |
239 | .TP 5 | |
240 | .B \-t | |
241 | Take the following argument as a suffix list. | |
242 | Files whose suffices do not appear in the suffix list are not touched. | |
243 | The suffix list is dot seperated, and ``*'' wildcards work. | |
244 | Thus the suffix list: | |
245 | .IP | |
246 | \& ".c.y.foo*.h" | |
247 | .IP | |
248 | allows | |
249 | .I error | |
250 | to touch files ending with ``.c'', ``.y'', ``.foo*'' and ``.y''. | |
251 | .TP 5 | |
252 | .B \-s | |
253 | Print out | |
254 | .I statistics | |
255 | regarding the error categorization. | |
256 | Not too useful. | |
257 | .PP | |
258 | .I Error | |
259 | catches interrupt and terminate signals, | |
260 | and if in the insertion phase, | |
261 | will orderly terminate what it is doing. | |
262 | .SH AUTHOR | |
263 | Robert Henry | |
264 | .SH FILES | |
265 | .ta 2i | |
266 | ~/.errorrc function names to ignore for \fIlint\fP error messages | |
267 | .br | |
268 | /dev/tty user's teletype | |
269 | .SH BUGS | |
270 | .PP | |
271 | Opens the teletype directly to do user querying. | |
272 | .PP | |
273 | Source files with links make a new copy of the file with | |
274 | only one link to it. | |
275 | .PP | |
276 | Changing a language processor's format of error messages | |
277 | may cause | |
278 | .I error | |
279 | to not understand the error message. | |
280 | .PP | |
281 | .I Error, | |
282 | since it is purely mechanical, | |
283 | will not filter out subsequent errors caused by `floodgating' | |
284 | initiated by one syntactically trivial error. | |
285 | Humans are still much better at discarding these related errors. | |
286 | .PP | |
287 | Pascal error messages belong after the lines affected | |
288 | (error puts them before). The alignment of the `\||\|' marking | |
289 | the point of error is also disturbed by | |
290 | .I error. | |
291 | .PP | |
292 | .I Error | |
293 | was designed for work on CRT's at reasonably high speed. | |
294 | It is less pleasant on slow speed terminals, and has never been | |
295 | used on hardcopy terminals. |