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

FreeBSD Manual Pages

  
 
  

home | help
ltrace(1)		    General Commands Manual		     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+12.0-RELEASE+and+Ports>

home | help