Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ltrace(1)							     ltrace(1)

NAME
       ltrace -	A library call tracer

SYNOPSIS
       ltrace  [-bCfghiLrStttV]	 [-a column] [-A maxelts] [-D level] [-e expr]
       [-l filename] [-n nr] [-o filename] [-p pid] ...	[-s strsize] [-u user-
       name]   [-w   count]  [-X  extern]  [-x	extern]	 ...  [--align=column]
       [--debug=level] [--demangle]  [--help]  [--indent=nr]  [--library=file-
       name] [--no-signals] [--output=filename]	[--version] [--where=NR] [com-
       mand [arg ...]]

DESCRIPTION
       ltrace is a program that	simply runs the	 specified  command  until  it
       exits.	It  intercepts and records the dynamic library calls which are
       called by the executed process and the signals which  are  received  by
       that  process.	It  can	also intercept and print the system calls exe-
       cuted by	the program.

       Its use is very similar to strace(1).

OPTIONS
       -a, --align column
	      Align return values in a specific	column (default	column is  5/8
	      of screen	width).

       -A maxelts
	      Maximum number of	array elements to print	before suppressing the
	      rest with	an ellipsis ("...")

       -b, --no-signals
	      Disable printing of signals recieved by the traced process.

       -c     Count time and calls for each library call and report a  summary
	      on program exit.

       -C, --demangle
	      Decode  (demangle) low-level symbol names	into user-level	names.
	      Besides removing any initial underscore prefix used by the  sys-
	      tem, this	makes C++ function names readable.

       -D, --debug level
	      Show  debugging output of	ltrace itself.	level must be a	sum of
	      some of the following numbers:

	      01     DEBUG_GENERAL.  Shows helpful progress information

	      010    DEBUG_EVENT.  Shows every event received by a traced pro-
		     gram

	      020    DEBUG_PROCESS.   Shows every action ltrace	carries	upon a
		     traced process

	      040    DEBUG_FUNCTION.  Shows every entry	to internal functions

       -e filter
	      A	qualifying expression which modifies which  library  calls  to
	      trace.   The format of the filter	expression is described	in the
	      section FILTER EXPRESSIONS.  If more than	one -e option  appears
	      on  the  command	line, the library calls	that match any of them
	      are traced.  If no -e is given, @MAIN is assumed as a default.

       -f     Trace child processes as they are	created	 by  currently	traced
	      processes	 as  a result of the fork(2) or	clone(2) system	calls.
	      The new process is attached immediately.

       -g     Do not place breakpoints on PLT entries. This option reduces the
	      output  of  ltrace.  This	is commonly used to avoid tracing libc
	      functions.

       -F     Load an alternate	config file.  Normally,	 /etc/ltrace.conf  and
	      ~/.ltrace.conf will be read (the latter only if it exists).  Use
	      this option to load the given file or files instead of those two
	      default files.

       -h, --help
	      Show a summary of	the options to ltrace and exit.

       -i     Print the	instruction pointer at the time	of the library call.

       -l, --library filename
	      Display  only  the symbols included in the library filename.  Up
	      to 30 library names can be specified with	several	 instances  of
	      this option.

       -L     DON'T display library calls (use it with the -S option).

       -n, --indent nr
	      Indent  trace  output by nr number of spaces for each new	nested
	      call. Using this option makes  the  program  flow	 visualization
	      easy to follow.

       -o, --output filename
	      Write  the  trace	 output	 to  the  file filename	rather than to
	      stderr.

       -p pid Attach to	the process with the process ID	pid and	begin tracing.

       -r     Print  a	relative  timestamp with each line of the trace.  This
	      records the time difference between the beginning	of  successive
	      lines.

       -s strsize
	      Specify the maximum string size to print (the default is 32).

       -S     Display system calls as well as library calls

       -t     Prefix each line of the trace with the time of day.

       -tt    If  given	twice, the time	printed	will include the microseconds.

       -ttt   If given thrice, the time	printed	will include the  microseconds
	      and the leading portion will be printed as the number of seconds
	      since the	epoch.

       -T     Show  the	 time  spent inside each call. This records  the  time
	      difference between the beginning and the end of each call.

       -u username
	      Run command with the userid, groupid and supplementary groups of
	      username.	 This option is	only useful when running as  root  and
	      enables  the correct execution of	setuid and/or setgid binaries.

       -w, --where NR
	      Show backtrace of	NR stack frames	for each traced	function. This
	      option  enabled only if libunwind	support	was enabled at compile
	      time.

       -X extern
	      Some architectures need to know where to set a  breakpoint  that
	      will  be	hit after the dynamic linker has run.  If this flag is
	      used, then the breakpoint	is set at extern,  which  must	be  an
	      external	function.   By	default, '_start' is used.  NOTE: this
	      flag is only available on	the architectures that need it.

       -x filter
	      A	qualifying expression which modifies which symbol table	 entry
	      points  to  trace.   The	format	of  the	 filter	 expression is
	      described	in the section FILTER EXPRESSIONS.  If more  than  one
	      -x  option  appears  on the command line,	the symbols that match
	      any of them are traced.  No entry	points are traced if no	-x  is
	      given.

       -V, --version
	      Show the version number of ltrace	and exit.

