mtree.1

这是一个C程序分析工具

.TH MTREE 1 "3 April 1995"
.SH NAME
mtree \- call-graph printer for Standard (ANSI/ISO) C
.SH SYNOPSIS
.B mtree
[
.BI \-c indention
] [
.B \-C
] [
.BI \-D name =
.cc +
... ]
+cc .
.if n .ti +5
[
.BI \-D name = def
.cc +
... ] [
+cc .
.B \-g
] [
.B \-l
] [
.BI \-m file-margin
]
.if n .ti +5
.if t .ti +.5i
[
.B \-n
] [
.BI \-o output-file
] [
.BI \-r root-function
]
.if n .ti +5
[
.BI \-S subst-file
.cc +
... ] [
+cc .
.B \-t
] [
.B \-w
]
.if t .ti +.5i
[
.I input-file
.cc +
... ]
+cc .
.RE
.LP
.B mtree
.BI \-f resp-file
.TP
.B mtree \-h
.SH DESCRIPTION
.LP
.B mtree
accepts
.I Standard C
as input and prints one or more call graphs and an optional table of
contents. Each call graph is printed as an annotated, indented tree of
function names. Once the tree for the root-function has been printed,
.B mtree
prints call trees for functions that have not yet taken part in a call
tree. This is especially useful for function libraries, where there is
not just one root function.
.LP
Input is taken from the list of
.IR input-file s
that are named on the command line. If no
.IR input-file s
are specified, input is taken from standard input. Output is written to
standard output or, if the
.B \-o
option is used, to the
.IR output-file .
.SH OPTIONS
Options may appear in any order and may be interspersed with
.IR input-file s.
There are no spaces between an option and its argument. Options cannot be
combined into a single argument.
.TP
.BI \-c indention
Number of columns to indent each call level. For example,
.B \-c8
causes
.B mtree
to indent each level by eight columns. The default is by four columns.
.TP
.B \-C
Causes the input stream to be interspersed with the output stream.
.TP
.BI \-D name =
Remove all occurences of
.I name
from the input stream. Can be repeated any number of times.
.TP
.BI \-D name = def
Replace all occurences of
.I name
in the input stream with
.IR def .
Can be repeated any number of times. The
.B \-D
option may be enough to convert any compiler-specific extensions you are
using to something that
.B mtree
understands as Standard C syntax. For example, since Borland uses
.B cdecl
in its
.B stdio.h
file, I have to use the following command to get
.B mtree
to accept it:
.RS
.IP
.B mtree \-Dcdecl= trerules.i
.RE
.IP
This defines cdecl as a null string, effectively removing all
occurrences from the input stream. There may also be a situation where a
lexeme used in a declaration could be converted to another, as in the
following:
.RS
.IP
.B mtree \-Dselector=int foo.i
.RE
.IP
The lexeme,
.BR selector ,
is a type specifier recognized by Intel's iRMX C compiler.
.IP
Depending on which command-line interpreter, or shell, you are using,
quoting a definition option may allow you to specify expansion text
that contains imbedded spaces, such as
.B
"\-Dulong=unsigned long"
.cc +
.
+cc .
.TP
.BI \-f resp-file
Read all command-line options from a
.IR "response file" .
For example,
.BR \-fmtree.cmd ,
causes
.B mtree
to ignore any other arguments on the command line and use whatever
arguments are in the file,
.BR mtree.cmd .
The arguments in this file can be specified on one or more lines. Any input
or output redirection must be specified on the command line,
however. A response file is especially useful when
.B mtree
is executed repeatedly with a large number of command-line arguments,
such as file names or
.B \-D
options.
.TP
.B \-g
Use graphic characters for tree. The tree graphically connects calling
functions with called functions. By default,
.B mtree
uses ASCII characters to draw the tree lines so that its output is
displayable on virtually all output devices. The
.B \-g
option overrides this behavior and causes
.B mtree
to use line-draw characters from the
.IR "IBM graphic character set" .
Trees drawn with these characters look much nicer. Many printers,
including laser printers, have a font that contains these characters.
Use the
.B \-n
option if you do not want
.B mtree
to draw the tree at all.
.TP
.B \-h
Display help.
.TP
.B \-l
Ignore calls to functions in the Standard C library, such as
.BR printf() .
This is useful if you want to consider these functions as part of the
language and do not want the call-graph cluttered with their calls.
.TP
.BI \-m file-margin
Width of the left margin within which
.B mtree
prints file names.
.B mtree
right-justifies the file name within this margin and truncates any
extras characters to the left so that some path information may be lost.
This assures that at least the file name can be seen. The default
.I file-margin
is 12 columns. As an example,
.B \-m20
allows for a margin for potentially longer UNIX file names. Specify
.B \-m0
if you do not want the file name in the output.
.TP
.B \-n
Do not draw the calling-hierarchy tree. See the
.B \-g
option.
.TP
.BI \-o output-file
Redirect output to a file, e.g.,
.BR \-oout.txt .
This is provided for environments such as VMS that do not have
command-line redirection.
.TP
.BI \-r root-function
If a
.I root-function
is specified, e.g.,
.BR \-rlog_transaction ,
.B mtree
starts the first tree with that function as its root. If not specified,
.B mtree
starts with the function named
.BI main .
If there is no
.B main
function,
.B mtree
starts with the first function it encounters.
.TP
.BI \-S subst-file
Substitute
.I input-file
name. Since
.B mtree
reports the name of the
.I input-file
and this may not be the name of the
original source file (for example, you ran the preprocessor on it but
the preprocessor did not generate line directives which would contain
the name of the original file), the
.B \-S
option can be used to specify the name of the original file, e.g.,
.BR \-Smyfile.c .
This option can be repeated so that each instance specifies a
.I subst-file
name for each
.IR input-file ,
respectively. If you entered this line:
.RS
.IP
.B mtree \-Sa.c \-Sb.c a.i b.i
.RE
.IP
the
.B mtree
output would use the name,
.BR a.c ,
for the first file
.RB ( a.i )
and
.B b.c
for the second file
.RB ( b.i ).
.TP
.B \-t
Print table of contents after the call tree(s). This lists all functions
by file name along with the line number on which they are defined.
.BR mtree "'s"
file, function, and line are analogous to a book's part, chapter, and page.
.TP
.B \-w
Suppress warning diagnostics.
.SH NOTES
.LP
This is the man page for the
.B mtree
call-graph printer that is part of the Metre source-code distribution.
.LP
.B mtree
refers to lines by number in an
.I input-file
unless it encounters a line directive, for example,
.IP
.B
#line 5 "startup.c"
.LP
or
.IP
.B
# 503 "main.c" 2
.LP
It replaces the current line number and file name with whatever is specified
in the line directive. Some preprocessors can place line directives in the
output file that relate back to the original source file. If yours can, you
probably want to instruct it to do so.
.LP
.B mtree
ignores preprocessor directives (from
.B #
to end-of-line) other than line
directives, so if your preprocessor passes any through, such as
.BR #pragmas ,
everything should be okay. This could also be useful if you
only rely on the preprocessor for simple substitution. If so, you might
be able to get away with running your C source file directly into
.B mtree
without being preprocessed.
.LP
While this is a UNIX man page,
.B mtree
is portable across operating systems. This explains references that may seem
out of place or redundant for the UNIX environment, such as the
.B \-o
option.
.SH "SEE ALSO"
The man page or other documentation for your Standard C compiler or
preprocessor.
.LP
The documentation file,
.BR metre.doc ,
which accompanies the Metre source-code distribution.
.SH BUGS
For the name of a called function,
.B mtree
uses the identifier immediately before the call's
.RB "'" ( "'."
This may give misleading results if a function is called through an
expression that yields a function pointer.
.LP
.B mtree
ignores duplicate function names. This only causes a problem if you have
identically named functions in different files with interal linkage,
e.g,
.BR "static foo() {" ... } .
.B mtree
ignores the second and subsequent definitions of functions with the same
name.
.LP
While
.B mtree
recognizes C comments, for example,
.BR "/* a comment */" ,
it does not recognize
C++ comments\-those that begin with
.BR // .
.LP
The
.B \-C
option only works if
.B mtree
was built with an MKS or AT&T lexer and not a flex or pclex lexer. The
lexer distributed with
.B mtree
is an MKS lexer. If built with a flex or pclex lexer, this option is ignored.
.LP
.B mtree
does not perform preprocessing, so you should typically run your source
through a preprocessor first and then run the output of the preprocessor
into
.BR mtree .
.LP
All typedefs are treated as if they have file scope.
.LP
Structure members cannot have the same name as a visible typedef.