From 82fab4747083d312a797d63bccca8bd94259a01b Mon Sep 17 00:00:00 2001 From: fche Date: Mon, 8 Aug 2005 16:03:38 +0000 Subject: 2005-08-08 Frank Ch. Eigler * stap.1.in: Autoconfify old man page. * configure.ac: Make it so. * stap.1: Removed. * configure, Makefile.in, aclocal.m4: Regenerated. --- ChangeLog | 7 + Makefile.in | 12 +- aclocal.m4 | 458 ++++++++++++++++++++++++++++++++------------ configure | 4 +- configure.ac | 4 +- stap.1 | 613 ---------------------------------------------------------- stap.1.in | 615 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 7 files changed, 966 insertions(+), 747 deletions(-) delete mode 100644 stap.1 create mode 100644 stap.1.in diff --git a/ChangeLog b/ChangeLog index ea9068a2..dea736f6 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2005-08-08 Frank Ch. Eigler + + * stap.1.in: Autoconfify old man page. + * configure.ac: Make it so. + * stap.1: Removed. + * configure, Makefile.in, aclocal.m4: Regenerated. + 2005-08-05 Frank Ch. Eigler * runtest.sh: Keep around log files from crashed processes, diff --git a/Makefile.in b/Makefile.in index a3503eef..5226dd5f 100644 --- a/Makefile.in +++ b/Makefile.in @@ -1,8 +1,8 @@ -# Makefile.in generated by automake 1.9.6 from Makefile.am. +# Makefile.in generated by automake 1.9.2 from Makefile.am. # @configure_input@ # Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, -# 2003, 2004, 2005 Free Software Foundation, Inc. +# 2003, 2004 Free Software Foundation, Inc. # This Makefile.in is free software; the Free Software Foundation # gives unlimited permission to copy and/or distribute it, # with or without modifications, as long as this notice is preserved. @@ -16,6 +16,8 @@ # Makefile.am --- automake input file for systemtap +SOURCES = $(stap_SOURCES) $(stpd_SOURCES) + srcdir = @srcdir@ top_srcdir = @top_srcdir@ VPATH = @srcdir@ @@ -41,7 +43,7 @@ noinst_PROGRAMS = stpd$(EXEEXT) subdir = . DIST_COMMON = README $(am__configure_deps) $(dist_man_MANS) \ $(srcdir)/Makefile.am $(srcdir)/Makefile.in \ - $(srcdir)/config.in $(srcdir)/stp_check.in \ + $(srcdir)/config.in $(srcdir)/stap.1.in $(srcdir)/stp_check.in \ $(srcdir)/systemtap.spec.in $(top_srcdir)/configure AUTHORS \ COPYING ChangeLog INSTALL NEWS TODO depcomp install-sh missing ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 @@ -52,7 +54,7 @@ am__CONFIG_DISTCLEAN_FILES = config.status config.cache config.log \ configure.lineno configure.status.lineno mkinstalldirs = $(install_sh) -d CONFIG_HEADER = config.h -CONFIG_CLEAN_FILES = systemtap.spec stp_check +CONFIG_CLEAN_FILES = systemtap.spec stp_check stap.1 am__installdirs = "$(DESTDIR)$(bindir)" "$(DESTDIR)$(man1dir)" binPROGRAMS_INSTALL = $(INSTALL_PROGRAM) PROGRAMS = $(bin_PROGRAMS) $(noinst_PROGRAMS) @@ -277,6 +279,8 @@ systemtap.spec: $(top_builddir)/config.status $(srcdir)/systemtap.spec.in cd $(top_builddir) && $(SHELL) ./config.status $@ stp_check: $(top_builddir)/config.status $(srcdir)/stp_check.in cd $(top_builddir) && $(SHELL) ./config.status $@ +stap.1: $(top_builddir)/config.status $(srcdir)/stap.1.in + cd $(top_builddir) && $(SHELL) ./config.status $@ install-binPROGRAMS: $(bin_PROGRAMS) @$(NORMAL_INSTALL) test -z "$(bindir)" || $(mkdir_p) "$(DESTDIR)$(bindir)" diff --git a/aclocal.m4 b/aclocal.m4 index 7b5533cd..22795ef4 100644 --- a/aclocal.m4 +++ b/aclocal.m4 @@ -1,7 +1,7 @@ -# generated automatically by aclocal 1.9.6 -*- Autoconf -*- +# generated automatically by aclocal 1.9.2 -*- Autoconf -*- -# Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, -# 2005 Free Software Foundation, Inc. +# Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 +# Free Software Foundation, Inc. # This file is free software; the Free Software Foundation # gives unlimited permission to copy and/or distribute it, # with or without modifications, as long as this notice is preserved. @@ -11,11 +11,23 @@ # even the implied warranty of MERCHANTABILITY or FITNESS FOR A # PARTICULAR PURPOSE. -# Copyright (C) 2002, 2003, 2005 Free Software Foundation, Inc. -# -# This file is free software; the Free Software Foundation -# gives unlimited permission to copy and/or distribute it, -# with or without modifications, as long as this notice is preserved. +# -*- Autoconf -*- +# Copyright (C) 2002, 2003 Free Software Foundation, Inc. +# Generated from amversion.in; do not edit by hand. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA # AM_AUTOMAKE_VERSION(VERSION) # ---------------------------- @@ -28,15 +40,26 @@ AC_DEFUN([AM_AUTOMAKE_VERSION], [am__api_version="1.9"]) # Call AM_AUTOMAKE_VERSION so it can be traced. # This function is AC_REQUIREd by AC_INIT_AUTOMAKE. AC_DEFUN([AM_SET_CURRENT_AUTOMAKE_VERSION], - [AM_AUTOMAKE_VERSION([1.9.6])]) + [AM_AUTOMAKE_VERSION([1.9.2])]) -# AM_AUX_DIR_EXPAND -*- Autoconf -*- +# AM_AUX_DIR_EXPAND -# Copyright (C) 2001, 2003, 2005 Free Software Foundation, Inc. -# -# This file is free software; the Free Software Foundation -# gives unlimited permission to copy and/or distribute it, -# with or without modifications, as long as this notice is preserved. +# Copyright (C) 2001, 2003 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA +# 02111-1307, USA. # For projects using AC_CONFIG_AUX_DIR([foo]), Autoconf sets # $ac_aux_dir to `$srcdir/foo'. In other projects, it is set to @@ -84,14 +107,25 @@ am_aux_dir=`cd $ac_aux_dir && pwd` ]) -# Copyright (C) 1996, 1997, 1999, 2000, 2001, 2002, 2003, 2005 +# Copyright (C) 1996, 1997, 1999, 2000, 2001, 2002, 2003 # Free Software Foundation, Inc. -# -# This file is free software; the Free Software Foundation -# gives unlimited permission to copy and/or distribute it, -# with or without modifications, as long as this notice is preserved. -# serial 4 +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA +# 02111-1307, USA. + +# serial 3 # This was merged into AC_PROG_CC in Autoconf. @@ -106,16 +140,26 @@ am_cv_prog_cc_stdc=$ac_cv_prog_cc_stdc ]) AU_DEFUN([fp_PROG_CC_STDC]) -# AM_CONDITIONAL -*- Autoconf -*- +# AM_CONDITIONAL -*- Autoconf -*- -# Copyright (C) 1997, 2000, 2001, 2003, 2004, 2005 -# Free Software Foundation, Inc. -# -# This file is free software; the Free Software Foundation -# gives unlimited permission to copy and/or distribute it, -# with or without modifications, as long as this notice is preserved. +# Copyright (C) 1997, 2000, 2001, 2003, 2004 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. -# serial 7 +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA +# 02111-1307, USA. + +# serial 6 # AM_CONDITIONAL(NAME, SHELL-CONDITION) # ------------------------------------- @@ -139,15 +183,26 @@ AC_CONFIG_COMMANDS_PRE( Usually this means the macro was only invoked conditionally.]]) fi])]) +# serial 7 -*- Autoconf -*- -# Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005 +# Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004 # Free Software Foundation, Inc. -# -# This file is free software; the Free Software Foundation -# gives unlimited permission to copy and/or distribute it, -# with or without modifications, as long as this notice is preserved. -# serial 8 +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA +# 02111-1307, USA. + # There are a few dirty hacks below to avoid letting `AC_PROG_CC' be # written in clear, in which case automake, when reading aclocal.m4, @@ -156,6 +211,7 @@ fi])]) # CC etc. in the Makefile, will ask for an AC_PROG_CC use... + # _AM_DEPENDENCIES(NAME) # ---------------------- # See how the compiler implements dependency checking. @@ -295,16 +351,27 @@ AM_CONDITIONAL([AMDEP], [test "x$enable_dependency_tracking" != xno]) AC_SUBST([AMDEPBACKSLASH]) ]) -# Generate code to set up dependency tracking. -*- Autoconf -*- +# Generate code to set up dependency tracking. -*- Autoconf -*- -# Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005 -# Free Software Foundation, Inc. -# -# This file is free software; the Free Software Foundation -# gives unlimited permission to copy and/or distribute it, -# with or without modifications, as long as this notice is preserved. +# Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004 +# Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. -#serial 3 +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA +# 02111-1307, USA. + +#serial 2 # _AM_OUTPUT_DEPENDENCY_COMMANDS # ------------------------------ @@ -363,19 +430,30 @@ AC_DEFUN([AM_OUTPUT_DEPENDENCY_COMMANDS], [AMDEP_TRUE="$AMDEP_TRUE" ac_aux_dir="$ac_aux_dir"]) ]) -# Do all the work for Automake. -*- Autoconf -*- +# Do all the work for Automake. -*- Autoconf -*- -# Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 +# This macro actually does too much some checks are only needed if +# your package does certain things. But this isn't really a big deal. + +# Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 # Free Software Foundation, Inc. -# -# This file is free software; the Free Software Foundation -# gives unlimited permission to copy and/or distribute it, -# with or without modifications, as long as this notice is preserved. -# serial 12 +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. -# This macro actually does too much. Some checks are only needed if -# your package does certain things. But this isn't really a big deal. +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA +# 02111-1307, USA. + +# serial 11 # AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE]) # AM_INIT_AUTOMAKE([OPTIONS]) @@ -477,27 +555,51 @@ for _am_header in $config_headers :; do done echo "timestamp for $1" >`AS_DIRNAME([$1])`/stamp-h[]$_am_stamp_count]) -# Copyright (C) 2001, 2003, 2005 Free Software Foundation, Inc. -# -# This file is free software; the Free Software Foundation -# gives unlimited permission to copy and/or distribute it, -# with or without modifications, as long as this notice is preserved. - # AM_PROG_INSTALL_SH # ------------------ # Define $install_sh. + +# Copyright (C) 2001, 2003 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA +# 02111-1307, USA. + AC_DEFUN([AM_PROG_INSTALL_SH], [AC_REQUIRE([AM_AUX_DIR_EXPAND])dnl install_sh=${install_sh-"$am_aux_dir/install-sh"} AC_SUBST(install_sh)]) -# Copyright (C) 2003, 2005 Free Software Foundation, Inc. -# -# This file is free software; the Free Software Foundation -# gives unlimited permission to copy and/or distribute it, -# with or without modifications, as long as this notice is preserved. +# -*- Autoconf -*- +# Copyright (C) 2003 Free Software Foundation, Inc. -# serial 2 +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA +# 02111-1307, USA. + +# serial 1 # Check whether the underlying file-system supports filenames # with a leading dot. For instance MS-DOS doesn't. @@ -512,17 +614,28 @@ fi rmdir .tst 2>/dev/null AC_SUBST([am__leading_dot])]) -# Add --enable-maintainer-mode option to configure. -*- Autoconf -*- +# Add --enable-maintainer-mode option to configure. # From Jim Meyering -# Copyright (C) 1996, 1998, 2000, 2001, 2002, 2003, 2004, 2005 +# Copyright (C) 1996, 1998, 2000, 2001, 2002, 2003, 2004 # Free Software Foundation, Inc. -# -# This file is free software; the Free Software Foundation -# gives unlimited permission to copy and/or distribute it, -# with or without modifications, as long as this notice is preserved. -# serial 4 +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA +# 02111-1307, USA. + +# serial 3 AC_DEFUN([AM_MAINTAINER_MODE], [AC_MSG_CHECKING([whether to enable maintainer-specific portions of Makefiles]) @@ -541,15 +654,26 @@ AC_DEFUN([AM_MAINTAINER_MODE], AU_DEFUN([jm_MAINTAINER_MODE], [AM_MAINTAINER_MODE]) -# Check to see how 'make' treats includes. -*- Autoconf -*- +# Check to see how 'make' treats includes. -*- Autoconf -*- -# Copyright (C) 2001, 2002, 2003, 2005 Free Software Foundation, Inc. -# -# This file is free software; the Free Software Foundation -# gives unlimited permission to copy and/or distribute it, -# with or without modifications, as long as this notice is preserved. +# Copyright (C) 2001, 2002, 2003 Free Software Foundation, Inc. -# serial 3 +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA +# 02111-1307, USA. + +# serial 2 # AM_MAKE_INCLUDE() # ----------------- @@ -593,16 +717,27 @@ AC_MSG_RESULT([$_am_result]) rm -f confinc confmf ]) -# Fake the existence of programs that GNU maintainers use. -*- Autoconf -*- +# -*- Autoconf -*- -# Copyright (C) 1997, 1999, 2000, 2001, 2003, 2005 -# Free Software Foundation, Inc. -# -# This file is free software; the Free Software Foundation -# gives unlimited permission to copy and/or distribute it, -# with or without modifications, as long as this notice is preserved. -# serial 4 +# Copyright (C) 1997, 1999, 2000, 2001, 2003 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA +# 02111-1307, USA. + +# serial 3 # AM_MISSING_PROG(NAME, PROGRAM) # ------------------------------ @@ -628,16 +763,27 @@ else fi ]) -# Copyright (C) 2003, 2004, 2005 Free Software Foundation, Inc. -# -# This file is free software; the Free Software Foundation -# gives unlimited permission to copy and/or distribute it, -# with or without modifications, as long as this notice is preserved. - # AM_PROG_MKDIR_P # --------------- # Check whether `mkdir -p' is supported, fallback to mkinstalldirs otherwise. -# + +# Copyright (C) 2003, 2004 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA +# 02111-1307, USA. + # Automake 1.8 used `mkdir -m 0755 -p --' to ensure that directories # created by `make install' are always world readable, even if the # installer happens to have an overly restrictive umask (e.g. 077). @@ -691,15 +837,26 @@ else fi AC_SUBST([mkdir_p])]) -# Helper functions for option handling. -*- Autoconf -*- +# Helper functions for option handling. -*- Autoconf -*- -# Copyright (C) 2001, 2002, 2003, 2005 Free Software Foundation, Inc. -# -# This file is free software; the Free Software Foundation -# gives unlimited permission to copy and/or distribute it, -# with or without modifications, as long as this notice is preserved. +# Copyright (C) 2001, 2002, 2003 Free Software Foundation, Inc. -# serial 3 +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA +# 02111-1307, USA. + +# serial 2 # _AM_MANGLE_OPTION(NAME) # ----------------------- @@ -724,14 +881,26 @@ AC_DEFUN([_AM_SET_OPTIONS], AC_DEFUN([_AM_IF_OPTION], [m4_ifset(_AM_MANGLE_OPTION([$1]), [$2], [$3])]) -# Copyright (C) 1996, 1997, 1998, 2000, 2001, 2002, 2003, 2005 + +# Copyright (C) 1996, 1997, 1998, 2000, 2001, 2002, 2003 # Free Software Foundation, Inc. -# -# This file is free software; the Free Software Foundation -# gives unlimited permission to copy and/or distribute it, -# with or without modifications, as long as this notice is preserved. -# serial 4 +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA +# 02111-1307, USA. + +# serial 3 AC_DEFUN([AM_C_PROTOTYPES], [AC_REQUIRE([AC_C_PROTOTYPES]) @@ -749,16 +918,28 @@ AC_SUBST(ANSI2KNR)dnl AU_DEFUN([fp_C_PROTOTYPES], [AM_C_PROTOTYPES]) -# Check to make sure that the build environment is sane. -*- Autoconf -*- - -# Copyright (C) 1996, 1997, 2000, 2001, 2003, 2005 -# Free Software Foundation, Inc. # -# This file is free software; the Free Software Foundation -# gives unlimited permission to copy and/or distribute it, -# with or without modifications, as long as this notice is preserved. +# Check to make sure that the build environment is sane. +# + +# Copyright (C) 1996, 1997, 2000, 2001, 2003 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA +# 02111-1307, USA. -# serial 4 +# serial 3 # AM_SANITY_CHECK # --------------- @@ -801,14 +982,25 @@ Check your system clock]) fi AC_MSG_RESULT(yes)]) -# Copyright (C) 2001, 2003, 2005 Free Software Foundation, Inc. -# -# This file is free software; the Free Software Foundation -# gives unlimited permission to copy and/or distribute it, -# with or without modifications, as long as this notice is preserved. - # AM_PROG_INSTALL_STRIP -# --------------------- + +# Copyright (C) 2001, 2003 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA +# 02111-1307, USA. + # One issue with vendor `install' (even GNU) is that you can't # specify the program used to strip binaries. This is especially # annoying in cross-compiling environments, where the build's strip @@ -831,13 +1023,25 @@ AC_SUBST([INSTALL_STRIP_PROGRAM])]) # Check how to create a tarball. -*- Autoconf -*- -# Copyright (C) 2004, 2005 Free Software Foundation, Inc. -# -# This file is free software; the Free Software Foundation -# gives unlimited permission to copy and/or distribute it, -# with or without modifications, as long as this notice is preserved. +# Copyright (C) 2004 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA +# 02111-1307, USA. + +# serial 1 -# serial 2 # _AM_PROG_TAR(FORMAT) # -------------------- diff --git a/configure b/configure index 739b4cdd..69a2cb56 100755 --- a/configure +++ b/configure @@ -5165,11 +5165,12 @@ cat >>confdefs.h <<_ACEOF #define DATE "$date" _ACEOF +DATE="$date" ac_config_headers="$ac_config_headers config.h:config.in" - ac_config_files="$ac_config_files Makefile systemtap.spec stp_check" + ac_config_files="$ac_config_files Makefile systemtap.spec stp_check stap.1" cat >confcache <<\_ACEOF # This file is a shell script that caches the results of configure @@ -5744,6 +5745,7 @@ do "Makefile" ) CONFIG_FILES="$CONFIG_FILES Makefile" ;; "systemtap.spec" ) CONFIG_FILES="$CONFIG_FILES systemtap.spec" ;; "stp_check" ) CONFIG_FILES="$CONFIG_FILES stp_check" ;; + "stap.1" ) CONFIG_FILES="$CONFIG_FILES stap.1" ;; "depfiles" ) CONFIG_COMMANDS="$CONFIG_COMMANDS depfiles" ;; "config.h" ) CONFIG_HEADERS="$CONFIG_HEADERS config.h:config.in" ;; *) { { echo "$as_me:$LINENO: error: invalid argument: $ac_config_target" >&5 diff --git a/configure.ac b/configure.ac index 0189a2ed..0e0f4da0 100644 --- a/configure.ac +++ b/configure.ac @@ -37,8 +37,8 @@ fi dnl Plop in the build (configure) date date=`date +%Y-%m-%d` AC_DEFINE_UNQUOTED(DATE, "$date", [Configuration/build date]) -AC_SUBST(DATE) +AC_SUBST(DATE, "$date") AC_CONFIG_HEADERS([config.h:config.in]) -AC_CONFIG_FILES(Makefile systemtap.spec stp_check) +AC_CONFIG_FILES(Makefile systemtap.spec stp_check stap.1) AC_OUTPUT diff --git a/stap.1 b/stap.1 deleted file mode 100644 index 230f7a9b..00000000 --- a/stap.1 +++ /dev/null @@ -1,613 +0,0 @@ -.\" t -.TH STAP 1 "July 28 2005" "Red Hat" -.SH NAME -stap \- systemtap script translator/driver -.SH SYNOPSIS - -.br -.B stap -[ -.I OPTIONS -] -.I FILENAME -.br -.B stap -[ -.I OPTIONS -] -.B \- -.br -.B stap -[ -.I OPTIONS -] -.BI \-e " SCRIPT" - -.SH DESCRIPTION - -The -.IR stap -program is the front-end to the Systemtap tool. -It accepts probing instructions (written in a simple scripting language), translates -those instructions into C code, compiles this C code, and loads the -resulting kernel module into a running Linux kernel to perform the -requested system trace/probe functions. -You can supply the script in a named file, from standard input, or from the command line. -.PP -The language, which is described in a later section, is strictly typed, -declaration free, procedural, and 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 that are executed synchronously. It is -somewhat similar conceptually to "breakpoint command lists" in the -.IR gdb -debugger. - -.SH OPTIONS -The systemtap translator supports the following options. Any other option -prints a list of supported options. -.\" undocumented for now: -.\" -t test mode -.\" -r RELEASE -.TP -.B \-v -Verbose mode. Produces more informative output. -.TP -.B \-k -Keep the temporary directory after all processing. This may be useful -in order to examine the generated C code, or to reuse the compiled -kernel object. -.TP -.B \-g -Guru mode. Enables parsing of unsafe expert-level constructs like -embedded C. -.TP -.BI \-p " NUM" -Stop after pass NUM. The passes are numbered 1-5: parse, elaborate, -translate, compile, run. See the -.B PROCESSING -section for details. -.TP -.BI \-I " DIR" -Add the given directory to the tapset search directory. See the -description of pass 2 for details. -.TP -.BI \-R " DIR" -Look for the systemtap runtime sources in the given directory. -.TP -.BI \-m " MODULE" -Use the given name for the generated kernel object module, instead -of a unique randomized name. -.TP -.BI \-o " FILE" -Send standard output to named file. - -.SH SCRIPT LANGUAGE - -The systemtap script language resembles -.IR awk . -There are two main outermost constructs: probes and functions. Within -these, statements and expressions use C-like operator syntax and -precedence. - -.SS GENERAL SYNTAX -Whitespace is ignored. Three forms of comments are supported: -.RS -.br -# ... shell style, to the end of line -.br -// ... C++ style, to the end of line -.br -/* ... C style ... */ -.RE -Literals are either strings enclosed in double-quotes (soon supporting -the usual C escape codes with backslashes), or integers (in decimal, -hexadecimal, or octal, using the same notation as in C). All strings -are limited in length to some reasonable value (a few hundred bytes). -Integers are 64-bit signed quantities, although the parser also accepts -(and wraps around) values above positive 2**63. - -.SS VARIABLES -Identifiers for variables and functions are an alphanumeric sequence, -and may include "_" and "$" characters. They may not start with a -plain digit, as in C. Each variable is by default local to the probe -or function statement block within which it is mentioned, and therefore -its scope and lifetime is limited to a particular probe or function -invocation. -.\" XXX add statistics type here once it's supported -.PP -Scalar variables are implicitly typed as either string or integer. -Associative arrays also have a string or integer value, and a -a tuple of strings and/or integers serving as a key. -The translator performs -.I type inference -on all identifiers, including array indexes and function parameters. -Inconsistent type-related use of identifiers signals an error. -.PP -Variables may be declared global, so that they are shared amongst all -probes and live as long as the entire systemtap session. There is one -namespace for all global variables, regardless of which script file -they are found within. A global declaration may be written at the -outermost level anywhere, not within a block of code. The following -declaration marks "var1" and "var2" as global. The translator will -infer for each its value type, and if it is used as an array, its key -types. -.RS -global var1, var2 -.RE -.\" XXX add statistics type here once it's supported - -.SS STATEMENTS -Statements enable procedural control flow. They may occur within -functions and probe handlers. The total number of statements executed -in response to any single probe event is limited to some number -defined by a macro in the translated C code, and is in the -neighbourhood of 1000. -.TP -EXP -Execute the string- or integer-valued expression and throw away -the value. -.TP -.BR { " STMT1 STMT2 ... " } -Execute each statement in sequence in this block. Note that -separators or terminators are generally not necessary between statements. -.TP -.BR ; -Null statement, do nothing. It is useful as an optional separator between -statements to improve syntax-error detection and to handle certain -grammar ambiguities. -.TP -.BR if " (EXP) STMT1 [ " else " STMT2 ]" -Compare integer-valued EXP to zero. Execute the first (non-zero) -or second STMT (zero). -.TP -.BR while " (EXP) STMT" -While integer-valued EXP evaluates to non-zero, execute STMT. -.TP -.BR for " (EXP1; EXP2; EXP2) STMT" -Execute EXP2 as initialization. While EXP1 is non-zero, execute -STMT, then the iteration expression EXP1. -.TP -.BR foreach " (VAR " in " ARRAY) STMT" -Loop over each element of the named global array, assigning current -key to VAR. The array may not be modified within the statement. -.TP -.BR foreach " ([VAR1, VAR2, ...] " in " ARRAY) STMT" -Same as above, used when the array is indexed with a tuple of keys. -.TP -.BR break ", " continue -Exit or iterate the innermost nesting loop -.RB ( while " or " for " or " foreach ) -statement. -.TP -.BR return " EXP" -Return EXP value from enclosing function. A return value is mandatory, -since void functions are not supported. -.TP -.BR next -Return now from enclosing probe handler. - -.SS EXPRESSIONS -Systemtap supports a number of operators that have the same general syntax, -semantics, and precedence as in C and awk. Arithmetic is performed as per -C rules. Division by zero is detected and results in an error. -.TP -binary numeric operators -.B * / % + - >> << & ^ | && || -.TP -binary string operators -.B . -(string concatenation) -.TP -numeric assignment operators -.B = *= /= %= += -= >>= <<= &= ^= |= -.TP -string assignment operators -.B = .= -.TP -unary numeric operators -.B - ! ~ ++ -- -.TP -binary numeric or string comparison operators -.B < > <= >= == != -.TP -ternary operator -.RB cond " ? " exp1 " : " exp2 -.TP -grouping operator -.BR ( " exp " ) -.TP -function call -.RB "fn " ( "[ arg1, arg2, ... ]" ) - -.SS PROBES -The main construct in the scripting language identifies probes. -Probes associate abstract events with a statement block ("probe -handler") that is to be executed when those events occur. The -general syntax is as follows: -.RS -.br -.nh -.nf -.BR probe " PROBEPOINT [" , " PROBEPOINT] " { " [STMT ...] " } -.hy -.fi -.RE -.PP -Events are specified in a special syntax called "probe points". One -family refers to specific points in a kernel, which are identified by -module, source file, line number, function name, C label name, or some -combination of these. This kind of "synchronous" event is deemed to -occur when any processor executes an instruction matched by the -specification. Other families of probe points refer to "asynchronous" -events such as timers/counters rolling over, where there is no fixed -execution point that is related. Each probe point specification may -match multiple physical locations, all of which are then probed. A -probe declaration may also contain several comma-separated -specifications, all of which are probed. -.PP -Here is a list of probe point families currently supported. The -.B .function -variant places a probe near the beginning of the named function, so that -parameters are available as context variables. The -.B .return -variant places a probe at the moment of return from the named function, so -the return value is available as the "$retvalue" context variable. -The -.B .statement -variant places a probe at the exact spot, exposing those local variables -that are visible there. -.RS -.nf -.br -.BR kernel.function( PATTERN ) -.br -.BR kernel.function( PATTERN ).return -.br -.BR module( MPATTERN ).function( PATTERN ) -.br -.BR module( MPATTERN ).function( PATTERN ).return -.br -.BR kernel.statement( PATTERN ) -.br -.BR module( MPATTERN ).statement( PATTERN ) -.fi -.RE -.PP -In the above list, MPATTERN stands for a string literal that aims to -identify the loaded kernel module of interest. It may include "*" and -"?" wildcards. PATTERN stands for a string literal that aims to -identify a point in the program. It is made up of three parts. The -first part is the name of a function, as would appear in the -.I nm -program's output. This part may use the "*" and "?" wildcarding -operators to match multiple names. The second part is optional, and -begins with the "@" character. It is followed by a source file name -wildcard pattern, such as -.IR mm/slab* . -Finally, the third part is optional if the file name part was given, -and identifies the line number in the source file, preceded by a ":". -As an alternative, PATTERN may be a numeric constant, indicating an -(module-relative or kernel-absolute) address. -.PP -Here are some example probe points: -.TP -.B kernel.function("*init*"), kernel.function("*exit*") -refers to all kernel functions with "init" or "exit" in the name. -.TP -.B kernel.function("*@kernel/sched.c:240") -refers to any functions within the "kernel/sched.c" file that span -line 240. -.TP -.B module("usb*").function("*sync*").return -refers to the moment of return from all functions with "sync" in the -name in any of the USB drivers. -.TP -.B kernel.statement(0xc0044852) -refers to the first byte of the statement whose compiled instructions -include the given address in the kernel. - -.PP -When any matching event occurs, the probe handler is run within that -context. For events that are defined by execution of specific parts -of code, this context may include variables defined in the source code -at that spot. These "target variables" are presented to the script as -variables whose names are prefixed with "$". They may be read/written -only if the kernel's compiler preserved them despite optimization. -This is the same constraint that a debugger user faces when working -with optimized code. Asynchronous probes have very little context. -.PP -In addition, "probe aliases" may be defined. Probe aliases look -similar to probe definitions, but instead of activating a probe at the -given point, it defines a new probe point name to alias an existing -one. This is identified by the "=" assignment operator. In addition, -the probe handler defined with an alias is implicitly added as a -prologue to any probe that refers to the alias. For example: -.RS -.nf -.nh -probe syscall("read") = kernel.function("sys_read") { - fildes = $fd -} -.hy -.fi -.RE -defines a new probe point -.nh -.IR syscall("read") , -.hy -which expands to -.nh -.IR kernel.function("sys_read") , -.hy -with the given assignment as a prologue. Another probe definition -may use the alias like this: -.RS -.nf -probe syscall("read") { - printk ("reading fd=" . string (fildes)) -} -.fi -.RE - -.SS FUNCTIONS -Systemtap scripts may define subroutines to factor out common work. -Functions take any number of scalar (integer or string) arguments, and -must return a single scalar (integer or string). An example function -declaration looks like this: -.RS -.nf -function thisfn (arg1, arg2) { - return arg1 + arg2 -} -.fi -.RE -Note the usual absence of type declarations, which are instead -inferred by the translator. Because a return value type is required, -each function must contain at least one -.I return -statement. Functions may call others or themselves recursively, up to -a fixed nesting limit. This limit is defined by a macro in the -translated C code and is in the neighbourhood of 30. - -.SS EMBEDDED C -When in guru mode, the translator accepts embedded code in the -script. Such code is enclosed between -.IR %{ -and -.IR %} -markers, and is transcribed verbatim, without analysis, in some -sequence, into the generated C code. At the outermost level, this may -be useful to add -.IR #include -instructions, and any auxiliary definitions for use by other embedded -code. -.PP -The other place where embedded code is permitted is as a function body. -In this case, the script language body is replaced entirely by a piece -of C code enclosed again between -.IR %{ " and " %} -markers. -This C code may do anything reasonable and safe. There are a number -of undocumented but complex safety constraints on concurrency, -resource consumption, and runtime limits, so this is an advanced -technique. -.PP -The memory locations set aside for input and output values -are made available to it using a macro -.IR THIS . -Here are some examples: -.RS -.br -.nf -function add_one (val) %{ - THIS->__retvalue = THIS->val + 1; -%} -function add_one_str (val) %{ - strncpy (THIS->__retvalue, THIS->val, MAXSTRINGLEN); - strncat (THIS->__retvalue, "one", MAXSTRINGLEN); -%} -.fi -.RE -The function argument and return value types have to be inferred by -the translator from the call sites in order for this to work. The -user should examine C code generated for ordinary script-language -functions in order to write compatible embedded-C ones. - -.SS BUILT-INS -A set of builtin functions and probe aliases are provided by the -scripts installed under the -.IR /usr/share/systemtap/tapset -directory. - -.SH PROCESSING -The translator begins pass 1 by parsing the given input script, -and all scripts (files named -.IR *.stp ) -found in a tapset directory. The directories listed -with -.BR -I -are processed in sequence. For each directory, a number of subdirectories -are also searched. These subdirectories are derived from the selected -kernel version (the -.BR -R -option), -in order to allow more kernel-version-specific scripts to override less -specific ones. For example, for a kernel version -.IR 2.6.12-23.FC3 -the following patterns would be searched, in sequence: -.IR 2.6.12-23.FC3/*.stp , -.IR 2.6.12/*.stp , -.IR 2.6/*.stp , -and finally -.IR *.stp -Stopping the translator after pass 1 causes it to print the parse trees. - -.PP -In pass 2, the translator analyzes the input script to resolve symbols -and types. References to variables, functions, and probe aliases that -are unresolved internally are satisfied by searching through the -parsed tapset scripts. If any tapset script is selected because it -defines an unresolved symbol, then the entirety of that script is -added to the translator's resolution queue. This process iterates -until all symbols are resolved and a subset of tapset scripts is -selected. -.PP -Next, all probe point descriptions are validated -against the wide variety supported by the translator. Probe points that -refer to code locations ("synchronous probe points") require the -appropriate kernel debugging information to be installed. In the -associated probe handlers, target-side variables (whose names begin -with "$") are found and have their run-time locations decoded. -.PP -Finally, all variable, function, parameter, array, and index types are -inferred from context (literals and operators). Stopping the -translator after pass 2 causes it to list all the probes, functions, -and variables, along with all inferred types. Any inconsistent or -unresolved types cause an error. - -.PP -In pass 3, the translator writes C code that represents the actions -of all selected script files, and creates a -.IR Makefile -to build that into a kernel object. These files are placed into a -temporary directory. Stopping the translator at this point causes -it to print the contents of the C file. - -.PP -In pass 4, the translator invokes the Linux kernel build system to -create the actual kernel object file. This involves running -.IR make -in the temporary directory, and requires a kernel module build -system (headers, config and Makefiles) to be installed in the usual -spot -.IR /lib/modules/VERSION/build . -Stopping the translator after pass 4 is the last chance before -running the kernel object. This may be useful if you want to -archive the file. - -.PP -In pass 5, the translator invokes the systemtap auxiliary program -.I stpd -program for the given kernel object. This program arranges to load -the module then communicates with it, copying trace data from the -kernel into temporary files, until the user sends an interrupt signal. -Any run-time error encountered by the probe handlers, such as running -out of memory, division by zero, exceeding nesting or runtime limits, -results in an error condition that prevents further probes from -running. Finally, stpd unloads the module, and cleans up. - -.SH EXAMPLES -To trace entry and exit from a function, use a pair of probes: -.RS -.br -.nf -probe kernel.function("foo") { log ("enter") } -probe kernel.function("foo").return { log ("exit") } -.fi -.RE - -To list the probeable functions in the kernel, use -.RS -.br -.nf -stap -p2 -e 'probe kernel.function("*") {}' -.fi -.RE - -.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. Use of guru mode constructs such as embedded C can violate -these constraints, leading to kernel crash or data corruption. - -.SH FILES -.\" consider autoconf-substituting these directories -.TP -/tmp/stapXXXXXX -Temporary directory for systemtap files, including translated C code -and kernel object. -.TP -/usr/share/systemtap/tapset -The automatic tapset search directory, unless overridden by -the -.I SYSTEMTAP_TAPSET -environment variable. -.TP -/usr/share/systemtap/runtime -The runtime sources, unless overridden by the -.I SYSTEMTAP_RUNTIME -environment variable. -.TP -/lib/modules/VERSION/build -The location of kernel module building infrastructure. -.TP -/usr/lib/debug/lib/modules/VERSION -The location of kernel debugging information when packaged into the -.IR kernel-debuginfo -RPM. -.TP -/usr/libexec/systemtap/stpd -The auxiliary program supervising module loading, interaction, and -unloading. - -.SH SEE ALSO -.IR dtrace (1), -.IR dprobes (1), -.IR awk (1), -.IR sudo (8), -.IR elfutils (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: -.nh -.BR http://sources.redhat.com/systemtap/ . -.hy - -.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. Contact them -using the public mailing list: -.nh -.BR . -.hy - -.SH ACKNOWLEDGEMENTS -The script language design was inspired by Sun's -.IR dtrace . -The primary probing mechanism uses IBM's -.IR kprobes , -and -.IR relayfs -packages, which were improved and ported by IBM and Intel staff. -The elfutils library from Ulrich Drepper and Roland McGrath is used -to process dwarf debugging information. Many project members contributed -to the overall design and priorities of the system, including Will Cohen, -Jim Keniston, Vara Prasad, and Brad Chen. - diff --git a/stap.1.in b/stap.1.in new file mode 100644 index 00000000..dc421cdd --- /dev/null +++ b/stap.1.in @@ -0,0 +1,615 @@ +.TH STAP 1 @DATE@ "Red Hat" +.SH NAME +stap \- systemtap script translator/driver +.SH SYNOPSIS + +.br +.B stap +[ +.I OPTIONS +] +.I FILENAME +.br +.B stap +[ +.I OPTIONS +] +.B \- +.br +.B stap +[ +.I OPTIONS +] +.BI \-e " SCRIPT" + +.SH DESCRIPTION + +The +.IR stap +program is the front-end to the Systemtap tool. It accepts probing +instructions (written in a simple scripting language), translates +those instructions into C code, compiles this C code, and loads the +resulting kernel module into a running Linux kernel to perform the +requested system trace/probe functions. You can supply the script in +a named file, from standard input, or from the command line. +.PP +The language, which is described in a later section, is strictly typed, +declaration free, procedural, and 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 that are executed synchronously. It is +somewhat similar conceptually to "breakpoint command lists" in the +.IR gdb +debugger. +.PP +This manual corresponds to version @VERSION@. + +.SH OPTIONS +The systemtap translator supports the following options. Any other option +prints a list of supported options. +.\" undocumented for now: +.\" -t test mode +.\" -r RELEASE +.TP +.B \-v +Verbose mode. Produces more informative output. +.TP +.B \-k +Keep the temporary directory after all processing. This may be useful +in order to examine the generated C code, or to reuse the compiled +kernel object. +.TP +.B \-g +Guru mode. Enables parsing of unsafe expert-level constructs like +embedded C. +.TP +.BI \-p " NUM" +Stop after pass NUM. The passes are numbered 1-5: parse, elaborate, +translate, compile, run. See the +.B PROCESSING +section for details. +.TP +.BI \-I " DIR" +Add the given directory to the tapset search directory. See the +description of pass 2 for details. +.TP +.BI \-R " DIR" +Look for the systemtap runtime sources in the given directory. +.TP +.BI \-m " MODULE" +Use the given name for the generated kernel object module, instead +of a unique randomized name. +.TP +.BI \-o " FILE" +Send standard output to named file. + +.SH SCRIPT LANGUAGE + +The systemtap script language resembles +.IR awk . +There are two main outermost constructs: probes and functions. Within +these, statements and expressions use C-like operator syntax and +precedence. + +.SS GENERAL SYNTAX +Whitespace is ignored. Three forms of comments are supported: +.RS +.br +.BR # " ... shell style, to the end of line" +.br +.BR // " ... C++ style, to the end of line" +.br +.BR /* " ... C style ... " */ +.RE +Literals are either strings enclosed in double-quotes (soon supporting +the usual C escape codes with backslashes), or integers (in decimal, +hexadecimal, or octal, using the same notation as in C). All strings +are limited in length to some reasonable value (a few hundred bytes). +Integers are 64-bit signed quantities, although the parser also accepts +(and wraps around) values above positive 2**63. + +.SS VARIABLES +Identifiers for variables and functions are an alphanumeric sequence, +and may include "_" and "$" characters. They may not start with a +plain digit, as in C. Each variable is by default local to the probe +or function statement block within which it is mentioned, and therefore +its scope and lifetime is limited to a particular probe or function +invocation. +.\" XXX add statistics type here once it's supported +.PP +Scalar variables are implicitly typed as either string or integer. +Associative arrays also have a string or integer value, and a +a tuple of strings and/or integers serving as a key. +The translator performs +.I type inference +on all identifiers, including array indexes and function parameters. +Inconsistent type-related use of identifiers signals an error. +.PP +Variables may be declared global, so that they are shared amongst all +probes and live as long as the entire systemtap session. There is one +namespace for all global variables, regardless of which script file +they are found within. A global declaration may be written at the +outermost level anywhere, not within a block of code. The following +declaration marks "var1" and "var2" as global. The translator will +infer for each its value type, and if it is used as an array, its key +types. +.RS +.BR global " var1" , " var2" +.RE +.\" XXX add statistics type here once it's supported + +.SS STATEMENTS +Statements enable procedural control flow. They may occur within +functions and probe handlers. The total number of statements executed +in response to any single probe event is limited to some number +defined by a macro in the translated C code, and is in the +neighbourhood of 1000. +.TP +EXP +Execute the string- or integer-valued expression and throw away +the value. +.TP +.BR { " STMT1 STMT2 ... " } +Execute each statement in sequence in this block. Note that +separators or terminators are generally not necessary between statements. +.TP +.BR ; +Null statement, do nothing. It is useful as an optional separator between +statements to improve syntax-error detection and to handle certain +grammar ambiguities. +.TP +.BR if " (EXP) STMT1 [ " else " STMT2 ]" +Compare integer-valued EXP to zero. Execute the first (non-zero) +or second STMT (zero). +.TP +.BR while " (EXP) STMT" +While integer-valued EXP evaluates to non-zero, execute STMT. +.TP +.BR for " (EXP1; EXP2; EXP2) STMT" +Execute EXP2 as initialization. While EXP1 is non-zero, execute +STMT, then the iteration expression EXP1. +.TP +.BR foreach " (VAR " in " ARRAY) STMT" +Loop over each element of the named global array, assigning current +key to VAR. The array may not be modified within the statement. +.TP +.BR foreach " ([VAR1, VAR2, ...] " in " ARRAY) STMT" +Same as above, used when the array is indexed with a tuple of keys. +.TP +.BR break ", " continue +Exit or iterate the innermost nesting loop +.RB ( while " or " for " or " foreach ) +statement. +.TP +.BR return " EXP" +Return EXP value from enclosing function. A return value is mandatory, +since void functions are not supported. +.TP +.BR next +Return now from enclosing probe handler. + +.SS EXPRESSIONS +Systemtap supports a number of operators that have the same general syntax, +semantics, and precedence as in C and awk. Arithmetic is performed as per +C rules. Division by zero is detected and results in an error. +.TP +binary numeric operators +.B * / % + - >> << & ^ | && || +.TP +binary string operators +.B . +(string concatenation) +.TP +numeric assignment operators +.B = *= /= %= += -= >>= <<= &= ^= |= +.TP +string assignment operators +.B = .= +.TP +unary numeric operators +.B - ! ~ ++ -- +.TP +binary numeric or string comparison operators +.B < > <= >= == != +.TP +ternary operator +.RB cond " ? " exp1 " : " exp2 +.TP +grouping operator +.BR ( " exp " ) +.TP +function call +.RB "fn " ( "[ arg1, arg2, ... ]" ) + +.SS PROBES +The main construct in the scripting language identifies probes. +Probes associate abstract events with a statement block ("probe +handler") that is to be executed when those events occur. The +general syntax is as follows: +.RS +.br +.nh +.nf +.BR probe " PROBEPOINT [" , " PROBEPOINT] " { " [STMT ...] " } +.hy +.fi +.RE +.PP +Events are specified in a special syntax called "probe points". One +family refers to specific points in a kernel, which are identified by +module, source file, line number, function name, C label name, or some +combination of these. This kind of "synchronous" event is deemed to +occur when any processor executes an instruction matched by the +specification. Other families of probe points refer to "asynchronous" +events such as timers/counters rolling over, where there is no fixed +execution point that is related. Each probe point specification may +match multiple physical locations, all of which are then probed. A +probe declaration may also contain several comma-separated +specifications, all of which are probed. +.PP +Here is a list of probe point families currently supported. The +.B .function +variant places a probe near the beginning of the named function, so that +parameters are available as context variables. The +.B .return +variant places a probe at the moment of return from the named function, so +the return value is available as the "$retvalue" context variable. +The +.B .statement +variant places a probe at the exact spot, exposing those local variables +that are visible there. +.RS +.nf +.br +kernel.function(PATTERN) +.br +kernel.function(PATTERN).return +.br +module(MPATTERN).function(PATTERN) +.br +module(MPATTERN).function(PATTERN).return +.br +kernel.statement(PATTERN) +.br +module(MPATTERN).statement(PATTERN) +.fi +.RE +.PP +In the above list, MPATTERN stands for a string literal that aims to +identify the loaded kernel module of interest. It may include "*" and +"?" wildcards. PATTERN stands for a string literal that aims to +identify a point in the program. It is made up of three parts. The +first part is the name of a function, as would appear in the +.I nm +program's output. This part may use the "*" and "?" wildcarding +operators to match multiple names. The second part is optional, and +begins with the "@" character. It is followed by a source file name +wildcard pattern, such as +.IR mm/slab* . +Finally, the third part is optional if the file name part was given, +and identifies the line number in the source file, preceded by a ":". +As an alternative, PATTERN may be a numeric constant, indicating an +(module-relative or kernel-absolute) address. +.PP +Here are some example probe points: +.TP +kernel.function("*init*"), kernel.function("*exit*") +refers to all kernel functions with "init" or "exit" in the name. +.TP +kernel.function("*@kernel/sched.c:240") +refers to any functions within the "kernel/sched.c" file that span +line 240. +.TP +module("usb*").function("*sync*").return +refers to the moment of return from all functions with "sync" in the +name in any of the USB drivers. +.TP +kernel.statement(0xc0044852) +refers to the first byte of the statement whose compiled instructions +include the given address in the kernel. + +.PP +When any matching event occurs, the probe handler is run within that +context. For events that are defined by execution of specific parts +of code, this context may include variables defined in the source code +at that spot. These "target variables" are presented to the script as +variables whose names are prefixed with "$". They may be read/written +only if the kernel's compiler preserved them despite optimization. +This is the same constraint that a debugger user faces when working +with optimized code. Asynchronous probes have very little context. +.PP +In addition, "probe aliases" may be defined. Probe aliases look +similar to probe definitions, but instead of activating a probe at the +given point, it defines a new probe point name to alias an existing +one. This is identified by the "=" assignment operator. In addition, +the probe handler defined with an alias is implicitly added as a +prologue to any probe that refers to the alias. For example: +.RS +.nf +.nh +probe syscall("read") = kernel.function("sys_read") { + fildes = $fd +} +.hy +.fi +.RE +defines a new probe point +.nh +.IR syscall("read") , +.hy +which expands to +.nh +.IR kernel.function("sys_read") , +.hy +with the given assignment as a prologue. Another probe definition +may use the alias like this: +.RS +.nf +probe syscall("read") { + printk ("reading fd=" . string (fildes)) +} +.fi +.RE + +.SS FUNCTIONS +Systemtap scripts may define subroutines to factor out common work. +Functions take any number of scalar (integer or string) arguments, and +must return a single scalar (integer or string). An example function +declaration looks like this: +.RS +.nf +function thisfn (arg1, arg2) { + return arg1 + arg2 +} +.fi +.RE +Note the usual absence of type declarations, which are instead +inferred by the translator. Because a return value type is required, +each function must contain at least one +.I return +statement. Functions may call others or themselves recursively, up to +a fixed nesting limit. This limit is defined by a macro in the +translated C code and is in the neighbourhood of 30. + +.SS EMBEDDED C +When in guru mode, the translator accepts embedded code in the +script. Such code is enclosed between +.IR %{ +and +.IR %} +markers, and is transcribed verbatim, without analysis, in some +sequence, into the generated C code. At the outermost level, this may +be useful to add +.IR #include +instructions, and any auxiliary definitions for use by other embedded +code. +.PP +The other place where embedded code is permitted is as a function body. +In this case, the script language body is replaced entirely by a piece +of C code enclosed again between +.IR %{ " and " %} +markers. +This C code may do anything reasonable and safe. There are a number +of undocumented but complex safety constraints on concurrency, +resource consumption, and runtime limits, so this is an advanced +technique. +.PP +The memory locations set aside for input and output values +are made available to it using a macro +.IR THIS . +Here are some examples: +.RS +.br +.nf +function add_one (val) %{ + THIS->__retvalue = THIS->val + 1; +%} +function add_one_str (val) %{ + strncpy (THIS->__retvalue, THIS->val, MAXSTRINGLEN); + strncat (THIS->__retvalue, "one", MAXSTRINGLEN); +%} +.fi +.RE +The function argument and return value types have to be inferred by +the translator from the call sites in order for this to work. The +user should examine C code generated for ordinary script-language +functions in order to write compatible embedded-C ones. + +.SS BUILT-INS +A set of builtin functions and probe aliases are provided by the +scripts installed under the +.nh +.IR /usr/share/systemtap/tapset +.hy +directory. + +.SH PROCESSING +The translator begins pass 1 by parsing the given input script, +and all scripts (files named +.IR *.stp ) +found in a tapset directory. The directories listed +with +.BR -I +are processed in sequence. For each directory, a number of subdirectories +are also searched. These subdirectories are derived from the selected +kernel version (the +.BR -R +option), +in order to allow more kernel-version-specific scripts to override less +specific ones. For example, for a kernel version +.IR 2.6.12-23.FC3 +the following patterns would be searched, in sequence: +.IR 2.6.12-23.FC3/*.stp , +.IR 2.6.12/*.stp , +.IR 2.6/*.stp , +and finally +.IR *.stp +Stopping the translator after pass 1 causes it to print the parse trees. + +.PP +In pass 2, the translator analyzes the input script to resolve symbols +and types. References to variables, functions, and probe aliases that +are unresolved internally are satisfied by searching through the +parsed tapset scripts. If any tapset script is selected because it +defines an unresolved symbol, then the entirety of that script is +added to the translator's resolution queue. This process iterates +until all symbols are resolved and a subset of tapset scripts is +selected. +.PP +Next, all probe point descriptions are validated +against the wide variety supported by the translator. Probe points that +refer to code locations ("synchronous probe points") require the +appropriate kernel debugging information to be installed. In the +associated probe handlers, target-side variables (whose names begin +with "$") are found and have their run-time locations decoded. +.PP +Finally, all variable, function, parameter, array, and index types are +inferred from context (literals and operators). Stopping the +translator after pass 2 causes it to list all the probes, functions, +and variables, along with all inferred types. Any inconsistent or +unresolved types cause an error. + +.PP +In pass 3, the translator writes C code that represents the actions +of all selected script files, and creates a +.IR Makefile +to build that into a kernel object. These files are placed into a +temporary directory. Stopping the translator at this point causes +it to print the contents of the C file. + +.PP +In pass 4, the translator invokes the Linux kernel build system to +create the actual kernel object file. This involves running +.IR make +in the temporary directory, and requires a kernel module build +system (headers, config and Makefiles) to be installed in the usual +spot +.IR /lib/modules/VERSION/build . +Stopping the translator after pass 4 is the last chance before +running the kernel object. This may be useful if you want to +archive the file. + +.PP +In pass 5, the translator invokes the systemtap auxiliary program +.I stpd +program for the given kernel object. This program arranges to load +the module then communicates with it, copying trace data from the +kernel into temporary files, until the user sends an interrupt signal. +Any run-time error encountered by the probe handlers, such as running +out of memory, division by zero, exceeding nesting or runtime limits, +results in an error condition that prevents further probes from +running. Finally, stpd unloads the module, and cleans up. + +.SH EXAMPLES +To trace entry and exit from a function, use a pair of probes: +.RS +.br +.nf +probe kernel.function("foo") { log ("enter") } +probe kernel.function("foo").return { log ("exit") } +.fi +.RE + +To list the probeable functions in the kernel, use +.RS +.br +.nf +stap -p2 -e 'probe kernel.function("*") {}' +.fi +.RE + +.SH SAFETY AND SECURITY +Systemtap is an administrative tool. 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. Use of guru mode constructs such as embedded C can violate +these constraints, leading to kernel crash or data corruption. + +.SH FILES +.\" consider autoconf-substituting these directories +.TP +/tmp/stapXXXXXX +Temporary directory for systemtap files, including translated C code +and kernel object. +.TP +/usr/share/systemtap/tapset +The automatic tapset search directory, unless overridden by +the +.I SYSTEMTAP_TAPSET +environment variable. +.TP +/usr/share/systemtap/runtime +The runtime sources, unless overridden by the +.I SYSTEMTAP_RUNTIME +environment variable. +.TP +/lib/modules/VERSION/build +The location of kernel module building infrastructure. +.TP +/usr/lib/debug/lib/modules/VERSION +The location of kernel debugging information when packaged into the +.IR kernel-debuginfo +RPM. +.TP +/usr/libexec/systemtap/stpd +The auxiliary program supervising module loading, interaction, and +unloading. + +.SH SEE ALSO +.IR dtrace (1), +.IR dprobes (1), +.IR awk (1), +.IR sudo (8), +.IR elfutils (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: +.nh +.BR http://sources.redhat.com/systemtap/ . +.hy + +.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. Contact them +using the public mailing list: +.nh +.BR . +.hy + +.SH ACKNOWLEDGEMENTS +The script language design was inspired by Sun's +.IR dtrace . +The primary probing mechanism uses IBM's +.IR kprobes , +and +.IR relayfs +packages, which were improved and ported by IBM and Intel staff. +The elfutils library from Ulrich Drepper and Roland McGrath is used +to process dwarf debugging information. Many project members contributed +to the overall design and priorities of the system, including Will Cohen, +Jim Keniston, Vara Prasad, and Brad Chen. + -- cgit