Update documentation for new ustctl cli
authorNils Carlson <nils.carlson@ericsson.com>
Thu, 20 Jan 2011 11:15:54 +0000 (12:15 +0100)
committerNils Carlson <nils.carlson@ericsson.com>
Thu, 27 Jan 2011 15:54:49 +0000 (16:54 +0100)
Signed-off-by: Nils Carlson <nils.carlson@ericsson.com>
doc/info/ust.texi
doc/man/ustctl.1
doc/man/ustctl.1.md

index efad0f6b92111664a390dda92adb954c8cf35a03..73a8bcd3faf65eef72457db1a9120b4498ccc0a3 100644 (file)
@@ -395,25 +395,25 @@ $ ust-consumerd
 # it has pid 1234.
 
 # List the available markers
 # it has pid 1234.
 
 # List the available markers
-$ ustctl --list-markers 1234
+$ ustctl list-markers 1234
 # A column indicates 0 for an inactive marker and 1 for an active marker.
 
 # Enable a marker
 # A column indicates 0 for an inactive marker and 1 for an active marker.
 
 # Enable a marker
-$ ustctl --enable-marker ust/mymark 1234
+$ ustctl enable-marker 1234 auto ust/mymark
 
 # Create a trace
 
 # Create a trace
-$ ustctl --create-trace 1234
+$ ustctl create-trace 1234 auto
 
 # Start tracing
 
 # Start tracing
-$ ustctl --start-trace 1234
+$ ustctl start-trace 1234 auto
 
 # Do things...
 
 # Stop tracing
 
 # Do things...
 
 # Stop tracing
-$ ustctl --stop-trace 1234
+$ ustctl stop-trace 1234 auto
 
 # Destroy the trace
 
 # Destroy the trace
-$ ustctl --destroy-trace 1234
+$ ustctl destroy-trace 1234 auto
 @end verbatim
 @end example
 
 @end verbatim
 @end example
 
index b0f97d9a774e5898a91b2b30f053061867d9606d..2250b316a78500af31ec7c89cfd0887433a44b7c 100644 (file)
-.\" generated with Ronn/v0.5
-.\" http://github.com/rtomayko/ronn/
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
 .
-.TH "USTCTL" "1" "August 2010" "" ""
+.TH "USTCTL" "1" "January 2011" "" ""
 .
 .SH "NAME"
 .
 .SH "NAME"
-\fBustctl\fR \-\- a program to control the tracing of userspace applications
+\fBustctl\fR \- a program to control the tracing of userspace applications
 .
 .SH "SYNOPSIS"
 .
 .SH "SYNOPSIS"
-\fBustctl\fR [\fIcommand\fR] [\fIPIDs\fR]...
+\fBustctl\fR [\fICOMMAND\fR] [\fIARGS\fR]\.\.\.
 .
 .SH "DESCRIPTION"
 .
 .SH "DESCRIPTION"
-\fBustctl\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.
+\fBustctl\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"
 .
 .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.
+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
 .
 .TP
 \fB\-h\fR, \fB\-\-help\fR
-Show summary of options.
+Show summary of commands\.
+.
+.SH "COMMANDS"
+\fBustctl\fR accepts commands followed by arguments for each respective command\. Most commands require the pid of the application being traced\.
 .
 .TP
 .
 .TP
-\fB\-\-create\-trace\fR
-Create trace.
+\fBcreate\-trace\fR \fIPID\fR \fITRACE\fR
+Create trace\.
 .
 .TP
 .
 .TP
-\fB\-\-alloc\-trace\fR
-Allocate trace.
+\fBalloc\-trace\fR \fIPID\fR \fITRACE\fR
+Allocate trace\.
 .
 .TP
 .
 .TP
-\fB\-\-start\-trace\fR
-Start tracing.
+\fBstart\-trace\fR \fIPID\fR \fITRACE\fR
+Start tracing\.
 .
 .TP
 .
 .TP
-\fB\-\-stop\-trace\fR
-Stop tracing.
+\fBstop\-trace\fR \fIPID\fR \fITRACE\fR
+Stop tracing\.
 .
 .TP
 .
 .TP
-\fB\-\-destroy\-trace\fR
-Destroy the trace.
+\fBdestroy\-trace\fR \fIPID\fR \fITRACE\fR
+Destroy the trace\.
 .
 .TP
 .
 .TP