FILTER EXPRESSIONS
       Filter  expression  is  a chain of glob-	or regexp-based	rules that are
       used to pick symbols for	tracing	from libraries that the	process	 uses.
       Most  of	 it  is	intuitive, so as an example, the following would trace
       calls to	malloc and free, except	those done by libc:

       -e malloc+free-@libc.so*

       This reads: trace malloc	and free, but don't trace anything that	 comes
       from  libc.   Semi-formally,  the  syntax  of  the  above example looks
       approximately like this:

       {[+-][symbol pattern][@library pattern]}

       Symbol pattern is used to match symbol names, library pattern to	 match
       library SONAMEs.	 Both are implicitly globs, but	can be regular expres-
       sions as	well (see below).  The glob syntax supports meta-characters  *
       and  ?  and  character classes, similarly to what basic bash globs sup-
       port.  ^	and $ are recognized to	mean, respectively, start and  end  of
       given name.

       Both  symbol  pattern and library pattern have to match the whole name.
       If you want to match only a part	of name, surround it with one  or  two
       *'s  as	appropriate.  The exception is if the pattern is not mentioned
       at all, in which	case it's as if	the corresponding pattern were *.  (So
       malloc is really	malloc@* and @libc.* is	really *@libc.*.)

       In  libraries that don't	have an	explicit SONAME, basename is taken for
       SONAME.	That holds for main binary as well: /bin/echo has an  implicit
       SONAME  of  echo.   In  addition	 to that, special library pattern MAIN
       always matches symbols in the main binary  and  never  a	 library  with
       actual SONAME MAIN (use e.g. ^MAIN or [M]AIN for	that).

       If  the	symbol	or  library  pattern  is  surrounded in	slashes	(/like
       this/), then it is considered  a	 regular  expression  instead.	 As  a
       shorthand, instead of writing /x/@/y/, you can write /x@y/.

       If  the library pattern starts with a slash, it is not a	SONAME expres-
       sion, but a path	expression, and	is matched against  the	 library  path
       name.

       The first rule may lack a sign, in which	case + is assumed.  If,	on the
       other hand, the first rule has a	- sign,	it is as if there was  another
       rule @* in front	of it.

       The  above rules	are used to construct the set of traced	symbols.  Each
       candidate symbol	is passed through the  chain  of  above	 rules.	  Ini-
       tially,	the  symbol  is	 unmarked.   If	it symbol matches a + rule, it
       becomes marked, if it matches a - rule, it becomes unmarked.  If, after
       applying	all rules, the symbol is marked, it will be traced.

BUGS
       It has most of the bugs stated in strace(1).

       Manual page and documentation are not very up-to-date.

       Option -f sometimes fails to trace some children.

       It only works on	Linux and in a small subset of architectures.

       If  you	would like to report a bug, send a message to the mailing list
       (ltrace-devel@lists.alioth.debian.org), or use the reportbug(1) program
       if you are under	the Debian GNU/Linux distribution.

FILES
       /etc/ltrace.conf
	      System configuration file

       ~/.ltrace.conf
	      Personal config file, overrides /etc/ltrace.conf

AUTHOR
       Juan Cespedes <cespedes@debian.org>
       Petr Machata <pmachata@redhat.com>

SEE ALSO
       strace(1), ptrace(2)

								     ltrace(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | FILTER EXPRESSIONS | BUGS | FILES | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ltrace&manpath=FreeBSD+11.1-RELEASE+and+Ports>

home | help