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.

7 files changed, 221 insertions, 30 deletions

diff --git a/ChangeLog b/ChangeLog
index a8d5cb0a..45a7d919 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,14 @@
 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.
+
+2005-07-28  Frank Ch. Eigler  <fche@redhat.com>
+
 	* translate.cxx: Add "pt_regs*" field to context.
 	* tapsets.cxx (*): Correct kprobes API interface.
 	* testsuite/buildok/three.stp: New test, copied from semok.
diff --git a/Makefile.am b/Makefile.am
index 0da0a1bc..1a20caf1 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -6,6 +6,7 @@ AM_MAKEFLAGS = 'CXXFLAGS=$(CXXFLAGS)' 'LDFLAGS=$(LDFLAGS)'
 AM_CPPFLAGS = -DPKGLIBDIR='"${libexecdir}/${PACKAGE}"' \
 	      -DPKGDATADIR='"${datadir}/${PACKAGE}"'
 
+man_MANS = stap.1
 bin_PROGRAMS = stap
 stap_SOURCES = main.cxx \
 	parse.cxx staptree.cxx elaborate.cxx translate.cxx \
@@ -16,7 +17,7 @@ libexec_PROGRAMS = stpd
 stpd_SOURCES = runtime/stpd/stpd.c runtime/stpd/librelay.c
 stpd_LDADD = -lpthread
 # automake doesn't get rpath right unless we do this
-stpd_LDFLAGS = -Wl,-rpath '$(libdir)/systemtap'
+# stpd_LDFLAGS = -Wl,-rpath '$(libdir)/systemtap'
 
 AM_CXXFLAGS = -Wall
 
diff --git a/Makefile.in b/Makefile.in
index 7e4d7c39..2bdf9aab 100644
--- a/Makefile.in
+++ b/Makefile.in
@@ -54,7 +54,8 @@ am__CONFIG_DISTCLEAN_FILES = config.status config.cache config.log \
 mkinstalldirs = $(install_sh) -d
 CONFIG_HEADER = config.h
 CONFIG_CLEAN_FILES = systemtap.spec
-am__installdirs = "$(DESTDIR)$(bindir)" "$(DESTDIR)$(libexecdir)"
+am__installdirs = "$(DESTDIR)$(bindir)" "$(DESTDIR)$(libexecdir)" \
+	"$(DESTDIR)$(man1dir)"
 binPROGRAMS_INSTALL = $(INSTALL_PROGRAM)
 libexecPROGRAMS_INSTALL = $(INSTALL_PROGRAM)
 PROGRAMS = $(bin_PROGRAMS) $(libexec_PROGRAMS)
@@ -82,6 +83,9 @@ CXXLINK = $(CXXLD) $(AM_CXXFLAGS) $(CXXFLAGS) $(AM_LDFLAGS) $(LDFLAGS) \
 	-o $@
 SOURCES = $(stap_SOURCES) $(stpd_SOURCES)
 DIST_SOURCES = $(stap_SOURCES) $(stpd_SOURCES)
+man1dir = $(mandir)/man1
+NROFF = nroff
+MANS = $(man_MANS)
 ETAGS = etags
 CTAGS = ctags
 DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
@@ -185,6 +189,7 @@ AM_MAKEFLAGS = 'CXXFLAGS=$(CXXFLAGS)' 'LDFLAGS=$(LDFLAGS)'
 AM_CPPFLAGS = -DPKGLIBDIR='"${libexecdir}/${PACKAGE}"' \
 	      -DPKGDATADIR='"${datadir}/${PACKAGE}"'
 
+man_MANS = stap.1
 stap_SOURCES = main.cxx \
 	parse.cxx staptree.cxx elaborate.cxx translate.cxx \
 	tapsets.cxx buildrun.cxx
@@ -193,7 +198,7 @@ stap_CXXFLAGS = -Werror $(AM_CXXFLAGS)
 stpd_SOURCES = runtime/stpd/stpd.c runtime/stpd/librelay.c
 stpd_LDADD = -lpthread
 # automake doesn't get rpath right unless we do this
