1.\" $OpenBSD: ltrace.1,v 1.10 2016/07/18 09:36:50 guenther 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: July 18 2016 $ 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 t Ar trstr 57.Op Fl u Ar trspec 58.Ar command 59.Sh DESCRIPTION 60.Nm ltrace 61enables shared library function calls issued by the specified processes 62to be traced using the 63.Xr utrace 2 64user tracing facility. 65By default, call trace data is logged to the file 66.Pa ktrace.out , 67unless overridden by the 68.Fl f 69option. 70Each function call is traced as a pair of 71.Dv KTRFAC_USER 72entries; 73the first entry contains the shared library containing the symbol being 74called, and the second entry contains the symbol name. 75.Pp 76Once tracing is enabled on a process, trace data will be logged until 77either the process exits or the trace point is cleared with 78.Xr ktrace 1 . 79A traced process can generate enormous amounts of log data quickly; 80it is strongly suggested that users memorize how to disable tracing before 81attempting to trace a process. 82The following command is sufficient to disable tracing on all user owned 83processes and, if executed by root, all processes: 84.Pp 85.Dl $ ktrace -C 86.Pp 87The trace file is not human-readable; use 88.Xr kdump 1 89to decode it. 90.Pp 91The options are as follows: 92.Bl -tag -width 9n 93.It Fl a 94Append to the trace file instead of recreating it. 95.It Fl f Ar trfile 96Log trace records to 97.Ar trfile 98instead of 99.Pa ktrace.out . 100.It Fl i 101Inherit; pass the trace flags to all future children of the designated 102processes. 103.It Fl t Ar trstr 104The string argument represents the kernel trace points, one per letter. 105The default is just 106.Cm u . 107The following table equates the letters with the trace points: 108.Pp 109.Bl -tag -width flag -offset indent -compact 110.It Cm c 111trace system calls 112.It Cm i 113trace I/O 114.It Cm n 115trace namei translations 116.It Cm p 117trace violation of 118.Xr pledge 2 119restrictions 120.It Cm s 121trace signal processing 122.It Cm t 123trace various structures 124.It Cm u 125trace user data coming from 126.Xr utrace 2 127.It Cm x 128trace argument vector in 129.Xr execve 2 130.It Cm X 131trace environment in 132.Xr execve 2 133.It Cm + 134trace the default points 135.El 136.It Fl u Ar trspec 137Restrict the trace to a list of shared objects and/or function names, as 138specified by the 139.Ar trspec 140argument. 141The trace specification is a comma-separated list of library names, 142followed by a colon 143.Pq :\& , 144and a comma-separated list of function names. 145Each list can be empty. 146Each list member may end with a star 147.Pq * 148to only match the beginning of a name. 149An exclamation mark at the beginning of a list turns it into a rejection list, 150causing all unmatched names to be traced. 151Library names are compared without their version number and 152.Sq .so 153suffix. 154.It Ar command 155Execute 156.Ar command 157with the specified trace flags. 158.El 159.Sh FILES 160.Bl -tag -width ktrace.outXXX -compact 161.It Pa ktrace.out 162Default 163.Nm 164dump file. 165.El 166.Sh EXAMPLES 167Trace all shared library function calls from 168.Xr wc 1 169reading the message of the day: 170.Dl $ ltrace wc -lh /etc/motd 171.Pp 172Trace only the shared library function calls in 173.Pa libutil.so : 174.Dl $ ltrace -u libutil wc -lh /etc/motd 175.Pp 176Trace all the shared library function calls but those in 177.Pa libc.so : 178.Dl $ ltrace -u \(dq!libc\(dq wc -lh /etc/motd 179.Pp 180Trace all the shared library function calls with names starting 181.Qq fmt : 182.Dl $ ltrace -u \(dq:fmt*\(dq wc -lh /etc/motd 183.Pp 184Trace all shared library function calls, as well as all system calls: 185.Dl $ ltrace -t cu wc -lh /etc/motd 186.Sh SEE ALSO 187.Xr kdump 1 , 188.Xr ktrace 1 , 189.Xr ktrace 2 , 190.Xr utrace 2 191.Sh HISTORY 192The 193.Nm ltrace 194command appeared in 195.Ox 5.4 . 196