Annotation of src/usr.bin/error/error.1, Revision 1.1.1.1
1.1 deraadt 1: .\" $NetBSD: error.1,v 1.3 1995/09/02 06:15:20 jtc 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. All advertising materials mentioning features or use of this software
15: .\" must display the following acknowledgement:
16: .\" This product includes software developed by the University of
17: .\" California, Berkeley and its contributors.
18: .\" 4. Neither the name of the University nor the names of its contributors
19: .\" may be used to endorse or promote products derived from this software
20: .\" without specific prior written permission.
21: .\"
22: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32: .\" SUCH DAMAGE.
33: .\"
34: .\" @(#)error.1 8.1 (Berkeley) 6/6/93
35: .\"
36: .Dd June 6, 1993
37: .Dt ERROR 1
38: .Os BSD 4
39: .Sh NAME
40: .Nm error
41: .Nd analyze and disperse compiler error messages
42: .Sh SYNOPSIS
43: .Nm error
44: .Op Fl n
45: .Op Fl s
46: .Op Fl q
47: .Op Fl v
48: .Op Fl t Ar suffixlist
49: .Op Fl I Ar ignorefile
50: .Op name
51: .Sh DESCRIPTION
52: .Nm Error
53: analyzes and optionally disperses the diagnostic error messages
54: produced by a number of compilers and language processors to the source
55: file and line where the errors occurred. It can replace the painful,
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
60: Options are:
61: .Bl -tag -width Ds
62: .It Fl n
63: Do
64: .Em not
65: touch any files; all error messages are sent to the
66: standard output.
67: .It Fl q
68: The user is
69: .Ar queried
70: whether s/he wants to touch the file.
71: A ``y'' or ``n'' to the question is necessary to continue.
72: Absence of the
73: .Fl q
74: option implies that all referenced files
75: (except those referring to discarded error messages)
76: are to be touched.
77: .It Fl v
78: After all files have been touched,
79: overlay the visual editor
80: .Xr \&vi 1
81: with it set up to edit all files touched,
82: and positioned in the first touched file at the first error.
83: If
84: .Xr \&vi 1
85: can't be found, try
86: .Xr \&ex 1
87: or
88: .Xr \&ed 1
89: from standard places.
90: .It Fl t
91: Take the following argument as a suffix list.
92: Files whose suffixes do not appear in the suffix list are not touched.
93: The suffix list is dot separated, and ``*'' wildcards work.
94: Thus the suffix list:
95: .Pp
96: .Dl ".c.y.foo*.h"
97: .Pp
98: allows
99: .Nm error
100: to touch files ending with ``.c'', ``.y'', ``.foo*'' and ``.y''.
101: .It Fl s
102: Print out
103: .Em statistics
104: regarding the error categorization.
105: Not too useful.
106: .El
107: .Pp
108: .Nm Error
109: looks at the error messages,
110: either from the specified file
111: .Ar name
112: or from the standard input,
113: and attempts to determine which
114: language processor produced each error message,
115: determines the source file and line number to which the error message refers,
116: determines if the error message is to be ignored or not,
117: and inserts the (possibly slightly modified) error message into
118: the source file as a comment on the line preceding to which the
119: line the error message refers.
120: Error messages which can't be categorized by language processor
121: or content are not inserted into any file,
122: but are sent to the standard output.
123: .Nm Error
124: touches source files only after all input has been read.
125: .Pp
126: .Nm Error
127: is intended to be run
128: with its standard input
129: connected via a pipe to the error message source.
130: Some language processors put error messages on their standard error file;
131: others put their messages on the standard output.
132: Hence, both error sources should be piped together into
133: .Nm error .
134: For example, when using the
135: .Xr csh 1
136: syntax,
137: .Pp
138: .Dl make \-s lint \&| error \-q \-v
139: .Pp
140: will analyze all the error messages produced
141: by whatever programs
142: .Xr make 1
143: runs when making lint.
144: .Pp
145: .Nm Error
146: knows about the error messages produced by:
147: .Xr make 1 ,
148: .Xr \&cc 1 ,
149: .Xr cpp 1 ,
150: .Xr ccom 1 ,
151: .Xr \&as 1 ,
152: .Xr \&ld 1 ,
153: .Xr lint 1 ,
154: .Xr \&pi 1 ,
155: .Xr \&pc 1 ,
156: .Xr f77 1 ,
157: and
158: .Em DEC Western Research Modula\-2 .
159: .Nm Error
160: knows a standard format for error messages produced by
161: the language processors,
162: so is sensitive to changes in these formats.
163: For all languages except
164: .Em Pascal ,
165: error messages are restricted to be on one line.
166: Some error messages refer to more than one line in more than
167: one files;
168: .Nm error
169: will duplicate the error message and insert it at
170: all of the places referenced.
171: .Pp
172: .Nm Error
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.
178: .Nm Error
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
191: .Pa /usr/libdata/lint/llib-port
192: are discarded,
193: to prevent accidently touching these libraries.
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.
233: .Nm Error
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
257: .Nm Error
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: .Pp
280: Opens the teletype directly to do user querying.
281: .Pp
282: Source files with links make a new copy of the file with
283: only one link to it.
284: .Pp
285: Changing a language processor's format of error messages
286: may cause
287: .Nm error
288: to not understand the error message.
289: .Pp
290: .Nm Error ,
291: since it is purely mechanical,
292: will not filter out subsequent errors caused by `floodgating'
293: initiated by one syntactically trivial error.
294: Humans are still much better at discarding these related errors.
295: .Pp
296: Pascal error messages belong after the lines affected
297: (error puts them before). The alignment of the `\\' marking
298: the point of error is also disturbed by
299: .Nm error .
300: .Pp
301: .Nm Error
302: was designed for work on
303: .Tn CRT Ns 's
304: at reasonably high speed.
305: It is less pleasant on slow speed terminals, and has never been
306: 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