rpms/ltrace
7
0
Fork 0
Code Issues Pull Requests Releases Activity

Add man page improvements

Browse Source
This commit is contained in:
Petr Machata 2013-01-11 23:43:48 +01:00
parent 5bfaa48406
commit 3a2cf5cf11
2 changed files with 374 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

364
ltrace-0.7.2-man.patch Normal file
View File

@ -0,0 +1,364 @@
From b340bd5fc0448da0079e02d4ede8c123d14a1620 Mon Sep 17 00:00:00 2001
From: Petr Machata <pmachata@redhat.com>
Date: Fri, 11 Jan 2013 23:32:17 +0100
Subject: [PATCH] Update documentation
- Add several missing options to synopsis in ltrace.1
- Synchronize naming of arguments between ltrace.1 and --help
- Fix formatting in ltrace.1 -- argument names should be in emphasis,
only the argument metavariables should.
---
ltrace.1 | 207 ++++++++++++++++++++++++++++++++-----------------------------
options.c | 18 +++---
2 files changed, 118 insertions(+), 107 deletions(-)
diff --git a/ltrace.1 b/ltrace.1
index 8b459ee..7f3c5bc 100644
--- a/ltrace.1
+++ b/ltrace.1
@@ -1,5 +1,5 @@
.\" -*-nroff-*-
-.\" Copyright (c) 2012 Petr Machata, Red Hat Inc.
+.\" Copyright (c) 2012, 2013 Petr Machata, Red Hat Inc.
.\" Copyright (c) 1997-2005 Juan Cespedes <cespedes@debian.org>
.\"
.\" This program is free software; you can redistribute it and/or
@@ -17,13 +17,65 @@
.\" Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
.\" 02110-1301 USA
.\"
-.TH LTRACE "1" "October 2012" "" "User Commands"
+.TH LTRACE "1" "January 2013" "" "User Commands"
.SH NAME
ltrace \- A library call tracer
.SH SYNOPSIS
+.\"
+.\" ---------------------------------------------------------------------------
+.\"
+.PP
.B ltrace
-.I "[-bCfghiLrStttV] [-a column] [-A maxelts] [-D level] [-e expr] [-l library_pattern] [-n nr] [-o filename] [-p pid] ... [-s strsize] [-u username] [-w count] [-x extern] ... [--align=column] [--debug=level] [--demangle] [--help] [--indent=nr] [--library=library_pattern] [--no-signals] [--output=filename] [--version] [--where=NR] [command [arg ...]]"
+.\"
+.\" What events to trace:
+.\"
+[\-e \fIfilter\fR|\-L] [\-l|\-\-library=\fIlibrary_pattern\fR]
+[\-x \fIfilter\fR] [\-S] [\-b|\-\-no-signals]
+.\"
+.\" What to display with each event:
+.\"
+[\-i] [\-w|\-\-where=\fInr\fR] [\-r|\-t|\-tt|\-ttt] [\-T]
+.\"
+.\" Output formatting:
+.\"
+[\-F \fIfilename\fR]
+[\-A \fImaxelts\fR] [\-s \fIstrsize\fR] [\-C|\-\-demangle]
+[\-a|\-\-align \fIcolumn\fR] [\-n|\-\-indent \fInr\fR]
+[\-o|\-\-output \fIfilename\fR]
+.\"
+.\" Various:
+.\"
+[\-D|\-\-debug \fImask\fR] [\-u \fIusername\fR]
+.\"
+.\" What processes to trace:
+.\"
+[\-f] [\-p \fIpid\fR] [[\-\-] \fIcommand [arg ...]\fR]
+.\"
+.\" ---------------------------------------------------------------------------
+.\"
+.PP
+.BR ltrace " -c"
+.\"
+.\" What events to trace:
+.\"
+[\-e \fIfilter\fR|\-L] [\-l|\-\-library=\fIlibrary_pattern\fR]
+[\-x \fIfilter\fR] [\-S]
+.\"
+.\" Output formatting:
+.\"
+[\-o|\-\-output \fIfilename\fR]
+.\"
+.\" What processes to trace:
+.\"
+[\-f] [\-p \fIpid\fR] [[\-\-] \fIcommand [arg ...]\fR]
+.\"
+.\" ---------------------------------------------------------------------------
+.\"
+.PP
+.BR ltrace " \-V|\-\-version"
+.PP
+.BR ltrace " \-h|\-\-help"
.SH DESCRIPTION
.B ltrace
@@ -38,77 +90,51 @@ Its use is very similar to
.BR strace(1) .
.SH OPTIONS
-.TP
-.I \-a, \-\-align column
+.PP
+.IP "\-a, \-\-align \fIcolumn"
Align return values in a specific
.IR column
(default column is 5/8 of screen width).
-.TP
-.I \-A maxelts
+.IP "\-A \fImaxelts"
Maximum number of array elements to print before suppressing the rest
with an ellipsis ("..."). This also limits number of recursive
structure expansions.
-.TP
-.I \-b, \-\-no-signals
+.IP "\-b, \-\-no-signals"
Disable printing of signals recieved by the traced process.
-.TP
-.I \-c
-Count time and calls for each library call and report a summary on program exit.
-.TP
-.I \-C, \-\-demangle
+.IP \-c
+Count time and calls for each library call and report a summary on
+program exit.
+.IP "\-C, \-\-demangle"
Decode (demangle) low-level symbol names into user-level names.
Besides removing any initial underscore prefix used by the system,
this makes C++ function names readable.
-.TP
-.I \-D, \-\-debug level
-Show debugging output of
-.B ltrace
-itself.
-.I level
-must be a sum of some of the following numbers:
-.RS
-.TP
-.B 01
-DEBUG_GENERAL. Shows helpful progress information
-.TP
-.B 010
-DEBUG_EVENT. Shows every event received by a traced program
-.TP
-.B 020
-DEBUG_PROCESS. Shows every action
-.B ltrace
-carries upon a traced process
-.TP
-.B 040
-DEBUG_FUNCTION. Shows every entry to internal functions
-.RE
-.TP
-.I \-e filter
+.IP "\-D, \-\-debug \fRmask\fI"
+Show debugging output of \fBltrace\fR itself. \fImask\fR is a number
+with internal meaning that's not really well defined at all.
+\fImask\fR of 77 shows all debug messages, which is what you usually
+need.
+.IP "\-e \fIfilter"
A qualifying expression which modifies which library calls to trace.
The format of the filter expression is described in the section
\fBFILTER EXPRESSIONS\fR. 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, \fB@MAIN\fR is assumed as a default.
-.TP
-.I \-f
+.IP \-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.
-.TP
-.I \-F
+.IP "\-F \fIfilename"
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.
-.TP
-.I \-h, \-\-help
+~/.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. See ltrace.conf(5) for details on the syntax of ltrace
+configuration files.
+.IP "\-h, \-\-help"
Show a summary of the options to ltrace and exit.
-.TP
-.I \-i
+.IP \-i
Print the instruction pointer at the time of the library call.
-.TP
-.I \-l, \-\-library library_pattern
+.IP "\-l, \-\-library \fIlibrary_pattern"
Display only calls to functions implemented by libraries that match
.I library_pattern.
Multiple library patters can be specified with several instances of
@@ -120,71 +146,55 @@ the selected libraries, there's no actual guarantee that the call
won't be directed elsewhere due to e.g. LD_PRELOAD or simply
dependency ordering. If you want to make sure that symbols in given
library are actually called, use \fB-x @\fIlibrary_pattern\fR instead.
-.TP
-.I \-L
+.IP \-L
When no -e option is given, don't assume the default action of
\fB@MAIN\fR.
-.TP
-.I \-n, \-\-indent nr
-Indent trace output by
-.I nr
-number of spaces for each new nested call. Using this option makes
-the program flow visualization easy to follow.
-.TP
-.I \-o, \-\-output filename
-Write the trace output to the file
-.I filename
-rather than to stderr.
-.TP
-.I \-p pid
-Attach to the process with the process ID
-.I pid
-and begin tracing.
-.TP
-.I \-r
-Print a relative timestamp with each line of the trace.
-This records the time difference between the beginning of
-successive lines.
-.TP
-.I \-s strsize
+.IP "\-n, \-\-indent \fInr"
+Indent trace output by \fInr\fR spaces for each level of call
+nesting. Using this option makes the program flow visualization easy
+to follow. This indents uselessly also functions that never return,
+such as service functions for throwing exceptions in the C++ runtime.
+.IP "\-o, \-\-output \fIfilename"
+Write the trace output to the file \fIfilename\fR rather than to
+stderr.
+.IP "\-p \fIpid"
+Attach to the process with the process ID \fIpid\fR and begin tracing.
+This option can be used together with passing a command to execute.
+It is possible to attach to several processes by passing more than one
+option \-p.
+.IP \-r
+Print a relative timestamp with each line of the trace. This records
+the time difference between the beginning of successive lines.
+.IP "\-s \fIstrsize"
Specify the maximum string size to print (the default is 32).
-.TP
-.I \-S
+.IP \-S
Display system calls as well as library calls
-.TP
-.I \-t
+.IP \-t
Prefix each line of the trace with the time of day.
-.TP
-.I \-tt
+.IP \-tt
If given twice, the time printed will include the microseconds.
-.TP
-.I \-ttt
+.IP \-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.
-.TP
-.I \-T
+.IP \-T
Show the time spent inside each call. This records the time difference
between the beginning and the end of each call.
-.TP
-.I \-u username
+.IP "\-u \fIusername"
Run command with the userid, groupid and supplementary groups of
.IR username .
This option is only useful when running as root and enables the
correct execution of setuid and/or setgid binaries.
-.TP
-.I \-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.
-.TP
-.I \-x filter
+.IP "\-w, --where \fInr"
+Show backtrace of \fInr\fR stack frames for each traced function. This
+option enabled only if libunwind support was enabled at compile time.
+.IP "\-x \fIfilter"
A qualifying expression which modifies which symbol table entry points
to trace. The format of the filter expression is described in the
section \fBFILTER EXPRESSIONS\fR. 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.
-.TP
-.I \-V, \-\-version
+.IP "\-V, \-\-version"
Show the version number of ltrace and exit.
.SH FILTER EXPRESSIONS
@@ -235,7 +245,8 @@ path name.
The first rule may lack a sign, in which case \fB+\fR is assumed. If,
on the other hand, the first rule has a \fB-\fR sign, it is as if
-there was another rule \fB@*\fR in front of it.
+there was another rule \fB@\fR in front of it, which has the effect of
+tracing complement of given rule.
The above rules are used to construct the set of traced symbols. Each
candidate symbol is passed through the chain of above rules.
diff --git a/options.c b/options.c
index e8fd2a2..0aa893a 100644
--- a/options.c
+++ b/options.c
@@ -1,6 +1,6 @@
/*
* This file is part of ltrace.
- * Copyright (C) 2012 Petr Machata, Red Hat Inc.
+ * Copyright (C) 2012, 2013 Petr Machata, Red Hat Inc.
* Copyright (C) 2009,2010 Joe Damato
* Copyright (C) 1998,1999,2002,2003,2004,2007,2008,2009 Juan Cespedes
* Copyright (C) 2006 Ian Wienand
@@ -86,27 +86,27 @@ usage(void) {
fprintf(stdout, "Usage: %s [option ...] [command [arg ...]]\n"
"Trace library calls of a given program.\n\n"
" -a, --align=COLUMN align return values in a secific column.\n"
- " -A ARRAYLEN maximum number of array elements to print.\n"
+ " -A MAXELTS maximum number of array elements to print.\n"
" -b, --no-signals don't print signals.\n"
" -c count time and calls, and report a summary on exit.\n"
# ifdef USE_DEMANGLE
" -C, --demangle decode low-level symbol names into user-level names.\n"
# endif
- " -D, --debug=LEVEL enable debugging (see -Dh or --debug=help).\n"
+ " -D, --debug=MASK enable debugging (see -Dh or --debug=help).\n"
" -Dh, --debug=help show help on debugging.\n"
- " -e expr modify which events to trace.\n"
+ " -e FILTER modify which library calls to trace.\n"
" -f trace children (fork() and clone()).\n"
" -F, --config=FILE load alternate configuration file (may be repeated).\n"
" -h, --help display this help and exit.\n"
" -i print instruction pointer at time of library call.\n"
- " -l, --library=FILE only trace symbols implemented by this library.\n"
+ " -l, --library=LIBRARY_PATTERN only trace symbols implemented by this library.\n"
" -L do NOT display library calls.\n"
" -n, --indent=NR indent output by NR spaces for each call level nesting.\n"
- " -o, --output=FILE write the trace output to that file.\n"
+ " -o, --output=FILENAME write the trace output to file with given name.\n"
" -p PID attach to the process with the process ID pid.\n"
" -r print relative timestamps.\n"
- " -s STRLEN specify the maximum string size to print.\n"
- " -S display system calls.\n"
+ " -s STRSIZE specify the maximum string size to print.\n"
+ " -S trace system calls as well as library calls.\n"
" -t, -tt, -ttt print absolute timestamps.\n"
" -T show the time spent inside each call.\n"
" -u USERNAME run command with the userid, groupid of username.\n"
@@ -114,7 +114,7 @@ usage(void) {
#if defined(HAVE_LIBUNWIND)
" -w, --where=NR print backtrace showing NR stack frames at most.\n"
#endif /* defined(HAVE_LIBUNWIND) */
- " -x NAME treat the global NAME like a library subroutine.\n"
+ " -x FILTER modify which static functions to trace.\n"
"\nReport bugs to ltrace-devel@lists.alioth.debian.org\n",
progname);
}
--
1.7.6.5

