dialyzer(3)

NAME
dialyzer - 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

  Note:

* 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:

                    o   "The clause matching on X will never match; argument is of type T"

                    o   "The clause matching on tuple with arity N will never match; "

                    o   " argument is of type T!"

            -   Description:

                    o   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:

                    o   "Call to function X with signature S will fail since the arguments are of type T!"

            -   Description:

                    o   The arguments which the function is called with are not what the function implicitly expects.

    *   Closure of wrong type

            -   Warnings:

                    o   "Fun application using type T instead of a fun!"

                    o   "Trying to use fun with type T with arguments AT"

            -   Description:

                    o   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:

                    o   "Cons will produce a non-proper list since its 2nd arg is of type T!"

                    o   "Call to '++'/2 will produce a non-proper list since its 2nd arg is of type T!"

            -   Description:

                    o   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:

                    o   "Function will never return a proper value!"

            -   Description:

                    o   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:

                    o   "Type guard X will always fail since variable is of type T!"

            -   Description:

                    o   The case clause is redundant since the input argument is of a different type.

    *   Unreachable function clause

            -   Warning:

                    o   "The guard X will always fail since the arguments are of type T!"

            -   Description:

                    o   The clause is made redundant due to one of its guards always failing.

    *   Term comparison failure

            -   Warnings:

                    o   "=:= between T1 and T2 will always fail!"

                    o   "=/= between T1 and T2 will always fail!"

            -   Description:

                    o   The term comparison will always fail making the test always return 'false' or, in a guard context, making the clause redundant.

    *   Unused function

            -   Warning:

                    o   "Function will never be called!"

            -   Description:

                    o   The function is unused; no need to have it uncommented in the code.

CODE RELICS

    *   Tuple used as fun

            -   Warnings:

                    o   "Unsafe use of tuple as a fun in call to X"

                    o   "Tuple used as fun will fail in native compiled code"

            -   Description:

                    o   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:

                    o   "Unsafe BEAM code! Please recompile with a newer BEAM compiler."

            -   Description:

                    o   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