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