Return to ltrace.1 CVS log

Up to [local] / src / usr.bin / ktrace

Annotation of src/usr.bin/ktrace/ltrace.1, Revision 1.2

1.2     ! jmc         1: .\"    $OpenBSD: ltrace.1,v 1.1 2013/06/01 09:57:58 miod Exp $
1.1       miod        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: .\"
1.2     ! jmc        46: .Dd $Mdocdate: June 1 2013 $
1.1       miod       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
                     60: enables shared library function calls issued by the specified processes
                     61: to be traced using the
                     62: .Xr utrace 2
                     63: user tracing facility.
                     64: By default, call trace data is logged to the file
                     65: .Pa ktrace.out ,
                     66: unless overridden by the
                     67: .Fl f
                     68: option.
                     69: Each function call is traced as a pair of
                     70: .Dv KTRFAC_USER
                     71: entries;
                     72: the first entry contains the shared library containing the symbol being
                     73: called, and the second entry contains the symbol name.
                     74: .Pp
                     75: Once tracing is enabled on a process, trace data will be logged until
                     76: either the process exits or the trace point is cleared with
                     77: .Xr ktrace 1 .
                     78: A traced process can generate enormous amounts of log data quickly;
                     79: it is strongly suggested that users memorize how to disable tracing before
                     80: attempting to trace a process.
                     81: The following command is sufficient to disable tracing on all user owned
                     82: processes, and, if executed by root, all processes:
                     83: .Pp
                     84: .Dl $ ktrace -C
                     85: .Pp
                     86: The trace file is not human-readable; use
                     87: .Xr kdump 1
                     88: to decode it.
                     89: .Pp
                     90: The options are as follows:
                     91: .Bl -tag -width 9n
                     92: .It Fl a
                     93: Append to the trace file instead of recreating it.
                     94: .It Fl f Ar trfile
                     95: Log trace records to
                     96: .Ar trfile
                     97: instead of
                     98: .Pa ktrace.out .
                     99: .It Fl i
                    100: Inherit; pass the trace flags to all future children of the designated
                    101: processes.
                    102: .It Fl u Ar trspec
                    103: Restrict the trace to a list of shared objects and/or function names, as
                    104: specified by the
                    105: .Ar trspec
                    106: argument.
                    107: The trace specification is a comma-separated list of library names,
                    108: followed by a colon
1.2     ! jmc       109: .Pq :\& ,
        !           110: and a comma-separated list of function names.
1.1       miod      111: Each list can be empty.
1.2     ! jmc       112: Each list member may end with a star
1.1       miod      113: .Pq *
                    114: to only match the beginning of a name.
                    115: A leading bang at the beginning of a list turns it into a rejection list,
                    116: causing all unmatched names to be traced.
                    117: Library names are compared without their version number and
                    118: .Sq .so
                    119: suffix.
1.2     ! jmc       120: .It Ar command
        !           121: Execute
        !           122: .Ar command
        !           123: with the specified trace flags.
1.1       miod      124: .El
                    125: .Sh FILES
1.2     ! jmc       126: .Bl -tag -width ktrace.outXXX -compact
1.1       miod      127: .It Pa ktrace.out
1.2     ! jmc       128: Default
        !           129: .Nm
        !           130: dump file.
1.1       miod      131: .El
                    132: .Sh EXAMPLES
                    133: Trace all shared library function calls from
                    134: .Xr wc 1
                    135: reading the message of the day:
                    136: .Dl $ ltrace wc -lh /etc/motd
                    137: .Pp
                    138: Trace only the shared library function calls in
                    139: .Pa libutil.so :
                    140: .Dl $ ltrace -u libutil wc -lh /etc/motd
                    141: .Pp
                    142: Trace 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
1.2     ! jmc       146: Trace all the shared library function calls with names starting
1.1       miod      147: .Pq 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