Annotation of src/usr.bin/error/error.1, Revision 1.2
1.2 ! deraadt 1: .\" $OpenBSD: error.1,v 1.3 1995/09/02 06:15:20 jtc 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
39: .Os BSD 4
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
51: .Op name
52: .Sh DESCRIPTION
53: .Nm Error
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.
91: .It Fl t
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
101: to touch files ending with ``.c'', ``.y'', ``.foo*'' and ``.y''.
102: .It Fl s
103: Print out
104: .Em statistics
105: regarding the error categorization.
106: Not too useful.
107: .El
108: .Pp
109: .Nm Error
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,
116: determines the source file and line number to which the error message refers,
117: determines if the error message is to be ignored or not,
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.
124: .Nm Error
125: touches source files only after all input has been read.
126: .Pp
127: .Nm Error
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
146: .Nm Error
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 .
160: .Nm Error
161: knows a standard format for error messages produced by
162: the language processors,
163: so is sensitive to changes in these formats.
164: For all languages except
165: .Em Pascal ,
166: error messages are restricted to be on one line.
167: Some error messages refer to more than one line in more than
168: one files;
169: .Nm error
170: will duplicate the error message and insert it at
171: all of the places referenced.
172: .Pp
173: .Nm Error
174: will do one of six things with error messages.
175: .Bl -tag -width Em synchronize
176: .It Em synchronize
177: Some language processors produce short errors describing
178: which file it is processing.
179: .Nm Error
180: uses these to determine the file name for languages that
181: don't include the file name in each error message.
182: These synchronization messages are consumed entirely by
183: .Nm error .
184: .It Em discard
185: Error messages from
186: .Xr lint 1
187: that refer to one of the two
188: .Xr lint 1
189: libraries,
190: .Pa /usr/libdata/lint/llib-lc
191: and
192: .Pa /usr/libdata/lint/llib-port
193: are discarded,
194: to prevent accidently touching these libraries.
195: Again, these error messages are consumed entirely by
196: .Nm error .
197: .It Em nullify
198: Error messages from
199: .Xr lint 1
200: can be nullified if they refer to a specific function,
201: which is known to generate diagnostics which are not interesting.
202: Nullified error messages are not inserted into the source file,
203: but are written to the standard output.
204: The names of functions to ignore are taken from
205: either the file named
206: .Pa .errorrc
207: in the users's home directory,
208: or from the file named by the
209: .Fl I
210: option.
211: If the file does not exist,
212: no error messages are nullified.
213: If the file does exist, there must be one function
214: name per line.
215: .It Em not file specific
216: Error messages that can't be intuited are grouped together,
217: and written to the standard output before any files are touched.
218: They will not be inserted into any source file.
219: .It Em file specific
220: Error message that refer to a specific file,
221: but to no specific line,
222: are written to the standard output when
223: that file is touched.
224: .It Em true errors
225: Error messages that can be intuited are candidates for
226: insertion into the file to which they refer.
227: .El
228: .Pp
229: Only true error messages are candidates for inserting into
230: the file they refer to.
231: Other error messages are consumed entirely by
232: .Nm error
233: or are written to the standard output.
234: .Nm Error
235: inserts the error messages into the source file on the line
236: preceding the line the language processor found in error.
237: Each error message is turned into a one line comment for the
238: language,
239: and is internally flagged
240: with the string ``###'' at
241: the beginning of the error,
242: and ``%%%'' at the end of the error.
243: This makes pattern searching for errors easier with an editor,
244: and allows the messages to be easily removed.
245: In addition, each error message contains the source line number
246: for the line the message refers to.
247: A reasonably formatted source program can be recompiled
248: with the error messages still in it,
249: without having the error messages themselves cause future errors.
250: For poorly formatted source programs in free format languages,
251: such as C or Pascal,
252: it is possible to insert a comment into another comment,
253: which can wreak havoc with a future compilation.
254: To avoid this, programs with comments and source
255: on the same line should be formatted
256: so that language statements appear before comments.
257: .Pp
258: .Nm Error
259: catches interrupt and terminate signals,
260: and if in the insertion phase,
261: will orderly terminate what it is doing.
262: .Sh FILES
263: .Bl -tag -width ~/.errorrc -compact
264: .It Pa ~/.errorrc
265: function names to ignore for
266: .Xr lint 1
267: error messages
268: .It Pa /dev/tty
269: user's teletype
270: .El
271: .Sh HISTORY
272: The
273: .Nm error
274: command
275: appeared in
276: .Bx 4.0 .
277: .Sh AUTHOR
278: Robert Henry
279: .Sh BUGS
280: .Pp
281: Opens the teletype directly to do user querying.
282: .Pp
283: Source files with links make a new copy of the file with
284: only one link to it.
285: .Pp
286: Changing a language processor's format of error messages
287: may cause
288: .Nm error
289: to not understand the error message.
290: .Pp
291: .Nm Error ,
292: since it is purely mechanical,
293: will not filter out subsequent errors caused by `floodgating'
294: initiated by one syntactically trivial error.
295: Humans are still much better at discarding these related errors.
296: .Pp
297: Pascal error messages belong after the lines affected
298: (error puts them before). The alignment of the `\\' marking
299: the point of error is also disturbed by
300: .Nm error .
301: .Pp
302: .Nm Error
303: was designed for work on
304: .Tn CRT Ns 's
305: at reasonably high speed.
306: It is less pleasant on slow speed terminals, and has never been
307: 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