-\fB\-\-set\-subbuf\-size\fR \fICHANNEL\fR/\fIbytes\fR
-Set the size of subbuffers in CHANNEL.
+\fBset\-subbuf\-size\fR \fIPID\fR \fITRACE\fR \fICHANNEL\fR/\fIbytes\fR
+Set the size of subbuffers in CHANNEL\.
 .
 .TP
 .
 .TP
-\fB\-\-set\-subbuf\-num\fR \fICHANNEL\fR
-Set the number of subbuffers per buffer for CHANNEL. Must be a power of 2.
+\fBset\-subbuf\-num\fR \fIPID\fR \fITRACE\fR \fICHANNEL\fR/\fInr\fR
+Set the number of subbuffers per buffer for CHANNEL\. Must be a power of 2\.
 .
 .TP
 .
 .TP
-\fB\-\-set\-sock\-path\fR
-Set the path of the daemon socket.
+\fBset\-sock\-path\fR \fIPID\fR \fISOCKPATH\fR
+Set the path of the daemon socket\.
 .
 .TP
 .
 .TP
-\fB\-\-get\-subbuf\-size\fR \fICHANNEL\fR
-Print the size of subbuffers per buffer for CHANNEL.
+\fBget\-subbuf\-size\fR \fIPID\fR \fITRACE\fR \fICHANNEL\fR
+Print the size of subbuffers per buffer for CHANNEL\.
 .
 .TP
 .
 .TP
-\fB\-\-get\-subbuf\-num\fR \fICHANNEL\fR
-Print the number of subbuffers per buffer for CHANNEL.
+\fBget\-subbuf\-num\fR \fIPID\fR \fITRACE\fR \fICHANNEL\fR
+Print the number of subbuffers per buffer for CHANNEL\.
 .
 .TP
 .
 .TP
-\fB\-\-get\-sock\-path\fR
-Get the path of the daemon socket.
+\fBget\-sock\-path\fR \fIPID\fR
+Get the path of the daemon socket\.
 .
 .TP
 .
 .TP
-\fB\-\-enable\-marker\fR \fICHANNEL\fR/\fIMARKER\fR
-Enable a marker.
+\fBenable\-marker\fR \fIPID\fR \fITRACE\fR \fICHANNEL\fR/\fIMARKER\fR
+Enable a marker\.
 .
 .TP
 .
 .TP
-\fB\-\-disable\-marker\fR \fICHANNEL\fR/\fIMARKER\fR
-Disable a marker.
+\fBdisable\-marker\fR \fIPID\fR \fITRACE\fR \fICHANNEL\fR/\fIMARKER\fR
+Disable a marker\.
 .
 .TP
 .
 .TP
-\fB\-\-list\-markers\fR
-List the markers of the process, their state and format string.
+\fBlist\-markers\fR \fIPID\fR
+List the markers of the process, their state and format string\.
 .
 .TP
 .
 .TP
-\fB\-\-force\-switch\fR
-Force a subbuffer switch. This will flush all the data currently held.
+\fBforce\-subbuf\-switch\fR \fIPID\fR \fITRACE\fR
+Force a subbuffer switch\. This will flush all the data currently held\.
 .
 .SH "LIFE CYCLE OF A TRACE"
 .
 .SH "LIFE CYCLE OF A TRACE"
-Typically, the first step is to enable markers with \fB\-\-enable\-marker\fR. An
-enabled marker generates an event when the control flow passes over it
-(assuming the trace is recording). A disabled marker produces nothing. Enabling
-and disabling markers may however be done at any point, including while the
-trace is being recorded.
+Typically, the first step is to enable markers with \fBenable\-marker\fR\. An enabled marker generates an event when the control flow passes over it (assuming the trace is recording)\. A disabled marker produces nothing\. Enabling and disabling markers may however be done at any point, including while the trace is being recorded\.
 .
 .P
 .
 .P
-In order to record events, a trace is first created with \fB\-\-create\-trace\fR. At
-this point, the subbuffer count and size may be changed with \fB\-\-set\-subbuf\-num\fR
-and \fB\-\-set\-subbuf\-size\fR.
+In order to record events, a trace is first created with \fBcreate\-trace\fR\. At this point, the subbuffer count and size may be changed with \fBset\-subbuf\-num\fR and \fBset\-subbuf\-size\fR\.
 .
 .P
 .
 .P
