# dialyzer

### COMMAND

dialyzer

### COMMAND SUMMARY

Erlang Dialyzer

### DESCRIPTION

This is the command line version for automated use. Below is a brief description of the list of its options. The same information can be obtained by writing

            "dialyzer --help"

in a shell. Please refer to the GUI description in the User's Guide, for more details on the operation of Dialyzer.

The exit status of the command line version is:

        0 - No problems were encountered during the analysis and no
            warnings were emitted.
        1 - Problems were encountered during the analysis.
        2 - No problems were encountered, but warnings were emitted.

    Usage: dialyzer [--otp OTP_DIR] [--help] [--version] [--shell]
                     [-pa dir]* [-plt plt] [-Ddefine]* [-I include_dir]*
                     [--output_plt file] [-Wwarn]*  [--src]
                     [-c applications] [-r applications] [-o outfile] [-q]

    Options:
       -c applications (or --command-line applications)
           use Dialyzer from the command line (no GUI) to detect defects in the
           specified applications (directories or .erl or .beam files)
       -r applications
           same as -c only that directories are searched recursively for
           subdirectories containing .erl or .beam files (depending on the
           type of analysis)
       -o outfile (or --output outfile)
           when using Dialyzer from the command line, send the analysis
           results in the specified "outfile" rather than in stdout
       --src
           overwrite the default, which is to analyze BEAM bytecode, and
           analyze starting from Erlang source code instead
       -Dname (or -Dname=value)
           when analyzing from source, pass the define to Dialyzer (**)
       -I include_dir
           when analyzing from source, pass the include_dir to Dialyzer (**)
       --output_plt file
           Store the plt at the specified location after building it.
       --no_warn_on_inline
           Suppress warnings when analyzing an inline compiled bytecode file.
       -plt plt
           Use the specified plt as the initial plt. If the plt was built
           during setup the files will be checked for consistency.
       -pa dir
           Include dir in the path for Erlang. Useful when analyzing files
           that have '-include_lib()' directives.
       -Wwarn
           a family of option which selectively turn on/off warnings.
            (for help on the names of warnings use dialyzer -Whelp)
       --otp OTP_DIR
           overrides the default location of the Erlang/OTP system to use
       --shell
           do not disable the Erlang shell while running the GUI
       --version (or -v)
           prints the Dialyzer version and some more information and exits
       --help (or -h)
           prints this message and exits
       -q
           makes Dialyzer a bit more quiet

| * denotes that multiple occurrences of these options are possible. ** options -D and -I work both from command-line and in the Dialyzer GUI; the syntax of defines and includes is the same as that used by "erlc".

    Warning options:
      -Wno_return
         Suppress warnings for functions of no return.
      -Wno_unused
         Suppress warnings for unused functions.
      -Wno_improper_lists
         Suppress warnings for construction of improper lists.
      -Wno_tuple_as_fun
         Suppress warnings for using tuples instead of funs.
      -Wno_fun_app
         Suppress warnings for fun applications that will fail.
      -Wno_match
         Suppress warnings for pattern matching operations that will never
         succeed.
      -Wno_comp
         Suppress warnings for term comparisons that will always return false.
      -Wno_guards
         Suppress warnings for guards that will always fail.
      -Wno_unsafe_beam
         Suppress warnings for unsafe BEAM code produced by an old
         BEAM compiler.
      -Werror_handling ***
         Include warnings for functions that only return by means of an
         exception.
    Note:
       *** This is the only option that turns on warnings rather than
           turning them off.

### Identified discrepancies

The discrepancies currently identified by Dialyzer can be classified in the following categories:

TYPE ERRORS

- Match failure
  - Warnings:
    - "The clause matching on X will never match; argument is of type T"
    - "The clause matching on tuple with arity N will never match; "
    - " argument is of type T!"
  - Description:
    - The function or case clause will never match since the calling argument has a different type than the expected one. Note that due to pattern-matching compilation the X above may be an argument enclosed in some structured term (tuple or list).
- Function call with wrong arguments
  - Warning:
    - "Call to function X with signature S will fail since the arguments are of type T!"
  - Description:
    - The arguments which the function is called with are not what the function implicitly expects.
- Closure of wrong type
  - Warnings:
    - "Fun application using type T instead of a fun!"
    - "Trying to use fun with type T with arguments AT"
  - Description:
    - The variable that is used in the fun application is either not a closure (fun entry) or a closure with the wrong domain.
- Improper list construction
  - Warnings:
    - "Cons will produce a non-proper list since its 2nd arg is of type T!"
    - "Call to '++'/2 will produce a non-proper list since its 2nd arg is of type T!"
  - Description:
    - This is a place where an improper list (i.e., a list whose last element is not the empty list []) is constructed. Strictly, these are not discrepancies in Erlang, but we strongly recommend that you fix these; there is ABSOLUTELY NO reason to create improper lists.
- Function of no return
  - Warning:
    - "Function will never return a proper value!"
  - Description:
    - This is a function that never returns. Strictly speaking, this is not a function and the code is OK only if this is used as a point where an exception is thrown when handling an error.

REDUNDANT OR UNREACHABLE CODE

- Unreachable case clause
  - Warning:
    - "Type guard X will always fail since variable is of type T!"
  - Description:
    - The case clause is redundant since the input argument is of a different type.
- Unreachable function clause
  - Warning:
    - "The guard X will always fail since the arguments are of type T!"
  - Description:
    - The clause is made redundant due to one of its guards always failing.
- Term comparison failure
  - Warnings:
    - "=:= between T1 and T2 will always fail!"
    - "=/= between T1 and T2 will always fail!"
  - Description:
    - The term comparison will always fail making the test always return 'false' or, in a guard context, making the clause redundant.
- Unused function
  - Warning:
    - "Function will never be called!"
  - Description:
    - The function is unused; no need to have it uncommented in the code.

CODE RELICS

- Tuple used as fun
  - Warnings:
    - "Unsafe use of tuple as a fun in call to X"
    - "Tuple used as fun will fail in native compiled code"
  - Description:
    - A 2-tuple is used as a function closure. The modern way of calling higher-order code in Erlang is by using proper funs. The code should be rewritten using a proper 'fun' rather than a 2-tuple since among other things makes the code cleaner and is safer for execution in native code.
- Unsafe BEAM code
  - Warning:
    - "Unsafe BEAM code! Please recompile with a newer BEAM compiler."
  - Description:
    - The analysis has encountered BEAM bytecode which will fail in a really bad way (even with a seg-fault) if used in an impoper way. Such code was produced by the BEAM compiler of R9C-0 (and prior) for some record expressions. The recommended action is to generate a new .beam file using a newer version of the BEAM compiler.

### Feedback & bug reports

At this point, we very much welcome user feedback (even wish-lists!). If you notice something weird, especially if the Dialyzer reports any discrepancy that is a false positive, please send an error report describing the symptoms and how to reproduce them

### AUTHORS

Tobias Lindahl - support@erlang.ericsson.se
Kostis Sagonas - support@erlang.ericsson.se

dialyzer 1.5.0
Copyright © 1991-2006 Ericsson AB