Annotation of src/usr.bin/error/error.1, Revision 1.18
1.18 ! jmc 1: .\" $OpenBSD: error.1,v 1.17 2003/06/03 02:56:07 millert 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.
1.17 millert 15: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 16: .\" may be used to endorse or promote products derived from this software
17: .\" without specific prior written permission.
18: .\"
19: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29: .\" SUCH DAMAGE.
30: .\"
31: .\" @(#)error.1 8.1 (Berkeley) 6/6/93
32: .\"
33: .Dd June 6, 1993
34: .Dt ERROR 1
1.6 aaron 35: .Os
1.1 deraadt 36: .Sh NAME
37: .Nm error
38: .Nd analyze and disperse compiler error messages
39: .Sh SYNOPSIS
40: .Nm error
1.12 aaron 41: .Op Fl STnqsv
42: .Op Fl I Ar ignorefile
1.1 deraadt 43: .Op Fl t Ar suffixlist
1.5 aaron 44: .Op Ar name
1.1 deraadt 45: .Sh DESCRIPTION
1.8 aaron 46: The
1.7 aaron 47: .Nm
1.8 aaron 48: utility analyzes and optionally disperses the diagnostic error messages
1.1 deraadt 49: produced by a number of compilers and language processors to the source
1.10 aaron 50: file and line where the errors occurred.
51: It can replace the painful,
1.1 deraadt 52: traditional methods of scribbling abbreviations of errors on paper, and
53: permits error messages and source code to be viewed simultaneously
54: without machinations of multiple windows in a screen editor.
55: .Pp
1.8 aaron 56: The options are as follows:
1.1 deraadt 57: .Bl -tag -width Ds
1.12 aaron 58: .It Fl S
59: Show the errors in unsorted order (as they come from the error file).
60: .It Fl T
61: Terse output.
1.1 deraadt 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
1.9 aaron 68: The user is queried whether or not to touch the file.
1.8 aaron 69: A
70: .Sq y
71: or
72: .Sq n
73: to the question is necessary to continue.
1.1 deraadt 74: Absence of the
75: .Fl q
76: option implies that all referenced files
77: (except those referring to discarded error messages)
78: are to be touched.
1.12 aaron 79: .It Fl s
80: Print out statistics regarding the error categorization.
81: Not too useful.
1.1 deraadt 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.12 aaron 95: .It Fl I Ar ignorefile
96: Specifies a file containing a list of functions to ignore.
1.5 aaron 97: .It Fl t Ar suffixlist
1.1 deraadt 98: Take the following argument as a suffix list.
99: Files whose suffixes do not appear in the suffix list are not touched.
1.8 aaron 100: The suffix list is dot separated, and
101: .Sq \&*
102: wildcards work.
1.1 deraadt 103: Thus the suffix list:
104: .Pp
105: .Dl ".c.y.foo*.h"
106: .Pp
107: allows
1.7 aaron 108: .Nm
1.8 aaron 109: to touch files ending with
1.9 aaron 110: .Dq \&.c ,
111: .Dq \&.y ,
112: .Dq \&.foo\&* ,
1.8 aaron 113: and
1.9 aaron 114: .Dq \&.h .
1.1 deraadt 115: .El
116: .Pp
1.7 aaron 117: .Nm
1.1 deraadt 118: looks at the error messages,
119: either from the specified file
120: .Ar name
121: or from the standard input,
122: and attempts to determine which
123: language processor produced each error message,
1.5 aaron 124: the source file and line number to which the error message refers,
125: if the error message is to be ignored or not,
1.1 deraadt 126: and inserts the (possibly slightly modified) error message into
127: the source file as a comment on the line preceding to which the
128: line the error message refers.
129: Error messages which can't be categorized by language processor
130: or content are not inserted into any file,
131: but are sent to the standard output.
1.7 aaron 132: .Nm
1.1 deraadt 133: touches source files only after all input has been read.
134: .Pp
1.7 aaron 135: .Nm
1.1 deraadt 136: is intended to be run
137: with its standard input
138: connected via a pipe to the error message source.
139: Some language processors put error messages on their standard error file;
140: others put their messages on the standard output.
141: Hence, both error sources should be piped together into
142: .Nm error .
143: For example, when using the
144: .Xr csh 1
145: syntax,
146: .Pp
147: .Dl make \-s lint \&| error \-q \-v
148: .Pp
149: will analyze all the error messages produced
150: by whatever programs
151: .Xr make 1
152: runs when making lint.
153: .Pp
1.7 aaron 154: .Nm
1.1 deraadt 155: knows about the error messages produced by:
1.14 millert 156: .Xr as 1 ,
1.8 aaron 157: .Xr cc 1 ,
1.15 jmc 158: .Xr ccom ,
1.1 deraadt 159: .Xr cpp 1 ,
1.14 millert 160: .Xr f77 1 ,
1.8 aaron 161: .Xr ld 1 ,
1.1 deraadt 162: .Xr lint 1 ,
1.14 millert 163: .Xr make 1 ,
1.15 jmc 164: .Xr pc ,
165: .Xr pi ,
1.14 millert 166: .Xr yacc 1 ,
1.9 aaron 167: and DEC Western Research Modula\-2.
168: .Pp
1.7 aaron 169: .Nm
1.1 deraadt 170: knows a standard format for error messages produced by
171: the language processors,
172: so is sensitive to changes in these formats.
1.5 aaron 173: For all languages except Pascal,
1.1 deraadt 174: error messages are restricted to be on one line.
175: Some error messages refer to more than one line in more than
1.5 aaron 176: one file;
1.7 aaron 177: .Nm
1.1 deraadt 178: will duplicate the error message and insert it at
179: all of the places referenced.
180: .Pp
1.7 aaron 181: .Nm
1.1 deraadt 182: will do one of six things with error messages.
183: .Bl -tag -width Em synchronize
184: .It Em synchronize
185: Some language processors produce short errors describing
186: which file it is processing.
1.7 aaron 187: .Nm
1.1 deraadt 188: uses these to determine the file name for languages that
189: don't include the file name in each error message.
190: These synchronization messages are consumed entirely by
191: .Nm error .
192: .It Em discard
193: Error messages from
194: .Xr lint 1
195: that refer to one of the two
196: .Xr lint 1
197: libraries,
198: .Pa /usr/libdata/lint/llib-lc
199: and
1.5 aaron 200: .Pa /usr/libdata/lint/llib-port ,
1.1 deraadt 201: are discarded,
1.4 deraadt 202: to prevent accidentally touching these libraries.
1.1 deraadt 203: Again, these error messages are consumed entirely by
204: .Nm error .
205: .It Em nullify
206: Error messages from
207: .Xr lint 1
208: can be nullified if they refer to a specific function,
209: which is known to generate diagnostics which are not interesting.
210: Nullified error messages are not inserted into the source file,
211: but are written to the standard output.
212: The names of functions to ignore are taken from
213: either the file named
214: .Pa .errorrc
1.16 jmc 215: in the user's home directory,
1.1 deraadt 216: or from the file named by the
217: .Fl I
218: option.
219: If the file does not exist,
220: no error messages are nullified.
221: If the file does exist, there must be one function
222: name per line.
223: .It Em not file specific
224: Error messages that can't be intuited are grouped together,
225: and written to the standard output before any files are touched.
226: They will not be inserted into any source file.
227: .It Em file specific
1.11 aaron 228: Error messages that refer to a specific file,
1.1 deraadt 229: but to no specific line,
230: are written to the standard output when
231: that file is touched.
232: .It Em true errors
233: Error messages that can be intuited are candidates for
234: insertion into the file to which they refer.
235: .El
236: .Pp
237: Only true error messages are candidates for inserting into
238: the file they refer to.
239: Other error messages are consumed entirely by
1.7 aaron 240: .Nm
1.1 deraadt 241: or are written to the standard output.
1.7 aaron 242: .Nm
1.1 deraadt 243: inserts the error messages into the source file on the line
244: preceding the line the language processor found in error.
245: Each error message is turned into a one line comment for the
246: language,
247: and is internally flagged
1.8 aaron 248: with the string
249: .Dq ###
250: at the beginning of the error,
251: and
252: .Dq %%%
253: at the end of the error.
1.1 deraadt 254: This makes pattern searching for errors easier with an editor,
255: and allows the messages to be easily removed.
256: In addition, each error message contains the source line number
257: for the line the message refers to.
258: A reasonably formatted source program can be recompiled
259: with the error messages still in it,
260: without having the error messages themselves cause future errors.
261: For poorly formatted source programs in free format languages,
262: such as C or Pascal,
263: it is possible to insert a comment into another comment,
264: which can wreak havoc with a future compilation.
265: To avoid this, programs with comments and source
266: on the same line should be formatted
267: so that language statements appear before comments.
268: .Pp
1.7 aaron 269: .Nm
1.1 deraadt 270: catches interrupt and terminate signals,
271: and if in the insertion phase,
272: will orderly terminate what it is doing.
273: .Sh FILES
274: .Bl -tag -width ~/.errorrc -compact
275: .It Pa ~/.errorrc
276: function names to ignore for
277: .Xr lint 1
278: error messages
279: .It Pa /dev/tty
280: user's teletype
281: .El
282: .Sh HISTORY
283: The
1.7 aaron 284: .Nm
1.13 aaron 285: command appeared in
1.1 deraadt 286: .Bx 4.0 .
1.18 ! jmc 287: .Sh AUTHORS
! 288: Robert Henry
1.1 deraadt 289: .Sh BUGS
290: Opens the teletype directly to do user querying.
291: .Pp
292: Source files with links make a new copy of the file with
293: only one link to it.
294: .Pp
295: Changing a language processor's format of error messages
296: may cause
1.7 aaron 297: .Nm
1.1 deraadt 298: to not understand the error message.
299: .Pp
1.5 aaron 300: .Nm error ,
1.1 deraadt 301: since it is purely mechanical,
1.8 aaron 302: will not filter out subsequent errors caused by
303: .Dq floodgating
1.1 deraadt 304: initiated by one syntactically trivial error.
305: Humans are still much better at discarding these related errors.
306: .Pp
307: Pascal error messages belong after the lines affected
1.10 aaron 308: (error puts them before).
309: The alignment of the
1.8 aaron 310: .Sq \e
311: marking the point of error is also disturbed by
1.1 deraadt 312: .Nm error .
313: .Pp
1.7 aaron 314: .Nm
1.1 deraadt 315: was designed for work on
1.5 aaron 316: .Tn CRT Ns s
1.1 deraadt 317: at reasonably high speed.
318: It is less pleasant on slow speed terminals, and has never been
319: 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