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