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