-Afterward, the trace may be allocated with \fB\-\-alloc\-trace\fR. This allocates the
-buffers in memory, so once this is done, the subbuffer size and count can not
-be changed. Trace allocation also causes the daemon to connect to the trace
-buffers and wait for data to arrive. Explicit allocation is optional, as it is
-done automatically at trace start.
+Afterward, the trace may be allocated with \fBalloc\-trace\fR\. This allocates the buffers in memory, so once this is done, the subbuffer size and count can not be changed\. Trace allocation also causes the daemon to connect to the trace buffers and wait for data to arrive\. Explicit allocation is optional, as it is done automatically at trace start\.
 .
 .P
 .
 .P
-The trace may then be started with \fB\-\-start\-trace\fR. This results in events
-being recorded in the buffer. The daemon automatically collects these events.
+The trace may then be started with \fBstart\-trace\fR\. This results in events being recorded in the buffer\. The daemon automatically collects these events\.
 .
 .P
 .
 .P
-The trace may be stopped with \fB\-\-stop\-trace\fR, either definitely after all the
-wanted information is collected, or temporarily, before being started again
-with \fB\-\-start\-trace\fR. This results in effectively 'pausing' the recording.
-After using \fB\-\-stop\-trace\fR, if a daemon is collecting the trace, it may not
-have flushed to the disk the full contents of the buffer yet.
+The trace may be stopped with \fBstop\-trace\fR, either definitely after all the wanted information is collected, or temporarily, before being started again with \fBstart\-trace\fR\. This results in effectively \'pausing\' the recording\. After using \fBstop\-trace\fR, if a daemon is collecting the trace, it may not have flushed to the disk the full contents of the buffer yet\.
 .
 .P
 .
 .P
-Finally, when \fB\-\-destroy\-trace\fR is used, the trace buffers are unallocated.
-However, the memory may not be effectively freed until the daemon finishes to
-collect them. When the trace is being collected by \fBust-consumerd\fR, this command
-guarantees its full contents is flushed to the disk.
+Finally, when \fBdestroy\-trace\fR is used, the trace buffers are unallocated\. However, the memory may not be effectively freed until the daemon finishes to collect them\. When the trace is being collected by \fBust\-consumerd\fR, this command guarantees its full contents is flushed to the disk\.
 .
 .SH "STRUCTURE OF A TRACE"
 .
 .SH "STRUCTURE OF A TRACE"
-Each instrumentation point that is added in a program is associated to a
-channel.
+Each instrumentation point that is added in a program is associated to a channel\.
 .
 .P
 .
 .P
-Trace events are put in buffers. There is one buffer per channel, per cpu.
-For example, on a system with 4 cores and tracing an application with 3
-channels, there will be 12 buffers in total. The content of each of these
-buffers is put in a distinct file in the trace directory. For example, the \fBmetadata_2\fR file contains the data that was extracted from the buffer that
-contained the events from the metadata channel and having occurred on cpu 2.
+Trace events are put in buffers\. There is one buffer per channel, per cpu\. For example, on a system with 4 cores and tracing an application with 3 channels, there will be 12 buffers in total\. The content of each of these buffers is put in a distinct file in the trace directory\. For example, the \fBmetadata_2\fR file contains the data that was extracted from the buffer that contained the events from the metadata channel and having occurred on cpu 2\.
 .
 .P
 .
 .P
-In memory, each buffer is divided in subbuffers. Subbuffers are equally\-sized,
-contiguous parts of a buffer. The size of a buffer is equal to the number of
-subbuffers it contains times the size of each subbuffer. When a subbuffer is
-full, it is collected by the daemon while the others are filled. If, however,
-the buffer size is too small, buffer overflows may occur and result in event
-loss. By default, the number of subbuffers per buffer is 2. Subbuffer size
-for a given channel may be chosen with \fB\-\-set\-subbuf\-size\fR while the subbuffer
-count is set with \fB\-\-set\-subbuf\-num\fR.
+In memory, each buffer is divided in subbuffers\. Subbuffers are equally\-sized, contiguous parts of a buffer\. The size of a buffer is equal to the number of subbuffers it contains times the size of each subbuffer\. When a subbuffer is full, it is collected by the daemon while the others are filled\. If, however, the buffer size is too small, buffer overflows may occur and result in event loss\. By default, the number of subbuffers per buffer is 2\. Subbuffer size for a given channel may be chosen with \fBset\-subbuf\-size\fR while the subbuffer count is set with \fBset\-subbuf\-num\fR\.
 .
 .SH "SEE ALSO"
 .
 .SH "SEE ALSO"
