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

FreeBSD Manual Pages


home | help
ltrace(1)		    General Commands Manual		     ltrace(1)

       ltrace -	A library call tracer

       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]	[--de-
       bug=level]  [--demangle]	 [--help]  [--indent=nr]  [--library=filename]
       [--no-signals]  [--output=filename]  [--version]	 [--where=NR] [command
       [arg ...]]

       ltrace is a program that	simply runs the	specified command until	it ex-
       its.   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).

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

	      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

       -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

       -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

       -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

       -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 ex-
	      ternal 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  de-
	      scribed  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

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

       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:


       This  reads: trace malloc and free, but don't trace anything that comes
       from libc.  Semi-formally, the syntax of	the above  example  looks  ap-
       proximately 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  al-
       ways 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

       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  be-
       comes  marked,  if it matches a - rule, it becomes unmarked.  If, after
       applying	all rules, the symbol is marked, it will be traced.

       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
       (, or use the reportbug(1) program
       if you are under	the Debian GNU/Linux distribution.

	      System configuration file

	      Personal config file, overrides /etc/ltrace.conf

       Juan Cespedes <>
       Petr Machata <>

       strace(1), ptrace(2)



Want to link to this manual page? Use this URL:

home | help