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