Annotation of src/usr.bin/error/error.1, Revision 1.9
1.9 ! aaron 1: .\" $OpenBSD: error.1,v 1.8 1999/12/04 19:04:52 aaron 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
45: .Op Fl n
46: .Op Fl s
47: .Op Fl q
48: .Op Fl v
49: .Op Fl t Ar suffixlist
50: .Op Fl I Ar ignorefile
1.5 aaron 51: .Op Ar name
1.1 deraadt 52: .Sh DESCRIPTION
1.8 aaron 53: The
1.7 aaron 54: .Nm
1.8 aaron 55: utility analyzes and optionally disperses the diagnostic error messages
1.1 deraadt 56: produced by a number of compilers and language processors to the source
57: file and line where the errors occurred. It can replace the painful,
58: traditional methods of scribbling abbreviations of errors on paper, and
59: permits error messages and source code to be viewed simultaneously
60: without machinations of multiple windows in a screen editor.
61: .Pp
1.8 aaron 62: The options are as follows:
1.1 deraadt 63: .Bl -tag -width Ds
64: .It Fl n
65: Do
66: .Em not
67: touch any files; all error messages are sent to the
68: standard output.
69: .It Fl q
1.9 ! aaron 70: The user is queried whether or not to touch the file.
1.8 aaron 71: A
72: .Sq y
73: or
74: .Sq n
75: to the question is necessary to continue.
1.1 deraadt 76: Absence of the
77: .Fl q
78: option implies that all referenced files
79: (except those referring to discarded error messages)
80: are to be touched.
81: .It Fl v
82: After all files have been touched,
83: overlay the visual editor
84: .Xr \&vi 1
85: with it set up to edit all files touched,
86: and positioned in the first touched file at the first error.
87: If
88: .Xr \&vi 1
89: can't be found, try
90: .Xr \&ex 1
91: or
92: .Xr \&ed 1
93: from standard places.
1.5 aaron 94: .It Fl t Ar suffixlist
1.1 deraadt 95: Take the following argument as a suffix list.
96: Files whose suffixes do not appear in the suffix list are not touched.
1.8 aaron 97: The suffix list is dot separated, and
98: .Sq \&*
99: wildcards work.
1.1 deraadt 100: Thus the suffix list:
101: .Pp
102: .Dl ".c.y.foo*.h"
103: .Pp
104: allows
1.7 aaron 105: .Nm
1.8 aaron 106: to touch files ending with
1.9 ! aaron 107: .Dq \&.c ,
! 108: .Dq \&.y ,
! 109: .Dq \&.foo\&* ,
1.8 aaron 110: and
1.9 ! aaron 111: .Dq \&.h .
1.1 deraadt 112: .It Fl s
1.9 ! aaron 113: Print out statistics regarding the error categorization.
1.1 deraadt 114: Not too useful.
1.8 aaron 115: .It Fl I Ar ignorefile
116: Specifies a file containing a list of functions to ignore.
1.1 deraadt 117: .El
118: .Pp
1.7 aaron 119: .Nm
1.1 deraadt 120: looks at the error messages,
121: either from the specified file
122: .Ar name
123: or from the standard input,
124: and attempts to determine which
125: language processor produced each error message,
1.5 aaron 126: the source file and line number to which the error message refers,
127: if the error message is to be ignored or not,
1.1 deraadt 128: and inserts the (possibly slightly modified) error message into
129: the source file as a comment on the line preceding to which the
130: line the error message refers.
131: Error messages which can't be categorized by language processor
132: or content are not inserted into any file,
133: but are sent to the standard output.
1.7 aaron 134: .Nm
1.1 deraadt 135: touches source files only after all input has been read.
136: .Pp
1.7 aaron 137: .Nm
1.1 deraadt 138: is intended to be run
139: with its standard input
140: connected via a pipe to the error message source.
141: Some language processors put error messages on their standard error file;
142: others put their messages on the standard output.
143: Hence, both error sources should be piped together into
144: .Nm error .
145: For example, when using the
146: .Xr csh 1
147: syntax,
148: .Pp
149: .Dl make \-s lint \&| error \-q \-v
150: .Pp
151: will analyze all the error messages produced
152: by whatever programs
153: .Xr make 1
154: runs when making lint.
155: .Pp
1.7 aaron 156: .Nm
1.1 deraadt 157: knows about the error messages produced by:
158: .Xr make 1 ,
1.8 aaron 159: .Xr cc 1 ,
1.1 deraadt 160: .Xr cpp 1 ,
161: .Xr ccom 1 ,
1.8 aaron 162: .Xr as 1 ,
163: .Xr ld 1 ,
1.1 deraadt 164: .Xr lint 1 ,
1.8 aaron 165: .Xr pi 1 ,
166: .Xr pc 1 ,
1.1 deraadt 167: .Xr f77 1 ,
1.9 ! aaron 168: and DEC Western Research Modula\-2.
! 169: .Pp
1.7 aaron 170: .Nm
1.1 deraadt 171: knows a standard format for error messages produced by
172: the language processors,
173: so is sensitive to changes in these formats.
1.5 aaron 174: For all languages except Pascal,
1.1 deraadt 175: error messages are restricted to be on one line.
176: Some error messages refer to more than one line in more than
1.5 aaron 177: one file;
1.7 aaron 178: .Nm
1.1 deraadt 179: will duplicate the error message and insert it at
180: all of the places referenced.
181: .Pp
1.7 aaron 182: .Nm
1.1 deraadt 183: will do one of six things with error messages.
184: .Bl -tag -width Em synchronize
185: .It Em synchronize
186: Some language processors produce short errors describing
187: which file it is processing.
1.7 aaron 188: .Nm
1.1 deraadt 189: uses these to determine the file name for languages that
190: don't include the file name in each error message.
191: These synchronization messages are consumed entirely by
192: .Nm error .
193: .It Em discard
194: Error messages from
195: .Xr lint 1
196: that refer to one of the two
197: .Xr lint 1
198: libraries,
199: .Pa /usr/libdata/lint/llib-lc
200: and
1.5 aaron 201: .Pa /usr/libdata/lint/llib-port ,
1.1 deraadt 202: are discarded,
1.4 deraadt 203: to prevent accidentally touching these libraries.
1.1 deraadt 204: Again, these error messages are consumed entirely by
205: .Nm error .
206: .It Em nullify
207: Error messages from
208: .Xr lint 1
209: can be nullified if they refer to a specific function,
210: which is known to generate diagnostics which are not interesting.
211: Nullified error messages are not inserted into the source file,
212: but are written to the standard output.
213: The names of functions to ignore are taken from
214: either the file named
215: .Pa .errorrc
216: in the users's home directory,
217: or from the file named by the
218: .Fl I
219: option.
220: If the file does not exist,
221: no error messages are nullified.
222: If the file does exist, there must be one function
223: name per line.
224: .It Em not file specific
225: Error messages that can't be intuited are grouped together,
226: and written to the standard output before any files are touched.
227: They will not be inserted into any source file.
228: .It Em file specific
229: Error message that refer to a specific file,
230: but to no specific line,
231: are written to the standard output when
232: that file is touched.
233: .It Em true errors
234: Error messages that can be intuited are candidates for
235: insertion into the file to which they refer.
236: .El
237: .Pp
238: Only true error messages are candidates for inserting into
239: the file they refer to.
240: Other error messages are consumed entirely by
1.7 aaron 241: .Nm
1.1 deraadt 242: or are written to the standard output.
1.7 aaron 243: .Nm
1.1 deraadt 244: inserts the error messages into the source file on the line
245: preceding the line the language processor found in error.
246: Each error message is turned into a one line comment for the
247: language,
248: and is internally flagged
1.8 aaron 249: with the string
250: .Dq ###
251: at the beginning of the error,
252: and
253: .Dq %%%
254: at the end of the error.
1.1 deraadt 255: This makes pattern searching for errors easier with an editor,
256: and allows the messages to be easily removed.
257: In addition, each error message contains the source line number
258: for the line the message refers to.
259: A reasonably formatted source program can be recompiled
260: with the error messages still in it,
261: without having the error messages themselves cause future errors.
262: For poorly formatted source programs in free format languages,
263: such as C or Pascal,
264: it is possible to insert a comment into another comment,
265: which can wreak havoc with a future compilation.
266: To avoid this, programs with comments and source
267: on the same line should be formatted
268: so that language statements appear before comments.
269: .Pp
1.7 aaron 270: .Nm
1.1 deraadt 271: catches interrupt and terminate signals,
272: and if in the insertion phase,
273: will orderly terminate what it is doing.
274: .Sh FILES
275: .Bl -tag -width ~/.errorrc -compact
276: .It Pa ~/.errorrc
277: function names to ignore for
278: .Xr lint 1
279: error messages
280: .It Pa /dev/tty
281: user's teletype
282: .El
283: .Sh HISTORY
284: The
1.7 aaron 285: .Nm
1.1 deraadt 286: command
287: appeared in
288: .Bx 4.0 .
289: .Sh AUTHOR
290: Robert Henry
291: .Sh BUGS
292: Opens the teletype directly to do user querying.
293: .Pp
294: Source files with links make a new copy of the file with
295: only one link to it.
296: .Pp
297: Changing a language processor's format of error messages
298: may cause
1.7 aaron 299: .Nm
1.1 deraadt 300: to not understand the error message.
301: .Pp
1.5 aaron 302: .Nm error ,
1.1 deraadt 303: since it is purely mechanical,
1.8 aaron 304: will not filter out subsequent errors caused by
305: .Dq floodgating
1.1 deraadt 306: initiated by one syntactically trivial error.
307: Humans are still much better at discarding these related errors.
308: .Pp
309: Pascal error messages belong after the lines affected
1.8 aaron 310: (error puts them before). The alignment of the
311: .Sq \e
312: marking the point of error is also disturbed by
1.1 deraadt 313: .Nm error .
314: .Pp
1.7 aaron 315: .Nm
1.1 deraadt 316: was designed for work on
1.5 aaron 317: .Tn CRT Ns s
1.1 deraadt 318: at reasonably high speed.
319: It is less pleasant on slow speed terminals, and has never been
320: used on hardcopy terminals.
![[BACK]](/icons/back.gif){kind=icon}
Return to error.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / error