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