-stpd_LDFLAGS = -Wl,-rpath '$(libdir)/systemtap'
+# stpd_LDFLAGS = -Wl,-rpath '$(libdir)/systemtap'
 AM_CXXFLAGS = -Wall
 
 # Get extra libs as needed
@@ -494,6 +499,51 @@ stap-buildrun.obj: buildrun.cxx
 @AMDEP_TRUE@@am__fastdepCXX_FALSE@	DEPDIR=$(DEPDIR) $(CXXDEPMODE) $(depcomp) @AMDEPBACKSLASH@
 @am__fastdepCXX_FALSE@	$(CXX) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(stap_CXXFLAGS) $(CXXFLAGS) -c -o stap-buildrun.obj `if test -f 'buildrun.cxx'; then $(CYGPATH_W) 'buildrun.cxx'; else $(CYGPATH_W) '$(srcdir)/buildrun.cxx'; fi`
 uninstall-info-am:
+install-man1: $(man1_MANS) $(man_MANS)
+	@$(NORMAL_INSTALL)
+	test -z "$(man1dir)" || $(mkdir_p) "$(DESTDIR)$(man1dir)"
+	@list='$(man1_MANS) $(dist_man1_MANS) $(nodist_man1_MANS)'; \
+	l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \
+	for i in $$l2; do \
+	  case "$$i" in \
+	    *.1*) list="$$list $$i" ;; \
+	  esac; \
+	done; \
+	for i in $$list; do \
+	  if test -f $(srcdir)/$$i; then file=$(srcdir)/$$i; \
+	  else file=$$i; fi; \
+	  ext=`echo $$i | sed -e 's/^.*\\.//'`; \
+	  case "$$ext" in \
+	    1*) ;; \
+	    *) ext='1' ;; \
+	  esac; \
+	  inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \
+	  inst=`echo $$inst | sed -e 's/^.*\///'`; \
+	  inst=`echo $$inst | sed '$(transform)'`.$$ext; \
+	  echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man1dir)/$$inst'"; \
+	  $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man1dir)/$$inst"; \
+	done
+uninstall-man1:
+	@$(NORMAL_UNINSTALL)
+	@list='$(man1_MANS) $(dist_man1_MANS) $(nodist_man1_MANS)'; \
+	l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \
+	for i in $$l2; do \
+	  case "$$i" in \
+	    *.1*) list="$$list $$i" ;; \
+	  esac; \
+	done; \
+	for i in $$list; do \
+	  ext=`echo $$i | sed -e 's/^.*\\.//'`; \
+	  case "$$ext" in \
+	    1*) ;; \
+	    *) ext='1' ;; \
+	  esac; \
+	  inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \
+	  inst=`echo $$inst | sed -e 's/^.*\///'`; \
+	  inst=`echo $$inst | sed '$(transform)'`.$$ext; \
+	  echo " rm -f '$(DESTDIR)$(man1dir)/$$inst'"; \
+	  rm -f "$(DESTDIR)$(man1dir)/$$inst"; \
+	done
 
 ID: $(HEADERS) $(SOURCES) $(LISP) $(TAGS_FILES)
 	list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \
@@ -749,9 +799,9 @@ distcleancheck: distclean
 check-am: all-am
 	$(MAKE) $(AM_MAKEFLAGS) check-TESTS
 check: check-am
-all-am: Makefile $(PROGRAMS) config.h
+all-am: Makefile $(PROGRAMS) $(MANS) config.h
 installdirs:
-	for dir in "$(DESTDIR)$(bindir)" "$(DESTDIR)$(libexecdir)"; do \
+	for dir in "$(DESTDIR)$(bindir)" "$(DESTDIR)$(libexecdir)" "$(DESTDIR)$(man1dir)"; do \
 	  test -z "$$dir" || $(mkdir_p) "$$dir"; \
 	done
 install: install-am
@@ -800,13 +850,13 @@ info: info-am
 
 info-am:
 
