usr.bin/error/error.1

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