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