2005-07-28 Frank Ch. Eigler <fche@redhat.com>

	* stap.1: Beginnings of a man page.
	* Makefile.am: Install it.  Comment out stpd LDADD goodies.
	* configure.ac: Futilely complain about non-stpd LIBS.
	* Makefile.in, configure.in: Regenerated.
	* main.cxx (usage): Remove ARGS from help text, as nothing is
	done with these yet.

1 files changed, 128 insertions, 0 deletions

diff --git a/stap.1 b/stap.1
new file mode 100644
index 00000000..69b0aaa3
--- /dev/null
+++ b/stap.1
@@ -0,0 +1,128 @@
+.TH STAP 1 "July 28 2005" "Red Hat" "Utility Commands"
+.SH NAME
+stap \- systemtap script translator/driver
+.SH SYNOPSIS
+.TP
+.B stap
+[
+.I options
+]
+.BI FILE
+.TP
+.B stap
+[
+.I options
+]
+.BI -
+.TP
+.B stap
+[
+.I options
+]
+.BI "-e SCRIPT"
+
+.SH DESCRIPTION
+
+The
+.I stap
+program is the front-end to the SystemTap system.  It accepts probing
+instructions, written in a simple scripting language.  It translates
+the script to C code.  It then compiles this C code, and loads the
+resulting kernel module into a running Linux kernel to perform the
+requested system trace/probe functions.  The script is supplied in a
+named file, or standard input, or on the command line itself,
+respectively.
+.PP
+The language is described in a later section.
+It is strictly typed, largely declaration free, and procedural,
+inspired by
+.IR dtrace 
+and
+.IR awk .
+It allows source code points or events in the kernel to be associated
+with handlers, which are subroutines executed synchronously.  It is
+somewhat similar to "breakpoint command lists" in the
+.IR gdb
+tool.
+
+.SH OPTIONS
+
+.SH PROCESSING
+
+.SH SCRIPT LANGUAGE
+
+.SH EXAMPLES
+
+.SH SAFETY AND SECURITY
+
+SystemTap is an administrative tool at this time.  It exposes kernel
+internal data structures and potentially private user information.
+It acquires root privileges to actually run the kernel objects it
+builds using the
+.IR sudo
+command applied to the
+.IR stpd
+program.  The latter is a part of the SystemTap package, dedicated to
+module loading and unloading (but only in the white zone), and
+kernel-to-user data transfer.  Since 
+.IR stpd
+does not perform any additional security checks on the kernel objects
+it is given, it would be unwise for a system administrator to give
+even targeted
+.IR sudo
+privileges to untrusted users.
+
+.PP
+The translator asserts certain safety constraints.  It aims to ensure
+that no handler routine can run for very long, allocate memory,
+perform unsafe operations, or in unintentionally interfere with the
+kernel.
+
+.SH ENVIRONMENT VARIABLES
+
+The
+.B SYSTEMTAP_RUNTIME
+environment variable provides a default for the
+.B \-R
+option.  Similarly, the
+.B SYSTEMTAP_TAPSET
+environment variable provides a default for the
+.B \-I
+option.
+
+.SH SEE ALSO
+
+.IR dtrace (1)
+.IR dprobes (1)
+.IR awk (1)
+.IR sudo (8)
+.IR libelf (3)
+.IR gdb (1)
+
+.SH BUGS
+
+There are numerous missing features and possibly numerous bugs.  Use
+the Bugzilla link off of the project web page
+.BR http://sources.redhat.com/systemtap/ ,
+or the mailing list
+.BR systemtap@sources.redhat.com .
+
+.SH AUTHORS
+
+The
+.IR stap
+translator was written by Frank Ch. Eigler and Graydon Hoare.  The
+kernel-side runtime library and the user-level
+.IR stpd
+daemon was written by Martin Hunt and Tom Zanussi.
+
+.SH ACKNOWLEDGEMENTS
+
+The script language design was inspired by Sun's 
+.IR dtrace ,
+and refined by numerous participants on the project mailing list.
+The current probing mechanism uses IBM's
+.IR kprobes ,
+and
+.IR relayfs
+packages.