1.\" $OpenBSD: ltrace.1,v 1.11 2023/09/30 13:03:40 naddy 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 30 2023 $ 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.\" Keep this list in sync with kdump(1) and ktrace(1). 111.It Cm c 112trace system calls 113.It Cm i 114trace I/O 115.It Cm n 116trace namei translations 117.It Cm p 118trace violation of 119.Xr pledge 2 120restrictions 121.It Cm s 122trace signal processing 123.It Cm t 124trace various structures 125.It Cm u 126trace user data coming from 127.Xr utrace 2 128.It Cm x 129trace argument vector in 130.Xr execve 2 131.It Cm X 132trace environment in 133.Xr execve 2 134.It Cm + 135trace the default points 136.El 137.It Fl u Ar trspec 138Restrict the trace to a list of shared objects and/or function names, as 139specified by the 140.Ar trspec 141argument. 142The trace specification is a comma-separated list of library names, 143followed by a colon 144.Pq :\& , 145and a comma-separated list of function names. 146Each list can be empty. 147Each list member may end with a star 148.Pq * 149to only match the beginning of a name. 150An exclamation mark at the beginning of a list turns it into a rejection list, 151causing all unmatched names to be traced. 152Library names are compared without their version number and 153.Sq .so 154suffix. 155.It Ar command 156Execute 157.Ar command 158with the specified trace flags. 159.El 160.Sh FILES 161.Bl -tag -width ktrace.outXXX -compact 162.It Pa ktrace.out 163Default 164.Nm 165dump file. 166.El 167.Sh EXAMPLES 168Trace all shared library function calls from 169.Xr wc 1 170reading the message of the day: 171.Dl $ ltrace wc -lh /etc/motd 172.Pp 173Trace only the shared library function calls in 174.Pa libutil.so : 175.Dl $ ltrace -u libutil wc -lh /etc/motd 176.Pp 177Trace all the shared library function calls but those in 178.Pa libc.so : 179.Dl $ ltrace -u \(dq!libc\(dq wc -lh /etc/motd 180.Pp 181Trace all the shared library function calls with names starting 182.Qq fmt : 183.Dl $ ltrace -u \(dq:fmt*\(dq wc -lh /etc/motd 184.Pp 185Trace all shared library function calls, as well as all system calls: 186.Dl $ ltrace -t cu wc -lh /etc/motd 187.Sh SEE ALSO 188.Xr kdump 1 , 189.Xr ktrace 1 , 190.Xr ktrace 2 , 191.Xr utrace 2 192.Sh HISTORY 193The 194.Nm ltrace 195command appeared in 196.Ox 5.4 . 197