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