1.\" Copyright (c) 1980, 1990, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.roff% 5.\" 6.\" @(#)error.1 8.1 (Berkeley) 06/06/93 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.Bl -tag -width Ds 34.It Fl n 35Do 36.Em not 37touch any files; all error messages are sent to the 38standard output. 39.It 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.It 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.It 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.It Fl s 74Print out 75.Em statistics 76regarding the error categorization. 77Not too useful. 78.El 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.Bl -tag -width Em synchronize 147.It Em synchronize 148Some language processors produce short errors describing 149which file it is processing. 150.Nm Error 151uses these to determine the file name for languages that 152don't include the file name in each error message. 153These synchronization messages are consumed entirely by 154.Nm error . 155.It Em discard 156Error messages from 157.Xr lint 1 158that refer to one of the two 159.Xr lint 1 160libraries, 161.Pa /usr/libdata/lint/llib-lc 162and 163.Pa /usr/libdata/lint/llib-port 164are discarded, 165to prevent accidently touching these libraries. 166Again, these error messages are consumed entirely by 167.Nm error . 168.It Em nullify 169Error messages from 170.Xr lint 1 171can be nullified if they refer to a specific function, 172which is known to generate diagnostics which are not interesting. 173Nullified error messages are not inserted into the source file, 174but are written to the standard output. 175The names of functions to ignore are taken from 176either the file named 177.Pa .errorrc 178in the users's home directory, 179or from the file named by the 180.Fl I 181option. 182If the file does not exist, 183no error messages are nullified. 184If the file does exist, there must be one function 185name per line. 186.It Em not file specific 187Error messages that can't be intuited are grouped together, 188and written to the standard output before any files are touched. 189They will not be inserted into any source file. 190.It Em file specific 191Error message that refer to a specific file, 192but to no specific line, 193are written to the standard output when 194that file is touched. 195.It Em true errors 196Error messages that can be intuited are candidates for 197insertion into the file to which they refer. 198.El 199.Pp 200Only true error messages are candidates for inserting into 201the file they refer to. 202Other error messages are consumed entirely by 203.Nm error 204or are written to the standard output. 205.Nm Error 206inserts the error messages into the source file on the line 207preceding the line the language processor found in error. 208Each error message is turned into a one line comment for the 209language, 210and is internally flagged 211with the string ``###'' at 212the beginning of the error, 213and ``%%%'' at the end of the error. 214This makes pattern searching for errors easier with an editor, 215and allows the messages to be easily removed. 216In addition, each error message contains the source line number 217for the line the message refers to. 218A reasonably formatted source program can be recompiled 219with the error messages still in it, 220without having the error messages themselves cause future errors. 221For poorly formatted source programs in free format languages, 222such as C or Pascal, 223it is possible to insert a comment into another comment, 224which can wreak havoc with a future compilation. 225To avoid this, programs with comments and source 226on the same line should be formatted 227so that language statements appear before comments. 228.Pp 229.Nm Error 230catches interrupt and terminate signals, 231and if in the insertion phase, 232will orderly terminate what it is doing. 233.Sh FILES 234.Bl -tag -width ~/.errorrc -compact 235.It Pa ~/.errorrc 236function names to ignore for 237.Xr lint 1 238error messages 239.It Pa /dev/tty 240user's teletype 241.El 242.Sh HISTORY 243The 244.Nm error 245command 246appeared in 247.Bx 4.0 . 248.Sh AUTHOR 249Robert Henry 250.Sh BUGS 251.Pp 252Opens the teletype directly to do user querying. 253.Pp 254Source files with links make a new copy of the file with 255only one link to it. 256.Pp 257Changing a language processor's format of error messages 258may cause 259.Nm error 260to not understand the error message. 261.Pp 262.Nm Error , 263since it is purely mechanical, 264will not filter out subsequent errors caused by `floodgating' 265initiated by one syntactically trivial error. 266Humans are still much better at discarding these related errors. 267.Pp 268Pascal error messages belong after the lines affected 269(error puts them before). The alignment of the `\\' marking 270the point of error is also disturbed by 271.Nm error . 272.Pp 273.Nm Error 274was designed for work on 275.Tn CRT Ns 's 276at reasonably high speed. 277It is less pleasant on slow speed terminals, and has never been 278used on hardcopy terminals. 279