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