-usttrace(1), ust-consumerd(1)
+usttrace(1), ust\-consumerd(1)
 .
 .SH "AUTHOR"
 .
 .SH "AUTHOR"
-\fBustctl\fR was written by Pierre\-Marc Fournier.
+\fBustctl\fR was written by Pierre\-Marc Fournier\.
 .
 .P
 .
 .P
-This manual page was written by Jon Bernard <jbernard@debian.org>, for
-the Debian project (and may be used by others). It was updated 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)\. It was updated by Pierre\-Marc Fournier\.
index c8ad1f1722fc907bb03a31e0f88a2cfb59b44b55..89a952ac33a9e5f6b58824053183bb485d5636cc 100644 (file)
@@ -3,7 +3,7 @@ ustctl(1) -- a program to control the tracing of userspace applications
 
 ## SYNOPSIS
 
 
 ## SYNOPSIS
 
-`ustctl` [<command>] [<PIDs>]...
+`ustctl` [<COMMAND>] [<ARGS>]...
 
 ## DESCRIPTION
 
 
 ## DESCRIPTION
 
@@ -16,81 +16,86 @@ 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`:
 starting with two dashes(`-'). A summary of options is included below.
 
   * `-h`, `--help`:
-    Show summary of options.
+    Show summary of commands.
 
 
-  * `--create-trace`:
+## COMMANDS
+
+`ustctl` accepts commands followed by arguments for each respective command.
+Most commands require the pid of the application being traced.
+
+  * `create-trace` <PID> <TRACE>:
     Create trace.
 
     Create trace.
 
-  * `--alloc-trace`:
+  * `alloc-trace` <PID> <TRACE>:
     Allocate trace.
 
     Allocate trace.
 
-  * `--start-trace`:
+  * `start-trace` <PID> <TRACE>:
     Start tracing.
 
     Start tracing.
 
-  * `--stop-trace`:
+  * `stop-trace` <PID> <TRACE>:
     Stop tracing.
 
     Stop tracing.
 
-  * `--destroy-trace`:
+  * `destroy-trace` <PID> <TRACE>:
     Destroy the trace.
 
     Destroy the trace.
 
-  * `--set-subbuf-size` <CHANNEL>/<bytes>:
+  * `set-subbuf-size`  <PID> <TRACE> <CHANNEL>/<bytes>:
     Set the size of subbuffers in CHANNEL.
 
     Set the size of subbuffers in CHANNEL.
 
-  * `--set-subbuf-num` <CHANNEL>:
+  * `set-subbuf-num`  <PID> <TRACE> <CHANNEL>/<nr>:
     Set the number of subbuffers per buffer for CHANNEL. Must be a power of 2.
 
     Set the number of subbuffers per buffer for CHANNEL. Must be a power of 2.
 
-  * `--set-sock-path`:
+  * `set-sock-path` <PID> <SOCKPATH>:
     Set the path of the daemon socket.
 
     Set the path of the daemon socket.
 
-  * `--get-subbuf-size` <CHANNEL>:
+  * `get-subbuf-size` <PID> <TRACE> <CHANNEL>:
     Print the size of subbuffers per buffer for CHANNEL.
 
     Print the size of subbuffers per buffer for CHANNEL.
 
-  * `--get-subbuf-num` <CHANNEL>:
+  * `get-subbuf-num` <PID> <TRACE> <CHANNEL>:
     Print the number of subbuffers per buffer for CHANNEL.
 
     Print the number of subbuffers per buffer for CHANNEL.
 
-  * `--get-sock-path`:
+  * `get-sock-path` <PID>:
     Get the path of the daemon socket.
 
     Get the path of the daemon socket.
 
-  * `--enable-marker` <CHANNEL>/<MARKER>:
+  * `enable-marker` <PID> <TRACE> <CHANNEL>/<MARKER>:
     Enable a marker.
 
     Enable a marker.
 
-  * `--disable-marker` <CHANNEL>/<MARKER>:
+  * `disable-marker` <PID> <TRACE> <CHANNEL>/<MARKER>:
     Disable a marker.
 
     Disable a marker.
 
