Commit | Line | Data |
---|---|---|
d6dcb673 KB |
1 | .\" Copyright (c) 1980, 1990, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
ea733718 | 3 | .\" |
4808ee96 | 4 | .\" %sccs.include.redist.roff% |
ca3a0045 | 5 | .\" |
d6dcb673 | 6 | .\" @(#)error.1 8.1 (Berkeley) %G% |
ea733718 | 7 | .\" |
f35cac8e CL |
8 | .Dd |
9 | .Dt ERROR 1 | |
10 | .Os BSD 4 | |
11 | .Sh NAME | |
12 | .Nm error | |
13 | .Nd analyze and disperse compiler error messages | |
14 | .Sh SYNOPSIS | |
15 | .Nm error | |
16 | .Op Fl n | |
17 | .Op Fl s | |
18 | .Op Fl q | |
19 | .Op Fl v | |
20 | .Op Fl t Ar suffixlist | |
21 | .Op Fl I Ar ignorefile | |
22 | .Op name | |
23 | .Sh DESCRIPTION | |
24 | .Nm Error | |
ea733718 KM |
25 | analyzes and optionally disperses the diagnostic error messages |
26 | produced by a number of compilers and language processors to the source | |
27 | file and line where the errors occurred. It can replace the painful, | |
28 | traditional methods of scribbling abbreviations of errors on paper, and | |
29 | permits error messages and source code to be viewed simultaneously | |
30 | without machinations of multiple windows in a screen editor. | |
f35cac8e CL |
31 | .Pp |
32 | Options are: | |
4808ee96 CL |
33 | .Bl -tag -width Ds |
34 | .It Fl n | |
f35cac8e CL |
35 | Do |
36 | .Em not | |
37 | touch any files; all error messages are sent to the | |
38 | standard output. | |
4808ee96 | 39 | .It Fl q |
f35cac8e CL |
40 | The user is |
41 | .Ar queried | |
42 | whether s/he wants to touch the file. | |
43 | A ``y'' or ``n'' to the question is necessary to continue. | |
44 | Absence of the | |
45 | .Fl q | |
46 | option implies that all referenced files | |
47 | (except those referring to discarded error messages) | |
48 | are to be touched. | |
4808ee96 | 49 | .It Fl v |
f35cac8e CL |
50 | After all files have been touched, |
51 | overlay the visual editor | |
4808ee96 | 52 | .Xr \&vi 1 |
f35cac8e CL |
53 | with it set up to edit all files touched, |
54 | and positioned in the first touched file at the first error. | |
55 | If | |
4808ee96 | 56 | .Xr \&vi 1 |
f35cac8e | 57 | can't be found, try |
4808ee96 | 58 | .Xr \&ex 1 |
f35cac8e | 59 | or |
4808ee96 | 60 | .Xr \&ed 1 |
f35cac8e | 61 | from standard places. |
4808ee96 | 62 | .It Fl t |
f35cac8e CL |
63 | Take the following argument as a suffix list. |
64 | Files whose suffixes do not appear in the suffix list are not touched. | |
65 | The suffix list is dot separated, and ``*'' wildcards work. | |
66 | Thus the suffix list: | |
67 | .Pp | |
68 | .Dl ".c.y.foo*.h" | |
69 | .Pp | |
70 | allows | |
71 | .Nm error | |
72 | to touch files ending with ``.c'', ``.y'', ``.foo*'' and ``.y''. | |
4808ee96 | 73 | .It Fl s |
f35cac8e CL |
74 | Print out |
75 | .Em statistics | |
76 | regarding the error categorization. | |
77 | Not too useful. | |
4808ee96 | 78 | .El |
f35cac8e CL |
79 | .Pp |
80 | .Nm Error | |
ea733718 | 81 | looks at the error messages, |
f35cac8e CL |
82 | either from the specified file |
83 | .Ar name | |
ea733718 KM |
84 | or from the standard input, |
85 | and attempts to determine which | |
86 | language processor produced each error message, | |
87 | determines the source file and line number to which the error message refers, | |
88 | determines if the error message is to be ignored or not, | |
89 | and inserts the (possibly slightly modified) error message into | |
62f70816 | 90 | the source file as a comment on the line preceding to which the |
ea733718 KM |
91 | line the error message refers. |
92 | Error messages which can't be categorized by language processor | |
93 | or content are not inserted into any file, | |
94 | but are sent to the standard output. | |
f35cac8e | 95 | .Nm Error |
ea733718 | 96 | touches source files only after all input has been read. |
f35cac8e CL |
97 | .Pp |
98 | .Nm Error | |
ea733718 KM |
99 | is intended to be run |
100 | with its standard input | |
101 | connected via a pipe to the error message source. | |
102 | Some language processors put error messages on their standard error file; | |
103 | others put their messages on the standard output. | |
104 | Hence, both error sources should be piped together into | |
f35cac8e CL |
105 | .Nm error . |
106 | For example, when using the | |
107 | .Xr csh 1 | |
108 | syntax, | |
109 | .Pp | |
5325ced3 | 110 | .Dl make \-s lint \&| error \-q \-v |
f35cac8e | 111 | .Pp |
ea733718 KM |
112 | will analyze all the error messages produced |
113 | by whatever programs | |
f35cac8e | 114 | .Xr make 1 |
ea733718 | 115 | runs when making lint. |
f35cac8e CL |
116 | .Pp |
117 | .Nm Error | |
ea733718 | 118 | knows about the error messages produced by: |
f35cac8e | 119 | .Xr make 1 , |
4808ee96 | 120 | .Xr \&cc 1 , |
f35cac8e CL |
121 | .Xr cpp 1 , |
122 | .Xr ccom 1 , | |
4808ee96 CL |
123 | .Xr \&as 1 , |
124 | .Xr \&ld 1 , | |
f35cac8e | 125 | .Xr lint 1 , |
4808ee96 CL |
126 | .Xr \&pi 1 , |
127 | .Xr \&pc 1 , | |
f35cac8e | 128 | .Xr f77 1 , |
ea733718 | 129 | and |
f35cac8e CL |
130 | .Em DEC Western Research Modula\-2 . |
131 | .Nm Error | |
ea733718 KM |
132 | knows a standard format for error messages produced by |
133 | the language processors, | |
134 | so is sensitive to changes in these formats. | |
f35cac8e CL |
135 | For all languages except |
136 | .Em Pascal , | |
ea733718 KM |
137 | error messages are restricted to be on one line. |
138 | Some error messages refer to more than one line in more than | |
139 | one files; | |
f35cac8e | 140 | .Nm error |
ea733718 KM |
141 | will duplicate the error message and insert it at |
142 | all of the places referenced. | |
f35cac8e CL |
143 | .Pp |
144 | .Nm Error | |
ea733718 | 145 | will do one of six things with error messages. |
4808ee96 CL |
146 | .Bl -tag -width Em synchronize |
147 | .It Em synchronize | |
ea733718 KM |
148 | Some language processors produce short errors describing |
149 | which file it is processing. | |
f35cac8e | 150 | .Nm Error |
ea733718 KM |
151 | uses these to determine the file name for languages that |
152 | don't include the file name in each error message. | |
153 | These synchronization messages are consumed entirely by | |
f35cac8e | 154 | .Nm error . |
4808ee96 | 155 | .It Em discard |
ea733718 | 156 | Error messages from |
f35cac8e | 157 | .Xr lint 1 |
ea733718 | 158 | that refer to one of the two |
f35cac8e | 159 | .Xr lint 1 |
ea733718 | 160 | libraries, |
f35cac8e | 161 | .Pa /usr/libdata/lint/llib-lc |
ea733718 | 162 | and |
f35cac8e | 163 | .Pa /usr/libdata/lint/llib-port |
ea733718 KM |
164 | are discarded, |
165 | to prevent accidently touching these libraries. | |
166 | Again, these error messages are consumed entirely by | |
f35cac8e | 167 | .Nm error . |
4808ee96 | 168 | .It Em nullify |
ea733718 | 169 | Error messages from |
f35cac8e | 170 | .Xr lint 1 |
ea733718 KM |
171 | can be nullified if they refer to a specific function, |
172 | which is known to generate diagnostics which are not interesting. | |
173 | Nullified error messages are not inserted into the source file, | |
174 | but are written to the standard output. | |
175 | The names of functions to ignore are taken from | |
176 | either the file named | |
f35cac8e CL |
177 | .Pa .errorrc |
178 | in the users's home directory, | |
ea733718 | 179 | or from the file named by the |
f35cac8e | 180 | .Fl I |
ea733718 KM |
181 | option. |
182 | If the file does not exist, | |
183 | no error messages are nullified. | |
184 | If the file does exist, there must be one function | |
185 | name per line. | |
4808ee96 | 186 | .It Em not file specific |
ea733718 KM |
187 | Error messages that can't be intuited are grouped together, |
188 | and written to the standard output before any files are touched. | |
189 | They will not be inserted into any source file. | |
4808ee96 | 190 | .It Em file specific |
ea733718 KM |
191 | Error message that refer to a specific file, |
192 | but to no specific line, | |
193 | are written to the standard output when | |
194 | that file is touched. | |
4808ee96 | 195 | .It Em true errors |
ea733718 KM |
196 | Error messages that can be intuited are candidates for |
197 | insertion into the file to which they refer. | |
4808ee96 | 198 | .El |
f35cac8e | 199 | .Pp |
ea733718 KM |
200 | Only true error messages are candidates for inserting into |
201 | the file they refer to. | |
202 | Other error messages are consumed entirely by | |
f35cac8e | 203 | .Nm error |
ea733718 | 204 | or are written to the standard output. |
f35cac8e | 205 | .Nm Error |
ea733718 | 206 | inserts the error messages into the source file on the line |
62f70816 | 207 | preceding the line the language processor found in error. |
ea733718 KM |
208 | Each error message is turned into a one line comment for the |
209 | language, | |
210 | and is internally flagged | |
211 | with the string ``###'' at | |
212 | the beginning of the error, | |
213 | and ``%%%'' at the end of the error. | |
214 | This makes pattern searching for errors easier with an editor, | |
215 | and allows the messages to be easily removed. | |
216 | In addition, each error message contains the source line number | |
217 | for the line the message refers to. | |
218 | A reasonably formatted source program can be recompiled | |
219 | with the error messages still in it, | |
220 | without having the error messages themselves cause future errors. | |
221 | For poorly formatted source programs in free format languages, | |
222 | such as C or Pascal, | |
223 | it is possible to insert a comment into another comment, | |
224 | which can wreak havoc with a future compilation. | |
62f70816 KM |
225 | To avoid this, programs with comments and source |
226 | on the same line should be formatted | |
227 | so that language statements appear before comments. | |
f35cac8e CL |
228 | .Pp |
229 | .Nm Error | |
ea733718 KM |
230 | catches interrupt and terminate signals, |
231 | and if in the insertion phase, | |
232 | will orderly terminate what it is doing. | |
f35cac8e | 233 | .Sh FILES |
4808ee96 CL |
234 | .Bl -tag -width ~/.errorrc -compact |
235 | .It Pa ~/.errorrc | |
f35cac8e CL |
236 | function names to ignore for |
237 | .Xr lint 1 | |
238 | error messages | |
4808ee96 | 239 | .It Pa /dev/tty |
f35cac8e | 240 | user's teletype |
4808ee96 | 241 | .El |
f35cac8e | 242 | .Sh HISTORY |
4808ee96 CL |
243 | The |
244 | .Nm error | |
245 | command | |
246 | appeared in | |
247 | .Bx 4.0 . | |
f35cac8e | 248 | .Sh AUTHOR |
ea733718 | 249 | Robert Henry |
f35cac8e CL |
250 | .Sh BUGS |
251 | .Pp | |
ea733718 | 252 | Opens the teletype directly to do user querying. |
f35cac8e | 253 | .Pp |
ea733718 KM |
254 | Source files with links make a new copy of the file with |
255 | only one link to it. | |
f35cac8e | 256 | .Pp |
ea733718 | 257 | Changing a language processor's format of error messages |
f35cac8e CL |
258 | may cause |
259 | .Nm error | |
ea733718 | 260 | to not understand the error message. |
f35cac8e CL |
261 | .Pp |
262 | .Nm Error , | |
ea733718 KM |
263 | since it is purely mechanical, |
264 | will not filter out subsequent errors caused by `floodgating' | |
265 | initiated by one syntactically trivial error. | |
266 | Humans are still much better at discarding these related errors. | |
f35cac8e | 267 | .Pp |
ea733718 | 268 | Pascal error messages belong after the lines affected |
f35cac8e | 269 | (error puts them before). The alignment of the `\\' marking |
ea733718 | 270 | the point of error is also disturbed by |
f35cac8e CL |
271 | .Nm error . |
272 | .Pp | |
273 | .Nm Error | |
4808ee96 CL |
274 | was designed for work on |
275 | .Tn CRT Ns 's | |
276 | at reasonably high speed. | |
ea733718 KM |
277 | It is less pleasant on slow speed terminals, and has never been |
278 | used on hardcopy terminals. |