1.\" $OpenBSD: ltrace.1,v 1.4 2013/09/12 09:27:27 jmc Exp $ 2.\" 3.\" Copyright (c) 2013 Miodrag Vallat. 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.\" Copyright (c) 1990, 1993 18.\" The Regents of the University of California. All rights reserved. 19.\" 20.\" Redistribution and use in source and binary forms, with or without 21.\" modification, are permitted provided that the following conditions 22.\" are met: 23.\" 1. Redistributions of source code must retain the above copyright 24.\" notice, this list of conditions and the following disclaimer. 25.\" 2. Redistributions in binary form must reproduce the above copyright 26.\" notice, this list of conditions and the following disclaimer in the 27.\" documentation and/or other materials provided with the distribution. 28.\" 3. Neither the name of the University nor the names of its contributors 29.\" may be used to endorse or promote products derived from this software 30.\" without specific prior written permission. 31.\" 32.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 33.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 34.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 35.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 36.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 37.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 38.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 39.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 40.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 41.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 42.\" SUCH DAMAGE. 43.\" 44.\" from: @(#)ktrace.1 8.1 (Berkeley) 6/6/93 45.\" 46.Dd $Mdocdate: September 12 2013 $ 47.Dt LTRACE 1 48.Os 49.Sh NAME 50.Nm ltrace 51.Nd shared library function call tracer 52.Sh SYNOPSIS 53.Nm ltrace 54.Op Fl ai 55.Op Fl f Ar trfile 56.Op Fl u Ar trspec 57.Ar command 58.Sh DESCRIPTION 59.Nm ltrace 60enables shared library function calls issued by the specified processes 61to be traced using the 62.Xr utrace 2 63user tracing facility. 64By default, call trace data is logged to the file 65.Pa ktrace.out , 66unless overridden by the 67.Fl f 68option. 69Each function call is traced as a pair of 70.Dv KTRFAC_USER 71entries; 72the first entry contains the shared library containing the symbol being 73called, and the second entry contains the symbol name. 74.Pp 75Once tracing is enabled on a process, trace data will be logged until 76either the process exits or the trace point is cleared with 77.Xr ktrace 1 . 78A traced process can generate enormous amounts of log data quickly; 79it is strongly suggested that users memorize how to disable tracing before 80attempting to trace a process. 81The following command is sufficient to disable tracing on all user owned 82processes, and, if executed by root, all processes: 83.Pp 84.Dl $ ktrace -C 85.Pp 86The trace file is not human-readable; use 87.Xr kdump 1 88to decode it. 89.Pp 90The options are as follows: 91.Bl -tag -width 9n 92.It Fl a 93Append to the trace file instead of recreating it. 94.It Fl f Ar trfile 95Log trace records to 96.Ar trfile 97instead of 98.Pa ktrace.out . 99.It Fl i 100Inherit; pass the trace flags to all future children of the designated 101processes. 102.It Fl u Ar trspec 103Restrict the trace to a list of shared objects and/or function names, as 104specified by the 105.Ar trspec 106argument. 107The trace specification is a comma-separated list of library names, 108followed by a colon 109.Pq :\& , 110and a comma-separated list of function names. 111Each list can be empty. 112Each list member may end with a star 113.Pq * 114to only match the beginning of a name. 115An exclamation mark at the beginning of a list turns it into a rejection list, 116causing all unmatched names to be traced. 117Library names are compared without their version number and 118.Sq .so 119suffix. 120.It Ar command 121Execute 122.Ar command 123with the specified trace flags. 124.El 125.Sh FILES 126.Bl -tag -width ktrace.outXXX -compact 127.It Pa ktrace.out 128Default 129.Nm 130dump file. 131.El 132.Sh EXAMPLES 133Trace all shared library function calls from 134.Xr wc 1 135reading the message of the day: 136.Dl $ ltrace wc -lh /etc/motd 137.Pp 138Trace only the shared library function calls in 139.Pa libutil.so : 140.Dl $ ltrace -u libutil wc -lh /etc/motd 141.Pp 142Trace all the shared library function calls but those in 143.Pa libc.so : 144.Dl $ ltrace -u \(dq!libc\(dq wc -lh /etc/motd 145.Pp 146Trace all the shared library function calls with names starting 147.Qq fmt : 148.Dl $ ltrace -u \(dq:fmt*\(dq wc -lh /etc/motd 149.Sh SEE ALSO 150.Xr kdump 1 , 151.Xr ktrace 1 , 152.Xr ktrace 2 , 153.Xr utrace 2 154