1
<!doctype comref PUBLIC "-//Stork//DTD comref//EN">
4
``The contents of this file are subject to the Erlang Public License,
5
Version 1.1, (the "License"); you may not use this file except in
6
compliance with the License. You should have received a copy of the
7
Erlang Public License along with this software. If not, it can be
8
retrieved via the world wide web at http://www.erlang.org/.
10
Software distributed under the License is distributed on an "AS IS"
11
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
12
the License for the specific language governing rights and limitations
15
The Initial Developer of the Original Code is Ericsson Utvecklings AB.
16
Portions created by Ericsson are Copyright 1999, Ericsson Utvecklings
17
AB. All Rights Reserved.''
23
<TITLE>dialyzer</TITLE>
24
<PREPARED>Tobias Lindahl and Kostis Sagonas</PREPARED>
30
<COMSUMMARY>Erlang Dialyzer</COMSUMMARY>
32
<P>This is the command line version for automated use. Below is a
33
brief description of the list of its options. The same information can
34
be obtained by writing</P>
37
<INPUT>"dialyzer --help"</INPUT>
40
<P>in a shell. Please refer to the GUI description in the User's Guide, for more details on the operation of Dialyzer.</P>
42
<P>The exit status of the command line version is:</P>
45
0 - No problems were encountered during the analysis and no
46
warnings were emitted.
47
1 - Problems were encountered during the analysis.
48
2 - No problems were encountered, but warnings were emitted.
52
Usage: dialyzer [--otp OTP_DIR] [--help] [--version] [--shell]
53
[-pa dir]* [-plt plt] [-Ddefine]* [-I include_dir]*
54
[--output_plt file] [-Wwarn]* [--src]
55
[-c applications] [-r applications] [-o outfile] [-q]
58
-c applications (or --command-line applications)
59
use Dialyzer from the command line (no GUI) to detect defects in the
60
specified applications (directories or .erl or .beam files)
62
same as -c only that directories are searched recursively for
63
subdirectories containing .erl or .beam files (depending on the
65
-o outfile (or --output outfile)
66
when using Dialyzer from the command line, send the analysis
67
results in the specified "outfile" rather than in stdout
69
overwrite the default, which is to analyze BEAM bytecode, and
70
analyze starting from Erlang source code instead
71
-Dname (or -Dname=value)
72
when analyzing from source, pass the define to Dialyzer (**)
74
when analyzing from source, pass the include_dir to Dialyzer (**)
76
Store the plt at the specified location after building it.
78
Suppress warnings when analyzing an inline compiled bytecode file.
80
Use the specified plt as the initial plt. If the plt was built
81
during setup the files will be checked for consistency.
83
Include dir in the path for Erlang. Useful when analyzing files
84
that have '-include_lib()' directives.
86
a family of option which selectively turn on/off warnings.
87
(for help on the names of warnings use dialyzer -Whelp)
89
overrides the default location of the Erlang/OTP system to use
91
do not disable the Erlang shell while running the GUI
93
prints the Dialyzer version and some more information and exits
95
prints this message and exits
97
makes Dialyzer a bit more quiet
101
<P>* denotes that multiple occurrences of these options are possible.</P>
102
<P> ** options -D and -I work both from command-line and in the Dialyzer GUI;
103
the syntax of defines and includes is the same as that used by "erlc".</P>
109
Suppress warnings for functions of no return.
111
Suppress warnings for unused functions.
113
Suppress warnings for construction of improper lists.
115
Suppress warnings for using tuples instead of funs.
117
Suppress warnings for fun applications that will fail.
119
Suppress warnings for pattern matching operations that will never
122
Suppress warnings for term comparisons that will always return false.
124
Suppress warnings for guards that will always fail.
126
Suppress warnings for unsafe BEAM code produced by an old
129
Include warnings for functions that only return by means of an
132
*** This is the only option that turns on warnings rather than
140
<TITLE>Identified discrepancies</TITLE>
141
<P>The discrepancies currently identified by Dialyzer can be classified
142
in the following categories:</P>
146
<P><EM>TYPE ERRORS</EM></P
148
<ITEM><P>Match failure</P>
150
<ITEM><P>Warnings:</P>
153
<P>"The clause matching on X will never match; argument is of type T"</P>
156
<P>"The clause matching on tuple with arity N will never match; "</P>
159
<P>" argument is of type T!"</P>
163
<ITEM><P>Description:</P>
166
<P>The function or case clause will never match since the calling
167
argument has a different type than the expected one.
168
Note that due to pattern-matching compilation the X above may be
169
an argument enclosed in some structured term (tuple or list).</P>
175
<ITEM><P>Function call with wrong arguments</P>
177
<ITEM><P>Warning:</P>
180
<P>"Call to function X with signature S will fail since the arguments are of type T!"</P>
184
<ITEM><P>Description:</P>
187
<P>The arguments which the function is called with are
188
not what the function implicitly expects.</P>
193
<ITEM><P>Closure of wrong type</P>
195
<ITEM><P>Warnings:</P>
198
<P>"Fun application using type T instead of a fun!"</P>
201
<P>"Trying to use fun with type T with arguments AT"</P>
205
<ITEM><P>Description:</P>
208
<P>The variable that is used in the fun application is either not
209
a closure (fun entry) or a closure with the wrong domain.</P>
215
<ITEM><P>Improper list construction</P>
217
<ITEM><P>Warnings:</P>
220
<P>"Cons will produce a non-proper list since its 2nd arg is of type T!"</P>
223
<P>"Call to '++'/2 will produce a non-proper list since its 2nd arg is of type T!"</P>
227
<ITEM><P>Description:</P>
230
<P>This is a place where an improper list (i.e., a list whose last
231
element is not the empty list []) is constructed. Strictly, these
232
are not discrepancies in Erlang, but we strongly recommend that
233
you fix these; there is ABSOLUTELY NO reason to create improper lists.</P>
239
<ITEM><P>Function of no return</P>
241
<ITEM><P>Warning:</P>
244
<P>"Function will never return a proper value!"</P>
248
<ITEM><P>Description:</P>
251
<P>This is a function that never returns. Strictly speaking, this
252
is not a function and the code is OK only if this is used as a
253
point where an exception is thrown when handling an error.</P>
263
<P><EM>REDUNDANT OR UNREACHABLE CODE</EM></P>
267
<P>Unreachable case clause</P>
273
<P>"Type guard X will always fail since variable is of type T!"</P>
281
<P>The case clause is redundant since the input argument is of a
289
<P>Unreachable function clause</P>
295
<P>"The guard X will always fail since the arguments are of type T!"</P>
303
<P>The clause is made redundant due to one of its guards always failing.</P>
310
<P>Term comparison failure</P>
316
<P>"=:= between T1 and T2 will always fail!"</P>
319
<P>"=/= between T1 and T2 will always fail!"</P>
327
<P>The term comparison will always fail making the test always return
328
'false' or, in a guard context, making the clause redundant.</P>
335
<P>Unused function</P>
341
<P>"Function will never be called!"</P>
349
<P>The function is unused; no need to have it uncommented in the code.</P>
359
<P><EM>CODE RELICS</EM></P>
363
<P>Tuple used as fun</P>
369
<P>"Unsafe use of tuple as a fun in call to X"</P>
372
<P>"Tuple used as fun will fail in native compiled code"</P>
380
<P>A 2-tuple is used as a function closure. The modern way of
381
calling higher-order code in Erlang is by using proper funs.
382
The code should be rewritten using a proper 'fun' rather than
383
a 2-tuple since among other things makes the code cleaner and
384
is safer for execution in native code.</P>
391
<P>Unsafe BEAM code</P>
397
<P>"Unsafe BEAM code! Please recompile with a newer BEAM compiler."</P>
405
<P>The analysis has encountered BEAM bytecode which will fail in a
406
really bad way (even with a seg-fault) if used in an impoper way.
407
Such code was produced by the BEAM compiler of R9C-0 (and prior)
408
for some record expressions. The recommended action is to
409
generate a new .beam file using a newer version of the BEAM
421
<TITLE>Feedback & bug reports</TITLE>
423
<P>At this point, we very much welcome user feedback (even wish-lists!).
424
If you notice something weird, especially if the Dialyzer reports any
425
discrepancy that is a false positive, please send an error report
426
describing the symptoms and how to reproduce them</P>
431
<ANAME> Tobias Lindahl</ANAME>
432
<EMAIL> tobias.lindahl@it.uu.se</EMAIL>
433
<ANAME> Kostis Sagonas</ANAME>
434
<EMAIL> kostis@it.uu.se</EMAIL>
added
removed
lib/dialyzer/doc/src/dialyzer.sgml
