1.\" $NetBSD: error.1,v 1.18 2012/01/22 09:25:26 apb 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 January 22, 2012 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 . 137.Pp 138For example, when using the 139.Xr sh 1 140syntax 141.Pp 142.Dl make \-s lint 2\*[Gt]\*[Am]1 \&| error \-q \-v 143.Pp 144or the 145.Xr csh 1 146syntax 147.Pp 148.Dl make \-s lint \&|\*[Am] error \-q \-v 149.Pp 150.Nm 151will analyze all the error messages produced 152by whatever programs 153.Xr make 1 154runs when making lint. 155.Pp 156.Nm 157knows about the error messages produced by: 158.Xr make 1 , 159.Xr \&cc 1 , 160.Xr cpp 1 , 161.Ic ccom , 162.Xr \&as 1 , 163.Xr \&ld 1 , 164.Xr lint 1 , 165.Ic \&pi , 166.Ic \&pc , 167.Xr f77 1 , 168and 169.Em DEC Western Research Modula\-2 . 170.Nm 171knows a standard format for error messages produced by 172the language processors, 173so is sensitive to changes in these formats. 174For all languages except 175.Em Pascal , 176error messages are restricted to be on one line. 177Some error messages refer to more than one line in more than 178one files; 179.Nm 180will duplicate the error message and insert it at 181all of the places referenced. 182.Pp 183.Nm 184will do one of six things with error messages. 185.Bl -tag -width synchronize 186.It Em synchronize 187Some language processors produce short errors describing 188which file it is processing. 189.Nm 190uses these to determine the file name for languages that 191don't include the file name in each error message. 192These synchronization messages are consumed entirely by 193.Nm . 194.It Em discard 195Error messages from 196.Xr lint 1 197that refer to one of the two 198.Xr lint 1 199libraries, 200.Pa /usr/libdata/lint/llib-lc 201and 202.Pa /usr/libdata/lint/llib-port 203are discarded, 204to prevent accidentally touching these libraries. 205Again, these error messages are consumed entirely by 206.Nm . 207.It Em nullify 208Error messages from 209.Xr lint 1 210can be nullified if they refer to a specific function, 211which is known to generate diagnostics which are not interesting. 212Nullified error messages are not inserted into the source file, 213but are written to the standard output. 214The names of functions to ignore are taken from 215either the file named 216.Pa .errorrc 217in the user's home directory, 218or from the file named by the 219.Fl I 220option. 221If the file does not exist, 222no error messages are nullified. 223If the file does exist, there must be one function 224name per line. 225.It Em not file specific 226Error messages that can't be intuited are grouped together, 227and written to the standard output before any files are touched. 228They will not be inserted into any source file. 229.It Em file specific 230Error message that refer to a specific file, 231but to no specific line, 232are written to the standard output when 233that file is touched. 234.It Em true errors 235Error messages that can be intuited are candidates for 236insertion into the file to which they refer. 237.El 238.Pp 239Only true error messages are candidates for inserting into 240the file they refer to. 241Other error messages are consumed entirely by 242.Nm 243or are written to the standard output. 244.Nm 245inserts the error messages into the source file on the line 246preceding the line the language processor found in error. 247Each error message is turned into a one line comment for the 248language, 249and is internally flagged 250with the string ``###'' at 251the beginning of the error, 252and ``%%%'' at the end of the error. 253This makes pattern searching for errors easier with an editor, 254and allows the messages to be easily removed. 255In addition, each error message contains the source line number 256for the line the message refers to. 257A reasonably formatted source program can be recompiled 258with the error messages still in it, 259without having the error messages themselves cause future errors. 260For poorly formatted source programs in free format languages, 261such as C or Pascal, 262it is possible to insert a comment into another comment, 263which can wreak havoc with a future compilation. 264To avoid this, programs with comments and source 265on the same line should be formatted 266so that language statements appear before comments. 267.Pp 268.Nm 269catches interrupt and terminate signals, 270and if in the insertion phase, 271will orderly terminate what it is doing. 272.Sh FILES 273.Bl -tag -width ~/.errorrc -compact 274.It Pa ~/.errorrc 275function names to ignore for 276.Xr lint 1 277error messages 278.It Pa /dev/tty 279user's teletype 280.El 281.Sh HISTORY 282The 283.Nm 284command 285appeared in 286.Bx 4.0 . 287.Sh AUTHORS 288.An Robert Henry 289.Sh BUGS 290Opens the teletype directly to do user querying. 291.Pp 292Source files with links make a new copy of the file with 293only one link to it. 294.Pp 295Changing a language processor's format of error messages 296may cause 297.Nm 298to not understand the error message. 299.Pp 300.Nm , 301since it is purely mechanical, 302will not filter out subsequent errors caused by `floodgating' 303initiated by one syntactically trivial error. 304Humans are still much better at discarding these related errors. 305.Pp 306Pascal error messages belong after the lines affected 307(error puts them before). The alignment of the `\e' marking 308the point of error is also disturbed by 309.Nm . 310.Pp 311.Nm 312was designed for work on 313.Tn CRT Ns 's 314at reasonably high speed. 315It is less pleasant on slow speed terminals, and has never been 316used on hardcopy terminals. 317