-  * `--list-markers`:
+  * `list-markers` <PID>:
     List the markers of the process, their state and format string.
 
     List the markers of the process, their state and format string.
 
-  * `--force-switch`:
+  * `force-subbuf-switch` <PID> <TRACE>:
     Force a subbuffer switch. This will flush all the data currently held.
 
 ## LIFE CYCLE OF A TRACE
 
     Force a subbuffer switch. This will flush all the data currently held.
 
 ## LIFE CYCLE OF A TRACE
 
-Typically, the first step is to enable markers with `--enable-marker`. An
+Typically, the first step is to enable markers with `enable-marker`. An
 enabled marker generates an event when the control flow passes over it
 (assuming the trace is recording). A disabled marker produces nothing. Enabling
 and disabling markers may however be done at any point, including while the
 trace is being recorded.
 
 enabled marker generates an event when the control flow passes over it
 (assuming the trace is recording). A disabled marker produces nothing. Enabling
 and disabling markers may however be done at any point, including while the
 trace is being recorded.
 
-In order to record events, a trace is first created with `--create-trace`. At
-this point, the subbuffer count and size may be changed with `--set-subbuf-num`
-and `--set-subbuf-size`.
+In order to record events, a trace is first created with `create-trace`. At
+this point, the subbuffer count and size may be changed with `set-subbuf-num`
+and `set-subbuf-size`.
 
 
-Afterward, the trace may be allocated with `--alloc-trace`. This allocates the
+Afterward, the trace may be allocated with `alloc-trace`. This allocates the
 buffers in memory, so once this is done, the subbuffer size and count can not
 be changed. Trace allocation also causes the daemon to connect to the trace
 buffers and wait for data to arrive. Explicit allocation is optional, as it is
 done automatically at trace start.
 
 buffers in memory, so once this is done, the subbuffer size and count can not
 be changed. Trace allocation also causes the daemon to connect to the trace
 buffers and wait for data to arrive. Explicit allocation is optional, as it is
 done automatically at trace start.
 
-The trace may then be started with `--start-trace`. This results in events
+The trace may then be started with `start-trace`. This results in events
 being recorded in the buffer. The daemon automatically collects these events.
 
 being recorded in the buffer. The daemon automatically collects these events.
 
-The trace may be stopped with `--stop-trace`, either definitely after all the
+The trace may be stopped with `stop-trace`, either definitely after all the
 wanted information is collected, or temporarily, before being started again
 wanted information is collected, or temporarily, before being started again
-with `--start-trace`. This results in effectively 'pausing' the recording.
-After using `--stop-trace`, if a daemon is collecting the trace, it may not
+with `start-trace`. This results in effectively 'pausing' the recording.
+After using `stop-trace`, if a daemon is collecting the trace, it may not
 have flushed to the disk the full contents of the buffer yet.
 
 have flushed to the disk the full contents of the buffer yet.
 
-Finally, when `--destroy-trace` is used, the trace buffers are unallocated.
+Finally, when `destroy-trace` is used, the trace buffers are unallocated.
 However, the memory may not be effectively freed until the daemon finishes to
 collect them. When the trace is being collected by `ust-consumerd`, this command
 guarantees its full contents is flushed to the disk.
 However, the memory may not be effectively freed until the daemon finishes to
 collect them. When the trace is being collected by `ust-consumerd`, this command
 guarantees its full contents is flushed to the disk.
@@ -113,8 +118,8 @@ subbuffers it contains times the size of each subbuffer. When a subbuffer is
 full, it is collected by the daemon while the others are filled. If, however,
 the buffer size is too small, buffer overflows may occur and result in event
 loss. By default, the number of subbuffers per buffer is 2. Subbuffer size
 full, it is collected by the daemon while the others are filled. If, however,
 the buffer size is too small, buffer overflows may occur and result in event
 loss. By default, the number of subbuffers per buffer is 2. Subbuffer size
-for a given channel may be chosen with `--set-subbuf-size` while the subbuffer
-count is set with `--set-subbuf-num`.
+for a given channel may be chosen with `set-subbuf-size` while the subbuffer
+count is set with `set-subbuf-num`.
 
 ## SEE ALSO
 
 
 ## SEE ALSO
 
This page took 0.030652 seconds and 4 git commands to generate.