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