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