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