11
ltrace.spec
View File

@ -1,7 +1,7 @@
Summary: Tracks runtime library calls from dynamically linked executables
Name: ltrace
Version: 0.7.2
Release: 1%{?dist}
Release: 2%{?dist}
URL: http://ltrace.alioth.debian.org/
License: GPLv2+
Group: Development/Debuggers
@ -14,6 +14,9 @@ BuildRequires: libselinux-devel
# https://alioth.debian.org/frs/?group_id=30892
Source: http://alioth.debian.org/frs/download.php/3848/ltrace-0.7.2.tar.bz2
# Upstream patch for fixes in man page and --help.
Patch0: ltrace-0.7.2-man.patch
%description
Ltrace is a debugging program which runs a specified command until the
command exits. While the command is executing, ltrace intercepts and
@ -26,6 +29,7 @@ execution of processes.
%prep
%setup -q
%patch0 -p1
%build
%configure
@ -50,6 +54,11 @@ echo ====================TESTING END=====================
%config(noreplace) %{_sysconfdir}/ltrace.conf
%changelog
* Fri Jan 11 2013 Petr Machata <pmachata@redhat.com> - 0.7.2-2
- Improve documentation: better correlation between ltrace(1) and
--help, other minor improvements in ltrace(1).
(ltrace-0.7.2-man.patch)
* Mon Dec 10 2012 Petr Machata <pmachata@redhat.com> - 0.7.2-1
- Upstream 0.7.2
- Drop all the patches