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.\" from: @(#)error.1 6.7 (Berkeley) 7/24/91 33.\" $Id: error.1,v 1.2 1993/08/01 07:33:08 mycroft Exp $ 34.\" 35.Dd July 24, 1991 36.Dt ERROR 1 37.Os BSD 4 38.Sh NAME 39.Nm error 40.Nd analyze and disperse compiler error messages 41.Sh SYNOPSIS 42.Nm error 43.Op Fl n 44.Op Fl s 45.Op Fl q 46.Op Fl v 47.Op Fl t Ar suffixlist 48.Op Fl I Ar ignorefile 49.Op name 50.Sh DESCRIPTION 51.Nm Error 52analyzes and optionally disperses the diagnostic error messages 53produced by a number of compilers and language processors to the source 54file and line where the errors occurred. It can replace the painful, 55traditional methods of scribbling abbreviations of errors on paper, and 56permits error messages and source code to be viewed simultaneously 57without machinations of multiple windows in a screen editor. 58.Pp 59Options are: 60.Bl -tag -width Ds 61.It Fl n 62Do 63.Em not 64touch any files; all error messages are sent to the 65standard output. 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 v 77After all files have been touched, 78overlay the visual editor 79.Xr \&vi 1 80with it set up to edit all files touched, 81and positioned in the first touched file at the first error. 82If 83.Xr \&vi 1 84can't be found, try 85.Xr \&ex 1 86or 87.Xr \&ed 1 88from standard places. 89.It Fl t 90Take the following argument as a suffix list. 91Files whose suffixes do not appear in the suffix list are not touched. 92The suffix list is dot separated, and ``*'' wildcards work. 93Thus the suffix list: 94.Pp 95.Dl ".c.y.foo*.h" 96.Pp 97allows 98.Nm error 99to touch files ending with ``.c'', ``.y'', ``.foo*'' and ``.y''. 100.It Fl s 101Print out 102.Em statistics 103regarding the error categorization. 104Not too useful. 105.El 106.Pp 107.Nm Error 108looks at the error messages, 109either from the specified file 110.Ar name 111or from the standard input, 112and attempts to determine which 113language processor produced each error message, 114determines the source file and line number to which the error message refers, 115determines if the error message is to be ignored or not, 116and inserts the (possibly slightly modified) error message into 117the source file as a comment on the line preceding to which the 118line the error message refers. 119Error messages which can't be categorized by language processor 120or content are not inserted into any file, 121but are sent to the standard output. 122.Nm Error 123touches source files only after all input has been read. 124.Pp 125.Nm Error 126is intended to be run 127with its standard input 128connected via a pipe to the error message source. 129Some language processors put error messages on their standard error file; 130others put their messages on the standard output. 131Hence, both error sources should be piped together into 132.Nm error . 133For example, when using the 134.Xr csh 1 135syntax, 136.Pp 137.Dl make \-s lint \&| error \-q \-v 138.Pp 139will analyze all the error messages produced 140by whatever programs 141.Xr make 1 142runs when making lint. 143.Pp 144.Nm Error 145knows about the error messages produced by: 146.Xr make 1 , 147.Xr \&cc 1 , 148.Xr cpp 1 , 149.Xr ccom 1 , 150.Xr \&as 1 , 151.Xr \&ld 1 , 152.Xr lint 1 , 153.Xr \&pi 1 , 154.Xr \&pc 1 , 155.Xr f77 1 , 156and 157.Em DEC Western Research Modula\-2 . 158.Nm Error 159knows a standard format for error messages produced by 160the language processors, 161so is sensitive to changes in these formats. 162For all languages except 163.Em Pascal , 164error messages are restricted to be on one line. 165Some error messages refer to more than one line in more than 166one files; 167.Nm error 168will duplicate the error message and insert it at 169all of the places referenced. 170.Pp 171.Nm Error 172will do one of six things with error messages. 173.Bl -tag -width Em synchronize 174.It Em synchronize 175Some language processors produce short errors describing 176which file it is processing. 177.Nm Error 178uses these to determine the file name for languages that 179don't include the file name in each error message. 180These synchronization messages are consumed entirely by 181.Nm error . 182.It Em discard 183Error messages from 184.Xr lint 1 185that refer to one of the two 186.Xr lint 1 187libraries, 188.Pa /usr/libdata/lint/llib-lc 189and 190.Pa /usr/libdata/lint/llib-port 191are discarded, 192to prevent accidently touching these libraries. 193Again, these error messages are consumed entirely by 194.Nm error . 195.It Em nullify 196Error messages from 197.Xr lint 1 198can be nullified if they refer to a specific function, 199which is known to generate diagnostics which are not interesting. 200Nullified error messages are not inserted into the source file, 201but are written to the standard output. 202The names of functions to ignore are taken from 203either the file named 204.Pa .errorrc 205in the users's home directory, 206or from the file named by the 207.Fl I 208option. 209If the file does not exist, 210no error messages are nullified. 211If the file does exist, there must be one function 212name per line. 213.It Em not file specific 214Error messages that can't be intuited are grouped together, 215and written to the standard output before any files are touched. 216They will not be inserted into any source file. 217.It Em file specific 218Error message that refer to a specific file, 219but to no specific line, 220are written to the standard output when 221that file is touched. 222.It Em true errors 223Error messages that can be intuited are candidates for 224insertion into the file to which they refer. 225.El 226.Pp 227Only true error messages are candidates for inserting into 228the file they refer to. 229Other error messages are consumed entirely by 230.Nm error 231or are written to the standard output. 232.Nm Error 233inserts the error messages into the source file on the line 234preceding the line the language processor found in error. 235Each error message is turned into a one line comment for the 236language, 237and is internally flagged 238with the string ``###'' at 239the beginning of the error, 240and ``%%%'' at the end of the error. 241This makes pattern searching for errors easier with an editor, 242and allows the messages to be easily removed. 243In addition, each error message contains the source line number 244for the line the message refers to. 245A reasonably formatted source program can be recompiled 246with the error messages still in it, 247without having the error messages themselves cause future errors. 248For poorly formatted source programs in free format languages, 249such as C or Pascal, 250it is possible to insert a comment into another comment, 251which can wreak havoc with a future compilation. 252To avoid this, programs with comments and source 253on the same line should be formatted 254so that language statements appear before comments. 255.Pp 256.Nm Error 257catches interrupt and terminate signals, 258and if in the insertion phase, 259will orderly terminate what it is doing. 260.Sh FILES 261.Bl -tag -width ~/.errorrc -compact 262.It Pa ~/.errorrc 263function names to ignore for 264.Xr lint 1 265error messages 266.It Pa /dev/tty 267user's teletype 268.El 269.Sh HISTORY 270The 271.Nm error 272command 273appeared in 274.Bx 4.0 . 275.Sh AUTHOR 276Robert Henry 277.Sh BUGS 278.Pp 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 error 287to not understand the error message. 288.Pp 289.Nm Error , 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 error . 299.Pp 300.Nm Error 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