error(1)							     error(1)



NAME

  error - Analyzes and disperses compiler error messages

SYNOPSIS

  error [-n] [-q] [-s] [-v] [-t suffix_list] [-I ignore_file] [file]

  The error program analyzes and optionally disperses the diagnostic error
  messages produced by a number of compilers and language processors to the
  source file and line where the errors occurred.

FLAGS

  -I ignore_file
      Takes the names of functions to ignore from ignore_file.	If the -I
      flag is not specified, the function names are taken from a file named
      .errorrc in the users's home directory. If this file does not exist, no
      error messages are nullified.  Function names must be listed one per
      line in ignore_file or in the .errorrc file.

  -n  Does not touch any files; all error messages are sent to the standard
      output.

  -q  Queries the user whether or not to touch the file.  You must enter y or
      n, or the locale's equivalent of an affirmative or negative response,
      before continuing.  If you do not specify the -q flag, all referenced
      files (except those referring to discarded error messages) are touched
      by default.

  -s  Prints out statistics regarding the error categorization.

  -t suffix_list
      Does not touch files whose suffixes do not appear suffix_list.  The
      suffix list is dot-separated, and * wildcards may be used.  For exam-
      ple, the suffix list .c.y.foo*.h allows error to touch files ending
      with .c, .y, .foo* and .y.

  -v  Overlays and sets up the visual editor vi to edit all files touched,
      and positions the editor at the first error in the first touched file.
      If vi cannot be found, try ex or ed from standard places.

DESCRIPTION

  Using the error program can replace the painful, traditional methods of
  scribbling abbreviations of errors on paper, and permits error messages and
  source code to be viewed simultaneously without machinations of multiple
  windows in a screen editor.

  The error program looks at the error messages, either from the specified
  file file or from the standard input, and performs the following opera-
  tions:

    +  Attempts to determine which language processor produced each error
       message.

    +  Determines the source file and line number to which the error message
       refers.

    +  Determines if the error message is to be ignored or not.

    +  Inserts the (possibly slightly modified) error message into the source
       file as a comment on the line preceding to which the line the error
       message refers.

    +  Sends error messages that cannot be categorized by language processor
       or content to the standard output; does not insert these error mes-
       sages into any file,
  The error program touches source files only after all input has been read.

  error is intended to be run with its standard input connected via a pipe to
  the error message source.  Some language processors put error messages on
  their standard error file; others put their messages on the standard out-
  put.	Hence, both error sources should be piped together into error.	For
  example, when using the csh syntax, the following command line analyzes all
  the error messages produced by whatever programs make runs when making
  lint:

       make -s lint | error -q -v

  error knows about the error messages produced by the following programs:

    +  as

    +  cc

    +  ccom

    +  cpp

    +  f77

    +  ld

    +  lint

    +  make

    +  pc

    +  pi
  error knows a standard format for error messages produced by the language
  processors, so is sensitive to changes in these formats.  For all languages
  except Pascal, error messages are restricted to be on one line.  Some error
  messages refer to more than one line in more than one file; error dupli-
  cates the error message and inserts it at all of the places referenced.

  error does one of six things with error messages:

  Synchronizes
      Some language processors produce short errors describing which file it
      is processing.  error uses these to determine the file name for
      languages that do not include the file name in each error message.
      These synchronization messages are consumed entirely by error.

  Discards
      Error messages from lint that refer to one of the two lint libraries,
      /usr/libdata/lint/llib-lc and /usr/libdata/lint/llib-port are dis-
      carded, to prevent accidentally touching these libraries.	 Again, these
      error messages are consumed entirely by error.

  Nullifies
      Error messages from lint can be nullified if they refer to a specific
      function, which is known to generate diagnostics which are not
      interesting.  Nullified error messages are not inserted into the source
      file, but are written to the standard output.  The names of lint func-
      tions to ignore are taken from either the file named .errorrc in the
      user's home directory, or from the file named by the -I flag.  If the
      file does not exist, no error messages are nullified.  If the file does
      exist, there must be one function name per line.

  Identifies Non-File-Specific Messages
      Error messages that cannot be "intuited" are grouped together, and
      written to the standard output before any files are touched.  These
      messages are not inserted into any source file.

  Identifies File-Specific Messages
      Error message that refer to a specific file, but to no specific line,
      are written to the standard output when that file is touched.

  Identifies True Errors
      Error messages that can be "intuited" are candidates for insertion into
      the file to which they refer.

  Only true error messages are candidates for inserting into the file to
  which they refer.  Other error messages are consumed entirely by error or
  are written to the standard output.  error inserts the error messages into
  the source file on the line preceding the line the language processor found
  in error.  Each error message is turned into a one-line comment for the
  language, and is internally flagged with the string ### at the beginning of
  the error, and %%% at the end of the error.  This makes pattern searching
  for errors easier with an editor, and allows the messages to be easily
  removed.  In addition, each error message contains the source line number
  for the line to which the message refers.  A reasonably formatted source
  program can be recompiled with the error messages still in it, without hav-
  ing the error messages themselves cause future errors.  For poorly format-
  ted source programs in free format languages, such as C or Pascal, it is
  possible to insert a comment into another comment, which can wreak havoc
  with a future compilation.  To avoid this, programs with comments and
  source on the same line should be formatted so that language statements
  appear before comments.

  error catches interrupt and terminate signals, and if in the insertion
  phase, will orderly terminate what it is doing.

FILES

  ~/.errorrc Function names to ignore for lint error messages.

  /dev/tty   User's teletype.

NOTES

   1.  Opens the teletype directly to do user querying.

   2.  Source files with links make a new copy of the file with only one link
       to it.

   3.  Changing a language processor's format of error messages may cause
       error to not understand the error message.

   4.  The error program, since it is purely mechanical, does not filter out
       subsequent errors caused by "floodgating" initiated by one syntacti-
       cally trivial error.  Humans are still much better at discarding these
       related errors.

   5.  Pascal error messages belong after the lines affected (error puts them
       before).	 The alignment of the \\ marking the point of error is also
       disturbed by error.

   6.  error was designed for work on CRTs at reasonably high speed.  It is
       less pleasant on slow speed terminals, and has never been used on
       hardcopy terminals.