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