-install-data-am: install-data-local
+install-data-am: install-data-local install-man
 
 install-exec-am: install-binPROGRAMS install-libexecPROGRAMS
 
 install-info: install-info-am
 
-install-man:
+install-man: install-man1
 
 installcheck-am:
 
@@ -830,7 +880,9 @@ ps: ps-am
 ps-am:
 
 uninstall-am: uninstall-binPROGRAMS uninstall-info-am \
-	uninstall-libexecPROGRAMS
+	uninstall-libexecPROGRAMS uninstall-man
+
+uninstall-man: uninstall-man1
 
 .PHONY: CTAGS GTAGS all all-am am--refresh check check-TESTS check-am \
 	clean clean-binPROGRAMS clean-generic clean-libexecPROGRAMS \
@@ -842,11 +894,12 @@ uninstall-am: uninstall-binPROGRAMS uninstall-info-am \
 	install-binPROGRAMS install-data install-data-am \
 	install-data-local install-exec install-exec-am install-info \
 	install-info-am install-libexecPROGRAMS install-man \
-	install-strip installcheck installcheck-am installdirs \
-	maintainer-clean maintainer-clean-generic mostlyclean \
-	mostlyclean-compile mostlyclean-generic pdf pdf-am ps ps-am \
-	tags uninstall uninstall-am uninstall-binPROGRAMS \
-	uninstall-info-am uninstall-libexecPROGRAMS
+	install-man1 install-strip installcheck installcheck-am \
+	installdirs maintainer-clean maintainer-clean-generic \
+	mostlyclean mostlyclean-compile mostlyclean-generic pdf pdf-am \
+	ps ps-am tags uninstall uninstall-am uninstall-binPROGRAMS \
+	uninstall-info-am uninstall-libexecPROGRAMS uninstall-man \
+	uninstall-man1
 
 dist-hook:
 	find $(distdir) -name CVS -o -name '*~' -o -name '.#*' | xargs rm -rf
diff --git a/configure b/configure
index 93fe0bec..ce3886a9 100755
--- a/configure
+++ b/configure
@@ -1,6 +1,6 @@
 #! /bin/sh
 # Guess values for system-dependent variables and create Makefiles.
-# Generated by GNU Autoconf 2.59 for systemtap 0.1.1.
+# Generated by GNU Autoconf 2.59 for systemtap 0.2.
 #
 # Report bugs to <systemtap@sources.redhat.com>.
 #
@@ -269,8 +269,8 @@ SHELL=${CONFIG_SHELL-/bin/sh}
 # Identity of this package.
 PACKAGE_NAME='systemtap'
 PACKAGE_TARNAME='systemtap'
-PACKAGE_VERSION='0.1.1'
-PACKAGE_STRING='systemtap 0.1.1'
+PACKAGE_VERSION='0.2'
+PACKAGE_STRING='systemtap 0.2'
 PACKAGE_BUGREPORT='systemtap@sources.redhat.com'
 
 # Factoring default headers for most tests.
@@ -791,7 +791,7 @@ if test "$ac_init_help" = "long"; then
   # Omit some internal or obsolete options to make the list less imposing.
   # This message is too long to be a string in the A/UX 3.1 sh.
   cat <<_ACEOF
