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