From d9e3e39eef31587ea762f4b017b46495f7a0b70f Mon Sep 17 00:00:00 2001 From: William Cohen Date: Tue, 24 Mar 2009 11:16:38 -0400 Subject: Move tapset documentation manpages from man3stap to man3. --- doc/SystemTap_Tapset_Reference/Makefile.am | 6 +++--- doc/SystemTap_Tapset_Reference/Makefile.in | 6 +++--- systemtap.spec | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/SystemTap_Tapset_Reference/Makefile.am b/doc/SystemTap_Tapset_Reference/Makefile.am index 68dfd971..b21bfcd6 100644 --- a/doc/SystemTap_Tapset_Reference/Makefile.am +++ b/doc/SystemTap_Tapset_Reference/Makefile.am @@ -2,7 +2,7 @@ ## process this file with automake to produce Makefile.in DOC_INSTALL_DIR = $(DESTDIR)$(datadir)/doc/systemtap -MAN_INSTALL_DIR = $(DESTDIR)$(mandir)/man3stap +MAN_INSTALL_DIR = $(DESTDIR)$(mandir)/man3 HTML_INSTALL_DIR = $(DESTDIR)$(datadir)/doc/systemtap/tapsets @@ -36,7 +36,7 @@ tapsets.pdf: tapsets.xml xmlto pdf tapsets.xml stamp-mandocs: tapsets.xml - xmlto man -o man3stap tapsets.xml + xmlto man -o man3 tapsets.xml touch stamp-mandocs #FIXME need to figure out where to install things appropriately @@ -45,7 +45,7 @@ install-data-hook: $(MKDIR_P) $(DOC_INSTALL_DIR) $(INSTALL_DATA) tapsets.pdf $(DOC_INSTALL_DIR) $(MKDIR_P) $(MAN_INSTALL_DIR) - $(INSTALL_DATA) man3stap/* $(MAN_INSTALL_DIR) + $(INSTALL_DATA) man3/* $(MAN_INSTALL_DIR) $(MKDIR_P) $(HTML_INSTALL_DIR) $(INSTALL_DATA) tapsets/* $(HTML_INSTALL_DIR) endif diff --git a/doc/SystemTap_Tapset_Reference/Makefile.in b/doc/SystemTap_Tapset_Reference/Makefile.in index 2f8a5294..6fe6bab2 100644 --- a/doc/SystemTap_Tapset_Reference/Makefile.in +++ b/doc/SystemTap_Tapset_Reference/Makefile.in @@ -170,7 +170,7 @@ top_build_prefix = @top_build_prefix@ top_builddir = @top_builddir@ top_srcdir = @top_srcdir@ DOC_INSTALL_DIR = $(DESTDIR)$(datadir)/doc/systemtap -MAN_INSTALL_DIR = $(DESTDIR)$(mandir)/man3stap +MAN_INSTALL_DIR = $(DESTDIR)$(mandir)/man3 HTML_INSTALL_DIR = $(DESTDIR)$(datadir)/doc/systemtap/tapsets SRCTREE = $(abs_top_srcdir)/ DOCPROC = $(abs_builddir)/docproc @@ -430,7 +430,7 @@ uninstall-am: @BUILD_REFDOCS_TRUE@ xmlto pdf tapsets.xml @BUILD_REFDOCS_TRUE@stamp-mandocs: tapsets.xml -@BUILD_REFDOCS_TRUE@ xmlto man -o man3stap tapsets.xml +@BUILD_REFDOCS_TRUE@ xmlto man -o man3 tapsets.xml @BUILD_REFDOCS_TRUE@ touch stamp-mandocs #FIXME need to figure out where to install things appropriately @@ -439,7 +439,7 @@ uninstall-am: @BUILD_REFDOCS_TRUE@ $(MKDIR_P) $(DOC_INSTALL_DIR) @BUILD_REFDOCS_TRUE@ $(INSTALL_DATA) tapsets.pdf $(DOC_INSTALL_DIR) @BUILD_REFDOCS_TRUE@ $(MKDIR_P) $(MAN_INSTALL_DIR) -@BUILD_REFDOCS_TRUE@ $(INSTALL_DATA) man3stap/* $(MAN_INSTALL_DIR) +@BUILD_REFDOCS_TRUE@ $(INSTALL_DATA) man3/* $(MAN_INSTALL_DIR) @BUILD_REFDOCS_TRUE@ $(MKDIR_P) $(HTML_INSTALL_DIR) @BUILD_REFDOCS_TRUE@ $(INSTALL_DATA) tapsets/* $(HTML_INSTALL_DIR) # Tell versions [3.59,3.63) of GNU make to not export all variables. diff --git a/systemtap.spec b/systemtap.spec index 540a9d93..cbf36662 100644 --- a/systemtap.spec +++ b/systemtap.spec @@ -245,7 +245,7 @@ exit 0 %if %{with_docs} %doc docs.installed/*.pdf %doc docs.installed/tapsets -%{_mandir}/man3stap/* +%{_mandir}/man3/* %endif %{_bindir}/stap -- cgit From e97c0b2970dfd8c23163d2712557a30401c75282 Mon Sep 17 00:00:00 2001 From: Will Cohen Date: Tue, 24 Mar 2009 12:01:52 -0400 Subject: Move man pages from man5 to man3 (3stap). --- Makefile.am | 10 +- Makefile.in | 137 +-- configure | 34 +- configure.ac | 2 +- doc/Makefile.in | 1 - doc/SystemTap_Tapset_Reference/Makefile.in | 1 - man/stapprobes.iosched.3stap.in | 100 +++ man/stapprobes.iosched.5.in | 100 --- man/stapprobes.netdev.3stap.in | 77 ++ man/stapprobes.netdev.5.in | 77 -- man/stapprobes.nfs.3stap.in | 1236 ++++++++++++++++++++++++++++ man/stapprobes.nfs.5.in | 1236 ---------------------------- man/stapprobes.nfsd.3stap.in | 513 ++++++++++++ man/stapprobes.nfsd.5.in | 513 ------------ man/stapprobes.pagefault.3stap.in | 40 + man/stapprobes.pagefault.5.in | 40 - man/stapprobes.process.3stap.in | 106 +++ man/stapprobes.process.5.in | 106 --- man/stapprobes.rpc.3stap.in | 583 +++++++++++++ man/stapprobes.rpc.5.in | 583 ------------- man/stapprobes.scsi.3stap.in | 151 ++++ man/stapprobes.scsi.5.in | 151 ---- man/stapprobes.signal.3stap.in | 509 ++++++++++++ man/stapprobes.signal.5.in | 509 ------------ man/stapprobes.socket.3stap.in | 485 +++++++++++ man/stapprobes.socket.5.in | 485 ----------- man/stapprobes.tcp.3stap.in | 102 +++ man/stapprobes.tcp.5.in | 102 --- man/stapprobes.udp.3stap.in | 102 +++ man/stapprobes.udp.5.in | 102 --- stap-server.8.in | 8 +- stap.1.in | 14 +- stapex.3stap.in | 126 +++ stapex.5.in | 126 --- stapfuncs.3stap.in | 668 +++++++++++++++ stapfuncs.5.in | 668 --------------- stapprobes.3stap.in | 676 +++++++++++++++ stapprobes.5.in | 676 --------------- staprun.8.in | 8 +- stapvars.3stap.in | 51 ++ stapvars.5.in | 51 -- systemtap.spec | 3 +- 42 files changed, 5637 insertions(+), 5631 deletions(-) create mode 100644 man/stapprobes.iosched.3stap.in delete mode 100644 man/stapprobes.iosched.5.in create mode 100644 man/stapprobes.netdev.3stap.in delete mode 100644 man/stapprobes.netdev.5.in create mode 100644 man/stapprobes.nfs.3stap.in delete mode 100644 man/stapprobes.nfs.5.in create mode 100644 man/stapprobes.nfsd.3stap.in delete mode 100644 man/stapprobes.nfsd.5.in create mode 100644 man/stapprobes.pagefault.3stap.in delete mode 100644 man/stapprobes.pagefault.5.in create mode 100644 man/stapprobes.process.3stap.in delete mode 100644 man/stapprobes.process.5.in create mode 100644 man/stapprobes.rpc.3stap.in delete mode 100644 man/stapprobes.rpc.5.in create mode 100644 man/stapprobes.scsi.3stap.in delete mode 100644 man/stapprobes.scsi.5.in create mode 100644 man/stapprobes.signal.3stap.in delete mode 100644 man/stapprobes.signal.5.in create mode 100644 man/stapprobes.socket.3stap.in delete mode 100644 man/stapprobes.socket.5.in create mode 100644 man/stapprobes.tcp.3stap.in delete mode 100644 man/stapprobes.tcp.5.in create mode 100644 man/stapprobes.udp.3stap.in delete mode 100644 man/stapprobes.udp.5.in create mode 100644 stapex.3stap.in delete mode 100644 stapex.5.in create mode 100644 stapfuncs.3stap.in delete mode 100644 stapfuncs.5.in create mode 100644 stapprobes.3stap.in delete mode 100644 stapprobes.5.in create mode 100644 stapvars.3stap.in delete mode 100644 stapvars.5.in diff --git a/Makefile.am b/Makefile.am index 9681381d..580c4178 100644 --- a/Makefile.am +++ b/Makefile.am @@ -12,7 +12,15 @@ AM_CPPFLAGS = -DBINDIR='"$(bindir)"' -DPKGDATADIR='"${pkgdatadir}"' -DPKGLIBDIR= AM_CFLAGS = -D_GNU_SOURCE -fexceptions -Wall -Werror -Wunused -Wformat=2 -W AM_CXXFLAGS = -Wall -Werror -man_MANS = stap.1 stapprobes.5 stapfuncs.5 stapvars.5 stapex.5 staprun.8 man/stapprobes.iosched.5 man/stapprobes.netdev.5 man/stapprobes.nfs.5 man/stapprobes.nfsd.5 man/stapprobes.pagefault.5 man/stapprobes.process.5 man/stapprobes.rpc.5 man/stapprobes.scsi.5 man/stapprobes.signal.5 man/stapprobes.socket.5 man/stapprobes.tcp.5 man/stapprobes.udp.5 +man_MANS = stap.1 \ +stapprobes.3stap stapfuncs.3stap stapvars.3stap stapex.3stap \ +staprun.8 \ +man/stapprobes.iosched.3stap man/stapprobes.netdev.3stap \ +man/stapprobes.nfs.3stap man/stapprobes.nfsd.3stap \ +man/stapprobes.pagefault.3stap man/stapprobes.process.3stap \ +man/stapprobes.rpc.3stap man/stapprobes.scsi.3stap \ +man/stapprobes.signal.3stap man/stapprobes.socket.3stap \ +man/stapprobes.tcp.3stap man/stapprobes.udp.3stap # see also configure.ac bin_PROGRAMS = stap staprun diff --git a/Makefile.in b/Makefile.in index 12a5e6ea..35bcd486 100644 --- a/Makefile.in +++ b/Makefile.in @@ -56,21 +56,21 @@ subdir = . DIST_COMMON = INSTALL NEWS README AUTHORS $(srcdir)/Makefile.in \ $(srcdir)/Makefile.am $(top_srcdir)/configure \ $(am__configure_deps) $(srcdir)/config.in $(srcdir)/stap.1.in \ - $(srcdir)/stapprobes.5.in $(srcdir)/stapfuncs.5.in \ - $(srcdir)/stapvars.5.in $(srcdir)/stapex.5.in \ + $(srcdir)/stapprobes.3stap.in $(srcdir)/stapfuncs.3stap.in \ + $(srcdir)/stapvars.3stap.in $(srcdir)/stapex.3stap.in \ $(srcdir)/staprun.8.in $(srcdir)/stap-server.8.in \ - $(top_srcdir)/man/stapprobes.iosched.5.in \ - $(top_srcdir)/man/stapprobes.netdev.5.in \ - $(top_srcdir)/man/stapprobes.nfs.5.in \ - $(top_srcdir)/man/stapprobes.nfsd.5.in \ - $(top_srcdir)/man/stapprobes.pagefault.5.in \ - $(top_srcdir)/man/stapprobes.process.5.in \ - $(top_srcdir)/man/stapprobes.rpc.5.in \ - $(top_srcdir)/man/stapprobes.scsi.5.in \ - $(top_srcdir)/man/stapprobes.signal.5.in \ - $(top_srcdir)/man/stapprobes.socket.5.in \ - $(top_srcdir)/man/stapprobes.tcp.5.in \ - $(top_srcdir)/man/stapprobes.udp.5.in \ + $(top_srcdir)/man/stapprobes.iosched.3stap.in \ + $(top_srcdir)/man/stapprobes.netdev.3stap.in \ + $(top_srcdir)/man/stapprobes.nfs.3stap.in \ + $(top_srcdir)/man/stapprobes.nfsd.3stap.in \ + $(top_srcdir)/man/stapprobes.pagefault.3stap.in \ + $(top_srcdir)/man/stapprobes.process.3stap.in \ + $(top_srcdir)/man/stapprobes.rpc.3stap.in \ + $(top_srcdir)/man/stapprobes.scsi.3stap.in \ + $(top_srcdir)/man/stapprobes.signal.3stap.in \ + $(top_srcdir)/man/stapprobes.socket.3stap.in \ + $(top_srcdir)/man/stapprobes.tcp.3stap.in \ + $(top_srcdir)/man/stapprobes.udp.3stap.in \ $(top_srcdir)/initscript/systemtap.in $(srcdir)/run-stap.in \ depcomp $(oldinclude_HEADERS) ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 @@ -81,19 +81,20 @@ am__CONFIG_DISTCLEAN_FILES = config.status config.cache config.log \ configure.lineno config.status.lineno mkinstalldirs = $(install_sh) -d CONFIG_HEADER = config.h -CONFIG_CLEAN_FILES = stap.1 stapprobes.5 stapfuncs.5 stapvars.5 \ - stapex.5 staprun.8 stap-server.8 man/stapprobes.iosched.5 \ - man/stapprobes.netdev.5 man/stapprobes.nfs.5 \ - man/stapprobes.nfsd.5 man/stapprobes.pagefault.5 \ - man/stapprobes.process.5 man/stapprobes.rpc.5 \ - man/stapprobes.scsi.5 man/stapprobes.signal.5 \ - man/stapprobes.socket.5 man/stapprobes.tcp.5 \ - man/stapprobes.udp.5 initscript/systemtap run-stap +CONFIG_CLEAN_FILES = stap.1 stapprobes.3stap stapfuncs.3stap \ + stapvars.3stap stapex.3stap staprun.8 stap-server.8 \ + man/stapprobes.iosched.3stap man/stapprobes.netdev.3stap \ + man/stapprobes.nfs.3stap man/stapprobes.nfsd.3stap \ + man/stapprobes.pagefault.3stap man/stapprobes.process.3stap \ + man/stapprobes.rpc.3stap man/stapprobes.scsi.3stap \ + man/stapprobes.signal.3stap man/stapprobes.socket.3stap \ + man/stapprobes.tcp.3stap man/stapprobes.udp.3stap \ + initscript/systemtap run-stap @BUILD_SERVER_TRUE@am__EXEEXT_1 = stap-client-connect$(EXEEXT) \ @BUILD_SERVER_TRUE@ stap-server-connect$(EXEEXT) am__installdirs = "$(DESTDIR)$(bindir)" "$(DESTDIR)$(pkglibexecdir)" \ "$(DESTDIR)$(bindir)" "$(DESTDIR)$(man1dir)" \ - "$(DESTDIR)$(man5dir)" "$(DESTDIR)$(man8dir)" \ + "$(DESTDIR)$(man3dir)" "$(DESTDIR)$(man8dir)" \ "$(DESTDIR)$(oldincludedir)" binPROGRAMS_INSTALL = $(INSTALL_PROGRAM) pkglibexecPROGRAMS_INSTALL = $(INSTALL_PROGRAM) @@ -164,7 +165,7 @@ RECURSIVE_TARGETS = all-recursive check-recursive dvi-recursive \ installcheck-recursive installdirs-recursive pdf-recursive \ ps-recursive uninstall-recursive man1dir = $(mandir)/man1 -man5dir = $(mandir)/man5 +man3dir = $(mandir)/man3 man8dir = $(mandir)/man8 NROFF = nroff MANS = $(man_MANS) @@ -288,7 +289,6 @@ staplog_CPPFLAGS = @staplog_CPPFLAGS@ subdirs = @subdirs@ sysconfdir = @sysconfdir@ target_alias = @target_alias@ -top_build_prefix = @top_build_prefix@ top_builddir = @top_builddir@ top_srcdir = @top_srcdir@ @@ -298,13 +298,14 @@ pkglibexecdir = ${libexecdir}/${PACKAGE} AM_CPPFLAGS = -DBINDIR='"$(bindir)"' -DPKGDATADIR='"${pkgdatadir}"' -DPKGLIBDIR='"$(pkglibexecdir)"' AM_CFLAGS = -D_GNU_SOURCE -fexceptions -Wall -Werror -Wunused -Wformat=2 -W AM_CXXFLAGS = -Wall -Werror -man_MANS = stap.1 stapprobes.5 stapfuncs.5 stapvars.5 stapex.5 \ - staprun.8 man/stapprobes.iosched.5 man/stapprobes.netdev.5 \ - man/stapprobes.nfs.5 man/stapprobes.nfsd.5 \ - man/stapprobes.pagefault.5 man/stapprobes.process.5 \ - man/stapprobes.rpc.5 man/stapprobes.scsi.5 \ - man/stapprobes.signal.5 man/stapprobes.socket.5 \ - man/stapprobes.tcp.5 man/stapprobes.udp.5 $(am__append_1) +man_MANS = stap.1 stapprobes.3stap stapfuncs.3stap stapvars.3stap \ + stapex.3stap staprun.8 man/stapprobes.iosched.3stap \ + man/stapprobes.netdev.3stap man/stapprobes.nfs.3stap \ + man/stapprobes.nfsd.3stap man/stapprobes.pagefault.3stap \ + man/stapprobes.process.3stap man/stapprobes.rpc.3stap \ + man/stapprobes.scsi.3stap man/stapprobes.signal.3stap \ + man/stapprobes.socket.3stap man/stapprobes.tcp.3stap \ + man/stapprobes.udp.3stap $(am__append_1) bin_SCRIPTS = stap-report $(am__append_3) dtrace oldinclude_HEADERS = includes/sys/sdt.h stap_SOURCES = main.cxx \ @@ -433,41 +434,41 @@ distclean-hdr: -rm -f config.h stamp-h1 stap.1: $(top_builddir)/config.status $(srcdir)/stap.1.in cd $(top_builddir) && $(SHELL) ./config.status $@ -stapprobes.5: $(top_builddir)/config.status $(srcdir)/stapprobes.5.in +stapprobes.3stap: $(top_builddir)/config.status $(srcdir)/stapprobes.3stap.in cd $(top_builddir) && $(SHELL) ./config.status $@ -stapfuncs.5: $(top_builddir)/config.status $(srcdir)/stapfuncs.5.in +stapfuncs.3stap: $(top_builddir)/config.status $(srcdir)/stapfuncs.3stap.in cd $(top_builddir) && $(SHELL) ./config.status $@ -stapvars.5: $(top_builddir)/config.status $(srcdir)/stapvars.5.in +stapvars.3stap: $(top_builddir)/config.status $(srcdir)/stapvars.3stap.in cd $(top_builddir) && $(SHELL) ./config.status $@ -stapex.5: $(top_builddir)/config.status $(srcdir)/stapex.5.in +stapex.3stap: $(top_builddir)/config.status $(srcdir)/stapex.3stap.in cd $(top_builddir) && $(SHELL) ./config.status $@ staprun.8: $(top_builddir)/config.status $(srcdir)/staprun.8.in cd $(top_builddir) && $(SHELL) ./config.status $@ stap-server.8: $(top_builddir)/config.status $(srcdir)/stap-server.8.in cd $(top_builddir) && $(SHELL) ./config.status $@ -man/stapprobes.iosched.5: $(top_builddir)/config.status $(top_srcdir)/man/stapprobes.iosched.5.in +man/stapprobes.iosched.3stap: $(top_builddir)/config.status $(top_srcdir)/man/stapprobes.iosched.3stap.in cd $(top_builddir) && $(SHELL) ./config.status $@ -man/stapprobes.netdev.5: $(top_builddir)/config.status $(top_srcdir)/man/stapprobes.netdev.5.in +man/stapprobes.netdev.3stap: $(top_builddir)/config.status $(top_srcdir)/man/stapprobes.netdev.3stap.in cd $(top_builddir) && $(SHELL) ./config.status $@ -man/stapprobes.nfs.5: $(top_builddir)/config.status $(top_srcdir)/man/stapprobes.nfs.5.in +man/stapprobes.nfs.3stap: $(top_builddir)/config.status $(top_srcdir)/man/stapprobes.nfs.3stap.in cd $(top_builddir) && $(SHELL) ./config.status $@ -man/stapprobes.nfsd.5: $(top_builddir)/config.status $(top_srcdir)/man/stapprobes.nfsd.5.in +man/stapprobes.nfsd.3stap: $(top_builddir)/config.status $(top_srcdir)/man/stapprobes.nfsd.3stap.in cd $(top_builddir) && $(SHELL) ./config.status $@ -man/stapprobes.pagefault.5: $(top_builddir)/config.status $(top_srcdir)/man/stapprobes.pagefault.5.in +man/stapprobes.pagefault.3stap: $(top_builddir)/config.status $(top_srcdir)/man/stapprobes.pagefault.3stap.in cd $(top_builddir) && $(SHELL) ./config.status $@ -man/stapprobes.process.5: $(top_builddir)/config.status $(top_srcdir)/man/stapprobes.process.5.in +man/stapprobes.process.3stap: $(top_builddir)/config.status $(top_srcdir)/man/stapprobes.process.3stap.in cd $(top_builddir) && $(SHELL) ./config.status $@ -man/stapprobes.rpc.5: $(top_builddir)/config.status $(top_srcdir)/man/stapprobes.rpc.5.in +man/stapprobes.rpc.3stap: $(top_builddir)/config.status $(top_srcdir)/man/stapprobes.rpc.3stap.in cd $(top_builddir) && $(SHELL) ./config.status $@ -man/stapprobes.scsi.5: $(top_builddir)/config.status $(top_srcdir)/man/stapprobes.scsi.5.in +man/stapprobes.scsi.3stap: $(top_builddir)/config.status $(top_srcdir)/man/stapprobes.scsi.3stap.in cd $(top_builddir) && $(SHELL) ./config.status $@ -man/stapprobes.signal.5: $(top_builddir)/config.status $(top_srcdir)/man/stapprobes.signal.5.in +man/stapprobes.signal.3stap: $(top_builddir)/config.status $(top_srcdir)/man/stapprobes.signal.3stap.in cd $(top_builddir) && $(SHELL) ./config.status $@ -man/stapprobes.socket.5: $(top_builddir)/config.status $(top_srcdir)/man/stapprobes.socket.5.in +man/stapprobes.socket.3stap: $(top_builddir)/config.status $(top_srcdir)/man/stapprobes.socket.3stap.in cd $(top_builddir) && $(SHELL) ./config.status $@ -man/stapprobes.tcp.5: $(top_builddir)/config.status $(top_srcdir)/man/stapprobes.tcp.5.in +man/stapprobes.tcp.3stap: $(top_builddir)/config.status $(top_srcdir)/man/stapprobes.tcp.3stap.in cd $(top_builddir) && $(SHELL) ./config.status $@ -man/stapprobes.udp.5: $(top_builddir)/config.status $(top_srcdir)/man/stapprobes.udp.5.in +man/stapprobes.udp.3stap: $(top_builddir)/config.status $(top_srcdir)/man/stapprobes.udp.3stap.in cd $(top_builddir) && $(SHELL) ./config.status $@ initscript/systemtap: $(top_builddir)/config.status $(top_srcdir)/initscript/systemtap.in cd $(top_builddir) && $(SHELL) ./config.status $@ @@ -1059,14 +1060,14 @@ uninstall-man1: echo " rm -f '$(DESTDIR)$(man1dir)/$$inst'"; \ rm -f "$(DESTDIR)$(man1dir)/$$inst"; \ done -install-man5: $(man5_MANS) $(man_MANS) +install-man3: $(man3_MANS) $(man_MANS) @$(NORMAL_INSTALL) - test -z "$(man5dir)" || $(MKDIR_P) "$(DESTDIR)$(man5dir)" - @list='$(man5_MANS) $(dist_man5_MANS) $(nodist_man5_MANS)'; \ + test -z "$(man3dir)" || $(MKDIR_P) "$(DESTDIR)$(man3dir)" + @list='$(man3_MANS) $(dist_man3_MANS) $(nodist_man3_MANS)'; \ l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ for i in $$l2; do \ case "$$i" in \ - *.5*) list="$$list $$i" ;; \ + *.3*) list="$$list $$i" ;; \ esac; \ done; \ for i in $$list; do \ @@ -1074,35 +1075,35 @@ install-man5: $(man5_MANS) $(man_MANS) else file=$$i; fi; \ ext=`echo $$i | sed -e 's/^.*\\.//'`; \ case "$$ext" in \ - 5*) ;; \ - *) ext='5' ;; \ + 3*) ;; \ + *) ext='3' ;; \ 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)$(man5dir)/$$inst'"; \ - $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man5dir)/$$inst"; \ + echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man3dir)/$$inst'"; \ + $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man3dir)/$$inst"; \ done -uninstall-man5: +uninstall-man3: @$(NORMAL_UNINSTALL) - @list='$(man5_MANS) $(dist_man5_MANS) $(nodist_man5_MANS)'; \ + @list='$(man3_MANS) $(dist_man3_MANS) $(nodist_man3_MANS)'; \ l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ for i in $$l2; do \ case "$$i" in \ - *.5*) list="$$list $$i" ;; \ + *.3*) list="$$list $$i" ;; \ esac; \ done; \ for i in $$list; do \ ext=`echo $$i | sed -e 's/^.*\\.//'`; \ case "$$ext" in \ - 5*) ;; \ - *) ext='5' ;; \ + 3*) ;; \ + *) ext='3' ;; \ 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)$(man5dir)/$$inst'"; \ - rm -f "$(DESTDIR)$(man5dir)/$$inst"; \ + echo " rm -f '$(DESTDIR)$(man3dir)/$$inst'"; \ + rm -f "$(DESTDIR)$(man3dir)/$$inst"; \ done install-man8: $(man8_MANS) $(man_MANS) @$(NORMAL_INSTALL) @@ -1304,7 +1305,7 @@ all-am: Makefile $(PROGRAMS) $(SCRIPTS) $(MANS) $(HEADERS) config.h \ all-local installdirs: installdirs-recursive installdirs-am: - for dir in "$(DESTDIR)$(bindir)" "$(DESTDIR)$(pkglibexecdir)" "$(DESTDIR)$(bindir)" "$(DESTDIR)$(man1dir)" "$(DESTDIR)$(man5dir)" "$(DESTDIR)$(man8dir)" "$(DESTDIR)$(oldincludedir)"; do \ + for dir in "$(DESTDIR)$(bindir)" "$(DESTDIR)$(pkglibexecdir)" "$(DESTDIR)$(bindir)" "$(DESTDIR)$(man1dir)" "$(DESTDIR)$(man3dir)" "$(DESTDIR)$(man8dir)" "$(DESTDIR)$(oldincludedir)"; do \ test -z "$$dir" || $(MKDIR_P) "$$dir"; \ done install: $(BUILT_SOURCES) @@ -1369,7 +1370,7 @@ install-html: install-html-recursive install-info: install-info-recursive -install-man: install-man1 install-man5 install-man8 +install-man: install-man1 install-man3 install-man8 install-pdf: install-pdf-recursive @@ -1400,7 +1401,7 @@ uninstall-am: uninstall-binPROGRAMS uninstall-binSCRIPTS \ uninstall-local uninstall-man uninstall-oldincludeHEADERS \ uninstall-pkglibexecPROGRAMS -uninstall-man: uninstall-man1 uninstall-man5 uninstall-man8 +uninstall-man: uninstall-man1 uninstall-man3 uninstall-man8 .MAKE: $(RECURSIVE_CLEAN_TARGETS) $(RECURSIVE_TARGETS) install-am \ install-exec-am install-strip @@ -1416,7 +1417,7 @@ uninstall-man: uninstall-man1 uninstall-man5 uninstall-man8 install-data-local install-dvi install-dvi-am install-exec \ install-exec-am install-exec-hook install-exec-local \ install-html install-html-am install-info install-info-am \ - install-man install-man1 install-man5 install-man8 \ + install-man install-man1 install-man3 install-man8 \ install-oldincludeHEADERS install-pdf install-pdf-am \ install-pkglibexecPROGRAMS install-ps install-ps-am \ install-strip installcheck installcheck-am installdirs \ @@ -1424,7 +1425,7 @@ uninstall-man: uninstall-man1 uninstall-man5 uninstall-man8 mostlyclean mostlyclean-compile mostlyclean-generic pdf pdf-am \ ps ps-am tags tags-recursive uninstall uninstall-am \ uninstall-binPROGRAMS uninstall-binSCRIPTS uninstall-local \ - uninstall-man uninstall-man1 uninstall-man5 uninstall-man8 \ + uninstall-man uninstall-man1 uninstall-man3 uninstall-man8 \ uninstall-oldincludeHEADERS uninstall-pkglibexecPROGRAMS git_version.stamp: diff --git a/configure b/configure index 779dd4de..57afc1bb 100755 --- a/configure +++ b/configure @@ -7859,7 +7859,7 @@ _ACEOF ac_config_headers="$ac_config_headers config.h:config.in" -ac_config_files="$ac_config_files Makefile doc/Makefile doc/SystemTap_Tapset_Reference/Makefile stap.1 stapprobes.5 stapfuncs.5 stapvars.5 stapex.5 staprun.8 stap-server.8 man/stapprobes.iosched.5 man/stapprobes.netdev.5 man/stapprobes.nfs.5 man/stapprobes.nfsd.5 man/stapprobes.pagefault.5 man/stapprobes.process.5 man/stapprobes.rpc.5 man/stapprobes.scsi.5 man/stapprobes.signal.5 man/stapprobes.socket.5 man/stapprobes.tcp.5 man/stapprobes.udp.5 initscript/systemtap" +ac_config_files="$ac_config_files Makefile doc/Makefile doc/SystemTap_Tapset_Reference/Makefile stap.1 stapprobes.3stap stapfuncs.3stap stapvars.3stap stapex.3stap staprun.8 stap-server.8 man/stapprobes.iosched.3stap man/stapprobes.netdev.3stap man/stapprobes.nfs.3stap man/stapprobes.nfsd.3stap man/stapprobes.pagefault.3stap man/stapprobes.process.3stap man/stapprobes.rpc.3stap man/stapprobes.scsi.3stap man/stapprobes.signal.3stap man/stapprobes.socket.3stap man/stapprobes.tcp.3stap man/stapprobes.udp.3stap initscript/systemtap" subdirs="$subdirs testsuite" @@ -8504,24 +8504,24 @@ do "doc/Makefile") CONFIG_FILES="$CONFIG_FILES doc/Makefile" ;; "doc/SystemTap_Tapset_Reference/Makefile") CONFIG_FILES="$CONFIG_FILES doc/SystemTap_Tapset_Reference/Makefile" ;; "stap.1") CONFIG_FILES="$CONFIG_FILES stap.1" ;; - "stapprobes.5") CONFIG_FILES="$CONFIG_FILES stapprobes.5" ;; - "stapfuncs.5") CONFIG_FILES="$CONFIG_FILES stapfuncs.5" ;; - "stapvars.5") CONFIG_FILES="$CONFIG_FILES stapvars.5" ;; - "stapex.5") CONFIG_FILES="$CONFIG_FILES stapex.5" ;; + "stapprobes.3stap") CONFIG_FILES="$CONFIG_FILES stapprobes.3stap" ;; + "stapfuncs.3stap") CONFIG_FILES="$CONFIG_FILES stapfuncs.3stap" ;; + "stapvars.3stap") CONFIG_FILES="$CONFIG_FILES stapvars.3stap" ;; + "stapex.3stap") CONFIG_FILES="$CONFIG_FILES stapex.3stap" ;; "staprun.8") CONFIG_FILES="$CONFIG_FILES staprun.8" ;; "stap-server.8") CONFIG_FILES="$CONFIG_FILES stap-server.8" ;; - "man/stapprobes.iosched.5") CONFIG_FILES="$CONFIG_FILES man/stapprobes.iosched.5" ;; - "man/stapprobes.netdev.5") CONFIG_FILES="$CONFIG_FILES man/stapprobes.netdev.5" ;; - "man/stapprobes.nfs.5") CONFIG_FILES="$CONFIG_FILES man/stapprobes.nfs.5" ;; - "man/stapprobes.nfsd.5") CONFIG_FILES="$CONFIG_FILES man/stapprobes.nfsd.5" ;; - "man/stapprobes.pagefault.5") CONFIG_FILES="$CONFIG_FILES man/stapprobes.pagefault.5" ;; - "man/stapprobes.process.5") CONFIG_FILES="$CONFIG_FILES man/stapprobes.process.5" ;; - "man/stapprobes.rpc.5") CONFIG_FILES="$CONFIG_FILES man/stapprobes.rpc.5" ;; - "man/stapprobes.scsi.5") CONFIG_FILES="$CONFIG_FILES man/stapprobes.scsi.5" ;; - "man/stapprobes.signal.5") CONFIG_FILES="$CONFIG_FILES man/stapprobes.signal.5" ;; - "man/stapprobes.socket.5") CONFIG_FILES="$CONFIG_FILES man/stapprobes.socket.5" ;; - "man/stapprobes.tcp.5") CONFIG_FILES="$CONFIG_FILES man/stapprobes.tcp.5" ;; - "man/stapprobes.udp.5") CONFIG_FILES="$CONFIG_FILES man/stapprobes.udp.5" ;; + "man/stapprobes.iosched.3stap") CONFIG_FILES="$CONFIG_FILES man/stapprobes.iosched.3stap" ;; + "man/stapprobes.netdev.3stap") CONFIG_FILES="$CONFIG_FILES man/stapprobes.netdev.3stap" ;; + "man/stapprobes.nfs.3stap") CONFIG_FILES="$CONFIG_FILES man/stapprobes.nfs.3stap" ;; + "man/stapprobes.nfsd.3stap") CONFIG_FILES="$CONFIG_FILES man/stapprobes.nfsd.3stap" ;; + "man/stapprobes.pagefault.3stap") CONFIG_FILES="$CONFIG_FILES man/stapprobes.pagefault.3stap" ;; + "man/stapprobes.process.3stap") CONFIG_FILES="$CONFIG_FILES man/stapprobes.process.3stap" ;; + "man/stapprobes.rpc.3stap") CONFIG_FILES="$CONFIG_FILES man/stapprobes.rpc.3stap" ;; + "man/stapprobes.scsi.3stap") CONFIG_FILES="$CONFIG_FILES man/stapprobes.scsi.3stap" ;; + "man/stapprobes.signal.3stap") CONFIG_FILES="$CONFIG_FILES man/stapprobes.signal.3stap" ;; + "man/stapprobes.socket.3stap") CONFIG_FILES="$CONFIG_FILES man/stapprobes.socket.3stap" ;; + "man/stapprobes.tcp.3stap") CONFIG_FILES="$CONFIG_FILES man/stapprobes.tcp.3stap" ;; + "man/stapprobes.udp.3stap") CONFIG_FILES="$CONFIG_FILES man/stapprobes.udp.3stap" ;; "initscript/systemtap") CONFIG_FILES="$CONFIG_FILES initscript/systemtap" ;; "run-stap") CONFIG_FILES="$CONFIG_FILES run-stap" ;; diff --git a/configure.ac b/configure.ac index f74d8d99..9d8dd7ae 100644 --- a/configure.ac +++ b/configure.ac @@ -355,7 +355,7 @@ dnl Don't use this directly (when not given it is set to NONE). AC_DEFINE_UNQUOTED(STAP_PREFIX, "$prefix", [configure prefix location]) AC_CONFIG_HEADERS([config.h:config.in]) -AC_CONFIG_FILES(Makefile doc/Makefile doc/SystemTap_Tapset_Reference/Makefile stap.1 stapprobes.5 stapfuncs.5 stapvars.5 stapex.5 staprun.8 stap-server.8 man/stapprobes.iosched.5 man/stapprobes.netdev.5 man/stapprobes.nfs.5 man/stapprobes.nfsd.5 man/stapprobes.pagefault.5 man/stapprobes.process.5 man/stapprobes.rpc.5 man/stapprobes.scsi.5 man/stapprobes.signal.5 man/stapprobes.socket.5 man/stapprobes.tcp.5 man/stapprobes.udp.5 initscript/systemtap) +AC_CONFIG_FILES(Makefile doc/Makefile doc/SystemTap_Tapset_Reference/Makefile stap.1 stapprobes.3stap stapfuncs.3stap stapvars.3stap stapex.3stap staprun.8 stap-server.8 man/stapprobes.iosched.3stap man/stapprobes.netdev.3stap man/stapprobes.nfs.3stap man/stapprobes.nfsd.3stap man/stapprobes.pagefault.3stap man/stapprobes.process.3stap man/stapprobes.rpc.3stap man/stapprobes.scsi.3stap man/stapprobes.signal.3stap man/stapprobes.socket.3stap man/stapprobes.tcp.3stap man/stapprobes.udp.3stap initscript/systemtap) AC_CONFIG_SUBDIRS(testsuite) AC_CONFIG_FILES([run-stap], [chmod +x run-stap]) AC_OUTPUT diff --git a/doc/Makefile.in b/doc/Makefile.in index e23a6699..93753666 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -163,7 +163,6 @@ staplog_CPPFLAGS = @staplog_CPPFLAGS@ subdirs = @subdirs@ sysconfdir = @sysconfdir@ target_alias = @target_alias@ -top_build_prefix = @top_build_prefix@ top_builddir = @top_builddir@ top_srcdir = @top_srcdir@ PDF_FILES = tutorial.pdf langref.pdf diff --git a/doc/SystemTap_Tapset_Reference/Makefile.in b/doc/SystemTap_Tapset_Reference/Makefile.in index 6fe6bab2..06286d6c 100644 --- a/doc/SystemTap_Tapset_Reference/Makefile.in +++ b/doc/SystemTap_Tapset_Reference/Makefile.in @@ -166,7 +166,6 @@ staplog_CPPFLAGS = @staplog_CPPFLAGS@ subdirs = @subdirs@ sysconfdir = @sysconfdir@ target_alias = @target_alias@ -top_build_prefix = @top_build_prefix@ top_builddir = @top_builddir@ top_srcdir = @top_srcdir@ DOC_INSTALL_DIR = $(DESTDIR)$(datadir)/doc/systemtap diff --git a/man/stapprobes.iosched.3stap.in b/man/stapprobes.iosched.3stap.in new file mode 100644 index 00000000..e08dce8c --- /dev/null +++ b/man/stapprobes.iosched.3stap.in @@ -0,0 +1,100 @@ +.\" -*- nroff -*- +.TH STAPPROBES.IOSCHED 3stap @DATE@ "IBM" +.SH NAME +stapprobes.iosched \- systemtap IO scheduler probe points + +.\" macros +.de SAMPLE +.br +.RS +.nf +.nh +.. +.de ESAMPLE +.hy +.fi +.RE +.. + +.SH DESCRIPTION + +This family of probe points is used to probe the IO scheduler +activities. It contains the following probe points: + +.P +.TP +.B ioscheduler.elv_next_request +Fires when retrieves a request from request queue + +.B Arguments: + +.I elevator_name + The elevator name + +.P +.TP +.B ioscheduler.elv_next_request.return +Fires when return from retrieving a request + +.B Arguments: + +.I req + Address of the request + +.I req_flags + request flags + +.I disk_major + disk major number of the request + +.I disk_minor + disk minor number of the request + +.P +.TP +.B ioscheduler.elv_add_request +Fires when add a request into request queue + +.B Arguments: + +.I elevator_name + The elevator name + +.I req + Address of the request + +.I req_flags + request flags + +.I disk_major + disk major number of the request + +.I disk_minor + disk minor number of the request + +.P +.TP +.B ioscheduler.elv_completed_request +Fires when a request is completed + +.B Arguments: + +.I elevator_name + The elevator name + +.I req + Address of the request + +.I req_flags + request flags + +.I disk_major + disk major number of the request + +.I disk_minor + disk minor number of the request + +.SH SEE ALSO +.IR stap (1), +.IR stapprobes (3stap), + diff --git a/man/stapprobes.iosched.5.in b/man/stapprobes.iosched.5.in deleted file mode 100644 index f638b2ff..00000000 --- a/man/stapprobes.iosched.5.in +++ /dev/null @@ -1,100 +0,0 @@ -.\" -*- nroff -*- -.TH STAPPROBES.IOSCHED 5 @DATE@ "IBM" -.SH NAME -stapprobes.iosched \- systemtap IO scheduler probe points - -.\" macros -.de SAMPLE -.br -.RS -.nf -.nh -.. -.de ESAMPLE -.hy -.fi -.RE -.. - -.SH DESCRIPTION - -This family of probe points is used to probe the IO scheduler -activities. It contains the following probe points: - -.P -.TP -.B ioscheduler.elv_next_request -Fires when retrieves a request from request queue - -.B Arguments: - -.I elevator_name - The elevator name - -.P -.TP -.B ioscheduler.elv_next_request.return -Fires when return from retrieving a request - -.B Arguments: - -.I req - Address of the request - -.I req_flags - request flags - -.I disk_major - disk major number of the request - -.I disk_minor - disk minor number of the request - -.P -.TP -.B ioscheduler.elv_add_request -Fires when add a request into request queue - -.B Arguments: - -.I elevator_name - The elevator name - -.I req - Address of the request - -.I req_flags - request flags - -.I disk_major - disk major number of the request - -.I disk_minor - disk minor number of the request - -.P -.TP -.B ioscheduler.elv_completed_request -Fires when a request is completed - -.B Arguments: - -.I elevator_name - The elevator name - -.I req - Address of the request - -.I req_flags - request flags - -.I disk_major - disk major number of the request - -.I disk_minor - disk minor number of the request - -.SH SEE ALSO -.IR stap (1), -.IR stapprobes (5), - diff --git a/man/stapprobes.netdev.3stap.in b/man/stapprobes.netdev.3stap.in new file mode 100644 index 00000000..c25fbd44 --- /dev/null +++ b/man/stapprobes.netdev.3stap.in @@ -0,0 +1,77 @@ +.\" -*- nroff -*- +.TH STAPPROBES.NETDEV 3stap @DATE@ "IBM" +.SH NAME +stapprobes.netdev \- systemtap network device probe points + +.\" macros +.de SAMPLE +.br +.RS +.nf +.nh +.. +.de ESAMPLE +.hy +.fi +.RE +.. + +.SH DESCRIPTION + +This family of probe points is used to probe the activities of network +device. +It contains the following probe points: + +.P +.TP +.B netdev.receive +Fires when data arrives on network device + +.B Arguments: + +.I dev_name + The name of the device. e.g: eth0, ath1 + +.I length + The length of the receiving buffer + +.I protocol + The possible values of protocol could be: + 0800 IP + 8100 802.1Q VLAN + 0001 802.3 + 0002 AX.25 + 0004 802.2 + 8035 RARP + 0005 SNAP + 0805 X.25 + 0806 ARP + 8137 IPX + 0009 Localtalk + 86DD IPv6 + +.I truesize + The size of the received data + +.P +.TP +.B netdev.transmit +Fires when the network device wants to transmit a buffer + +.B Arguments: + +.I dev_name + The name of the device. e.g: eth0, ath1 + +.I length + The length of the transmit buffer + +.I protocol + The protocol of this packet. + +.I truesize + The size of the the data to be transmitted. + +.SH SEE ALSO +.IR stap (1), +.IR stapprobes (3stap), diff --git a/man/stapprobes.netdev.5.in b/man/stapprobes.netdev.5.in deleted file mode 100644 index 0510b07b..00000000 --- a/man/stapprobes.netdev.5.in +++ /dev/null @@ -1,77 +0,0 @@ -.\" -*- nroff -*- -.TH STAPPROBES.NETDEV 5 @DATE@ "IBM" -.SH NAME -stapprobes.netdev \- systemtap network device probe points - -.\" macros -.de SAMPLE -.br -.RS -.nf -.nh -.. -.de ESAMPLE -.hy -.fi -.RE -.. - -.SH DESCRIPTION - -This family of probe points is used to probe the activities of network -device. -It contains the following probe points: - -.P -.TP -.B netdev.receive -Fires when data arrives on network device - -.B Arguments: - -.I dev_name - The name of the device. e.g: eth0, ath1 - -.I length - The length of the receiving buffer - -.I protocol - The possible values of protocol could be: - 0800 IP - 8100 802.1Q VLAN - 0001 802.3 - 0002 AX.25 - 0004 802.2 - 8035 RARP - 0005 SNAP - 0805 X.25 - 0806 ARP - 8137 IPX - 0009 Localtalk - 86DD IPv6 - -.I truesize - The size of the received data - -.P -.TP -.B netdev.transmit -Fires when the network device wants to transmit a buffer - -.B Arguments: - -.I dev_name - The name of the device. e.g: eth0, ath1 - -.I length - The length of the transmit buffer - -.I protocol - The protocol of this packet. - -.I truesize - The size of the the data to be transmitted. - -.SH SEE ALSO -.IR stap (1), -.IR stapprobes (5), diff --git a/man/stapprobes.nfs.3stap.in b/man/stapprobes.nfs.3stap.in new file mode 100644 index 00000000..b6a81cde --- /dev/null +++ b/man/stapprobes.nfs.3stap.in @@ -0,0 +1,1236 @@ +.\" -*- nroff -*- +.TH STAPPROBES.NFS 3stap @DATE@ "IBM" +.SH NAME +stapprobes.nfs \- systemtap NFS client side probe points + +.\" macros +.de SAMPLE +.br +.RS +.nf +.nh +.. +.de ESAMPLE +.hy +.fi +.RE +.. + +.SH DESCRIPTION + +This family of probe points is used to probe NFS activities on +client side. +It contains the following probe points: + +.P +.TP +.B nfs.fop.llseek + +Fires whenever doing a llseek operation on nfs client side + +.B Arguments: + +.I dev + device identifier + +.I ino + inode number + +.I s_id + the pointer to s_id + +.I devname + the combination of server ip and the name of block device + on server + +.I maxbyte + Maximum size of the files + +.I offset + the offset of file to be repositioned + +.I origin + the original position. The possible value could be: + SEEK_SET + The offset is set to offset bytes. + SEEK_CUR + The offset is set to its current location + plus offset bytes. + SEEK_END + The offset is set to the size of the file + plus offset bytes. + +.P +.TP +.B nfs.fop.llseek.return + +Fires whenever nfs llseek operation is done + +.B Arguments: + +.I retstr + resulting offset location + +.P +.TP +.B nfs.fop.read + +Fires whenever doing a read operation on nfs client side + +.B Arguments: + +.I dev + device identifier + +.I ino + inode number + +.I s_id + the pointer to s_id + +.I devname + the combination of server ip and the name of block device + on server + +.I len,size + number of bytes to be read + +.I pos + current file offset + +.I buf + the buf address + +.P +.TP +.B nfs.fop.read.return + +Fires whenever nfs read operation is done + +.B Arguments: + +.I size + number of bytes read + +.P +.TP +.B nfs.fop.write + +Fires whenever doing a write operation on nfs client side + +.B Arguments: + +.I dev + device identifier + +.I ino + inode number + +.I s_id + the pointer to s_id + +.I devname + the combination of server ip and the name of block device + on server + +.I len,size + number of bytes to written + +.I pos + current file offset + +.I buf + the buf address + +.P +.TP +.B nfs.fop.write.return + +Fires whenever nfs write operation is done + +.B Arguments: + +.I size + number of bytes written + +.P +.TP +.B nfs.fop.aio_read + +Fires whenever doing an aio_read operation on nfs client side + +.B Arguments: + +.I dev + device identifier + +.I ino + inode number + +.I s_id + the pointer to s_id + +.I devname + the combination of server ip and the name of block device + on server + +.I count,size + number of bytes to be read + +.I pos + current file offset + +.I buf + the buf address + +.I parent_name + parent dir name + +.I file_name + file name + +.I cache_valid + cache related bit mask flag + +.I cache_time + when we started read-caching this inode + +.I attrtimeo + how long the cached information is assumed to be valid. + + The cached attrs for this inode needed to be revalidated if + jiffies \- read_cache_jiffies > attrtime + +.P +.TP +.B nfs.fop.aio_read.return + +Fires whenever nfs aio_read operation is done + +.B Arguments: + +.I size + number of bytes read + +.P +.TP +.B nfs.fop.aio_write + +Fires whenever doing an aio_write operation on nfs client side + +.B Arguments: + +.I dev + device identifier + +.I ino + inode number + +.I s_id + the pointer to s_id + +.I devname + the combination of server ip and the name of block device + on server + +.I count,size + number of bytes to written + +.I pos + current file offset + +.I buf + the buf address + +.I parent_name + parent dir name + +.I file_name + file name + +.P +.TP +.B nfs.fop.aio_write.return + +Fires whenever nfs aio_write operation is done + +.B Arguments: + +.I size + number of bytes written + +.P +.TP +.B nfs.fop.mmap + +Fires whenever doing an mmap operation on nfs client side + +.B Arguments: + +.I dev + device identifier + +.I ino + inode number + +.I s_id + the pointer to s_id + +.I devname + the combination of server ip and the name of block device + on server + +.I vm_start + start address within vm_mm + +.I vm_end + the first byte after end address within vm_mm + +.I vm_flag + vm flags + +.I parent_name + parent dir name + +.I file_name + file name + +.I cache_valid + cache related bit mask flag + +.I cache_time + when we started read-caching this inode + +.I attrtimeo + how long the cached information is assumed to be valid. + + The cached attrs for this inode needed to be revalidated if + jiffies \- read_cache_jiffies > attrtime + +.P +.TP +.B nfs.fop.open + +Fires whenever doing an open operation on nfs client side + +.B Arguments: + +.I dev + device identifier + +.I ino + inode number + +.I s_id + the pointer to s_id + +.I devname + the combination of server ip and the name of block device + on server + +.I file_name + file name + +.I flag + file flag + +.I i_size + file length in bytes + +.P +.TP +.B nfs.fop.flush + +Fires whenever doing an flush operation on nfs client side + +.B Arguments: + +.I dev + device identifier + +.I ino + inode number + +.I s_id + the pointer to s_id + +.I devname + the combination of server ip and the name of block device + on server + +.I mode + file mode + +.I ndirty + number of dirty page to be flushed + +.P +.TP +.B nfs.fop.release + +Fires whenever doing a release page operation on nfs client side + +.B Arguments: + +.I dev + device identifier + +.I ino + inode number + +.I s_id + the pointer to s_id + +.I devname + the combination of server ip and the name of block device + on server + +.I mode + file mode + +.P +.TP +.B nfs.fop.fsync + +Fires whenever doing a fsync operation on nfs client side + +.B Arguments: + +.I dev + device identifier + +.I ino + inode number + +.I s_id + the pointer to s_id + +.I devname + the combination of server ip and the name of block device + on server + +.I ndirty + number of dirty page to be flushed + +.P +.TP +.B nfs.fop.lock + +Fires whenever doing a file lock operation on nfs client side + +.B Arguments: + +.I dev + device identifier + +.I ino + inode number + +.I s_id + the pointer to s_id + +.I devname + the combination of server ip and the name of block device + on server + +.I i_mode + file type and access rights + +.I cmd + cmd arguments + +.I fl_type + lock type + +.I fl_flag + lock flags + +.I fl_start + starting offset of locked region + +.I fl_end + ending offset of locked region + +.P +.TP +.B nfs.fop.sendfile + +Fires whenever doing a send file operation on nfs client side + +.B Arguments: + +.I dev + device identifier + +.I ino + inode number + +.I s_id + the pointer to s_id + +.I devname + the combination of server ip and the name of block device + on server + +.I count,size + number of bytes to sent + +.I ppos + current file offset + +.I cache_valid + cache related bit mask flag + +.I cache_time + when we started read-caching this inode + +.I attrtimeo + how long the cached information is assumed to be valid. + + The cached attrs for this inode needed to be revalidated if + jiffies \- read_cache_jiffies > attrtime + +.P +.TP +.B nfs.fop.sendfile.return + +Fires whenever nfs sendfile operation is done + +.B Arguments: + +.I size + number of bytes sent + +.P +.TP +.B nfs.fop.check_flags + +Fires whenever doing a check flag operation on nfs client side + +.B Arguments: + +.I flags + file flag + +.P +.TP +.B nfs.aop.readpage + +Fires when a previous async read operation failed + +.B Arguments: + +.I __page + the address of page + +.I dev + device identifier + +.I ino + inode number + +.I i_flag + file flags + +.I i_size + file length in bytes + +.I sb_flag + super block flags + +.I file + file argument + +.I page_index + offset within mapping + +.I rsize + read size (in bytes) + +.P +.TP +.B nfs.aop.readpages + +Fies when in readahead way,read several pages once + +.B Arguments: + +.I dev + device identifier + +.I ino + inode number + +.I nr_pages ,size + number of pages attempted to read in this execution + +.I file + filp argument + +.I rpages + read size (in pages) + +.I rsize + read size (in bytes) + +.P +.TP +.B nfs.aop.readpages.return + +Fies whenever a nfs read pages operation is done + +.B Arguments: + +.I size + number of pages read + +.P +.TP +.B nfs.aop.set_page_dirty + +Fies whenever set page dirty on nfs client side + +.B Arguments: + +.I __page + the address of page + +.I page_flag + page flags + +.P +.TP +.B nfs.aop.writepage + +Fies whenever writing an mapped page to the server from nfs client side + +.B Arguments: + +.I __page + the address of page + +.I dev + device identifier + +.I ino + inode number + +.I for_reclaim + a flag of writeback_control, indicates if it's invoked from the page allocator + +.I for_kupdate + a flag of writeback_control, indicates if it's a kupdate writeback + The priority of wb is decided by above two flags + +.I i_flag + file flags + +.I i_size + file length in bytes + +.I i_state + inode state flags + +.I sb_flag + super block flags + +.I page_index + offset within mapping + +.I wsize + write size + +.P +.TP +.B nfs.aop.writepages + +Fies whenever writing several dirty pages to the server from nfs client sides + +.B Arguments: + +.I dev + device identifier + +.I ino + inode number + +.I for_reclaim + a flag of writeback_control, indicates if it's invoked from the page allocator + +.I for_kupdate + a flag of writeback_control, indicates if it's a kupdate writeback + The priority of wb is decided by above two flags + +.I wpages + write size (in pages) + +.I wsize + write size + +.I nr_to_write ,size + number of pages attempted to be written in this execution + +.P +.TP +.B nfs.aop.prepare_write + +Fies whenever prepare a page for writting on nfs client sides + +.B Arguments: + +.I __page + the address of page + +.I dev + device identifier + +.I ino + inode number + +.I offset + start address of this write operation + +.I to + end address of this write operation + +.I page_index + offset within mapping + +.I size + read bytes + +.P +.TP +.B nfs.aop.commit_write + +Fies often after prepare write operation + +.B Arguments: + +.I __page + the address of page + +.I dev + device identifier + +.I ino + inode number + +.I offset + start address of this write operation + +.I to + end address of this write operation + +.I i_flag + file flags + +.I i_size + file length in bytes + +.I sb_flag + super block flag + +.I page_index + offset within mapping + +.I size + read bytes + +.P +.TP +.B nfs.aop.release_page + +.B Arguments: + +.I __page + the address of page + +.I dev + device identifier + +.I ino + inode number + +.I page_index + offset within mapping + +.P +.TP +.B nfs.proc.lookup + +.B Arguments: + +.I server_ip + ip address of server + +.I prot + transfer protocol + +.I version + nfs version + +.I filename + the name of file which client opens/searchs on server + +.I name_len + the length of file name + +.I bitmask0, bitmask1 + V4 bitmask representing the set of attributes + supported on this filesystem (only in probe nfs.proc4.lookup) + +.P +.TP +.B nfs.proc.read + +Fires when client synchronously reads file from server + +.B Arguments: + +.I server_ip + ip address of server + +.I prot + transfer protocol + +.I version + nfs version + +.I flags + used to set task\->tk_flags in rpc_init_task function + +.I size,count + number of bytes to be read in this execution + +.I offset + the file offset + +.P +.TP +.B nfs.proc.read.return + +Fires when synchronously reading file from server is done + +.B Arguments: + +.I size + number of bytes read + +.P +.TP +.B nfs.proc.write + +Fires when client synchronously writes file to server + +.B Arguments: + +.I server_ip + ip address of server + +.I prot + transfer protocol + +.I version + nfs version + +.I flags + used to set task\->tk_flags in rpc_init_task function + +.I size,count + number of bytes to be written in this execution + +.I offset + the file offset + +.I bitmask0, bitmask1 + V4 bitmask representing the set of attributes + supported on this filesystem (only in probe nfs.proc4.lookup) + +.P +.TP +.B nfs.proc.write.return + +Fires when synchronously writting file from server is done + +.B Arguments: + +.I size + number of bytes written + +.P +.TP +.B nfs.proc.commit + +Fires when client writes the buffered data to disk,the buffered +data is asynchronously written by client before(not exist in NFSV2) + +.B Arguments: + +.I server_ip + ip address of server + +.I prot + transfer protocol + +.I version + nfs version + +.I size,count + number of bytes to be written in this execution + +.I offset + the file offset + +.I bitmask0, bitmask1 + V4 bitmask representing the set of attributes + supported on this filesystem (only in probe nfs.proc4.lookup) + +.P +.TP +.B nfs.proc.commit.return + +Fires when committing operation is done + +.B Arguments: + +.I size + number of bytes written + +.P +.TP +.B nfs.proc.read_setup + +Fires when client asynchronously reads file from server, +this function is used to setup a read rpc task,not do +a real read operation. + +.B Arguments: + +.I server_ip + ip address of server + +.I prot + transfer protocol + +.I version + nfs version + +.I size,count + number of bytes to be read in this execution + +.I offset + the file offset + +.P +.TP +.B nfs.proc.read_done + +Fires when a read reply is received or some read error occur +(timeout or socket shutdown) + +.B Arguments: + +.I server_ip + ip address of server + +.I prot + transfer protocol + +.I version + nfs version + +.I status + result of last async read operation + +.I count + number of bytes read + +.I timestamp + time stamp ,which is used for lease renewal (only + in nfs.proc4.read_done) + +.P +.TP +.B nfs.proc.write_setup + +Fires when client asynchronously write data to server, +this function is used to setup a write rpc task,not do +a write read operation. + +.B Arguments: + +.I server_ip + ip address of server + +.I prot + transfer protocol + +.I version + nfs version + +.I size,count + number of bytes to be written in this execution + +.I offset + the file offset + +.I how + used to set args.stable,The possible value could be: + NFS_UNSTABLE, + NFS_DATA_SYNC, + NFS_FILE_SYNC + (only in nfs.proc3.write_setup and nfs.proc4.write_setup) + +.I bitmask0, bitmask1 + V4 bitmask representing the set of attributes supported + on this filesystem (only in probe nfs.proc4.write_setup) + +.P +.TP +.B nfs.proc.write_done + +Fires when a write reply is received or some write error occur +(timeout or socket shutdown) + +.B Arguments: + +.I server_ip + ip address of server + +.I prot + transfer protocol + +.I version + nfs version + +.I status + result of last async write operation + +.I valid + fattr\->valid ,indicates which fields are valid + +.I count + number of bytes written + +.I timestamp + time stamp ,which is used for lease renewal (only + in nfs.proc4.read_done) + +.P +.TP +.B nfs.proc.commit_setup + +Fires when client asynchronously do a commit operation, +this function is used to setup a commit rpc task,not do +a commit read operation. + +.B Arguments: + +.I server_ip + ip address of server + +.I prot + transfer protocol + +.I version + nfs version + +.I size,count + number of bytes to be written in this execution + +.I offset + the file offset + +.I bitmask0, bitmask1 + V4 bitmask representing the set of attributes supported + on this filesystem (only in probe nfs.proc4.commit_setup) + +.P +.TP +.B nfs.proc.commit_done + +Fires when a commit reply is received or some commit error occur +(timeout or socket shutdown) + +.B Arguments: + +.I server_ip + ip address of server + +.I prot + transfer protocol + +.I version + nfs version + +.I status + result of last async write operation + +.I valid + fattr\->valid ,indicates which fields are valid + +.I count + number of bytes written + +.I timestamp + time stamp ,which is used for lease renewal (only + in nfs.proc4.read_done) + +.P +.TP +.B nfs.proc.open + +Fires whenever doing a open operation on nfs client side, +the nfs_open function is used to allocate file read/write +context information + +.B Arguments: + +.I server_ip + ip address of server + +.I prot + transfer protocol + +.I version + nfs version + +.I filename + file name + +.I flag + file flag + +.I mode + file mode + +.P +.TP +.B nfs.proc.release + +Fires whenever doing a release operation on nfs client side, + +.B Arguments: + +.I server_ip + ip address of server + +.I prot + transfer protocol + +.I version + nfs version + +.I filename + file name + +.I flag + file flag + +.I mode + file mode + +.P +.TP +.B nfs.proc4.handle_exception + +Fires whenever doing the error handling, only exist in NFSV4 + +.I errorcode + error code + +.P +.TP +.B nfs.proc.create + +Fires whenever nfs client creates a file on server + +.B Arguments: + +.I server_ip + ip address of server + +.I prot + transfer protocol + +.I version + nfs version + +.I fh + file handler of parent dir + +.I filename + file name + +.I filelen + length of file name + +.I flag + indicates create mode(only for NFSV3 and NFSV4) + +.P +.TP +.B nfs.proc.remove + +Fires whenever nfs client removes a file from server + +.B Arguments: + +.I server_ip + ip address of server + +.I prot + transfer protocol + +.I version + nfs version + +.I fh + file handler of parent dir + +.I filename + file name + +.I filelen + length of file name + +.P +.TP +.B nfs.proc.rename + +Fires whenever nfs client renames a file on server + +.B Arguments: + +.I server_ip + ip address of server + +.I prot + transfer protocol + +.I version + nfs version + +.I old_fh + file handler of old parent dir + +.I old_name + old file name + +.I old_filelen + length of old file name + +.I new_fh + file handler of new parent dir + +.I new_name + new file name + +.I new_filelen + length of new file name + +.SH SEE ALSO +.IR stap (1), +.IR stapprobes (3stap), + diff --git a/man/stapprobes.nfs.5.in b/man/stapprobes.nfs.5.in deleted file mode 100644 index bf575ae4..00000000 --- a/man/stapprobes.nfs.5.in +++ /dev/null @@ -1,1236 +0,0 @@ -.\" -*- nroff -*- -.TH STAPPROBES.NFS 5 @DATE@ "IBM" -.SH NAME -stapprobes.nfs \- systemtap NFS client side probe points - -.\" macros -.de SAMPLE -.br -.RS -.nf -.nh -.. -.de ESAMPLE -.hy -.fi -.RE -.. - -.SH DESCRIPTION - -This family of probe points is used to probe NFS activities on -client side. -It contains the following probe points: - -.P -.TP -.B nfs.fop.llseek - -Fires whenever doing a llseek operation on nfs client side - -.B Arguments: - -.I dev - device identifier - -.I ino - inode number - -.I s_id - the pointer to s_id - -.I devname - the combination of server ip and the name of block device - on server - -.I maxbyte - Maximum size of the files - -.I offset - the offset of file to be repositioned - -.I origin - the original position. The possible value could be: - SEEK_SET - The offset is set to offset bytes. - SEEK_CUR - The offset is set to its current location - plus offset bytes. - SEEK_END - The offset is set to the size of the file - plus offset bytes. - -.P -.TP -.B nfs.fop.llseek.return - -Fires whenever nfs llseek operation is done - -.B Arguments: - -.I retstr - resulting offset location - -.P -.TP -.B nfs.fop.read - -Fires whenever doing a read operation on nfs client side - -.B Arguments: - -.I dev - device identifier - -.I ino - inode number - -.I s_id - the pointer to s_id - -.I devname - the combination of server ip and the name of block device - on server - -.I len,size - number of bytes to be read - -.I pos - current file offset - -.I buf - the buf address - -.P -.TP -.B nfs.fop.read.return - -Fires whenever nfs read operation is done - -.B Arguments: - -.I size - number of bytes read - -.P -.TP -.B nfs.fop.write - -Fires whenever doing a write operation on nfs client side - -.B Arguments: - -.I dev - device identifier - -.I ino - inode number - -.I s_id - the pointer to s_id - -.I devname - the combination of server ip and the name of block device - on server - -.I len,size - number of bytes to written - -.I pos - current file offset - -.I buf - the buf address - -.P -.TP -.B nfs.fop.write.return - -Fires whenever nfs write operation is done - -.B Arguments: - -.I size - number of bytes written - -.P -.TP -.B nfs.fop.aio_read - -Fires whenever doing an aio_read operation on nfs client side - -.B Arguments: - -.I dev - device identifier - -.I ino - inode number - -.I s_id - the pointer to s_id - -.I devname - the combination of server ip and the name of block device - on server - -.I count,size - number of bytes to be read - -.I pos - current file offset - -.I buf - the buf address - -.I parent_name - parent dir name - -.I file_name - file name - -.I cache_valid - cache related bit mask flag - -.I cache_time - when we started read-caching this inode - -.I attrtimeo - how long the cached information is assumed to be valid. - - The cached attrs for this inode needed to be revalidated if - jiffies \- read_cache_jiffies > attrtime - -.P -.TP -.B nfs.fop.aio_read.return - -Fires whenever nfs aio_read operation is done - -.B Arguments: - -.I size - number of bytes read - -.P -.TP -.B nfs.fop.aio_write - -Fires whenever doing an aio_write operation on nfs client side - -.B Arguments: - -.I dev - device identifier - -.I ino - inode number - -.I s_id - the pointer to s_id - -.I devname - the combination of server ip and the name of block device - on server - -.I count,size - number of bytes to written - -.I pos - current file offset - -.I buf - the buf address - -.I parent_name - parent dir name - -.I file_name - file name - -.P -.TP -.B nfs.fop.aio_write.return - -Fires whenever nfs aio_write operation is done - -.B Arguments: - -.I size - number of bytes written - -.P -.TP -.B nfs.fop.mmap - -Fires whenever doing an mmap operation on nfs client side - -.B Arguments: - -.I dev - device identifier - -.I ino - inode number - -.I s_id - the pointer to s_id - -.I devname - the combination of server ip and the name of block device - on server - -.I vm_start - start address within vm_mm - -.I vm_end - the first byte after end address within vm_mm - -.I vm_flag - vm flags - -.I parent_name - parent dir name - -.I file_name - file name - -.I cache_valid - cache related bit mask flag - -.I cache_time - when we started read-caching this inode - -.I attrtimeo - how long the cached information is assumed to be valid. - - The cached attrs for this inode needed to be revalidated if - jiffies \- read_cache_jiffies > attrtime - -.P -.TP -.B nfs.fop.open - -Fires whenever doing an open operation on nfs client side - -.B Arguments: - -.I dev - device identifier - -.I ino - inode number - -.I s_id - the pointer to s_id - -.I devname - the combination of server ip and the name of block device - on server - -.I file_name - file name - -.I flag - file flag - -.I i_size - file length in bytes - -.P -.TP -.B nfs.fop.flush - -Fires whenever doing an flush operation on nfs client side - -.B Arguments: - -.I dev - device identifier - -.I ino - inode number - -.I s_id - the pointer to s_id - -.I devname - the combination of server ip and the name of block device - on server - -.I mode - file mode - -.I ndirty - number of dirty page to be flushed - -.P -.TP -.B nfs.fop.release - -Fires whenever doing a release page operation on nfs client side - -.B Arguments: - -.I dev - device identifier - -.I ino - inode number - -.I s_id - the pointer to s_id - -.I devname - the combination of server ip and the name of block device - on server - -.I mode - file mode - -.P -.TP -.B nfs.fop.fsync - -Fires whenever doing a fsync operation on nfs client side - -.B Arguments: - -.I dev - device identifier - -.I ino - inode number - -.I s_id - the pointer to s_id - -.I devname - the combination of server ip and the name of block device - on server - -.I ndirty - number of dirty page to be flushed - -.P -.TP -.B nfs.fop.lock - -Fires whenever doing a file lock operation on nfs client side - -.B Arguments: - -.I dev - device identifier - -.I ino - inode number - -.I s_id - the pointer to s_id - -.I devname - the combination of server ip and the name of block device - on server - -.I i_mode - file type and access rights - -.I cmd - cmd arguments - -.I fl_type - lock type - -.I fl_flag - lock flags - -.I fl_start - starting offset of locked region - -.I fl_end - ending offset of locked region - -.P -.TP -.B nfs.fop.sendfile - -Fires whenever doing a send file operation on nfs client side - -.B Arguments: - -.I dev - device identifier - -.I ino - inode number - -.I s_id - the pointer to s_id - -.I devname - the combination of server ip and the name of block device - on server - -.I count,size - number of bytes to sent - -.I ppos - current file offset - -.I cache_valid - cache related bit mask flag - -.I cache_time - when we started read-caching this inode - -.I attrtimeo - how long the cached information is assumed to be valid. - - The cached attrs for this inode needed to be revalidated if - jiffies \- read_cache_jiffies > attrtime - -.P -.TP -.B nfs.fop.sendfile.return - -Fires whenever nfs sendfile operation is done - -.B Arguments: - -.I size - number of bytes sent - -.P -.TP -.B nfs.fop.check_flags - -Fires whenever doing a check flag operation on nfs client side - -.B Arguments: - -.I flags - file flag - -.P -.TP -.B nfs.aop.readpage - -Fires when a previous async read operation failed - -.B Arguments: - -.I __page - the address of page - -.I dev - device identifier - -.I ino - inode number - -.I i_flag - file flags - -.I i_size - file length in bytes - -.I sb_flag - super block flags - -.I file - file argument - -.I page_index - offset within mapping - -.I rsize - read size (in bytes) - -.P -.TP -.B nfs.aop.readpages - -Fies when in readahead way,read several pages once - -.B Arguments: - -.I dev - device identifier - -.I ino - inode number - -.I nr_pages ,size - number of pages attempted to read in this execution - -.I file - filp argument - -.I rpages - read size (in pages) - -.I rsize - read size (in bytes) - -.P -.TP -.B nfs.aop.readpages.return - -Fies whenever a nfs read pages operation is done - -.B Arguments: - -.I size - number of pages read - -.P -.TP -.B nfs.aop.set_page_dirty - -Fies whenever set page dirty on nfs client side - -.B Arguments: - -.I __page - the address of page - -.I page_flag - page flags - -.P -.TP -.B nfs.aop.writepage - -Fies whenever writing an mapped page to the server from nfs client side - -.B Arguments: - -.I __page - the address of page - -.I dev - device identifier - -.I ino - inode number - -.I for_reclaim - a flag of writeback_control, indicates if it's invoked from the page allocator - -.I for_kupdate - a flag of writeback_control, indicates if it's a kupdate writeback - The priority of wb is decided by above two flags - -.I i_flag - file flags - -.I i_size - file length in bytes - -.I i_state - inode state flags - -.I sb_flag - super block flags - -.I page_index - offset within mapping - -.I wsize - write size - -.P -.TP -.B nfs.aop.writepages - -Fies whenever writing several dirty pages to the server from nfs client sides - -.B Arguments: - -.I dev - device identifier - -.I ino - inode number - -.I for_reclaim - a flag of writeback_control, indicates if it's invoked from the page allocator - -.I for_kupdate - a flag of writeback_control, indicates if it's a kupdate writeback - The priority of wb is decided by above two flags - -.I wpages - write size (in pages) - -.I wsize - write size - -.I nr_to_write ,size - number of pages attempted to be written in this execution - -.P -.TP -.B nfs.aop.prepare_write - -Fies whenever prepare a page for writting on nfs client sides - -.B Arguments: - -.I __page - the address of page - -.I dev - device identifier - -.I ino - inode number - -.I offset - start address of this write operation - -.I to - end address of this write operation - -.I page_index - offset within mapping - -.I size - read bytes - -.P -.TP -.B nfs.aop.commit_write - -Fies often after prepare write operation - -.B Arguments: - -.I __page - the address of page - -.I dev - device identifier - -.I ino - inode number - -.I offset - start address of this write operation - -.I to - end address of this write operation - -.I i_flag - file flags - -.I i_size - file length in bytes - -.I sb_flag - super block flag - -.I page_index - offset within mapping - -.I size - read bytes - -.P -.TP -.B nfs.aop.release_page - -.B Arguments: - -.I __page - the address of page - -.I dev - device identifier - -.I ino - inode number - -.I page_index - offset within mapping - -.P -.TP -.B nfs.proc.lookup - -.B Arguments: - -.I server_ip - ip address of server - -.I prot - transfer protocol - -.I version - nfs version - -.I filename - the name of file which client opens/searchs on server - -.I name_len - the length of file name - -.I bitmask0, bitmask1 - V4 bitmask representing the set of attributes - supported on this filesystem (only in probe nfs.proc4.lookup) - -.P -.TP -.B nfs.proc.read - -Fires when client synchronously reads file from server - -.B Arguments: - -.I server_ip - ip address of server - -.I prot - transfer protocol - -.I version - nfs version - -.I flags - used to set task\->tk_flags in rpc_init_task function - -.I size,count - number of bytes to be read in this execution - -.I offset - the file offset - -.P -.TP -.B nfs.proc.read.return - -Fires when synchronously reading file from server is done - -.B Arguments: - -.I size - number of bytes read - -.P -.TP -.B nfs.proc.write - -Fires when client synchronously writes file to server - -.B Arguments: - -.I server_ip - ip address of server - -.I prot - transfer protocol - -.I version - nfs version - -.I flags - used to set task\->tk_flags in rpc_init_task function - -.I size,count - number of bytes to be written in this execution - -.I offset - the file offset - -.I bitmask0, bitmask1 - V4 bitmask representing the set of attributes - supported on this filesystem (only in probe nfs.proc4.lookup) - -.P -.TP -.B nfs.proc.write.return - -Fires when synchronously writting file from server is done - -.B Arguments: - -.I size - number of bytes written - -.P -.TP -.B nfs.proc.commit - -Fires when client writes the buffered data to disk,the buffered -data is asynchronously written by client before(not exist in NFSV2) - -.B Arguments: - -.I server_ip - ip address of server - -.I prot - transfer protocol - -.I version - nfs version - -.I size,count - number of bytes to be written in this execution - -.I offset - the file offset - -.I bitmask0, bitmask1 - V4 bitmask representing the set of attributes - supported on this filesystem (only in probe nfs.proc4.lookup) - -.P -.TP -.B nfs.proc.commit.return - -Fires when committing operation is done - -.B Arguments: - -.I size - number of bytes written - -.P -.TP -.B nfs.proc.read_setup - -Fires when client asynchronously reads file from server, -this function is used to setup a read rpc task,not do -a real read operation. - -.B Arguments: - -.I server_ip - ip address of server - -.I prot - transfer protocol - -.I version - nfs version - -.I size,count - number of bytes to be read in this execution - -.I offset - the file offset - -.P -.TP -.B nfs.proc.read_done - -Fires when a read reply is received or some read error occur -(timeout or socket shutdown) - -.B Arguments: - -.I server_ip - ip address of server - -.I prot - transfer protocol - -.I version - nfs version - -.I status - result of last async read operation - -.I count - number of bytes read - -.I timestamp - time stamp ,which is used for lease renewal (only - in nfs.proc4.read_done) - -.P -.TP -.B nfs.proc.write_setup - -Fires when client asynchronously write data to server, -this function is used to setup a write rpc task,not do -a write read operation. - -.B Arguments: - -.I server_ip - ip address of server - -.I prot - transfer protocol - -.I version - nfs version - -.I size,count - number of bytes to be written in this execution - -.I offset - the file offset - -.I how - used to set args.stable,The possible value could be: - NFS_UNSTABLE, - NFS_DATA_SYNC, - NFS_FILE_SYNC - (only in nfs.proc3.write_setup and nfs.proc4.write_setup) - -.I bitmask0, bitmask1 - V4 bitmask representing the set of attributes supported - on this filesystem (only in probe nfs.proc4.write_setup) - -.P -.TP -.B nfs.proc.write_done - -Fires when a write reply is received or some write error occur -(timeout or socket shutdown) - -.B Arguments: - -.I server_ip - ip address of server - -.I prot - transfer protocol - -.I version - nfs version - -.I status - result of last async write operation - -.I valid - fattr\->valid ,indicates which fields are valid - -.I count - number of bytes written - -.I timestamp - time stamp ,which is used for lease renewal (only - in nfs.proc4.read_done) - -.P -.TP -.B nfs.proc.commit_setup - -Fires when client asynchronously do a commit operation, -this function is used to setup a commit rpc task,not do -a commit read operation. - -.B Arguments: - -.I server_ip - ip address of server - -.I prot - transfer protocol - -.I version - nfs version - -.I size,count - number of bytes to be written in this execution - -.I offset - the file offset - -.I bitmask0, bitmask1 - V4 bitmask representing the set of attributes supported - on this filesystem (only in probe nfs.proc4.commit_setup) - -.P -.TP -.B nfs.proc.commit_done - -Fires when a commit reply is received or some commit error occur -(timeout or socket shutdown) - -.B Arguments: - -.I server_ip - ip address of server - -.I prot - transfer protocol - -.I version - nfs version - -.I status - result of last async write operation - -.I valid - fattr\->valid ,indicates which fields are valid - -.I count - number of bytes written - -.I timestamp - time stamp ,which is used for lease renewal (only - in nfs.proc4.read_done) - -.P -.TP -.B nfs.proc.open - -Fires whenever doing a open operation on nfs client side, -the nfs_open function is used to allocate file read/write -context information - -.B Arguments: - -.I server_ip - ip address of server - -.I prot - transfer protocol - -.I version - nfs version - -.I filename - file name - -.I flag - file flag - -.I mode - file mode - -.P -.TP -.B nfs.proc.release - -Fires whenever doing a release operation on nfs client side, - -.B Arguments: - -.I server_ip - ip address of server - -.I prot - transfer protocol - -.I version - nfs version - -.I filename - file name - -.I flag - file flag - -.I mode - file mode - -.P -.TP -.B nfs.proc4.handle_exception - -Fires whenever doing the error handling, only exist in NFSV4 - -.I errorcode - error code - -.P -.TP -.B nfs.proc.create - -Fires whenever nfs client creates a file on server - -.B Arguments: - -.I server_ip - ip address of server - -.I prot - transfer protocol - -.I version - nfs version - -.I fh - file handler of parent dir - -.I filename - file name - -.I filelen - length of file name - -.I flag - indicates create mode(only for NFSV3 and NFSV4) - -.P -.TP -.B nfs.proc.remove - -Fires whenever nfs client removes a file from server - -.B Arguments: - -.I server_ip - ip address of server - -.I prot - transfer protocol - -.I version - nfs version - -.I fh - file handler of parent dir - -.I filename - file name - -.I filelen - length of file name - -.P -.TP -.B nfs.proc.rename - -Fires whenever nfs client renames a file on server - -.B Arguments: - -.I server_ip - ip address of server - -.I prot - transfer protocol - -.I version - nfs version - -.I old_fh - file handler of old parent dir - -.I old_name - old file name - -.I old_filelen - length of old file name - -.I new_fh - file handler of new parent dir - -.I new_name - new file name - -.I new_filelen - length of new file name - -.SH SEE ALSO -.IR stap (1), -.IR stapprobes (5), - diff --git a/man/stapprobes.nfsd.3stap.in b/man/stapprobes.nfsd.3stap.in new file mode 100644 index 00000000..d3aea639 --- /dev/null +++ b/man/stapprobes.nfsd.3stap.in @@ -0,0 +1,513 @@ +.\" -*- nroff -*- +.TH STAPPROBES.NFSD 3stap @DATE@ "IBM" +.SH NAME +stapprobes.nfsd \- systemtap NFS server side probe points + +.\" macros +.de SAMPLE +.br +.RS +.nf +.nh +.. +.de ESAMPLE +.hy +.fi +.RE +.. + +.SH DESCRIPTION + +This family of probe points is used to probe NFS activities on +server side. Because there is only one function, i.e., nfsd4_proc_compound +in proc level for NFSv4, all the following nfsd.proc probe points except +nfsd.proc.compound are only for NFSv2 and NFSv3. + +It contains the following probe points: + +.P +.TP +.B nfsd.proc.lookup + +Fires whenever client opens/searchs file on server + +.B Arguments: + +.I client_ip + the ip address of client + +.I proto + transfer protocol + +.I version + nfs version + +.I fh + the pointer to file handler of parent dir + +.I filename + file name + +.I filelen + the length of file name + +.P +.TP +.B nfsd.proc.read + +Fires whenever client reads file on server + +.B Arguments: + +.I client_ip + the ip address of client + +.I proto + transfer protocol + +.I version + nfs version + +.I fh + the pointer to file handler of file + +.I count,size + number of bytes to be read + +.I offset + the offset of file + +.I vec + struct kvec ,includes buf address in kernel address + and the length of each buffer + +.I vlen + number of blocks to be read + +.P +.TP +.B nfsd.proc.write + +Fires whenever client writes data to file on server + +.B Arguments: + +.I client_ip + the ip address of client + +.I proto + transfer protocol + +.I version + nfs version + +.I fh + the pointer to file handler of file + +.I count,size + number of bytes to written + +.I offset + the offset of file + +.I vec + struct kvec ,includes buf address in kernel address + and the length of each buffer + +.I vlen + number of blocks to written + +.I stable + argp\->stable(only for nfs.proc3.write) + +.P +.TP +.B nfsd.proc.commit + +Fires whenever client does a commit operation + +.B Arguments: + +.I client_ip + the ip address of client + +.I proto + transfer protocol + +.I version + nfs version + +.I fh + the pointer to file handler of file + +.I count,size + number of bytes to written + +.I offset + the offset of file + +.P +.TP +.B nfsd.proc.create + +Fires whenever client creates a file on server + +.B Arguments: + +.I client_ip + the ip address of client + +.I proto + transfer protocol + +.I version + nfs version + +.I fh + the pointer to file handler of parent dir + +.I filename + file name + +.I filelen + the length of file name + +.P +.TP +.B nfsd.proc.remove + +Fires whenever client removes a file on server + +.B Arguments: + +.I client_ip + the ip address of client + +.I proto + transfer protocol + +.I version + nfs version + +.I fh + the pointer to file handler of file + +.I filename + file name + +.I filelen + the length of file name + +.P +.TP +.B nfsd.proc.rename + +Fires whenever client renames a file on server + +.B Arguments: + +.I client_ip + the ip address of client + +.I proto + transfer protocol + +.I version + nfs version + +.I fh + the pointer to file handler of old path + +.I tfh + the pointer to file handler of new path + +.I filename + old file name + +.I tname + new file name + +.I filelen + the length of old file name + +.I tlen + the length of new file name + +.P +.TP +.B nfsd.proc.compound + +Fires whenever server receives a NFSV4 operation from client + +.B Arguments: + +.I client_ip + the ip address of client + +.I proto + transfer protocol + +.I version + nfs version + +.I num + number of file operation + +.I op + head of operation list + +.P +.TP +.B nfsd.open + +Fires whenever server opens file + +.B Arguments: + +.I fh + file handle (the first part is the length of the file handle) + +.I access + type of open (read/write/commit/readdir...) + +.I type + type of file(regular file or dir) + +.P +.TP +.B nfsd.read + +Fires whenever server reads file + +.B Arguments: + +.I fh + file handle (the first part is the length of the file handle) + +.I file + argument :file, indicates if the file has been opened. + +.I count,size + number of bytes to be read + +.I offset + the offset of file + +.I vec + struct kvec ,includes buf address in kernel address + and the length of each buffer + +.I vlen + number of blocks to be read + +.P +.TP +.B nfsd.write + +Fires whenever server writes file + +.B Arguments: + +.I fh + file handle (the first part is the length of the file handle) + +.I file + argument :file, indicates if the file has been opened. + +.I count,size + number of bytes to be read + +.I offset + the offset of file + +.I vec + struct kvec ,includes buf address in kernel address + and the length of each buffer + +.I vlen + number of blocks to be written + +.P +.TP +.B nfsd.commit + +Fires when server commits all pending writes to stable storage + +.B Arguments: + +.I fh + file handle (the first part is the length of the file handle) + +.I count,size + number of bytes to be read + +.I offset + the offset of file + +.P +.TP +.B nfsd.lookup + +Fires whenever client opens/searchs file on server + +.B Arguments: + +.I fh + file handle (the first part is the length of the file handle) + +.I filename + file name + +.I filelen + the length of file name + +.P +.TP +.B nfsd.create + + Fires when client creates a file(regular,dir,device,fifo) on + server side, sometimes nfsd will call nfsd_create_v3 instead + of this function + +.B Arguments: + +.I fh + file handle (the first part is the length of the file handle) + +.I filename + file name + +.I filelen + the length of file name + +.I type + file type(regular,dir,device,fifo ...) + +.I iap_valid + Attribute flags + +.I iap_mode + file access mod + +.P +.TP +.B nfsd.createv3 + +Fires when client creates a regular file or set file attributes +on server side,only called by nfsd3_proc_create and nfsd4_open +(op_claim_type is NFS4_OPEN_CLAIM_NULL) + +.B Arguments: + +.I fh + file handle (the first part is the length of the file handle) + +.I filename + file name + +.I filelen + the length of file name + +.I iap_valid + Attribute flags + +.I iap_mode + file access mode + +.I createmode + create mode .The possible values could be: + NFS3_CREATE_EXCLUSIVE,NFS3_CREATE_UNCHECKED,NFS3_CREATE_GUARDED + +.I truncp + trunp arguments, indicates if the file shouldbe truncate + +.I verfier + file attributes (atime,mtime,mode).It's used to reset file + attributes for CREATE_EXCLUSIVE + +.P +.TP +.B nfsd.unlink + +Fires when client removes a file or a dir on server side, + +.B Arguments: + +.I fh + file handle (the first part is the length of the file handle) + +.I filename + file name + +.I filelen + the length of file name + +.I type + file type(file or dir) + +.P +.TP +.B nfsd.rename +Fires when clients rename a file on server side + +.B Arguments: + +.I fh + file handler of old path + +.I tfh + file handler of new path + +.I filename + old file name + +.I tname + new file name + +.I flen + length of old file name + +.I tlen + length of new file name + +.P +.TP +.B nfsd.close + +Fires whenever server closes file + +.B Arguments: + +.I filename + file name + +.P +.TP +.B nfsd.dispatch + +Fires whenever server receives NFS operation from client + +.B Arguments: + +.I client_ip + the ip address of client + +.I proto + transfer protocol + +.I version + nfs version + +.I xid + transmission id + +.I prog + program number + +.I proc + procedure number + +.SH SEE ALSO +.IR stap (1), +.IR stapprobes (3stap), + diff --git a/man/stapprobes.nfsd.5.in b/man/stapprobes.nfsd.5.in deleted file mode 100644 index 8d30b38b..00000000 --- a/man/stapprobes.nfsd.5.in +++ /dev/null @@ -1,513 +0,0 @@ -.\" -*- nroff -*- -.TH STAPPROBES.NFSD 5 @DATE@ "IBM" -.SH NAME -stapprobes.nfsd \- systemtap NFS server side probe points - -.\" macros -.de SAMPLE -.br -.RS -.nf -.nh -.. -.de ESAMPLE -.hy -.fi -.RE -.. - -.SH DESCRIPTION - -This family of probe points is used to probe NFS activities on -server side. Because there is only one function, i.e., nfsd4_proc_compound -in proc level for NFSv4, all the following nfsd.proc probe points except -nfsd.proc.compound are only for NFSv2 and NFSv3. - -It contains the following probe points: - -.P -.TP -.B nfsd.proc.lookup - -Fires whenever client opens/searchs file on server - -.B Arguments: - -.I client_ip - the ip address of client - -.I proto - transfer protocol - -.I version - nfs version - -.I fh - the pointer to file handler of parent dir - -.I filename - file name - -.I filelen - the length of file name - -.P -.TP -.B nfsd.proc.read - -Fires whenever client reads file on server - -.B Arguments: - -.I client_ip - the ip address of client - -.I proto - transfer protocol - -.I version - nfs version - -.I fh - the pointer to file handler of file - -.I count,size - number of bytes to be read - -.I offset - the offset of file - -.I vec - struct kvec ,includes buf address in kernel address - and the length of each buffer - -.I vlen - number of blocks to be read - -.P -.TP -.B nfsd.proc.write - -Fires whenever client writes data to file on server - -.B Arguments: - -.I client_ip - the ip address of client - -.I proto - transfer protocol - -.I version - nfs version - -.I fh - the pointer to file handler of file - -.I count,size - number of bytes to written - -.I offset - the offset of file - -.I vec - struct kvec ,includes buf address in kernel address - and the length of each buffer - -.I vlen - number of blocks to written - -.I stable - argp\->stable(only for nfs.proc3.write) - -.P -.TP -.B nfsd.proc.commit - -Fires whenever client does a commit operation - -.B Arguments: - -.I client_ip - the ip address of client - -.I proto - transfer protocol - -.I version - nfs version - -.I fh - the pointer to file handler of file - -.I count,size - number of bytes to written - -.I offset - the offset of file - -.P -.TP -.B nfsd.proc.create - -Fires whenever client creates a file on server - -.B Arguments: - -.I client_ip - the ip address of client - -.I proto - transfer protocol - -.I version - nfs version - -.I fh - the pointer to file handler of parent dir - -.I filename - file name - -.I filelen - the length of file name - -.P -.TP -.B nfsd.proc.remove - -Fires whenever client removes a file on server - -.B Arguments: - -.I client_ip - the ip address of client - -.I proto - transfer protocol - -.I version - nfs version - -.I fh - the pointer to file handler of file - -.I filename - file name - -.I filelen - the length of file name - -.P -.TP -.B nfsd.proc.rename - -Fires whenever client renames a file on server - -.B Arguments: - -.I client_ip - the ip address of client - -.I proto - transfer protocol - -.I version - nfs version - -.I fh - the pointer to file handler of old path - -.I tfh - the pointer to file handler of new path - -.I filename - old file name - -.I tname - new file name - -.I filelen - the length of old file name - -.I tlen - the length of new file name - -.P -.TP -.B nfsd.proc.compound - -Fires whenever server receives a NFSV4 operation from client - -.B Arguments: - -.I client_ip - the ip address of client - -.I proto - transfer protocol - -.I version - nfs version - -.I num - number of file operation - -.I op - head of operation list - -.P -.TP -.B nfsd.open - -Fires whenever server opens file - -.B Arguments: - -.I fh - file handle (the first part is the length of the file handle) - -.I access - type of open (read/write/commit/readdir...) - -.I type - type of file(regular file or dir) - -.P -.TP -.B nfsd.read - -Fires whenever server reads file - -.B Arguments: - -.I fh - file handle (the first part is the length of the file handle) - -.I file - argument :file, indicates if the file has been opened. - -.I count,size - number of bytes to be read - -.I offset - the offset of file - -.I vec - struct kvec ,includes buf address in kernel address - and the length of each buffer - -.I vlen - number of blocks to be read - -.P -.TP -.B nfsd.write - -Fires whenever server writes file - -.B Arguments: - -.I fh - file handle (the first part is the length of the file handle) - -.I file - argument :file, indicates if the file has been opened. - -.I count,size - number of bytes to be read - -.I offset - the offset of file - -.I vec - struct kvec ,includes buf address in kernel address - and the length of each buffer - -.I vlen - number of blocks to be written - -.P -.TP -.B nfsd.commit - -Fires when server commits all pending writes to stable storage - -.B Arguments: - -.I fh - file handle (the first part is the length of the file handle) - -.I count,size - number of bytes to be read - -.I offset - the offset of file - -.P -.TP -.B nfsd.lookup - -Fires whenever client opens/searchs file on server - -.B Arguments: - -.I fh - file handle (the first part is the length of the file handle) - -.I filename - file name - -.I filelen - the length of file name - -.P -.TP -.B nfsd.create - - Fires when client creates a file(regular,dir,device,fifo) on - server side, sometimes nfsd will call nfsd_create_v3 instead - of this function - -.B Arguments: - -.I fh - file handle (the first part is the length of the file handle) - -.I filename - file name - -.I filelen - the length of file name - -.I type - file type(regular,dir,device,fifo ...) - -.I iap_valid - Attribute flags - -.I iap_mode - file access mod - -.P -.TP -.B nfsd.createv3 - -Fires when client creates a regular file or set file attributes -on server side,only called by nfsd3_proc_create and nfsd4_open -(op_claim_type is NFS4_OPEN_CLAIM_NULL) - -.B Arguments: - -.I fh - file handle (the first part is the length of the file handle) - -.I filename - file name - -.I filelen - the length of file name - -.I iap_valid - Attribute flags - -.I iap_mode - file access mode - -.I createmode - create mode .The possible values could be: - NFS3_CREATE_EXCLUSIVE,NFS3_CREATE_UNCHECKED,NFS3_CREATE_GUARDED - -.I truncp - trunp arguments, indicates if the file shouldbe truncate - -.I verfier - file attributes (atime,mtime,mode).It's used to reset file - attributes for CREATE_EXCLUSIVE - -.P -.TP -.B nfsd.unlink - -Fires when client removes a file or a dir on server side, - -.B Arguments: - -.I fh - file handle (the first part is the length of the file handle) - -.I filename - file name - -.I filelen - the length of file name - -.I type - file type(file or dir) - -.P -.TP -.B nfsd.rename -Fires when clients rename a file on server side - -.B Arguments: - -.I fh - file handler of old path - -.I tfh - file handler of new path - -.I filename - old file name - -.I tname - new file name - -.I flen - length of old file name - -.I tlen - length of new file name - -.P -.TP -.B nfsd.close - -Fires whenever server closes file - -.B Arguments: - -.I filename - file name - -.P -.TP -.B nfsd.dispatch - -Fires whenever server receives NFS operation from client - -.B Arguments: - -.I client_ip - the ip address of client - -.I proto - transfer protocol - -.I version - nfs version - -.I xid - transmission id - -.I prog - program number - -.I proc - procedure number - -.SH SEE ALSO -.IR stap (1), -.IR stapprobes (5), - diff --git a/man/stapprobes.pagefault.3stap.in b/man/stapprobes.pagefault.3stap.in new file mode 100644 index 00000000..b1c53a19 --- /dev/null +++ b/man/stapprobes.pagefault.3stap.in @@ -0,0 +1,40 @@ +.\" -*- nroff -*- +.TH STAPPROBES.PAGEFAULT 3stap @DATE@ "IBM" +.SH NAME +stapprobes.pagefault \- systemtap pagefault probe points + +.\" macros +.de SAMPLE +.br +.RS +.nf +.nh +.. +.de ESAMPLE +.hy +.fi +.RE +.. + +.SH DESCRIPTION + +This family of probe points is used to probe page fault events. +It contains the following probe points: + +.P +.TP +.B vm.pagefault +Fires when there is a pagefault + +.B Arguments: + +.I address + The address caused this page fault. + +.I write_access + 1 means this is a write access and 0 means this is a read access + +.SH SEE ALSO +.IR stap (1), +.IR stapprobes (3stap), + diff --git a/man/stapprobes.pagefault.5.in b/man/stapprobes.pagefault.5.in deleted file mode 100644 index ea93f325..00000000 --- a/man/stapprobes.pagefault.5.in +++ /dev/null @@ -1,40 +0,0 @@ -.\" -*- nroff -*- -.TH STAPPROBES.PAGEFAULT 5 @DATE@ "IBM" -.SH NAME -stapprobes.pagefault \- systemtap pagefault probe points - -.\" macros -.de SAMPLE -.br -.RS -.nf -.nh -.. -.de ESAMPLE -.hy -.fi -.RE -.. - -.SH DESCRIPTION - -This family of probe points is used to probe page fault events. -It contains the following probe points: - -.P -.TP -.B vm.pagefault -Fires when there is a pagefault - -.B Arguments: - -.I address - The address caused this page fault. - -.I write_access - 1 means this is a write access and 0 means this is a read access - -.SH SEE ALSO -.IR stap (1), -.IR stapprobes (5), - diff --git a/man/stapprobes.process.3stap.in b/man/stapprobes.process.3stap.in new file mode 100644 index 00000000..3b5e751d --- /dev/null +++ b/man/stapprobes.process.3stap.in @@ -0,0 +1,106 @@ +.\" -*- nroff -*- +.TH STAPPROBES.PROCESS 3stap @DATE@ "Intel, IBM" +.SH NAME +stapprobes.process \- systemtap process probe points + +.\" macros +.de SAMPLE +.br +.RS +.nf +.nh +.. +.de ESAMPLE +.hy +.fi +.RE +.. + +.SH DESCRIPTION + +This family of probe points is used to probe the process activities. +It contains the following probe points: + +.P +.TP +.B process.create + +Fires whenever a new process is successfully created, either as a +result of one of the fork syscall variants, or a new kernel thread. + +.B Arguments: + +.I task + a handle to the newly created process + +.I new_pid + pid of the newly created process + +.P +.TP +.B process.start + +Fires immediately before a new process begins execution. + +.B Arguments: + +.I N/A + +.P +.TP +.B process.exec + +Fires whenever a process attempts to exec to a new program + +.B Arguments: + +.I filename + the path to the new executable + +.P +.TP +.B process.exec_complete + +Fires at the completion of an exec call + +.B Arguments: + +.I errno + the error number resulting from the exec + +.I success + a boolean indicating whether the exec was successful + +.P +.TP +.B process.exit + +Fires when a process terminates. This will always be followed by a +process.release, though the latter may be delayed if the process +waits in a zombie state. + +.B Arguments: + +.I code + the exit code of the process + +.P +.TP +.B process.release + +Fires when a process is released from the kernel. This always +follows a process.exit, though it may be delayed somewhat if the +process waits in a zombie state. + +.B Arguments: + +.I task + a task handle to the process being released + +.I pid + pid of the process being released + +.SH SEE ALSO +.IR stap (1), +.IR stapprobes (3stap), + diff --git a/man/stapprobes.process.5.in b/man/stapprobes.process.5.in deleted file mode 100644 index b725a907..00000000 --- a/man/stapprobes.process.5.in +++ /dev/null @@ -1,106 +0,0 @@ -.\" -*- nroff -*- -.TH STAPPROBES.PROCESS 5 @DATE@ "Intel, IBM" -.SH NAME -stapprobes.process \- systemtap process probe points - -.\" macros -.de SAMPLE -.br -.RS -.nf -.nh -.. -.de ESAMPLE -.hy -.fi -.RE -.. - -.SH DESCRIPTION - -This family of probe points is used to probe the process activities. -It contains the following probe points: - -.P -.TP -.B process.create - -Fires whenever a new process is successfully created, either as a -result of one of the fork syscall variants, or a new kernel thread. - -.B Arguments: - -.I task - a handle to the newly created process - -.I new_pid - pid of the newly created process - -.P -.TP -.B process.start - -Fires immediately before a new process begins execution. - -.B Arguments: - -.I N/A - -.P -.TP -.B process.exec - -Fires whenever a process attempts to exec to a new program - -.B Arguments: - -.I filename - the path to the new executable - -.P -.TP -.B process.exec_complete - -Fires at the completion of an exec call - -.B Arguments: - -.I errno - the error number resulting from the exec - -.I success - a boolean indicating whether the exec was successful - -.P -.TP -.B process.exit - -Fires when a process terminates. This will always be followed by a -process.release, though the latter may be delayed if the process -waits in a zombie state. - -.B Arguments: - -.I code - the exit code of the process - -.P -.TP -.B process.release - -Fires when a process is released from the kernel. This always -follows a process.exit, though it may be delayed somewhat if the -process waits in a zombie state. - -.B Arguments: - -.I task - a task handle to the process being released - -.I pid - pid of the process being released - -.SH SEE ALSO -.IR stap (1), -.IR stapprobes (5), - diff --git a/man/stapprobes.rpc.3stap.in b/man/stapprobes.rpc.3stap.in new file mode 100644 index 00000000..a2622fe5 --- /dev/null +++ b/man/stapprobes.rpc.3stap.in @@ -0,0 +1,583 @@ +.\" -*- nroff -*- +.TH STAPPROBES.RPC 3stap @DATE@ "IBM" +.SH NAME +stapprobes.rpc \- systemtap SunRPC probe points + +.\" macros +.de SAMPLE +.br +.RS +.nf +.nh +.. +.de ESAMPLE +.hy +.fi +.RE +.. + +.SH DESCRIPTION + +This family of probe points is used to probe the SUNRPC activities, +including the client, the server and the sunrpc scheduler. + +It contains the following probe points: + +.P +.TP +.B sunrpc.clnt.create_client +Fires when an RPC client is to be created + +.B Arguments: + +.I servername + The name of the server machine + +.I progname + The name of the RPC program + +.I prog + The number of the RPC program + +.I vers + The version number of the RPC program + +.I prot + The number of the IP protocol + +.I authflavor + The authentication flavor + +.P +.TP +.B sunrpc.clnt.clone_client +Fires when an RPC client structure is to be cloned + +.B Arguments: + +.I servername + The name of the server machine + +.I progname + The name of the RPC program + +.I prog + The number of the RPC program + +.I vers + The version number of the RPC program + +.I prot + The number of the IP protocol + +.I authflavor + The authentication flavor + +.P +.TP +.B sunrpc.clnt.shutdown_client +Fires when an RPC client is to be shut down + +.B Arguments + +.I servername + The name of the server machine + +.I progname + The name of the RPC program + +.I prog + The number of the RPC program + +.I vers + The version number of the RPC program + +.I prot + The number of the IP protocol + +.I authflavor + The authentication flavor + +.I clones + The number of clones + +.I tasks + The number of references + +.I netreconn + The count of reconnections + +.I rpccnt + The count of RPC calls + +.I om_ops + The count of operations + +.I om_ntrans + The count of RPC transmissions + +.I om_bytes_sent + The count of bytes out + +.I om_bytes_recv + The count of bytes in + +.I om_queue + The jiffies queued for transmission + +.I om_rtt + The RPC RTT jiffies + +.I om_execution + The RPC execution jiffies + +.P +.TP +.B sunrpc.clnt.bind_new_program +Fires when a new RPC program is to be bound an existing client + +.B Arguments + +.I servername + The name of the server machine + +.I old_progname + The name of old RPC program + +.I old_prog + The number of old RPC program + +.I old_vers + The version of old RPC program + +.I progname + The name of new RPC program + +.I prog + The number of new RPC program + +.I vers + The version of new RPC program + +.P +.TP +.B sunrpc.clnt.call_sync +Fires when an RPC procedure is to be called synchronously + +.B Arguments + +.I servername + The name of the server machine + +.I progname + The name of the RPC program + +.I prog + The number of the RPC program + +.I vers + The version number of the RPC program + +.I prot + The number of the IP protocol + +.I port + The port number + +.I xid + Current transmission id + +.I dead + Whether this client is abandoned + +.I procname + The procedure name in this RPC call + +.I proc + The procedure number in this RPC call + +.I flags + The flags of this RPC call + +.P +.TP +.B sunrpc.clnt.call_async +Fires when an RPC procedure is to be called asynchronously + +.B Arguments + +.I servername + The name of the server machine + +.I progname + The name of the RPC program + +.I prog + The number of the RPC program + +.I vers + The version number of the RPC program + +.I prot + The number of the IP protocol + +.I port + The port number + +.I xid + Current transmission id + +.I dead + Whether this client is abandoned + +.I procname + The procedure name in this RPC call + +.I proc + The procedure number in this RPC call + +.I flags + The flags of this RPC call + +.P +.TP +.B sunrpc.clnt.restart_call +Fires when an (async) RPC client is to be restarted + +.B Arguments + +.I servername + The name of the server machine + +.I prog + The number of the RPC program + +.I xid + The transmission id + +.I tk_pid + The debugging aid of this task + +.I tk_flags + The task flags + +.I tk_priority + The task priority + +.I tk_runstate + The task run status + +.P +.TP +.B sunrpc.svc.register +Fires when an RPC service is to be registered with the local portmapper. +If proto and port == 0, it means to unregister a service. + +.B Arguments + +.I sv_name + The name of the service + +.I progname + The name of the RPC program + +.I prog + The number of the RPC program + +.I prot + The number of the IP protocol + +.I port + The port number + +.P +.TP +.B sunrpc.svc.create +Fires when an RPC service is to be created + +.B Arguments + +.I progname + The name of the RPC program + +.I prog + The number of the RPC program + +.I pg_nvers + The total of the supported versions + +.I bufsize + The buffer size + +.P +.TP +.B sunrpc.svc.destroy +Fires when an RPC client is to be destroyed + +.B Arguments + +.I sv_name + The service name + +.I sv_progname + The name of the program + +.I sv_prog + The number of the program + +.I sv_nrthreads + The number of concurrent threads + +.I netcnt + The count of received RPC requests + +.I nettcpconn + The count of accepted TCP connections + +.I rpccnt + The count of valid RPC requests + +.I rpcbadfmt + The count of requests dropped for bad formats + +.I rpcbadauth + The count of requests drooped for authentication failure + +.P +.TP +.B sunrpc.svc.process +Fires when an RPC client is to be processed + +.B Arguments + +.I sv_name + The service name + +.I sv_prog + The number of the program + +.I sv_nrthreads + The number of concurrent threads + +.I peer_ip + The peer address where the request is from + +.I rq_xid + The transmission id in the request + +.I rq_prog + The program number in the request + +.I rq_vers + The program version in the request + +.I rq_proc + The procedure number in the request + +.I rq_prot + The IP protocol of the reqeust + +.P +.TP +.B sunrpc.svc.authorise +Fires when an RPC client is to be authorised + +.B Arguments + +.I sv_name + The service name + +.I peer_ip + The peer address where the request is from + +.I rq_xid + The transmission id in the request + +.I rq_prog + The program number in the request + +.I rq_vers + The program version in the request + +.I rq_proc + The procedure number in the request + +.I rq_prot + The IP protocol of the reqeust + +.P +.TP +.B sunrpc.svc.recv +Fires when the server is to receive the next request on any socket + +.B Arguments + +.I sv_name + The service name + +.I sv_prog + The number of the program + +.I sv_nrthreads + The number of concurrent threads + +.I timeout + The timeout of waiting for data + +.P +.TP +.B sunrpc.svc.send +Fires when want to return reply to client + +.B Arguments + +.I sv_name + The service name + +.I peer_ip + The peer address where the request is from + +.I rq_xid + The transmission id in the request + +.I rq_prog + The program number in the request + +.I rq_vers + The program version in the request + +.I rq_proc + The procedure number in the request + +.I rq_prot + The IP protocol of the reqeust + +.P +.TP +.B sunrpc.svc.drop +Fires when a request is to be dropped + +.B Arguments + +.I sv_name + The service name + +.I peer_ip + The peer address where the request is from + +.I rq_xid + The transmission id in the request + +.I rq_prog + The program number in the request + +.I rq_vers + The program version in the request + +.I rq_proc + The procedure number in the request + +.I rq_prot + The IP protocol of the reqeust + +.P +.TP +.B sunrpc.sched.new_task +Fires when a new task is to be created for the specified client + +.B Arguments +.I xid + The transmission id in the RPC call + +.I prog + The program number in the RPC call + +.I vers + The program version in the RPC call + +.I prot + The IP protocol in the RPC call + +.I tk_flags + The flags of the task + +.P +.TP +.B sunrpc.sched.release_task +Fires when all resources associated with a task are to be released + +.B Arguments + +.I xid + The transmission id in the RPC call + +.I prog + The program number in the RPC call + +.I vers + The program version in the RPC call + +.I prot + The IP protocol in the RPC call + +.I tk_flags + The flags of the task + +.P +.TP +.B sunrpc.sched.execute +Fires when the RPC `scheduler'(or rather, the finite state machine) +is to be executed + +.B Arguments + +.I xid + The transmission id in the RPC call + +.I prog + The program number in the RPC call + +.I vers + The program version in the RPC call + +.I prot + The IP protocol in the RPC call + +.I tk_pid + The debugging id of the task + +.I tk_flags + The flags of the task + +.P +.TP +.B sunrpc.sched.delay +Fires when a task is to be delayed + +.B Arguments + +.I xid + The transmission id in the RPC call + +.I prog + The program number in the RPC call + +.I vers + The program version in the RPC call + +.I prot + The IP protocol in the RPC call + +.I tk_pid + The debugging id of the task + +.I tk_flags + The flags of the task + +.I delay + The time delayed + +.SH SEE ALSO +.IR stap (1), +.IR stapprobes (3stap), + diff --git a/man/stapprobes.rpc.5.in b/man/stapprobes.rpc.5.in deleted file mode 100644 index 7f411de6..00000000 --- a/man/stapprobes.rpc.5.in +++ /dev/null @@ -1,583 +0,0 @@ -.\" -*- nroff -*- -.TH STAPPROBES.RPC 5 @DATE@ "IBM" -.SH NAME -stapprobes.rpc \- systemtap SunRPC probe points - -.\" macros -.de SAMPLE -.br -.RS -.nf -.nh -.. -.de ESAMPLE -.hy -.fi -.RE -.. - -.SH DESCRIPTION - -This family of probe points is used to probe the SUNRPC activities, -including the client, the server and the sunrpc scheduler. - -It contains the following probe points: - -.P -.TP -.B sunrpc.clnt.create_client -Fires when an RPC client is to be created - -.B Arguments: - -.I servername - The name of the server machine - -.I progname - The name of the RPC program - -.I prog - The number of the RPC program - -.I vers - The version number of the RPC program - -.I prot - The number of the IP protocol - -.I authflavor - The authentication flavor - -.P -.TP -.B sunrpc.clnt.clone_client -Fires when an RPC client structure is to be cloned - -.B Arguments: - -.I servername - The name of the server machine - -.I progname - The name of the RPC program - -.I prog - The number of the RPC program - -.I vers - The version number of the RPC program - -.I prot - The number of the IP protocol - -.I authflavor - The authentication flavor - -.P -.TP -.B sunrpc.clnt.shutdown_client -Fires when an RPC client is to be shut down - -.B Arguments - -.I servername - The name of the server machine - -.I progname - The name of the RPC program - -.I prog - The number of the RPC program - -.I vers - The version number of the RPC program - -.I prot - The number of the IP protocol - -.I authflavor - The authentication flavor - -.I clones - The number of clones - -.I tasks - The number of references - -.I netreconn - The count of reconnections - -.I rpccnt - The count of RPC calls - -.I om_ops - The count of operations - -.I om_ntrans - The count of RPC transmissions - -.I om_bytes_sent - The count of bytes out - -.I om_bytes_recv - The count of bytes in - -.I om_queue - The jiffies queued for transmission - -.I om_rtt - The RPC RTT jiffies - -.I om_execution - The RPC execution jiffies - -.P -.TP -.B sunrpc.clnt.bind_new_program -Fires when a new RPC program is to be bound an existing client - -.B Arguments - -.I servername - The name of the server machine - -.I old_progname - The name of old RPC program - -.I old_prog - The number of old RPC program - -.I old_vers - The version of old RPC program - -.I progname - The name of new RPC program - -.I prog - The number of new RPC program - -.I vers - The version of new RPC program - -.P -.TP -.B sunrpc.clnt.call_sync -Fires when an RPC procedure is to be called synchronously - -.B Arguments - -.I servername - The name of the server machine - -.I progname - The name of the RPC program - -.I prog - The number of the RPC program - -.I vers - The version number of the RPC program - -.I prot - The number of the IP protocol - -.I port - The port number - -.I xid - Current transmission id - -.I dead - Whether this client is abandoned - -.I procname - The procedure name in this RPC call - -.I proc - The procedure number in this RPC call - -.I flags - The flags of this RPC call - -.P -.TP -.B sunrpc.clnt.call_async -Fires when an RPC procedure is to be called asynchronously - -.B Arguments - -.I servername - The name of the server machine - -.I progname - The name of the RPC program - -.I prog - The number of the RPC program - -.I vers - The version number of the RPC program - -.I prot - The number of the IP protocol - -.I port - The port number - -.I xid - Current transmission id - -.I dead - Whether this client is abandoned - -.I procname - The procedure name in this RPC call - -.I proc - The procedure number in this RPC call - -.I flags - The flags of this RPC call - -.P -.TP -.B sunrpc.clnt.restart_call -Fires when an (async) RPC client is to be restarted - -.B Arguments - -.I servername - The name of the server machine - -.I prog - The number of the RPC program - -.I xid - The transmission id - -.I tk_pid - The debugging aid of this task - -.I tk_flags - The task flags - -.I tk_priority - The task priority - -.I tk_runstate - The task run status - -.P -.TP -.B sunrpc.svc.register -Fires when an RPC service is to be registered with the local portmapper. -If proto and port == 0, it means to unregister a service. - -.B Arguments - -.I sv_name - The name of the service - -.I progname - The name of the RPC program - -.I prog - The number of the RPC program - -.I prot - The number of the IP protocol - -.I port - The port number - -.P -.TP -.B sunrpc.svc.create -Fires when an RPC service is to be created - -.B Arguments - -.I progname - The name of the RPC program - -.I prog - The number of the RPC program - -.I pg_nvers - The total of the supported versions - -.I bufsize - The buffer size - -.P -.TP -.B sunrpc.svc.destroy -Fires when an RPC client is to be destroyed - -.B Arguments - -.I sv_name - The service name - -.I sv_progname - The name of the program - -.I sv_prog - The number of the program - -.I sv_nrthreads - The number of concurrent threads - -.I netcnt - The count of received RPC requests - -.I nettcpconn - The count of accepted TCP connections - -.I rpccnt - The count of valid RPC requests - -.I rpcbadfmt - The count of requests dropped for bad formats - -.I rpcbadauth - The count of requests drooped for authentication failure - -.P -.TP -.B sunrpc.svc.process -Fires when an RPC client is to be processed - -.B Arguments - -.I sv_name - The service name - -.I sv_prog - The number of the program - -.I sv_nrthreads - The number of concurrent threads - -.I peer_ip - The peer address where the request is from - -.I rq_xid - The transmission id in the request - -.I rq_prog - The program number in the request - -.I rq_vers - The program version in the request - -.I rq_proc - The procedure number in the request - -.I rq_prot - The IP protocol of the reqeust - -.P -.TP -.B sunrpc.svc.authorise -Fires when an RPC client is to be authorised - -.B Arguments - -.I sv_name - The service name - -.I peer_ip - The peer address where the request is from - -.I rq_xid - The transmission id in the request - -.I rq_prog - The program number in the request - -.I rq_vers - The program version in the request - -.I rq_proc - The procedure number in the request - -.I rq_prot - The IP protocol of the reqeust - -.P -.TP -.B sunrpc.svc.recv -Fires when the server is to receive the next request on any socket - -.B Arguments - -.I sv_name - The service name - -.I sv_prog - The number of the program - -.I sv_nrthreads - The number of concurrent threads - -.I timeout - The timeout of waiting for data - -.P -.TP -.B sunrpc.svc.send -Fires when want to return reply to client - -.B Arguments - -.I sv_name - The service name - -.I peer_ip - The peer address where the request is from - -.I rq_xid - The transmission id in the request - -.I rq_prog - The program number in the request - -.I rq_vers - The program version in the request - -.I rq_proc - The procedure number in the request - -.I rq_prot - The IP protocol of the reqeust - -.P -.TP -.B sunrpc.svc.drop -Fires when a request is to be dropped - -.B Arguments - -.I sv_name - The service name - -.I peer_ip - The peer address where the request is from - -.I rq_xid - The transmission id in the request - -.I rq_prog - The program number in the request - -.I rq_vers - The program version in the request - -.I rq_proc - The procedure number in the request - -.I rq_prot - The IP protocol of the reqeust - -.P -.TP -.B sunrpc.sched.new_task -Fires when a new task is to be created for the specified client - -.B Arguments -.I xid - The transmission id in the RPC call - -.I prog - The program number in the RPC call - -.I vers - The program version in the RPC call - -.I prot - The IP protocol in the RPC call - -.I tk_flags - The flags of the task - -.P -.TP -.B sunrpc.sched.release_task -Fires when all resources associated with a task are to be released - -.B Arguments - -.I xid - The transmission id in the RPC call - -.I prog - The program number in the RPC call - -.I vers - The program version in the RPC call - -.I prot - The IP protocol in the RPC call - -.I tk_flags - The flags of the task - -.P -.TP -.B sunrpc.sched.execute -Fires when the RPC `scheduler'(or rather, the finite state machine) -is to be executed - -.B Arguments - -.I xid - The transmission id in the RPC call - -.I prog - The program number in the RPC call - -.I vers - The program version in the RPC call - -.I prot - The IP protocol in the RPC call - -.I tk_pid - The debugging id of the task - -.I tk_flags - The flags of the task - -.P -.TP -.B sunrpc.sched.delay -Fires when a task is to be delayed - -.B Arguments - -.I xid - The transmission id in the RPC call - -.I prog - The program number in the RPC call - -.I vers - The program version in the RPC call - -.I prot - The IP protocol in the RPC call - -.I tk_pid - The debugging id of the task - -.I tk_flags - The flags of the task - -.I delay - The time delayed - -.SH SEE ALSO -.IR stap (1), -.IR stapprobes (5), - diff --git a/man/stapprobes.scsi.3stap.in b/man/stapprobes.scsi.3stap.in new file mode 100644 index 00000000..b595105a --- /dev/null +++ b/man/stapprobes.scsi.3stap.in @@ -0,0 +1,151 @@ +.\" -*- nroff -*- +.TH STAPPROBES.SCSI 3stap @DATE@ "IBM" +.SH NAME +stapprobes.scsi \- systemtap scsi probe points + +.\" macros +.de SAMPLE +.br +.RS +.nf +.nh +.. +.de ESAMPLE +.hy +.fi +.RE +.. + +.SH DESCRIPTION + +This family of probe points is used to probe the SCSI activities. +It contains the following probe points: + +.P +.TP +.B scsi.ioentry +Fires when SCSI mid layer prepares a SCSI request + +.B Arguments: + +.I disk_major + The major number of the disk + +.I disk_minor + The minor number of the disk + +.I device_state + The current state of the device. The possible values could be: + + SDEV_CREATED = 1, /* device created but not added to sysfs + * Only internal commands allowed (for inq) */ + SDEV_RUNNING = 2, /* device properly configured + * All commands allowed */ + SDEV_CANCEL = 3, /* beginning to delete device + * Only error handler commands allowed */ + SDEV_DEL = 4, /* device deleted + * no commands allowed */ + SDEV_QUIESCE = 5, /* Device quiescent. No block commands + * will be accepted, only specials (which + * originate in the mid-layer) */ + SDEV_OFFLINE = 6, /* Device offlined (by error handling or + * user request */ + SDEV_BLOCK = 7, /* Device blocked by scsi lld. No scsi + * commands from user or midlayer should be issued + * to the scsi lld. */ + +.P +.TP +.B scsi.iodispatching +Fires when the SCSI mid layer dispatches a SCSI command to the low level driver + +.B Arguments: + +.I host_no + The host number + +.I channel + The channel number + +.I lun + The lun number + +.I dev_id + The scsi device id + +.I device_state + The current state of the device. + +.I data_direction + The data_direction specifies whether this command is from/to the device. + The possible values could be: + + DMA_BIDIRECTIONAL = 0, + DMA_TO_DEVICE = 1, + DMA_FROM_DEVICE = 2, + DMA_NONE = 3, + +.I request_buffer + The request buffer address + +.I req_bufflen + The request buffer length + +.P +.TP +.B scsi.iodone +Fires when a SCSI command is done by low level driver and enqueued into the done queue. + +.B Arguments: + +.I host_no + The host number + +.I channel + The channel number + +.I lun + The lun number + +.I dev_id + The scsi device id + +.I device_state + The current state of the device + +.I data_direction + The data_direction specifies whether this command is from/to the device. + +.P +.TP +.B scsi.iocompleted +Fires when SCSI mid layer runs the completion processing for +block device I/O requests + +.B Arguments: + +.I host_no + The host number + +.I channel + The channel number + +.I lun + The lun number + +.I dev_id + The scsi device id + +.I device_state + The current state of the device + +.I data_direction + The data_direction specifies whether this command is from/to the device. + +.I goodbytes + The bytes completed. + +.SH SEE ALSO +.IR stap (1), +.IR stapprobes (3stap), + diff --git a/man/stapprobes.scsi.5.in b/man/stapprobes.scsi.5.in deleted file mode 100644 index bbebcc81..00000000 --- a/man/stapprobes.scsi.5.in +++ /dev/null @@ -1,151 +0,0 @@ -.\" -*- nroff -*- -.TH STAPPROBES.SCSI 5 @DATE@ "IBM" -.SH NAME -stapprobes.scsi \- systemtap scsi probe points - -.\" macros -.de SAMPLE -.br -.RS -.nf -.nh -.. -.de ESAMPLE -.hy -.fi -.RE -.. - -.SH DESCRIPTION - -This family of probe points is used to probe the SCSI activities. -It contains the following probe points: - -.P -.TP -.B scsi.ioentry -Fires when SCSI mid layer prepares a SCSI request - -.B Arguments: - -.I disk_major - The major number of the disk - -.I disk_minor - The minor number of the disk - -.I device_state - The current state of the device. The possible values could be: - - SDEV_CREATED = 1, /* device created but not added to sysfs - * Only internal commands allowed (for inq) */ - SDEV_RUNNING = 2, /* device properly configured - * All commands allowed */ - SDEV_CANCEL = 3, /* beginning to delete device - * Only error handler commands allowed */ - SDEV_DEL = 4, /* device deleted - * no commands allowed */ - SDEV_QUIESCE = 5, /* Device quiescent. No block commands - * will be accepted, only specials (which - * originate in the mid-layer) */ - SDEV_OFFLINE = 6, /* Device offlined (by error handling or - * user request */ - SDEV_BLOCK = 7, /* Device blocked by scsi lld. No scsi - * commands from user or midlayer should be issued - * to the scsi lld. */ - -.P -.TP -.B scsi.iodispatching -Fires when the SCSI mid layer dispatches a SCSI command to the low level driver - -.B Arguments: - -.I host_no - The host number - -.I channel - The channel number - -.I lun - The lun number - -.I dev_id - The scsi device id - -.I device_state - The current state of the device. - -.I data_direction - The data_direction specifies whether this command is from/to the device. - The possible values could be: - - DMA_BIDIRECTIONAL = 0, - DMA_TO_DEVICE = 1, - DMA_FROM_DEVICE = 2, - DMA_NONE = 3, - -.I request_buffer - The request buffer address - -.I req_bufflen - The request buffer length - -.P -.TP -.B scsi.iodone -Fires when a SCSI command is done by low level driver and enqueued into the done queue. - -.B Arguments: - -.I host_no - The host number - -.I channel - The channel number - -.I lun - The lun number - -.I dev_id - The scsi device id - -.I device_state - The current state of the device - -.I data_direction - The data_direction specifies whether this command is from/to the device. - -.P -.TP -.B scsi.iocompleted -Fires when SCSI mid layer runs the completion processing for -block device I/O requests - -.B Arguments: - -.I host_no - The host number - -.I channel - The channel number - -.I lun - The lun number - -.I dev_id - The scsi device id - -.I device_state - The current state of the device - -.I data_direction - The data_direction specifies whether this command is from/to the device. - -.I goodbytes - The bytes completed. - -.SH SEE ALSO -.IR stap (1), -.IR stapprobes (5), - diff --git a/man/stapprobes.signal.3stap.in b/man/stapprobes.signal.3stap.in new file mode 100644 index 00000000..f42a7781 --- /dev/null +++ b/man/stapprobes.signal.3stap.in @@ -0,0 +1,509 @@ +.\" -*- nroff -*- +.TH STAPPROBES.SIGNAL 3stap @DATE@ "IBM" +.SH NAME +stapprobes.signal \- systemtap signal probe points + +.\" macros +.de SAMPLE +.br +.RS +.nf +.nh +.. +.de ESAMPLE +.hy +.fi +.RE +.. + +.SH DESCRIPTION + +This family of probe points is used to probe signal activities. +It contains the following probe points: + +.P +.TP +.B signal.send + +Fires when a signal is sent to a process + +.B Arguments: + +.I sig + signal number + +.I sig_name + a string representation of the signal + +.I sig_pid + pid of the signal recipient process + +.I pid_name + name of the signal recipient process + +.I si_code + indicates the signal type + +.I task + a task handle to the signal recipient + +.I sinfo + the address of siginfo struct + +.I shared + indicates whether this signal is shared by the thread group + +.I send2queue + indicates whether this signal is sent to an existing sigqueue + +.I name + name of the function used to send out this signal + +.P +.TP +.B signal.send.return + +Fires when return from sending a signal + +.B Arguments: + +.I retstr + the return value + + Return values for "__group_send_sig_info" and "specific_send_sig_info" + +.RS +.RS +- return 0 if the signal is sucessfully sent to a process, +which means the following: + +<1> the signal is ignored by receiving process + +<2> this is a non-RT signal and we already have one queued + +<3> the signal is successfully added into the sigqueue of receiving process + +- return \-EAGAIN if the sigqueue is overflow the signal was RT and sent +by user using something other than kill() +.RE + + Return values for "send_group_sigqueue" + +.RS +- return 0 if the signal is either sucessfully added into the +sigqueue of receiving process or a SI_TIMER entry is already +queued so just increment the overrun count + +- return 1 if this signal is ignored by receiving process +.RE + + Return values for "send_sigqueue" + +.RS +- return 0 if the signal is either sucessfully added into the +sigqueue of receiving process or a SI_TIMER entry is already +queued so just increment the overrun count + +- return 1 if this signal is ignored by receiving process + +- return \-1 if the task is marked exiting, so posix_timer_event +can redirect it to the group leader +.RE + +.I shared + indicates whether this signal is shared by the thread group + +.I send2queue + indicates whether this signal is sent to an existing sigqueue + +.I name + name of the function used to send out this signal + + +.RE +.RE +.P +.TP +.B signal.checkperm + +Fires when check permissions for sending the signal + +.B Arguments: + +.I sig + the number of the signal + +.I sig_name + a string representation of the signal + +.I sig_pid + pid of the signal recipient process + +.I pid_name + name of the signal recipient process + +.I si_code + indicates the signal type + +.I task + a task handle to the signal recipient + +.I sinfo + the address of siginfo struct + +.I name + name of the probe point, is set to "signal.checkperm" + +.P +.TP +.B signal.checkperm.return + +Fires when return from permissions check for sending a signal + +.B Arguments: + +.I retstr + the return value + +.I name + name of the probe point, is set to "signal.checkperm" + +.P +.TP +.B signal.wakeup + +Fires when wake up the process for new active signals + +.B Arguments: + +.I sig_pid + pid of the process to be woke up + +.I pid_name + name of the process to be woke up + +.I resume + indicate whether to wake up a task in STOPPED or TRACED state + +.I state_mask + a string representation indicate the mask of task states +that can be woken. Possible values are +(TASK_INTERRUPTIBLE|TASK_STOPPED|TASK_TRACED) and +TASK_INTERRUPTIBLE. + +.P +.TP +.B signal.check_ignored + +Fires when check whether the signal is ignored or not + +.B Arguments: + +.I sig_pid + pid of the signal recipient process + +.I pid_name + name of the signal recipient process + +.I sig + the signal to be checked + +.I sig_name + name of the signal + +.P +.TP +.B signal.check_ignored.return + +Fires when return from signal.check_ignored + +.B Arguments: + +.I retstr + return value. 0 indicate the current signal isn't ignored. + +.P +.TP +.B signal.force_segv + +Forces SIGSEGV when there are some issues while handling +signals for the process + +.B Arguments: + +.I sig_pid + pid of the signal recipient process + +.I pid_name + name of the signal recipient process + +.I sig + the signal being handled + +.I sig_name + name of this signal + +.P +.TP +.B signal.force_segv.return + +Fires when return from signal.force_segv + +.B Arguments: + +.I retstr + return value. Always return 0 + +.P +.TP +.B signal.syskill + +Fires when sys_kill is called to send a signal to a process. + +.B Arguments: + +.I pid + pid of the recipient process + +.I sig + the signal to be sent + +.P +.TP +.B signal.syskill.return + +Fires when returning from sys_kill + +.P +.TP +.B signal.tgkill + +Fires when sys_tgkill is called to send a signal to one specific thread + +.B Arguments: + +.I pid + pid of the recipient thread + +.I tgid + thread group id which the target thread should have + +.I sig + the signal to be sent + +.P +.TP +.B signal.tgkill.return + +Fires when returning from sys_tgkill + +.P +.TP +.B signal.tkill + +Fires when sys_tkill is called to send a signal to a single process. + +.B Arguments: + +.I pid + pid of the recipient process + +.I sig + the signal to be sent + +.P +.TP +.B signal.tkill.return + +Fires when returning from sys_tkill + +.P +.TP +.B signal.send_sig_queue + +Fires when queue a signal to a process + +.B Arguments: + +.I sig + the signal to be queued + +.I sig_name + name of this signal + +.I sig_pid + pid of the process to which the signal is queued + +.I pid_name + name of the process to which the signal is queued + +.I sigqueue_addr + address of the signal queue + +.P +.TP +.B signal.send_sig_queue.return + +Fires when return from signal.send_sig_queue + +.B Arguments: + +.I retstr + return value + +.P +.TP +.B signal.pending + +Fires when examine the set of signals that are +pending for delivery to the calling thread + +.B Arguments: + +.I sigset_add + address of user space sigset_t + +.I sigset_size + sigset size + +.P +.TP +.B signal.pending.return + +Fires when return from signal.pending + +.B Arguments: + +.I retstr + return value + +.P +.TP +.B signal.handle + +Fires when invoking the signal handler + +.B Arguments: + +.I sig + signal number + +.I sig_name + signal name + +.I sinfo + address of siginfo struct + +.I sig_code + the si_code of siginfo + +.I ka_addr + Address of the k_sigaction struct associated with the signal + +.I oldset_addr + Address of a bit mask array of blocked signals + +.I sig_mode + indicates whether the signal is a User Mode or Kernel mode Signal + +.P +.TP +.B signal.handle.return + +Fires when return from signal.handle + +.B Arguments: + +.I retstr + return value of handle_signal() + +.P +.TP +.B signal.do_action + +Fires by calling thread to examine and change a signal action + +.B Arguments: + +.I sig + signal number + +.I sigact_addr + address of the new sigaction struct associated with the signal + +.I oldsigact_addr + address of a previous sigaction struct associated with the signal + +.I sa_handler + the new handler of the signal + +.I sa_mask + the new mask of the signal + +.P +.TP +.B signal.do_action.return + +Fires when return from signal.do_action + +.B Arguments: + +.I retstr + return value of do_sigaction() + +.P +.TP +.B signal.procmask + +Fires by calling thread to examine and change blocked signals + +.B Arguments: + +.I how + indicates how to change the blocked signals. + Possible values are: + SIG_BLOCK=0 for blocking signals + SIG_UNBLOCK=1 for unblocking signals + SIG_SETMASK=2 for setting the signal mask + +.I sigset_addr + address of sigset_t to be set + +.I oldsigset_addr + address of the old sigset_t + +.I sigset + the actual sigset to be set + +.P +.TP +.B signal.procmask.return + +Fires when return from signal.procmask + +.B Arguments: + +.I retstr + return value of sigprocmask() + +.P +.TP +.B signal.flush + +Fires when flush all pending signals for a task + +.B Arguments: + +.I task + the task handler of the process + +.I sig_pid + pid of the task + +.I pid_name + name of the task + +.SH SEE ALSO +.IR stap (1), +.IR stapprobes (3stap), + diff --git a/man/stapprobes.signal.5.in b/man/stapprobes.signal.5.in deleted file mode 100644 index dc669b0c..00000000 --- a/man/stapprobes.signal.5.in +++ /dev/null @@ -1,509 +0,0 @@ -.\" -*- nroff -*- -.TH STAPPROBES.SIGNAL 5 @DATE@ "IBM" -.SH NAME -stapprobes.signal \- systemtap signal probe points - -.\" macros -.de SAMPLE -.br -.RS -.nf -.nh -.. -.de ESAMPLE -.hy -.fi -.RE -.. - -.SH DESCRIPTION - -This family of probe points is used to probe signal activities. -It contains the following probe points: - -.P -.TP -.B signal.send - -Fires when a signal is sent to a process - -.B Arguments: - -.I sig - signal number - -.I sig_name - a string representation of the signal - -.I sig_pid - pid of the signal recipient process - -.I pid_name - name of the signal recipient process - -.I si_code - indicates the signal type - -.I task - a task handle to the signal recipient - -.I sinfo - the address of siginfo struct - -.I shared - indicates whether this signal is shared by the thread group - -.I send2queue - indicates whether this signal is sent to an existing sigqueue - -.I name - name of the function used to send out this signal - -.P -.TP -.B signal.send.return - -Fires when return from sending a signal - -.B Arguments: - -.I retstr - the return value - - Return values for "__group_send_sig_info" and "specific_send_sig_info" - -.RS -.RS -- return 0 if the signal is sucessfully sent to a process, -which means the following: - -<1> the signal is ignored by receiving process - -<2> this is a non-RT signal and we already have one queued - -<3> the signal is successfully added into the sigqueue of receiving process - -- return \-EAGAIN if the sigqueue is overflow the signal was RT and sent -by user using something other than kill() -.RE - - Return values for "send_group_sigqueue" - -.RS -- return 0 if the signal is either sucessfully added into the -sigqueue of receiving process or a SI_TIMER entry is already -queued so just increment the overrun count - -- return 1 if this signal is ignored by receiving process -.RE - - Return values for "send_sigqueue" - -.RS -- return 0 if the signal is either sucessfully added into the -sigqueue of receiving process or a SI_TIMER entry is already -queued so just increment the overrun count - -- return 1 if this signal is ignored by receiving process - -- return \-1 if the task is marked exiting, so posix_timer_event -can redirect it to the group leader -.RE - -.I shared - indicates whether this signal is shared by the thread group - -.I send2queue - indicates whether this signal is sent to an existing sigqueue - -.I name - name of the function used to send out this signal - - -.RE -.RE -.P -.TP -.B signal.checkperm - -Fires when check permissions for sending the signal - -.B Arguments: - -.I sig - the number of the signal - -.I sig_name - a string representation of the signal - -.I sig_pid - pid of the signal recipient process - -.I pid_name - name of the signal recipient process - -.I si_code - indicates the signal type - -.I task - a task handle to the signal recipient - -.I sinfo - the address of siginfo struct - -.I name - name of the probe point, is set to "signal.checkperm" - -.P -.TP -.B signal.checkperm.return - -Fires when return from permissions check for sending a signal - -.B Arguments: - -.I retstr - the return value - -.I name - name of the probe point, is set to "signal.checkperm" - -.P -.TP -.B signal.wakeup - -Fires when wake up the process for new active signals - -.B Arguments: - -.I sig_pid - pid of the process to be woke up - -.I pid_name - name of the process to be woke up - -.I resume - indicate whether to wake up a task in STOPPED or TRACED state - -.I state_mask - a string representation indicate the mask of task states -that can be woken. Possible values are -(TASK_INTERRUPTIBLE|TASK_STOPPED|TASK_TRACED) and -TASK_INTERRUPTIBLE. - -.P -.TP -.B signal.check_ignored - -Fires when check whether the signal is ignored or not - -.B Arguments: - -.I sig_pid - pid of the signal recipient process - -.I pid_name - name of the signal recipient process - -.I sig - the signal to be checked - -.I sig_name - name of the signal - -.P -.TP -.B signal.check_ignored.return - -Fires when return from signal.check_ignored - -.B Arguments: - -.I retstr - return value. 0 indicate the current signal isn't ignored. - -.P -.TP -.B signal.force_segv - -Forces SIGSEGV when there are some issues while handling -signals for the process - -.B Arguments: - -.I sig_pid - pid of the signal recipient process - -.I pid_name - name of the signal recipient process - -.I sig - the signal being handled - -.I sig_name - name of this signal - -.P -.TP -.B signal.force_segv.return - -Fires when return from signal.force_segv - -.B Arguments: - -.I retstr - return value. Always return 0 - -.P -.TP -.B signal.syskill - -Fires when sys_kill is called to send a signal to a process. - -.B Arguments: - -.I pid - pid of the recipient process - -.I sig - the signal to be sent - -.P -.TP -.B signal.syskill.return - -Fires when returning from sys_kill - -.P -.TP -.B signal.tgkill - -Fires when sys_tgkill is called to send a signal to one specific thread - -.B Arguments: - -.I pid - pid of the recipient thread - -.I tgid - thread group id which the target thread should have - -.I sig - the signal to be sent - -.P -.TP -.B signal.tgkill.return - -Fires when returning from sys_tgkill - -.P -.TP -.B signal.tkill - -Fires when sys_tkill is called to send a signal to a single process. - -.B Arguments: - -.I pid - pid of the recipient process - -.I sig - the signal to be sent - -.P -.TP -.B signal.tkill.return - -Fires when returning from sys_tkill - -.P -.TP -.B signal.send_sig_queue - -Fires when queue a signal to a process - -.B Arguments: - -.I sig - the signal to be queued - -.I sig_name - name of this signal - -.I sig_pid - pid of the process to which the signal is queued - -.I pid_name - name of the process to which the signal is queued - -.I sigqueue_addr - address of the signal queue - -.P -.TP -.B signal.send_sig_queue.return - -Fires when return from signal.send_sig_queue - -.B Arguments: - -.I retstr - return value - -.P -.TP -.B signal.pending - -Fires when examine the set of signals that are -pending for delivery to the calling thread - -.B Arguments: - -.I sigset_add - address of user space sigset_t - -.I sigset_size - sigset size - -.P -.TP -.B signal.pending.return - -Fires when return from signal.pending - -.B Arguments: - -.I retstr - return value - -.P -.TP -.B signal.handle - -Fires when invoking the signal handler - -.B Arguments: - -.I sig - signal number - -.I sig_name - signal name - -.I sinfo - address of siginfo struct - -.I sig_code - the si_code of siginfo - -.I ka_addr - Address of the k_sigaction struct associated with the signal - -.I oldset_addr - Address of a bit mask array of blocked signals - -.I sig_mode - indicates whether the signal is a User Mode or Kernel mode Signal - -.P -.TP -.B signal.handle.return - -Fires when return from signal.handle - -.B Arguments: - -.I retstr - return value of handle_signal() - -.P -.TP -.B signal.do_action - -Fires by calling thread to examine and change a signal action - -.B Arguments: - -.I sig - signal number - -.I sigact_addr - address of the new sigaction struct associated with the signal - -.I oldsigact_addr - address of a previous sigaction struct associated with the signal - -.I sa_handler - the new handler of the signal - -.I sa_mask - the new mask of the signal - -.P -.TP -.B signal.do_action.return - -Fires when return from signal.do_action - -.B Arguments: - -.I retstr - return value of do_sigaction() - -.P -.TP -.B signal.procmask - -Fires by calling thread to examine and change blocked signals - -.B Arguments: - -.I how - indicates how to change the blocked signals. - Possible values are: - SIG_BLOCK=0 for blocking signals - SIG_UNBLOCK=1 for unblocking signals - SIG_SETMASK=2 for setting the signal mask - -.I sigset_addr - address of sigset_t to be set - -.I oldsigset_addr - address of the old sigset_t - -.I sigset - the actual sigset to be set - -.P -.TP -.B signal.procmask.return - -Fires when return from signal.procmask - -.B Arguments: - -.I retstr - return value of sigprocmask() - -.P -.TP -.B signal.flush - -Fires when flush all pending signals for a task - -.B Arguments: - -.I task - the task handler of the process - -.I sig_pid - pid of the task - -.I pid_name - name of the task - -.SH SEE ALSO -.IR stap (1), -.IR stapprobes (5), - diff --git a/man/stapprobes.socket.3stap.in b/man/stapprobes.socket.3stap.in new file mode 100644 index 00000000..6124e7b7 --- /dev/null +++ b/man/stapprobes.socket.3stap.in @@ -0,0 +1,485 @@ +.\" -*- nroff -*- +.TH STAPPROBES.SOCKET 3stap @DATE@ "IBM" +.SH NAME +stapprobes.socket \- systemtap socket probe points + +.\" macros +.de SAMPLE +.br +.RS +.nf +.nh +.. +.de ESAMPLE +.hy +.fi +.RE +.. + +.SH DESCRIPTION + +This family of probe points is used to probe socket activities. +It contains the following probe points: + +.P +.TP +.B socket.send + +Fires at the conclusion of sending a message on a socket. +This probe alias includes the +.B socket.sendmsg.return, +.B socket.aio_write.return +and +.B socket.writev.return +probes (these probes should +catch all messages sent on sockets). The arguments supplied at the beginning +of the send are cached and made available in this probe. + +.B Context: + +The message sender. + +.B Arguments: + +.I name + Name of this probe. + +.I size + Size of message sent (in bytes) or error code if success == 0 + +.I protocol + Protocol used on the socket. Use sock_prot_num2str(protocol) + to convert to a string. + + Common values include: + 0 - IP (Internet Procotol, local interprocess communications) + 6 - TCP (Transmission Control Protocol) + 17 - UDP (User Datagram Protocol) + 132 - SCTP (Stream Control Transmission Protocol) + + Refer to /etc/protocols for a complete list of possible values. + +.I family + Protocol family of the socket (from include/linux/socket.h). + Use sock_fam_num2str(family) to convert to a string. + + Possible values are: + 0 - UNSPEC (Unspecified) + 1 - LOCAL (Unix domain/local sockets) + 2 - INET (Internet Protocol (IP)) + 3 - AX25 (Amateur Radio AX.25) + 4 - IPX (Novell IPX) + 5 - APPLETALK (AppleTalk DDP) + 6 - NETROM (Amateur Radio NET/ROM) + 7 - BRIDGE (Multiprotocol bridge) + 8 - ATMPVC (ATM PVCs) + 9 - X25 (X.25) + 10 - INET6 (IP version 6) + 11 - ROSE (Amateur Radio X.25 PLP) + 12 - DECNET (Reserved for DECnet project) + 13 - NETBEUI (Reserved for 802.2LLC project) + 14 - SECURITY (Security callback pseudo AF) + 15 - KEY (key management API) + 16 - NETLINK (Netlink protocol) + 17 - PACKET (Packet family) + 18 - ASH (Ash) + 19 - ECONET (Acorn Econet) + 20 - ATMSVC (ATM SVCs) + 22 - SNA (Linux SNA Project) + 23 - IRDA (IRDA sockets) + 24 - PPP0X (PPPoX sockets) + 25 - WANPIPE (Wanpipe API Sockets) + 26 - LLC (Linux LLC) + 30 - TIPC (TIPC sockets) + 31 - BLUETOOTH (Bluetooth sockets) + +.I state + State of the socket. Use sock_state_num2str(state) to convert + to a string. + + Possible values are: + 0 - FREE (not allocated) + 1 - UNCONNECTED (unconnected to any socket) + 2 - CONNECTING (in the process of connecting) + 3 - CONNECTED (connected to a socket) + 4 - DISCONNECTING (in the process of disconnecting) + +.I flags + Socket flags. Use sock_flags_num2str(flags) to convert + to a string. + + Possible values are: + 0 - ASYNC_NOSPACE + 1 - ASYNC_WAITDATA + 2 - NOSPACE + 3 - PASSCRED + 4 - PASSSEC + +.I type + Socket type. Use sock_type_num2str(type) to convert + to a string. + + Possible values are: + 1 - STREAM (stream connection socket) + 2 - DGRAM (datagram connectionless socket) + 3 - RAW (raw socket) + 4 - RDM (reliably-deliverd message) + 5 - SEQPACKET (sequential packet socket) + 6 - DCCP (datagram congestion control protocol socket) + 10 - PACKET (Linux-specific way of getting packets at device level) + +.I success + Was send successful? + + Possible values are: + 1 - Yes + 0 - No + +.TP +.B socket.receive + +Fires at the conclusion of receiving a message on a socket. +This probe alias includes the +.B socket.recvmsg.return, +.B socket.aio_read.return +and +.B socket.readv.return +probes (these probes should +catch all messages received on sockets). The arguments supplied at +the beginning of the receive are cached and made available in this probe. + +.B Context: + +The message receiver. + +.B Arguments: + +Same as +.B socket.send. + +.TP +.B socket.sendmsg + +Fires when the sock_sendmsg() kernel function is entered. + +.B Context: + +The message sender. + +.B Arguments: + +Same as +.B socket.send, +with the following exceptions: + +.I size + + Size of message being sent (in bytes). + +.I success + + Not used. + +.TP +.B socket.sendmsg.return + +Fires when the sock_sendmsg() kernel function returns. + +.B Context: + +The message sender. + +.B Arguments: + +Same as +.B socket.send + +.TP +.B socket.recvmsg + +Fires when the sock_recvmsg() kernel function is entered. + +.B Context: + +The message receiver. + +.B Arguments: + +Same as +.B socket.receive, +with the following exceptions: + +.I size + + Size of message being received (in bytes). + +.I success + + Not used. + +.TP +.B socket.recvmsg.return + +Fires when the sock_recvmsg() kernel function returns. + +.B Context: + +The message receiver. + +.B Arguments: + +Same as +.B socket.receive. + + + + + + +.TP +.B socket.aio_write + +Fires when the sock_aio_write() kernel function is entered. + +.B Context: + +The message sender. + +.B Arguments: + +Same as +.B socket.send, +with the following exceptions: + +.I size + + Size of message being sent (in bytes). + +.I success + + Not used. + +.TP +.B socket.aio_write.return + +Fires when the sock_aio_write() kernel function returns. + +.B Context: + +The message sender. + +.B Arguments: + +Same as +.B socket.send. + +.TP +.B socket.aio_read + +Fires when the sock_aio_read() kernel function is entered. + +.B Context: + +The message receiver. + +.B Arguments: + +Same as +.B socket.receive, +with the following exceptions: + +.I size + + Size of message being received (in bytes). + +.I success + + Not used. + +.TP +.B socket.aio_read.return + +Fires when the sock_aio_read() kernel function returns. + +.B Context: + +The message receiver. + +.B Arguments: + +Same as +.B socket.receive. + +.TP +.B socket.writev + +Fires when the sock_writev() kernel function is entered. + +.B Context: + +The message sender. + +.B Arguments: + +Same as +.B socket.send, +with the following exceptions: + +.I size + + Size of message being sent (in bytes). + +.I success + + Not used. + +.TP +.B socket.writev.return + +Fires when the sock_writev() kernel function returns. + +.B Context: + +The message sender. + +.B Arguments: + +Same as +.B socket.send. + +.TP +.B socket.readv + +Fires when the sock_readv() kernel function is entered. + +.B Context: + +The message receiver. + +.B Arguments: + +Same as +.B socket.receive, +with the following exceptions: + +.I size + + Size of message being received (in bytes). + +.I success + + Not used. + +.TP +.B socket.readv.return + +Fires when the sock_readv() kernel function returns. + +.B Context: + +The message receiver. + +.B Arguments: + +Same as +.B socket.receive. + +.TP +.B socket.create + +Fires at the beginning of creating a socket. + +.B Context: + +The socket creator. + +.B Arguments: + +.I name +.br +.I protocol +.br +.I family +.br +.I type + See +.B socket.send. + +.I requester + Requester type. + + Possible values are: + 1 - kernel + 0 - user + +.TP +.B socket.create.return + +Fires at the end of creating a socket. + +.B Context: + +The socket creator. + +.B Arguments: + +Same as +.B socket.create, +plus: + +.I err + Return code. + + Possible values are: + 0 - success + < 0 - error + +.I success + Was the socket created successfully? + + Possible values are: + 1 - Yes + 0 - No +.TP +.B socket.close + +Fires at the beginning of closing a socket. + +.B Context: + +The socket closer. + +.B Arguments: + +.I name +.br +.I protocol +.br +.I family +.br +.I state +.br +.I flags +.br +.I type + See +.B socket.send. + +.TP +.B socket.close.return + +Fires at the end of closing a socket. + +.B Context: + +The socket closer. + +.B Arguments: + +.I name + Name of this probe. + +.SH SEE ALSO +.IR stap (1), +.IR stapprobes (3stap), +.IR stapfuncs (3stap) diff --git a/man/stapprobes.socket.5.in b/man/stapprobes.socket.5.in deleted file mode 100644 index 6c939fd2..00000000 --- a/man/stapprobes.socket.5.in +++ /dev/null @@ -1,485 +0,0 @@ -.\" -*- nroff -*- -.TH STAPPROBES.SOCKET 5 @DATE@ "IBM" -.SH NAME -stapprobes.socket \- systemtap socket probe points - -.\" macros -.de SAMPLE -.br -.RS -.nf -.nh -.. -.de ESAMPLE -.hy -.fi -.RE -.. - -.SH DESCRIPTION - -This family of probe points is used to probe socket activities. -It contains the following probe points: - -.P -.TP -.B socket.send - -Fires at the conclusion of sending a message on a socket. -This probe alias includes the -.B socket.sendmsg.return, -.B socket.aio_write.return -and -.B socket.writev.return -probes (these probes should -catch all messages sent on sockets). The arguments supplied at the beginning -of the send are cached and made available in this probe. - -.B Context: - -The message sender. - -.B Arguments: - -.I name - Name of this probe. - -.I size - Size of message sent (in bytes) or error code if success == 0 - -.I protocol - Protocol used on the socket. Use sock_prot_num2str(protocol) - to convert to a string. - - Common values include: - 0 - IP (Internet Procotol, local interprocess communications) - 6 - TCP (Transmission Control Protocol) - 17 - UDP (User Datagram Protocol) - 132 - SCTP (Stream Control Transmission Protocol) - - Refer to /etc/protocols for a complete list of possible values. - -.I family - Protocol family of the socket (from include/linux/socket.h). - Use sock_fam_num2str(family) to convert to a string. - - Possible values are: - 0 - UNSPEC (Unspecified) - 1 - LOCAL (Unix domain/local sockets) - 2 - INET (Internet Protocol (IP)) - 3 - AX25 (Amateur Radio AX.25) - 4 - IPX (Novell IPX) - 5 - APPLETALK (AppleTalk DDP) - 6 - NETROM (Amateur Radio NET/ROM) - 7 - BRIDGE (Multiprotocol bridge) - 8 - ATMPVC (ATM PVCs) - 9 - X25 (X.25) - 10 - INET6 (IP version 6) - 11 - ROSE (Amateur Radio X.25 PLP) - 12 - DECNET (Reserved for DECnet project) - 13 - NETBEUI (Reserved for 802.2LLC project) - 14 - SECURITY (Security callback pseudo AF) - 15 - KEY (key management API) - 16 - NETLINK (Netlink protocol) - 17 - PACKET (Packet family) - 18 - ASH (Ash) - 19 - ECONET (Acorn Econet) - 20 - ATMSVC (ATM SVCs) - 22 - SNA (Linux SNA Project) - 23 - IRDA (IRDA sockets) - 24 - PPP0X (PPPoX sockets) - 25 - WANPIPE (Wanpipe API Sockets) - 26 - LLC (Linux LLC) - 30 - TIPC (TIPC sockets) - 31 - BLUETOOTH (Bluetooth sockets) - -.I state - State of the socket. Use sock_state_num2str(state) to convert - to a string. - - Possible values are: - 0 - FREE (not allocated) - 1 - UNCONNECTED (unconnected to any socket) - 2 - CONNECTING (in the process of connecting) - 3 - CONNECTED (connected to a socket) - 4 - DISCONNECTING (in the process of disconnecting) - -.I flags - Socket flags. Use sock_flags_num2str(flags) to convert - to a string. - - Possible values are: - 0 - ASYNC_NOSPACE - 1 - ASYNC_WAITDATA - 2 - NOSPACE - 3 - PASSCRED - 4 - PASSSEC - -.I type - Socket type. Use sock_type_num2str(type) to convert - to a string. - - Possible values are: - 1 - STREAM (stream connection socket) - 2 - DGRAM (datagram connectionless socket) - 3 - RAW (raw socket) - 4 - RDM (reliably-deliverd message) - 5 - SEQPACKET (sequential packet socket) - 6 - DCCP (datagram congestion control protocol socket) - 10 - PACKET (Linux-specific way of getting packets at device level) - -.I success - Was send successful? - - Possible values are: - 1 - Yes - 0 - No - -.TP -.B socket.receive - -Fires at the conclusion of receiving a message on a socket. -This probe alias includes the -.B socket.recvmsg.return, -.B socket.aio_read.return -and -.B socket.readv.return -probes (these probes should -catch all messages received on sockets). The arguments supplied at -the beginning of the receive are cached and made available in this probe. - -.B Context: - -The message receiver. - -.B Arguments: - -Same as -.B socket.send. - -.TP -.B socket.sendmsg - -Fires when the sock_sendmsg() kernel function is entered. - -.B Context: - -The message sender. - -.B Arguments: - -Same as -.B socket.send, -with the following exceptions: - -.I size - - Size of message being sent (in bytes). - -.I success - - Not used. - -.TP -.B socket.sendmsg.return - -Fires when the sock_sendmsg() kernel function returns. - -.B Context: - -The message sender. - -.B Arguments: - -Same as -.B socket.send - -.TP -.B socket.recvmsg - -Fires when the sock_recvmsg() kernel function is entered. - -.B Context: - -The message receiver. - -.B Arguments: - -Same as -.B socket.receive, -with the following exceptions: - -.I size - - Size of message being received (in bytes). - -.I success - - Not used. - -.TP -.B socket.recvmsg.return - -Fires when the sock_recvmsg() kernel function returns. - -.B Context: - -The message receiver. - -.B Arguments: - -Same as -.B socket.receive. - - - - - - -.TP -.B socket.aio_write - -Fires when the sock_aio_write() kernel function is entered. - -.B Context: - -The message sender. - -.B Arguments: - -Same as -.B socket.send, -with the following exceptions: - -.I size - - Size of message being sent (in bytes). - -.I success - - Not used. - -.TP -.B socket.aio_write.return - -Fires when the sock_aio_write() kernel function returns. - -.B Context: - -The message sender. - -.B Arguments: - -Same as -.B socket.send. - -.TP -.B socket.aio_read - -Fires when the sock_aio_read() kernel function is entered. - -.B Context: - -The message receiver. - -.B Arguments: - -Same as -.B socket.receive, -with the following exceptions: - -.I size - - Size of message being received (in bytes). - -.I success - - Not used. - -.TP -.B socket.aio_read.return - -Fires when the sock_aio_read() kernel function returns. - -.B Context: - -The message receiver. - -.B Arguments: - -Same as -.B socket.receive. - -.TP -.B socket.writev - -Fires when the sock_writev() kernel function is entered. - -.B Context: - -The message sender. - -.B Arguments: - -Same as -.B socket.send, -with the following exceptions: - -.I size - - Size of message being sent (in bytes). - -.I success - - Not used. - -.TP -.B socket.writev.return - -Fires when the sock_writev() kernel function returns. - -.B Context: - -The message sender. - -.B Arguments: - -Same as -.B socket.send. - -.TP -.B socket.readv - -Fires when the sock_readv() kernel function is entered. - -.B Context: - -The message receiver. - -.B Arguments: - -Same as -.B socket.receive, -with the following exceptions: - -.I size - - Size of message being received (in bytes). - -.I success - - Not used. - -.TP -.B socket.readv.return - -Fires when the sock_readv() kernel function returns. - -.B Context: - -The message receiver. - -.B Arguments: - -Same as -.B socket.receive. - -.TP -.B socket.create - -Fires at the beginning of creating a socket. - -.B Context: - -The socket creator. - -.B Arguments: - -.I name -.br -.I protocol -.br -.I family -.br -.I type - See -.B socket.send. - -.I requester - Requester type. - - Possible values are: - 1 - kernel - 0 - user - -.TP -.B socket.create.return - -Fires at the end of creating a socket. - -.B Context: - -The socket creator. - -.B Arguments: - -Same as -.B socket.create, -plus: - -.I err - Return code. - - Possible values are: - 0 - success - < 0 - error - -.I success - Was the socket created successfully? - - Possible values are: - 1 - Yes - 0 - No -.TP -.B socket.close - -Fires at the beginning of closing a socket. - -.B Context: - -The socket closer. - -.B Arguments: - -.I name -.br -.I protocol -.br -.I family -.br -.I state -.br -.I flags -.br -.I type - See -.B socket.send. - -.TP -.B socket.close.return - -Fires at the end of closing a socket. - -.B Context: - -The socket closer. - -.B Arguments: - -.I name - Name of this probe. - -.SH SEE ALSO -.IR stap (1), -.IR stapprobes (5), -.IR stapfuncs (5) diff --git a/man/stapprobes.tcp.3stap.in b/man/stapprobes.tcp.3stap.in new file mode 100644 index 00000000..3e607b69 --- /dev/null +++ b/man/stapprobes.tcp.3stap.in @@ -0,0 +1,102 @@ +.\" -*- nroff -*- +.TH STAPPROBES.TCP 3stap @DATE@ "IBM, Intel" +.SH NAME +stapprobes.tcp \- systemtap tcp probe points + +.\" macros +.de SAMPLE +.br +.RS +.nf +.nh +.. +.de ESAMPLE +.hy +.fi +.RE +.. + +.SH DESCRIPTION + +This family of probe points is used to probe TCP layer activities. +It contains the following probe points: + +.P +.TP +.B tcp.sendmsg + +Fires whenever sending a tcp message + +.B Arguments: + +.I sock + network socket + +.I size + number of bytes to send + +.P +.TP +.B tcp.sendmsg.return + +Fires whenever sending message is done + +.B Arguments: + +.I size + number of bytes sent + +.P +.TP +.B tcp.recvmsg + +Fires whenever a message is received + +.B Arguments: + +.I sock + network socket + +.I size + number of bytes to be received + +.P +.TP +.B tcp.recvmsg.return + +Fires whenever message receiving is done + +.B Arguments: + +.I size + number of bytes received + +.P +.TP +.B tcp.disconnect + +Fires whenever tcp is disconnected + +.B Arguments: + +.I sock + network socket + +.I flags + TCP flags (e.g. FIN, etc) + +.P +.TP +.B tcp.disconnect.return + +Fires when returning from tcp.disconnect + +.B Arguments: + +.I ret + error code (0: no error) + +.SH SEE ALSO +.IR stap (1), +.IR stapprobes (3stap), + diff --git a/man/stapprobes.tcp.5.in b/man/stapprobes.tcp.5.in deleted file mode 100644 index c5194261..00000000 --- a/man/stapprobes.tcp.5.in +++ /dev/null @@ -1,102 +0,0 @@ -.\" -*- nroff -*- -.TH STAPPROBES.TCP 5 @DATE@ "IBM, Intel" -.SH NAME -stapprobes.tcp \- systemtap tcp probe points - -.\" macros -.de SAMPLE -.br -.RS -.nf -.nh -.. -.de ESAMPLE -.hy -.fi -.RE -.. - -.SH DESCRIPTION - -This family of probe points is used to probe TCP layer activities. -It contains the following probe points: - -.P -.TP -.B tcp.sendmsg - -Fires whenever sending a tcp message - -.B Arguments: - -.I sock - network socket - -.I size - number of bytes to send - -.P -.TP -.B tcp.sendmsg.return - -Fires whenever sending message is done - -.B Arguments: - -.I size - number of bytes sent - -.P -.TP -.B tcp.recvmsg - -Fires whenever a message is received - -.B Arguments: - -.I sock - network socket - -.I size - number of bytes to be received - -.P -.TP -.B tcp.recvmsg.return - -Fires whenever message receiving is done - -.B Arguments: - -.I size - number of bytes received - -.P -.TP -.B tcp.disconnect - -Fires whenever tcp is disconnected - -.B Arguments: - -.I sock - network socket - -.I flags - TCP flags (e.g. FIN, etc) - -.P -.TP -.B tcp.disconnect.return - -Fires when returning from tcp.disconnect - -.B Arguments: - -.I ret - error code (0: no error) - -.SH SEE ALSO -.IR stap (1), -.IR stapprobes (5), - diff --git a/man/stapprobes.udp.3stap.in b/man/stapprobes.udp.3stap.in new file mode 100644 index 00000000..3fbfd3e7 --- /dev/null +++ b/man/stapprobes.udp.3stap.in @@ -0,0 +1,102 @@ +.\" -*- nroff -*- +.TH STAPPROBES.UDP 3stap @DATE@ "Intel" +.SH NAME +stapprobes.udp \- systemtap udp probe points + +.\" macros +.de SAMPLE +.br +.RS +.nf +.nh +.. +.de ESAMPLE +.hy +.fi +.RE +.. + +.SH DESCRIPTION + +This family of probe points is used to probe UDP layer activities. +It contains the following probe points: + +.P +.TP +.B udp.sendmsg + +Fires whenever sending a udp message + +.B Arguments: + +.I sock + network socket + +.I size + number of bytes to send + +.P +.TP +.B udp.sendmsg.return + +Fires whenever sending message is done + +.B Arguments: + +.I size + number of bytes sent + +.P +.TP +.B udp.recvmsg + +Fires whenever a message is received + +.B Arguments: + +.I sock + network socket + +.I size + number of bytes to be received + +.P +.TP +.B udp.recvmsg.return + +Fires whenever message receiving is done + +.B Arguments: + +.I size + number of bytes received + +.P +.TP +.B udp.disconnect + +Fires whenever udp is disconnected + +.B Arguments: + +.I sock + network socket + +.I flags + flags (e.g. FIN, etc) + +.P +.TP +.B udp.disconnect.return + +Fires when returning from udp.disconnect + +.B Arguments: + +.I ret + error code (0: no error) + +.SH SEE ALSO +.IR stap (1), +.IR stapprobes (3stap), + diff --git a/man/stapprobes.udp.5.in b/man/stapprobes.udp.5.in deleted file mode 100644 index 6e89adf0..00000000 --- a/man/stapprobes.udp.5.in +++ /dev/null @@ -1,102 +0,0 @@ -.\" -*- nroff -*- -.TH STAPPROBES.UDP 5 @DATE@ "Intel" -.SH NAME -stapprobes.udp \- systemtap udp probe points - -.\" macros -.de SAMPLE -.br -.RS -.nf -.nh -.. -.de ESAMPLE -.hy -.fi -.RE -.. - -.SH DESCRIPTION - -This family of probe points is used to probe UDP layer activities. -It contains the following probe points: - -.P -.TP -.B udp.sendmsg - -Fires whenever sending a udp message - -.B Arguments: - -.I sock - network socket - -.I size - number of bytes to send - -.P -.TP -.B udp.sendmsg.return - -Fires whenever sending message is done - -.B Arguments: - -.I size - number of bytes sent - -.P -.TP -.B udp.recvmsg - -Fires whenever a message is received - -.B Arguments: - -.I sock - network socket - -.I size - number of bytes to be received - -.P -.TP -.B udp.recvmsg.return - -Fires whenever message receiving is done - -.B Arguments: - -.I size - number of bytes received - -.P -.TP -.B udp.disconnect - -Fires whenever udp is disconnected - -.B Arguments: - -.I sock - network socket - -.I flags - flags (e.g. FIN, etc) - -.P -.TP -.B udp.disconnect.return - -Fires when returning from udp.disconnect - -.B Arguments: - -.I ret - error code (0: no error) - -.SH SEE ALSO -.IR stap (1), -.IR stapprobes (5), - diff --git a/stap-server.8.in b/stap-server.8.in index 1976b6ea..bab8d82a 100644 --- a/stap-server.8.in +++ b/stap-server.8.in @@ -265,7 +265,7 @@ host. .SH EXAMPLES See the -.IR stapex (5) +.IR stapex (3stap) manual page for a collection of sample scripts. .PP Here is a very basic example of how to use @@ -351,9 +351,9 @@ access permissions before making use of any certificate database. .SH SEE ALSO .IR stap (1), .IR staprun (8), -.IR stapprobes (5), -.IR stapfuncs (5), -.IR stapex (5), +.IR stapprobes (3stap), +.IR stapfuncs (3stap), +.IR stapex (3stap), .IR NSS , .IR certutil , .IR signtool diff --git a/stap.1.in b/stap.1.in index c562c8b7..088449c0 100644 --- a/stap.1.in +++ b/stap.1.in @@ -535,7 +535,7 @@ Events are specified in a special syntax called "probe points". There are several varieties of probe points defined by the translator, and tapset scripts may define further ones using aliases. These are listed in the -.IR stapprobes (5) +.IR stapprobes (3stap) manual pages. .PP The probe handler is interpreted relative to the context of each @@ -860,7 +860,7 @@ by the scripts installed under the .IR @prefix@/share/systemtap/tapset .hy directory. These are described in the -.IR stapfuncs "(5) and " stapprobes (5) +.IR stapfuncs "(3stap) and " stapprobes (3stap) manual pages. .SH PROCESSING @@ -957,7 +957,7 @@ unloads the module, and cleans up. .SH EXAMPLES See the -.IR stapex (5) +.IR stapex (3stap) manual page for a collection of samples. .SH CACHING @@ -1202,10 +1202,10 @@ The auxiliary program supervising module loading, interaction, and unloading. .SH SEE ALSO -.IR stapprobes (5), -.IR stapfuncs (5), -.IR stapvars (5), -.IR stapex (5), +.IR stapprobes (3stap), +.IR stapfuncs (3stap), +.IR stapvars (3stap), +.IR stapex (3stap), .IR awk (1), .IR gdb (1) diff --git a/stapex.3stap.in b/stapex.3stap.in new file mode 100644 index 00000000..8d02fc5c --- /dev/null +++ b/stapex.3stap.in @@ -0,0 +1,126 @@ +.\" -*- nroff -*- +.TH STAPEX 3stap @DATE@ "Red Hat" +.SH NAME +stapex \- systemtap examples + +.\" macros +.de SAMPLE +.br +.RS +.nf +.nh +.. +.de ESAMPLE +.hy +.fi +.RE +.. + +.SH LANGUAGE BASICS +These examples give a feel for basic systemtap syntax and +control structures. + +.SAMPLE +global odds, evens + +probe begin { + # "no" and "ne" are local integers + for (i=0; i<10; i++) { + if (i % 2) odds [no++] = i + else evens [ne++] = i + } + delete odds[2] + delete evens[3] + exit () +} + +probe end { + foreach (x+ in odds) { + printf ("odds[%d] = %d\n", x, odds[x]) + } + foreach (x in evens\-) { + printf ("evens[%d] = %d\n", x, evens[x]) + } +} +.ESAMPLE +This prints: +.SAMPLE +odds[1] = 1 +odds[3] = 5 +odds[4] = 7 +odds[5] = 9 +evens[5] = 8 +evens[4] = 6 +evens[2] = 2 +evens[1] = 0 +.ESAMPLE +Note that all variables types are inferred, and that all locals +and globals are automatically initialized. + +.PP +This script prints the primes between 0 and 49. +.SAMPLE +function isprime (x) { + if (x < 2) return 0 + for (i=2; i x) break + } + return 1 +} +probe begin { + for (i=0; i<50; i++) + if (isprime (i)) printf("%d\n", i) + exit() +} +.ESAMPLE + +.PP +This script demonstrates recursive functions. +.SAMPLE +function fibonacci(i) { + if (i < 1) error ("bad number") + if (i == 1) return 1 + if (i == 2) return 2 + return fibonacci (i\-1) + fibonacci (i\-2) +} +probe begin { + printf ("11th fibonacci number: %d\n", fibonacci (11)) + exit () +} +.ESAMPLE +Any larger number may exceed the MAXACTION or MAXNESTING +limits, and result in an error. + + +.SH PROBING + +To trace entry and exit from a function, use a pair of probes: +.SAMPLE +probe kernel.function("sys_mkdir") { println ("enter") } +probe kernel.function("sys_mkdir").return { println ("exit") } +.ESAMPLE + +To list the probeable functions in the kernel, use the listings mode. +.SAMPLE +% stap \-l \[aq]kernel.function("*")\[aq] +.ESAMPLE + +To list the probeable functions and local variables in the kernel, use another listings mode. +.SAMPLE +% stap \-L \[aq]kernel.function("*")\[aq] +.ESAMPLE + +.SH MORE EXAMPLES + +Larger examples, demos and samples can be found in +@prefix@/doc/systemtap*/examples, each example comes with either a .txt +or .meta file explaining what the example, sample or demo does and how +it is ordinarily run. + +.SH SEE ALSO +.BR @prefix@/doc/systemtap*/examples +.IR stap (1) +.IR stapprobes (3stap) +.IR stapfuncs (3stap) + diff --git a/stapex.5.in b/stapex.5.in deleted file mode 100644 index 38f30f62..00000000 --- a/stapex.5.in +++ /dev/null @@ -1,126 +0,0 @@ -.\" -*- nroff -*- -.TH STAPEX 5 @DATE@ "Red Hat" -.SH NAME -stapex \- systemtap examples - -.\" macros -.de SAMPLE -.br -.RS -.nf -.nh -.. -.de ESAMPLE -.hy -.fi -.RE -.. - -.SH LANGUAGE BASICS -These examples give a feel for basic systemtap syntax and -control structures. - -.SAMPLE -global odds, evens - -probe begin { - # "no" and "ne" are local integers - for (i=0; i<10; i++) { - if (i % 2) odds [no++] = i - else evens [ne++] = i - } - delete odds[2] - delete evens[3] - exit () -} - -probe end { - foreach (x+ in odds) { - printf ("odds[%d] = %d\n", x, odds[x]) - } - foreach (x in evens\-) { - printf ("evens[%d] = %d\n", x, evens[x]) - } -} -.ESAMPLE -This prints: -.SAMPLE -odds[1] = 1 -odds[3] = 5 -odds[4] = 7 -odds[5] = 9 -evens[5] = 8 -evens[4] = 6 -evens[2] = 2 -evens[1] = 0 -.ESAMPLE -Note that all variables types are inferred, and that all locals -and globals are automatically initialized. - -.PP -This script prints the primes between 0 and 49. -.SAMPLE -function isprime (x) { - if (x < 2) return 0 - for (i=2; i x) break - } - return 1 -} -probe begin { - for (i=0; i<50; i++) - if (isprime (i)) printf("%d\n", i) - exit() -} -.ESAMPLE - -.PP -This script demonstrates recursive functions. -.SAMPLE -function fibonacci(i) { - if (i < 1) error ("bad number") - if (i == 1) return 1 - if (i == 2) return 2 - return fibonacci (i\-1) + fibonacci (i\-2) -} -probe begin { - printf ("11th fibonacci number: %d\n", fibonacci (11)) - exit () -} -.ESAMPLE -Any larger number may exceed the MAXACTION or MAXNESTING -limits, and result in an error. - - -.SH PROBING - -To trace entry and exit from a function, use a pair of probes: -.SAMPLE -probe kernel.function("sys_mkdir") { println ("enter") } -probe kernel.function("sys_mkdir").return { println ("exit") } -.ESAMPLE - -To list the probeable functions in the kernel, use the listings mode. -.SAMPLE -% stap \-l \[aq]kernel.function("*")\[aq] -.ESAMPLE - -To list the probeable functions and local variables in the kernel, use another listings mode. -.SAMPLE -% stap \-L \[aq]kernel.function("*")\[aq] -.ESAMPLE - -.SH MORE EXAMPLES - -Larger examples, demos and samples can be found in -@prefix@/doc/systemtap*/examples, each example comes with either a .txt -or .meta file explaining what the example, sample or demo does and how -it is ordinarily run. - -.SH SEE ALSO -.BR @prefix@/doc/systemtap*/examples -.IR stap (1) -.IR stapprobes (5) -.IR stapfuncs (5) - diff --git a/stapfuncs.3stap.in b/stapfuncs.3stap.in new file mode 100644 index 00000000..1f2955da --- /dev/null +++ b/stapfuncs.3stap.in @@ -0,0 +1,668 @@ +.\" -*- nroff -*- +.TH STAPFUNCS 3stap @DATE@ "Red Hat" +.SH NAME +stapfuncs \- systemtap functions + +.SH DESCRIPTION +The following sections enumerate the public functions provided by +standard tapsets installed under @prefix@/share/systemtap/tapset. Each +function is described with a signature, and its behavior/restrictions. +The signature line includes the name of the function, the type of +its return value (if any), and the names and types of all parameters. +The syntax is the same as printed with the +.IR stap " option " \-p2 . +Examples: + +.TP +example1:long (v:string, k:long) +In function "example1", do something with the given string and integer. +Return some integer. + +.TP +example2:unknown () +In function "example2", do something. There is no explicit return value +and take no parameters. + +.SS PRINTING + +.TP +log:unknown (msg:string) +Writes the given string to the common trace buffer. Append an implicit +end-of-line. Deprecated. Please use the faster print functions. + +.TP +warn:unknown (msg:string) +Write the given string to the warning stream. Append an implicit end-of-line. +.I staprun +prepends the string "WARNING:". + +.TP +error:unknown (msg:string) +An error has occurred. Write the given string to the error stream. +Append an implicit end-of-line. +.I staprun +prepends the string "ERROR:". +Block any further execution of statements in this probe. If the number +of errors so far exceeds the MAXERRORS parameter, also trigger an +.IR exit() . + +.TP +exit:unknown () +Enqueue a request to shut down the systemtap session. This does +.B not +unwind the current probe handler, nor block new probe handlers. +.I staprun +will shortly respond to the request and initiate an orderly shutdown. + +.SS CONVERSIONS +.PP +These functions access kernel or user-space data. They try to validate the +supplied addresses, and can thus result in errors if the pointers are invalid, +or if a user-space access would cause a fault. +.TP +kernel_string:string (addr:long) +Copy a 0-terminated string from kernel space at given address. +.TP +kernel_string_n:string (addr:long, n:long) +Similar with kernel_string, except that not more than n bytes are copied. +Thus, if there are null bytes among the first n bytes, it is same as +kernel_string(addr). If not, n bytes will be copied and a null byte will +be padded to the end. +.TP +kernel_long:long (addr:long) +Copy a long from kernel space at given address. +.TP +kernel_int:long (addr:long) +Copy an int from kernel space at given address. +.TP +kernel_short:long (addr:long) +Copy a short from kernel space at given address. +.TP +kernel_char:long (addr:long) +Copy a char from kernel space at given address. +.TP +user_string:string (addr:long) +Copy a string from user space at given address. If the access would +fault, return "" and signal no errors. +.TP +user_string2:string (addr:long, err_msg:string) +Copy a string from user space at given address. If the access would +fault, return instead the err_msg value. +.TP +user_string_warn:string (addr:long) +Copy a string from user space at given address. If the access would +fault, signal a warning and return "". +.TP +user_string_quoted:string (addr:long) +Copy a string from user space at given address. Any ASCII characters +that are not printable are replaced by the corresponding escape +sequence in the returned string. +.TP +user_string_n:string (addr:long, n:long) +Copy a string of n bytes from user space at given address. If the access +would fault, return "". +.TP +user_string_n2:string (addr:long, n:long, err_msg:string) +Copy a string of n bytes from user space at given address. If the access +would fault, return the err_msg value. +.TP +user_string_n_warn:string (addr:long, n:long) +Copy a string of n bytes from user space at given address. If the access +would fault, signal a warning and return "". +.TP +user_string_n_quoted:string (addr:long, n:long) +Copy a string of n bytes from user space at given address. Any ASCII +characters that are not printable are replaced by the corresponding escape +sequence in the returned string. If the access would fault, return "". +.TP +user_short:long (addr:long) +Copy a short from user space at given address. If the access would fault, +return 0. +.TP +user_short_warn:long (addr:long) +Copy a short from user space at given address. If the access would fault, +signal a warning and return 0. +.TP +user_int:long (addr:long) +Copy an int from user space at given address. If the access would fault, +return 0. +.TP +user_int_warn:long (addr:long) +Copy an int from user space at given address. If the access would fault, +signal a warning and return 0. +.TP +user_long:long (addr:long) +Copy a long from user space at given address. If the access would fault, +return 0. +.TP +user_long_warn:long (addr:long) +Copy a long from user space at given address. If the access would fault, +signal a warning and return 0. +.TP +user_char:long (addr:long) +Copy a char from user space at given address. If the access would fault, +return 0. +.TP +user_char_warn:long (addr:long) +Copy a char from user space at given address. If the access would fault, +signal a warning and return 0. +.SS STRING +.TP +strlen:long (str:string) +Return the number of characters in str. +.TP +substr:string (str:string,start:long, stop:long) +Return the substring of str starting from character start and ending at character stop. +.TP +isinstr:long (s1:string, s2:string) +Return 1 if string s1 contains string s2, returns 0 otherwise. +.TP +strtol:long (str:string, base:long) +Convert the string representation of a number to a long using the numbering system +specified by base. For example, strtol("1000", 16) returns 4096. Returns 0 if the +string cannot be converted. +.TP +tokenize:string (str:string, delim:string) +Return the next token in the given str string, where the tokens are delimited +by one of the characters in the delim string. If the str string is not blank, +it returns the first token. If the str string is blank, it returns the next +token in the string passed in the previous call to tokenize. If no delimiter +is found, the entire remaining str string is returned. Returns blank when +no more tokens are left. + +.SS TIMESTAMP +.TP +get_cycles:long () +Return the processor cycle counter value, or 0 if unavailable. +.TP +gettimeofday_ns:long () +Return the number of nanoseconds since the UNIX epoch. +.TP +gettimeofday_us:long () +Return the number of microseconds since the UNIX epoch. +.TP +gettimeofday_ms:long () +Return the number of milliseconds since the UNIX epoch. +.TP +gettimeofday_s:long () +Return the number of seconds since the UNIX epoch. + +.SS CONTEXT INFO +.TP +cpu:long () +Return the current cpu number. +.TP +execname:string () +Return the name of the current process. +.TP +pexecname:string() +Return the name of the parent process. +.TP +tid:long () +Return the id of the current thread. +.TP +pid:long () +Return the id of the current process. +.TP +ppid:long () +Return the id of the parent process. +.TP +uid:long () +Return the uid of the current process. +.TP +euid:long () +Return the effective uid of the current process. +.TP +gid:long () +Return the gid of the current process. +.TP +egid:long () +Return the effective gid of the current process. +.TP +print_regs:unknown () +Print a register dump. +.TP +backtrace:string () +Return a string of hex addresses that are a backtrace of the stack. +It may be truncated due to maximum string length. +.TP +print_stack:unknown (bt:string) +Perform a symbolic lookup of the addresses in the given string, +which is assumed to be the result of a prior call to +.IR backtrace() . +Print one line per address, including the address, the name of the +function containing the address, and an estimate of its position +within that function. Return nothing. +.TP +print_backtrace:unknown () +Equivalent to +.IR print_stack(backtrace()) , +except that deeper stack nesting may be supported. Return nothing. +.TP +pp:string () +Return the probe point associated with the currently running probe handler, +including alias and wildcard expansion effects. +.TP +probefunc:string () +Return the probe point's function name, if known. +.TP +probemod:string () +Return the probe point's module name, if known. +.TP +target:long () +Return the pid of the target process. +.TP +user_mode:long () +Return 1 if the probe point occurred in user-mode. +.TP +is_return:long () +Return 1 if the probe point is a return probe. Deprecated. + +.SS TARGET_SET +.TP +target_set_pid:long (tid:long) +Return whether the given process-id is within the "target set", that is whether +it is a descendent of the top-level target() process. +.TP +target_set_report:unknown () +Print a report about the target set, and their ancestry. + +.SS ERRNO +.TP +errno_str:string (e:long) +Return the symbolic string associated with the given error code, like +"ENOENT" for the number 2, or "E#3333" for an out-of-range value like 3333. + +.SS TASK +.PP +These functions return data about a task. They all require +a task handle as input, such as the value return by task_current() or the variables +prev_task and next_task in the scheduler.ctxswitch probe alias. + +.TP +task_current:long() +Return the task_struct of the current process. + +.TP +task_parent:long(task:long) +Return the parent task_struct of the given task. +.TP +task_state:long(task:long) +Return the state of the given task, which can be one of the following: + + TASK_RUNNING 0 + TASK_INTERRUPTIBLE 1 + TASK_UNINTERRUPTIBLE 2 + TASK_STOPPED 4 + TASK_TRACED 8 + EXIT_ZOMBIE 16 + EXIT_DEAD 32 + +.TP +task_execname:string(task:long) +Return the name of the given task. + +.TP +task_pid:long(task:long) +Return the process id of the given task. + +.TP +task_tid:long(task:long) +Return the thread id of the given task. + +.TP +task_gid:long(task:long) +Return the group id of the given task. + +.TP +task_egid:long(task:long) +Return the effective group id of the given task. + +.TP +task_uid:long(task:long) +Return the user id of the given task. + +.TP +task_euid:long(task:long) +Return the effective user id of the given task. + +.TP +task_prio:long(task:long) +Return the priority of the given task. + +.TP +task_nice:long(task:long) +Return the nice value of the given task. + +.TP +task_cpu:long(task:long) +Return the scheduled cpu for the given task. + +.TP +task_open_file_handles:long(task:long) +Return the number of open file handles for the given task. + +.TP +task_max_file_handles:long(task:long) +Return the maximum number of file handles for the given task. + +.SS CPU REGISTERS +.TP +registers_valid:long () +Return 1 if register() and u_register() can be used +in the current context, or 0 otherwise. +For example, registers_valid() returns 0 when called from a begin or end probe. +.TP +register:long (name:string) +Return the value of the named CPU register, +as it was saved when the current probe point was hit. +If the register is 32 bits, it is sign-extended to 64 bits. + +For the i386 architecture, the following names are recognized. +(name1/name2 indicates that name1 and name2 are alternative names +for the same register.) +eax/ax, ebp/bp, ebx/bx, ecx/cx, edi/di, edx/dx, eflags/flags, +eip/ip, esi/si, esp/sp, orig_eax/orig_ax, +xcs/cs, xds/ds, xes/es, xfs/fs, xss/ss. + +For the x86_64 architecture, the following names are recognized: +64-bit registers: +r8, r9, r10, r11, r12, r13, r14, r15, +rax/ax, rbp/bp, rbx/bx, rcx/cx, rdi/di, rdx/dx, +rip/ip, rsi/si, rsp/sp; +32-bit registers: +eax, ebp, ebx, ecx, edx, edi, edx, eip, esi, esp, flags/eflags, orig_eax; +segment registers: xcs/cs, xss/ss. + +For powerpc, the following names are recognized: +r0, r1, ... r31, nip, msr, orig_gpr3, ctr, link, xer, ccr, softe, trap, +dar, dsisr, result. + +For s390x, the following names are recognized: +r0, r1, ... r15, args, psw.mask, psw.addr, orig_gpr2, ilc, trap. + +.TP +u_register:long (name:string) +Same as register(name), except that +if the register is 32 bits, it is zero-extended to 64 bits. + +.SS NUMBERED FUNCTION ARGUMENTS +The functions in this section provide the values of a probed function's +arguments. +They can be called when you have hit +a probe point at the entry to a function. +Arguments are referred to by number, starting at 1. +Ordinarily, you can access arguments by name as well, +but you may find these functions useful if the code you are probing +was built without debugging information. + +On 32-bit architectures +\(em and when probing 32-bit applications on 64-bit architectures \(em +a 64-bit argument occupies two "arg slots." +For example, if you are probing the following function + + void f(int a, long long b, char *c) + +you would refer to a, b, and c as int_arg(1), longlong_arg(2), and +pointer_arg(3), respectively, on a 64-bit architecture; +but on a 32-bit architecture, you would refer to c as pointer_arg(4) +(since b occupies slots 2 and 3). + +If the function you are probing doesn't follow the default rules +for argument passing, you need to call one of the following functions +(which see) in your handler before calling any *_arg function: +asmlinkage(), fastcall(), or regparm(). +(This isn't necessary when referring to arguments only by name.) +.TP +int_arg:long (n:long) +Return the value of argument n as a signed int +(i.e., a 32-bit integer sign-extended to 64 bits). +.TP +uint_arg:long (n:long) +Return the value of argument n as an unsigned int +(i.e., a 32-bit integer zero-extended to 64 bits). +.TP +long_arg:long (n:long) +Return the value of argument n as a signed long. +On architectures where a long is 32 bits, the value is sign-extended to 64 bits. +.TP +ulong_arg:long (n:long) +Return the value of argument n as an unsigned long. +On architectures where a long is 32 bits, the value is zero-extended to 64 bits. +.TP +longlong_arg:long (n:long) +Return the value of argument n as a 64-bit value. +.TP +ulonglong_arg:long (n:long) +Same as longlong_arg(n). +.TP +pointer_arg:long (n:long) +Same as ulong_arg(n). +Use with any type of pointer. +.TP +s32_arg:long (n:long) +Same as int_arg(n). +.TP +u32_arg:long (n:long) +Same as uint_arg(n). +.TP +s64_arg:long (n:long) +Same as longlong_arg(n). +.TP +u64_arg:long (n:long) +Same as [u]longlong_arg(n). +.TP +asmlinkage:unknown () +The probed kernel function is declared asmlinkage in the source. +.TP +fastcall:unknown () +The probed kernel function is declared fastcall in the source. +.TP +regparm:unknown (n:long) +The probed function was built with the gcc \-mregparm=n option. +(The i386 kernel is built with \-mregparm=3, so systemtap considers +regparm(3) the default for kernel functions on that architecture.) + +For some architectures, the *_arg functions may reject unusually high +values of n. + +.SS QUEUE_STATS +.PP +The queue_stats tapset provides functions that, given notifications of +elementary queuing events (wait, run, done), tracks averages such as +queue length, service and wait times, utilization. The following +three functions should be called from appropriate probes, in sequence. +.TP +qs_wait:unknown (qname:string) +Record that a new request was enqueued for the given queue name. +.TP +qs_run:unknown (qname:string) +Record that a previously enqueued request was removed from the given +wait queue and is now being serviced. +.TP +qs_done:unknown (qname:string) +Record that a request originally from the given queue has completed +being serviced. +.\" XXX: qs_time +.PP +Functions with the prefix +.BR qsq_ +are for querying the statistics averaged since the first queue operation +(or when +.BR qsq_start +was called). Since statistics are often fractional, a scale parameter +is multiplies the result to a more useful scale. For some fractions, +a scale of 100 will usefully return percentage numbers. +.TP +qsq_start:unknown (qname:string) +Reset the statistics counters for the given queue, and start tracking +anew from this moment. +.TP +qsq_print:unknown (qname:string) +Print a line containing a selection of the given queue's statistics. +.TP +qsq_utilization:long (qname:string, scale:long) +Return the fraction of elapsed time when the resource was utilized. +.TP +qsq_blocked:long (qname:string, scale:long) +Return the fraction of elapsed time when the wait queue was used. +.TP +qsq_wait_queue_length:long (qname:string, scale:long) +Return the average length of the wait queue. +.TP +qsq_service_time:long (qname:string, scale:long) +Return the average time required to service a request. +.TP +qsq_wait_time:long (qname:string, scale:long) +Return the average time a request took from being enqueued to completed. +.TP +qsq_throughput:long (qname:string, scale:long) +Return the average rate of requests per scale units of time. + +.SS INDENT +.PP +The indent tapset provides functions to generate indented lines for +nested kinds of trace messages. Each line contains a relative +timestamp, and the process name / pid. +.TP +thread_indent:string (delta:long) +Return a string with an appropriate indentation for this thread. +Call it with a small positive or matching negative delta. +If this is the outermost, initial level of indentation, reset the +relative timestamp base to zero. +.TP +thread_timestamp:long () +Return an absolute timestamp value for use by the indentation function. +The default function uses +.IR gettimeofday_us + +.SS SYSTEM +.TP +system (cmd:string) +Runs a command on the system. The command will run in the background +when the current probe completes. + +.SS NUMA +.TP +addr_to_node:long (addr:long) +Return which node the given address belongs to in a NUMA system. + +.SS CTIME +.TP +ctime:string (seconds:long) +Return a simple textual rendering (e.g., "Wed\ Jun\ 30\ 21:49:008\ 1993") +of the given number of seconds since the epoch, as perhaps returned by +.IR gettimeofday_s() . + +.SS PERFMON +.TP +read_counter:long (handle:long) +Returns the value for the processor's performance counter for the associated +handle. The body of the a perfmon probe should set record +the handle being used for that event. + +.SS SOCKETS +These functions convert arguments in the socket tapset back and +forth between their numeric and string representations. +See +.IR stapprobes.socket (3stap) +for details. + +.TP +sock_prot_num2str:string (proto:long) +Returns the string representation of the given protocol value. +.TP +sock_prot_str2num:long (proto:string) +Returns the numeric value associated with the given protocol string. +.TP +sock_fam_num2str:string (family:long) +Returns the string representation of the given protocol family value. +.TP +sock_fam_str2num:long (family:string) +Returns the numeric value associated with the given protocol family string. +.TP +sock_state_num2str:string (state:long) +Returns the string representation of the given socket state value. +.TP +sock_state_str2num:long (state:string) +Returns the numeric value associated with the given socket state string. +.TP +sock_type_num2str:string (type:long) +Returns the string representation of the given socket type value. +.TP +sock_type_str2num:long (type:string) +Returns the numeric value associated with the given socket type string. +.TP +sock_flags_num2str:string (flags:long) +Returns the string representation of the given socket flags value. +.TP +msg_flags_num2str:string (flags:long) +Returns the string representation of the given message flags bit map. + +.SS INET +These functions convert between network (big-endian) and host byte order, like their +namesake C functions. +.TP +ntohll:long (x:long) +Convert from network to host byte order, 64-bit. +.TP +ntohl:long (x:long) +Convert from network to host byte order, 32-bit. +.TP +ntohs:long (x:long) +Convert from network to host byte order, 16-bit. +.TP +htonll:long (x:long) +Convert from host to network byte order, 64-bit. +.TP +htonl:long (x:long) +Convert from host to network byte order, 32-bit. +.TP +htons:long (x:long) +Convert from host to network byte order, 16-bit. + +.SS SIGNAL +.TP +get_sa_flags:long (act:long) +Returns the numeric value of sa_flags. +.TP +get_sa_handler:long (act:long) +Returns the numeric value of sa_handler. +.TP +sigset_mask_str:string (mask:long) +Returns the string representation of the sigset sa_mask. +.TP +is_sig_blocked:long (task:long, sig:long) +Returns 1 if the signal is currently blocked, or 0 if it is not. +.TP +sa_flags_str:string (sa_flags:long) +Returns the string representation of sa_flags. +.TP +sa_handler_str(handler) +Returns the string representation of sa_handler. If it is not SIG_DFL, SIG_IGN +or SIG_ERR, it will return the address of the handler. +.TP +signal_str(num) +Returns the string representation of the given signal number. + +.SS DEVICE +.TP +MAJOR:long(dev:long) +Extracts the major device number from a kernel device number (kdev_t). +.TP +MINOR:long(dev:long) +Extracts the minor device number from a kernel device number (kdev_t). +.TP +MKDEV:long(major:long, minor:long) +Creates a value that can be compared to a kernel device number (kdev_t). +.TP +usrdev2kerndev:long(dev:long) +Converts a user-space device number into the format used in the kernel. + +.SH FILES +.nh +.IR @prefix@/share/systemtap/tapset +.hy + +.SH SEE ALSO +.IR stap (1) diff --git a/stapfuncs.5.in b/stapfuncs.5.in deleted file mode 100644 index 0322369e..00000000 --- a/stapfuncs.5.in +++ /dev/null @@ -1,668 +0,0 @@ -.\" -*- nroff -*- -.TH STAPFUNCS 5 @DATE@ "Red Hat" -.SH NAME -stapfuncs \- systemtap functions - -.SH DESCRIPTION -The following sections enumerate the public functions provided by -standard tapsets installed under @prefix@/share/systemtap/tapset. Each -function is described with a signature, and its behavior/restrictions. -The signature line includes the name of the function, the type of -its return value (if any), and the names and types of all parameters. -The syntax is the same as printed with the -.IR stap " option " \-p2 . -Examples: - -.TP -example1:long (v:string, k:long) -In function "example1", do something with the given string and integer. -Return some integer. - -.TP -example2:unknown () -In function "example2", do something. There is no explicit return value -and take no parameters. - -.SS PRINTING - -.TP -log:unknown (msg:string) -Writes the given string to the common trace buffer. Append an implicit -end-of-line. Deprecated. Please use the faster print functions. - -.TP -warn:unknown (msg:string) -Write the given string to the warning stream. Append an implicit end-of-line. -.I staprun -prepends the string "WARNING:". - -.TP -error:unknown (msg:string) -An error has occurred. Write the given string to the error stream. -Append an implicit end-of-line. -.I staprun -prepends the string "ERROR:". -Block any further execution of statements in this probe. If the number -of errors so far exceeds the MAXERRORS parameter, also trigger an -.IR exit() . - -.TP -exit:unknown () -Enqueue a request to shut down the systemtap session. This does -.B not -unwind the current probe handler, nor block new probe handlers. -.I staprun -will shortly respond to the request and initiate an orderly shutdown. - -.SS CONVERSIONS -.PP -These functions access kernel or user-space data. They try to validate the -supplied addresses, and can thus result in errors if the pointers are invalid, -or if a user-space access would cause a fault. -.TP -kernel_string:string (addr:long) -Copy a 0-terminated string from kernel space at given address. -.TP -kernel_string_n:string (addr:long, n:long) -Similar with kernel_string, except that not more than n bytes are copied. -Thus, if there are null bytes among the first n bytes, it is same as -kernel_string(addr). If not, n bytes will be copied and a null byte will -be padded to the end. -.TP -kernel_long:long (addr:long) -Copy a long from kernel space at given address. -.TP -kernel_int:long (addr:long) -Copy an int from kernel space at given address. -.TP -kernel_short:long (addr:long) -Copy a short from kernel space at given address. -.TP -kernel_char:long (addr:long) -Copy a char from kernel space at given address. -.TP -user_string:string (addr:long) -Copy a string from user space at given address. If the access would -fault, return "" and signal no errors. -.TP -user_string2:string (addr:long, err_msg:string) -Copy a string from user space at given address. If the access would -fault, return instead the err_msg value. -.TP -user_string_warn:string (addr:long) -Copy a string from user space at given address. If the access would -fault, signal a warning and return "". -.TP -user_string_quoted:string (addr:long) -Copy a string from user space at given address. Any ASCII characters -that are not printable are replaced by the corresponding escape -sequence in the returned string. -.TP -user_string_n:string (addr:long, n:long) -Copy a string of n bytes from user space at given address. If the access -would fault, return "". -.TP -user_string_n2:string (addr:long, n:long, err_msg:string) -Copy a string of n bytes from user space at given address. If the access -would fault, return the err_msg value. -.TP -user_string_n_warn:string (addr:long, n:long) -Copy a string of n bytes from user space at given address. If the access -would fault, signal a warning and return "". -.TP -user_string_n_quoted:string (addr:long, n:long) -Copy a string of n bytes from user space at given address. Any ASCII -characters that are not printable are replaced by the corresponding escape -sequence in the returned string. If the access would fault, return "". -.TP -user_short:long (addr:long) -Copy a short from user space at given address. If the access would fault, -return 0. -.TP -user_short_warn:long (addr:long) -Copy a short from user space at given address. If the access would fault, -signal a warning and return 0. -.TP -user_int:long (addr:long) -Copy an int from user space at given address. If the access would fault, -return 0. -.TP -user_int_warn:long (addr:long) -Copy an int from user space at given address. If the access would fault, -signal a warning and return 0. -.TP -user_long:long (addr:long) -Copy a long from user space at given address. If the access would fault, -return 0. -.TP -user_long_warn:long (addr:long) -Copy a long from user space at given address. If the access would fault, -signal a warning and return 0. -.TP -user_char:long (addr:long) -Copy a char from user space at given address. If the access would fault, -return 0. -.TP -user_char_warn:long (addr:long) -Copy a char from user space at given address. If the access would fault, -signal a warning and return 0. -.SS STRING -.TP -strlen:long (str:string) -Return the number of characters in str. -.TP -substr:string (str:string,start:long, stop:long) -Return the substring of str starting from character start and ending at character stop. -.TP -isinstr:long (s1:string, s2:string) -Return 1 if string s1 contains string s2, returns 0 otherwise. -.TP -strtol:long (str:string, base:long) -Convert the string representation of a number to a long using the numbering system -specified by base. For example, strtol("1000", 16) returns 4096. Returns 0 if the -string cannot be converted. -.TP -tokenize:string (str:string, delim:string) -Return the next token in the given str string, where the tokens are delimited -by one of the characters in the delim string. If the str string is not blank, -it returns the first token. If the str string is blank, it returns the next -token in the string passed in the previous call to tokenize. If no delimiter -is found, the entire remaining str string is returned. Returns blank when -no more tokens are left. - -.SS TIMESTAMP -.TP -get_cycles:long () -Return the processor cycle counter value, or 0 if unavailable. -.TP -gettimeofday_ns:long () -Return the number of nanoseconds since the UNIX epoch. -.TP -gettimeofday_us:long () -Return the number of microseconds since the UNIX epoch. -.TP -gettimeofday_ms:long () -Return the number of milliseconds since the UNIX epoch. -.TP -gettimeofday_s:long () -Return the number of seconds since the UNIX epoch. - -.SS CONTEXT INFO -.TP -cpu:long () -Return the current cpu number. -.TP -execname:string () -Return the name of the current process. -.TP -pexecname:string() -Return the name of the parent process. -.TP -tid:long () -Return the id of the current thread. -.TP -pid:long () -Return the id of the current process. -.TP -ppid:long () -Return the id of the parent process. -.TP -uid:long () -Return the uid of the current process. -.TP -euid:long () -Return the effective uid of the current process. -.TP -gid:long () -Return the gid of the current process. -.TP -egid:long () -Return the effective gid of the current process. -.TP -print_regs:unknown () -Print a register dump. -.TP -backtrace:string () -Return a string of hex addresses that are a backtrace of the stack. -It may be truncated due to maximum string length. -.TP -print_stack:unknown (bt:string) -Perform a symbolic lookup of the addresses in the given string, -which is assumed to be the result of a prior call to -.IR backtrace() . -Print one line per address, including the address, the name of the -function containing the address, and an estimate of its position -within that function. Return nothing. -.TP -print_backtrace:unknown () -Equivalent to -.IR print_stack(backtrace()) , -except that deeper stack nesting may be supported. Return nothing. -.TP -pp:string () -Return the probe point associated with the currently running probe handler, -including alias and wildcard expansion effects. -.TP -probefunc:string () -Return the probe point's function name, if known. -.TP -probemod:string () -Return the probe point's module name, if known. -.TP -target:long () -Return the pid of the target process. -.TP -user_mode:long () -Return 1 if the probe point occurred in user-mode. -.TP -is_return:long () -Return 1 if the probe point is a return probe. Deprecated. - -.SS TARGET_SET -.TP -target_set_pid:long (tid:long) -Return whether the given process-id is within the "target set", that is whether -it is a descendent of the top-level target() process. -.TP -target_set_report:unknown () -Print a report about the target set, and their ancestry. - -.SS ERRNO -.TP -errno_str:string (e:long) -Return the symbolic string associated with the given error code, like -"ENOENT" for the number 2, or "E#3333" for an out-of-range value like 3333. - -.SS TASK -.PP -These functions return data about a task. They all require -a task handle as input, such as the value return by task_current() or the variables -prev_task and next_task in the scheduler.ctxswitch probe alias. - -.TP -task_current:long() -Return the task_struct of the current process. - -.TP -task_parent:long(task:long) -Return the parent task_struct of the given task. -.TP -task_state:long(task:long) -Return the state of the given task, which can be one of the following: - - TASK_RUNNING 0 - TASK_INTERRUPTIBLE 1 - TASK_UNINTERRUPTIBLE 2 - TASK_STOPPED 4 - TASK_TRACED 8 - EXIT_ZOMBIE 16 - EXIT_DEAD 32 - -.TP -task_execname:string(task:long) -Return the name of the given task. - -.TP -task_pid:long(task:long) -Return the process id of the given task. - -.TP -task_tid:long(task:long) -Return the thread id of the given task. - -.TP -task_gid:long(task:long) -Return the group id of the given task. - -.TP -task_egid:long(task:long) -Return the effective group id of the given task. - -.TP -task_uid:long(task:long) -Return the user id of the given task. - -.TP -task_euid:long(task:long) -Return the effective user id of the given task. - -.TP -task_prio:long(task:long) -Return the priority of the given task. - -.TP -task_nice:long(task:long) -Return the nice value of the given task. - -.TP -task_cpu:long(task:long) -Return the scheduled cpu for the given task. - -.TP -task_open_file_handles:long(task:long) -Return the number of open file handles for the given task. - -.TP -task_max_file_handles:long(task:long) -Return the maximum number of file handles for the given task. - -.SS CPU REGISTERS -.TP -registers_valid:long () -Return 1 if register() and u_register() can be used -in the current context, or 0 otherwise. -For example, registers_valid() returns 0 when called from a begin or end probe. -.TP -register:long (name:string) -Return the value of the named CPU register, -as it was saved when the current probe point was hit. -If the register is 32 bits, it is sign-extended to 64 bits. - -For the i386 architecture, the following names are recognized. -(name1/name2 indicates that name1 and name2 are alternative names -for the same register.) -eax/ax, ebp/bp, ebx/bx, ecx/cx, edi/di, edx/dx, eflags/flags, -eip/ip, esi/si, esp/sp, orig_eax/orig_ax, -xcs/cs, xds/ds, xes/es, xfs/fs, xss/ss. - -For the x86_64 architecture, the following names are recognized: -64-bit registers: -r8, r9, r10, r11, r12, r13, r14, r15, -rax/ax, rbp/bp, rbx/bx, rcx/cx, rdi/di, rdx/dx, -rip/ip, rsi/si, rsp/sp; -32-bit registers: -eax, ebp, ebx, ecx, edx, edi, edx, eip, esi, esp, flags/eflags, orig_eax; -segment registers: xcs/cs, xss/ss. - -For powerpc, the following names are recognized: -r0, r1, ... r31, nip, msr, orig_gpr3, ctr, link, xer, ccr, softe, trap, -dar, dsisr, result. - -For s390x, the following names are recognized: -r0, r1, ... r15, args, psw.mask, psw.addr, orig_gpr2, ilc, trap. - -.TP -u_register:long (name:string) -Same as register(name), except that -if the register is 32 bits, it is zero-extended to 64 bits. - -.SS NUMBERED FUNCTION ARGUMENTS -The functions in this section provide the values of a probed function's -arguments. -They can be called when you have hit -a probe point at the entry to a function. -Arguments are referred to by number, starting at 1. -Ordinarily, you can access arguments by name as well, -but you may find these functions useful if the code you are probing -was built without debugging information. - -On 32-bit architectures -\(em and when probing 32-bit applications on 64-bit architectures \(em -a 64-bit argument occupies two "arg slots." -For example, if you are probing the following function - - void f(int a, long long b, char *c) - -you would refer to a, b, and c as int_arg(1), longlong_arg(2), and -pointer_arg(3), respectively, on a 64-bit architecture; -but on a 32-bit architecture, you would refer to c as pointer_arg(4) -(since b occupies slots 2 and 3). - -If the function you are probing doesn't follow the default rules -for argument passing, you need to call one of the following functions -(which see) in your handler before calling any *_arg function: -asmlinkage(), fastcall(), or regparm(). -(This isn't necessary when referring to arguments only by name.) -.TP -int_arg:long (n:long) -Return the value of argument n as a signed int -(i.e., a 32-bit integer sign-extended to 64 bits). -.TP -uint_arg:long (n:long) -Return the value of argument n as an unsigned int -(i.e., a 32-bit integer zero-extended to 64 bits). -.TP -long_arg:long (n:long) -Return the value of argument n as a signed long. -On architectures where a long is 32 bits, the value is sign-extended to 64 bits. -.TP -ulong_arg:long (n:long) -Return the value of argument n as an unsigned long. -On architectures where a long is 32 bits, the value is zero-extended to 64 bits. -.TP -longlong_arg:long (n:long) -Return the value of argument n as a 64-bit value. -.TP -ulonglong_arg:long (n:long) -Same as longlong_arg(n). -.TP -pointer_arg:long (n:long) -Same as ulong_arg(n). -Use with any type of pointer. -.TP -s32_arg:long (n:long) -Same as int_arg(n). -.TP -u32_arg:long (n:long) -Same as uint_arg(n). -.TP -s64_arg:long (n:long) -Same as longlong_arg(n). -.TP -u64_arg:long (n:long) -Same as [u]longlong_arg(n). -.TP -asmlinkage:unknown () -The probed kernel function is declared asmlinkage in the source. -.TP -fastcall:unknown () -The probed kernel function is declared fastcall in the source. -.TP -regparm:unknown (n:long) -The probed function was built with the gcc \-mregparm=n option. -(The i386 kernel is built with \-mregparm=3, so systemtap considers -regparm(3) the default for kernel functions on that architecture.) - -For some architectures, the *_arg functions may reject unusually high -values of n. - -.SS QUEUE_STATS -.PP -The queue_stats tapset provides functions that, given notifications of -elementary queuing events (wait, run, done), tracks averages such as -queue length, service and wait times, utilization. The following -three functions should be called from appropriate probes, in sequence. -.TP -qs_wait:unknown (qname:string) -Record that a new request was enqueued for the given queue name. -.TP -qs_run:unknown (qname:string) -Record that a previously enqueued request was removed from the given -wait queue and is now being serviced. -.TP -qs_done:unknown (qname:string) -Record that a request originally from the given queue has completed -being serviced. -.\" XXX: qs_time -.PP -Functions with the prefix -.BR qsq_ -are for querying the statistics averaged since the first queue operation -(or when -.BR qsq_start -was called). Since statistics are often fractional, a scale parameter -is multiplies the result to a more useful scale. For some fractions, -a scale of 100 will usefully return percentage numbers. -.TP -qsq_start:unknown (qname:string) -Reset the statistics counters for the given queue, and start tracking -anew from this moment. -.TP -qsq_print:unknown (qname:string) -Print a line containing a selection of the given queue's statistics. -.TP -qsq_utilization:long (qname:string, scale:long) -Return the fraction of elapsed time when the resource was utilized. -.TP -qsq_blocked:long (qname:string, scale:long) -Return the fraction of elapsed time when the wait queue was used. -.TP -qsq_wait_queue_length:long (qname:string, scale:long) -Return the average length of the wait queue. -.TP -qsq_service_time:long (qname:string, scale:long) -Return the average time required to service a request. -.TP -qsq_wait_time:long (qname:string, scale:long) -Return the average time a request took from being enqueued to completed. -.TP -qsq_throughput:long (qname:string, scale:long) -Return the average rate of requests per scale units of time. - -.SS INDENT -.PP -The indent tapset provides functions to generate indented lines for -nested kinds of trace messages. Each line contains a relative -timestamp, and the process name / pid. -.TP -thread_indent:string (delta:long) -Return a string with an appropriate indentation for this thread. -Call it with a small positive or matching negative delta. -If this is the outermost, initial level of indentation, reset the -relative timestamp base to zero. -.TP -thread_timestamp:long () -Return an absolute timestamp value for use by the indentation function. -The default function uses -.IR gettimeofday_us - -.SS SYSTEM -.TP -system (cmd:string) -Runs a command on the system. The command will run in the background -when the current probe completes. - -.SS NUMA -.TP -addr_to_node:long (addr:long) -Return which node the given address belongs to in a NUMA system. - -.SS CTIME -.TP -ctime:string (seconds:long) -Return a simple textual rendering (e.g., "Wed\ Jun\ 30\ 21:49:008\ 1993") -of the given number of seconds since the epoch, as perhaps returned by -.IR gettimeofday_s() . - -.SS PERFMON -.TP -read_counter:long (handle:long) -Returns the value for the processor's performance counter for the associated -handle. The body of the a perfmon probe should set record -the handle being used for that event. - -.SS SOCKETS -These functions convert arguments in the socket tapset back and -forth between their numeric and string representations. -See -.IR stapprobes.socket (5) -for details. - -.TP -sock_prot_num2str:string (proto:long) -Returns the string representation of the given protocol value. -.TP -sock_prot_str2num:long (proto:string) -Returns the numeric value associated with the given protocol string. -.TP -sock_fam_num2str:string (family:long) -Returns the string representation of the given protocol family value. -.TP -sock_fam_str2num:long (family:string) -Returns the numeric value associated with the given protocol family string. -.TP -sock_state_num2str:string (state:long) -Returns the string representation of the given socket state value. -.TP -sock_state_str2num:long (state:string) -Returns the numeric value associated with the given socket state string. -.TP -sock_type_num2str:string (type:long) -Returns the string representation of the given socket type value. -.TP -sock_type_str2num:long (type:string) -Returns the numeric value associated with the given socket type string. -.TP -sock_flags_num2str:string (flags:long) -Returns the string representation of the given socket flags value. -.TP -msg_flags_num2str:string (flags:long) -Returns the string representation of the given message flags bit map. - -.SS INET -These functions convert between network (big-endian) and host byte order, like their -namesake C functions. -.TP -ntohll:long (x:long) -Convert from network to host byte order, 64-bit. -.TP -ntohl:long (x:long) -Convert from network to host byte order, 32-bit. -.TP -ntohs:long (x:long) -Convert from network to host byte order, 16-bit. -.TP -htonll:long (x:long) -Convert from host to network byte order, 64-bit. -.TP -htonl:long (x:long) -Convert from host to network byte order, 32-bit. -.TP -htons:long (x:long) -Convert from host to network byte order, 16-bit. - -.SS SIGNAL -.TP -get_sa_flags:long (act:long) -Returns the numeric value of sa_flags. -.TP -get_sa_handler:long (act:long) -Returns the numeric value of sa_handler. -.TP -sigset_mask_str:string (mask:long) -Returns the string representation of the sigset sa_mask. -.TP -is_sig_blocked:long (task:long, sig:long) -Returns 1 if the signal is currently blocked, or 0 if it is not. -.TP -sa_flags_str:string (sa_flags:long) -Returns the string representation of sa_flags. -.TP -sa_handler_str(handler) -Returns the string representation of sa_handler. If it is not SIG_DFL, SIG_IGN -or SIG_ERR, it will return the address of the handler. -.TP -signal_str(num) -Returns the string representation of the given signal number. - -.SS DEVICE -.TP -MAJOR:long(dev:long) -Extracts the major device number from a kernel device number (kdev_t). -.TP -MINOR:long(dev:long) -Extracts the minor device number from a kernel device number (kdev_t). -.TP -MKDEV:long(major:long, minor:long) -Creates a value that can be compared to a kernel device number (kdev_t). -.TP -usrdev2kerndev:long(dev:long) -Converts a user-space device number into the format used in the kernel. - -.SH FILES -.nh -.IR @prefix@/share/systemtap/tapset -.hy - -.SH SEE ALSO -.IR stap (1) diff --git a/stapprobes.3stap.in b/stapprobes.3stap.in new file mode 100644 index 00000000..f175e6e0 --- /dev/null +++ b/stapprobes.3stap.in @@ -0,0 +1,676 @@ +.\" -*- nroff -*- +.TH STAPPROBES 3stap @DATE@ "Red Hat" +.SH NAME +stapprobes \- systemtap probe points + +.\" macros +.de SAMPLE +.br +.RS +.nf +.nh +.. +.de ESAMPLE +.hy +.fi +.RE +.. + +.SH DESCRIPTION +The following sections enumerate the variety of probe points supported +by the systemtap translator, and additional aliases defined by +standard tapset scripts. +.PP +The general probe point syntax is a dotted-symbol sequence. This +allows a breakdown of the event namespace into parts, somewhat like +the Domain Name System does on the Internet. Each component +identifier may be parametrized by a string or number literal, with a +syntax like a function call. A component may include a "*" character, +to expand to a set of matching probe points. Probe aliases likewise +expand to other probe points. Each and every resulting probe point is +normally resolved to some low-level system instrumentation facility +(e.g., a kprobe address, marker, or a timer configuration), otherwise +the elaboration phase will fail. +.PP +However, a probe point may be followed by a "?" character, to indicate +that it is optional, and that no error should result if it fails to +resolve. Optionalness passes down through all levels of +alias/wildcard expansion. Alternately, a probe point may be followed +by a "!" character, to indicate that it is both optional and +sufficient. (Think vaguely of the prolog cut operator.) If it does +resolve, then no further probe points in the same comma-separated list +will be resolved. Therefore, the "!" sufficiency mark only makes +sense in a list of probe point alternatives. +.PP +Additionally, a probe point may be followed by a "if (expr)" statement, in +order to enable/disable the probe point on-the-fly. With the "if" statement, +if the "expr" is false when the probe point is hit, the whole probe body +including alias's body is skipped. The condition is stacked up through +all levels of alias/wildcard expansion. So the final condition becomes +the logical-and of conditions of all expanded alias/wildcard. + +These are all syntactically valid probe points: + +.SAMPLE +kernel.function("foo").return +syscall(22) +user.inode("/bin/vi").statement(0x2222) +end +syscall.* +kernel.function("no_such_function") ? +module("awol").function("no_such_function") ! +signal.*? if (switch) +.ESAMPLE + +Probes may be broadly classified into "synchronous" and +"asynchronous". A "synchronous" event is deemed to occur when any +processor executes an instruction matched by the specification. This +gives these probes a reference point (instruction address) from which +more contextual data may be available. Other families of probe points +refer to "asynchronous" events such as timers/counters rolling over, +where there is no fixed reference point that is related. Each probe +point specification may match multiple locations (for example, using +wildcards or aliases), and all them are then probed. A probe +declaration may also contain several comma-separated specifications, +all of which are probed. + +.SS BEGIN/END/ERROR + +The probe points +.IR begin " and " end +are defined by the translator to refer to the time of session startup +and shutdown. All "begin" probe handlers are run, in some sequence, +during the startup of the session. All global variables will have +been initialized prior to this point. All "end" probes are run, in +some sequence, during the +.I normal +shutdown of a session, such as in the aftermath of an +.I exit () +function call, or an interruption from the user. In the case of an +error-triggered shutdown, "end" probes are not run. There are no +target variables available in either context. +.PP +If the order of execution among "begin" or "end" probes is significant, +then an optional sequence number may be provided: + +.SAMPLE +begin(N) +end(N) +.ESAMPLE + +The number N may be positive or negative. The probe handlers are run in +increasing order, and the order between handlers with the same sequence +number is unspecified. When "begin" or "end" are given without a +sequence, they are effectively sequence zero. + +The +.IR error +probe point is similar to the +.IR end +probe, except that each such probe handler run when the session ends +after errors have occurred. In such cases, "end" probes are skipped, +but each "error" prober is still attempted. This kind of probe can be +used to clean up or emit a "final gasp". It may also be numerically +parametrized to set a sequence. + +.SS NEVER +The probe point +.IR never +is specially defined by the translator to mean "never". Its probe +handler is never run, though its statements are analyzed for symbol / +type correctness as usual. This probe point may be useful in +conjunction with optional probes. + +.SS SYSCALL + +The +.IR syscall.* +aliases define several hundred probes, too many to +summarize here. They are: + +.SAMPLE +syscall.NAME +.br +syscall.NAME.return +.ESAMPLE + +Generally, two probes are defined for each normal system call as listed in the +.IR syscalls(2) +manual page, one for entry and one for return. Those system calls that never +return do not have a corresponding +.IR .return +probe. +.PP +Each probe alias defines a variety of variables. Looking at the tapset source +code is the most reliable way. Generally, each variable listed in the standard +manual page is made available as a script-level variable, so +.IR syscall.open +exposes +.IR filename ", " flags ", and " mode . +In addition, a standard suite of variables is available at most aliases: +.TP +.IR argstr +A pretty-printed form of the entire argument list, without parentheses. +.TP +.IR name +The name of the system call. +.TP +.IR retstr +For return probes, a pretty-printed form of the system-call result. +.PP +Not all probe aliases obey all of these general guidelines. Please report +any bothersome ones you encounter as a bug. + + +.SS TIMERS + +Intervals defined by the standard kernel "jiffies" timer may be used +to trigger probe handlers asynchronously. Two probe point variants +are supported by the translator: + +.SAMPLE +timer.jiffies(N) +timer.jiffies(N).randomize(M) +.ESAMPLE + +The probe handler is run every N jiffies (a kernel-defined unit of +time, typically between 1 and 60 ms). If the "randomize" component is +given, a linearly distributed random value in the range [\-M..+M] is +added to N every time the handler is run. N is restricted to a +reasonable range (1 to around a million), and M is restricted to be +smaller than N. There are no target variables provided in either +context. It is possible for such probes to be run concurrently on +a multi-processor computer. +.PP +Alternatively, intervals may be specified in units of time. +There are two probe point variants similar to the jiffies timer: + +.SAMPLE +timer.ms(N) +timer.ms(N).randomize(M) +.ESAMPLE + +Here, N and M are specified in milliseconds, but the full options for units +are seconds (s/sec), milliseconds (ms/msec), microseconds (us/usec), +nanoseconds (ns/nsec), and hertz (hz). Randomization is not supported for +hertz timers. + +The actual resolution of the timers depends on the target kernel. For +kernels prior to 2.6.17, timers are limited to jiffies resolution, so +intervals are rounded up to the nearest jiffies interval. After 2.6.17, +the implementation uses hrtimers for tighter precision, though the actual +resolution will be arch-dependent. In either case, if the "randomize" +component is given, then the random value will be added to the interval +before any rounding occurs. +.PP +Profiling timers are also available to provide probes that execute on all +CPUs at the rate of the system tick (CONFIG_HZ). +This probe takes no parameters. + +.SAMPLE +timer.profile +.ESAMPLE + +Full context information of the interrupted process is available, making +this probe suitable for a time-based sampling profiler. + +.SS DWARF + +This family of probe points uses symbolic debugging information for +the target kernel/module/program, as may be found in unstripped +executables, or the separate +.I debuginfo +packages. They allow placement of probes logically into the execution +path of the target program, by specifying a set of points in the +source or object code. When a matching statement executes on any +processor, the probe handler is run in that context. +.PP +Points in a kernel, which are identified by +module, source file, line number, function name, or some +combination of these. +.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 +.B after +the return from the named function, so the return value is available +as the "$return" context variable. The +.B .inline +modifier for +.B .function +filters the results to include only instances of inlined functions. +The +.B .call +modifier selects the opposite subset. Inline functions do not have an +identifiable return point, so +.B .return +is not supported on +.B .inline +probes. The +.B .statement +variant places a probe at the exact spot, exposing those local variables +that are visible there. + +.SAMPLE +kernel.function(PATTERN) +.br +kernel.function(PATTERN).call +.br +kernel.function(PATTERN).return +.br +kernel.function(PATTERN).inline +.br +kernel.function(PATTERN).label(LPATTERN) +.br +module(MPATTERN).function(PATTERN) +.br +module(MPATTERN).function(PATTERN).call +.br +module(MPATTERN).function(PATTERN).return +.br +module(MPATTERN).function(PATTERN).inline +.br +.br +kernel.statement(PATTERN) +.br +kernel.statement(ADDRESS).absolute +.br +module(MPATTERN).statement(PATTERN) +.ESAMPLE + +In the above list, MPATTERN stands for a string literal that aims to +identify the loaded kernel module of interest and LPATTERN stands for +a source program label. Both MPATTERN and LPATTERN may include the "*" +"[]", and "?" wildcards. +PATTERN stands for a string literal that +aims to identify a point in the program. It is made up of three +parts: +.IP \(bu 4 +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. +.IP \(bu 4 +The second part is optional and begins with the "@" character. +It is followed by the path to the source file containing the function, +which may include a wildcard pattern, such as mm/slab*. +If it does not match as is, an implicit "*/" is optionally added +.I before +the pattern, so that a script need only name the last few components +of a possibly long source directory path. +.IP \(bu 4 +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 ":" +or a "+". The line number is assumed to be an +absolute line number if preceded by a ":", or relative to the entry of +the function if preceded by a "+". +All the lines in the function can be matched with ":*". +A range of lines x through y can be matched with ":x-y". +.PP +As an alternative, PATTERN may be a numeric constant, indicating an +address. Such an address may be found from symbol tables of the +appropriate kernel / module object file. It is verified against +known statement code boundaries, and will be relocated for use at +run time. +.PP +In guru mode only, absolute kernel-space addresses may be specified with +the ".absolute" suffix. Such an address is considered already relocated, +as if it came from +.BR /proc/kallsyms , +so it cannot be checked against statement/instruction boundaries. +.PP +Some of the source-level context variables, such as function parameters, +locals, globals visible in the compilation unit, may be visible to +probe handlers. They may refer to these variables by prefixing their +name with "$" within the scripts. In addition, a special syntax +allows limited traversal of structures, pointers, and arrays. +.TP +$var +refers to an in-scope variable "var". If it's an integer-like type, +it will be cast to a 64-bit int for systemtap script use. String-like +pointers (char *) may be copied to systemtap string values using the +.IR kernel_string " or " user_string +functions. +.TP +$var\->field +traversal to a structure's field. The indirection operator +may be repeated to follow more levels of pointers. +.TP +$return +is available in return probes only for functions that are declared +with a return value. +.TP +.TP +$var[N] +indexes into an array. The index is given with a +literal number. +.TP +$$vars +expands to a character string that is equivalent to +sprintf("parm1=%x ... parmN=%x var1=%x ... varN=%x", parm1, ..., parmN, +var1, ..., varN) +.TP +$$locals +expands to a subset of $$vars for only local variables. +.TP +$$parms +expands to a subset of $$vars for only function parameters. +.TP +$$return +is available in return probes only. It expands to a string that +is equivalent to sprintf("return=%x", $return) +if the probed function has a return value, or else an empty string. +.PP +For ".return" probes, context variables other than the "$return" +value itself are only available for the function call parameters. +The expressions evaluate to the +.IR entry-time +values of those variables, since that is when a snapshot is taken. +Other local variables are not generally accessible, since by the time +a ".return" probe hits, the probed function will have already returned. + + +.SS USER-SPACE +Early prototype support for user-space probing is available in the +form of a non-symbolic probe point: +.SAMPLE +process(PID).statement(ADDRESS).absolute +.ESAMPLE +is analogous to +.IR +kernel.statement(ADDRESS).absolute +in that both use raw (unverified) virtual addresses and provide +no $variables. The target PID parameter must identify a running +process, and ADDRESS should identify a valid instruction address. +All threads of that process will be probed. +.PP +Additional user-space probing is available in the following forms: +.SAMPLE +process(PID).begin +process("PATH").begin +process.begin +process(PID).thread.begin +process("PATH").thread.begin +process.thread.begin +process(PID).end +process("PATH").end +process.end +process(PID).thread.end +process("PATH").thread.end +process.thread.end +process(PID).syscall +process("PATH").syscall +process.syscall +process(PID).syscall.return +process("PATH").syscall.return +process.syscall.return +process(PID).insn +process("PATH").insn +process(PID).insn.block +process("PATH").insn.block +process("PATH").mark("LABEL") +.ESAMPLE +.PP +A +.B .begin +probe gets called when new process described by PID or PATH gets created. +A +.B .thread.begin +probe gets called when a new thread described by PID or PATH gets created. +A +.B .end +probe gets called when process described by PID or PATH dies. +A +.B .thread.end +probe gets called when a thread described by PID or PATH dies. +A +.B .syscall +probe gets called when a thread described by PID or PATH makes a +system call. The system call number is available in the +.BR $syscall +context variable, and the first 6 arguments of the system call +are available in the +.BR $argN +(ex. $arg1, $arg2, ...) context variable. +A +.B .syscall.return +probe gets called when a thread described by PID or PATH returns from a +system call. The system call number is available in the +.BR $syscall +context variable, and the return value of the system call is available +in the +.BR $return +context variable. +A +.B .insn +probe gets called for every single-stepped instruction of the process described by PID or PATH. +A +.B .insn.block +probe gets called for every block-stepped instruction of the process described by PID or PATH. +A +.B .mark +probe gets called via a static probe which is defined in the +application by +STAP_PROBE1(handle,LABEL,arg1), which is defined in sdt.h. The handle is an application handle, +LABEL corresponds to the .mark argument, and arg1 is the argument. +STAP_PROBE1 is used for probes with 1 argument, STAP_PROBE2 is used +for probes with 2 arguments, and so on. +The arguments of the probe are available in the context variables +$arg1, $arg2, ... An alternative to using the STAP_PROBE macros is to +use the dtrace script to create custom macros. +.PP +Note that +.I PATH +names refer to executables that are searched the same way shells do: relative +to the working directory if they contain a "/" character, otherwise in +.BR $PATH . +If a process probe is specified without a PID or PATH, all user +threads are probed. + +.SS PROCFS + +These probe points allow procfs "files" in +/proc/systemtap/MODNAME to be created, read and written +.RI ( MODNAME +is the name of the systemtap module). The +.I proc +filesystem is a pseudo-filesystem which is used an an interface to +kernel data structures. There are four probe point variants supported +by the translator: + +.SAMPLE +procfs("PATH").read +procfs("PATH").write +procfs.read +procfs.write +.ESAMPLE + +.I PATH +is the file name (relative to /proc/systemtap/MODNAME) to be created. +If no +.I PATH +is specified (as in the last two variants above), +.I PATH +defaults to "command". +.PP +When a user reads /proc/systemtap/MODNAME/PATH, the corresponding +procfs +.I read +probe is triggered. The string data to be read should be assigned to +a variable named +.IR $value , +like this: + +.SAMPLE +procfs("PATH").read { $value = "100\\n" } +.ESAMPLE +.PP +When a user writes into /proc/systemtap/MODNAME/PATH, the +corresponding procfs +.I write +probe is triggered. The data the user wrote is available in the +string variable named +.IR $value , +like this: + +.SAMPLE +procfs("PATH").write { printf("user wrote: %s", $value) } +.ESAMPLE + +.SS MARKERS + +This family of probe points hooks up to static probing markers +inserted into the kernel or modules. These markers are special macro +calls inserted by kernel developers to make probing faster and more +reliable than with DWARF-based probes. Further, DWARF debugging +information is +.I not +required to probe markers. + +Marker probe points begin with +.BR kernel . +The next part names the marker itself: +.BR mark("name") . +The marker name string, which may contain the usual wildcard characters, +is matched against the names given to the marker macros when the kernel +and/or module was compiled. Optionally, you can specify +.BR format("format") . +Specifying the marker format string allows differentation between two +markers with the same name but different marker format strings. + +The handler associated with a marker-based probe may read the +optional parameters specified at the macro call site. These are +named +.BR $arg1 " through " $argNN , +where NN is the number of parameters supplied by the macro. Number +and string parameters are passed in a type-safe manner. + +The marker format string associated with a marker is available in +.BR $format . +And also the marker name string is avalable in +.BR $name . + +.SS TRACEPOINTS + +This family of probe points hooks up to static probing tracepoints +inserted into the kernel or modules. As with markers, these +tracepoints are special macro calls inserted by kernel developers to +make probing faster and more reliable than with DWARF-based probes, +and DWARF debugging information is not required to probe tracepoints. +Tracepoints have an extra advantage of more strongly-typed parameters +than markers. + +Tracepoint probes begin with +.BR kernel . +The next part names the tracepoint itself: +.BR trace("name") . +The tracepoint name string, which may contain the usual wildcard +characters, is matched against the names defined by the kernel +developers in the tracepoint header files. + +The handler associated with a tracepoint-based probe may read the +optional parameters specified at the macro call site. These are +named according to the declaration by the tracepoint author. For +example, the tracepoint probe +.BR kernel.trace("sched_switch") +provides the parameters +.BR $rq ", " $prev ", and " $next . +If the parameter is a complex type, as in a struct pointer, then a +script can access fields with the same syntax as DWARF $target +variables. Also, tracepoint parameters cannot be modified, but in +guru-mode a script may modify fields of parameters. + +The name of the tracepoint is available in +.BR $$name , +and a string of name=value pairs for all parameters of the tracepoint +is available in +.BR $$vars " or " $$parms . + +.SS PERFORMANCE MONITORING HARDWARE + +The perfmon family of probe points is used to access the performance +monitoring hardware available in modern processors. This family of +probes points needs the perfmon2 support in the kernel to access the +performance monitoring hardware. +.PP +Performance monitor hardware points begin with a +.BR perfmon ". " +The next part of the names the event being counted +.BR counter("event") . +The event names are processor implementation specific with the +execption of the generic +.BR cycles " and " instructions +events, which are available on all processors. This sets up a counter +on the processor to count the number of events occuring on the +processor. For more details on the performance monitoring events +available on a specific processor use the command perfmon2 command: + +.SAMPLE +pfmon \-l +.ESAMPLE +.TP +$counter +is a handle used in the body of the probe for operations +involving the counter associated with the probe. +.TP +read_counter +is a function that is passed the handle for the perfmon probe and returns +the current count for the event. + +.SH EXAMPLES +.PP +Here are some example probe points, defining the associated events. +.TP +begin, end, end +refers to the startup and normal shutdown of the session. In this +case, the handler would run once during startup and twice during +shutdown. +.TP +timer.jiffies(1000).randomize(200) +refers to a periodic interrupt, every 1000 +/\- 200 jiffies. +.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 +kernel.mark("getuid") +refers to an STAP_MARK(getuid, ...) macro call in the kernel. +.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. +.TP +kernel.statement("*@kernel/sched.c:2917") +refers to the statement of line 2917 within "kernel/sched.c". +.TP +kernel.statement("bio_init@fs/bio.c+3") +refers to the statement at line bio_init+3 within "fs/bio.c". +.TP +syscall.*.return +refers to the group of probe aliases with any name in the third position + +.SH SEE ALSO +.IR stap (1), +.IR stapprobes.iosched (3stap), +.IR stapprobes.netdev (3stap), +.IR stapprobes.nfs (3stap), +.IR stapprobes.nfsd (3stap), +.IR stapprobes.pagefault (3stap), +.IR stapprobes.process (3stap), +.IR stapprobes.rpc (3stap), +.IR stapprobes.scsi (3stap), +.IR stapprobes.signal (3stap), +.IR stapprobes.socket (3stap), +.IR stapprobes.tcp (3stap), +.IR stapprobes.udp (3stap), +.IR proc (3stap) diff --git a/stapprobes.5.in b/stapprobes.5.in deleted file mode 100644 index f4a872cb..00000000 --- a/stapprobes.5.in +++ /dev/null @@ -1,676 +0,0 @@ -.\" -*- nroff -*- -.TH STAPPROBES 5 @DATE@ "Red Hat" -.SH NAME -stapprobes \- systemtap probe points - -.\" macros -.de SAMPLE -.br -.RS -.nf -.nh -.. -.de ESAMPLE -.hy -.fi -.RE -.. - -.SH DESCRIPTION -The following sections enumerate the variety of probe points supported -by the systemtap translator, and additional aliases defined by -standard tapset scripts. -.PP -The general probe point syntax is a dotted-symbol sequence. This -allows a breakdown of the event namespace into parts, somewhat like -the Domain Name System does on the Internet. Each component -identifier may be parametrized by a string or number literal, with a -syntax like a function call. A component may include a "*" character, -to expand to a set of matching probe points. Probe aliases likewise -expand to other probe points. Each and every resulting probe point is -normally resolved to some low-level system instrumentation facility -(e.g., a kprobe address, marker, or a timer configuration), otherwise -the elaboration phase will fail. -.PP -However, a probe point may be followed by a "?" character, to indicate -that it is optional, and that no error should result if it fails to -resolve. Optionalness passes down through all levels of -alias/wildcard expansion. Alternately, a probe point may be followed -by a "!" character, to indicate that it is both optional and -sufficient. (Think vaguely of the prolog cut operator.) If it does -resolve, then no further probe points in the same comma-separated list -will be resolved. Therefore, the "!" sufficiency mark only makes -sense in a list of probe point alternatives. -.PP -Additionally, a probe point may be followed by a "if (expr)" statement, in -order to enable/disable the probe point on-the-fly. With the "if" statement, -if the "expr" is false when the probe point is hit, the whole probe body -including alias's body is skipped. The condition is stacked up through -all levels of alias/wildcard expansion. So the final condition becomes -the logical-and of conditions of all expanded alias/wildcard. - -These are all syntactically valid probe points: - -.SAMPLE -kernel.function("foo").return -syscall(22) -user.inode("/bin/vi").statement(0x2222) -end -syscall.* -kernel.function("no_such_function") ? -module("awol").function("no_such_function") ! -signal.*? if (switch) -.ESAMPLE - -Probes may be broadly classified into "synchronous" and -"asynchronous". A "synchronous" event is deemed to occur when any -processor executes an instruction matched by the specification. This -gives these probes a reference point (instruction address) from which -more contextual data may be available. Other families of probe points -refer to "asynchronous" events such as timers/counters rolling over, -where there is no fixed reference point that is related. Each probe -point specification may match multiple locations (for example, using -wildcards or aliases), and all them are then probed. A probe -declaration may also contain several comma-separated specifications, -all of which are probed. - -.SS BEGIN/END/ERROR - -The probe points -.IR begin " and " end -are defined by the translator to refer to the time of session startup -and shutdown. All "begin" probe handlers are run, in some sequence, -during the startup of the session. All global variables will have -been initialized prior to this point. All "end" probes are run, in -some sequence, during the -.I normal -shutdown of a session, such as in the aftermath of an -.I exit () -function call, or an interruption from the user. In the case of an -error-triggered shutdown, "end" probes are not run. There are no -target variables available in either context. -.PP -If the order of execution among "begin" or "end" probes is significant, -then an optional sequence number may be provided: - -.SAMPLE -begin(N) -end(N) -.ESAMPLE - -The number N may be positive or negative. The probe handlers are run in -increasing order, and the order between handlers with the same sequence -number is unspecified. When "begin" or "end" are given without a -sequence, they are effectively sequence zero. - -The -.IR error -probe point is similar to the -.IR end -probe, except that each such probe handler run when the session ends -after errors have occurred. In such cases, "end" probes are skipped, -but each "error" prober is still attempted. This kind of probe can be -used to clean up or emit a "final gasp". It may also be numerically -parametrized to set a sequence. - -.SS NEVER -The probe point -.IR never -is specially defined by the translator to mean "never". Its probe -handler is never run, though its statements are analyzed for symbol / -type correctness as usual. This probe point may be useful in -conjunction with optional probes. - -.SS SYSCALL - -The -.IR syscall.* -aliases define several hundred probes, too many to -summarize here. They are: - -.SAMPLE -syscall.NAME -.br -syscall.NAME.return -.ESAMPLE - -Generally, two probes are defined for each normal system call as listed in the -.IR syscalls(2) -manual page, one for entry and one for return. Those system calls that never -return do not have a corresponding -.IR .return -probe. -.PP -Each probe alias defines a variety of variables. Looking at the tapset source -code is the most reliable way. Generally, each variable listed in the standard -manual page is made available as a script-level variable, so -.IR syscall.open -exposes -.IR filename ", " flags ", and " mode . -In addition, a standard suite of variables is available at most aliases: -.TP -.IR argstr -A pretty-printed form of the entire argument list, without parentheses. -.TP -.IR name -The name of the system call. -.TP -.IR retstr -For return probes, a pretty-printed form of the system-call result. -.PP -Not all probe aliases obey all of these general guidelines. Please report -any bothersome ones you encounter as a bug. - - -.SS TIMERS - -Intervals defined by the standard kernel "jiffies" timer may be used -to trigger probe handlers asynchronously. Two probe point variants -are supported by the translator: - -.SAMPLE -timer.jiffies(N) -timer.jiffies(N).randomize(M) -.ESAMPLE - -The probe handler is run every N jiffies (a kernel-defined unit of -time, typically between 1 and 60 ms). If the "randomize" component is -given, a linearly distributed random value in the range [\-M..+M] is -added to N every time the handler is run. N is restricted to a -reasonable range (1 to around a million), and M is restricted to be -smaller than N. There are no target variables provided in either -context. It is possible for such probes to be run concurrently on -a multi-processor computer. -.PP -Alternatively, intervals may be specified in units of time. -There are two probe point variants similar to the jiffies timer: - -.SAMPLE -timer.ms(N) -timer.ms(N).randomize(M) -.ESAMPLE - -Here, N and M are specified in milliseconds, but the full options for units -are seconds (s/sec), milliseconds (ms/msec), microseconds (us/usec), -nanoseconds (ns/nsec), and hertz (hz). Randomization is not supported for -hertz timers. - -The actual resolution of the timers depends on the target kernel. For -kernels prior to 2.6.17, timers are limited to jiffies resolution, so -intervals are rounded up to the nearest jiffies interval. After 2.6.17, -the implementation uses hrtimers for tighter precision, though the actual -resolution will be arch-dependent. In either case, if the "randomize" -component is given, then the random value will be added to the interval -before any rounding occurs. -.PP -Profiling timers are also available to provide probes that execute on all -CPUs at the rate of the system tick (CONFIG_HZ). -This probe takes no parameters. - -.SAMPLE -timer.profile -.ESAMPLE - -Full context information of the interrupted process is available, making -this probe suitable for a time-based sampling profiler. - -.SS DWARF - -This family of probe points uses symbolic debugging information for -the target kernel/module/program, as may be found in unstripped -executables, or the separate -.I debuginfo -packages. They allow placement of probes logically into the execution -path of the target program, by specifying a set of points in the -source or object code. When a matching statement executes on any -processor, the probe handler is run in that context. -.PP -Points in a kernel, which are identified by -module, source file, line number, function name, or some -combination of these. -.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 -.B after -the return from the named function, so the return value is available -as the "$return" context variable. The -.B .inline -modifier for -.B .function -filters the results to include only instances of inlined functions. -The -.B .call -modifier selects the opposite subset. Inline functions do not have an -identifiable return point, so -.B .return -is not supported on -.B .inline -probes. The -.B .statement -variant places a probe at the exact spot, exposing those local variables -that are visible there. - -.SAMPLE -kernel.function(PATTERN) -.br -kernel.function(PATTERN).call -.br -kernel.function(PATTERN).return -.br -kernel.function(PATTERN).inline -.br -kernel.function(PATTERN).label(LPATTERN) -.br -module(MPATTERN).function(PATTERN) -.br -module(MPATTERN).function(PATTERN).call -.br -module(MPATTERN).function(PATTERN).return -.br -module(MPATTERN).function(PATTERN).inline -.br -.br -kernel.statement(PATTERN) -.br -kernel.statement(ADDRESS).absolute -.br -module(MPATTERN).statement(PATTERN) -.ESAMPLE - -In the above list, MPATTERN stands for a string literal that aims to -identify the loaded kernel module of interest and LPATTERN stands for -a source program label. Both MPATTERN and LPATTERN may include the "*" -"[]", and "?" wildcards. -PATTERN stands for a string literal that -aims to identify a point in the program. It is made up of three -parts: -.IP \(bu 4 -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. -.IP \(bu 4 -The second part is optional and begins with the "@" character. -It is followed by the path to the source file containing the function, -which may include a wildcard pattern, such as mm/slab*. -If it does not match as is, an implicit "*/" is optionally added -.I before -the pattern, so that a script need only name the last few components -of a possibly long source directory path. -.IP \(bu 4 -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 ":" -or a "+". The line number is assumed to be an -absolute line number if preceded by a ":", or relative to the entry of -the function if preceded by a "+". -All the lines in the function can be matched with ":*". -A range of lines x through y can be matched with ":x-y". -.PP -As an alternative, PATTERN may be a numeric constant, indicating an -address. Such an address may be found from symbol tables of the -appropriate kernel / module object file. It is verified against -known statement code boundaries, and will be relocated for use at -run time. -.PP -In guru mode only, absolute kernel-space addresses may be specified with -the ".absolute" suffix. Such an address is considered already relocated, -as if it came from -.BR /proc/kallsyms , -so it cannot be checked against statement/instruction boundaries. -.PP -Some of the source-level context variables, such as function parameters, -locals, globals visible in the compilation unit, may be visible to -probe handlers. They may refer to these variables by prefixing their -name with "$" within the scripts. In addition, a special syntax -allows limited traversal of structures, pointers, and arrays. -.TP -$var -refers to an in-scope variable "var". If it's an integer-like type, -it will be cast to a 64-bit int for systemtap script use. String-like -pointers (char *) may be copied to systemtap string values using the -.IR kernel_string " or " user_string -functions. -.TP -$var\->field -traversal to a structure's field. The indirection operator -may be repeated to follow more levels of pointers. -.TP -$return -is available in return probes only for functions that are declared -with a return value. -.TP -.TP -$var[N] -indexes into an array. The index is given with a -literal number. -.TP -$$vars -expands to a character string that is equivalent to -sprintf("parm1=%x ... parmN=%x var1=%x ... varN=%x", parm1, ..., parmN, -var1, ..., varN) -.TP -$$locals -expands to a subset of $$vars for only local variables. -.TP -$$parms -expands to a subset of $$vars for only function parameters. -.TP -$$return -is available in return probes only. It expands to a string that -is equivalent to sprintf("return=%x", $return) -if the probed function has a return value, or else an empty string. -.PP -For ".return" probes, context variables other than the "$return" -value itself are only available for the function call parameters. -The expressions evaluate to the -.IR entry-time -values of those variables, since that is when a snapshot is taken. -Other local variables are not generally accessible, since by the time -a ".return" probe hits, the probed function will have already returned. - - -.SS USER-SPACE -Early prototype support for user-space probing is available in the -form of a non-symbolic probe point: -.SAMPLE -process(PID).statement(ADDRESS).absolute -.ESAMPLE -is analogous to -.IR -kernel.statement(ADDRESS).absolute -in that both use raw (unverified) virtual addresses and provide -no $variables. The target PID parameter must identify a running -process, and ADDRESS should identify a valid instruction address. -All threads of that process will be probed. -.PP -Additional user-space probing is available in the following forms: -.SAMPLE -process(PID).begin -process("PATH").begin -process.begin -process(PID).thread.begin -process("PATH").thread.begin -process.thread.begin -process(PID).end -process("PATH").end -process.end -process(PID).thread.end -process("PATH").thread.end -process.thread.end -process(PID).syscall -process("PATH").syscall -process.syscall -process(PID).syscall.return -process("PATH").syscall.return -process.syscall.return -process(PID).insn -process("PATH").insn -process(PID).insn.block -process("PATH").insn.block -process("PATH").mark("LABEL") -.ESAMPLE -.PP -A -.B .begin -probe gets called when new process described by PID or PATH gets created. -A -.B .thread.begin -probe gets called when a new thread described by PID or PATH gets created. -A -.B .end -probe gets called when process described by PID or PATH dies. -A -.B .thread.end -probe gets called when a thread described by PID or PATH dies. -A -.B .syscall -probe gets called when a thread described by PID or PATH makes a -system call. The system call number is available in the -.BR $syscall -context variable, and the first 6 arguments of the system call -are available in the -.BR $argN -(ex. $arg1, $arg2, ...) context variable. -A -.B .syscall.return -probe gets called when a thread described by PID or PATH returns from a -system call. The system call number is available in the -.BR $syscall -context variable, and the return value of the system call is available -in the -.BR $return -context variable. -A -.B .insn -probe gets called for every single-stepped instruction of the process described by PID or PATH. -A -.B .insn.block -probe gets called for every block-stepped instruction of the process described by PID or PATH. -A -.B .mark -probe gets called via a static probe which is defined in the -application by -STAP_PROBE1(handle,LABEL,arg1), which is defined in sdt.h. The handle is an application handle, -LABEL corresponds to the .mark argument, and arg1 is the argument. -STAP_PROBE1 is used for probes with 1 argument, STAP_PROBE2 is used -for probes with 2 arguments, and so on. -The arguments of the probe are available in the context variables -$arg1, $arg2, ... An alternative to using the STAP_PROBE macros is to -use the dtrace script to create custom macros. -.PP -Note that -.I PATH -names refer to executables that are searched the same way shells do: relative -to the working directory if they contain a "/" character, otherwise in -.BR $PATH . -If a process probe is specified without a PID or PATH, all user -threads are probed. - -.SS PROCFS - -These probe points allow procfs "files" in -/proc/systemtap/MODNAME to be created, read and written -.RI ( MODNAME -is the name of the systemtap module). The -.I proc -filesystem is a pseudo-filesystem which is used an an interface to -kernel data structures. There are four probe point variants supported -by the translator: - -.SAMPLE -procfs("PATH").read -procfs("PATH").write -procfs.read -procfs.write -.ESAMPLE - -.I PATH -is the file name (relative to /proc/systemtap/MODNAME) to be created. -If no -.I PATH -is specified (as in the last two variants above), -.I PATH -defaults to "command". -.PP -When a user reads /proc/systemtap/MODNAME/PATH, the corresponding -procfs -.I read -probe is triggered. The string data to be read should be assigned to -a variable named -.IR $value , -like this: - -.SAMPLE -procfs("PATH").read { $value = "100\\n" } -.ESAMPLE -.PP -When a user writes into /proc/systemtap/MODNAME/PATH, the -corresponding procfs -.I write -probe is triggered. The data the user wrote is available in the -string variable named -.IR $value , -like this: - -.SAMPLE -procfs("PATH").write { printf("user wrote: %s", $value) } -.ESAMPLE - -.SS MARKERS - -This family of probe points hooks up to static probing markers -inserted into the kernel or modules. These markers are special macro -calls inserted by kernel developers to make probing faster and more -reliable than with DWARF-based probes. Further, DWARF debugging -information is -.I not -required to probe markers. - -Marker probe points begin with -.BR kernel . -The next part names the marker itself: -.BR mark("name") . -The marker name string, which may contain the usual wildcard characters, -is matched against the names given to the marker macros when the kernel -and/or module was compiled. Optionally, you can specify -.BR format("format") . -Specifying the marker format string allows differentation between two -markers with the same name but different marker format strings. - -The handler associated with a marker-based probe may read the -optional parameters specified at the macro call site. These are -named -.BR $arg1 " through " $argNN , -where NN is the number of parameters supplied by the macro. Number -and string parameters are passed in a type-safe manner. - -The marker format string associated with a marker is available in -.BR $format . -And also the marker name string is avalable in -.BR $name . - -.SS TRACEPOINTS - -This family of probe points hooks up to static probing tracepoints -inserted into the kernel or modules. As with markers, these -tracepoints are special macro calls inserted by kernel developers to -make probing faster and more reliable than with DWARF-based probes, -and DWARF debugging information is not required to probe tracepoints. -Tracepoints have an extra advantage of more strongly-typed parameters -than markers. - -Tracepoint probes begin with -.BR kernel . -The next part names the tracepoint itself: -.BR trace("name") . -The tracepoint name string, which may contain the usual wildcard -characters, is matched against the names defined by the kernel -developers in the tracepoint header files. - -The handler associated with a tracepoint-based probe may read the -optional parameters specified at the macro call site. These are -named according to the declaration by the tracepoint author. For -example, the tracepoint probe -.BR kernel.trace("sched_switch") -provides the parameters -.BR $rq ", " $prev ", and " $next . -If the parameter is a complex type, as in a struct pointer, then a -script can access fields with the same syntax as DWARF $target -variables. Also, tracepoint parameters cannot be modified, but in -guru-mode a script may modify fields of parameters. - -The name of the tracepoint is available in -.BR $$name , -and a string of name=value pairs for all parameters of the tracepoint -is available in -.BR $$vars " or " $$parms . - -.SS PERFORMANCE MONITORING HARDWARE - -The perfmon family of probe points is used to access the performance -monitoring hardware available in modern processors. This family of -probes points needs the perfmon2 support in the kernel to access the -performance monitoring hardware. -.PP -Performance monitor hardware points begin with a -.BR perfmon ". " -The next part of the names the event being counted -.BR counter("event") . -The event names are processor implementation specific with the -execption of the generic -.BR cycles " and " instructions -events, which are available on all processors. This sets up a counter -on the processor to count the number of events occuring on the -processor. For more details on the performance monitoring events -available on a specific processor use the command perfmon2 command: - -.SAMPLE -pfmon \-l -.ESAMPLE -.TP -$counter -is a handle used in the body of the probe for operations -involving the counter associated with the probe. -.TP -read_counter -is a function that is passed the handle for the perfmon probe and returns -the current count for the event. - -.SH EXAMPLES -.PP -Here are some example probe points, defining the associated events. -.TP -begin, end, end -refers to the startup and normal shutdown of the session. In this -case, the handler would run once during startup and twice during -shutdown. -.TP -timer.jiffies(1000).randomize(200) -refers to a periodic interrupt, every 1000 +/\- 200 jiffies. -.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 -kernel.mark("getuid") -refers to an STAP_MARK(getuid, ...) macro call in the kernel. -.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. -.TP -kernel.statement("*@kernel/sched.c:2917") -refers to the statement of line 2917 within "kernel/sched.c". -.TP -kernel.statement("bio_init@fs/bio.c+3") -refers to the statement at line bio_init+3 within "fs/bio.c". -.TP -syscall.*.return -refers to the group of probe aliases with any name in the third position - -.SH SEE ALSO -.IR stap (1), -.IR stapprobes.iosched (5), -.IR stapprobes.netdev (5), -.IR stapprobes.nfs (5), -.IR stapprobes.nfsd (5), -.IR stapprobes.pagefault (5), -.IR stapprobes.process (5), -.IR stapprobes.rpc (5), -.IR stapprobes.scsi (5), -.IR stapprobes.signal (5), -.IR stapprobes.socket (5), -.IR stapprobes.tcp (5), -.IR stapprobes.udp (5), -.IR proc (5) diff --git a/staprun.8.in b/staprun.8.in index 01ef2320..5d2a72a6 100644 --- a/staprun.8.in +++ b/staprun.8.in @@ -103,7 +103,7 @@ module. .SH EXAMPLES See the -.IR stapex (5) +.IR stapex (3stap) manual page for a collection of sample scripts. .PP Here is a very basic example of how to use @@ -167,9 +167,9 @@ located in this directory. This directory should be owned by the root user and not be world writable. .SH SEE ALSO .IR stap (1), -.IR stapprobes (5), -.IR stapfuncs (5), -.IR stapex (5), +.IR stapprobes (3stap), +.IR stapfuncs (3stap), +.IR stapex (3stap), .SH BUGS Use the Bugzilla link off of the project web page or our mailing list. diff --git a/stapvars.3stap.in b/stapvars.3stap.in new file mode 100644 index 00000000..0ece000f --- /dev/null +++ b/stapvars.3stap.in @@ -0,0 +1,51 @@ +.\" -*- nroff -*- +.TH STAPVARS 3stap @DATE@ "Red Hat" +.SH NAME +stapvars \- systemtap variables + +.SH DESCRIPTION +The following sections enumerate the public variables provided by +standard tapsets installed under @prefix@/share/systemtap/tapset. Each +variable is described with a type, and its behavior/restrictions. +The syntax is the same as printed with the +.IR stap " option " \-p2 . +Examples: + +.TP +example1:long +Variable "example1" contains an integer. + +.TP +example2:string [long] +Variable "example2" is an array of strings, indexed by integers. + +.SS ARGV + +.TP +argc:long +Contains the value of the +.BR +$# +value: the number of command line arguments passed to the systemtap script. +It is initialized with an implicit begin(-1) probe. + +.TP +argv:string [long] +Contains each command line argument as a string. argv[1] will equal @1 if +there was at least one command line argument. Arguments beyond #32 are not +transcribed, and produce a warning message within the begin(-1) probe that +initializes this array. + +.SS NULL + +.TP +NULL:long +Simply defined as the number 0. + +.SH FILES +.nh +.IR @prefix@/share/systemtap/tapset +.hy + +.SH SEE ALSO +.IR stap (1) diff --git a/stapvars.5.in b/stapvars.5.in deleted file mode 100644 index 94e47667..00000000 --- a/stapvars.5.in +++ /dev/null @@ -1,51 +0,0 @@ -.\" -*- nroff -*- -.TH STAPVARS 5 @DATE@ "Red Hat" -.SH NAME -stapvars \- systemtap variables - -.SH DESCRIPTION -The following sections enumerate the public variables provided by -standard tapsets installed under @prefix@/share/systemtap/tapset. Each -variable is described with a type, and its behavior/restrictions. -The syntax is the same as printed with the -.IR stap " option " \-p2 . -Examples: - -.TP -example1:long -Variable "example1" contains an integer. - -.TP -example2:string [long] -Variable "example2" is an array of strings, indexed by integers. - -.SS ARGV - -.TP -argc:long -Contains the value of the -.BR -$# -value: the number of command line arguments passed to the systemtap script. -It is initialized with an implicit begin(-1) probe. - -.TP -argv:string [long] -Contains each command line argument as a string. argv[1] will equal @1 if -there was at least one command line argument. Arguments beyond #32 are not -transcribed, and produce a warning message within the begin(-1) probe that -initializes this array. - -.SS NULL - -.TP -NULL:long -Simply defined as the number 0. - -.SH FILES -.nh -.IR @prefix@/share/systemtap/tapset -.hy - -.SH SEE ALSO -.IR stap (1) diff --git a/systemtap.spec b/systemtap.spec index cbf36662..020cd001 100644 --- a/systemtap.spec +++ b/systemtap.spec @@ -245,13 +245,12 @@ exit 0 %if %{with_docs} %doc docs.installed/*.pdf %doc docs.installed/tapsets -%{_mandir}/man3/* %endif %{_bindir}/stap %{_bindir}/stap-report %{_mandir}/man1/* -%{_mandir}/man5/* +%{_mandir}/man3/* %dir %{_datadir}/%{name} %{_datadir}/%{name}/runtime -- cgit From 64c6aab0a7992ed950d01fec0d9592630af39ca4 Mon Sep 17 00:00:00 2001 From: Stan Cox Date: Tue, 24 Mar 2009 12:40:05 -0400 Subject: Keep static probe parameters visible while inlining. * includes/sys/sdt.h (STAP_PROBEN): Revive the STAP_LABEL macro to prevent inlining to keep probe parameters visible. Use +rm constraints. * tapsets.cxx (build): Use .probes section for all uses of static probes. --- includes/sys/sdt.h | 217 ++++++++++++++++++++++++++++++----------------------- tapsets.cxx | 13 +--- 2 files changed, 126 insertions(+), 104 deletions(-) diff --git a/includes/sys/sdt.h b/includes/sys/sdt.h index 3da4ff66..ac24b6fb 100644 --- a/includes/sys/sdt.h +++ b/includes/sys/sdt.h @@ -13,180 +13,209 @@ #include #include -#define STAP_PROBE_DATA_(probe,dataop) \ +#define STAP_PROBE_DATA_(probe) \ __asm__ volatile (".section .probes\n" \ "\t.align 8\n" \ "1:\n\t.asciz " #probe "\n" \ "\t.align 4\n" \ "\t.int 0x31425250\n" \ "\t.align 8\n" \ - "\t" #dataop " 1b\n" \ + "\t.long 1b\n" \ "\t.align 8\n" \ - "\t" #dataop " 2f\n" \ + "\t.long 2f\n" \ "\t.previous\n") -#if _LP64 #define STAP_PROBE_DATA(probe) \ - STAP_PROBE_DATA_(#probe,.quad) + STAP_PROBE_DATA_(#probe) + +/* These baroque macros are used to create a unique label. */ +#define STAP_CONCAT(a,b) a ## b +#define STAP_LABEL_PREFIX(p) _stapprobe1_ ## p +/* __COUNTER__ is not present in gcc 4.1 */ +#if __GNUC__ == 4 && __GNUC_MINOR__ >= 3 +#define STAP_COUNTER STAP_CONCAT(__,COUNTER__) #else -#define STAP_PROBE_DATA(probe) \ - STAP_PROBE_DATA_(#probe,.long) +#define STAP_COUNTER STAP_CONCAT(__,LINE__) #endif +#define STAP_LABEL(a,b) STAP_CONCAT(a,b) -#define STAP_PROBE_(probe) \ +#define STAP_PROBE_(probe) \ do { \ STAP_PROBE_DATA(probe); \ - __asm__ volatile ("2:\n" \ + __asm__ volatile ("2:\n" \ "\tnop"); \ } while (0) -#define STAP_PROBE1_(probe,parm1) \ +/* Taking the address of a local label prevents the containing function + from being inlined, which keeps the parameters visible. */ + +#define STAP_PROBE1_(probe,label,parm1) \ do { \ - volatile __typeof__((parm1)) arg1 __attribute__ ((unused)) = parm1; \ + __extension__ static volatile long labelval __attribute__ ((unused)) = (long) &&label; \ + volatile __typeof__((parm1)) arg1 = parm1; \ STAP_PROBE_DATA(probe); \ + label: \ __asm__ volatile ("2:\n" \ - "\tnop /* %0 */" :: "X"(arg1)); \ + "\tnop /* %0 */" : "+rm"(arg1)); \ } while (0) -#define STAP_PROBE2_(probe,parm1,parm2) \ +#define STAP_PROBE2_(probe,label,parm1,parm2) \ do { \ - volatile __typeof__((parm1)) arg1 __attribute__ ((unused)) = parm1; \ - volatile __typeof__((parm2)) arg2 __attribute__ ((unused)) = parm2; \ + __extension__ static volatile long labelval __attribute__ ((unused)) = (long) &&label; \ + volatile __typeof__((parm1)) arg1 = parm1; \ + volatile __typeof__((parm2)) arg2 = parm2; \ STAP_PROBE_DATA(probe); \ + label: \ __asm__ volatile ("2:\n" \ - "\tnop /* %0 %1 */" :: "X"(arg1), "X"(arg2)); \ + "\tnop /* %0 %1 */" : "+rm"(arg1), "+rm"(arg2)); \ } while (0) -#define STAP_PROBE3_(probe,parm1,parm2,parm3) \ +#define STAP_PROBE3_(probe,label,parm1,parm2,parm3) \ do { \ - volatile __typeof__((parm1)) arg1 __attribute__ ((unused)) = parm1; \ - volatile __typeof__((parm2)) arg2 __attribute__ ((unused)) = parm2; \ - volatile __typeof__((parm3)) arg3 __attribute__ ((unused)) = parm3; \ + __extension__ static volatile long labelval __attribute__ ((unused)) = (long) &&label; \ + volatile __typeof__((parm1)) arg1 = parm1; \ + volatile __typeof__((parm2)) arg2 = parm2; \ + volatile __typeof__((parm3)) arg3 = parm3; \ STAP_PROBE_DATA(probe); \ + label: \ __asm__ volatile ("2:\n" \ - "\tnop /* %0 %1 %2 */" :: "X"(arg1), "X"(arg2), "X"(arg3)); \ + "\tnop /* %0 %1 %2 */" : "+rm"(arg1), "+rm"(arg2), "+rm"(arg3)); \ } while (0) -#define STAP_PROBE4_(probe,parm1,parm2,parm3,parm4) \ +#define STAP_PROBE4_(probe,label,parm1,parm2,parm3,parm4) \ do { \ - volatile __typeof__((parm1)) arg1 __attribute__ ((unused)) = parm1; \ - volatile __typeof__((parm2)) arg2 __attribute__ ((unused)) = parm2; \ - volatile __typeof__((parm3)) arg3 __attribute__ ((unused)) = parm3; \ - volatile __typeof__((parm4)) arg4 __attribute__ ((unused)) = parm4; \ + __extension__ static volatile long labelval __attribute__ ((unused)) = (long) &&label; \ + volatile __typeof__((parm1)) arg1 = parm1; \ + volatile __typeof__((parm2)) arg2 = parm2; \ + volatile __typeof__((parm3)) arg3 = parm3; \ + volatile __typeof__((parm4)) arg4 = parm4; \ STAP_PROBE_DATA(probe); \ + label: \ __asm__ volatile ("2:\n" \ - "\tnop /* %0 %1 %2 %3 */" :: "X"(arg1), "X"(arg2), "X"(arg3), "X"(arg4)); \ + "\tnop /* %0 %1 %2 %3 */" : "+rm"(arg1), "+rm"(arg2), "+rm"(arg3), "+rm"(arg4)); \ } while (0) -#define STAP_PROBE5_(probe,parm1,parm2,parm3,parm4,parm5) \ +#define STAP_PROBE5_(probe,label,parm1,parm2,parm3,parm4,parm5) \ do { \ - volatile __typeof__((parm1)) arg1 __attribute__ ((unused)) = parm1; \ - volatile __typeof__((parm2)) arg2 __attribute__ ((unused)) = parm2; \ - volatile __typeof__((parm3)) arg3 __attribute__ ((unused)) = parm3; \ - volatile __typeof__((parm4)) arg4 __attribute__ ((unused)) = parm4; \ - volatile __typeof__((parm5)) arg5 __attribute__ ((unused)) = parm5; \ + __extension__ static volatile long labelval __attribute__ ((unused)) = (long) &&label; \ + volatile __typeof__((parm1)) arg1 = parm1; \ + volatile __typeof__((parm2)) arg2 = parm2; \ + volatile __typeof__((parm3)) arg3 = parm3; \ + volatile __typeof__((parm4)) arg4 = parm4; \ + volatile __typeof__((parm5)) arg5 = parm5; \ STAP_PROBE_DATA(probe); \ + label: \ __asm__ volatile ("2:\n" \ - "\tnop /* %0 %1 %2 %3 %4 */" :: "X"(arg1), "X"(arg2), "X"(arg3), "X"(arg4), "X"(arg5)); \ + "\tnop /* %0 %1 %2 %3 %4 */" : "+rm"(arg1), "+rm"(arg2), "+rm"(arg3), "+rm"(arg4), "+rm"(arg5)); \ } while (0) -#define STAP_PROBE6_(probe,parm1,parm2,parm3,parm4,parm5,parm6) \ +#define STAP_PROBE6_(probe,label,parm1,parm2,parm3,parm4,parm5,parm6) \ do { \ - volatile __typeof__((parm1)) arg1 __attribute__ ((unused)) = parm1; \ - volatile __typeof__((parm2)) arg2 __attribute__ ((unused)) = parm2; \ - volatile __typeof__((parm3)) arg3 __attribute__ ((unused)) = parm3; \ - volatile __typeof__((parm4)) arg4 __attribute__ ((unused)) = parm4; \ - volatile __typeof__((parm5)) arg5 __attribute__ ((unused)) = parm5; \ - volatile __typeof__((parm6)) arg6 __attribute__ ((unused)) = parm6; \ + __extension__ static volatile long labelval __attribute__ ((unused)) = (long) &&label; \ + volatile __typeof__((parm1)) arg1 = parm1; \ + volatile __typeof__((parm2)) arg2 = parm2; \ + volatile __typeof__((parm3)) arg3 = parm3; \ + volatile __typeof__((parm4)) arg4 = parm4; \ + volatile __typeof__((parm5)) arg5 = parm5; \ + volatile __typeof__((parm6)) arg6 = parm6; \ STAP_PROBE_DATA(probe); \ + label: \ __asm__ volatile ("2:\n" \ - "\tnop /* %0 %1 %2 %3 %4 %5 */" :: "X"(arg1), "X"(arg2), "X"(arg3), "X"(arg4), "X"(arg5), "X"(arg6)); \ + "\tnop /* %0 %1 %2 %3 %4 %5 */" : "+rm"(arg1), "+rm"(arg2), "+rm"(arg3), "+rm"(arg4), "+rm"(arg5), "+rm"(arg6)); \ } while (0) -#define STAP_PROBE7_(probe,parm1,parm2,parm3,parm4,parm5,parm6,parm7) \ +#define STAP_PROBE7_(probe,label,parm1,parm2,parm3,parm4,parm5,parm6,parm7) \ do { \ - volatile __typeof__((parm1)) arg1 __attribute__ ((unused)) = parm1; \ - volatile __typeof__((parm2)) arg2 __attribute__ ((unused)) = parm2; \ - volatile __typeof__((parm3)) arg3 __attribute__ ((unused)) = parm3; \ - volatile __typeof__((parm4)) arg4 __attribute__ ((unused)) = parm4; \ - volatile __typeof__((parm5)) arg5 __attribute__ ((unused)) = parm5; \ - volatile __typeof__((parm6)) arg6 __attribute__ ((unused)) = parm6; \ - volatile __typeof__((parm7)) arg7 __attribute__ ((unused)) = parm7; \ + __extension__ static volatile long labelval __attribute__ ((unused)) = (long) &&label; \ + volatile __typeof__((parm1)) arg1 = parm1; \ + volatile __typeof__((parm2)) arg2 = parm2; \ + volatile __typeof__((parm3)) arg3 = parm3; \ + volatile __typeof__((parm4)) arg4 = parm4; \ + volatile __typeof__((parm5)) arg5 = parm5; \ + volatile __typeof__((parm6)) arg6 = parm6; \ + volatile __typeof__((parm7)) arg7 = parm7; \ STAP_PROBE_DATA(probe); \ + label: \ __asm__ volatile ("2:\n" \ - "\tnop /* %0 %1 %2 %3 %4 %5 %6 */" :: "X"(arg1), "X"(arg2), "X"(arg3), "X"(arg4), "X"(arg5), "X"(arg6), "X"(arg7)); \ + "\tnop /* %0 %1 %2 %3 %4 %5 %6 */" : "+rm"(arg1), "+rm"(arg2), "+rm"(arg3), "+rm"(arg4), "+rm"(arg5), "+rm"(arg6), "+rm"(arg7)); \ } while (0) -#define STAP_PROBE8_(probe,parm1,parm2,parm3,parm4,parm5,parm6,parm7,parm8) \ +#define STAP_PROBE8_(probe,label,parm1,parm2,parm3,parm4,parm5,parm6,parm7,parm8) \ do { \ - volatile __typeof__((parm1)) arg1 __attribute__ ((unused)) = parm1; \ - volatile __typeof__((parm2)) arg2 __attribute__ ((unused)) = parm2; \ - volatile __typeof__((parm3)) arg3 __attribute__ ((unused)) = parm3; \ - volatile __typeof__((parm4)) arg4 __attribute__ ((unused)) = parm4; \ - volatile __typeof__((parm5)) arg5 __attribute__ ((unused)) = parm5; \ - volatile __typeof__((parm6)) arg6 __attribute__ ((unused)) = parm6; \ - volatile __typeof__((parm7)) arg7 __attribute__ ((unused)) = parm7; \ - volatile __typeof__((parm8)) arg8 __attribute__ ((unused)) = parm8; \ + __extension__ static volatile long labelval __attribute__ ((unused)) = (long) &&label; \ + volatile __typeof__((parm1)) arg1 = parm1; \ + volatile __typeof__((parm2)) arg2 = parm2; \ + volatile __typeof__((parm3)) arg3 = parm3; \ + volatile __typeof__((parm4)) arg4 = parm4; \ + volatile __typeof__((parm5)) arg5 = parm5; \ + volatile __typeof__((parm6)) arg6 = parm6; \ + volatile __typeof__((parm7)) arg7 = parm7; \ + volatile __typeof__((parm8)) arg8 = parm8; \ STAP_PROBE_DATA(probe); \ + label: \ __asm__ volatile ("2:\n" \ - "\tnop /* %0 %1 %2 %3 %4 %5 %6 %7 */" :: "X"(arg1), "X"(arg2), "X"(arg3), "X"(arg4), "X"(arg5), "X"(arg6), "X"(arg7), "X"(arg8)); \ + "\tnop /* %0 %1 %2 %3 %4 %5 %6 %7 */" : "+rm"(arg1), "+rm"(arg2), "+rm"(arg3), "+rm"(arg4), "+rm"(arg5), "+rm"(arg6), "+rm"(arg7), "+rm"(arg8)); \ } while (0) -#define STAP_PROBE9_(probe,parm1,parm2,parm3,parm4,parm5,parm6,parm7,parm8,parm9) \ +#define STAP_PROBE9_(probe,label,parm1,parm2,parm3,parm4,parm5,parm6,parm7,parm8,parm9) \ do { \ - volatile __typeof__((parm1)) arg1 __attribute__ ((unused)) = parm1; \ - volatile __typeof__((parm2)) arg2 __attribute__ ((unused)) = parm2; \ - volatile __typeof__((parm3)) arg3 __attribute__ ((unused)) = parm3; \ - volatile __typeof__((parm4)) arg4 __attribute__ ((unused)) = parm4; \ - volatile __typeof__((parm5)) arg5 __attribute__ ((unused)) = parm5; \ - volatile __typeof__((parm6)) arg6 __attribute__ ((unused)) = parm6; \ - volatile __typeof__((parm7)) arg7 __attribute__ ((unused)) = parm7; \ - volatile __typeof__((parm8)) arg8 __attribute__ ((unused)) = parm8; \ - volatile __typeof__((parm9)) arg9 __attribute__ ((unused)) = parm9; \ + __extension__ static volatile long labelval __attribute__ ((unused)) = (long) &&label; \ + volatile __typeof__((parm1)) arg1 = parm1; \ + volatile __typeof__((parm2)) arg2 = parm2; \ + volatile __typeof__((parm3)) arg3 = parm3; \ + volatile __typeof__((parm4)) arg4 = parm4; \ + volatile __typeof__((parm5)) arg5 = parm5; \ + volatile __typeof__((parm6)) arg6 = parm6; \ + volatile __typeof__((parm7)) arg7 = parm7; \ + volatile __typeof__((parm8)) arg8 = parm8; \ + volatile __typeof__((parm9)) arg9 = parm9; \ STAP_PROBE_DATA(probe); \ + label: \ __asm__ volatile ("2:\n" \ - "\tnop /* %0 %1 %2 %3 %4 %5 %6 %7 %8 */" :: "X"(arg1), "X"(arg2), "X"(arg3), "X"(arg4), "X"(arg5), "X"(arg6), "X"(arg7), "X"(arg8), "X"(arg9)); \ + "\tnop /* %0 %1 %2 %3 %4 %5 %6 %7 %8 */" : "+rm"(arg1), "+rm"(arg2), "+rm"(arg3), "+rm"(arg4), "+rm"(arg5), "+rm"(arg6), "+rm"(arg7), "+rm"(arg8), "+rm"(arg9)); \ } while (0) -#define STAP_PROBE10_(probe,parm1,parm2,parm3,parm4,parm5,parm6,parm7,parm8,parm9,parm10) \ +#define STAP_PROBE10_(probe,label,parm1,parm2,parm3,parm4,parm5,parm6,parm7,parm8,parm9,parm10) \ do { \ - volatile __typeof__((parm1)) arg1 __attribute__ ((unused)) = parm1; \ - volatile __typeof__((parm2)) arg2 __attribute__ ((unused)) = parm2; \ - volatile __typeof__((parm3)) arg3 __attribute__ ((unused)) = parm3; \ - volatile __typeof__((parm4)) arg4 __attribute__ ((unused)) = parm4; \ - volatile __typeof__((parm5)) arg5 __attribute__ ((unused)) = parm5; \ - volatile __typeof__((parm6)) arg6 __attribute__ ((unused)) = parm6; \ - volatile __typeof__((parm7)) arg7 __attribute__ ((unused)) = parm7; \ - volatile __typeof__((parm8)) arg8 __attribute__ ((unused)) = parm8; \ - volatile __typeof__((parm9)) arg9 __attribute__ ((unused)) = parm9; \ - volatile __typeof__((parm10)) arg10 __attribute__ ((unused)) = parm10; \ + __extension__ static volatile long labelval __attribute__ ((unused)) = (long) &&label; \ + volatile __typeof__((parm1)) arg1 = parm1; \ + volatile __typeof__((parm2)) arg2 = parm2; \ + volatile __typeof__((parm3)) arg3 = parm3; \ + volatile __typeof__((parm4)) arg4 = parm4; \ + volatile __typeof__((parm5)) arg5 = parm5; \ + volatile __typeof__((parm6)) arg6 = parm6; \ + volatile __typeof__((parm7)) arg7 = parm7; \ + volatile __typeof__((parm8)) arg8 = parm8; \ + volatile __typeof__((parm9)) arg9 = parm9; \ + volatile __typeof__((parm10)) arg10 = parm10; \ STAP_PROBE_DATA(probe); \ + label: \ __asm__ volatile ("2:\n" \ - "\tnop /* %0 %1 %2 %3 %4 %5 %6 %7 %8 %9 */" :: "X"(arg1), "X"(arg2), "X"(arg3), "X"(arg4), "X"(arg5), "X"(arg6), "X"(arg7), "X"(arg8), "X"(arg9), "X"(arg10)); \ + "\tnop /* %0 %1 %2 %3 %4 %5 %6 %7 %8 %9 */" : "+rm"(arg1), "+rm"(arg2), "+rm"(arg3), "+rm"(arg4), "+rm"(arg5), "+rm"(arg6), "+rm"(arg7), "+rm"(arg8), "+rm"(arg9), "+rm"(arg10)); \ } while (0) #define STAP_PROBE(provider,probe) \ STAP_PROBE_(probe) #define STAP_PROBE1(provider,probe,parm1) \ - STAP_PROBE1_(probe,(parm1)) + STAP_PROBE1_(probe,STAP_LABEL(STAP_LABEL_PREFIX(probe),STAP_COUNTER),(parm1)) #define STAP_PROBE2(provider,probe,parm1,parm2) \ - STAP_PROBE2_(probe,(parm1),(parm2)) + STAP_PROBE2_(probe,STAP_LABEL(STAP_LABEL_PREFIX(probe),STAP_COUNTER),(parm1),(parm2)) #define STAP_PROBE3(provider,probe,parm1,parm2,parm3) \ - STAP_PROBE3_(probe,(parm1),(parm2),(parm3)) + STAP_PROBE3_(probe,STAP_LABEL(STAP_LABEL_PREFIX(probe),STAP_COUNTER),(parm1),(parm2),(parm3)) #define STAP_PROBE4(provider,probe,parm1,parm2,parm3,parm4) \ - STAP_PROBE4_(probe,(parm1),(parm2),(parm3),(parm4)) + STAP_PROBE4_(probe,STAP_LABEL(STAP_LABEL_PREFIX(probe),STAP_COUNTER),(parm1),(parm2),(parm3),(parm4)) #define STAP_PROBE5(provider,probe,parm1,parm2,parm3,parm4,parm5) \ - STAP_PROBE5_(probe,(parm1),(parm2),(parm3),(parm4),(parm5)) + STAP_PROBE5_(probe,STAP_LABEL(STAP_LABEL_PREFIX(probe),STAP_COUNTER),(parm1),(parm2),(parm3),(parm4),(parm5)) #define STAP_PROBE6(provider,probe,parm1,parm2,parm3,parm4,parm5,parm6) \ - STAP_PROBE6_(probe,(parm1),(parm2),(parm3),(parm4),(parm5),(parm6)) + STAP_PROBE6_(probe,STAP_LABEL(STAP_LABEL_PREFIX(probe),STAP_COUNTER),(parm1),(parm2),(parm3),(parm4),(parm5),(parm6)) #define STAP_PROBE7(provider,probe,parm1,parm2,parm3,parm4,parm5,parm6,parm7) \ - STAP_PROBE7_(probe,(parm1),(parm2),(parm3),(parm4),(parm5),(parm6),(parm7)) + STAP_PROBE7_(probe,STAP_LABEL(STAP_LABEL_PREFIX(probe),STAP_COUNTER),(parm1),(parm2),(parm3),(parm4),(parm5),(parm6),(parm7)) #define STAP_PROBE8(provider,probe,parm1,parm2,parm3,parm4,parm5,parm6,parm7,parm8) \ - STAP_PROBE8_(probe,(parm1),(parm2),(parm3),(parm4),(parm5),(parm6),(parm7),(parm8)) + STAP_PROBE8_(probe,STAP_LABEL(STAP_LABEL_PREFIX(probe),STAP_COUNTER),(parm1),(parm2),(parm3),(parm4),(parm5),(parm6),(parm7),(parm8)) #define STAP_PROBE9(provider,probe,parm1,parm2,parm3,parm4,parm5,parm6,parm7,parm8,parm9) \ - STAP_PROBE9_(probe,(parm1),(parm2),(parm3),(parm4),(parm5),(parm6),(parm7),(parm8),(parm9)) + STAP_PROBE9_(probe,STAP_LABEL(STAP_LABEL_PREFIX(probe),STAP_COUNTER),(parm1),(parm2),(parm3),(parm4),(parm5),(parm6),(parm7),(parm8),(parm9)) #define STAP_PROBE10(provider,probe,parm1,parm2,parm3,parm4,parm5,parm6,parm7,parm8,parm9,parm10) \ - STAP_PROBE10_(probe,(parm1),(parm2),(parm3),(parm4),(parm5),(parm6),(parm7),(parm8),(parm9),(parm10)) + STAP_PROBE10_(probe,STAP_LABEL(STAP_LABEL_PREFIX(probe),STAP_COUNTER),(parm1),(parm2),(parm3),(parm4),(parm5),(parm6),(parm7),(parm8),(parm9),(parm10)) #define DTRACE_PROBE(provider,probe) \ STAP_PROBE(provider,probe) diff --git a/tapsets.cxx b/tapsets.cxx index e9ade595..bc16d6fa 100644 --- a/tapsets.cxx +++ b/tapsets.cxx @@ -5731,8 +5731,6 @@ dwarf_builder::build(systemtap_session & sess, Elf* elf = dwfl_module_getelf (dw->module, &bias); size_t shstrndx; Elf_Scn *probe_scn = NULL; - bool probe_found = false; - bool dynamic = (dwfl_module_relocations (dw->module) == 1); dwfl_assert ("getshstrndx", elf_getshstrndx (elf, &shstrndx)); GElf_Shdr *shdr = NULL; @@ -5750,8 +5748,6 @@ dwarf_builder::build(systemtap_session & sess, break; } } - if (dynamic || sess.listing_mode) - probe_type = dwarf_no_probes; if (probe_type == probes_and_dwarf) { @@ -5779,9 +5775,7 @@ dwarf_builder::build(systemtap_session & sess, probe_arg = *((__uint64_t*)((char*)pdata->d_buf + probe_scn_offset)); if (probe_scn_offset % (sizeof(__uint64_t)*2)) probe_scn_offset = (probe_scn_offset + sizeof(__uint64_t)*2) - (probe_scn_offset % (sizeof(__uint64_t)*2)); - if (strcmp (location->components[1]->arg->tok->content.c_str(), probe_name.c_str()) == 0) - probe_found = true; - else + if (strcmp (location->components[1]->arg->tok->content.c_str(), probe_name.c_str()) != 0) continue; const token* sv_tok = location->components[1]->arg->tok; location->components[1]->functor = TOK_STATEMENT; @@ -5791,11 +5785,10 @@ dwarf_builder::build(systemtap_session & sess, dwarf_query q(sess, base, location, *dw, parameters, finished_results); dw->query_modules(&q); } - if (probe_found) - return; + return; } - if (probe_type == dwarf_no_probes || ! probe_found) + if (probe_type == dwarf_no_probes) { location->components[1]->functor = TOK_FUNCTION; location->components[1]->arg = new literal_string("*"); -- cgit From 3c1b3d06ef3134b30e804d189d346c5f83c6f3a6 Mon Sep 17 00:00:00 2001 From: "Frank Ch. Eigler" Date: Tue, 24 Mar 2009 12:53:17 -0400 Subject: PR9993: tracepoint toleration for undeclared types in trace/*.h headers * tapsets.cxx (tracepoint_extra_headers): New function to return needed header file names. (emit_module_decls): Emit them. * buildrun.cxx (make_tracequery): Emit them. * testsuite/systemtap.base/tracepoints.exp: Rewrite to exercise building each tracepoint. --- buildrun.cxx | 7 ++++++- buildrun.h | 2 +- tapsets.cxx | 20 +++++++++++++++++++- testsuite/systemtap.base/tracepoints.exp | 23 +++++++++++++++++++++++ 4 files changed, 49 insertions(+), 3 deletions(-) diff --git a/buildrun.cxx b/buildrun.cxx index 6a266bd2..e19043cf 100644 --- a/buildrun.cxx +++ b/buildrun.cxx @@ -345,7 +345,7 @@ run_pass (systemtap_session& s) // Build a tiny kernel module to query tracepoints int -make_tracequery(systemtap_session& s, string& name) +make_tracequery(systemtap_session& s, string& name, const vector& extra_headers) { // create a subdirectory for the module string dir(s.tmpdir + "/tracequery"); @@ -382,6 +382,11 @@ make_tracequery(systemtap_session& s, string& name) osrc << "#define DEFINE_TRACE(name, proto, args) \\" << endl; osrc << " DECLARE_TRACE(name, TPPROTO(proto), TPARGS(args))" << endl; + // PR9993: Add extra headers to work around undeclared types in individual + // include/trace/foo.h files + for (unsigned z=0; z\n"; + // dynamically pull in all tracepoint headers from include/trace/ glob_t trace_glob; string globs[2] = { "/include/trace/*.h", "/source/include/trace/*.h" }; diff --git a/buildrun.h b/buildrun.h index 88127449..e87b7b85 100644 --- a/buildrun.h +++ b/buildrun.h @@ -14,7 +14,7 @@ int compile_pass (systemtap_session& s); int run_pass (systemtap_session& s); -int make_tracequery(systemtap_session& s, std::string& name); +int make_tracequery(systemtap_session& s, std::string& name, const std::vector& extra_headers); #endif // BUILDRUN_H diff --git a/tapsets.cxx b/tapsets.cxx index bc16d6fa..3a181cb3 100644 --- a/tapsets.cxx +++ b/tapsets.cxx @@ -9582,6 +9582,7 @@ tracepoint_derived_probe::tracepoint_derived_probe (systemtap_session& s, // tracepoints from FOO_event_types.h should really be included from FOO.h // XXX can dwarf tell us the include hierarchy? it would be better to // ... walk up to see which one was directly included by tracequery.c + // XXX: see also PR9993. header_pos = header.find("_event_types"); if (header_pos != string::npos) header.erase(header_pos, 12); @@ -9757,6 +9758,16 @@ tracepoint_derived_probe::emit_probe_context_vars (translator_output* o) } +static vector tracepoint_extra_headers () +{ + vector they_live; + // PR 9993 + // XXX: may need this to be configurable + they_live.push_back ("linux/skbuff.h"); + return they_live; +} + + void tracepoint_derived_probe_group::emit_module_decls (systemtap_session& s) { @@ -9766,6 +9777,12 @@ tracepoint_derived_probe_group::emit_module_decls (systemtap_session& s) s.op->newline() << "/* ---- tracepoint probes ---- */"; s.op->newline(); + // PR9993: Add extra headers to work around undeclared types in individual + // include/trace/foo.h files + const vector& extra_headers = tracepoint_extra_headers (); + for (unsigned z=0; znewline() << "#include <" << extra_headers[z] << ">\n"; + for (unsigned i = 0; i < probes.size(); ++i) { tracepoint_derived_probe *p = probes[i]; @@ -9963,6 +9980,7 @@ private: bool init_dw(systemtap_session& s); public: + tracepoint_builder(): dw(0) {} ~tracepoint_builder() { delete dw; } @@ -10009,7 +10027,7 @@ tracepoint_builder::init_dw(systemtap_session& s) // no cached module, time to make it string tracequery_ko; - int rc = make_tracequery(s, tracequery_ko); + int rc = make_tracequery(s, tracequery_ko, tracepoint_extra_headers()); if (rc != 0) return false; diff --git a/testsuite/systemtap.base/tracepoints.exp b/testsuite/systemtap.base/tracepoints.exp index bea461c4..cd033908 100644 --- a/testsuite/systemtap.base/tracepoints.exp +++ b/testsuite/systemtap.base/tracepoints.exp @@ -1,3 +1,26 @@ + +set tracepoints {} +spawn stap -l {kernel.trace("*")} +expect { + -re {^kernel.trace[^\r\n]*\r\n} { + append tracepoints $expect_out(0,string) + exp_continue + } + timeout {} + eof {} +} +catch {close}; catch { wait } + +foreach tp $tracepoints { + set test "tracepoint $tp -p4" + if {[catch {exec stap -w -p4 -e "probe $tp {}"} res]} { + fail "$test $res" + } else { + pass "$test" + } +} + set test "tracepoints" +if {![installtest_p]} { untested $test; return } set ::result_string {tracepoints OK} stap_run2 $srcdir/$subdir/$test.stp -- cgit From 7d6c591292084444ada2ecdecafe59c730865451 Mon Sep 17 00:00:00 2001 From: William Cohen Date: Tue, 24 Mar 2009 13:03:54 -0400 Subject: Strip off "probe" for the probe documentation generation. --- scripts/kernel-doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 92178910..7f2db03f 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2083,7 +2083,7 @@ sub process_state3_probe($$) { my $prototype = shift; my $file = shift; - $prototype =~ s@/probe/@@o; # strip off leading 'probe' + $prototype =~ s@probe@@o; # strip off leading 'probe' $prototype =~ s@^\s+@@gos; # strip leading spaces dump_probe($prototype,$file); reset_state(); -- cgit From 8e9d6257b102f40567b387fe45ab3d1474022f53 Mon Sep 17 00:00:00 2001 From: William Cohen Date: Tue, 24 Mar 2009 13:14:12 -0400 Subject: Add NEWS entry for the manpages. --- NEWS | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/NEWS b/NEWS index 7ae93675..74dde8b7 100644 --- a/NEWS +++ b/NEWS @@ -1,5 +1,9 @@ * What's new +- Systemtap probes and function man pages extracted from the tapsets + are now available. To look at man page for systemtap vm.pagefault: + $ man 3stap vm.pagefault + - Kernel tracepoints are now supported for probing predefined kernel events without any debuginfo. Tracepoints incur less overhead than kprobes, and context parameters are available with full type -- cgit From 8f7c6d4680717700fe8beb8cc6d59c241e6677ed Mon Sep 17 00:00:00 2001 From: Stan Cox Date: Tue, 24 Mar 2009 14:06:36 -0400 Subject: Use read operand "g" constraints. * includes/sdt.h (STAP_PROBEN): Use R "g" instead of RW "+rm" which can result in "read-only variable arg1 used as asm output" --- includes/sys/sdt.h | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/includes/sys/sdt.h b/includes/sys/sdt.h index ac24b6fb..ba75076b 100644 --- a/includes/sys/sdt.h +++ b/includes/sys/sdt.h @@ -56,7 +56,7 @@ do { \ STAP_PROBE_DATA(probe); \ label: \ __asm__ volatile ("2:\n" \ - "\tnop /* %0 */" : "+rm"(arg1)); \ + "\tnop /* %0 */" :: "g"(arg1)); \ } while (0) #define STAP_PROBE2_(probe,label,parm1,parm2) \ @@ -67,7 +67,7 @@ do { \ STAP_PROBE_DATA(probe); \ label: \ __asm__ volatile ("2:\n" \ - "\tnop /* %0 %1 */" : "+rm"(arg1), "+rm"(arg2)); \ + "\tnop /* %0 %1 */" :: "g"(arg1), "g"(arg2)); \ } while (0) #define STAP_PROBE3_(probe,label,parm1,parm2,parm3) \ @@ -79,7 +79,7 @@ do { \ STAP_PROBE_DATA(probe); \ label: \ __asm__ volatile ("2:\n" \ - "\tnop /* %0 %1 %2 */" : "+rm"(arg1), "+rm"(arg2), "+rm"(arg3)); \ + "\tnop /* %0 %1 %2 */" :: "g"(arg1), "g"(arg2), "g"(arg3)); \ } while (0) #define STAP_PROBE4_(probe,label,parm1,parm2,parm3,parm4) \ @@ -92,7 +92,7 @@ do { \ STAP_PROBE_DATA(probe); \ label: \ __asm__ volatile ("2:\n" \ - "\tnop /* %0 %1 %2 %3 */" : "+rm"(arg1), "+rm"(arg2), "+rm"(arg3), "+rm"(arg4)); \ + "\tnop /* %0 %1 %2 %3 */" :: "g"(arg1), "g"(arg2), "g"(arg3), "g"(arg4)); \ } while (0) #define STAP_PROBE5_(probe,label,parm1,parm2,parm3,parm4,parm5) \ @@ -106,7 +106,7 @@ do { \ STAP_PROBE_DATA(probe); \ label: \ __asm__ volatile ("2:\n" \ - "\tnop /* %0 %1 %2 %3 %4 */" : "+rm"(arg1), "+rm"(arg2), "+rm"(arg3), "+rm"(arg4), "+rm"(arg5)); \ + "\tnop /* %0 %1 %2 %3 %4 */" :: "g"(arg1), "g"(arg2), "g"(arg3), "g"(arg4), "g"(arg5)); \ } while (0) #define STAP_PROBE6_(probe,label,parm1,parm2,parm3,parm4,parm5,parm6) \ @@ -121,7 +121,7 @@ do { \ STAP_PROBE_DATA(probe); \ label: \ __asm__ volatile ("2:\n" \ - "\tnop /* %0 %1 %2 %3 %4 %5 */" : "+rm"(arg1), "+rm"(arg2), "+rm"(arg3), "+rm"(arg4), "+rm"(arg5), "+rm"(arg6)); \ + "\tnop /* %0 %1 %2 %3 %4 %5 */" :: "g"(arg1), "g"(arg2), "g"(arg3), "g"(arg4), "g"(arg5), "g"(arg6)); \ } while (0) #define STAP_PROBE7_(probe,label,parm1,parm2,parm3,parm4,parm5,parm6,parm7) \ @@ -137,7 +137,7 @@ do { \ STAP_PROBE_DATA(probe); \ label: \ __asm__ volatile ("2:\n" \ - "\tnop /* %0 %1 %2 %3 %4 %5 %6 */" : "+rm"(arg1), "+rm"(arg2), "+rm"(arg3), "+rm"(arg4), "+rm"(arg5), "+rm"(arg6), "+rm"(arg7)); \ + "\tnop /* %0 %1 %2 %3 %4 %5 %6 */" :: "g"(arg1), "g"(arg2), "g"(arg3), "g"(arg4), "g"(arg5), "g"(arg6), "g"(arg7)); \ } while (0) #define STAP_PROBE8_(probe,label,parm1,parm2,parm3,parm4,parm5,parm6,parm7,parm8) \ @@ -154,7 +154,7 @@ do { \ STAP_PROBE_DATA(probe); \ label: \ __asm__ volatile ("2:\n" \ - "\tnop /* %0 %1 %2 %3 %4 %5 %6 %7 */" : "+rm"(arg1), "+rm"(arg2), "+rm"(arg3), "+rm"(arg4), "+rm"(arg5), "+rm"(arg6), "+rm"(arg7), "+rm"(arg8)); \ + "\tnop /* %0 %1 %2 %3 %4 %5 %6 %7 */" :: "g"(arg1), "g"(arg2), "g"(arg3), "g"(arg4), "g"(arg5), "g"(arg6), "g"(arg7), "g"(arg8)); \ } while (0) #define STAP_PROBE9_(probe,label,parm1,parm2,parm3,parm4,parm5,parm6,parm7,parm8,parm9) \ @@ -172,7 +172,7 @@ do { \ STAP_PROBE_DATA(probe); \ label: \ __asm__ volatile ("2:\n" \ - "\tnop /* %0 %1 %2 %3 %4 %5 %6 %7 %8 */" : "+rm"(arg1), "+rm"(arg2), "+rm"(arg3), "+rm"(arg4), "+rm"(arg5), "+rm"(arg6), "+rm"(arg7), "+rm"(arg8), "+rm"(arg9)); \ + "\tnop /* %0 %1 %2 %3 %4 %5 %6 %7 %8 */" :: "g"(arg1), "g"(arg2), "g"(arg3), "g"(arg4), "g"(arg5), "g"(arg6), "g"(arg7), "g"(arg8), "g"(arg9)); \ } while (0) #define STAP_PROBE10_(probe,label,parm1,parm2,parm3,parm4,parm5,parm6,parm7,parm8,parm9,parm10) \ @@ -191,7 +191,7 @@ do { \ STAP_PROBE_DATA(probe); \ label: \ __asm__ volatile ("2:\n" \ - "\tnop /* %0 %1 %2 %3 %4 %5 %6 %7 %8 %9 */" : "+rm"(arg1), "+rm"(arg2), "+rm"(arg3), "+rm"(arg4), "+rm"(arg5), "+rm"(arg6), "+rm"(arg7), "+rm"(arg8), "+rm"(arg9), "+rm"(arg10)); \ + "\tnop /* %0 %1 %2 %3 %4 %5 %6 %7 %8 %9 */" :: "g"(arg1), "g"(arg2), "g"(arg3), "g"(arg4), "g"(arg5), "g"(arg6), "g"(arg7), "g"(arg8), "g"(arg9), "g"(arg10)); \ } while (0) #define STAP_PROBE(provider,probe) \ -- cgit From 30369ac1fe0ed4e022691eceaddb848689935f87 Mon Sep 17 00:00:00 2001 From: "Frank Ch. Eigler" Date: Tue, 24 Mar 2009 15:11:33 -0400 Subject: build fix for RHEL4-era gcc 3.4.6 * tapsets.cxx (stringhash): Go to __gnu_cxx. (dwarf_cast_expanding_visitor::visit_cast_op): Use ~0 for all-ones. --- tapsets.cxx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/tapsets.cxx b/tapsets.cxx index 3a181cb3..c36a1aa0 100644 --- a/tapsets.cxx +++ b/tapsets.cxx @@ -603,7 +603,8 @@ typedef tr1::unordered_map cu_function_cache_t; typedef tr1::unordered_map mod_cu_function_cache_t; // module:cu -> function -> die #else struct stringhash { - size_t operator() (const string& s) const { hash h; return h(s.c_str()); } + // __gnu_cxx:: is needed because our own hash.h has an ambiguous hash<> decl too. + size_t operator() (const string& s) const { __gnu_cxx::hash h; return h(s.c_str()); } }; typedef hash_map cu_function_cache_t; @@ -5022,7 +5023,7 @@ void dwarf_cast_expanding_visitor::visit_cast_op (cast_op* e) string code; exp_type type = pe_long; - size_t mod_end = -1; + size_t mod_end = ~0; do { // split the module string by ':' for alternatives -- cgit From 148f987f1bbc4a8fe23012a56bf89bb9fc69beb9 Mon Sep 17 00:00:00 2001 From: "Frank Ch. Eigler" Date: Tue, 24 Mar 2009 15:15:10 -0400 Subject: accelerate pass-3 symbol/unwind generation * translate.cxx (emit_symbol_data): Abort dwfl_getmodules loop as soon as we run out of modules we're looking for. --- translate.cxx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/translate.cxx b/translate.cxx index 40bb82c2..798d52fe 100644 --- a/translate.cxx +++ b/translate.cxx @@ -4826,7 +4826,7 @@ emit_symbol_data (systemtap_session& s) if (pending_interrupts) return; off = dwfl_getmodules (dwfl, &dump_unwindsyms, (void *) &ctx, 0); } - while (off > 0); + while (off > 0 && !ctx.undone_unwindsym_modules.empty()); dwfl_assert("dwfl_getmodules", off == 0); } dwfl_end(dwfl); @@ -4864,7 +4864,7 @@ emit_symbol_data (systemtap_session& s) if (pending_interrupts) return; off = dwfl_getmodules (dwfl, &dump_unwindsyms, (void *) &ctx, 0); } - while (off > 0); + while (off > 0 && !ctx.undone_unwindsym_modules.empty()); dwfl_assert("dwfl_getmodules", off == 0); } dwfl_end(dwfl); -- cgit From 59b6abb36a6b4db7025b65112164378621a70444 Mon Sep 17 00:00:00 2001 From: David Smith Date: Tue, 24 Mar 2009 14:43:08 -0500 Subject: PR 9989 fix. 2009-03-24 David Smith PR 9989. * runtime/task_finder.c (stap_utrace_detach): Ignores -EINPROGRESS. (stap_utrace_detach_ops): Ignores errors from stap_utrace_detach(), so that other tasks will get detached from this utrace engine. (__stp_utrace_attach): Better error handling from utrace_barrier(). (__stp_utrace_task_finder_target_quiesce): Ditto. --- runtime/task_finder.c | 39 ++++++++++++++++++++++++++------------- 1 file changed, 26 insertions(+), 13 deletions(-) diff --git a/runtime/task_finder.c b/runtime/task_finder.c index 3f4908cb..e494e7a8 100644 --- a/runtime/task_finder.c +++ b/runtime/task_finder.c @@ -39,15 +39,23 @@ static atomic_t __stp_attach_count = ATOMIC_INIT (0); #define debug_task_finder_attach() (atomic_inc(&__stp_attach_count)) #define debug_task_finder_detach() (atomic_dec(&__stp_attach_count)) +#ifdef DEBUG_TASK_FINDER_PRINTK +#define debug_task_finder_report() (printk(KERN_ERR \ + "%s:%d attach count: %d, inuse count: %d\n", \ + __FUNCTION__, __LINE__, \ + atomic_read(&__stp_attach_count), \ + atomic_read(&__stp_inuse_count))) +#else #define debug_task_finder_report() (_stp_dbug(__FUNCTION__, __LINE__, \ "attach count: %d, inuse count: %d\n", \ atomic_read(&__stp_attach_count), \ atomic_read(&__stp_inuse_count))) +#endif /* !DEBUG_TASK_FINDER_PRINTK */ #else #define debug_task_finder_attach() /* empty */ #define debug_task_finder_detach() /* empty */ #define debug_task_finder_report() /* empty */ -#endif +#endif /* !DEBUG_TASK_FINDER */ typedef int (*stap_task_finder_callback)(struct stap_task_finder_target *tgt, struct task_struct *tsk, @@ -280,11 +288,15 @@ stap_utrace_detach(struct task_struct *tsk, break; case -ESRCH: /* REAP callback already begun */ case -EALREADY: /* DEATH callback already begun */ - rc = 0; /* ignore these errors*/ + rc = 0; /* ignore these errors */ + break; + case -EINPROGRESS: + debug_task_finder_detach(); + rc = 0; break; default: rc = -rc; - _stp_error("utrace_detach returned error %d on pid %d", + _stp_error("utrace_control returned error %d on pid %d", rc, tsk->pid); break; } @@ -298,7 +310,6 @@ stap_utrace_detach_ops(struct utrace_engine_ops *ops) { struct task_struct *grp, *tsk; struct utrace_attached_engine *engine; - int rc = 0; pid_t pid = 0; // Notice we're not calling get_task_mm() in this loop. In @@ -324,11 +335,12 @@ stap_utrace_detach_ops(struct utrace_engine_ops *ops) continue; #endif - rc = stap_utrace_detach(tsk, ops); - if (rc != 0) - goto udo_err; + /* Notice we're purposefully ignoring errors from + * stap_utrace_detach(). Even if we got an error on + * this task, we need to keep detaching from other + * tasks. */ + (void) stap_utrace_detach(tsk, ops); } while_each_thread(grp, tsk); -udo_err: rcu_read_unlock(); debug_task_finder_report(); } @@ -475,7 +487,7 @@ __stp_utrace_attach(struct task_struct *tsk, * ref. */ rc = utrace_barrier(tsk, engine); - if (rc != 0) + if (rc != -ESRCH && rc != -EALREADY) _stp_error("utrace_barrier returned error %d on pid %d", rc, (int)tsk->pid); } @@ -494,7 +506,7 @@ __stp_utrace_attach(struct task_struct *tsk, } } - else + else if (rc != -ESRCH && rc != -EALREADY) _stp_error("utrace_set_events2 returned error %d on pid %d", rc, (int)tsk->pid); utrace_engine_put(engine); @@ -869,11 +881,12 @@ __stp_utrace_task_finder_target_quiesce(enum utrace_resume_action action, * a stale task pointer, if we have an engine ref. */ rc = utrace_barrier(tsk, engine); - if (rc != 0) + if (rc == 0) + rc = utrace_set_events(tsk, engine, + __STP_ATTACHED_TASK_BASE_EVENTS(tgt)); + else if (rc != -ESRCH && rc != -EALREADY) _stp_error("utrace_barrier returned error %d on pid %d", rc, (int)tsk->pid); - rc = utrace_set_events(tsk, engine, - __STP_ATTACHED_TASK_BASE_EVENTS(tgt)); } if (rc != 0) _stp_error("utrace_set_events returned error %d on pid %d", -- cgit From 168bcc7c71f203fed7a8f25bfd0a84369b968c0f Mon Sep 17 00:00:00 2001 From: "Frank Ch. Eigler" Date: Tue, 24 Mar 2009 15:48:56 -0400 Subject: itrace: zap "usr_itrace_init: completed for tid = NNNN" debug message --- runtime/itrace.c | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/runtime/itrace.c b/runtime/itrace.c index 618cbff0..97ba427e 100644 --- a/runtime/itrace.c +++ b/runtime/itrace.c @@ -340,7 +340,8 @@ static int usr_itrace_init(int single_step, pid_t tid, struct stap_itrace_probe put_task_struct(tsk); rcu_read_unlock(); - printk(KERN_INFO "usr_itrace_init: completed for tid = %d\n", tid); + if (debug) + printk(KERN_INFO "usr_itrace_init: completed for tid = %d\n", tid); return 0; } -- cgit From ccc11a14c5117fcee425d53f00f0b871ac727728 Mon Sep 17 00:00:00 2001 From: "Frank Ch. Eigler" Date: Tue, 24 Mar 2009 15:55:26 -0400 Subject: Revert "PR9940: avoid duplicated calling of uprobes in shared libraries" This fix caused a regression on fedora. stap -ve 'probe process("/bin/ls").function("main") { log(pp()); } probe process("/lib64/libc.so.6").function("*") { log(pp()); }' \ -c /bin/ls hung (with stapio & ls processes spinning) upon startup. --- runtime/task_finder.c | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/runtime/task_finder.c b/runtime/task_finder.c index e494e7a8..7949a81f 100644 --- a/runtime/task_finder.c +++ b/runtime/task_finder.c @@ -1045,7 +1045,6 @@ __stp_utrace_task_finder_target_syscall_entry(enum utrace_resume_action action, static void __stp_call_vm_callbacks_with_vma(struct stap_task_finder_target *tgt, struct task_struct *tsk, - int map_p, struct vm_area_struct *vma) { char *mmpath_buf; @@ -1072,7 +1071,7 @@ __stp_call_vm_callbacks_with_vma(struct stap_task_finder_target *tgt, rc, (int)tsk->pid); } else { - __stp_call_vm_callbacks(tgt, tsk, map_p, mmpath, + __stp_call_vm_callbacks(tgt, tsk, 1, mmpath, vma->vm_start, vma->vm_end, (vma->vm_pgoff << PAGE_SHIFT)); } @@ -1165,7 +1164,7 @@ __stp_utrace_task_finder_target_syscall_exit(enum utrace_resume_action action, down_read(&mm->mmap_sem); vma = __stp_find_file_based_vma(mm, rv); if (vma != NULL) { - __stp_call_vm_callbacks_with_vma(tgt, tsk, 0, vma); + __stp_call_vm_callbacks_with_vma(tgt, tsk, vma); } up_read(&mm->mmap_sem); mmput(mm); @@ -1238,7 +1237,6 @@ __stp_utrace_task_finder_target_syscall_exit(enum utrace_resume_action action, && vma->vm_end <= entry->vm_end) { __stp_call_vm_callbacks_with_vma(tgt, tsk, - 1, vma); if (vma->vm_end >= entry->vm_end) break; -- cgit From 49b50ec6c2b45456d33d3fa145ccd3adfe4c528b Mon Sep 17 00:00:00 2001 From: Stan Cox Date: Tue, 24 Mar 2009 16:11:55 -0400 Subject: Remove debugging line. * dtrace: Remove debugging line. --- dtrace | 1 - 1 file changed, 1 deletion(-) diff --git a/dtrace b/dtrace index 7966e1f2..fd7b4b99 100755 --- a/dtrace +++ b/dtrace @@ -80,7 +80,6 @@ class provider: elif (c == 8): self.h.write ('#define %s(arg1,arg2,arg3,arg4,arg5,arg6,arg7,arg8,arg9) STAP_PROBE%d(provider,%s,arg1,arg2,arg3,arg4,arg5,arg6,arg7,arg8,arg9)\n' % (this_probe_canon, c+1, this_probe)) elif (c == 9): - self.h.write('// X %d %s\n' % (c+1,this_probe_canon)) self.h.write ('#define %s(arg1,arg2,arg3,arg4,arg5,arg6,arg7,arg8,arg9,arg10) STAP_PROBE%d(provider,%s,arg1,arg2,arg3,arg4,arg5,arg6,arg7,arg8,arg9,arg10)\n' % (this_probe_canon, c+1, this_probe)) self.h.write ('#define %s_ENABLED() 1\n' % this_probe_canon) -- cgit From b84e888167b9ecc22497730078759ee3a7c4914e Mon Sep 17 00:00:00 2001 From: Mark Wielaard Date: Tue, 24 Mar 2009 21:37:30 +0100 Subject: Add testcase for uprobe on shared library (PR9940). * testsuite/systemtap.base/uprobes_exe.c: New file. * testsuite/systemtap.base/uprobes_lib.c: New file. * testsuite/systemtap.base/uprobes_lib.exp: New file. * testsuite/systemtap.base/uprobes_lib.stp: New file. --- testsuite/systemtap.base/uprobes_exe.c | 27 +++++++++++++++++++++++ testsuite/systemtap.base/uprobes_lib.c | 20 +++++++++++++++++ testsuite/systemtap.base/uprobes_lib.exp | 38 ++++++++++++++++++++++++++++++++ testsuite/systemtap.base/uprobes_lib.stp | 9 ++++++++ 4 files changed, 94 insertions(+) create mode 100644 testsuite/systemtap.base/uprobes_exe.c create mode 100644 testsuite/systemtap.base/uprobes_lib.c create mode 100644 testsuite/systemtap.base/uprobes_lib.exp create mode 100644 testsuite/systemtap.base/uprobes_lib.stp diff --git a/testsuite/systemtap.base/uprobes_exe.c b/testsuite/systemtap.base/uprobes_exe.c new file mode 100644 index 00000000..447434c6 --- /dev/null +++ b/testsuite/systemtap.base/uprobes_exe.c @@ -0,0 +1,27 @@ +/* uprobes_lib test case + * Copyright (C) 2009, Red Hat Inc. + * + * This file is part of systemtap, and is free software. You can + * redistribute it and/or modify it under the terms of the GNU General + * Public License (GPL); either version 2, or (at your option) any + * later version. + */ + +#include + +// function from our library +int lib_main (void); + +void +main_func (int foo) +{ + ; // nothing here... +} + +int +main (int argc, char *argv[], char *envp[]) +{ + main_func(1); + lib_main(); + return 0; +} diff --git a/testsuite/systemtap.base/uprobes_lib.c b/testsuite/systemtap.base/uprobes_lib.c new file mode 100644 index 00000000..c9d70625 --- /dev/null +++ b/testsuite/systemtap.base/uprobes_lib.c @@ -0,0 +1,20 @@ +/* uprobes_lib test case - library helper + * Copyright (C) 2009, Red Hat Inc. + * + * This file is part of systemtap, and is free software. You can + * redistribute it and/or modify it under the terms of the GNU General + * Public License (GPL); either version 2, or (at your option) any + * later version. + */ + +void +lib_func (int bar) +{ + ; // nothing here... +} + +void +lib_main () +{ + lib_func (3); +} diff --git a/testsuite/systemtap.base/uprobes_lib.exp b/testsuite/systemtap.base/uprobes_lib.exp new file mode 100644 index 00000000..ae1b72e8 --- /dev/null +++ b/testsuite/systemtap.base/uprobes_lib.exp @@ -0,0 +1,38 @@ +set test "uprobes_lib" +set testpath "$srcdir/$subdir" +set testsrc "$testpath/uprobes_exe.c" +set testsrclib "$testpath/uprobes_lib.c" +set testexe "./uprobes_exe" +set testlibname "uprobes_lib" +set testlibdir "." +set testso "$testlibdir/lib${testlibname}.so" +set testflags "additional_flags=-g additional_flags=-O" +set testlibflags "$testflags additional_flags=-fPIC additional_flags=-shared" +set maintestflags "$testflags additional_flags=-L$testlibdir additional_flags=-l$testlibname additional_flags=-Wl,-rpath,$testlibdir" + +# Only run on make installcheck +if {! [installtest_p]} { untested "$test"; return } + +# Compile our test program and library. +set res [target_compile $testsrclib $testso executable $testlibflags] +if { $res != "" } { + verbose "target_compile for $testso failed: $res" 2 + fail "unable to compile $testsrclib" + return +} +set res [target_compile $testsrc $testexe executable $maintestflags] +if { $res != "" } { + verbose "target_compile failed: $res" 2 + fail "unable to compile $testsrc" + return +} + +# XXX main_func needs another/extra test. Disabled for now. +# Enable (and in uprobes_lib.stp) after PR9940 is fixed. +# set ::result_string {main_func +# lib_func} +set ::result_string {lib_func} + +stap_run2 $srcdir/$subdir/$test.stp -c $testexe + +#exec rm -f $testexe $testso diff --git a/testsuite/systemtap.base/uprobes_lib.stp b/testsuite/systemtap.base/uprobes_lib.stp new file mode 100644 index 00000000..bc6cc249 --- /dev/null +++ b/testsuite/systemtap.base/uprobes_lib.stp @@ -0,0 +1,9 @@ +/* - Not activated probe... Seems always skipped? +probe process("uprobes_exe").function("main_func") { + printf("main_func\n"); +} +*/ + +probe process("libuprobes_lib.so").function("lib_func") { + printf("lib_func\n"); +} -- cgit From 5d6b014268ca47386ef92525b8669429dec6e49c Mon Sep 17 00:00:00 2001 From: "Frank Ch. Eigler" Date: Tue, 24 Mar 2009 16:41:31 -0400 Subject: further accelerate pass-3 symbol/unwind process, skip one more iteration --- translate.cxx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/translate.cxx b/translate.cxx index 798d52fe..55b266bf 100644 --- a/translate.cxx +++ b/translate.cxx @@ -4824,9 +4824,10 @@ emit_symbol_data (systemtap_session& s) do { if (pending_interrupts) return; + if (ctx.undone_unwindsym_modules.empty()) return; off = dwfl_getmodules (dwfl, &dump_unwindsyms, (void *) &ctx, 0); } - while (off > 0 && !ctx.undone_unwindsym_modules.empty()); + while (off > 0); dwfl_assert("dwfl_getmodules", off == 0); } dwfl_end(dwfl); @@ -4862,9 +4863,10 @@ emit_symbol_data (systemtap_session& s) do { if (pending_interrupts) return; + if (ctx.undone_unwindsym_modules.empty()) return; off = dwfl_getmodules (dwfl, &dump_unwindsyms, (void *) &ctx, 0); } - while (off > 0 && !ctx.undone_unwindsym_modules.empty()); + while (off > 0); dwfl_assert("dwfl_getmodules", off == 0); } dwfl_end(dwfl); -- cgit From d10b4351a0bc2386ff15c806bfc3cd531fe883f0 Mon Sep 17 00:00:00 2001 From: Roland McGrath Date: Tue, 24 Mar 2009 15:43:25 -0700 Subject: Typo and whitespace. --- stap.1.in | 66 +++++++++++++++++++++++++++++++-------------------------------- 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/stap.1.in b/stap.1.in index 088449c0..c664962c 100644 --- a/stap.1.in +++ b/stap.1.in @@ -150,7 +150,7 @@ Add the given directory to the tapset search directory. See the description of pass 2 for details. .TP .BI \-D " NAME=VALUE" -Add the given C preprocessor directive to the module Makefile. These can +Add the given C preprocessor directive to the module Makefile. These can be used to override limit parameters described below. .TP .BI \-R " DIR" @@ -183,7 +183,7 @@ This supports a subset of strftime(3) (%%, %C, %Y, %y, %m, %d, %e, %F, Start the probes, run CMD, and exit when CMD finishes. .TP .BI \-x " PID" -Sets target() to PID. This allows scripts to be written that filter on +Sets target() to PID. This allows scripts to be written that filter on a specific process. .TP .BI \-l " PROBE" @@ -197,7 +197,7 @@ Similar to "-l", but list probe points and script-level local variables. .BI \-F Without -o option, load module and start probes, then detach from the module leaving the probes running. -With -o option, run staprun in background as a daemon and show it's pid. +With -o option, run staprun in background as a daemon and show its pid. .TP .BI \-S " size[,N]" Sets the maximum size of output file and the maximum number of output files. @@ -253,7 +253,7 @@ parser for substitution. See below. .SH SCRIPT LANGUAGE -The systemtap script language resembles +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 @@ -292,7 +292,7 @@ number beyond what was actually given is an error. .SS PREPROCESSING A simple conditional preprocessing stage is run as a part of parsing. -The general form is similar to the +The general form is similar to the .RB cond " ? " exp1 " : " exp2 ternary operator: .SAMPLE @@ -316,7 +316,7 @@ version of the target kernel (as optionally overridden by the option) compares to the given version string. The comparison is performed by the glibc function .BR strverscmp . -As a special case, if the operator is for simple equality +As a special case, if the operator is for simple equality .RB ( == ), or inequality .RB ( != ), @@ -348,14 +348,14 @@ kernel version is newer than 2.6.5: .ESAMPLE The following code might adapt to hypothetical kernel version drift: .SAMPLE -probe kernel.function ( - %( kernel_v <= "2.6.12" %? "__mm_do_fault" %: +probe kernel.function ( + %( kernel_v <= "2.6.12" %? "__mm_do_fault" %: %( kernel_vr == "2.6.13*smp" %? "do_page_fault" %: UNSUPPORTED %) %) ) { /* ... */ } %( arch == "ia64" %? - probe syscall.vliw = kernel.function("vliw_widget") {} + probe syscall.vliw = kernel.function("vliw_widget") {} %) .ESAMPLE @@ -423,7 +423,7 @@ 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 +Execute each statement in sequence in this block. Note that separators or terminators are generally not necessary between statements. .TP .BR ; @@ -445,12 +445,12 @@ STMT, then the iteration expression EXP3. .BR foreach " (VAR " in " ARRAY [ "limit " EXP ]) STMT" Loop over each element of the named global array, assigning current key to VAR. The array may not be modified within the statement. -By adding a single +By adding a single .BR + " or " \- operator after the VAR or the ARRAY identifier, the iteration will proceed in a sorted order, by ascending or descending index or value. Using the optional -.BR limit +.BR limit keyword limits the number of loop iterations to EXP times. EXP is evaluted once at the beginning of the loop. .TP @@ -503,7 +503,7 @@ string assignment operators .B = .= .TP unary numeric operators -.B + \- ! ~ ++ \-\- +.B + \- ! ~ ++ \-\- .TP binary numeric or string comparison operators .B < > <= >= == != @@ -542,7 +542,7 @@ The probe handler is interpreted relative to the context of each event. For events associated with kernel code, this context may include .I variables -defined in the +defined in the .I source code at that spot. These "target variables" are presented to the script as variables whose names are prefixed with "$". They may be accessed @@ -553,9 +553,9 @@ with optimized code. Some other events have very little context. New probe points may be defined using "aliases". Probe point aliases look similar to probe definitions, but instead of activating a probe at the given point, it just defines a new probe point name as an alias -to an existing one. There are two types of alias, i.e. the prologue +to an existing one. There are two types of alias, i.e. the prologue style and the epilogue style which are identified by "=" and "+=" -respectively. +respectively. .PP For prologue style alias, the statement block that follows an alias definition is implicitly added as a prologue to any probe that refers @@ -655,9 +655,9 @@ The .IR printf formatting directives similar to those of C, except that they are fully type-checked by the translator: -.RS +.RS .TP -%b +%b Writes a binary blob of the value given, instead of ASCII text. The width specifier determines the number of bytes to write; valid specifiers are %b %1b %2b %4b %8b. Default (%b) is 8 bytes. .TP %c @@ -738,7 +738,7 @@ distinct extraction function operating on a given identifier, the translator arranges to compute a set of statistics that satisfy it. The statistics system is thereby "on-demand". Each execution of an extraction function causes the aggregation to be computed for -that moment across all processors. +that moment across all processors. .PP Here is the set of extractor functions. The first argument of each is the same style of lvalue used on the left hand side of the accumulate @@ -751,7 +751,7 @@ integers. Histograms are also available, but are more complicated because they have a vector rather than scalar value. .I @hist_linear(v,start,stop,interval) -represents a linear histogram from "start" to "stop" by increments +represents a linear histogram from "start" to "stop" by increments of "interval". The interval must be positive. Similarly, .I @hist_log(v) represents a base-2 logarithmic histogram. Printing a histogram @@ -763,7 +763,7 @@ family of functions renders a histogram object as a tabular probe foo { x <<< $value } -probe end { +probe end { printf ("avg %d = sum %d / count %d\\n", @avg(x), @sum(x), @count(x)) print (@hist_log(v)) @@ -823,7 +823,7 @@ 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. +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 @@ -884,7 +884,7 @@ the following patterns would be searched, in sequence: .IR 2.6/*.stp , and finally .IR *.stp -Stopping the translator after pass 1 causes it to print the parse trees. +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 @@ -896,7 +896,7 @@ 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 +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 @@ -913,7 +913,7 @@ Since this optimization can hide latent code errors such as type mismatches or invalid $target variables, it sometimes may be useful to disable the optimizations with the .BR \-u -option. +option. .PP Finally, all variable, function, parameter, array, and index types are inferred from context (literals and operators). Stopping the @@ -956,7 +956,7 @@ Finally, unloads the module, and cleans up. .SH EXAMPLES -See the +See the .IR stapex (3stap) manual page for a collection of samples. @@ -970,10 +970,10 @@ the .I $SYSTEMTAP_DIR/cache directory. The cache can be limited by having the file .I cache_mb_limit -placed in the cache directory (shown above) containing only an ASCII +placed in the cache directory (shown above) containing only an ASCII integer representing how many MiB the cache should not exceed. Note that this is a 'soft' limit in that the cache will be cleaned after a new entry -is added, so the total cache size may temporarily exceed this limit. In the +is added, so the total cache size may temporarily exceed this limit. In the absence of this file, a default will be created with the limit set to 64MiB. .SH SAFETY AND SECURITY @@ -1005,11 +1005,11 @@ program are run by the .IR staprun 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 +kernel-to-user data transfer. Since .IR staprun does not perform any additional security checks on the kernel objects it is given, it would be unwise for a system administrator to add -untrusted users to the +untrusted users to the .I stapdev or .I stapusr @@ -1026,7 +1026,7 @@ to kernel crash or data corruption. The resource use limits are set by macros in the generated C code. These may be overridden with the .BR \-D -flag. A selection of these is as follows: +flag. A selection of these is as follows: .TP MAXNESTING Maximum number of recursive function call levels, default 10. @@ -1099,7 +1099,7 @@ Note that you must unload guests before unloading a host. If there are some guests connected to the host, unloading the host will be failed. .PP -In case something goes wrong with +In case something goes wrong with .IR stap " or " staprun after a probe has already started running, one may safely kill both user processes, and remove the active probe kernel module with @@ -1173,7 +1173,7 @@ environment variable. Temporary directory for systemtap files, including translated C code and kernel object. .TP -@prefix@/share/systemtap/tapset +@prefix@/share/systemtap/tapset The automatic tapset search directory, unless overridden by the .I SYSTEMTAP_TAPSET -- cgit From c87193cfb18258abbad947d009e6ca0bd2d5e0cf Mon Sep 17 00:00:00 2001 From: "Frank Ch. Eigler" Date: Tue, 24 Mar 2009 19:14:57 -0400 Subject: brown paper bag fix for commit 5d6b0142 return != break --- translate.cxx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/translate.cxx b/translate.cxx index 55b266bf..0b81d9bb 100644 --- a/translate.cxx +++ b/translate.cxx @@ -4824,7 +4824,7 @@ emit_symbol_data (systemtap_session& s) do { if (pending_interrupts) return; - if (ctx.undone_unwindsym_modules.empty()) return; + if (ctx.undone_unwindsym_modules.empty()) break; off = dwfl_getmodules (dwfl, &dump_unwindsyms, (void *) &ctx, 0); } while (off > 0); @@ -4863,7 +4863,7 @@ emit_symbol_data (systemtap_session& s) do { if (pending_interrupts) return; - if (ctx.undone_unwindsym_modules.empty()) return; + if (ctx.undone_unwindsym_modules.empty()) break; off = dwfl_getmodules (dwfl, &dump_unwindsyms, (void *) &ctx, 0); } while (off > 0); -- cgit From e1e3ba36653db4b1dcd82e7cb3579776a6834de7 Mon Sep 17 00:00:00 2001 From: Rajan Arora Date: Tue, 24 Mar 2009 22:30:37 -0400 Subject: PR 9922 fix, make --disable-pie the configure default *configure.ac: Change the default to compiling without fPIE. *systemtap.spec: Add --enable-pie as the default option (set pie_supported to 1). *configure: Regenerated with autoconf 2.61. --- configure | 3 ++- configure.ac | 3 ++- systemtap.spec | 9 ++++++++- 3 files changed, 12 insertions(+), 3 deletions(-) diff --git a/configure b/configure index 57afc1bb..4f33313d 100755 --- a/configure +++ b/configure @@ -5990,12 +5990,13 @@ rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext fi +# Compiling without fPIE by default (see PR 9922) # Check whether --enable-pie was given. if test "${enable_pie+set}" = set; then enableval=$enable_pie; fi -if test "x$enable_pie" != xno; then +if test "x$enable_pie" == xyes; then save_CFLAGS="$CFLAGS" save_CXXFLAGS="$CXXFLAGS" diff --git a/configure.ac b/configure.ac index 9d8dd7ae..f1546673 100644 --- a/configure.ac +++ b/configure.ac @@ -82,9 +82,10 @@ AS_IF([test "x$enable_ssp" != xno],[ CFLAGS="$save_CFLAGS" CXXFLAGS="$save_CXXFLAGS"])]) +# Compiling without fPIE by default (see PR 9922) AC_ARG_ENABLE([pie], [AS_HELP_STRING([--disable-pie], [disable position-independent-executable])]) -AS_IF([test "x$enable_pie" != xno],[ +AS_IF([test "x$enable_pie" == xyes],[ save_CFLAGS="$CFLAGS" save_CXXFLAGS="$CXXFLAGS" save_LDFLAGS="$LDFLAGS" diff --git a/systemtap.spec b/systemtap.spec index 020cd001..e727b49c 100644 --- a/systemtap.spec +++ b/systemtap.spec @@ -3,6 +3,7 @@ %{!?with_crash: %define with_crash 0} %{!?with_bundled_elfutils: %define with_bundled_elfutils 0} %{!?elfutils_version: %define elfutils_version 0.127} +%{!?pie_supported: %define pie_supported 1} Name: systemtap Version: 0.9 @@ -175,9 +176,15 @@ cd .. %define docs_config --disable-docs %endif +# Enable pie as configure defaults to disabling it +%if %{pie_supported} +%define pie_config --enable-pie +%else +%define pie_config --disable-pie +%endif -%configure %{?elfutils_config} %{sqlite_config} %{crash_config} %{docs_config} +%configure %{?elfutils_config} %{sqlite_config} %{crash_config} %{docs_config} %{pie_config} make %{?_smp_mflags} %install -- cgit From 6a25ac4c75c33272af96fb3217a0e27b8e847a9a Mon Sep 17 00:00:00 2001 From: Mark Wielaard Date: Wed, 25 Mar 2009 11:33:56 +0100 Subject: NEWS: Document how to see man pages for probes and functions in 3stap section. --- NEWS | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/NEWS b/NEWS index 74dde8b7..c169c5e2 100644 --- a/NEWS +++ b/NEWS @@ -1,8 +1,11 @@ * What's new - Systemtap probes and function man pages extracted from the tapsets - are now available. To look at man page for systemtap vm.pagefault: - $ man 3stap vm.pagefault + are now available in a separate man section 3stap. + To look at the page for probe vm.pagefault: + $ man -S 3stap probe_vm.pagefault + To look at the page for the function pexecname: + $ man -S 3stap pexecname - Kernel tracepoints are now supported for probing predefined kernel events without any debuginfo. Tracepoints incur less overhead than -- cgit From 83dd1a8e273f5a30a94fd6438fe0567c5fd1aee7 Mon Sep 17 00:00:00 2001 From: Mark Wielaard Date: Wed, 25 Mar 2009 13:34:04 +0100 Subject: NEWS: Add description of probe process().insn and process().insn.block. --- NEWS | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/NEWS b/NEWS index c169c5e2..795d73c1 100644 --- a/NEWS +++ b/NEWS @@ -1,5 +1,14 @@ * What's new + - New probes process().insn and process().insn.block that allows + inspection of the process after each instruction or block of + instructions executed. So to count the total number of instructions + a process executes during a run do something like: + $ stap -e 'global steps; probe process("/bin/ls").insn {steps++} + probe end {printf("Total instructions: %d\n", steps);}' \ + -c /bin/ls + This feature can slow down execution of a process somewhat. + - Systemtap probes and function man pages extracted from the tapsets are now available in a separate man section 3stap. To look at the page for probe vm.pagefault: -- cgit From 8e2dc4511df5c321b7723549a559398a3aa84e96 Mon Sep 17 00:00:00 2001 From: Mark Wielaard Date: Wed, 25 Mar 2009 13:49:24 +0100 Subject: NEWS: Fix man 3stap description to original. --- NEWS | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/NEWS b/NEWS index 795d73c1..d10c2cc3 100644 --- a/NEWS +++ b/NEWS @@ -9,12 +9,11 @@ -c /bin/ls This feature can slow down execution of a process somewhat. -- Systemtap probes and function man pages extracted from the tapsets - are now available in a separate man section 3stap. - To look at the page for probe vm.pagefault: - $ man -S 3stap probe_vm.pagefault - To look at the page for the function pexecname: - $ man -S 3stap pexecname + - Systemtap probes and function man pages extracted from the tapsets + are now available under 3stap. To show the page for probe vm.pagefault + or the stap function pexecname do: + $ man 3stap vm.pagefault + $ man 3stap pexecname - Kernel tracepoints are now supported for probing predefined kernel events without any debuginfo. Tracepoints incur less overhead than -- cgit From 59fde7ccc0f707fb55a2e145e78a1e19a4fd2e80 Mon Sep 17 00:00:00 2001 From: Mark Wielaard Date: Wed, 25 Mar 2009 14:09:02 +0100 Subject: NEWS: Document mark/trace list mode, interrupt reentrancy, reentrancy debug. --- NEWS | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/NEWS b/NEWS index d10c2cc3..4dae77d7 100644 --- a/NEWS +++ b/NEWS @@ -54,6 +54,18 @@ This replaces any dwarf $variable expressions that could not be resolved with literal numeric zeros, along with a warning message. +- Both kernel markers and kernel tracepoint support argument listing + through stap -L 'kernel.mark("*")' or stap -L 'kernel.trace("*")' + +- Users can use -DINTERRUPTIBLE=0 to prevent interrupt reentrancy in + their script, at the cost of a bit more overhead to toggle the + interrupt mask. + +- Added reentrancy debugging. If stap is run with the arguments + "-t -DDEBUG_REENTRANCY", additional warnings will be printed for + every reentrancy event, including the probe points of the + resident and interloper probes. + * What's new in version 0.9 - Typecasting is now supported using the @cast operator. A script can -- cgit From 882ddac13d8a821b93d4f9d2b7a16c9322ee46b6 Mon Sep 17 00:00:00 2001 From: Rajan Arora Date: Wed, 25 Mar 2009 10:33:45 -0400 Subject: Update configure --help message now that default is changed *configure.ac: Update help message for building with pie support. *configure: Regenerate. --- configure | 2 +- configure.ac | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/configure b/configure index 4f33313d..777d6c0d 100755 --- a/configure +++ b/configure @@ -1336,7 +1336,7 @@ Optional Features: location). --enable-prologues make -P prologue-searching default --disable-ssp disable gcc stack-protector - --disable-pie disable position-independent-executable + --enable-pie enable position-independent-executable --enable-sqlite build with sqlite support --enable-crash[=DIRECTORY] enable crash extension (default is disabled). diff --git a/configure.ac b/configure.ac index f1546673..e980fbf5 100644 --- a/configure.ac +++ b/configure.ac @@ -84,7 +84,7 @@ AS_IF([test "x$enable_ssp" != xno],[ # Compiling without fPIE by default (see PR 9922) AC_ARG_ENABLE([pie], - [AS_HELP_STRING([--disable-pie], [disable position-independent-executable])]) + [AS_HELP_STRING([--enable-pie], [enable position-independent-executable])]) AS_IF([test "x$enable_pie" == xyes],[ save_CFLAGS="$CFLAGS" save_CXXFLAGS="$CXXFLAGS" -- cgit From b41a544e20a42413daa0323d2f149e9e34586ccf Mon Sep 17 00:00:00 2001 From: "Frank Ch. Eigler" Date: Wed, 25 Mar 2009 10:44:55 -0400 Subject: Fix for CVE-2009-0784: stapusr module-path checking race * runtime/staprun/staprun_funcs.c (check_path): Save fully canonicalized and checked module path for later loading. --- runtime/staprun/staprun_funcs.c | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/runtime/staprun/staprun_funcs.c b/runtime/staprun/staprun_funcs.c index 5e7fa102..e94e5d13 100644 --- a/runtime/staprun/staprun_funcs.c +++ b/runtime/staprun/staprun_funcs.c @@ -269,6 +269,15 @@ check_path(void) return -1; } + /* Overwrite the modpath with the canonicalized one, to defeat + a possible race between path checking below and somewhat later + module loading. */ + modpath = strdup (module_realpath); + if (modpath == NULL) { + _perr("allocating memory failed"); + exit (1); + } + /* To make sure the user can't specify something like * /lib/modules/`uname -r`/systemtapmod.ko, put a '/' on the * end of staplib_dir_realpath. */ -- cgit