-\`configure' configures systemtap 0.1.1 to adapt to many kinds of systems.
+\`configure' configures systemtap 0.2 to adapt to many kinds of systems.
 
 Usage: $0 [OPTION]... [VAR=VALUE]...
 
@@ -853,7 +853,7 @@ fi
 
 if test -n "$ac_init_help"; then
   case $ac_init_help in
-     short | recursive ) echo "Configuration of systemtap 0.1.1:";;
+     short | recursive ) echo "Configuration of systemtap 0.2:";;
    esac
   cat <<\_ACEOF
 
@@ -976,7 +976,7 @@ fi
 test -n "$ac_init_help" && exit 0
 if $ac_init_version; then
   cat <<\_ACEOF
-systemtap configure 0.1.1
+systemtap configure 0.2
 generated by GNU Autoconf 2.59
 
 Copyright (C) 2003 Free Software Foundation, Inc.
@@ -990,7 +990,7 @@ cat >&5 <<_ACEOF
 This file contains any messages produced by compilers while
 running configure, to aid debugging if configure makes a mistake.
 
-It was created by systemtap $as_me 0.1.1, which was
+It was created by systemtap $as_me 0.2, which was
 generated by GNU Autoconf 2.59.  Invocation command line was
 
   $ $0 $@
@@ -1635,7 +1635,7 @@ fi
 
 # Define the identity of the package.
  PACKAGE='systemtap'
- VERSION='0.1.1'
+ VERSION='0.2'
 
 
 cat >>confdefs.h <<_ACEOF
@@ -6093,7 +6093,7 @@ _ASBOX
 } >&5
 cat >&5 <<_CSEOF
 
-This file was extended by systemtap $as_me 0.1.1, which was
+This file was extended by systemtap $as_me 0.2, which was
 generated by GNU Autoconf 2.59.  Invocation command line was
 
   CONFIG_FILES    = $CONFIG_FILES
@@ -6156,7 +6156,7 @@ _ACEOF
 
 cat >>$CONFIG_STATUS <<_ACEOF
 ac_cs_version="\\
-systemtap config.status 0.1.1
+systemtap config.status 0.2
 configured by $0, generated by GNU Autoconf 2.59,
   with options \\"`echo "$ac_configure_args" | sed 's/[\\""\`\$]/\\\\&/g'`\\"
 
diff --git a/configure.ac b/configure.ac
index 00411023..05040698 100644
--- a/configure.ac
+++ b/configure.ac
@@ -1,7 +1,7 @@
 dnl configure.ac --- autoconf input file for systemtap
 dnl Process this file with autoconf to produce a configure script.
 
-AC_INIT([systemtap], 0.1.1, systemtap@sources.redhat.com, systemtap)
+AC_INIT([systemtap], 0.2, systemtap@sources.redhat.com, systemtap)
 
 AC_PREREQ(2.59)
 AM_INIT_AUTOMAKE
@@ -23,6 +23,8 @@ AC_SUBST(CFLAGS)
 AC_SUBST(CXXFLAGS)
 
 dnl Need libdwfl-capable elfutils 0.102+ from <drepper@redhat.com>
+dnl ... except that these libraries are only used by stap, not
+dnl stpd.  The implicit LIBS set from these is too broadly applied.
 AC_CHECK_HEADERS([libelf.h elfutils/libdw.h elfutils/libdwfl.h])
 AC_CHECK_LIB(dw, dwarf_begin)
 AC_CHECK_LIB(elf, elf_begin)
diff --git a/main.cxx b/main.cxx
index fb19fd43..9368573e 100644
--- a/main.cxx
+++ b/main.cxx
@@ -39,11 +39,11 @@ usage (systemtap_session& s)
     << "This is free software; see the source for copying conditions."
     << endl
     << endl
-    << "Usage: stap [options] FILE [ARGS ...]        Run script in file."
+    << "Usage: stap [options] FILE         Run script in file."
     << endl
-    << "   or: stap [options] - [ARGS ...]           Run script on stdin."
+    << "   or: stap [options] -            Run script on stdin."
     << endl
-    << "   or: stap [options] -e SCRIPT [ARGS ...]   Run given script." 
+    << "   or: stap [options] -e SCRIPT    Run given script." 
     << endl
     << endl
     << "Arguments:" << endl
@@ -66,12 +66,10 @@ usage (systemtap_session& s)
     <<      "              " << s.runtime_path << endl
     << "   -r RELEASE use kernel RELEASE, instead of" << endl
     <<      "              " << s.kernel_release << endl
-    << "   -m MODULE  set probe module name, insetad of" << endl
+    << "   -m MODULE  set probe module name, instead of" << endl
     <<      "              " << s.module_name << endl
     << "   -o FILE    send output to file instead of stdout" << endl
     << "   -k         keep temporary directory" << endl;
-  // XXX: other options:
-  // -s: safe mode
   // -d: dump safety-related external references 
 
   exit (0);
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.