[ltt-dev] [PATCH] Add manpages for ustd, ustctl, and usttrace
Jon Bernard
jbernard at debian.org
Thu Mar 25 15:20:57 EDT 2010
---
Makefile.am | 4 +-
configure.ac | 1 +
doc/Makefile.am | 2 +
doc/man/ustctl.1 | 77 +++++++++++++++++++++++++++++++++++++++++++
doc/man/ustctl.1.md | 62 +++++++++++++++++++++++++++++++++++
doc/man/ustd.1 | 48 +++++++++++++++++++++++++++
doc/man/ustd.1.md | 40 +++++++++++++++++++++++
doc/man/usttrace.1 | 86 +++++++++++++++++++++++++++++++++++++++++++++++++
doc/man/usttrace.1.md | 64 ++++++++++++++++++++++++++++++++++++
9 files changed, 382 insertions(+), 2 deletions(-)
create mode 100644 doc/Makefile.am
create mode 100644 doc/man/ustctl.1
create mode 100644 doc/man/ustctl.1.md
create mode 100644 doc/man/ustd.1
create mode 100644 doc/man/ustd.1.md
create mode 100644 doc/man/usttrace.1
create mode 100644 doc/man/usttrace.1.md
diff --git a/Makefile.am b/Makefile.am
index 112e8eb..05ea397 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -5,9 +5,9 @@ ACLOCAL_AMFLAGS = -I m4
# libust and '.' (that contains the linker script). However, '.'
# must be installed after libust so it can overwrite libust.so with
# the linker script.
-SUBDIRS = snprintf libustcomm libust . tests libustinstr-malloc ustd ustctl libustfork include
+SUBDIRS = snprintf libustcomm libust . tests libustinstr-malloc ustd ustctl libustfork include doc
-EXTRA_DIST = doc libust.ldscript.in libust-initializer.c
+EXTRA_DIST = libust.ldscript.in libust-initializer.c
dist_bin_SCRIPTS = usttrace
ldscriptsdir = $(libdir)
diff --git a/configure.ac b/configure.ac
index a354f83..689f891 100644
--- a/configure.ac
+++ b/configure.ac
@@ -105,6 +105,7 @@ AC_MSG_RESULT($LIBFORMAT)
AC_CONFIG_FILES([
Makefile
+ doc/Makefile
include/Makefile
libust/Makefile
tests/Makefile
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..c266f7d
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,2 @@
+EXTRA_DIST = manual
+man_MANS = man/ustctl.1 man/ustd.1 man/usttrace.1
diff --git a/doc/man/ustctl.1 b/doc/man/ustctl.1
new file mode 100644
index 0000000..bb942ae
--- /dev/null
+++ b/doc/man/ustctl.1
@@ -0,0 +1,77 @@
+.\" generated with Ronn/v0.4.1
+.\" http://github.com/rtomayko/ronn/
+.
+.TH "USTCTL" "1" "March 2010" "" ""
+.
+.SH "NAME"
+\fBustctl\fR \-\- a program to control the tracing of userspace applications
+.
+.SH "SYNOPSIS"
+\fBustctl\fR [\fIcommand\fR] [\fIPIDs\fR]...
+.
+.SH "DESCRIPTION"
+\fBustclt\fR is a program to control the tracing of userspace applications. It can
+list markers, start the tracing, stop the tracing, enable/disable markers, etc.
+.
+.SH "OPTIONS"
+These programs follow the usual GNU command line syntax, with long options
+starting with two dashes(`\-'). A summary of options is included below.
+.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Show summary of options.
+.
+.TP
+\fB\-\-create\-trace\fR
+Create trace.
+.
+.TP
+\fB\-\-alloc\-trace\fR
+Alloc trace.
+.
+.TP
+\fB\-\-start\-trace\fR
+Start tracing.
+.
+.TP
+\fB\-\-stop\-trace\fR
+Stop tracing.
+.
+.TP
+\fB\-\-destroy\-trace\fR
+Destroy the trace.
+.
+.TP
+\fB\-\-set\-subbuf\-size\fR \fICHANNEL\fR/\fIbytes\fR
+Set the size of subbuffers per channel.
+.
+.TP
+\fB\-\-set\-subbuf\-num\fR \fICHANNEL\fR
+Set the number of subbuffers per channel.
+.
+.TP
+\fB\-\-get\-subbuf\-size\fR \fICHANNEL\fR
+Get the size of subbuffers per channel.
+.
+.TP
+\fB\-\-get\-subbuf\-num\fR \fICHANNEL\fR
+Get the number of subbuffers per channel.
+.
+.TP
+\fB\-\-enable\-marker\fR \fICHANNEL\fR/\fIMARKER\fR
+Enable a marker.
+.
+.TP
+\fB\-\-disable\-marker\fR \fICHANNEL\fR/\fIMARKER\fR
+Disable a marker.
+.
+.TP
+\fB\-\-list\-markers\fR
+List the markers of the process, their state and format string.
+.
+.SH "AUTHOR"
+\fBustctl\fR was written by Pierre\-Marc Fournier.
+.
+.P
+This manual page was written by Jon Bernard <jbernard at debian.org>, for
+the Debian project (and may be used by others).
diff --git a/doc/man/ustctl.1.md b/doc/man/ustctl.1.md
new file mode 100644
index 0000000..12437c5
--- /dev/null
+++ b/doc/man/ustctl.1.md
@@ -0,0 +1,62 @@
+ustctl(1) -- a program to control the tracing of userspace applications
+=======================================================================
+
+## SYNOPSIS
+
+`ustctl` [<command>] [<PIDs>]...
+
+## DESCRIPTION
+
+`ustclt` is a program to control the tracing of userspace applications. It can
+list markers, start the tracing, stop the tracing, enable/disable markers, etc.
+
+## OPTIONS
+
+These programs follow the usual GNU command line syntax, with long options
+starting with two dashes(`-'). A summary of options is included below.
+
+ * `-h`, `--help`:
+ Show summary of options.
+
+ * `--create-trace`:
+ Create trace.
+
+ * `--alloc-trace`:
+ Alloc trace.
+
+ * `--start-trace`:
+ Start tracing.
+
+ * `--stop-trace`:
+ Stop tracing.
+
+ * `--destroy-trace`:
+ Destroy the trace.
+
+ * `--set-subbuf-size` <CHANNEL>/<bytes>:
+ Set the size of subbuffers per channel.
+
+ * `--set-subbuf-num` <CHANNEL>:
+ Set the number of subbuffers per channel.
+
+ * `--get-subbuf-size` <CHANNEL>:
+ Get the size of subbuffers per channel.
+
+ * `--get-subbuf-num` <CHANNEL>:
+ Get the number of subbuffers per channel.
+
+ * `--enable-marker` <CHANNEL>/<MARKER>:
+ Enable a marker.
+
+ * `--disable-marker` <CHANNEL>/<MARKER>:
+ Disable a marker.
+
+ * `--list-markers`:
+ List the markers of the process, their state and format string.
+
+## AUTHOR
+
+`ustctl` was written by Pierre-Marc Fournier.
+
+This manual page was written by Jon Bernard <jbernard at debian.org>, for
+the Debian project (and may be used by others).
diff --git a/doc/man/ustd.1 b/doc/man/ustd.1
new file mode 100644
index 0000000..bb7b982
--- /dev/null
+++ b/doc/man/ustd.1
@@ -0,0 +1,48 @@
+.\" generated with Ronn/v0.4.1
+.\" http://github.com/rtomayko/ronn/
+.
+.TH "USTD" "1" "March 2010" "" ""
+.
+.SH "NAME"
+\fBustd\fR \-\- a daemon that collects trace data and writes it to the disk
+.
+.SH "SYNOPSIS"
+\fBustd\fR [\fIoptions\fR]
+.
+.SH "DESCRIPTION"
+\fBustd\fR is a program that collects trace data and writes it to the disk.
+.
+.SH "OPTIONS"
+These programs follow the usual GNU command line syntax, with long options
+starting with two dashes(`\-'). A summary of options is included below.
+.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Show summary of options.
+.
+.TP
+\fB\-o\fR \fIDIR\fR
+Specify the directory where to output the traces.
+.
+.TP
+\fB\-s\fR \fIPATH\fR
+Specify the path to use for the daemon socket.
+.
+.TP
+\fB\-d\fR
+Start as a daemon.
+.
+.TP
+\fB\-p\fR, \fB\-\-pidfile\fR=\fIFILE\fR
+Write the PID in this file (when using \-d).
+.
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Show version of program.
+.
+.SH "AUTHOR"
+\fBustd\fR was written by Pierre\-Marc Fournier.
+.
+.P
+This manual page was written by Jon Bernard <jbernard at debian.org>, for
+the Debian project (and may be used by others).
diff --git a/doc/man/ustd.1.md b/doc/man/ustd.1.md
new file mode 100644
index 0000000..836589e
--- /dev/null
+++ b/doc/man/ustd.1.md
@@ -0,0 +1,40 @@
+ustd(1) -- a daemon that collects trace data and writes it to the disk
+======================================================================
+
+## SYNOPSIS
+
+`ustd` [<options>]
+
+## DESCRIPTION
+
+`ustd` is a program that collects trace data and writes it to the disk.
+
+## OPTIONS
+
+These programs follow the usual GNU command line syntax, with long options
+starting with two dashes(`-'). A summary of options is included below.
+
+ * `-h`, `--help`:
+ Show summary of options.
+
+ * `-o` <DIR>:
+ Specify the directory where to output the traces.
+
+ * `-s` <PATH>:
+ Specify the path to use for the daemon socket.
+
+ * `-d`:
+ Start as a daemon.
+
+ * `-p`, `--pidfile`=<FILE>:
+ Write the PID in this file (when using -d).
+
+ * `-V`, `--version`:
+ Show version of program.
+
+## AUTHOR
+
+`ustd` was written by Pierre-Marc Fournier.
+
+This manual page was written by Jon Bernard <jbernard at debian.org>, for
+the Debian project (and may be used by others).
diff --git a/doc/man/usttrace.1 b/doc/man/usttrace.1
new file mode 100644
index 0000000..8496cda
--- /dev/null
+++ b/doc/man/usttrace.1
@@ -0,0 +1,86 @@
+.\" generated with Ronn/v0.4.1
+.\" http://github.com/rtomayko/ronn/
+.
+.TH "USTTRACE" "1" "March 2010" "" ""
+.
+.SH "NAME"
+\fBusttrace\fR \-\- the simplest way to record a trace
+.
+.SH "SYNOPSIS"
+\fBusttrace\fR [\fIoptions\fR] [\fIcommand\fR]
+.
+.SH "DESCRIPTION"
+The \fBusttrace\fR script automatically:
+.
+.IP "\(bu" 4
+creates a daemon
+.
+.IP "\(bu" 4
+enables all markers
+.
+.IP "\(bu" 4
+runs the command specified on the command line
+.
+.IP "\(bu" 4
+after the command ends, prints the location where the trace was saved
+.
+.IP "" 0
+.
+.P
+Each subdirectory of the save location contains the trace of one process that
+was generated by the command. The name of a subdirectory consists in the PID of
+the process, followed by the timestamp of its creation.
+.
+.P
+The save location also contains logs of the tracing.
+.
+.P
+When using usttrace, the early tracing is always active, which means that the
+tracing is guaranteed to be started by the time the process enters its main()
+function.
+.
+.P
+Several usttrace's may be run simultaneously without risk of conflict. This
+facilitates the use of the tracer by independent users on a system. Each
+instance of usttrace starts its own daemon which collects the events of the
+processes it creates.
+.
+.SH "OPTIONS"
+These programs follow the usual GNU command line syntax, with long options
+starting with two dashes(`\-'). A summary of options is included below.
+.
+.TP
+\fB\-h\fR
+Show summary of options.
+.
+.TP
+\fB\-l\fR
+Runtime link with UST library. (Needed only if program was not linked at
+compile time with libust.)
+.
+.TP
+\fB\-L\fR
+Add path to ust libraries to LD_LIBRARY_PATH.
+.
+.TP
+\fB\-m\fR
+Instrument malloc calls.
+.
+.TP
+\fB\-f\fR
+Also trace forked processes.
+.
+.TP
+\fB\-s\fR
+Use system\-wide daemon instead of creating one for this session.
+.
+.TP
+\fB\-W\fR
+Undocumented option.
+.
+.SH "AUTHOR"
+\fBusttrace\fR was written by Pierre\-Marc Fournier.
+.
+.P
+This manual page was written by Jon Bernard <jbernard at debian.org>, for
+the Debian project (and may be used by others).
diff --git a/doc/man/usttrace.1.md b/doc/man/usttrace.1.md
new file mode 100644
index 0000000..c2b033e
--- /dev/null
+++ b/doc/man/usttrace.1.md
@@ -0,0 +1,64 @@
+usttrace(1) -- the simplest way to record a trace
+=================================================
+
+## SYNOPSIS
+
+`usttrace` [<options>] [<command>]
+
+## DESCRIPTION
+
+The `usttrace` script automatically:
+
+* creates a daemon
+* enables all markers
+* runs the command specified on the command line
+* after the command ends, prints the location where the trace was saved
+
+Each subdirectory of the save location contains the trace of one process that
+was generated by the command. The name of a subdirectory consists in the PID of
+the process, followed by the timestamp of its creation.
+
+The save location also contains logs of the tracing.
+
+When using usttrace, the early tracing is always active, which means that the
+tracing is guaranteed to be started by the time the process enters its main()
+function.
+
+Several usttrace's may be run simultaneously without risk of conflict. This
+facilitates the use of the tracer by independent users on a system. Each
+instance of usttrace starts its own daemon which collects the events of the
+processes it creates.
+
+## OPTIONS
+
+These programs follow the usual GNU command line syntax, with long options
+starting with two dashes(`-'). A summary of options is included below.
+
+ * `-h`:
+ Show summary of options.
+
+ * `-l`:
+ Runtime link with UST library. (Needed only if program was not linked at
+ compile time with libust.)
+
+ * `-L`:
+ Add path to ust libraries to LD_LIBRARY_PATH.
+
+ * `-m`:
+ Instrument malloc calls.
+
+ * `-f`:
+ Also trace forked processes.
+
+ * `-s`:
+ Use system-wide daemon instead of creating one for this session.
+
+ * `-W`:
+ Undocumented option.
+
+## AUTHOR
+
+`usttrace` was written by Pierre-Marc Fournier.
+
+This manual page was written by Jon Bernard <jbernard at debian.org>, for
+the Debian project (and may be used by others).
--
1.7.0.3
--
Jon
More information about the lttng-dev
mailing list