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