From 43550d379ea53556183002632da0d23c0c417d03 Mon Sep 17 00:00:00 2001 From: Jon Bernard Date: Thu, 25 Mar 2010 15:20:57 -0400 Subject: [PATCH] Add manpages for ustd, ustctl, and usttrace --- 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 , 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` [] []... + +## 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` /: + Set the size of subbuffers per channel. + + * `--set-subbuf-num` : + Set the number of subbuffers per channel. + + * `--get-subbuf-size` : + Get the size of subbuffers per channel. + + * `--get-subbuf-num` : + Get the number of subbuffers per channel. + + * `--enable-marker` /: + Enable a marker. + + * `--disable-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@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 , 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` [] + +## 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` : + Specify the directory where to output the traces. + + * `-s` : + Specify the path to use for the daemon socket. + + * `-d`: + Start as a daemon. + + * `-p`, `--pidfile`=: + 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@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 , 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` [] [] + +## 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@debian.org>, for +the Debian project (and may be used by others). -- 2.34.1