[PATCH 00/14] gentoo, manpage, and assorted other small fixes

[PATCH 00/14] gentoo, manpage, and assorted other small fixes

[Nick Alcock]

Most of these are bugs reported by Gentoo, but their request for a
dtprobed(8) manpage triggered a sweep of the dtrace manpage too, plus
a fix to a rather unfortunate millisecs-versus-sedcs bug which caused
us to wait for an hour and a half for a dtprobed parser child timeout
rather than the intended five seconds.

The only potentially contentious ones are libsystemd (quite a lot of
code, and not ours, but it's BSD-0-licensed and I took out the most
ridiculously overkill parts), and the last two, which drop apparently
redundant markup from the manpages whose purpose I'm not clear on but
which seems to be ancient and is probably working around bugs in old
Solaris troff or something. We can probably assume groff by this point,
it's been the only maintained troff for decades.

Nick Alcock (14):
  No longer depend on libsystemd
  pkgconfig: drop spaces in variable decls
  configure, build: make valgrind optional
  build: substitute LIBDIR in pkg-config files
  probe: get the size of the hash-lookup key right
  configure: fix dreadful behaviour of MANDIR / --mandir
  man: the synopsis is ended with .YS, not .SY
  man: use \- for option dashes, not -
  man: drop blank lines
  man: fix blank line in environment variables list
  dtprobed: fix parser child timeout
  man: add manpage for dtprobed(8)
  man: drop double-\fB at the start of every option line
  man: \fP-ize

 GNUmakefile              |   3 +-
 Makeconfig               |  37 +++++++++-
 cmd/Build                |   2 +-
 cmd/dtrace.8             | 151 ++++++++++++++++++++-------------------
 configure                |  11 ++-
 dtprobed/Build           |   9 +--
 dtprobed/dtprobed.8      |  66 +++++++++++++++++
 dtprobed/dtprobed.c      |  10 +--
 include/port.h           |   1 +
 libdtrace/dt_probe.c     |   6 +-
 libdtrace/dt_work.c      |  18 ++++-
 libport/Build            |   4 +-
 libport/systemd_notify.c |  70 ++++++++++++++++++
 uts/Build                |   1 +
 uts/dtrace.pc.in         |   6 +-
 uts/dtrace_sdt.pc.in     |   4 +-
 16 files changed, 291 insertions(+), 108 deletions(-)
 create mode 100644 dtprobed/dtprobed.8
 create mode 100644 libport/systemd_notify.c


base-commit: 8a1264bf0e818c8624be250eb5174714b62ed93c
-- 
2.46.0.278.g36e3a12567

[PATCH 01/14] No longer depend on libsystemd

[Nick Alcock]

We only need this for the systemd notification protocol, and that's so
simple there is MIT-0-licensed reusable code in the sd_notify manpage
showing you how to use it.  That code looks pretty much OK, so I modified it
lightly and pulled it into libport, with one tweak to remove the use of
__attribute__((cleanup)) (it could be replaced by one line of perfectly
trivial standard C code, saving five or six lines in all).

With libsystemd linkage gone, we need another way for the user to indicate
that systemd is not in use and the systemd unit files are not wanted: so
introduce a new --without-systemd (and corresponding --with-systemd=no,
etc) in configure.  (Someone directly running make can just pass
WITH_SYSTEMD= to make.)

We lose one feature of libsystemd's sd_notify: we no longer remove the
NOTIFY_SOCKET env var from the environment, so our children could in theory
pretend to be us and notify systemd on our behalf.  Since our only child
is in a seccomped jail and is part of dtprobed anyway, this loss of
functionality is purely theoretical.

Bug: https://github.com/oracle/dtrace-utils/issues/92
Signed-off-by: Nick Alcock <nick.alcock@oracle.com>
---
 GNUmakefile              |  1 +
 Makeconfig               |  1 -
 configure                |  8 +++--
 dtprobed/Build           |  7 +---
 dtprobed/dtprobed.c      |  8 +----
 include/port.h           |  1 +
 libport/Build            |  4 +--
 libport/systemd_notify.c | 70 ++++++++++++++++++++++++++++++++++++++++
 8 files changed, 82 insertions(+), 18 deletions(-)
 create mode 100644 libport/systemd_notify.c

diff --git a/GNUmakefile b/GNUmakefile
index e7657d466df5..99960227bcba 100644
--- a/GNUmakefile
+++ b/GNUmakefile
@@ -102,6 +102,7 @@ PKGCONFIGDIR = $(prefix)/share/pkgconfig
 INSTPKGCONFIGDIR = $(DESTDIR)$(PKGCONFIGDIR)
 TESTDIR = $(LIBDIR)/dtrace/testsuite
 INSTTESTDIR = $(DESTDIR)$(TESTDIR)
+WITH_SYSTEMD = true
 TARGETS =
 
 DTRACE ?= $(objdir)/dtrace
diff --git a/Makeconfig b/Makeconfig
index f3d47c086f4a..346078598624 100644
--- a/Makeconfig
+++ b/Makeconfig
@@ -218,7 +218,6 @@ $(eval $(call check-symbol-rule,ELF_GETSHDRSTRNDX,elf_getshdrstrndx,elf))
 $(eval $(call check-symbol-rule,LIBCTF,ctf_open,ctf,t))
 $(eval $(call check-symbol-rule,STRRSTR,strrstr,c))
 $(eval $(call check-symbol-rule,PTHREAD_ATFORK,pthread_atfork,c))
-$(eval $(call check-symbol-rule,LIBSYSTEMD,sd_notify,systemd,t))
 ifndef WANTS_LIBFUSE2
 $(eval $(call check-symbol-rule,FUSE_LOG,fuse_set_log_func,fuse3))
 $(eval $(call check-symbol-rule,LIBFUSE3,fuse_session_receive_buf,fuse3,t))
diff --git a/configure b/configure
index 4026a3eafcd3..42e496b97a7d 100755
--- a/configure
+++ b/configure
@@ -93,9 +93,13 @@ built locally, none of these should be needed):
 
 EOF
 	make help-overrides-header help-overrides-option
+	cat >&2 <<'EOF'
+--with-systemd=[yes/no]		Disable installation of the systemd unit files
+EOF
         echo >&2
         make help-overrides
 	cat >&2 <<'EOF'
+
 Options controlling the compiler (pass on the command line):
 
 CC				C compiler (may be a cross-compiler)
@@ -153,12 +157,12 @@ for option in "$@"; do
         --kernel-obj-dir=*) write_make_var KERNELOBJDIR "$option";;
         --kernel-src-suffix=*) write_make_var KERNELSRCNAME "$option";;
         --kernel-obj-suffix=*) write_make_var KERNELBLDNAME "$option";;
+        --with-systemd|--with-systemd=yes) write_make_var WITH_SYSTEMD "true";;
+        --with-systemd=no|--without-systemd) write_make_var WITH_SYSTEMD "";;
         HAVE_ELF_GETSHDRSTRNDX=*) write_config_var ELF_GETSHDRSTRNDX "$option";;
         --with-libctf=*) write_config_var LIBCTF "$option";;
         HAVE_LIBCTF=*) write_config_var LIBCTF "$option";;
         HAVE_STRRSTR=*) write_config_var STRRSTR "$option";;
-        --with-libsystemd=*) write_config_var LIBSYSTEMD "$option";;
-        HAVE_LIBSYSTEMD=*) write_config_var LIBSYSTEMD "$option";;
         HAVE_FUSE_LOG=*) write_config_var FUSE_LOG "$option";;
         --with-libfuse3=*) write_config_var LIBFUSE3 "$option";;
         HAVE_LIBFUSE3=*) write_config_var LIBFUSE3 "$option";;
diff --git a/dtprobed/Build b/dtprobed/Build
index 9132c3e31c8a..346cd6aee190 100644
--- a/dtprobed/Build
+++ b/dtprobed/Build
@@ -29,11 +29,6 @@ dtprobed_DEPS := libproc.a libcommon.a libport.a
 dtprobed_SOURCES := dtprobed.c dof_stash.c seccomp-assistance.c
 dtprobed_LIBSOURCES := libproc libcommon
 
-ifdef HAVE_LIBSYSTEMD
-dtprobed_CFLAGS += $(shell pkg-config --cflags libsystemd)
-dtprobed_LIBS += $(shell pkg-config --libs libsystemd)
-endif
-
 ifndef HAVE_FUSE_LOG
 dtprobed_SOURCES += rpl_fuse_log.c
 endif
@@ -43,7 +38,7 @@ seccomp-assistance.c_CFLAGS := -fno-lto
 endif
 
 install-dtprobed-autostart::
-ifdef HAVE_LIBSYSTEMD
+ifneq ($(WITH_SYSTEMD),)
 	mkdir -p $(INSTSYSTEMDUNITDIR) $(INSTSYSTEMDPRESETDIR)
 	$(call describe-install-target,$(INSTSYSTEMDUNITDIR),dtprobed.service)
 	sed 's,@SBINDIR@,$(SBINDIR),' < $(dtprobed_DIR)dtprobed.service.in > $(INSTSYSTEMDUNITDIR)/dtprobed.service
diff --git a/dtprobed/dtprobed.c b/dtprobed/dtprobed.c
index fdcdee14f851..c83f0adb56c4 100644
--- a/dtprobed/dtprobed.c
+++ b/dtprobed/dtprobed.c
@@ -61,10 +61,6 @@
 
 #include <dtrace/ioctl.h>
 
-#ifdef HAVE_LIBSYSTEMD
-#include <systemd/sd-daemon.h>
-#endif
-
 #include <dt_list.h>
 #include "dof_parser.h"
 #include "dof_stash.h"
@@ -1073,9 +1069,7 @@ main(int argc, char *argv[])
 		sync_fd = -1;
 	}
 
-#ifdef HAVE_LIBSYSTEMD
-	sd_notify(1, "READY=1");
-#endif
+	systemd_notify("READY=1");
 
 	ret = loop();
 
diff --git a/include/port.h b/include/port.h
index 427129000b4f..6ce8611e9025 100644
--- a/include/port.h
+++ b/include/port.h
@@ -29,6 +29,7 @@ int p_online(int cpun);
 #define MUTEX_HELD(x)	((x)->__data.__count == 0)
 
 int daemonize(int close_fds);
+int systemd_notify(const char *message);
 
 _dt_noreturn_ void daemon_perr(int fd, const char *err, int err_no);
 _dt_printflike_(2, 3) void daemon_log(int fd, const char *fmt, ...);
diff --git a/libport/Build b/libport/Build
index 48ed99e2b017..822049f5e547 100644
--- a/libport/Build
+++ b/libport/Build
@@ -1,5 +1,5 @@
 # Oracle Linux DTrace.
-# Copyright (c) 2011, 2023, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2011, 2024, Oracle and/or its affiliates. All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at
 # http://oss.oracle.com/licenses/upl.
 
@@ -8,7 +8,7 @@ LIBS += libport
 
 libport_TARGET = libport
 libport_DIR := $(current-dir)
-libport_SOURCES = gmatch.c linux_version_code.c strlcat.c strlcpy.c p_online.c time.c daemonize.c
+libport_SOURCES = gmatch.c linux_version_code.c strlcat.c strlcpy.c p_online.c time.c daemonize.c systemd_notify.c
 ifndef HAVE_CLOSE_RANGE
 libport_SOURCES += close_range.c
 endif
diff --git a/libport/systemd_notify.c b/libport/systemd_notify.c
new file mode 100644
index 000000000000..f78bca6e14c5
--- /dev/null
+++ b/libport/systemd_notify.c
@@ -0,0 +1,70 @@
+/* SPDX-License-Identifier: MIT-0 */
+/* Lightly modified from the sd_notify manpage.  */
+
+#include <sys/socket.h>
+#include <sys/un.h>
+#include <errno.h>
+#include <stdlib.h>
+#include <stddef.h>
+#include <string.h>
+#include <unistd.h>
+
+int
+systemd_notify(const char *message)
+{
+	union sockaddr_union {
+		struct sockaddr sa;
+		struct sockaddr_un sun;
+	} socket_addr = {
+		.sun.sun_family = AF_UNIX,
+	};
+
+	size_t path_length, message_length;
+	int fd = -1;
+	const char *socket_path;
+
+	/* Verify the argument first */
+	if (!message)
+		return -EINVAL;
+
+	message_length = strlen(message);
+	if (message_length == 0)
+		return -EINVAL;
+
+	/* If the variable is not set, the protocol is a noop */
+	socket_path = getenv("NOTIFY_SOCKET");
+	if (!socket_path)
+		return 0; /* Not set? Nothing to do */
+
+	/* Only AF_UNIX is supported, with path or abstract sockets */
+	if (socket_path[0] != '/' && socket_path[0] != '@')
+		return -EAFNOSUPPORT;
+
+	path_length = strlen(socket_path);
+	/* Ensure there is room for NUL byte */
+	if (path_length >= sizeof(socket_addr.sun.sun_path))
+		return -E2BIG;
+
+	memcpy(socket_addr.sun.sun_path, socket_path, path_length);
+
+	/* Support for abstract socket */
+	if (socket_addr.sun.sun_path[0] == '@')
+		socket_addr.sun.sun_path[0] = 0;
+
+	fd = socket(AF_UNIX, SOCK_DGRAM|SOCK_CLOEXEC, 0);
+	if (fd < 0)
+		return -errno;
+
+	if (connect(fd, &socket_addr.sa, offsetof(struct sockaddr_un, sun_path) + path_length) != 0) {
+		close(fd);
+		return -errno;
+	}
+
+	ssize_t written = write(fd, message, message_length);
+	if (written != (ssize_t) message_length) {
+		close(fd);
+		return written < 0 ? -errno : -EPROTO;
+	}
+
+	return 1; /* Notified! */
+}
-- 
2.46.0.278.g36e3a12567

Re: [PATCH 01/14] No longer depend on libsystemd

[Kris Van Hees]

On Thu, Oct 24, 2024 at 12:37:45PM +0100, Nick Alcock wrote:
> We only need this for the systemd notification protocol, and that's so
> simple there is MIT-0-licensed reusable code in the sd_notify manpage
> showing you how to use it.  That code looks pretty much OK, so I modified it
> lightly and pulled it into libport, with one tweak to remove the use of
> __attribute__((cleanup)) (it could be replaced by one line of perfectly
> trivial standard C code, saving five or six lines in all).
> 
> With libsystemd linkage gone, we need another way for the user to indicate
> that systemd is not in use and the systemd unit files are not wanted: so
> introduce a new --without-systemd (and corresponding --with-systemd=no,
> etc) in configure.  (Someone directly running make can just pass
> WITH_SYSTEMD= to make.)
> 
> We lose one feature of libsystemd's sd_notify: we no longer remove the
> NOTIFY_SOCKET env var from the environment, so our children could in theory
> pretend to be us and notify systemd on our behalf.  Since our only child
> is in a seccomped jail and is part of dtprobed anyway, this loss of
> functionality is purely theoretical.
> 
> Bug: https://github.com/oracle/dtrace-utils/issues/92
> Signed-off-by: Nick Alcock <nick.alcock@oracle.com>
> ---
>  GNUmakefile              |  1 +
>  Makeconfig               |  1 -
>  configure                |  8 +++--
>  dtprobed/Build           |  7 +---
>  dtprobed/dtprobed.c      |  8 +----
>  include/port.h           |  1 +
>  libport/Build            |  4 +--
>  libport/systemd_notify.c | 70 ++++++++++++++++++++++++++++++++++++++++
>  8 files changed, 82 insertions(+), 18 deletions(-)
>  create mode 100644 libport/systemd_notify.c
> 
> diff --git a/GNUmakefile b/GNUmakefile
> index e7657d466df5..99960227bcba 100644
> --- a/GNUmakefile
> +++ b/GNUmakefile
> @@ -102,6 +102,7 @@ PKGCONFIGDIR = $(prefix)/share/pkgconfig
>  INSTPKGCONFIGDIR = $(DESTDIR)$(PKGCONFIGDIR)
>  TESTDIR = $(LIBDIR)/dtrace/testsuite
>  INSTTESTDIR = $(DESTDIR)$(TESTDIR)
> +WITH_SYSTEMD = true

Why not: WITH_SYSTEMD = y

(since everything else seems to use = y)

>  TARGETS =
>  
>  DTRACE ?= $(objdir)/dtrace
> diff --git a/Makeconfig b/Makeconfig
> index f3d47c086f4a..346078598624 100644
> --- a/Makeconfig
> +++ b/Makeconfig
> @@ -218,7 +218,6 @@ $(eval $(call check-symbol-rule,ELF_GETSHDRSTRNDX,elf_getshdrstrndx,elf))
>  $(eval $(call check-symbol-rule,LIBCTF,ctf_open,ctf,t))
>  $(eval $(call check-symbol-rule,STRRSTR,strrstr,c))
>  $(eval $(call check-symbol-rule,PTHREAD_ATFORK,pthread_atfork,c))
> -$(eval $(call check-symbol-rule,LIBSYSTEMD,sd_notify,systemd,t))
>  ifndef WANTS_LIBFUSE2
>  $(eval $(call check-symbol-rule,FUSE_LOG,fuse_set_log_func,fuse3))
>  $(eval $(call check-symbol-rule,LIBFUSE3,fuse_session_receive_buf,fuse3,t))
> diff --git a/configure b/configure
> index 4026a3eafcd3..42e496b97a7d 100755
> --- a/configure
> +++ b/configure
> @@ -93,9 +93,13 @@ built locally, none of these should be needed):
>  
>  EOF
>  	make help-overrides-header help-overrides-option
> +	cat >&2 <<'EOF'
> +--with-systemd=[yes/no]		Disable installation of the systemd unit files

This makes no sense to me.  How would '--with-systemd' mean that installation
of the systemd unit files is to be disabled?  Surely that is not the correct
description?  Maybe something like: "Enable or disable ..." or
"Specify whether ..."?

> +EOF
>          echo >&2
>          make help-overrides
>  	cat >&2 <<'EOF'
> +
>  Options controlling the compiler (pass on the command line):
>  
>  CC				C compiler (may be a cross-compiler)
> @@ -153,12 +157,12 @@ for option in "$@"; do
>          --kernel-obj-dir=*) write_make_var KERNELOBJDIR "$option";;
>          --kernel-src-suffix=*) write_make_var KERNELSRCNAME "$option";;
>          --kernel-obj-suffix=*) write_make_var KERNELBLDNAME "$option";;
> +        --with-systemd|--with-systemd=yes) write_make_var WITH_SYSTEMD "true";;

"true" -> "y"

> +        --with-systemd=no|--without-systemd) write_make_var WITH_SYSTEMD "";;
>          HAVE_ELF_GETSHDRSTRNDX=*) write_config_var ELF_GETSHDRSTRNDX "$option";;
>          --with-libctf=*) write_config_var LIBCTF "$option";;
>          HAVE_LIBCTF=*) write_config_var LIBCTF "$option";;
>          HAVE_STRRSTR=*) write_config_var STRRSTR "$option";;
> -        --with-libsystemd=*) write_config_var LIBSYSTEMD "$option";;
> -        HAVE_LIBSYSTEMD=*) write_config_var LIBSYSTEMD "$option";;
>          HAVE_FUSE_LOG=*) write_config_var FUSE_LOG "$option";;
>          --with-libfuse3=*) write_config_var LIBFUSE3 "$option";;
>          HAVE_LIBFUSE3=*) write_config_var LIBFUSE3 "$option";;
> diff --git a/dtprobed/Build b/dtprobed/Build
> index 9132c3e31c8a..346cd6aee190 100644
> --- a/dtprobed/Build
> +++ b/dtprobed/Build
> @@ -29,11 +29,6 @@ dtprobed_DEPS := libproc.a libcommon.a libport.a
>  dtprobed_SOURCES := dtprobed.c dof_stash.c seccomp-assistance.c
>  dtprobed_LIBSOURCES := libproc libcommon
>  
> -ifdef HAVE_LIBSYSTEMD
> -dtprobed_CFLAGS += $(shell pkg-config --cflags libsystemd)
> -dtprobed_LIBS += $(shell pkg-config --libs libsystemd)
> -endif
> -
>  ifndef HAVE_FUSE_LOG
>  dtprobed_SOURCES += rpl_fuse_log.c
>  endif
> @@ -43,7 +38,7 @@ seccomp-assistance.c_CFLAGS := -fno-lto
>  endif
>  
>  install-dtprobed-autostart::
> -ifdef HAVE_LIBSYSTEMD
> +ifneq ($(WITH_SYSTEMD),)
>  	mkdir -p $(INSTSYSTEMDUNITDIR) $(INSTSYSTEMDPRESETDIR)
>  	$(call describe-install-target,$(INSTSYSTEMDUNITDIR),dtprobed.service)
>  	sed 's,@SBINDIR@,$(SBINDIR),' < $(dtprobed_DIR)dtprobed.service.in > $(INSTSYSTEMDUNITDIR)/dtprobed.service
> diff --git a/dtprobed/dtprobed.c b/dtprobed/dtprobed.c
> index fdcdee14f851..c83f0adb56c4 100644
> --- a/dtprobed/dtprobed.c
> +++ b/dtprobed/dtprobed.c
> @@ -61,10 +61,6 @@
>  
>  #include <dtrace/ioctl.h>
>  
> -#ifdef HAVE_LIBSYSTEMD
> -#include <systemd/sd-daemon.h>
> -#endif
> -
>  #include <dt_list.h>
>  #include "dof_parser.h"
>  #include "dof_stash.h"
> @@ -1073,9 +1069,7 @@ main(int argc, char *argv[])
>  		sync_fd = -1;
>  	}
>  
> -#ifdef HAVE_LIBSYSTEMD
> -	sd_notify(1, "READY=1");
> -#endif
> +	systemd_notify("READY=1");
>  
>  	ret = loop();
>  
> diff --git a/include/port.h b/include/port.h
> index 427129000b4f..6ce8611e9025 100644
> --- a/include/port.h
> +++ b/include/port.h
> @@ -29,6 +29,7 @@ int p_online(int cpun);
>  #define MUTEX_HELD(x)	((x)->__data.__count == 0)
>  
>  int daemonize(int close_fds);
> +int systemd_notify(const char *message);
>  
>  _dt_noreturn_ void daemon_perr(int fd, const char *err, int err_no);
>  _dt_printflike_(2, 3) void daemon_log(int fd, const char *fmt, ...);
> diff --git a/libport/Build b/libport/Build
> index 48ed99e2b017..822049f5e547 100644
> --- a/libport/Build
> +++ b/libport/Build
> @@ -1,5 +1,5 @@
>  # Oracle Linux DTrace.
> -# Copyright (c) 2011, 2023, Oracle and/or its affiliates. All rights reserved.
> +# Copyright (c) 2011, 2024, Oracle and/or its affiliates. All rights reserved.
>  # Licensed under the Universal Permissive License v 1.0 as shown at
>  # http://oss.oracle.com/licenses/upl.
>  
> @@ -8,7 +8,7 @@ LIBS += libport
>  
>  libport_TARGET = libport
>  libport_DIR := $(current-dir)
> -libport_SOURCES = gmatch.c linux_version_code.c strlcat.c strlcpy.c p_online.c time.c daemonize.c
> +libport_SOURCES = gmatch.c linux_version_code.c strlcat.c strlcpy.c p_online.c time.c daemonize.c systemd_notify.c
>  ifndef HAVE_CLOSE_RANGE
>  libport_SOURCES += close_range.c
>  endif
> diff --git a/libport/systemd_notify.c b/libport/systemd_notify.c
> new file mode 100644
> index 000000000000..f78bca6e14c5
> --- /dev/null
> +++ b/libport/systemd_notify.c
> @@ -0,0 +1,70 @@
> +/* SPDX-License-Identifier: MIT-0 */
> +/* Lightly modified from the sd_notify manpage.  */
> +
> +#include <sys/socket.h>
> +#include <sys/un.h>
> +#include <errno.h>
> +#include <stdlib.h>
> +#include <stddef.h>
> +#include <string.h>
> +#include <unistd.h>
> +
> +int
> +systemd_notify(const char *message)
> +{
> +	union sockaddr_union {
> +		struct sockaddr sa;
> +		struct sockaddr_un sun;
> +	} socket_addr = {
> +		.sun.sun_family = AF_UNIX,
> +	};
> +
> +	size_t path_length, message_length;
> +	int fd = -1;
> +	const char *socket_path;
> +
> +	/* Verify the argument first */
> +	if (!message)
> +		return -EINVAL;
> +
> +	message_length = strlen(message);
> +	if (message_length == 0)
> +		return -EINVAL;
> +
> +	/* If the variable is not set, the protocol is a noop */
> +	socket_path = getenv("NOTIFY_SOCKET");
> +	if (!socket_path)
> +		return 0; /* Not set? Nothing to do */
> +
> +	/* Only AF_UNIX is supported, with path or abstract sockets */
> +	if (socket_path[0] != '/' && socket_path[0] != '@')
> +		return -EAFNOSUPPORT;
> +
> +	path_length = strlen(socket_path);
> +	/* Ensure there is room for NUL byte */
> +	if (path_length >= sizeof(socket_addr.sun.sun_path))
> +		return -E2BIG;
> +
> +	memcpy(socket_addr.sun.sun_path, socket_path, path_length);
> +
> +	/* Support for abstract socket */
> +	if (socket_addr.sun.sun_path[0] == '@')
> +		socket_addr.sun.sun_path[0] = 0;
> +
> +	fd = socket(AF_UNIX, SOCK_DGRAM|SOCK_CLOEXEC, 0);
> +	if (fd < 0)
> +		return -errno;
> +
> +	if (connect(fd, &socket_addr.sa, offsetof(struct sockaddr_un, sun_path) + path_length) != 0) {
> +		close(fd);
> +		return -errno;
> +	}
> +
> +	ssize_t written = write(fd, message, message_length);
> +	if (written != (ssize_t) message_length) {
> +		close(fd);
> +		return written < 0 ? -errno : -EPROTO;
> +	}
> +
> +	return 1; /* Notified! */
> +}
> -- 
> 2.46.0.278.g36e3a12567
> 

Re: [PATCH 01/14] No longer depend on libsystemd

[Nick Alcock]

On 25 Oct 2024, Kris Van Hees stated:
> On Thu, Oct 24, 2024 at 12:37:45PM +0100, Nick Alcock wrote:
>> --- a/GNUmakefile
>> +++ b/GNUmakefile
>> @@ -102,6 +102,7 @@ PKGCONFIGDIR = $(prefix)/share/pkgconfig
>>  INSTPKGCONFIGDIR = $(DESTDIR)$(PKGCONFIGDIR)
>>  TESTDIR = $(LIBDIR)/dtrace/testsuite
>>  INSTTESTDIR = $(DESTDIR)$(TESTDIR)
>> +WITH_SYSTEMD = true
>
> Why not: WITH_SYSTEMD = y
>
> (since everything else seems to use = y)

Fixed (though there is nothing else in GNUmakefile that uses = y, or in
any Build script, so I'm not sure what you're referring to...)

... oh, you mean in the output of Makeconfig. Makes sense, agreed.

>>  TARGETS =
>>  
>>  DTRACE ?= $(objdir)/dtrace
>> diff --git a/Makeconfig b/Makeconfig
>> index f3d47c086f4a..346078598624 100644
>> --- a/Makeconfig
>> +++ b/Makeconfig
>> @@ -218,7 +218,6 @@ $(eval $(call check-symbol-rule,ELF_GETSHDRSTRNDX,elf_getshdrstrndx,elf))
>>  $(eval $(call check-symbol-rule,LIBCTF,ctf_open,ctf,t))
>>  $(eval $(call check-symbol-rule,STRRSTR,strrstr,c))
>>  $(eval $(call check-symbol-rule,PTHREAD_ATFORK,pthread_atfork,c))
>> -$(eval $(call check-symbol-rule,LIBSYSTEMD,sd_notify,systemd,t))
>>  ifndef WANTS_LIBFUSE2
>>  $(eval $(call check-symbol-rule,FUSE_LOG,fuse_set_log_func,fuse3))
>>  $(eval $(call check-symbol-rule,LIBFUSE3,fuse_session_receive_buf,fuse3,t))
>> diff --git a/configure b/configure
>> index 4026a3eafcd3..42e496b97a7d 100755
>> --- a/configure
>> +++ b/configure
>> @@ -93,9 +93,13 @@ built locally, none of these should be needed):
>>  
>>  EOF
>>  	make help-overrides-header help-overrides-option
>> +	cat >&2 <<'EOF'
>> +--with-systemd=[yes/no]		Disable installation of the systemd unit files
>
> This makes no sense to me.  How would '--with-systemd' mean that installation
> of the systemd unit files is to be disabled?  Surely that is not the correct
> description?  Maybe something like: "Enable or disable ..." or
> "Specify whether ..."?

... that's a really stupid description, isn't it! I kept on rephrasing
until I got something that was in <80 and ended up with gibberish.

Simply 'Install the systemd unit files (default: yes)' 45 chars, just
barely fits in 80.

>> +        --with-systemd|--with-systemd=yes) write_make_var WITH_SYSTEMD "true";;
>
> "true" -> "y"

Ack.

I've also arranged that --with-systemd=y* turns it on, and n* turns it
off, entirely so yes and y turn it on, and n and no turn it off :)

-- 
NULL && (void)

[PATCH 02/14] pkgconfig: drop spaces in variable decls

[Nick Alcock]

The requirement to have variable declarations with no spaces in them is not
documented, nor does pkg-config seem to care, but most pkg-config scripts in
the wild conform to it and pkgconf --validate complains.

(pkgconf --validate may also complain about the Version lines. This is a bug
in pkgconf, <https://todo.sr.ht/~kaniini/pkgconf/15>, and should be
ignored.)

Signed-off-by: Nick Alcock <nick.alcock@oracle.com>
Bug: https://github.com/oracle/dtrace-utils/issues/105
---
 uts/dtrace.pc.in     | 6 +++---
 uts/dtrace_sdt.pc.in | 4 ++--
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/uts/dtrace.pc.in b/uts/dtrace.pc.in
index 9977082c5a7c..fda6f755166d 100644
--- a/uts/dtrace.pc.in
+++ b/uts/dtrace.pc.in
@@ -1,6 +1,6 @@
-includedir = @INCLUDEDIR@
-libdir = @LIBDIR@
-dtrace = @DTRACE@
+includedir=@INCLUDEDIR@
+libdir=@LIBDIR@
+dtrace=@DTRACE@
 
 Name: DTrace
 Description: DTrace consumer headers
diff --git a/uts/dtrace_sdt.pc.in b/uts/dtrace_sdt.pc.in
index 32474bc3f75d..90977661b761 100644
--- a/uts/dtrace_sdt.pc.in
+++ b/uts/dtrace_sdt.pc.in
@@ -1,5 +1,5 @@
-sdtincludedir = @SDTINCLUDEDIR@
-dtrace = @DTRACE@
+sdtincludedir=@SDTINCLUDEDIR@
+dtrace=@DTRACE@
 
 Name: DTrace SDT
 Description: DTrace raw SDT headers
-- 
2.46.0.278.g36e3a12567

Re: [PATCH 02/14] pkgconfig: drop spaces in variable decls

[Kris Van Hees]

On Thu, Oct 24, 2024 at 12:37:46PM +0100, Nick Alcock wrote:
> The requirement to have variable declarations with no spaces in them is not
> documented, nor does pkg-config seem to care, but most pkg-config scripts in
> the wild conform to it and pkgconf --validate complains.
> 
> (pkgconf --validate may also complain about the Version lines. This is a bug
> in pkgconf, <https://todo.sr.ht/~kaniini/pkgconf/15>, and should be
> ignored.)
> 
> Signed-off-by: Nick Alcock <nick.alcock@oracle.com>
> Bug: https://github.com/oracle/dtrace-utils/issues/105

Move Bug before Signed-off-by, for clarity and consistency?

Reviewed-by: Kris Van Hees <kris.van.hees@oracle.com>

> ---
>  uts/dtrace.pc.in     | 6 +++---
>  uts/dtrace_sdt.pc.in | 4 ++--
>  2 files changed, 5 insertions(+), 5 deletions(-)
> 
> diff --git a/uts/dtrace.pc.in b/uts/dtrace.pc.in
> index 9977082c5a7c..fda6f755166d 100644
> --- a/uts/dtrace.pc.in
> +++ b/uts/dtrace.pc.in
> @@ -1,6 +1,6 @@
> -includedir = @INCLUDEDIR@
> -libdir = @LIBDIR@
> -dtrace = @DTRACE@
> +includedir=@INCLUDEDIR@
> +libdir=@LIBDIR@
> +dtrace=@DTRACE@
>  
>  Name: DTrace
>  Description: DTrace consumer headers
> diff --git a/uts/dtrace_sdt.pc.in b/uts/dtrace_sdt.pc.in
> index 32474bc3f75d..90977661b761 100644
> --- a/uts/dtrace_sdt.pc.in
> +++ b/uts/dtrace_sdt.pc.in
> @@ -1,5 +1,5 @@
> -sdtincludedir = @SDTINCLUDEDIR@
> -dtrace = @DTRACE@
> +sdtincludedir=@SDTINCLUDEDIR@
> +dtrace=@DTRACE@
>  
>  Name: DTrace SDT
>  Description: DTrace raw SDT headers
> -- 
> 2.46.0.278.g36e3a12567
> 

Re: [PATCH 02/14] pkgconfig: drop spaces in variable decls

[Nick Alcock]

On 25 Oct 2024, Kris Van Hees said:

> On Thu, Oct 24, 2024 at 12:37:46PM +0100, Nick Alcock wrote:
>> The requirement to have variable declarations with no spaces in them is not
>> documented, nor does pkg-config seem to care, but most pkg-config scripts in
>> the wild conform to it and pkgconf --validate complains.
>> 
>> (pkgconf --validate may also complain about the Version lines. This is a bug
>> in pkgconf, <https://todo.sr.ht/~kaniini/pkgconf/15>, and should be
>> ignored.)
>> 
>> Signed-off-by: Nick Alcock <nick.alcock@oracle.com>
>> Bug: https://github.com/oracle/dtrace-utils/issues/105
>
> Move Bug before Signed-off-by, for clarity and consistency?

I kept on oscillating on that. I'll shuffle them all.

> Reviewed-by: Kris Van Hees <kris.van.hees@oracle.com>

Thanks!

[PATCH 03/14] configure, build: make valgrind optional

[Nick Alcock]

We fail building if <valgrind/valgrind.h> is not available, which is
ridiculous given that the only reason we need it is to make valgrind go away
at suitable moments to let us drop uprobes.

A suitable new configure check (using a new check-header-macro-rule
function) lets us check for <valgrind/valgrind.h> and disable it if not
present: as usual, defining HAVE_VALGRIND or passing it to configure will
also suffice to override the check (though since the code this enables
doesn't require any part of valgrind at runtime, I don't see why one would
ever need to do so).

Signed-off-by: Nick Alcock <nick.alcock@oracle.com>
Bug: https://github.com/oracle/dtrace-utils/issues/80
---
 Makeconfig          | 36 ++++++++++++++++++++++++++++++++++++
 configure           |  1 +
 libdtrace/dt_work.c | 18 +++++++++++++++---
 3 files changed, 52 insertions(+), 3 deletions(-)

diff --git a/Makeconfig b/Makeconfig
index 346078598624..752bd79b01fc 100644
--- a/Makeconfig
+++ b/Makeconfig
@@ -163,6 +163,41 @@ $(CONFIG_H): $(objdir)/.config/config.$(1).h
 $(CONFIG_MK): $(objdir)/.config/config.$(1).mk
 endef
 
+# Generate a makefile rule to check for the presence of MACRO
+# in HEADER and emit an appropriate header file fragment into a file
+# under $(objdir)/.config.
+#
+# The first argument must be suitable for a filename fragment,
+# for a makefile rule name and for a #define.
+#
+# Syntax: $(call check-header-macro-rule,name,macro,header)
+define check-header-macro-rule
+$(objdir)/.config/config.$(1).h $(objdir)/.config/config.$(1).mk: $(objdir)/.config/.dir.stamp
+	case x$(HAVE_$(1)) in \
+	xyes) echo '#define HAVE_$(1) 1' > $(objdir)/.config/config.$(1).h; \
+	     echo 'HAVE_$(1)=y' > $(objdir)/.config/config.$(1).mk;; \
+	xno) echo '/* #undef HAVE_$(1) */' > $(objdir)/.config/config.$(1).h; \
+	     echo '# HAVE_$(1) undefined' > $(objdir)/.config/config.$(1).mk;; \
+	*) if printf '#include <%s.h>\n#ifndef %s\n#error %s not found.\n#endif' "$(3)" "$(2)" "$(2)" | \
+	       $(CC) $(filter-out --coverage,$(CFLAGS) $(LDFLAGS)) -Iinclude -D_GNU_SOURCE -Werror=implicit-function-declaration -c -o /dev/null -x c - >/dev/null 2>&1; then \
+	       echo '#define HAVE_$(1) 1' > $(objdir)/.config/config.$(1).h; \
+	       echo 'HAVE_$(1)=y' > $(objdir)/.config/config.$(1).mk; \
+	   else \
+	       echo '/* #undef HAVE_$(1) */' > $(objdir)/.config/config.$(1).h; \
+	       echo '# HAVE_$(1) undefined' > $(objdir)/.config/config.$(1).mk; \
+	   fi;; \
+	*) echo "HAVE_$(1) must be yes or no, not $(HAVE_$(1))" >&2; \
+	   false;; \
+	esac
+	rm -f $(CONFIG_H)
+	rm -f $(CONFIG_MK)
+
+$(eval $(call make-override-help,HAVE_$(1), presence of preprocessor macro $(2) in $(3).h))
+
+$(CONFIG_H): $(objdir)/.config/config.$(1).h
+$(CONFIG_MK): $(objdir)/.config/config.$(1).mk
+endef
+
 # Generate a makefile rule to check for support for OPTION in BPFC and emit an
 # appropriate header file fragment into a file under $(objdir)/.config.
 #
@@ -229,6 +264,7 @@ $(eval $(call check-header-rule,DIS1,disassembler(NULL),disasm))
 $(eval $(call check-header-rule,DIS4,disassembler(0,0,0,NULL),disasm))
 $(eval $(call check-header-rule,INITDISINFO3,init_disassemble_info(NULL,NULL,NULL),disasm))
 $(eval $(call check-header-rule,INITDISINFO4,init_disassemble_info(NULL,NULL,NULL,NULL),disasm))
+$(eval $(call check-header-macro-rule,VALGRIND,VALGRIND_NON_SIMD_CALL0,valgrind/valgrind))
 $(eval $(call check-bpfc-option-rule,BPFV3,-mcpu=v3))
 $(eval $(call check-bpfc-option-rule,BPFMASM,-masm=normal))
 
diff --git a/configure b/configure
index 42e496b97a7d..0c9fb309c494 100755
--- a/configure
+++ b/configure
@@ -169,6 +169,7 @@ for option in "$@"; do
         HAVE_FUSE_NUMA=*) write_config_var FUSE_NUMA "$option";;
         HAVE_CLOSE_RANGE=*) write_config_var CLOSE_RANGE "$option";;
         HAVE_GETTID=*) write_config_var GETTID "$option";;
+        HAVE_VALGRIND=*) write_config_var VALGRIND "$option";;
         HAVE_BPFV3=*) write_config_var BPFV3 "$option";;
         HAVE_BPFMASM=*) write_config_var BPFMASM "$option";;
 	*) echo "Unknown option $option" >&2
diff --git a/libdtrace/dt_work.c b/libdtrace/dt_work.c
index 11335345a6d7..c6de15414481 100644
--- a/libdtrace/dt_work.c
+++ b/libdtrace/dt_work.c
@@ -13,7 +13,9 @@
 #include <port.h>
 #include <linux/perf_event.h>
 #include <sys/epoll.h>
+#ifdef HAVE_VALGRIND
 #include <valgrind/valgrind.h>
+#endif
 #include <dt_impl.h>
 #include <dt_aggregate.h>
 #include <dt_peb.h>
@@ -187,9 +189,11 @@ beginend_child(void *arg) {
 	read(args->tochild[0], &cmd, sizeof(cmd));
 	if (cmd != CMD_BEGIN)
 		exit(1);
-	if (RUNNING_ON_VALGRIND)
+#ifdef HAVE_VALGRIND
+        if (RUNNING_ON_VALGRIND)
 		VALGRIND_NON_SIMD_CALL0(BEGIN_probe);
 	else
+#endif
 		BEGIN_probe();
 	cmd++;
 	write(args->frchild[1], &cmd, sizeof(cmd));
@@ -198,9 +202,11 @@ beginend_child(void *arg) {
 	read(args->tochild[0], &cmd, sizeof(cmd));
 	if (cmd != CMD_END)
 		exit(1);
+#ifdef HAVE_VALGRIND
 	if (RUNNING_ON_VALGRIND)
 		VALGRIND_NON_SIMD_CALL0(END_probe);
 	else
+#endif
 		END_probe();
 	cmd++;
 	write(args->frchild[1], &cmd, sizeof(cmd));
@@ -300,9 +306,12 @@ dtrace_go(dtrace_hdl_t *dtp, uint_t cflags)
 		}
 		if (cmd != CMD_BEGIN + 1)
 			return -1;
-	} else if (RUNNING_ON_VALGRIND)
+	}
+#ifdef HAVE_VALGRIND
+	else if (RUNNING_ON_VALGRIND)
 		VALGRIND_NON_SIMD_CALL0(BEGIN_probe);
 	else
+#endif
 		BEGIN_probe();
 
 	dtp->dt_active = 1;
@@ -344,9 +353,12 @@ dtrace_stop(dtrace_hdl_t *dtp)
 			return -1;
 		pthread_join(args->thr, NULL);
 		dt_free(dtp, args);
-	} else if (RUNNING_ON_VALGRIND)
+	}
+#ifdef HAVE_VALGRIND
+	else if (RUNNING_ON_VALGRIND)
 		VALGRIND_NON_SIMD_CALL0(END_probe);
 	else
+#endif
 		END_probe();
 
 	dtp->dt_stopped = 1;
-- 
2.46.0.278.g36e3a12567

Re: [PATCH 03/14] configure, build: make valgrind optional

[Kris Van Hees]

On Thu, Oct 24, 2024 at 12:37:47PM +0100, Nick Alcock wrote:
> We fail building if <valgrind/valgrind.h> is not available, which is
> ridiculous given that the only reason we need it is to make valgrind go away
> at suitable moments to let us drop uprobes.
> 
> A suitable new configure check (using a new check-header-macro-rule
> function) lets us check for <valgrind/valgrind.h> and disable it if not
> present: as usual, defining HAVE_VALGRIND or passing it to configure will
> also suffice to override the check (though since the code this enables
> doesn't require any part of valgrind at runtime, I don't see why one would
> ever need to do so).

I would remove the final ( ... ) since it is speculative about people's intent.

> Signed-off-by: Nick Alcock <nick.alcock@oracle.com>
> Bug: https://github.com/oracle/dtrace-utils/issues/80

Put Bug: before Signed-off-by:
Indentation issue (see below).

With that fixed...
Reviewed-by: Kris Van Hees <kris.van.hees@oracle.com>

> ---
>  Makeconfig          | 36 ++++++++++++++++++++++++++++++++++++
>  configure           |  1 +
>  libdtrace/dt_work.c | 18 +++++++++++++++---
>  3 files changed, 52 insertions(+), 3 deletions(-)
> 
> diff --git a/Makeconfig b/Makeconfig
> index 346078598624..752bd79b01fc 100644
> --- a/Makeconfig
> +++ b/Makeconfig
> @@ -163,6 +163,41 @@ $(CONFIG_H): $(objdir)/.config/config.$(1).h
>  $(CONFIG_MK): $(objdir)/.config/config.$(1).mk
>  endef
>  
> +# Generate a makefile rule to check for the presence of MACRO
> +# in HEADER and emit an appropriate header file fragment into a file
> +# under $(objdir)/.config.
> +#
> +# The first argument must be suitable for a filename fragment,
> +# for a makefile rule name and for a #define.
> +#
> +# Syntax: $(call check-header-macro-rule,name,macro,header)
> +define check-header-macro-rule
> +$(objdir)/.config/config.$(1).h $(objdir)/.config/config.$(1).mk: $(objdir)/.config/.dir.stamp
> +	case x$(HAVE_$(1)) in \
> +	xyes) echo '#define HAVE_$(1) 1' > $(objdir)/.config/config.$(1).h; \
> +	     echo 'HAVE_$(1)=y' > $(objdir)/.config/config.$(1).mk;; \
> +	xno) echo '/* #undef HAVE_$(1) */' > $(objdir)/.config/config.$(1).h; \
> +	     echo '# HAVE_$(1) undefined' > $(objdir)/.config/config.$(1).mk;; \
> +	*) if printf '#include <%s.h>\n#ifndef %s\n#error %s not found.\n#endif' "$(3)" "$(2)" "$(2)" | \
> +	       $(CC) $(filter-out --coverage,$(CFLAGS) $(LDFLAGS)) -Iinclude -D_GNU_SOURCE -Werror=implicit-function-declaration -c -o /dev/null -x c - >/dev/null 2>&1; then \
> +	       echo '#define HAVE_$(1) 1' > $(objdir)/.config/config.$(1).h; \
> +	       echo 'HAVE_$(1)=y' > $(objdir)/.config/config.$(1).mk; \
> +	   else \
> +	       echo '/* #undef HAVE_$(1) */' > $(objdir)/.config/config.$(1).h; \
> +	       echo '# HAVE_$(1) undefined' > $(objdir)/.config/config.$(1).mk; \
> +	   fi;; \
> +	*) echo "HAVE_$(1) must be yes or no, not $(HAVE_$(1))" >&2; \
> +	   false;; \
> +	esac
> +	rm -f $(CONFIG_H)
> +	rm -f $(CONFIG_MK)
> +
> +$(eval $(call make-override-help,HAVE_$(1), presence of preprocessor macro $(2) in $(3).h))
> +
> +$(CONFIG_H): $(objdir)/.config/config.$(1).h
> +$(CONFIG_MK): $(objdir)/.config/config.$(1).mk
> +endef
> +
>  # Generate a makefile rule to check for support for OPTION in BPFC and emit an
>  # appropriate header file fragment into a file under $(objdir)/.config.
>  #
> @@ -229,6 +264,7 @@ $(eval $(call check-header-rule,DIS1,disassembler(NULL),disasm))
>  $(eval $(call check-header-rule,DIS4,disassembler(0,0,0,NULL),disasm))
>  $(eval $(call check-header-rule,INITDISINFO3,init_disassemble_info(NULL,NULL,NULL),disasm))
>  $(eval $(call check-header-rule,INITDISINFO4,init_disassemble_info(NULL,NULL,NULL,NULL),disasm))
> +$(eval $(call check-header-macro-rule,VALGRIND,VALGRIND_NON_SIMD_CALL0,valgrind/valgrind))
>  $(eval $(call check-bpfc-option-rule,BPFV3,-mcpu=v3))
>  $(eval $(call check-bpfc-option-rule,BPFMASM,-masm=normal))
>  
> diff --git a/configure b/configure
> index 42e496b97a7d..0c9fb309c494 100755
> --- a/configure
> +++ b/configure
> @@ -169,6 +169,7 @@ for option in "$@"; do
>          HAVE_FUSE_NUMA=*) write_config_var FUSE_NUMA "$option";;
>          HAVE_CLOSE_RANGE=*) write_config_var CLOSE_RANGE "$option";;
>          HAVE_GETTID=*) write_config_var GETTID "$option";;
> +        HAVE_VALGRIND=*) write_config_var VALGRIND "$option";;
>          HAVE_BPFV3=*) write_config_var BPFV3 "$option";;
>          HAVE_BPFMASM=*) write_config_var BPFMASM "$option";;
>  	*) echo "Unknown option $option" >&2
> diff --git a/libdtrace/dt_work.c b/libdtrace/dt_work.c
> index 11335345a6d7..c6de15414481 100644
> --- a/libdtrace/dt_work.c
> +++ b/libdtrace/dt_work.c
> @@ -13,7 +13,9 @@
>  #include <port.h>
>  #include <linux/perf_event.h>
>  #include <sys/epoll.h>
> +#ifdef HAVE_VALGRIND
>  #include <valgrind/valgrind.h>
> +#endif
>  #include <dt_impl.h>
>  #include <dt_aggregate.h>
>  #include <dt_peb.h>
> @@ -187,9 +189,11 @@ beginend_child(void *arg) {
>  	read(args->tochild[0], &cmd, sizeof(cmd));
>  	if (cmd != CMD_BEGIN)
>  		exit(1);
> -	if (RUNNING_ON_VALGRIND)
> +#ifdef HAVE_VALGRIND
> +        if (RUNNING_ON_VALGRIND)

Indentation issue (spaces vs tabs).

>  		VALGRIND_NON_SIMD_CALL0(BEGIN_probe);
>  	else
> +#endif
>  		BEGIN_probe();
>  	cmd++;
>  	write(args->frchild[1], &cmd, sizeof(cmd));
> @@ -198,9 +202,11 @@ beginend_child(void *arg) {
>  	read(args->tochild[0], &cmd, sizeof(cmd));
>  	if (cmd != CMD_END)
>  		exit(1);
> +#ifdef HAVE_VALGRIND
>  	if (RUNNING_ON_VALGRIND)
>  		VALGRIND_NON_SIMD_CALL0(END_probe);
>  	else
> +#endif
>  		END_probe();
>  	cmd++;
>  	write(args->frchild[1], &cmd, sizeof(cmd));
> @@ -300,9 +306,12 @@ dtrace_go(dtrace_hdl_t *dtp, uint_t cflags)
>  		}
>  		if (cmd != CMD_BEGIN + 1)
>  			return -1;
> -	} else if (RUNNING_ON_VALGRIND)
> +	}
> +#ifdef HAVE_VALGRIND
> +	else if (RUNNING_ON_VALGRIND)
>  		VALGRIND_NON_SIMD_CALL0(BEGIN_probe);
>  	else
> +#endif
>  		BEGIN_probe();
>  
>  	dtp->dt_active = 1;
> @@ -344,9 +353,12 @@ dtrace_stop(dtrace_hdl_t *dtp)
>  			return -1;
>  		pthread_join(args->thr, NULL);
>  		dt_free(dtp, args);
> -	} else if (RUNNING_ON_VALGRIND)
> +	}
> +#ifdef HAVE_VALGRIND
> +	else if (RUNNING_ON_VALGRIND)
>  		VALGRIND_NON_SIMD_CALL0(END_probe);
>  	else
> +#endif
>  		END_probe();
>  
>  	dtp->dt_stopped = 1;
> -- 
> 2.46.0.278.g36e3a12567
> 

Re: [PATCH 03/14] configure, build: make valgrind optional

[Nick Alcock]

On 25 Oct 2024, Kris Van Hees uttered the following:

> On Thu, Oct 24, 2024 at 12:37:47PM +0100, Nick Alcock wrote:
>> We fail building if <valgrind/valgrind.h> is not available, which is
>> ridiculous given that the only reason we need it is to make valgrind go away
>> at suitable moments to let us drop uprobes.
>> 
>> A suitable new configure check (using a new check-header-macro-rule
>> function) lets us check for <valgrind/valgrind.h> and disable it if not
>> present: as usual, defining HAVE_VALGRIND or passing it to configure will
>> also suffice to override the check (though since the code this enables
>> doesn't require any part of valgrind at runtime, I don't see why one would
>> ever need to do so).
>
> I would remove the final ( ... ) since it is speculative about people's intent.

... what's wrong with speculating about people's intent? But fine, dropped.

>> Signed-off-by: Nick Alcock <nick.alcock@oracle.com>
>> Bug: https://github.com/oracle/dtrace-utils/issues/80
>
> Put Bug: before Signed-off-by:
> Indentation issue (see below).

Ack!

>> -	if (RUNNING_ON_VALGRIND)
>> +#ifdef HAVE_VALGRIND
>> +        if (RUNNING_ON_VALGRIND)
>
> Indentation issue (spaces vs tabs).

GNAH. Fixed series-wide. (And in the other ongoing series, too, which I
managed to forget to adjust before the most recent push.)

-- 
NULL && (void)

[PATCH 04/14] build: substitute LIBDIR in pkg-config files

[Nick Alcock]

/usr/share/pkgconfig/dtrace.pc says

libdir = @LIBDIR@
/* ... */
Libs: -L${libdir} -ldtrace

which is unlikely to work.

Fix by substituting LIBDIR properly.

(I looked at these pkg-config files after installation I don't know how many
times and never once spotted this incredibly obvious problem.)

Signed-off-by: Nick Alcock <nick.alcock@oracle.com>
Bug: https://github.com/oracle/dtrace-utils/issues/104
---
 uts/Build | 1 +
 1 file changed, 1 insertion(+)

diff --git a/uts/Build b/uts/Build
index 181819410624..65ddc39845c1 100644
--- a/uts/Build
+++ b/uts/Build
@@ -37,6 +37,7 @@ install::
 		(cd $(uts_DIR) && \
 		    sed -e 's,@SDTINCLUDEDIR@,$(SDTINCLUDEDIR),g;' \
 			-e 's,@INCLUDEDIR@,$(INCLUDEDIR),g;' \
+			-e 's,@LIBDIR@,$(LIBDIR),g;' \
 			-e 's,@VERSION@,$(VERSION),g;' \
 			-e 's,@DTRACE@,$(SBINDIR)/dtrace,g' < \
 			$${name}.in > $(INSTPKGCONFIGDIR)/$$name;) \
-- 
2.46.0.278.g36e3a12567

Re: [PATCH 04/14] build: substitute LIBDIR in pkg-config files

[Kris Van Hees]

On Thu, Oct 24, 2024 at 12:37:48PM +0100, Nick Alcock wrote:
> /usr/share/pkgconfig/dtrace.pc says
> 
> libdir = @LIBDIR@
> /* ... */
> Libs: -L${libdir} -ldtrace
> 
> which is unlikely to work.
> 
> Fix by substituting LIBDIR properly.
> 
> (I looked at these pkg-config files after installation I don't know how many
> times and never once spotted this incredibly obvious problem.)
> 
> Signed-off-by: Nick Alcock <nick.alcock@oracle.com>
> Bug: https://github.com/oracle/dtrace-utils/issues/104

Bug: before Signed-of-by:.

With that...
Reviewed-by: Kris Van Hees <kris.van.hees@oracle.com>

> ---
>  uts/Build | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/uts/Build b/uts/Build
> index 181819410624..65ddc39845c1 100644
> --- a/uts/Build
> +++ b/uts/Build
> @@ -37,6 +37,7 @@ install::
>  		(cd $(uts_DIR) && \
>  		    sed -e 's,@SDTINCLUDEDIR@,$(SDTINCLUDEDIR),g;' \
>  			-e 's,@INCLUDEDIR@,$(INCLUDEDIR),g;' \
> +			-e 's,@LIBDIR@,$(LIBDIR),g;' \
>  			-e 's,@VERSION@,$(VERSION),g;' \
>  			-e 's,@DTRACE@,$(SBINDIR)/dtrace,g' < \
>  			$${name}.in > $(INSTPKGCONFIGDIR)/$$name;) \
> -- 
> 2.46.0.278.g36e3a12567
> 

[PATCH 05/14] probe: get the size of the hash-lookup key right

[Nick Alcock]

This was allocated with alloca() but then snprintf()ed with a size of
INT_MAX.  This makes _FORTIFY_SOURCE rightly unhappy.

Passing in the size we actually allocated is trivial.

Signed-off-by: Nick Alcock <nick.alcock@oracle.com>
Bug: https://github.com/oracle/dtrace-utils/issues/78
---
 libdtrace/dt_probe.c | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/libdtrace/dt_probe.c b/libdtrace/dt_probe.c
index 686e2a661253..bb1773ee60d4 100644
--- a/libdtrace/dt_probe.c
+++ b/libdtrace/dt_probe.c
@@ -180,9 +180,9 @@ dt_probe_keylen(const dtrace_probedesc_t *pdp)
 }
 
 static char *
-dt_probe_key(const dtrace_probedesc_t *pdp, char *s)
+dt_probe_key(const dtrace_probedesc_t *pdp, char *s, size_t len)
 {
-	snprintf(s, INT_MAX, "%s:%s:%s", pdp->mod, pdp->fun, pdp->prb);
+	snprintf(s, len, "%s:%s:%s", pdp->mod, pdp->fun, pdp->prb);
 	return s;
 }
 
@@ -204,7 +204,7 @@ dt_probe_lookup2(dt_provider_t *pvp, const char *s)
 		return NULL; /* dt_errno is set for us */
 
 	keylen = dt_probe_keylen(&pd);
-	key = dt_probe_key(&pd, alloca(keylen));
+	key = dt_probe_key(&pd, alloca(keylen), keylen);
 
 	/*
 	 * If the probe is already declared, then return the dt_probe_t from
-- 
2.46.0.278.g36e3a12567

Re: [PATCH 05/14] probe: get the size of the hash-lookup key right

[Kris Van Hees]

On Thu, Oct 24, 2024 at 12:37:49PM +0100, Nick Alcock wrote:
> This was allocated with alloca() but then snprintf()ed with a size of
> INT_MAX.  This makes _FORTIFY_SOURCE rightly unhappy.
> 
> Passing in the size we actually allocated is trivial.

Except for the fact that dt_probe_keylen() and dt_probe_key() are only
ever used from dt_probe_lookup2().  So, getting rid of those two functions
and rewriting the call as shown below seems to be a much better fix.

> Signed-off-by: Nick Alcock <nick.alcock@oracle.com>
> Bug: https://github.com/oracle/dtrace-utils/issues/78
> ---
>  libdtrace/dt_probe.c | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/libdtrace/dt_probe.c b/libdtrace/dt_probe.c
> index 686e2a661253..bb1773ee60d4 100644
> --- a/libdtrace/dt_probe.c
> +++ b/libdtrace/dt_probe.c
> @@ -180,9 +180,9 @@ dt_probe_keylen(const dtrace_probedesc_t *pdp)
>  }
>  
>  static char *
> -dt_probe_key(const dtrace_probedesc_t *pdp, char *s)
> +dt_probe_key(const dtrace_probedesc_t *pdp, char *s, size_t len)
>  {
> -	snprintf(s, INT_MAX, "%s:%s:%s", pdp->mod, pdp->fun, pdp->prb);
> +	snprintf(s, len, "%s:%s:%s", pdp->mod, pdp->fun, pdp->prb);
>  	return s;
>  }
>  
> @@ -204,7 +204,7 @@ dt_probe_lookup2(dt_provider_t *pvp, const char *s)
>  		return NULL; /* dt_errno is set for us */
>  
>  	keylen = dt_probe_keylen(&pd);
> -	key = dt_probe_key(&pd, alloca(keylen));
> +	key = dt_probe_key(&pd, alloca(keylen), keylen);

Better would be:
	if (asprintf(&key, "%s:%s:%s", pdp->mod, pdp->fun, pdp->prb) == -1) {
		dt_set_errno(dtp, errno);
		return NULL;
	}

>  
>  	/*
>  	 * If the probe is already declared, then return the dt_probe_t from
> -- 
> 2.46.0.278.g36e3a12567
> 

Re: [PATCH 05/14] probe: get the size of the hash-lookup key right

[Nick Alcock]

On 25 Oct 2024, Kris Van Hees stated:

> On Thu, Oct 24, 2024 at 12:37:49PM +0100, Nick Alcock wrote:
>> This was allocated with alloca() but then snprintf()ed with a size of
>> INT_MAX.  This makes _FORTIFY_SOURCE rightly unhappy.
>> 
>> Passing in the size we actually allocated is trivial.
>
> Except for the fact that dt_probe_keylen() and dt_probe_key() are only
> ever used from dt_probe_lookup2().  So, getting rid of those two functions
> and rewriting the call as shown below seems to be a much better fix.

Yeah. I assumed you wanted to keep the alloca() for some reason, but if
you don't (and it seems to be not incredibly helpful), then I agree.

>> Signed-off-by: Nick Alcock <nick.alcock@oracle.com>
>> Bug: https://github.com/oracle/dtrace-utils/issues/78
>> ---
>>  libdtrace/dt_probe.c | 6 +++---
>>  1 file changed, 3 insertions(+), 3 deletions(-)
>> 
>> diff --git a/libdtrace/dt_probe.c b/libdtrace/dt_probe.c
>> index 686e2a661253..bb1773ee60d4 100644
>> --- a/libdtrace/dt_probe.c
>> +++ b/libdtrace/dt_probe.c
>> @@ -180,9 +180,9 @@ dt_probe_keylen(const dtrace_probedesc_t *pdp)
>>  }
>>  
>>  static char *
>> -dt_probe_key(const dtrace_probedesc_t *pdp, char *s)
>> +dt_probe_key(const dtrace_probedesc_t *pdp, char *s, size_t len)
>>  {
>> -	snprintf(s, INT_MAX, "%s:%s:%s", pdp->mod, pdp->fun, pdp->prb);
>> +	snprintf(s, len, "%s:%s:%s", pdp->mod, pdp->fun, pdp->prb);
>>  	return s;
>>  }
>>  
>> @@ -204,7 +204,7 @@ dt_probe_lookup2(dt_provider_t *pvp, const char *s)
>>  		return NULL; /* dt_errno is set for us */
>>  
>>  	keylen = dt_probe_keylen(&pd);
>> -	key = dt_probe_key(&pd, alloca(keylen));
>> +	key = dt_probe_key(&pd, alloca(keylen), keylen);
>
> Better would be:
> 	if (asprintf(&key, "%s:%s:%s", pdp->mod, pdp->fun, pdp->prb) == -1) {
> 		dt_set_errno(dtp, errno);
> 		return NULL;
> 	}

Went from that into a minor can of worms: the entire function is rusted
kernel-dtrace-era stuff, from a header comment that talks about caching
and interrogation of the kernel that the function never does, through a
probedesc that is always leaked, errno checks that succeed only randomly
(checking errno but no longer doing so after a function that can set
errno on failure, so basically random) which leads to the wrong error
return almost all the time... ... I think my latest version fixes all
those problems (more description in its commit comment, forthcoming).

Any problems in this one will likely be uncovered by the pre-release
valgrind run! but I'll do a full make check before mailing the series
out again anyway.

-- 
NULL && (void)

[PATCH 06/14] configure: fix dreadful behaviour of MANDIR / --mandir

[Nick Alcock]

This should obviously refer to the top-level mandir, i.e. PREFIX/share/man,
not PREFIX/share/man/man8!  Literally no package ever does that, I don't
know what I was thinking...

Signed-off-by: Nick Alcock <nick.alcock@oracle.com>
Bug: https://github.com/oracle/dtrace-utils/issues/106
---
 GNUmakefile | 2 +-
 cmd/Build   | 2 +-
 configure   | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/GNUmakefile b/GNUmakefile
index 99960227bcba..e2c4108fec6f 100644
--- a/GNUmakefile
+++ b/GNUmakefile
@@ -96,7 +96,7 @@ INSTSYSTEMDPRESETDIR = $(DESTDIR)$(SYSTEMDPRESETDIR)
 INSTSYSTEMDUNITDIR = $(DESTDIR)$(SYSTEMDUNITDIR)
 DOCDIR = $(prefix)/share/doc/dtrace-$(VERSION)
 INSTDOCDIR = $(DESTDIR)$(DOCDIR)
-MANDIR = $(prefix)/share/man/man8
+MANDIR = $(prefix)/share/man
 INSTMANDIR = $(DESTDIR)$(MANDIR)
 PKGCONFIGDIR = $(prefix)/share/pkgconfig
 INSTPKGCONFIGDIR = $(DESTDIR)$(PKGCONFIGDIR)
diff --git a/cmd/Build b/cmd/Build
index 68800fbeb5fc..38a538c1e3c9 100644
--- a/cmd/Build
+++ b/cmd/Build
@@ -55,4 +55,4 @@ install::
 	$(call describe-install-target,$(INSTSBINDIR),dtrace)
 	install -m 755 $(objdir)/dtrace $(INSTSBINDIR)
 	$(call describe-install-target,$(INSTMANDIR),dtrace.8)
-	install -m 644 $(dtrace_DIR)/dtrace.8 $(INSTMANDIR)
+	install -m 644 $(dtrace_DIR)/dtrace.8 $(INSTMANDIR)/man8
diff --git a/configure b/configure
index 0c9fb309c494..4ce64efe4ed3 100755
--- a/configure
+++ b/configure
@@ -58,7 +58,7 @@ Installation paths:
 --bindir=PREFIX/sbin				Binary directory
 --sbindir=PREFIX/sbin				Alias for --bindir
 --includedir=PREFIX/include			#include directory
---mandir=PREFIX/share/man/man8			Manpage directory
+--mandir=PREFIX/share/man			Manpage directory
 --pkg-config-dir=PREFIX/share/pkgconfig		Pkg-config directory
 --udevdir=PREFIX/lib/udev/rules.d		udev rules directory
 --systemd-unit-dir=PREFIX/lib/systemd/system	systemd unit directory
-- 
2.46.0.278.g36e3a12567

Re: [PATCH 06/14] configure: fix dreadful behaviour of MANDIR / --mandir

[Kris Van Hees]

On Thu, Oct 24, 2024 at 12:37:50PM +0100, Nick Alcock wrote:
> This should obviously refer to the top-level mandir, i.e. PREFIX/share/man,
> not PREFIX/share/man/man8!  Literally no package ever does that, I don't
> know what I was thinking...
> 
> Signed-off-by: Nick Alcock <nick.alcock@oracle.com>
> Bug: https://github.com/oracle/dtrace-utils/issues/106

Bug: before Signed-off-by:

With that...

Reviewed-by: Kris Van Hees <kris.van.hees@oracle.com>

> ---
>  GNUmakefile | 2 +-
>  cmd/Build   | 2 +-
>  configure   | 2 +-
>  3 files changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/GNUmakefile b/GNUmakefile
> index 99960227bcba..e2c4108fec6f 100644
> --- a/GNUmakefile
> +++ b/GNUmakefile
> @@ -96,7 +96,7 @@ INSTSYSTEMDPRESETDIR = $(DESTDIR)$(SYSTEMDPRESETDIR)
>  INSTSYSTEMDUNITDIR = $(DESTDIR)$(SYSTEMDUNITDIR)
>  DOCDIR = $(prefix)/share/doc/dtrace-$(VERSION)
>  INSTDOCDIR = $(DESTDIR)$(DOCDIR)
> -MANDIR = $(prefix)/share/man/man8
> +MANDIR = $(prefix)/share/man
>  INSTMANDIR = $(DESTDIR)$(MANDIR)
>  PKGCONFIGDIR = $(prefix)/share/pkgconfig
>  INSTPKGCONFIGDIR = $(DESTDIR)$(PKGCONFIGDIR)
> diff --git a/cmd/Build b/cmd/Build
> index 68800fbeb5fc..38a538c1e3c9 100644
> --- a/cmd/Build
> +++ b/cmd/Build
> @@ -55,4 +55,4 @@ install::
>  	$(call describe-install-target,$(INSTSBINDIR),dtrace)
>  	install -m 755 $(objdir)/dtrace $(INSTSBINDIR)
>  	$(call describe-install-target,$(INSTMANDIR),dtrace.8)
> -	install -m 644 $(dtrace_DIR)/dtrace.8 $(INSTMANDIR)
> +	install -m 644 $(dtrace_DIR)/dtrace.8 $(INSTMANDIR)/man8
> diff --git a/configure b/configure
> index 0c9fb309c494..4ce64efe4ed3 100755
> --- a/configure
> +++ b/configure
> @@ -58,7 +58,7 @@ Installation paths:
>  --bindir=PREFIX/sbin				Binary directory
>  --sbindir=PREFIX/sbin				Alias for --bindir
>  --includedir=PREFIX/include			#include directory
> ---mandir=PREFIX/share/man/man8			Manpage directory
> +--mandir=PREFIX/share/man			Manpage directory
>  --pkg-config-dir=PREFIX/share/pkgconfig		Pkg-config directory
>  --udevdir=PREFIX/lib/udev/rules.d		udev rules directory
>  --systemd-unit-dir=PREFIX/lib/systemd/system	systemd unit directory
> -- 
> 2.46.0.278.g36e3a12567
> 

[PATCH 07/14] man: the synopsis is ended with .YS, not .SY

[Nick Alcock]

.SY *starts* the synopsis.

Signed-off-by: Nick Alcock <nick.alcock@oracle.com>
---
 cmd/dtrace.8 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/cmd/dtrace.8 b/cmd/dtrace.8
index 0a1a15304aa1..940ddfc65d1a 100644
--- a/cmd/dtrace.8
+++ b/cmd/dtrace.8
@@ -33,8 +33,8 @@ dtrace \- DTrace dynamic tracing compiler and tracing utility
 .OP \-n [[[provider:]\ module:]\ function:]name\ [[predicate]\ action]
 .br
 .OP \-i probe-id\ [[predicate]\ action]
-.SY
-
+.YS
+.
 .SH DESCRIPTION
 .LP
 DTrace is a comprehensive dynamic tracing framework for the Linux operating system. DTrace provides a powerful infrastructure that permits administrators, developers, and service personnel to concisely answer arbitrary questions about the behavior of the operating system and user programs. 
-- 
2.46.0.278.g36e3a12567

Re: [PATCH 07/14] man: the synopsis is ended with .YS, not .SY

[Kris Van Hees]

On Thu, Oct 24, 2024 at 12:37:51PM +0100, Nick Alcock wrote:
> .SY *starts* the synopsis.
> 
> Signed-off-by: Nick Alcock <nick.alcock@oracle.com>

Reviewed-by: Kris Van Hees <kris.van.hees@oracle.com>

> ---
>  cmd/dtrace.8 | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/cmd/dtrace.8 b/cmd/dtrace.8
> index 0a1a15304aa1..940ddfc65d1a 100644
> --- a/cmd/dtrace.8
> +++ b/cmd/dtrace.8
> @@ -33,8 +33,8 @@ dtrace \- DTrace dynamic tracing compiler and tracing utility
>  .OP \-n [[[provider:]\ module:]\ function:]name\ [[predicate]\ action]
>  .br
>  .OP \-i probe-id\ [[predicate]\ action]
> -.SY
> -
> +.YS
> +.
>  .SH DESCRIPTION
>  .LP
>  DTrace is a comprehensive dynamic tracing framework for the Linux operating system. DTrace provides a powerful infrastructure that permits administrators, developers, and service personnel to concisely answer arbitrary questions about the behavior of the operating system and user programs. 
> -- 
> 2.46.0.278.g36e3a12567
> 

[PATCH 08/14] man: use \- for option dashes, not -

[Nick Alcock]

- is a line-breaking hyphen, almost always wrong for options.  (Its use
prevents the option from working when pasted into some terminal
emulators.)

Signed-off-by: Nick Alcock <nick.alcock@oracle.com>
---
 cmd/dtrace.8 | 116 +++++++++++++++++++++++++--------------------------
 1 file changed, 58 insertions(+), 58 deletions(-)

diff --git a/cmd/dtrace.8 b/cmd/dtrace.8
index 940ddfc65d1a..a53632949e72 100644
--- a/cmd/dtrace.8
+++ b/cmd/dtrace.8
@@ -57,119 +57,119 @@ Options that generate program stability reports
 Options that modify DTrace tracing and buffering behavior and enable additional D compiler features
 .RE
 .LP
-You can use \fBdtrace\fR to create D scripts by using it in a \fB#!\fR declaration to create an interpreter file. You can also use \fBdtrace\fR to attempt to compile D programs and determine their properties without actually enabling tracing using the \fB-e\fR option. See \fBOPTIONS\fR. See the \fIOracle Linux DTrace Guide\fR for detailed examples of how to use the \fBdtrace\fR utility to perform these tasks.
+You can use \fBdtrace\fR to create D scripts by using it in a \fB#!\fR declaration to create an interpreter file. You can also use \fBdtrace\fR to attempt to compile D programs and determine their properties without actually enabling tracing using the \fB\-e\fR option. See \fBOPTIONS\fR. See the \fIOracle Linux DTrace Guide\fR for detailed examples of how to use the \fBdtrace\fR utility to perform these tasks.
 .SH OPTIONS
 .LP
-The arguments accepted by the \fB-P\fR, \fB-m\fR, \fB-f\fR, \fB-n\fR, and \fB-i\fR options can include an optional D language \fIpredicate\fR enclosed in slashes \fB//\fR and optional D language \fIaction\fR statement list enclosed in braces \fB{}\fR. D program code specified on the command line must be appropriately quoted to avoid interpretation of meta-characters by the shell. 
+The arguments accepted by the \fB\-P\fR, \fB\-m\fR, \fB\-f\fR, \fB\-n\fR, and \fB\-i\fR options can include an optional D language \fIpredicate\fR enclosed in slashes \fB//\fR and optional D language \fIaction\fR statement list enclosed in braces \fB{}\fR. D program code specified on the command line must be appropriately quoted to avoid interpretation of meta-characters by the shell.
 .LP
 The following options are supported:
 .TP
-\fB\fB-b\fR \fIbufsz\fR\fR
+\fB\fB\-b\fR \fIbufsz\fR\fR
 Set principal trace buffer size (\fIbufsz\fR). The trace buffer size can include any of the size suffixes \fBk\fR, \fBm\fR, \fBg\fR, or \fBt\fR. If the buffer space cannot be allocated, \fBdtrace\fR attempts to reduce the buffer size or exit depending on the setting of the \fBbufresize\fR property.
 .TP
-\fB\fB-c\fR \fIcmd\fR\fR
-Run the specified command \fIcmd\fR and exit upon its completion. If more than one \fB-c\fR option is present on the command line, \fBdtrace\fR exits when all commands have exited, reporting the exit status for each child process as it terminates. The process-ID of the first command is made available to any D programs specified on the command line or using the \fB-s\fR option through the \fB$target\fR macro variable. Refer to the \fIOracle Linux DTrace Guide\fR for more information on macro variables.
+\fB\fB\-c\fR \fIcmd\fR\fR
+Run the specified command \fIcmd\fR and exit upon its completion. If more than one \fB\-c\fR option is present on the command line, \fBdtrace\fR exits when all commands have exited, reporting the exit status for each child process as it terminates. The process-ID of the first command is made available to any D programs specified on the command line or using the \fB\-s\fR option through the \fB$target\fR macro variable. Refer to the \fIOracle Linux DTrace Guide\fR for more information on macro variables.
 .TP
-\fB\fB-C\fR\fR
-Run the C preprocessor \fBcpp\fR(1) over D programs before compiling them. You can pass options to the C preprocessor using the \fB-D\fR, \fB-U\fR, \fB-I\fR, and \fB-H\fR options. You can select the degree of C standard conformance if you use the \fB-X\fR option. For a description of the set of tokens defined by the D compiler when invoking the C preprocessor, see \fB-X\fR.
+\fB\fB\-C\fR\fR
+Run the C preprocessor \fBcpp\fR(1) over D programs before compiling them. You can pass options to the C preprocessor using the \fB\-D\fR, \fB\-U\fR, \fB\-I\fR, and \fB\-H\fR options. You can select the degree of C standard conformance if you use the \fB\-X\fR option. For a description of the set of tokens defined by the D compiler when invoking the C preprocessor, see \fB\-X\fR.
 .TP
-\fB\fB-D\fR \fIname\fR \fB[=\fR\fIvalue\fR\fB]\fR\fR
-Define \fIname\fR when invoking \fBcpp\fR(1) (enabled using the \fB-C\fR option). If you specify the equals sign (\fB=\fR) and additional \fIvalue\fR, the name is assigned the corresponding value. This option passes the \fB-D\fR option to each \fBcpp\fR invocation.
+\fB\fB\-D\fR \fIname\fR \fB[=\fR\fIvalue\fR\fB]\fR\fR
+Define \fIname\fR when invoking \fBcpp\fR(1) (enabled using the \fB\-C\fR option). If you specify the equals sign (\fB=\fR) and additional \fIvalue\fR, the name is assigned the corresponding value. This option passes the \fB\-D\fR option to each \fBcpp\fR invocation.
 .TP
-\fB\fB-e\fR\fR
+\fB\fB\-e\fR\fR
 Exit after compiling any requests, but prior to enabling any probes. You can combine this option with D compiler options. This combination verifies that the programs compile without actually executing them and enabling the corresponding instrumentation.
 .TP
-\fB\fB-f\fR\fB[[\fR\fIprovider\fR\fB:]\fR\fImodule\fR\fB:]\fR\fIfunction\fR\fB[[\fR\fIpredicate\fR\fB]\fR\fIaction\fR\fB]]\fR\fR
-Specify function name to trace or list (\fB-l\fR option). The corresponding argument can include any of the probe description forms \fIprovider:module:function\fR, \fImodule:function\fR, or \fIfunction\fR. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fIfunction\fR are specified in the description, all probes with the corresponding \fIfunction\fR are matched. The \fB-f\fR argument can be suffixed with an optional D probe clause. You can specify more than one \fB-f\fR option on the command line at a time.
+\fB\fB\-f\fR\fB[[\fR\fIprovider\fR\fB:]\fR\fImodule\fR\fB:]\fR\fIfunction\fR\fB[[\fR\fIpredicate\fR\fB]\fR\fIaction\fR\fB]]\fR\fR
+Specify function name to trace or list (\fB\-l\fR option). The corresponding argument can include any of the probe description forms \fIprovider:module:function\fR, \fImodule:function\fR, or \fIfunction\fR. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fIfunction\fR are specified in the description, all probes with the corresponding \fIfunction\fR are matched. The \fB\-f\fR argument can be suffixed with an optional D probe clause. You can specify more than one \fB\-f\fR option on the command line at a time.
 .TP
-\fB\fB-F\fR\fR
+\fB\fB\-F\fR\fR
 Coalesce trace output by identifying function entry and return. Function entry probe reports are indented and their output is prefixed with \fB->\fR. Function return probe reports are unindented and their output is prefixed with \fB<-\fR\&. System call entry probe reports are indented and their output is prefixed with \fB=>\fR. System call return probe reports are unindented and their output is prefixed with \fB<=\fR\&.
 .TP
-\fB\fB-G\fR\fR
-Generate an ELF file containing an embedded DTrace program. The DTrace probes specified in the program are saved inside of a relocatable ELF object which can be linked into another program. If the \fB-o\fR option is present, the ELF file is saved using the pathname specified as the argument for this operand. If the \fB-o\fR option is not present and the DTrace program is contained with a file whose name is \fB\fIfilename\fR.d\fR, then the ELF file is saved using the name \fB\fIfilename\fR.o\fR. Otherwise the ELF file is saved using the name \fBd.out\fR.
+\fB\fB\-G\fR\fR
+Generate an ELF file containing an embedded DTrace program. The DTrace probes specified in the program are saved inside of a relocatable ELF object which can be linked into another program. If the \fB\-o\fR option is present, the ELF file is saved using the pathname specified as the argument for this operand. If the \fB\-o\fR option is not present and the DTrace program is contained with a file whose name is \fB\fIfilename\fR.d\fR, then the ELF file is saved using the name \fB\fIfilename\fR.o\fR. Otherwise the ELF file is saved using the name \fBd.out\fR.
 .TP
-\fB\fB-H\fR\fR
-Print the pathnames of included files when invoking \fBcpp\fR(1) (enabled using the \fB-C\fR option). This option passes the \fB-H\fR option to each \fBcpp\fR invocation, causing it to display the list of pathnames, one for each line, to \fBstderr\fR.
+\fB\fB\-H\fR\fR
+Print the pathnames of included files when invoking \fBcpp\fR(1) (enabled using the \fB\-C\fR option). This option passes the \fB\-H\fR option to each \fBcpp\fR invocation, causing it to display the list of pathnames, one for each line, to \fBstderr\fR.
 .TP
-\fB\fB-h\fR\fR
-Generate a header file containing macros that correspond to probes in the specified provider definitions. This option should be used to generate a header file that is included by other source files for later use with the \fB-G\fR option. If the \fB-o\fR option is present, the header file is saved using the pathname specified as the argument for that option. If the \fB-o\fR option is not present and the DTrace program is contained with a file whose name is \fIfilename\fR\fB\&.d\fR, then the header file is saved using the name \fIfilename\fR\fB\&.h\fR.
+\fB\fB\-h\fR\fR
+Generate a header file containing macros that correspond to probes in the specified provider definitions. This option should be used to generate a header file that is included by other source files for later use with the \fB\-G\fR option. If the \fB\-o\fR option is present, the header file is saved using the pathname specified as the argument for that option. If the \fB\-o\fR option is not present and the DTrace program is contained with a file whose name is \fIfilename\fR\fB\&.d\fR, then the header file is saved using the name \fIfilename\fR\fB\&.h\fR.
 .TP
-\fB\fB-i\fR \fIprobe-id\fR\fB[[\fR\fIpredicate\fR] \fIaction\fR\fB]\fR\fR
-Specify probe identifier (\fIprobe-id\fR) to trace or list (\fB-l\fR option). You can specify probe IDs using decimal integers as shown by \fBdtrace\fR \fB-l\fR. The \fB-i\fR argument can be suffixed with an optional D probe clause. You can specify more than one \fB-i\fR option at a time.
+\fB\fB\-i\fR \fIprobe-id\fR\fB[[\fR\fIpredicate\fR] \fIaction\fR\fB]\fR\fR
+Specify probe identifier (\fIprobe-id\fR) to trace or list (\fB\-l\fR option). You can specify probe IDs using decimal integers as shown by \fBdtrace\fR \fB\-l\fR. The \fB\-i\fR argument can be suffixed with an optional D probe clause. You can specify more than one \fB\-i\fR option at a time.
 .TP
-\fB\fB-I\fR \fIpath\fR\fR
-Add the specified directory \fIpath\fR to the search path for \fB#include\fR files when invoking \fBcpp\fR(1) (enabled using the \fB-C\fR option). This option passes the \fB-I\fR option to each \fBcpp\fR invocation. The specified \fIpath\fR is inserted into the search path ahead of the default directory list.
+\fB\fB\-I\fR \fIpath\fR\fR
+Add the specified directory \fIpath\fR to the search path for \fB#include\fR files when invoking \fBcpp\fR(1) (enabled using the \fB\-C\fR option). This option passes the \fB\-I\fR option to each \fBcpp\fR invocation. The specified \fIpath\fR is inserted into the search path ahead of the default directory list.
 .TP
-\fB\fB-L\fR \fIpath\fR\fR
+\fB\fB\-L\fR \fIpath\fR\fR
 Add the specified directory \fIpath\fR to the search path for DTrace libraries. DTrace libraries are used to contain common definitions that can be used when writing D programs. The specified \fIpath\fR is added after the default library search path. If it exists, a subdirectory of \fIpath\fR named after the minor version of the running kernel (e.g. 3.8) is searched immediately before \fIpath\fR. (But take note: dependency analysis is performed only within each directory, not across directories.)
 .TP
-\fB\fB-l\fR\fR
-List probes instead of enabling them. If the \fB-l\fR option is specified, \fBdtrace\fR produces a report of the probes matching the descriptions given using the \fB-P\fR, \fB-m\fR, \fB-f\fR, \fB-n\fR, \fB-i\fR, and \fB-s\fR options. If none of these options are specified, this option lists all probes.
+\fB\fB\-l\fR\fR
+List probes instead of enabling them. If the \fB\-l\fR option is specified, \fBdtrace\fR produces a report of the probes matching the descriptions given using the \fB\-P\fR, \fB\-m\fR, \fB\-f\fR, \fB\-n\fR, \fB\-i\fR, and \fB\-s\fR options. If none of these options are specified, this option lists all probes.
 .TP
-\fB\fB-m\fR [[\fIprovider:\fR] \fImodule:\fR [[\fIpredicate\fR] \fIaction\fR]]\fR
-Specify module name to trace or list (\fB-l\fR option). The corresponding argument can include any of the probe description forms \fIprovider:module\fR or \fImodule\fR. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fImodule\fR are specified in the description, all probes with a corresponding \fImodule\fR are matched. The \fB-m\fR argument can be suffixed with an optional D probe clause. More than one \fB-m\fR option can be specified on the command line at a time.
+\fB\fB\-m\fR [[\fIprovider:\fR] \fImodule:\fR [[\fIpredicate\fR] \fIaction\fR]]\fR
+Specify module name to trace or list (\fB\-l\fR option). The corresponding argument can include any of the probe description forms \fIprovider:module\fR or \fImodule\fR. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fImodule\fR are specified in the description, all probes with a corresponding \fImodule\fR are matched. The \fB\-m\fR argument can be suffixed with an optional D probe clause. More than one \fB\-m\fR option can be specified on the command line at a time.
 .TP
-\fB\fB-n\fR [[[\fIprovider:\fR] \fImodule:\fR] \fIfunction:\fR] \fIname\fR [[\fIpredicate\fR] \fIaction\fR]\fR
-Specify probe name to trace or list (\fB-l\fR option). The corresponding argument can include any of the probe description forms \fIprovider:module:function:name\fR, \fImodule:function:name\fR, \fIfunction:name\fR, or \fIname\fR. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fIname\fR are specified in the description, all probes with a corresponding \fIname\fR are matched. The \fB-n\fR argument can be suffixed with an optional D probe clause. More than one \fB-n\fR option can be specified on the command line at a time.
+\fB\fB\-n\fR [[[\fIprovider:\fR] \fImodule:\fR] \fIfunction:\fR] \fIname\fR [[\fIpredicate\fR] \fIaction\fR]\fR
+Specify probe name to trace or list (\fB\-l\fR option). The corresponding argument can include any of the probe description forms \fIprovider:module:function:name\fR, \fImodule:function:name\fR, \fIfunction:name\fR, or \fIname\fR. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fIname\fR are specified in the description, all probes with a corresponding \fIname\fR are matched. The \fB\-n\fR argument can be suffixed with an optional D probe clause. More than one \fB\-n\fR option can be specified on the command line at a time.
 .TP
-\fB\fB-o\fR \fIoutput\fR\fR
-Specify the \fIoutput\fR file for the \fB-G\fR, \fB-h\fR, and \fB-l\fR options, or for the traced data itself. If the \fB-G\fR option is present and the \fB-s\fR option's argument is of the form \fB\fIfilename\fR.d\fR and \fB-o\fR is not present, the default output file is \fB\fIfilename\fR.o\fR. Otherwise the default output file is \fBd.out\fR.
+\fB\fB\-o\fR \fIoutput\fR\fR
+Specify the \fIoutput\fR file for the \fB\-G\fR, \fB\-h\fR, and \fB\-l\fR options, or for the traced data itself. If the \fB\-G\fR option is present and the \fB\-s\fR option's argument is of the form \fB\fIfilename\fR.d\fR and \fB\-o\fR is not present, the default output file is \fB\fIfilename\fR.o\fR. Otherwise the default output file is \fBd.out\fR.
 .TP
-\fB\fB-p\fR \fIpid\fR\fR
-Grab the specified process-ID \fIpid\fR, cache its symbol tables, and exit upon its completion. If more than one \fB-p\fR option is present on the command line, \fBdtrace\fR exits when all commands have exited, reporting the exit status for each process as it terminates. The first process-ID is made available to any D programs specified on the command line or using the \fB-s\fR option through the \fB$target\fR macro variable. Refer to the \fIOracle Linux DTrace Guide\fR for more information on macro variables.
+\fB\fB\-p\fR \fIpid\fR\fR
+Grab the specified process-ID \fIpid\fR, cache its symbol tables, and exit upon its completion. If more than one \fB\-p\fR option is present on the command line, \fBdtrace\fR exits when all commands have exited, reporting the exit status for each process as it terminates. The first process-ID is made available to any D programs specified on the command line or using the \fB\-s\fR option through the \fB$target\fR macro variable. Refer to the \fIOracle Linux DTrace Guide\fR for more information on macro variables.
 .TP
-\fB\fB-P\fR \fIprovider\fR \fB[[\fR\fIpredicate\fR\fB]\fR \fIaction\fR]\fR
-Specify provider name to trace or list (\fB-l\fR option). The remaining probe description fields module, function, and name are left blank and match any probes regardless of the values in those fields. The \fB-P\fR argument can be suffixed with an optional D probe clause. You can specify more than one \fB-P\fR option on the command line at a time.
+\fB\fB\-P\fR \fIprovider\fR \fB[[\fR\fIpredicate\fR\fB]\fR \fIaction\fR]\fR
+Specify provider name to trace or list (\fB\-l\fR option). The remaining probe description fields module, function, and name are left blank and match any probes regardless of the values in those fields. The \fB\-P\fR argument can be suffixed with an optional D probe clause. You can specify more than one \fB\-P\fR option on the command line at a time.
 .TP
-\fB\fB-q\fR\fR
+\fB\fB\-q\fR\fR
 Set quiet mode. \fBdtrace\fR suppresses messages such as the number of probes matched by the specified options and D programs and does not print column headers, the CPU ID, the probe ID, or insert newlines into the output. Only data traced and formatted by D program statements such as \fBtrace()\fR and \fBprintf()\fR is displayed to \fBstdout\fR.
 .TP
-\fB\fB-s\fR\fR
-Compile the specified D program source file. If the \fB-e\fR option is present, the program is compiled but instrumentation is not enabled. If the \fB-l\fR option is present, the program is compiled and the set of probes matched by it is listed, but instrumentation is not enabled. If none of \fB-e\fR, \fB-l\fR, or \fB-G\fR are present, the instrumentation specified by the D program is enabled and tracing begins.
+\fB\fB\-s\fR\fR
+Compile the specified D program source file. If the \fB\-e\fR option is present, the program is compiled but instrumentation is not enabled. If the \fB\-l\fR option is present, the program is compiled and the set of probes matched by it is listed, but instrumentation is not enabled. If none of \fB\-e\fR, \fB\-l\fR, or \fB\-G\fR are present, the instrumentation specified by the D program is enabled and tracing begins.
 .TP
-\fB\fB-S\fR\fR
+\fB\fB\-S\fR\fR
 Show D compiler intermediate code. The D compiler produces a report of the intermediate code generated for each D program to \fBstderr\fR.
 .TP
-\fB\fB-U\fR \fIname\fR\fR
+\fB\fB\-U\fR \fIname\fR\fR
 Undefine the specified \fIname\fR when invoking \fBcpp\fR(1) (enabled using the \fB-C\fR option). This option passes the \fB-U\fR option to each \fBcpp\fR invocation.
 .TP
-\fB\fB-v\fR\fR
-Set verbose mode. If the \fB-v\fR option is specified, \fBdtrace\fR produces a program stability report showing the minimum interface stability and dependency level for the specified D programs. DTrace stability levels are explained in further detail in the \fIOracle Linux DTrace Guide\fR.
+\fB\fB\-v\fR\fR
+Set verbose mode. If the \fB\-v\fR option is specified, \fBdtrace\fR produces a program stability report showing the minimum interface stability and dependency level for the specified D programs. DTrace stability levels are explained in further detail in the \fIOracle Linux DTrace Guide\fR.
 .TP
-\fB\fB-V\fR\fR
-Report the highest D programming interface version supported by \fBdtrace\fR. The version information is printed to \fBstdout\fR and the \fBdtrace\fR command exits. Refer to the \fIOracle Linux DTrace Guide\fR for more information about DTrace versioning features. In conjunction with \fB-v\fR, also reports information on the version of the \fBdtrace\fR(1) tool and associated library.
+\fB\fB\-V\fR\fR
+Report the highest D programming interface version supported by \fBdtrace\fR. The version information is printed to \fBstdout\fR and the \fBdtrace\fR command exits. Refer to the \fIOracle Linux DTrace Guide\fR for more information about DTrace versioning features. In conjunction with \fB\-v\fR, also reports information on the version of the \fBdtrace\fR(1) tool and associated library.
 .TP
-\fB\fB-w\fR\fR
-Permit destructive actions in D programs specified using the \fB-s\fR, \fB-P\fR, \fB-m\fR, \fB-f\fR, \fB-n\fR, or \fB-i\fR options. If the \fB-w\fR option is not specified, \fBdtrace\fR does not permit the compilation or enabling of a D program that contains destructive actions.
+\fB\fB\-w\fR\fR
+Permit destructive actions in D programs specified using the \fB\-s\fR, \fB\-P\fR, \fB\-m\fR, \fB\-f\fR, \fB\-n\fR, or \fB\-i\fR options. If the \fB\-w\fR option is not specified, \fBdtrace\fR does not permit the compilation or enabling of a D program that contains destructive actions.
 .TP
-\fB\fB-x\fR \fIarg\fR [\fI=val\fR]\fR
+\fB\fB\-x\fR \fIarg\fR [\fI=val\fR]\fR
 Enable or modify a DTrace runtime option or D compiler option. The list of options is found in the \fIOracle Linux DTrace Guide\fR. Boolean options are enabled by specifying their name. Options with values are set by separating the option name and value with an equals sign (\fB=\fR).
 .TP
-\fB\fB-Z\fR\fR
-Permit probe descriptions that match zero probes. If the \fB-Z\fR option is not specified, \fBdtrace\fR reports an error and exits if any probe descriptions specified in D program files (\fB-s\fR option) or on the command line (\fB-P\fR, \fB-m\fR, \fB-f\fR, \fB-n\fR, or \fB-i\fR options) contain descriptions that do not match any known probes.
-
+\fB\fB\-Z\fR\fR
+Permit probe descriptions that match zero probes. If the \fB\-Z\fR option is not specified, \fBdtrace\fR reports an error and exits if any probe descriptions specified in D program files (\fB\-s\fR option) or on the command line (\fB\-P\fR, \fB\-m\fR, \fB\-f\fR, \fB\-n\fR, or \fB\-i\fR options) contain descriptions that do not match any known probes.
+.
 .SH OPERANDS
 .LP
-You can specify zero or more additional arguments on the \fBdtrace\fR command line to define a set of macro variables (\fB$1\fR, \fB$2\fR, and so forth). The additional arguments can be used in D programs specified using the \fB-s\fR option or on the command line. The use of macro variables is described further in the \fIOracle Linux DTrace Guide\fR.
-
+You can specify zero or more additional arguments on the \fBdtrace\fR command line to define a set of macro variables (\fB$1\fR, \fB$2\fR, and so forth). The additional arguments can be used in D programs specified using the \fB\-s\fR option or on the command line. The use of macro variables is described further in the \fIOracle Linux DTrace Guide\fR.
+.
 .SH EXIT STATUS
 .LP
 The following exit values are returned:
 .TP
 .B 0
 Successful completion. 
-
+.IP
 For D program requests, an exit status of \fB0\fR indicates that programs were successfully compiled, probes were successfully enabled, or anonymous state was successfully retrieved. \fBdtrace\fR returns \fB0\fR even if the specified tracing requests encountered errors or drops.
 .TP
 .B 1
 An error occurred.
-
+.IP
 For D program requests, an exit status of \fB1\fR indicates that program compilation failed or that the specified request could not be satisfied.
 .TP
 .B 2
 Invalid command line options or arguments were specified.
 .\" .RE
-
+.
 .SH "ENVIRONMENT VARIABLES"
 .LP
 The following environment variables are consulted:
@@ -180,7 +180,7 @@ Print CTF type library debugging output on standard error.
 .IP DTRACE_OPT_*
 Set a given DTrace option.
 
-Options set this way are overridden both by options specified via \fB-x\fR on the command line, and by \fBsetopt\fR statements.
+Options set this way are overridden both by options specified via \fB\-x\fR on the command line, and by \fBsetopt\fR statements.
 
 .SH SEE ALSO
 .BR cpp (1),
@@ -190,4 +190,4 @@ Options set this way are overridden both by options specified via \fB-x\fR on th
 
 .SH USAGE
 .LP
-When using the \fB-p\fR flag, \fBdtrace\fR stops the target processes while it is inspecting them and reporting results. A process can do nothing while it is stopped. This means that, if , for example, the X server is inspected by \fBdtrace\fR running in a window under the X server's control, the whole window system can become deadlocked, because the \fBdtrace\fR tool would be attempting to display its results to a window that cannot be refreshed. In such a case, logging in from another system using \fBssh\fR(1) and killing the offending \fBdtrace\fR tool clears the deadlock.
+When using the \fB\-p\fR flag, \fBdtrace\fR stops the target processes while it is inspecting them and reporting results. A process can do nothing while it is stopped. This means that, if, for example, the X server is inspected by \fBdtrace\fR running in a window under the X server's control, the whole window system can become deadlocked, because the \fBdtrace\fR tool would be attempting to display its results to a window that cannot be refreshed. In such a case, logging in from another system using \fBssh\fR(1) and killing the offending \fBdtrace\fR tool clears the deadlock.
-- 
2.46.0.278.g36e3a12567

Re: [PATCH 08/14] man: use \- for option dashes, not -

[Kris Van Hees]

On Thu, Oct 24, 2024 at 12:37:52PM +0100, Nick Alcock wrote:
> - is a line-breaking hyphen, almost always wrong for options.  (Its use
> prevents the option from working when pasted into some terminal
> emulators.)
> 
> Signed-off-by: Nick Alcock <nick.alcock@oracle.com>

Reviewed-by: Kris Van Hees <kris.van.hees@oracle.com>

> ---
>  cmd/dtrace.8 | 116 +++++++++++++++++++++++++--------------------------
>  1 file changed, 58 insertions(+), 58 deletions(-)
> 
> diff --git a/cmd/dtrace.8 b/cmd/dtrace.8
> index 940ddfc65d1a..a53632949e72 100644
> --- a/cmd/dtrace.8
> +++ b/cmd/dtrace.8
> @@ -57,119 +57,119 @@ Options that generate program stability reports
>  Options that modify DTrace tracing and buffering behavior and enable additional D compiler features
>  .RE
>  .LP
> -You can use \fBdtrace\fR to create D scripts by using it in a \fB#!\fR declaration to create an interpreter file. You can also use \fBdtrace\fR to attempt to compile D programs and determine their properties without actually enabling tracing using the \fB-e\fR option. See \fBOPTIONS\fR. See the \fIOracle Linux DTrace Guide\fR for detailed examples of how to use the \fBdtrace\fR utility to perform these tasks.
> +You can use \fBdtrace\fR to create D scripts by using it in a \fB#!\fR declaration to create an interpreter file. You can also use \fBdtrace\fR to attempt to compile D programs and determine their properties without actually enabling tracing using the \fB\-e\fR option. See \fBOPTIONS\fR. See the \fIOracle Linux DTrace Guide\fR for detailed examples of how to use the \fBdtrace\fR utility to perform these tasks.
>  .SH OPTIONS
>  .LP
> -The arguments accepted by the \fB-P\fR, \fB-m\fR, \fB-f\fR, \fB-n\fR, and \fB-i\fR options can include an optional D language \fIpredicate\fR enclosed in slashes \fB//\fR and optional D language \fIaction\fR statement list enclosed in braces \fB{}\fR. D program code specified on the command line must be appropriately quoted to avoid interpretation of meta-characters by the shell. 
> +The arguments accepted by the \fB\-P\fR, \fB\-m\fR, \fB\-f\fR, \fB\-n\fR, and \fB\-i\fR options can include an optional D language \fIpredicate\fR enclosed in slashes \fB//\fR and optional D language \fIaction\fR statement list enclosed in braces \fB{}\fR. D program code specified on the command line must be appropriately quoted to avoid interpretation of meta-characters by the shell.
>  .LP
>  The following options are supported:
>  .TP
> -\fB\fB-b\fR \fIbufsz\fR\fR
> +\fB\fB\-b\fR \fIbufsz\fR\fR
>  Set principal trace buffer size (\fIbufsz\fR). The trace buffer size can include any of the size suffixes \fBk\fR, \fBm\fR, \fBg\fR, or \fBt\fR. If the buffer space cannot be allocated, \fBdtrace\fR attempts to reduce the buffer size or exit depending on the setting of the \fBbufresize\fR property.
>  .TP
> -\fB\fB-c\fR \fIcmd\fR\fR
> -Run the specified command \fIcmd\fR and exit upon its completion. If more than one \fB-c\fR option is present on the command line, \fBdtrace\fR exits when all commands have exited, reporting the exit status for each child process as it terminates. The process-ID of the first command is made available to any D programs specified on the command line or using the \fB-s\fR option through the \fB$target\fR macro variable. Refer to the \fIOracle Linux DTrace Guide\fR for more information on macro variables.
> +\fB\fB\-c\fR \fIcmd\fR\fR
> +Run the specified command \fIcmd\fR and exit upon its completion. If more than one \fB\-c\fR option is present on the command line, \fBdtrace\fR exits when all commands have exited, reporting the exit status for each child process as it terminates. The process-ID of the first command is made available to any D programs specified on the command line or using the \fB\-s\fR option through the \fB$target\fR macro variable. Refer to the \fIOracle Linux DTrace Guide\fR for more information on macro variables.
>  .TP
> -\fB\fB-C\fR\fR
> -Run the C preprocessor \fBcpp\fR(1) over D programs before compiling them. You can pass options to the C preprocessor using the \fB-D\fR, \fB-U\fR, \fB-I\fR, and \fB-H\fR options. You can select the degree of C standard conformance if you use the \fB-X\fR option. For a description of the set of tokens defined by the D compiler when invoking the C preprocessor, see \fB-X\fR.
> +\fB\fB\-C\fR\fR
> +Run the C preprocessor \fBcpp\fR(1) over D programs before compiling them. You can pass options to the C preprocessor using the \fB\-D\fR, \fB\-U\fR, \fB\-I\fR, and \fB\-H\fR options. You can select the degree of C standard conformance if you use the \fB\-X\fR option. For a description of the set of tokens defined by the D compiler when invoking the C preprocessor, see \fB\-X\fR.
>  .TP
> -\fB\fB-D\fR \fIname\fR \fB[=\fR\fIvalue\fR\fB]\fR\fR
> -Define \fIname\fR when invoking \fBcpp\fR(1) (enabled using the \fB-C\fR option). If you specify the equals sign (\fB=\fR) and additional \fIvalue\fR, the name is assigned the corresponding value. This option passes the \fB-D\fR option to each \fBcpp\fR invocation.
> +\fB\fB\-D\fR \fIname\fR \fB[=\fR\fIvalue\fR\fB]\fR\fR
> +Define \fIname\fR when invoking \fBcpp\fR(1) (enabled using the \fB\-C\fR option). If you specify the equals sign (\fB=\fR) and additional \fIvalue\fR, the name is assigned the corresponding value. This option passes the \fB\-D\fR option to each \fBcpp\fR invocation.
>  .TP
> -\fB\fB-e\fR\fR
> +\fB\fB\-e\fR\fR
>  Exit after compiling any requests, but prior to enabling any probes. You can combine this option with D compiler options. This combination verifies that the programs compile without actually executing them and enabling the corresponding instrumentation.
>  .TP
> -\fB\fB-f\fR\fB[[\fR\fIprovider\fR\fB:]\fR\fImodule\fR\fB:]\fR\fIfunction\fR\fB[[\fR\fIpredicate\fR\fB]\fR\fIaction\fR\fB]]\fR\fR
> -Specify function name to trace or list (\fB-l\fR option). The corresponding argument can include any of the probe description forms \fIprovider:module:function\fR, \fImodule:function\fR, or \fIfunction\fR. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fIfunction\fR are specified in the description, all probes with the corresponding \fIfunction\fR are matched. The \fB-f\fR argument can be suffixed with an optional D probe clause. You can specify more than one \fB-f\fR option on the command line at a time.
> +\fB\fB\-f\fR\fB[[\fR\fIprovider\fR\fB:]\fR\fImodule\fR\fB:]\fR\fIfunction\fR\fB[[\fR\fIpredicate\fR\fB]\fR\fIaction\fR\fB]]\fR\fR
> +Specify function name to trace or list (\fB\-l\fR option). The corresponding argument can include any of the probe description forms \fIprovider:module:function\fR, \fImodule:function\fR, or \fIfunction\fR. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fIfunction\fR are specified in the description, all probes with the corresponding \fIfunction\fR are matched. The \fB\-f\fR argument can be suffixed with an optional D probe clause. You can specify more than one \fB\-f\fR option on the command line at a time.
>  .TP
> -\fB\fB-F\fR\fR
> +\fB\fB\-F\fR\fR
>  Coalesce trace output by identifying function entry and return. Function entry probe reports are indented and their output is prefixed with \fB->\fR. Function return probe reports are unindented and their output is prefixed with \fB<-\fR\&. System call entry probe reports are indented and their output is prefixed with \fB=>\fR. System call return probe reports are unindented and their output is prefixed with \fB<=\fR\&.
>  .TP
> -\fB\fB-G\fR\fR
> -Generate an ELF file containing an embedded DTrace program. The DTrace probes specified in the program are saved inside of a relocatable ELF object which can be linked into another program. If the \fB-o\fR option is present, the ELF file is saved using the pathname specified as the argument for this operand. If the \fB-o\fR option is not present and the DTrace program is contained with a file whose name is \fB\fIfilename\fR.d\fR, then the ELF file is saved using the name \fB\fIfilename\fR.o\fR. Otherwise the ELF file is saved using the name \fBd.out\fR.
> +\fB\fB\-G\fR\fR
> +Generate an ELF file containing an embedded DTrace program. The DTrace probes specified in the program are saved inside of a relocatable ELF object which can be linked into another program. If the \fB\-o\fR option is present, the ELF file is saved using the pathname specified as the argument for this operand. If the \fB\-o\fR option is not present and the DTrace program is contained with a file whose name is \fB\fIfilename\fR.d\fR, then the ELF file is saved using the name \fB\fIfilename\fR.o\fR. Otherwise the ELF file is saved using the name \fBd.out\fR.
>  .TP
> -\fB\fB-H\fR\fR
> -Print the pathnames of included files when invoking \fBcpp\fR(1) (enabled using the \fB-C\fR option). This option passes the \fB-H\fR option to each \fBcpp\fR invocation, causing it to display the list of pathnames, one for each line, to \fBstderr\fR.
> +\fB\fB\-H\fR\fR
> +Print the pathnames of included files when invoking \fBcpp\fR(1) (enabled using the \fB\-C\fR option). This option passes the \fB\-H\fR option to each \fBcpp\fR invocation, causing it to display the list of pathnames, one for each line, to \fBstderr\fR.
>  .TP
> -\fB\fB-h\fR\fR
> -Generate a header file containing macros that correspond to probes in the specified provider definitions. This option should be used to generate a header file that is included by other source files for later use with the \fB-G\fR option. If the \fB-o\fR option is present, the header file is saved using the pathname specified as the argument for that option. If the \fB-o\fR option is not present and the DTrace program is contained with a file whose name is \fIfilename\fR\fB\&.d\fR, then the header file is saved using the name \fIfilename\fR\fB\&.h\fR.
> +\fB\fB\-h\fR\fR
> +Generate a header file containing macros that correspond to probes in the specified provider definitions. This option should be used to generate a header file that is included by other source files for later use with the \fB\-G\fR option. If the \fB\-o\fR option is present, the header file is saved using the pathname specified as the argument for that option. If the \fB\-o\fR option is not present and the DTrace program is contained with a file whose name is \fIfilename\fR\fB\&.d\fR, then the header file is saved using the name \fIfilename\fR\fB\&.h\fR.
>  .TP
> -\fB\fB-i\fR \fIprobe-id\fR\fB[[\fR\fIpredicate\fR] \fIaction\fR\fB]\fR\fR
> -Specify probe identifier (\fIprobe-id\fR) to trace or list (\fB-l\fR option). You can specify probe IDs using decimal integers as shown by \fBdtrace\fR \fB-l\fR. The \fB-i\fR argument can be suffixed with an optional D probe clause. You can specify more than one \fB-i\fR option at a time.
> +\fB\fB\-i\fR \fIprobe-id\fR\fB[[\fR\fIpredicate\fR] \fIaction\fR\fB]\fR\fR
> +Specify probe identifier (\fIprobe-id\fR) to trace or list (\fB\-l\fR option). You can specify probe IDs using decimal integers as shown by \fBdtrace\fR \fB\-l\fR. The \fB\-i\fR argument can be suffixed with an optional D probe clause. You can specify more than one \fB\-i\fR option at a time.
>  .TP
> -\fB\fB-I\fR \fIpath\fR\fR
> -Add the specified directory \fIpath\fR to the search path for \fB#include\fR files when invoking \fBcpp\fR(1) (enabled using the \fB-C\fR option). This option passes the \fB-I\fR option to each \fBcpp\fR invocation. The specified \fIpath\fR is inserted into the search path ahead of the default directory list.
> +\fB\fB\-I\fR \fIpath\fR\fR
> +Add the specified directory \fIpath\fR to the search path for \fB#include\fR files when invoking \fBcpp\fR(1) (enabled using the \fB\-C\fR option). This option passes the \fB\-I\fR option to each \fBcpp\fR invocation. The specified \fIpath\fR is inserted into the search path ahead of the default directory list.
>  .TP
> -\fB\fB-L\fR \fIpath\fR\fR
> +\fB\fB\-L\fR \fIpath\fR\fR
>  Add the specified directory \fIpath\fR to the search path for DTrace libraries. DTrace libraries are used to contain common definitions that can be used when writing D programs. The specified \fIpath\fR is added after the default library search path. If it exists, a subdirectory of \fIpath\fR named after the minor version of the running kernel (e.g. 3.8) is searched immediately before \fIpath\fR. (But take note: dependency analysis is performed only within each directory, not across directories.)
>  .TP
> -\fB\fB-l\fR\fR
> -List probes instead of enabling them. If the \fB-l\fR option is specified, \fBdtrace\fR produces a report of the probes matching the descriptions given using the \fB-P\fR, \fB-m\fR, \fB-f\fR, \fB-n\fR, \fB-i\fR, and \fB-s\fR options. If none of these options are specified, this option lists all probes.
> +\fB\fB\-l\fR\fR
> +List probes instead of enabling them. If the \fB\-l\fR option is specified, \fBdtrace\fR produces a report of the probes matching the descriptions given using the \fB\-P\fR, \fB\-m\fR, \fB\-f\fR, \fB\-n\fR, \fB\-i\fR, and \fB\-s\fR options. If none of these options are specified, this option lists all probes.
>  .TP
> -\fB\fB-m\fR [[\fIprovider:\fR] \fImodule:\fR [[\fIpredicate\fR] \fIaction\fR]]\fR
> -Specify module name to trace or list (\fB-l\fR option). The corresponding argument can include any of the probe description forms \fIprovider:module\fR or \fImodule\fR. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fImodule\fR are specified in the description, all probes with a corresponding \fImodule\fR are matched. The \fB-m\fR argument can be suffixed with an optional D probe clause. More than one \fB-m\fR option can be specified on the command line at a time.
> +\fB\fB\-m\fR [[\fIprovider:\fR] \fImodule:\fR [[\fIpredicate\fR] \fIaction\fR]]\fR
> +Specify module name to trace or list (\fB\-l\fR option). The corresponding argument can include any of the probe description forms \fIprovider:module\fR or \fImodule\fR. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fImodule\fR are specified in the description, all probes with a corresponding \fImodule\fR are matched. The \fB\-m\fR argument can be suffixed with an optional D probe clause. More than one \fB\-m\fR option can be specified on the command line at a time.
>  .TP
> -\fB\fB-n\fR [[[\fIprovider:\fR] \fImodule:\fR] \fIfunction:\fR] \fIname\fR [[\fIpredicate\fR] \fIaction\fR]\fR
> -Specify probe name to trace or list (\fB-l\fR option). The corresponding argument can include any of the probe description forms \fIprovider:module:function:name\fR, \fImodule:function:name\fR, \fIfunction:name\fR, or \fIname\fR. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fIname\fR are specified in the description, all probes with a corresponding \fIname\fR are matched. The \fB-n\fR argument can be suffixed with an optional D probe clause. More than one \fB-n\fR option can be specified on the command line at a time.
> +\fB\fB\-n\fR [[[\fIprovider:\fR] \fImodule:\fR] \fIfunction:\fR] \fIname\fR [[\fIpredicate\fR] \fIaction\fR]\fR
> +Specify probe name to trace or list (\fB\-l\fR option). The corresponding argument can include any of the probe description forms \fIprovider:module:function:name\fR, \fImodule:function:name\fR, \fIfunction:name\fR, or \fIname\fR. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fIname\fR are specified in the description, all probes with a corresponding \fIname\fR are matched. The \fB\-n\fR argument can be suffixed with an optional D probe clause. More than one \fB\-n\fR option can be specified on the command line at a time.
>  .TP
> -\fB\fB-o\fR \fIoutput\fR\fR
> -Specify the \fIoutput\fR file for the \fB-G\fR, \fB-h\fR, and \fB-l\fR options, or for the traced data itself. If the \fB-G\fR option is present and the \fB-s\fR option's argument is of the form \fB\fIfilename\fR.d\fR and \fB-o\fR is not present, the default output file is \fB\fIfilename\fR.o\fR. Otherwise the default output file is \fBd.out\fR.
> +\fB\fB\-o\fR \fIoutput\fR\fR
> +Specify the \fIoutput\fR file for the \fB\-G\fR, \fB\-h\fR, and \fB\-l\fR options, or for the traced data itself. If the \fB\-G\fR option is present and the \fB\-s\fR option's argument is of the form \fB\fIfilename\fR.d\fR and \fB\-o\fR is not present, the default output file is \fB\fIfilename\fR.o\fR. Otherwise the default output file is \fBd.out\fR.
>  .TP
> -\fB\fB-p\fR \fIpid\fR\fR
> -Grab the specified process-ID \fIpid\fR, cache its symbol tables, and exit upon its completion. If more than one \fB-p\fR option is present on the command line, \fBdtrace\fR exits when all commands have exited, reporting the exit status for each process as it terminates. The first process-ID is made available to any D programs specified on the command line or using the \fB-s\fR option through the \fB$target\fR macro variable. Refer to the \fIOracle Linux DTrace Guide\fR for more information on macro variables.
> +\fB\fB\-p\fR \fIpid\fR\fR
> +Grab the specified process-ID \fIpid\fR, cache its symbol tables, and exit upon its completion. If more than one \fB\-p\fR option is present on the command line, \fBdtrace\fR exits when all commands have exited, reporting the exit status for each process as it terminates. The first process-ID is made available to any D programs specified on the command line or using the \fB\-s\fR option through the \fB$target\fR macro variable. Refer to the \fIOracle Linux DTrace Guide\fR for more information on macro variables.
>  .TP
> -\fB\fB-P\fR \fIprovider\fR \fB[[\fR\fIpredicate\fR\fB]\fR \fIaction\fR]\fR
> -Specify provider name to trace or list (\fB-l\fR option). The remaining probe description fields module, function, and name are left blank and match any probes regardless of the values in those fields. The \fB-P\fR argument can be suffixed with an optional D probe clause. You can specify more than one \fB-P\fR option on the command line at a time.
> +\fB\fB\-P\fR \fIprovider\fR \fB[[\fR\fIpredicate\fR\fB]\fR \fIaction\fR]\fR
> +Specify provider name to trace or list (\fB\-l\fR option). The remaining probe description fields module, function, and name are left blank and match any probes regardless of the values in those fields. The \fB\-P\fR argument can be suffixed with an optional D probe clause. You can specify more than one \fB\-P\fR option on the command line at a time.
>  .TP
> -\fB\fB-q\fR\fR
> +\fB\fB\-q\fR\fR
>  Set quiet mode. \fBdtrace\fR suppresses messages such as the number of probes matched by the specified options and D programs and does not print column headers, the CPU ID, the probe ID, or insert newlines into the output. Only data traced and formatted by D program statements such as \fBtrace()\fR and \fBprintf()\fR is displayed to \fBstdout\fR.
>  .TP
> -\fB\fB-s\fR\fR
> -Compile the specified D program source file. If the \fB-e\fR option is present, the program is compiled but instrumentation is not enabled. If the \fB-l\fR option is present, the program is compiled and the set of probes matched by it is listed, but instrumentation is not enabled. If none of \fB-e\fR, \fB-l\fR, or \fB-G\fR are present, the instrumentation specified by the D program is enabled and tracing begins.
> +\fB\fB\-s\fR\fR
> +Compile the specified D program source file. If the \fB\-e\fR option is present, the program is compiled but instrumentation is not enabled. If the \fB\-l\fR option is present, the program is compiled and the set of probes matched by it is listed, but instrumentation is not enabled. If none of \fB\-e\fR, \fB\-l\fR, or \fB\-G\fR are present, the instrumentation specified by the D program is enabled and tracing begins.
>  .TP
> -\fB\fB-S\fR\fR
> +\fB\fB\-S\fR\fR
>  Show D compiler intermediate code. The D compiler produces a report of the intermediate code generated for each D program to \fBstderr\fR.
>  .TP
> -\fB\fB-U\fR \fIname\fR\fR
> +\fB\fB\-U\fR \fIname\fR\fR
>  Undefine the specified \fIname\fR when invoking \fBcpp\fR(1) (enabled using the \fB-C\fR option). This option passes the \fB-U\fR option to each \fBcpp\fR invocation.
>  .TP
> -\fB\fB-v\fR\fR
> -Set verbose mode. If the \fB-v\fR option is specified, \fBdtrace\fR produces a program stability report showing the minimum interface stability and dependency level for the specified D programs. DTrace stability levels are explained in further detail in the \fIOracle Linux DTrace Guide\fR.
> +\fB\fB\-v\fR\fR
> +Set verbose mode. If the \fB\-v\fR option is specified, \fBdtrace\fR produces a program stability report showing the minimum interface stability and dependency level for the specified D programs. DTrace stability levels are explained in further detail in the \fIOracle Linux DTrace Guide\fR.
>  .TP
> -\fB\fB-V\fR\fR
> -Report the highest D programming interface version supported by \fBdtrace\fR. The version information is printed to \fBstdout\fR and the \fBdtrace\fR command exits. Refer to the \fIOracle Linux DTrace Guide\fR for more information about DTrace versioning features. In conjunction with \fB-v\fR, also reports information on the version of the \fBdtrace\fR(1) tool and associated library.
> +\fB\fB\-V\fR\fR
> +Report the highest D programming interface version supported by \fBdtrace\fR. The version information is printed to \fBstdout\fR and the \fBdtrace\fR command exits. Refer to the \fIOracle Linux DTrace Guide\fR for more information about DTrace versioning features. In conjunction with \fB\-v\fR, also reports information on the version of the \fBdtrace\fR(1) tool and associated library.
>  .TP
> -\fB\fB-w\fR\fR
> -Permit destructive actions in D programs specified using the \fB-s\fR, \fB-P\fR, \fB-m\fR, \fB-f\fR, \fB-n\fR, or \fB-i\fR options. If the \fB-w\fR option is not specified, \fBdtrace\fR does not permit the compilation or enabling of a D program that contains destructive actions.
> +\fB\fB\-w\fR\fR
> +Permit destructive actions in D programs specified using the \fB\-s\fR, \fB\-P\fR, \fB\-m\fR, \fB\-f\fR, \fB\-n\fR, or \fB\-i\fR options. If the \fB\-w\fR option is not specified, \fBdtrace\fR does not permit the compilation or enabling of a D program that contains destructive actions.
>  .TP
> -\fB\fB-x\fR \fIarg\fR [\fI=val\fR]\fR
> +\fB\fB\-x\fR \fIarg\fR [\fI=val\fR]\fR
>  Enable or modify a DTrace runtime option or D compiler option. The list of options is found in the \fIOracle Linux DTrace Guide\fR. Boolean options are enabled by specifying their name. Options with values are set by separating the option name and value with an equals sign (\fB=\fR).
>  .TP
> -\fB\fB-Z\fR\fR
> -Permit probe descriptions that match zero probes. If the \fB-Z\fR option is not specified, \fBdtrace\fR reports an error and exits if any probe descriptions specified in D program files (\fB-s\fR option) or on the command line (\fB-P\fR, \fB-m\fR, \fB-f\fR, \fB-n\fR, or \fB-i\fR options) contain descriptions that do not match any known probes.
> -
> +\fB\fB\-Z\fR\fR
> +Permit probe descriptions that match zero probes. If the \fB\-Z\fR option is not specified, \fBdtrace\fR reports an error and exits if any probe descriptions specified in D program files (\fB\-s\fR option) or on the command line (\fB\-P\fR, \fB\-m\fR, \fB\-f\fR, \fB\-n\fR, or \fB\-i\fR options) contain descriptions that do not match any known probes.
> +.
>  .SH OPERANDS
>  .LP
> -You can specify zero or more additional arguments on the \fBdtrace\fR command line to define a set of macro variables (\fB$1\fR, \fB$2\fR, and so forth). The additional arguments can be used in D programs specified using the \fB-s\fR option or on the command line. The use of macro variables is described further in the \fIOracle Linux DTrace Guide\fR.
> -
> +You can specify zero or more additional arguments on the \fBdtrace\fR command line to define a set of macro variables (\fB$1\fR, \fB$2\fR, and so forth). The additional arguments can be used in D programs specified using the \fB\-s\fR option or on the command line. The use of macro variables is described further in the \fIOracle Linux DTrace Guide\fR.
> +.
>  .SH EXIT STATUS
>  .LP
>  The following exit values are returned:
>  .TP
>  .B 0
>  Successful completion. 
> -
> +.IP
>  For D program requests, an exit status of \fB0\fR indicates that programs were successfully compiled, probes were successfully enabled, or anonymous state was successfully retrieved. \fBdtrace\fR returns \fB0\fR even if the specified tracing requests encountered errors or drops.
>  .TP
>  .B 1
>  An error occurred.
> -
> +.IP
>  For D program requests, an exit status of \fB1\fR indicates that program compilation failed or that the specified request could not be satisfied.
>  .TP
>  .B 2
>  Invalid command line options or arguments were specified.
>  .\" .RE
> -
> +.
>  .SH "ENVIRONMENT VARIABLES"
>  .LP
>  The following environment variables are consulted:
> @@ -180,7 +180,7 @@ Print CTF type library debugging output on standard error.
>  .IP DTRACE_OPT_*
>  Set a given DTrace option.
>  
> -Options set this way are overridden both by options specified via \fB-x\fR on the command line, and by \fBsetopt\fR statements.
> +Options set this way are overridden both by options specified via \fB\-x\fR on the command line, and by \fBsetopt\fR statements.
>  
>  .SH SEE ALSO
>  .BR cpp (1),
> @@ -190,4 +190,4 @@ Options set this way are overridden both by options specified via \fB-x\fR on th
>  
>  .SH USAGE
>  .LP
> -When using the \fB-p\fR flag, \fBdtrace\fR stops the target processes while it is inspecting them and reporting results. A process can do nothing while it is stopped. This means that, if , for example, the X server is inspected by \fBdtrace\fR running in a window under the X server's control, the whole window system can become deadlocked, because the \fBdtrace\fR tool would be attempting to display its results to a window that cannot be refreshed. In such a case, logging in from another system using \fBssh\fR(1) and killing the offending \fBdtrace\fR tool clears the deadlock.
> +When using the \fB\-p\fR flag, \fBdtrace\fR stops the target processes while it is inspecting them and reporting results. A process can do nothing while it is stopped. This means that, if, for example, the X server is inspected by \fBdtrace\fR running in a window under the X server's control, the whole window system can become deadlocked, because the \fBdtrace\fR tool would be attempting to display its results to a window that cannot be refreshed. In such a case, logging in from another system using \fBssh\fR(1) and killing the offending \fBdtrace\fR tool clears the deadlock.
> -- 
> 2.46.0.278.g36e3a12567
> 

[PATCH 09/14] man: drop blank lines

[Nick Alcock]

They don't do what you might expect in troff: a leading . is preferable.

Signed-off-by: Nick Alcock <nick.alcock@oracle.com>
---
 cmd/dtrace.8 | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/cmd/dtrace.8 b/cmd/dtrace.8
index a53632949e72..0639db2136a7 100644
--- a/cmd/dtrace.8
+++ b/cmd/dtrace.8
@@ -179,15 +179,15 @@ Print libdtrace debugging output on standard error.
 Print CTF type library debugging output on standard error.
 .IP DTRACE_OPT_*
 Set a given DTrace option.
-
+.
 Options set this way are overridden both by options specified via \fB\-x\fR on the command line, and by \fBsetopt\fR statements.
-
+.
 .SH SEE ALSO
 .BR cpp (1),
 .BR ssh (1)
 .LP
 .I Oracle Linux DTrace Guide
-
+.
 .SH USAGE
 .LP
 When using the \fB\-p\fR flag, \fBdtrace\fR stops the target processes while it is inspecting them and reporting results. A process can do nothing while it is stopped. This means that, if, for example, the X server is inspected by \fBdtrace\fR running in a window under the X server's control, the whole window system can become deadlocked, because the \fBdtrace\fR tool would be attempting to display its results to a window that cannot be refreshed. In such a case, logging in from another system using \fBssh\fR(1) and killing the offending \fBdtrace\fR tool clears the deadlock.
-- 
2.46.0.278.g36e3a12567

Re: [PATCH 09/14] man: drop blank lines

[Kris Van Hees]

On Thu, Oct 24, 2024 at 12:37:53PM +0100, Nick Alcock wrote:
> They don't do what you might expect in troff: a leading . is preferable.
> 
> Signed-off-by: Nick Alcock <nick.alcock@oracle.com>

Reviewed-by: Kris Van Hees <kris.van.hees@oracle.com>

> ---
>  cmd/dtrace.8 | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/cmd/dtrace.8 b/cmd/dtrace.8
> index a53632949e72..0639db2136a7 100644
> --- a/cmd/dtrace.8
> +++ b/cmd/dtrace.8
> @@ -179,15 +179,15 @@ Print libdtrace debugging output on standard error.
>  Print CTF type library debugging output on standard error.
>  .IP DTRACE_OPT_*
>  Set a given DTrace option.
> -
> +.
>  Options set this way are overridden both by options specified via \fB\-x\fR on the command line, and by \fBsetopt\fR statements.
> -
> +.
>  .SH SEE ALSO
>  .BR cpp (1),
>  .BR ssh (1)
>  .LP
>  .I Oracle Linux DTrace Guide
> -
> +.
>  .SH USAGE
>  .LP
>  When using the \fB\-p\fR flag, \fBdtrace\fR stops the target processes while it is inspecting them and reporting results. A process can do nothing while it is stopped. This means that, if, for example, the X server is inspected by \fBdtrace\fR running in a window under the X server's control, the whole window system can become deadlocked, because the \fBdtrace\fR tool would be attempting to display its results to a window that cannot be refreshed. In such a case, logging in from another system using \fBssh\fR(1) and killing the offending \fBdtrace\fR tool clears the deadlock.
> -- 
> 2.46.0.278.g36e3a12567
> 

[PATCH 10/14] man: fix blank line in environment variables list

[Nick Alcock]

Use .IP instead, to get an indented linebreak.

Signed-off-by: Nick Alcock <nick.alcock@oracle.com>
---
 cmd/dtrace.8 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/cmd/dtrace.8 b/cmd/dtrace.8
index 0639db2136a7..fb9392d29cb2 100644
--- a/cmd/dtrace.8
+++ b/cmd/dtrace.8
@@ -179,7 +179,7 @@ Print libdtrace debugging output on standard error.
 Print CTF type library debugging output on standard error.
 .IP DTRACE_OPT_*
 Set a given DTrace option.
-.
+.IP
 Options set this way are overridden both by options specified via \fB\-x\fR on the command line, and by \fBsetopt\fR statements.
 .
 .SH SEE ALSO
-- 
2.46.0.278.g36e3a12567

Re: [PATCH 10/14] man: fix blank line in environment variables list

[Kris Van Hees]

On Thu, Oct 24, 2024 at 12:37:54PM +0100, Nick Alcock wrote:
> Use .IP instead, to get an indented linebreak.
> 
> Signed-off-by: Nick Alcock <nick.alcock@oracle.com>

Reviewed-by: Kris Van Hees <kris.van.hees@oracle.com>

> ---
>  cmd/dtrace.8 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/cmd/dtrace.8 b/cmd/dtrace.8
> index 0639db2136a7..fb9392d29cb2 100644
> --- a/cmd/dtrace.8
> +++ b/cmd/dtrace.8
> @@ -179,7 +179,7 @@ Print libdtrace debugging output on standard error.
>  Print CTF type library debugging output on standard error.
>  .IP DTRACE_OPT_*
>  Set a given DTrace option.
> -.
> +.IP
>  Options set this way are overridden both by options specified via \fB\-x\fR on the command line, and by \fBsetopt\fR statements.
>  .
>  .SH SEE ALSO
> -- 
> 2.46.0.278.g36e3a12567
> 

[PATCH 11/14] dtprobed: fix parser child timeout

[Nick Alcock]

This was always meant to be five seconds, but when the option was
rejigged to take seconds rather than milliseconds, the default was
not changed, leading to a ridiculously huge multi-hour default
timeout.  We definitely don't want the parser child hanging for
nearly two hours: go back to seconds again.

Signed-off-by: Nick Alcock <nick.alcock@oracle.com>
---
 dtprobed/dtprobed.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/dtprobed/dtprobed.c b/dtprobed/dtprobed.c
index c83f0adb56c4..f4c6be1e045d 100644
--- a/dtprobed/dtprobed.c
+++ b/dtprobed/dtprobed.c
@@ -82,7 +82,7 @@ static pid_t parser_pid;
 static int parser_in_pipe;
 static int parser_out_pipe;
 static int sync_fd = -1;
-static int timeout = 5000; 			/* In seconds.  */
+static int timeout = 5; 			/* In seconds.  */
 static int rq_count = 0;
 static int cleanup_interval = 128;		/* In requests.  */
 
-- 
2.46.0.278.g36e3a12567

Re: [PATCH 11/14] dtprobed: fix parser child timeout

[Kris Van Hees]

On Thu, Oct 24, 2024 at 12:37:55PM +0100, Nick Alcock wrote:
> This was always meant to be five seconds, but when the option was
> rejigged to take seconds rather than milliseconds, the default was
> not changed, leading to a ridiculously huge multi-hour default
> timeout.  We definitely don't want the parser child hanging for
> nearly two hours: go back to seconds again.
> 
> Signed-off-by: Nick Alcock <nick.alcock@oracle.com>

Reviewed-by: Kris Van Hees <kris.van.hees@oracle.com>

> ---
>  dtprobed/dtprobed.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/dtprobed/dtprobed.c b/dtprobed/dtprobed.c
> index c83f0adb56c4..f4c6be1e045d 100644
> --- a/dtprobed/dtprobed.c
> +++ b/dtprobed/dtprobed.c
> @@ -82,7 +82,7 @@ static pid_t parser_pid;
>  static int parser_in_pipe;
>  static int parser_out_pipe;
>  static int sync_fd = -1;
> -static int timeout = 5000; 			/* In seconds.  */
> +static int timeout = 5; 			/* In seconds.  */
>  static int rq_count = 0;
>  static int cleanup_interval = 128;		/* In requests.  */
>  
> -- 
> 2.46.0.278.g36e3a12567
> 

[PATCH 12/14] man: add manpage for dtprobed(8)

[Nick Alcock]

Cross-reference it from dtrace(8).

Signed-off-by: Nick Alcock <nick.alcock@oracle.com>
Bug: https://github.com/oracle/dtrace-utils/issues/94
---
 cmd/dtrace.8        |  3 ++-
 dtprobed/Build      |  2 ++
 dtprobed/dtprobed.8 | 66 +++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 70 insertions(+), 1 deletion(-)
 create mode 100644 dtprobed/dtprobed.8

diff --git a/cmd/dtrace.8 b/cmd/dtrace.8
index fb9392d29cb2..c299073239eb 100644
--- a/cmd/dtrace.8
+++ b/cmd/dtrace.8
@@ -184,7 +184,8 @@ Options set this way are overridden both by options specified via \fB\-x\fR on t
 .
 .SH SEE ALSO
 .BR cpp (1),
-.BR ssh (1)
+.BR ssh (1),
+.BR dtprobed (1)
 .LP
 .I Oracle Linux DTrace Guide
 .
diff --git a/dtprobed/Build b/dtprobed/Build
index 346cd6aee190..7d98ddf836c3 100644
--- a/dtprobed/Build
+++ b/dtprobed/Build
@@ -57,6 +57,8 @@ install::
 	mkdir -p $(INSTSBINDIR)
 	$(call describe-install-target,$(INSTSBINDIR),dtprobed)
 	install -m 755 $(objdir)/dtprobed $(INSTSBINDIR)
+	$(call describe-install-target,$(INSTMANDIR),dtprobed.8)
+	install -m 644 $(dtprobed_DIR)/dtprobed.8 $(INSTMANDIR)/man8
 	mkdir -p $(INSTUDEVDIR)
 	$(call describe-install-target,$(INSTUDEVDIR),60-dtprobed.rules)
 	install -m 644 $(dtprobed_DIR)60-dtprobed.rules $(INSTUDEVDIR)
diff --git a/dtprobed/dtprobed.8 b/dtprobed/dtprobed.8
new file mode 100644
index 000000000000..145cece1840d
--- /dev/null
+++ b/dtprobed/dtprobed.8
@@ -0,0 +1,66 @@
+'\" te
+.\" Oracle Linux DTrace.
+.\" Copyright (c) 2009, 2024, Oracle and/or its affiliates. All Rights Reserved.
+.\" Licensed under the Universal Permissive License v 1.0 as shown at
+.\" http://oss.oracle.com/licenses/upl.
+.TH dtrace 8 "22 Oct 2023" "Oracle Linux" "Linux Programmer's Manual"
+.SH NAME
+dtprobed \- USDT-tracking daemon
+.SH SYNOPSIS
+.SY dtprobed
+.OP -Fd
+.OP \-d devname
+.OP \-t timeout
+.YS
+.
+.SH DESCRIPTION
+.LP
+\fBdtprobed\fP is a component of the DTrace system that keeps track of USDT probes within running processes, parsing and storing the DOF they provide for later consumption by \fBdtrace\fP proper.
+.LP
+\fBdtprobed\fP should be started as soon as possible after startup and should always be kept running: processes that start before it may not have usable USDT probes.  On systemd systems this is usually done automatically.  (Restarting on upgrade should also be done for you by the packaging system.)
+.LP
+The following options are supported:
+.TP
+\fB\-F\fP
+Put \fBdtprobed\fP into the foreground: log output to \fIstderr\fP instead of the syslog. (Routinely used by systemd.)
+.TP
+\fB\-d\fP
+Enable debugging: log extra output, and disable sandboxing of the DOF parser.
+.TP
+\fB-n\fP \fIdevname\fP
+Name the CUSE device something other than the default \fIdtrace/helper\fP. DOF-containing processes will not connect to this instance unless pointed at it via the \fIDTRACE_DOF_INIT_DEVNAME\fP environment variable.  Using this option is necessary if for some reason (perhaps debugging) you want to have two dtprobeds running at once.  (They will still share a state directory, so DTrace will know about all probes discovered by all running \fBdtprobed\fPs.)
+.TP
+\fB\-t\fP \fItimeout\fP
+Timeout, in seconds, for DOF reads from the parser child.  DOF that takes longer than this to parse will be discarded.  The default (5 seconds) is probably always reasonable. Setting this too low might cause legitimate DOF to be discarded: setting it too high might cause faulty DOF to block \fBdtprobed\fP, preventing registration of new probes.
+.
+.SH "ENVIRONMENT VARIABLES"
+.LP
+Ignoring internal testing-only variables, \fBdtprobed\fP itself does not accept any environment variables: but programs that talk to it (any program that contains USDT probes) do accept some.
+.TP
+\fIDTRACE_DOF_INIT_DEBUG\fP
+Output debugging messages to standard error if set (to anything).
+.TP
+\fIDTRACE_DOF_INIT_DEVNAME\fP
+The full name of the helper device to send registration requests on: by default, \fI/dev/dtrace/helper\fP. \fBdtprobed\fP is listening on the other end of this device.
+.TP
+\fIDTRACE_DOF_INIT_DISABLE\fP
+Disable DOF registration entirely.
+.
+.SH FILES
+.
+.TP
+\fI/run/dtrace/stash\fP
+Private stash of DOF.
+.TP
+\fI/run/dtrace/probes\fP
+Parsed representations of every probe.  The parsed representation is shared between
+.MR dtrace 8
+and \fBdtprobed\fP, and can change between releases: on upgrade, \fBdtprobed\fP should be restarted, and will regenerate any parsed DOF that is needed, so \fBdtrace\fPs started after the upgrade will still work.  (Still-running \fBdtrace\fPs from before the upgrade may become unable to see newly-added probes.)
+.
+.SH SEE ALSO
+.
+.BR cpp (1),
+.BR ssh (1),
+.BR dtprobed (1)
+.LP
+.I Oracle Linux DTrace Guide
-- 
2.46.0.278.g36e3a12567

Re: [PATCH 12/14] man: add manpage for dtprobed(8)

[Kris Van Hees]

On Thu, Oct 24, 2024 at 12:37:56PM +0100, Nick Alcock wrote:
> Cross-reference it from dtrace(8).
> 
> Signed-off-by: Nick Alcock <nick.alcock@oracle.com>
> Bug: https://github.com/oracle/dtrace-utils/issues/94

Bug: before Signed-off-by:

Also (see below)...

> ---
>  cmd/dtrace.8        |  3 ++-
>  dtprobed/Build      |  2 ++
>  dtprobed/dtprobed.8 | 66 +++++++++++++++++++++++++++++++++++++++++++++
>  3 files changed, 70 insertions(+), 1 deletion(-)
>  create mode 100644 dtprobed/dtprobed.8
> 
> diff --git a/cmd/dtrace.8 b/cmd/dtrace.8
> index fb9392d29cb2..c299073239eb 100644
> --- a/cmd/dtrace.8
> +++ b/cmd/dtrace.8
> @@ -184,7 +184,8 @@ Options set this way are overridden both by options specified via \fB\-x\fR on t
>  .
>  .SH SEE ALSO
>  .BR cpp (1),
> -.BR ssh (1)
> +.BR ssh (1),
> +.BR dtprobed (1)
>  .LP
>  .I Oracle Linux DTrace Guide
>  .
> diff --git a/dtprobed/Build b/dtprobed/Build
> index 346cd6aee190..7d98ddf836c3 100644
> --- a/dtprobed/Build
> +++ b/dtprobed/Build
> @@ -57,6 +57,8 @@ install::
>  	mkdir -p $(INSTSBINDIR)
>  	$(call describe-install-target,$(INSTSBINDIR),dtprobed)
>  	install -m 755 $(objdir)/dtprobed $(INSTSBINDIR)
> +	$(call describe-install-target,$(INSTMANDIR),dtprobed.8)
> +	install -m 644 $(dtprobed_DIR)/dtprobed.8 $(INSTMANDIR)/man8
>  	mkdir -p $(INSTUDEVDIR)
>  	$(call describe-install-target,$(INSTUDEVDIR),60-dtprobed.rules)
>  	install -m 644 $(dtprobed_DIR)60-dtprobed.rules $(INSTUDEVDIR)
> diff --git a/dtprobed/dtprobed.8 b/dtprobed/dtprobed.8
> new file mode 100644
> index 000000000000..145cece1840d
> --- /dev/null
> +++ b/dtprobed/dtprobed.8
> @@ -0,0 +1,66 @@
> +'\" te
> +.\" Oracle Linux DTrace.
> +.\" Copyright (c) 2009, 2024, Oracle and/or its affiliates. All Rights Reserved.
> +.\" Licensed under the Universal Permissive License v 1.0 as shown at
> +.\" http://oss.oracle.com/licenses/upl.
> +.TH dtrace 8 "22 Oct 2023" "Oracle Linux" "Linux Programmer's Manual"
> +.SH NAME
> +dtprobed \- USDT-tracking daemon
> +.SH SYNOPSIS
> +.SY dtprobed
> +.OP -Fd
> +.OP \-d devname
> +.OP \-t timeout
> +.YS
> +.
> +.SH DESCRIPTION
> +.LP
> +\fBdtprobed\fP is a component of the DTrace system that keeps track of USDT probes within running processes, parsing and storing the DOF they provide for later consumption by \fBdtrace\fP proper.
> +.LP
> +\fBdtprobed\fP should be started as soon as possible after startup and should always be kept running: processes that start before it may not have usable USDT probes.  On systemd systems this is usually done automatically.  (Restarting on upgrade should also be done for you by the packaging system.)
> +.LP
> +The following options are supported:
> +.TP
> +\fB\-F\fP
> +Put \fBdtprobed\fP into the foreground: log output to \fIstderr\fP instead of the syslog. (Routinely used by systemd.)
> +.TP
> +\fB\-d\fP
> +Enable debugging: log extra output, and disable sandboxing of the DOF parser.
> +.TP
> +\fB-n\fP \fIdevname\fP
> +Name the CUSE device something other than the default \fIdtrace/helper\fP. DOF-containing processes will not connect to this instance unless pointed at it via the \fIDTRACE_DOF_INIT_DEVNAME\fP environment variable.  Using this option is necessary if for some reason (perhaps debugging) you want to have two dtprobeds running at once.  (They will still share a state directory, so DTrace will know about all probes discovered by all running \fBdtprobed\fPs.)
> +.TP
> +\fB\-t\fP \fItimeout\fP
> +Timeout, in seconds, for DOF reads from the parser child.  DOF that takes longer than this to parse will be discarded.  The default (5 seconds) is probably always reasonable. Setting this too low might cause legitimate DOF to be discarded: setting it too high might cause faulty DOF to block \fBdtprobed\fP, preventing registration of new probes.
> +.
> +.SH "ENVIRONMENT VARIABLES"
> +.LP
> +Ignoring internal testing-only variables, \fBdtprobed\fP itself does not accept any environment variables: but programs that talk to it (any program that contains USDT probes) do accept some.
> +.TP
> +\fIDTRACE_DOF_INIT_DEBUG\fP
> +Output debugging messages to standard error if set (to anything).
> +.TP
> +\fIDTRACE_DOF_INIT_DEVNAME\fP
> +The full name of the helper device to send registration requests on: by default, \fI/dev/dtrace/helper\fP. \fBdtprobed\fP is listening on the other end of this device.
> +.TP
> +\fIDTRACE_DOF_INIT_DISABLE\fP
> +Disable DOF registration entirely.
> +.
> +.SH FILES
> +.
> +.TP
> +\fI/run/dtrace/stash\fP
> +Private stash of DOF.
> +.TP
> +\fI/run/dtrace/probes\fP
> +Parsed representations of every probe.  The parsed representation is shared between
> +.MR dtrace 8
> +and \fBdtprobed\fP, and can change between releases: on upgrade, \fBdtprobed\fP should be restarted, and will regenerate any parsed DOF that is needed, so \fBdtrace\fPs started after the upgrade will still work.  (Still-running \fBdtrace\fPs from before the upgrade may become unable to see newly-added probes.)
> +.
> +.SH SEE ALSO
> +.
> +.BR cpp (1),
> +.BR ssh (1),
> +.BR dtprobed (1)

I would think this would refer to dtrace (only).  There does not seem to be
any point in referring to cpp, ssh, dtprobed.  Copied from dtrace.8 and forgot
to edit out?

> +.LP
> +.I Oracle Linux DTrace Guide
> -- 
> 2.46.0.278.g36e3a12567
> 

Re: [PATCH 12/14] man: add manpage for dtprobed(8)

[Nick Alcock]

On 25 Oct 2024, Kris Van Hees uttered the following:

> On Thu, Oct 24, 2024 at 12:37:56PM +0100, Nick Alcock wrote:
>> Cross-reference it from dtrace(8).
>> 
>> Signed-off-by: Nick Alcock <nick.alcock@oracle.com>
>> Bug: https://github.com/oracle/dtrace-utils/issues/94
>
> Bug: before Signed-off-by:

Ack.

>> +.SH SEE ALSO
>> +.
>> +.BR cpp (1),
>> +.BR ssh (1),
>> +.BR dtprobed (1)
>
> I would think this would refer to dtrace (only).  There does not seem to be
> any point in referring to cpp, ssh, dtprobed.  Copied from dtrace.8 and forgot
> to edit out?

Absolutely! Fixed.

-- 
NULL && (void)

[PATCH 13/14] man: drop double-\fB at the start of every option line

[Nick Alcock]

All this does is stops \fP (which goes back to the previous font)
from working.  (The manpage looks fine afterwards, both on
the terminal and typeset.)

Signed-off-by: Nick Alcock <nick.alcock@oracle.com>
---
 cmd/dtrace.8 | 56 ++++++++++++++++++++++++++--------------------------
 1 file changed, 28 insertions(+), 28 deletions(-)

diff --git a/cmd/dtrace.8 b/cmd/dtrace.8
index c299073239eb..355484bd0d34 100644
--- a/cmd/dtrace.8
+++ b/cmd/dtrace.8
@@ -64,88 +64,88 @@ The arguments accepted by the \fB\-P\fR, \fB\-m\fR, \fB\-f\fR, \fB\-n\fR, and \f
 .LP
 The following options are supported:
 .TP
-\fB\fB\-b\fR \fIbufsz\fR\fR
+\fB\-b\fP \fIbufsz\fP
 Set principal trace buffer size (\fIbufsz\fR). The trace buffer size can include any of the size suffixes \fBk\fR, \fBm\fR, \fBg\fR, or \fBt\fR. If the buffer space cannot be allocated, \fBdtrace\fR attempts to reduce the buffer size or exit depending on the setting of the \fBbufresize\fR property.
 .TP
-\fB\fB\-c\fR \fIcmd\fR\fR
+\fB\-c\fP \fIcmd\fP
 Run the specified command \fIcmd\fR and exit upon its completion. If more than one \fB\-c\fR option is present on the command line, \fBdtrace\fR exits when all commands have exited, reporting the exit status for each child process as it terminates. The process-ID of the first command is made available to any D programs specified on the command line or using the \fB\-s\fR option through the \fB$target\fR macro variable. Refer to the \fIOracle Linux DTrace Guide\fR for more information on macro variables.
 .TP
-\fB\fB\-C\fR\fR
+\fB\-C\fP
 Run the C preprocessor \fBcpp\fR(1) over D programs before compiling them. You can pass options to the C preprocessor using the \fB\-D\fR, \fB\-U\fR, \fB\-I\fR, and \fB\-H\fR options. You can select the degree of C standard conformance if you use the \fB\-X\fR option. For a description of the set of tokens defined by the D compiler when invoking the C preprocessor, see \fB\-X\fR.
 .TP
-\fB\fB\-D\fR \fIname\fR \fB[=\fR\fIvalue\fR\fB]\fR\fR
+\fB\-D\fP \fIname\fP \fB[=\fP\fIvalue\fP\fB]\fP
 Define \fIname\fR when invoking \fBcpp\fR(1) (enabled using the \fB\-C\fR option). If you specify the equals sign (\fB=\fR) and additional \fIvalue\fR, the name is assigned the corresponding value. This option passes the \fB\-D\fR option to each \fBcpp\fR invocation.
 .TP
-\fB\fB\-e\fR\fR
+\fB\-e\fP
 Exit after compiling any requests, but prior to enabling any probes. You can combine this option with D compiler options. This combination verifies that the programs compile without actually executing them and enabling the corresponding instrumentation.
 .TP
-\fB\fB\-f\fR\fB[[\fR\fIprovider\fR\fB:]\fR\fImodule\fR\fB:]\fR\fIfunction\fR\fB[[\fR\fIpredicate\fR\fB]\fR\fIaction\fR\fB]]\fR\fR
+\fB\-f\fP\fB[[\fP\fIprovider\fP\fB:]\fP\fImodule\fP\fB:]\fP\fIfunction\fP\fB[[\fP\fIpredicate\fP\fB]\fP\fIaction\fP\fB]]\fP
 Specify function name to trace or list (\fB\-l\fR option). The corresponding argument can include any of the probe description forms \fIprovider:module:function\fR, \fImodule:function\fR, or \fIfunction\fR. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fIfunction\fR are specified in the description, all probes with the corresponding \fIfunction\fR are matched. The \fB\-f\fR argument can be suffixed with an optional D probe clause. You can specify more than one \fB\-f\fR option on the command line at a time.
 .TP
-\fB\fB\-F\fR\fR
+\fB\-F\fP
 Coalesce trace output by identifying function entry and return. Function entry probe reports are indented and their output is prefixed with \fB->\fR. Function return probe reports are unindented and their output is prefixed with \fB<-\fR\&. System call entry probe reports are indented and their output is prefixed with \fB=>\fR. System call return probe reports are unindented and their output is prefixed with \fB<=\fR\&.
 .TP
-\fB\fB\-G\fR\fR
+\fB\-G\fP
 Generate an ELF file containing an embedded DTrace program. The DTrace probes specified in the program are saved inside of a relocatable ELF object which can be linked into another program. If the \fB\-o\fR option is present, the ELF file is saved using the pathname specified as the argument for this operand. If the \fB\-o\fR option is not present and the DTrace program is contained with a file whose name is \fB\fIfilename\fR.d\fR, then the ELF file is saved using the name \fB\fIfilename\fR.o\fR. Otherwise the ELF file is saved using the name \fBd.out\fR.
 .TP
-\fB\fB\-H\fR\fR
+\fB\-H\fP
 Print the pathnames of included files when invoking \fBcpp\fR(1) (enabled using the \fB\-C\fR option). This option passes the \fB\-H\fR option to each \fBcpp\fR invocation, causing it to display the list of pathnames, one for each line, to \fBstderr\fR.
 .TP
-\fB\fB\-h\fR\fR
+\fB\-h\fP
 Generate a header file containing macros that correspond to probes in the specified provider definitions. This option should be used to generate a header file that is included by other source files for later use with the \fB\-G\fR option. If the \fB\-o\fR option is present, the header file is saved using the pathname specified as the argument for that option. If the \fB\-o\fR option is not present and the DTrace program is contained with a file whose name is \fIfilename\fR\fB\&.d\fR, then the header file is saved using the name \fIfilename\fR\fB\&.h\fR.
 .TP
-\fB\fB\-i\fR \fIprobe-id\fR\fB[[\fR\fIpredicate\fR] \fIaction\fR\fB]\fR\fR
+\fB\-i\fP \fIprobe-id\fP\fB[[\fP\fIpredicate\fP] \fIaction\fP\fB]\fP
 Specify probe identifier (\fIprobe-id\fR) to trace or list (\fB\-l\fR option). You can specify probe IDs using decimal integers as shown by \fBdtrace\fR \fB\-l\fR. The \fB\-i\fR argument can be suffixed with an optional D probe clause. You can specify more than one \fB\-i\fR option at a time.
 .TP
-\fB\fB\-I\fR \fIpath\fR\fR
+\fB\-I\fP \fIpath\fP
 Add the specified directory \fIpath\fR to the search path for \fB#include\fR files when invoking \fBcpp\fR(1) (enabled using the \fB\-C\fR option). This option passes the \fB\-I\fR option to each \fBcpp\fR invocation. The specified \fIpath\fR is inserted into the search path ahead of the default directory list.
 .TP
-\fB\fB\-L\fR \fIpath\fR\fR
+\fB\-L\fP \fIpath\fP
 Add the specified directory \fIpath\fR to the search path for DTrace libraries. DTrace libraries are used to contain common definitions that can be used when writing D programs. The specified \fIpath\fR is added after the default library search path. If it exists, a subdirectory of \fIpath\fR named after the minor version of the running kernel (e.g. 3.8) is searched immediately before \fIpath\fR. (But take note: dependency analysis is performed only within each directory, not across directories.)
 .TP
-\fB\fB\-l\fR\fR
+\fB\-l\fP
 List probes instead of enabling them. If the \fB\-l\fR option is specified, \fBdtrace\fR produces a report of the probes matching the descriptions given using the \fB\-P\fR, \fB\-m\fR, \fB\-f\fR, \fB\-n\fR, \fB\-i\fR, and \fB\-s\fR options. If none of these options are specified, this option lists all probes.
 .TP
-\fB\fB\-m\fR [[\fIprovider:\fR] \fImodule:\fR [[\fIpredicate\fR] \fIaction\fR]]\fR
+\fB\-m\fP [[\fIprovider:\fP] \fImodule:\fP [[\fIpredicate\fP] \fIaction\fP]]
 Specify module name to trace or list (\fB\-l\fR option). The corresponding argument can include any of the probe description forms \fIprovider:module\fR or \fImodule\fR. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fImodule\fR are specified in the description, all probes with a corresponding \fImodule\fR are matched. The \fB\-m\fR argument can be suffixed with an optional D probe clause. More than one \fB\-m\fR option can be specified on the command line at a time.
 .TP
-\fB\fB\-n\fR [[[\fIprovider:\fR] \fImodule:\fR] \fIfunction:\fR] \fIname\fR [[\fIpredicate\fR] \fIaction\fR]\fR
+\fB\-n\fP [[[\fIprovider:\fP] \fImodule:\fP] \fIfunction:\fP] \fIname\fP [[\fIpredicate\fP] \fIaction\fP]
 Specify probe name to trace or list (\fB\-l\fR option). The corresponding argument can include any of the probe description forms \fIprovider:module:function:name\fR, \fImodule:function:name\fR, \fIfunction:name\fR, or \fIname\fR. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fIname\fR are specified in the description, all probes with a corresponding \fIname\fR are matched. The \fB\-n\fR argument can be suffixed with an optional D probe clause. More than one \fB\-n\fR option can be specified on the command line at a time.
 .TP
-\fB\fB\-o\fR \fIoutput\fR\fR
+\fB\-o\fP \fIoutput\fP
 Specify the \fIoutput\fR file for the \fB\-G\fR, \fB\-h\fR, and \fB\-l\fR options, or for the traced data itself. If the \fB\-G\fR option is present and the \fB\-s\fR option's argument is of the form \fB\fIfilename\fR.d\fR and \fB\-o\fR is not present, the default output file is \fB\fIfilename\fR.o\fR. Otherwise the default output file is \fBd.out\fR.
 .TP
-\fB\fB\-p\fR \fIpid\fR\fR
+\fB\-p\fP \fIpid\fP
 Grab the specified process-ID \fIpid\fR, cache its symbol tables, and exit upon its completion. If more than one \fB\-p\fR option is present on the command line, \fBdtrace\fR exits when all commands have exited, reporting the exit status for each process as it terminates. The first process-ID is made available to any D programs specified on the command line or using the \fB\-s\fR option through the \fB$target\fR macro variable. Refer to the \fIOracle Linux DTrace Guide\fR for more information on macro variables.
 .TP
-\fB\fB\-P\fR \fIprovider\fR \fB[[\fR\fIpredicate\fR\fB]\fR \fIaction\fR]\fR
+\fB\-P\fP \fIprovider\fP \fB[[\fP\fIpredicate\fP\fB]\fP \fIaction\fP]
 Specify provider name to trace or list (\fB\-l\fR option). The remaining probe description fields module, function, and name are left blank and match any probes regardless of the values in those fields. The \fB\-P\fR argument can be suffixed with an optional D probe clause. You can specify more than one \fB\-P\fR option on the command line at a time.
 .TP
-\fB\fB\-q\fR\fR
+\fB\-q\fP
 Set quiet mode. \fBdtrace\fR suppresses messages such as the number of probes matched by the specified options and D programs and does not print column headers, the CPU ID, the probe ID, or insert newlines into the output. Only data traced and formatted by D program statements such as \fBtrace()\fR and \fBprintf()\fR is displayed to \fBstdout\fR.
 .TP
-\fB\fB\-s\fR\fR
+\fB\-s\fP
 Compile the specified D program source file. If the \fB\-e\fR option is present, the program is compiled but instrumentation is not enabled. If the \fB\-l\fR option is present, the program is compiled and the set of probes matched by it is listed, but instrumentation is not enabled. If none of \fB\-e\fR, \fB\-l\fR, or \fB\-G\fR are present, the instrumentation specified by the D program is enabled and tracing begins.
 .TP
-\fB\fB\-S\fR\fR
+\fB\-S\fP
 Show D compiler intermediate code. The D compiler produces a report of the intermediate code generated for each D program to \fBstderr\fR.
 .TP
-\fB\fB\-U\fR \fIname\fR\fR
+\fB\-U\fP \fIname\fP
 Undefine the specified \fIname\fR when invoking \fBcpp\fR(1) (enabled using the \fB-C\fR option). This option passes the \fB-U\fR option to each \fBcpp\fR invocation.
 .TP
-\fB\fB\-v\fR\fR
+\fB\-v\fP
 Set verbose mode. If the \fB\-v\fR option is specified, \fBdtrace\fR produces a program stability report showing the minimum interface stability and dependency level for the specified D programs. DTrace stability levels are explained in further detail in the \fIOracle Linux DTrace Guide\fR.
 .TP
-\fB\fB\-V\fR\fR
+\fB\-V\fP
 Report the highest D programming interface version supported by \fBdtrace\fR. The version information is printed to \fBstdout\fR and the \fBdtrace\fR command exits. Refer to the \fIOracle Linux DTrace Guide\fR for more information about DTrace versioning features. In conjunction with \fB\-v\fR, also reports information on the version of the \fBdtrace\fR(1) tool and associated library.
 .TP
-\fB\fB\-w\fR\fR
+\fB\-w\fP
 Permit destructive actions in D programs specified using the \fB\-s\fR, \fB\-P\fR, \fB\-m\fR, \fB\-f\fR, \fB\-n\fR, or \fB\-i\fR options. If the \fB\-w\fR option is not specified, \fBdtrace\fR does not permit the compilation or enabling of a D program that contains destructive actions.
 .TP
-\fB\fB\-x\fR \fIarg\fR [\fI=val\fR]\fR
+\fB\-x\fP \fIarg\fP [\fI=val\fP]
 Enable or modify a DTrace runtime option or D compiler option. The list of options is found in the \fIOracle Linux DTrace Guide\fR. Boolean options are enabled by specifying their name. Options with values are set by separating the option name and value with an equals sign (\fB=\fR).
 .TP
-\fB\fB\-Z\fR\fR
+\fB\-Z\fP
 Permit probe descriptions that match zero probes. If the \fB\-Z\fR option is not specified, \fBdtrace\fR reports an error and exits if any probe descriptions specified in D program files (\fB\-s\fR option) or on the command line (\fB\-P\fR, \fB\-m\fR, \fB\-f\fR, \fB\-n\fR, or \fB\-i\fR options) contain descriptions that do not match any known probes.
 .
 .SH OPERANDS
-- 
2.46.0.278.g36e3a12567

Re: [PATCH 13/14] man: drop double-\fB at the start of every option line

[Kris Van Hees]

On Thu, Oct 24, 2024 at 12:37:57PM +0100, Nick Alcock wrote:
> All this does is stops \fP (which goes back to the previous font)
> from working.  (The manpage looks fine afterwards, both on
> the terminal and typeset.)
> 
> Signed-off-by: Nick Alcock <nick.alcock@oracle.com>

Reviewed-by: Kris Van Hees <kris.van.hees@oracle.com>

> ---
>  cmd/dtrace.8 | 56 ++++++++++++++++++++++++++--------------------------
>  1 file changed, 28 insertions(+), 28 deletions(-)
> 
> diff --git a/cmd/dtrace.8 b/cmd/dtrace.8
> index c299073239eb..355484bd0d34 100644
> --- a/cmd/dtrace.8
> +++ b/cmd/dtrace.8
> @@ -64,88 +64,88 @@ The arguments accepted by the \fB\-P\fR, \fB\-m\fR, \fB\-f\fR, \fB\-n\fR, and \f
>  .LP
>  The following options are supported:
>  .TP
> -\fB\fB\-b\fR \fIbufsz\fR\fR
> +\fB\-b\fP \fIbufsz\fP
>  Set principal trace buffer size (\fIbufsz\fR). The trace buffer size can include any of the size suffixes \fBk\fR, \fBm\fR, \fBg\fR, or \fBt\fR. If the buffer space cannot be allocated, \fBdtrace\fR attempts to reduce the buffer size or exit depending on the setting of the \fBbufresize\fR property.
>  .TP
> -\fB\fB\-c\fR \fIcmd\fR\fR
> +\fB\-c\fP \fIcmd\fP
>  Run the specified command \fIcmd\fR and exit upon its completion. If more than one \fB\-c\fR option is present on the command line, \fBdtrace\fR exits when all commands have exited, reporting the exit status for each child process as it terminates. The process-ID of the first command is made available to any D programs specified on the command line or using the \fB\-s\fR option through the \fB$target\fR macro variable. Refer to the \fIOracle Linux DTrace Guide\fR for more information on macro variables.
>  .TP
> -\fB\fB\-C\fR\fR
> +\fB\-C\fP
>  Run the C preprocessor \fBcpp\fR(1) over D programs before compiling them. You can pass options to the C preprocessor using the \fB\-D\fR, \fB\-U\fR, \fB\-I\fR, and \fB\-H\fR options. You can select the degree of C standard conformance if you use the \fB\-X\fR option. For a description of the set of tokens defined by the D compiler when invoking the C preprocessor, see \fB\-X\fR.
>  .TP
> -\fB\fB\-D\fR \fIname\fR \fB[=\fR\fIvalue\fR\fB]\fR\fR
> +\fB\-D\fP \fIname\fP \fB[=\fP\fIvalue\fP\fB]\fP
>  Define \fIname\fR when invoking \fBcpp\fR(1) (enabled using the \fB\-C\fR option). If you specify the equals sign (\fB=\fR) and additional \fIvalue\fR, the name is assigned the corresponding value. This option passes the \fB\-D\fR option to each \fBcpp\fR invocation.
>  .TP
> -\fB\fB\-e\fR\fR
> +\fB\-e\fP
>  Exit after compiling any requests, but prior to enabling any probes. You can combine this option with D compiler options. This combination verifies that the programs compile without actually executing them and enabling the corresponding instrumentation.
>  .TP
> -\fB\fB\-f\fR\fB[[\fR\fIprovider\fR\fB:]\fR\fImodule\fR\fB:]\fR\fIfunction\fR\fB[[\fR\fIpredicate\fR\fB]\fR\fIaction\fR\fB]]\fR\fR
> +\fB\-f\fP\fB[[\fP\fIprovider\fP\fB:]\fP\fImodule\fP\fB:]\fP\fIfunction\fP\fB[[\fP\fIpredicate\fP\fB]\fP\fIaction\fP\fB]]\fP
>  Specify function name to trace or list (\fB\-l\fR option). The corresponding argument can include any of the probe description forms \fIprovider:module:function\fR, \fImodule:function\fR, or \fIfunction\fR. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fIfunction\fR are specified in the description, all probes with the corresponding \fIfunction\fR are matched. The \fB\-f\fR argument can be suffixed with an optional D probe clause. You can specify more than one \fB\-f\fR option on the command line at a time.
>  .TP
> -\fB\fB\-F\fR\fR
> +\fB\-F\fP
>  Coalesce trace output by identifying function entry and return. Function entry probe reports are indented and their output is prefixed with \fB->\fR. Function return probe reports are unindented and their output is prefixed with \fB<-\fR\&. System call entry probe reports are indented and their output is prefixed with \fB=>\fR. System call return probe reports are unindented and their output is prefixed with \fB<=\fR\&.
>  .TP
> -\fB\fB\-G\fR\fR
> +\fB\-G\fP
>  Generate an ELF file containing an embedded DTrace program. The DTrace probes specified in the program are saved inside of a relocatable ELF object which can be linked into another program. If the \fB\-o\fR option is present, the ELF file is saved using the pathname specified as the argument for this operand. If the \fB\-o\fR option is not present and the DTrace program is contained with a file whose name is \fB\fIfilename\fR.d\fR, then the ELF file is saved using the name \fB\fIfilename\fR.o\fR. Otherwise the ELF file is saved using the name \fBd.out\fR.
>  .TP
> -\fB\fB\-H\fR\fR
> +\fB\-H\fP
>  Print the pathnames of included files when invoking \fBcpp\fR(1) (enabled using the \fB\-C\fR option). This option passes the \fB\-H\fR option to each \fBcpp\fR invocation, causing it to display the list of pathnames, one for each line, to \fBstderr\fR.
>  .TP
> -\fB\fB\-h\fR\fR
> +\fB\-h\fP
>  Generate a header file containing macros that correspond to probes in the specified provider definitions. This option should be used to generate a header file that is included by other source files for later use with the \fB\-G\fR option. If the \fB\-o\fR option is present, the header file is saved using the pathname specified as the argument for that option. If the \fB\-o\fR option is not present and the DTrace program is contained with a file whose name is \fIfilename\fR\fB\&.d\fR, then the header file is saved using the name \fIfilename\fR\fB\&.h\fR.
>  .TP
> -\fB\fB\-i\fR \fIprobe-id\fR\fB[[\fR\fIpredicate\fR] \fIaction\fR\fB]\fR\fR
> +\fB\-i\fP \fIprobe-id\fP\fB[[\fP\fIpredicate\fP] \fIaction\fP\fB]\fP
>  Specify probe identifier (\fIprobe-id\fR) to trace or list (\fB\-l\fR option). You can specify probe IDs using decimal integers as shown by \fBdtrace\fR \fB\-l\fR. The \fB\-i\fR argument can be suffixed with an optional D probe clause. You can specify more than one \fB\-i\fR option at a time.
>  .TP
> -\fB\fB\-I\fR \fIpath\fR\fR
> +\fB\-I\fP \fIpath\fP
>  Add the specified directory \fIpath\fR to the search path for \fB#include\fR files when invoking \fBcpp\fR(1) (enabled using the \fB\-C\fR option). This option passes the \fB\-I\fR option to each \fBcpp\fR invocation. The specified \fIpath\fR is inserted into the search path ahead of the default directory list.
>  .TP
> -\fB\fB\-L\fR \fIpath\fR\fR
> +\fB\-L\fP \fIpath\fP
>  Add the specified directory \fIpath\fR to the search path for DTrace libraries. DTrace libraries are used to contain common definitions that can be used when writing D programs. The specified \fIpath\fR is added after the default library search path. If it exists, a subdirectory of \fIpath\fR named after the minor version of the running kernel (e.g. 3.8) is searched immediately before \fIpath\fR. (But take note: dependency analysis is performed only within each directory, not across directories.)
>  .TP
> -\fB\fB\-l\fR\fR
> +\fB\-l\fP
>  List probes instead of enabling them. If the \fB\-l\fR option is specified, \fBdtrace\fR produces a report of the probes matching the descriptions given using the \fB\-P\fR, \fB\-m\fR, \fB\-f\fR, \fB\-n\fR, \fB\-i\fR, and \fB\-s\fR options. If none of these options are specified, this option lists all probes.
>  .TP
> -\fB\fB\-m\fR [[\fIprovider:\fR] \fImodule:\fR [[\fIpredicate\fR] \fIaction\fR]]\fR
> +\fB\-m\fP [[\fIprovider:\fP] \fImodule:\fP [[\fIpredicate\fP] \fIaction\fP]]
>  Specify module name to trace or list (\fB\-l\fR option). The corresponding argument can include any of the probe description forms \fIprovider:module\fR or \fImodule\fR. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fImodule\fR are specified in the description, all probes with a corresponding \fImodule\fR are matched. The \fB\-m\fR argument can be suffixed with an optional D probe clause. More than one \fB\-m\fR option can be specified on the command line at a time.
>  .TP
> -\fB\fB\-n\fR [[[\fIprovider:\fR] \fImodule:\fR] \fIfunction:\fR] \fIname\fR [[\fIpredicate\fR] \fIaction\fR]\fR
> +\fB\-n\fP [[[\fIprovider:\fP] \fImodule:\fP] \fIfunction:\fP] \fIname\fP [[\fIpredicate\fP] \fIaction\fP]
>  Specify probe name to trace or list (\fB\-l\fR option). The corresponding argument can include any of the probe description forms \fIprovider:module:function:name\fR, \fImodule:function:name\fR, \fIfunction:name\fR, or \fIname\fR. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fIname\fR are specified in the description, all probes with a corresponding \fIname\fR are matched. The \fB\-n\fR argument can be suffixed with an optional D probe clause. More than one \fB\-n\fR option can be specified on the command line at a time.
>  .TP
> -\fB\fB\-o\fR \fIoutput\fR\fR
> +\fB\-o\fP \fIoutput\fP
>  Specify the \fIoutput\fR file for the \fB\-G\fR, \fB\-h\fR, and \fB\-l\fR options, or for the traced data itself. If the \fB\-G\fR option is present and the \fB\-s\fR option's argument is of the form \fB\fIfilename\fR.d\fR and \fB\-o\fR is not present, the default output file is \fB\fIfilename\fR.o\fR. Otherwise the default output file is \fBd.out\fR.
>  .TP
> -\fB\fB\-p\fR \fIpid\fR\fR
> +\fB\-p\fP \fIpid\fP
>  Grab the specified process-ID \fIpid\fR, cache its symbol tables, and exit upon its completion. If more than one \fB\-p\fR option is present on the command line, \fBdtrace\fR exits when all commands have exited, reporting the exit status for each process as it terminates. The first process-ID is made available to any D programs specified on the command line or using the \fB\-s\fR option through the \fB$target\fR macro variable. Refer to the \fIOracle Linux DTrace Guide\fR for more information on macro variables.
>  .TP
> -\fB\fB\-P\fR \fIprovider\fR \fB[[\fR\fIpredicate\fR\fB]\fR \fIaction\fR]\fR
> +\fB\-P\fP \fIprovider\fP \fB[[\fP\fIpredicate\fP\fB]\fP \fIaction\fP]
>  Specify provider name to trace or list (\fB\-l\fR option). The remaining probe description fields module, function, and name are left blank and match any probes regardless of the values in those fields. The \fB\-P\fR argument can be suffixed with an optional D probe clause. You can specify more than one \fB\-P\fR option on the command line at a time.
>  .TP
> -\fB\fB\-q\fR\fR
> +\fB\-q\fP
>  Set quiet mode. \fBdtrace\fR suppresses messages such as the number of probes matched by the specified options and D programs and does not print column headers, the CPU ID, the probe ID, or insert newlines into the output. Only data traced and formatted by D program statements such as \fBtrace()\fR and \fBprintf()\fR is displayed to \fBstdout\fR.
>  .TP
> -\fB\fB\-s\fR\fR
> +\fB\-s\fP
>  Compile the specified D program source file. If the \fB\-e\fR option is present, the program is compiled but instrumentation is not enabled. If the \fB\-l\fR option is present, the program is compiled and the set of probes matched by it is listed, but instrumentation is not enabled. If none of \fB\-e\fR, \fB\-l\fR, or \fB\-G\fR are present, the instrumentation specified by the D program is enabled and tracing begins.
>  .TP
> -\fB\fB\-S\fR\fR
> +\fB\-S\fP
>  Show D compiler intermediate code. The D compiler produces a report of the intermediate code generated for each D program to \fBstderr\fR.
>  .TP
> -\fB\fB\-U\fR \fIname\fR\fR
> +\fB\-U\fP \fIname\fP
>  Undefine the specified \fIname\fR when invoking \fBcpp\fR(1) (enabled using the \fB-C\fR option). This option passes the \fB-U\fR option to each \fBcpp\fR invocation.
>  .TP
> -\fB\fB\-v\fR\fR
> +\fB\-v\fP
>  Set verbose mode. If the \fB\-v\fR option is specified, \fBdtrace\fR produces a program stability report showing the minimum interface stability and dependency level for the specified D programs. DTrace stability levels are explained in further detail in the \fIOracle Linux DTrace Guide\fR.
>  .TP
> -\fB\fB\-V\fR\fR
> +\fB\-V\fP
>  Report the highest D programming interface version supported by \fBdtrace\fR. The version information is printed to \fBstdout\fR and the \fBdtrace\fR command exits. Refer to the \fIOracle Linux DTrace Guide\fR for more information about DTrace versioning features. In conjunction with \fB\-v\fR, also reports information on the version of the \fBdtrace\fR(1) tool and associated library.
>  .TP
> -\fB\fB\-w\fR\fR
> +\fB\-w\fP
>  Permit destructive actions in D programs specified using the \fB\-s\fR, \fB\-P\fR, \fB\-m\fR, \fB\-f\fR, \fB\-n\fR, or \fB\-i\fR options. If the \fB\-w\fR option is not specified, \fBdtrace\fR does not permit the compilation or enabling of a D program that contains destructive actions.
>  .TP
> -\fB\fB\-x\fR \fIarg\fR [\fI=val\fR]\fR
> +\fB\-x\fP \fIarg\fP [\fI=val\fP]
>  Enable or modify a DTrace runtime option or D compiler option. The list of options is found in the \fIOracle Linux DTrace Guide\fR. Boolean options are enabled by specifying their name. Options with values are set by separating the option name and value with an equals sign (\fB=\fR).
>  .TP
> -\fB\fB\-Z\fR\fR
> +\fB\-Z\fP
>  Permit probe descriptions that match zero probes. If the \fB\-Z\fR option is not specified, \fBdtrace\fR reports an error and exits if any probe descriptions specified in D program files (\fB\-s\fR option) or on the command line (\fB\-P\fR, \fB\-m\fR, \fB\-f\fR, \fB\-n\fR, or \fB\-i\fR options) contain descriptions that do not match any known probes.
>  .
>  .SH OPERANDS
> -- 
> 2.46.0.278.g36e3a12567
> 

[PATCH 14/14] man: \fP-ize

[Nick Alcock]

This adjusts everything to use \fN...\fP rather than \fN...\fR everywhere:
the few places that were using \fP (usually \fB\fIfilename\fP.ext\fR) were
re-expressed into \fIfilename\fP\fB.ext\fP. \& was added in the instances
of this pattern that weren't using it (about half were).

No effect on terminal or typeset output, other than very slightly improved
layout around the filename stuff above.

Signed-off-by: Nick Alcock <nick.alcock@oracle.com>
---
 cmd/dtrace.8 | 72 ++++++++++++++++++++++++++--------------------------
 1 file changed, 36 insertions(+), 36 deletions(-)

diff --git a/cmd/dtrace.8 b/cmd/dtrace.8
index 355484bd0d34..1f2d48a07531 100644
--- a/cmd/dtrace.8
+++ b/cmd/dtrace.8
@@ -39,9 +39,9 @@ dtrace \- DTrace dynamic tracing compiler and tracing utility
 .LP
 DTrace is a comprehensive dynamic tracing framework for the Linux operating system. DTrace provides a powerful infrastructure that permits administrators, developers, and service personnel to concisely answer arbitrary questions about the behavior of the operating system and user programs. 
 .LP
-The \fIOracle Linux DTrace Guide\fR describes how to use DTrace to observe, debug, and tune system behavior. Refer to this book for a detailed description of DTrace features, including the bundled DTrace observability tools, instrumentation providers, and the D programming language.
+The \fIOracle Linux DTrace Guide\fP describes how to use DTrace to observe, debug, and tune system behavior. Refer to this book for a detailed description of DTrace features, including the bundled DTrace observability tools, instrumentation providers, and the D programming language.
 .LP
-The \fBdtrace\fR command provides a generic interface to the essential services provided by the DTrace facility, including:
+The \fBdtrace\fP command provides a generic interface to the essential services provided by the DTrace facility, including:
 .RS +4
 .IP o
 Options that list the set of probes and providers currently published by DTrace
@@ -57,100 +57,100 @@ Options that generate program stability reports
 Options that modify DTrace tracing and buffering behavior and enable additional D compiler features
 .RE
 .LP
-You can use \fBdtrace\fR to create D scripts by using it in a \fB#!\fR declaration to create an interpreter file. You can also use \fBdtrace\fR to attempt to compile D programs and determine their properties without actually enabling tracing using the \fB\-e\fR option. See \fBOPTIONS\fR. See the \fIOracle Linux DTrace Guide\fR for detailed examples of how to use the \fBdtrace\fR utility to perform these tasks.
+You can use \fBdtrace\fP to create D scripts by using it in a \fB#!\fP declaration to create an interpreter file. You can also use \fBdtrace\fP to attempt to compile D programs and determine their properties without actually enabling tracing using the \fB\-e\fP option. See \fBOPTIONS\fP. See the \fIOracle Linux DTrace Guide\fP for detailed examples of how to use the \fBdtrace\fP utility to perform these tasks.
 .SH OPTIONS
 .LP
-The arguments accepted by the \fB\-P\fR, \fB\-m\fR, \fB\-f\fR, \fB\-n\fR, and \fB\-i\fR options can include an optional D language \fIpredicate\fR enclosed in slashes \fB//\fR and optional D language \fIaction\fR statement list enclosed in braces \fB{}\fR. D program code specified on the command line must be appropriately quoted to avoid interpretation of meta-characters by the shell.
+The arguments accepted by the \fB\-P\fP, \fB\-m\fP, \fB\-f\fP, \fB\-n\fP, and \fB\-i\fP options can include an optional D language \fIpredicate\fP enclosed in slashes \fB//\fP and optional D language \fIaction\fP statement list enclosed in braces \fB{}\fP. D program code specified on the command line must be appropriately quoted to avoid interpretation of meta-characters by the shell.
 .LP
 The following options are supported:
 .TP
 \fB\-b\fP \fIbufsz\fP
-Set principal trace buffer size (\fIbufsz\fR). The trace buffer size can include any of the size suffixes \fBk\fR, \fBm\fR, \fBg\fR, or \fBt\fR. If the buffer space cannot be allocated, \fBdtrace\fR attempts to reduce the buffer size or exit depending on the setting of the \fBbufresize\fR property.
+Set principal trace buffer size (\fIbufsz\fP). The trace buffer size can include any of the size suffixes \fBk\fP, \fBm\fP, \fBg\fP, or \fBt\fP. If the buffer space cannot be allocated, \fBdtrace\fP attempts to reduce the buffer size or exit depending on the setting of the \fBbufresize\fP property.
 .TP
 \fB\-c\fP \fIcmd\fP
-Run the specified command \fIcmd\fR and exit upon its completion. If more than one \fB\-c\fR option is present on the command line, \fBdtrace\fR exits when all commands have exited, reporting the exit status for each child process as it terminates. The process-ID of the first command is made available to any D programs specified on the command line or using the \fB\-s\fR option through the \fB$target\fR macro variable. Refer to the \fIOracle Linux DTrace Guide\fR for more information on macro variables.
+Run the specified command \fIcmd\fP and exit upon its completion. If more than one \fB\-c\fP option is present on the command line, \fBdtrace\fP exits when all commands have exited, reporting the exit status for each child process as it terminates. The process-ID of the first command is made available to any D programs specified on the command line or using the \fB\-s\fP option through the \fB$target\fP macro variable. Refer to the \fIOracle Linux DTrace Guide\fP for more information on macro variables.
 .TP
 \fB\-C\fP
-Run the C preprocessor \fBcpp\fR(1) over D programs before compiling them. You can pass options to the C preprocessor using the \fB\-D\fR, \fB\-U\fR, \fB\-I\fR, and \fB\-H\fR options. You can select the degree of C standard conformance if you use the \fB\-X\fR option. For a description of the set of tokens defined by the D compiler when invoking the C preprocessor, see \fB\-X\fR.
+Run the C preprocessor \fBcpp\fP(1) over D programs before compiling them. You can pass options to the C preprocessor using the \fB\-D\fP, \fB\-U\fP, \fB\-I\fP, and \fB\-H\fP options. You can select the degree of C standard conformance if you use the \fB\-X\fP option. For a description of the set of tokens defined by the D compiler when invoking the C preprocessor, see \fB\-X\fP.
 .TP
 \fB\-D\fP \fIname\fP \fB[=\fP\fIvalue\fP\fB]\fP
-Define \fIname\fR when invoking \fBcpp\fR(1) (enabled using the \fB\-C\fR option). If you specify the equals sign (\fB=\fR) and additional \fIvalue\fR, the name is assigned the corresponding value. This option passes the \fB\-D\fR option to each \fBcpp\fR invocation.
+Define \fIname\fP when invoking \fBcpp\fP(1) (enabled using the \fB\-C\fP option). If you specify the equals sign (\fB=\fP) and additional \fIvalue\fP, the name is assigned the corresponding value. This option passes the \fB\-D\fP option to each \fBcpp\fP invocation.
 .TP
 \fB\-e\fP
 Exit after compiling any requests, but prior to enabling any probes. You can combine this option with D compiler options. This combination verifies that the programs compile without actually executing them and enabling the corresponding instrumentation.
 .TP
 \fB\-f\fP\fB[[\fP\fIprovider\fP\fB:]\fP\fImodule\fP\fB:]\fP\fIfunction\fP\fB[[\fP\fIpredicate\fP\fB]\fP\fIaction\fP\fB]]\fP
-Specify function name to trace or list (\fB\-l\fR option). The corresponding argument can include any of the probe description forms \fIprovider:module:function\fR, \fImodule:function\fR, or \fIfunction\fR. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fIfunction\fR are specified in the description, all probes with the corresponding \fIfunction\fR are matched. The \fB\-f\fR argument can be suffixed with an optional D probe clause. You can specify more than one \fB\-f\fR option on the command line at a time.
+Specify function name to trace or list (\fB\-l\fP option). The corresponding argument can include any of the probe description forms \fIprovider:module:function\fP, \fImodule:function\fP, or \fIfunction\fP. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fIfunction\fP are specified in the description, all probes with the corresponding \fIfunction\fP are matched. The \fB\-f\fP argument can be suffixed with an optional D probe clause. You can specify more than one \fB\-f\fP option on the command line at a time.
 .TP
 \fB\-F\fP
-Coalesce trace output by identifying function entry and return. Function entry probe reports are indented and their output is prefixed with \fB->\fR. Function return probe reports are unindented and their output is prefixed with \fB<-\fR\&. System call entry probe reports are indented and their output is prefixed with \fB=>\fR. System call return probe reports are unindented and their output is prefixed with \fB<=\fR\&.
+Coalesce trace output by identifying function entry and return. Function entry probe reports are indented and their output is prefixed with \fB->\fP. Function return probe reports are unindented and their output is prefixed with \fB<-\fP\&. System call entry probe reports are indented and their output is prefixed with \fB=>\fP. System call return probe reports are unindented and their output is prefixed with \fB<=\fP\&.
 .TP
 \fB\-G\fP
-Generate an ELF file containing an embedded DTrace program. The DTrace probes specified in the program are saved inside of a relocatable ELF object which can be linked into another program. If the \fB\-o\fR option is present, the ELF file is saved using the pathname specified as the argument for this operand. If the \fB\-o\fR option is not present and the DTrace program is contained with a file whose name is \fB\fIfilename\fR.d\fR, then the ELF file is saved using the name \fB\fIfilename\fR.o\fR. Otherwise the ELF file is saved using the name \fBd.out\fR.
+Generate an ELF file containing an embedded DTrace program. The DTrace probes specified in the program are saved inside of a relocatable ELF object which can be linked into another program. If the \fB\-o\fP option is present, the ELF file is saved using the pathname specified as the argument for this operand. If the \fB\-o\fP option is not present and the DTrace program is contained with a file whose name is \fIfilename\fP\fB\&.d\fP, then the ELF file is saved using the name \fIfilename\fP\fB\&.o\fP. Otherwise the ELF file is saved using the name \fBd.out\fP.
 .TP
 \fB\-H\fP
-Print the pathnames of included files when invoking \fBcpp\fR(1) (enabled using the \fB\-C\fR option). This option passes the \fB\-H\fR option to each \fBcpp\fR invocation, causing it to display the list of pathnames, one for each line, to \fBstderr\fR.
+Print the pathnames of included files when invoking \fBcpp\fP(1) (enabled using the \fB\-C\fP option). This option passes the \fB\-H\fP option to each \fBcpp\fP invocation, causing it to display the list of pathnames, one for each line, to \fBstderr\fP.
 .TP
 \fB\-h\fP
-Generate a header file containing macros that correspond to probes in the specified provider definitions. This option should be used to generate a header file that is included by other source files for later use with the \fB\-G\fR option. If the \fB\-o\fR option is present, the header file is saved using the pathname specified as the argument for that option. If the \fB\-o\fR option is not present and the DTrace program is contained with a file whose name is \fIfilename\fR\fB\&.d\fR, then the header file is saved using the name \fIfilename\fR\fB\&.h\fR.
+Generate a header file containing macros that correspond to probes in the specified provider definitions. This option should be used to generate a header file that is included by other source files for later use with the \fB\-G\fP option. If the \fB\-o\fP option is present, the header file is saved using the pathname specified as the argument for that option. If the \fB\-o\fP option is not present and the DTrace program is contained with a file whose name is \fIfilename\fP\fB\&.d\fP, then the header file is saved using the name \fIfilename\fP\fB\&.h\fP.
 .TP
 \fB\-i\fP \fIprobe-id\fP\fB[[\fP\fIpredicate\fP] \fIaction\fP\fB]\fP
-Specify probe identifier (\fIprobe-id\fR) to trace or list (\fB\-l\fR option). You can specify probe IDs using decimal integers as shown by \fBdtrace\fR \fB\-l\fR. The \fB\-i\fR argument can be suffixed with an optional D probe clause. You can specify more than one \fB\-i\fR option at a time.
+Specify probe identifier (\fIprobe-id\fP) to trace or list (\fB\-l\fP option). You can specify probe IDs using decimal integers as shown by \fBdtrace\fP \fB\-l\fP. The \fB\-i\fP argument can be suffixed with an optional D probe clause. You can specify more than one \fB\-i\fP option at a time.
 .TP
 \fB\-I\fP \fIpath\fP
-Add the specified directory \fIpath\fR to the search path for \fB#include\fR files when invoking \fBcpp\fR(1) (enabled using the \fB\-C\fR option). This option passes the \fB\-I\fR option to each \fBcpp\fR invocation. The specified \fIpath\fR is inserted into the search path ahead of the default directory list.
+Add the specified directory \fIpath\fP to the search path for \fB#include\fP files when invoking \fBcpp\fP(1) (enabled using the \fB\-C\fP option). This option passes the \fB\-I\fP option to each \fBcpp\fP invocation. The specified \fIpath\fP is inserted into the search path ahead of the default directory list.
 .TP
 \fB\-L\fP \fIpath\fP
-Add the specified directory \fIpath\fR to the search path for DTrace libraries. DTrace libraries are used to contain common definitions that can be used when writing D programs. The specified \fIpath\fR is added after the default library search path. If it exists, a subdirectory of \fIpath\fR named after the minor version of the running kernel (e.g. 3.8) is searched immediately before \fIpath\fR. (But take note: dependency analysis is performed only within each directory, not across directories.)
+Add the specified directory \fIpath\fP to the search path for DTrace libraries. DTrace libraries are used to contain common definitions that can be used when writing D programs. The specified \fIpath\fP is added after the default library search path. If it exists, a subdirectory of \fIpath\fP named after the minor version of the running kernel (e.g. 3.8) is searched immediately before \fIpath\fP. (But take note: dependency analysis is performed only within each directory, not across directories.)
 .TP
 \fB\-l\fP
-List probes instead of enabling them. If the \fB\-l\fR option is specified, \fBdtrace\fR produces a report of the probes matching the descriptions given using the \fB\-P\fR, \fB\-m\fR, \fB\-f\fR, \fB\-n\fR, \fB\-i\fR, and \fB\-s\fR options. If none of these options are specified, this option lists all probes.
+List probes instead of enabling them. If the \fB\-l\fP option is specified, \fBdtrace\fP produces a report of the probes matching the descriptions given using the \fB\-P\fP, \fB\-m\fP, \fB\-f\fP, \fB\-n\fP, \fB\-i\fP, and \fB\-s\fP options. If none of these options are specified, this option lists all probes.
 .TP
 \fB\-m\fP [[\fIprovider:\fP] \fImodule:\fP [[\fIpredicate\fP] \fIaction\fP]]
-Specify module name to trace or list (\fB\-l\fR option). The corresponding argument can include any of the probe description forms \fIprovider:module\fR or \fImodule\fR. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fImodule\fR are specified in the description, all probes with a corresponding \fImodule\fR are matched. The \fB\-m\fR argument can be suffixed with an optional D probe clause. More than one \fB\-m\fR option can be specified on the command line at a time.
+Specify module name to trace or list (\fB\-l\fP option). The corresponding argument can include any of the probe description forms \fIprovider:module\fP or \fImodule\fP. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fImodule\fP are specified in the description, all probes with a corresponding \fImodule\fP are matched. The \fB\-m\fP argument can be suffixed with an optional D probe clause. More than one \fB\-m\fP option can be specified on the command line at a time.
 .TP
 \fB\-n\fP [[[\fIprovider:\fP] \fImodule:\fP] \fIfunction:\fP] \fIname\fP [[\fIpredicate\fP] \fIaction\fP]
-Specify probe name to trace or list (\fB\-l\fR option). The corresponding argument can include any of the probe description forms \fIprovider:module:function:name\fR, \fImodule:function:name\fR, \fIfunction:name\fR, or \fIname\fR. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fIname\fR are specified in the description, all probes with a corresponding \fIname\fR are matched. The \fB\-n\fR argument can be suffixed with an optional D probe clause. More than one \fB\-n\fR option can be specified on the command line at a time.
+Specify probe name to trace or list (\fB\-l\fP option). The corresponding argument can include any of the probe description forms \fIprovider:module:function:name\fP, \fImodule:function:name\fP, \fIfunction:name\fP, or \fIname\fP. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fIname\fP are specified in the description, all probes with a corresponding \fIname\fP are matched. The \fB\-n\fP argument can be suffixed with an optional D probe clause. More than one \fB\-n\fP option can be specified on the command line at a time.
 .TP
 \fB\-o\fP \fIoutput\fP
-Specify the \fIoutput\fR file for the \fB\-G\fR, \fB\-h\fR, and \fB\-l\fR options, or for the traced data itself. If the \fB\-G\fR option is present and the \fB\-s\fR option's argument is of the form \fB\fIfilename\fR.d\fR and \fB\-o\fR is not present, the default output file is \fB\fIfilename\fR.o\fR. Otherwise the default output file is \fBd.out\fR.
+Specify the \fIoutput\fP file for the \fB\-G\fP, \fB\-h\fP, and \fB\-l\fP options, or for the traced data itself. If the \fB\-G\fP option is present and the \fB\-s\fP option's argument is of the form \fIfilename\fP\fB\&.d\fP and \fB\-o\fP is not present, the default output file is \fIfilename\fP\fB\&.o\fP. Otherwise the default output file is \fBd.out\fP.
 .TP
 \fB\-p\fP \fIpid\fP
-Grab the specified process-ID \fIpid\fR, cache its symbol tables, and exit upon its completion. If more than one \fB\-p\fR option is present on the command line, \fBdtrace\fR exits when all commands have exited, reporting the exit status for each process as it terminates. The first process-ID is made available to any D programs specified on the command line or using the \fB\-s\fR option through the \fB$target\fR macro variable. Refer to the \fIOracle Linux DTrace Guide\fR for more information on macro variables.
+Grab the specified process-ID \fIpid\fP, cache its symbol tables, and exit upon its completion. If more than one \fB\-p\fP option is present on the command line, \fBdtrace\fP exits when all commands have exited, reporting the exit status for each process as it terminates. The first process-ID is made available to any D programs specified on the command line or using the \fB\-s\fP option through the \fB$target\fP macro variable. Refer to the \fIOracle Linux DTrace Guide\fP for more information on macro variables.
 .TP
 \fB\-P\fP \fIprovider\fP \fB[[\fP\fIpredicate\fP\fB]\fP \fIaction\fP]
-Specify provider name to trace or list (\fB\-l\fR option). The remaining probe description fields module, function, and name are left blank and match any probes regardless of the values in those fields. The \fB\-P\fR argument can be suffixed with an optional D probe clause. You can specify more than one \fB\-P\fR option on the command line at a time.
+Specify provider name to trace or list (\fB\-l\fP option). The remaining probe description fields module, function, and name are left blank and match any probes regardless of the values in those fields. The \fB\-P\fP argument can be suffixed with an optional D probe clause. You can specify more than one \fB\-P\fP option on the command line at a time.
 .TP
 \fB\-q\fP
-Set quiet mode. \fBdtrace\fR suppresses messages such as the number of probes matched by the specified options and D programs and does not print column headers, the CPU ID, the probe ID, or insert newlines into the output. Only data traced and formatted by D program statements such as \fBtrace()\fR and \fBprintf()\fR is displayed to \fBstdout\fR.
+Set quiet mode. \fBdtrace\fP suppresses messages such as the number of probes matched by the specified options and D programs and does not print column headers, the CPU ID, the probe ID, or insert newlines into the output. Only data traced and formatted by D program statements such as \fBtrace()\fP and \fBprintf()\fP is displayed to \fBstdout\fP.
 .TP
 \fB\-s\fP
-Compile the specified D program source file. If the \fB\-e\fR option is present, the program is compiled but instrumentation is not enabled. If the \fB\-l\fR option is present, the program is compiled and the set of probes matched by it is listed, but instrumentation is not enabled. If none of \fB\-e\fR, \fB\-l\fR, or \fB\-G\fR are present, the instrumentation specified by the D program is enabled and tracing begins.
+Compile the specified D program source file. If the \fB\-e\fP option is present, the program is compiled but instrumentation is not enabled. If the \fB\-l\fP option is present, the program is compiled and the set of probes matched by it is listed, but instrumentation is not enabled. If none of \fB\-e\fP, \fB\-l\fP, or \fB\-G\fP are present, the instrumentation specified by the D program is enabled and tracing begins.
 .TP
 \fB\-S\fP
-Show D compiler intermediate code. The D compiler produces a report of the intermediate code generated for each D program to \fBstderr\fR.
+Show D compiler intermediate code. The D compiler produces a report of the intermediate code generated for each D program to \fBstderr\fP.
 .TP
 \fB\-U\fP \fIname\fP
-Undefine the specified \fIname\fR when invoking \fBcpp\fR(1) (enabled using the \fB-C\fR option). This option passes the \fB-U\fR option to each \fBcpp\fR invocation.
+Undefine the specified \fIname\fP when invoking \fBcpp\fP(1) (enabled using the \fB-C\fP option). This option passes the \fB-U\fP option to each \fBcpp\fP invocation.
 .TP
 \fB\-v\fP
-Set verbose mode. If the \fB\-v\fR option is specified, \fBdtrace\fR produces a program stability report showing the minimum interface stability and dependency level for the specified D programs. DTrace stability levels are explained in further detail in the \fIOracle Linux DTrace Guide\fR.
+Set verbose mode. If the \fB\-v\fP option is specified, \fBdtrace\fP produces a program stability report showing the minimum interface stability and dependency level for the specified D programs. DTrace stability levels are explained in further detail in the \fIOracle Linux DTrace Guide\fP.
 .TP
 \fB\-V\fP
-Report the highest D programming interface version supported by \fBdtrace\fR. The version information is printed to \fBstdout\fR and the \fBdtrace\fR command exits. Refer to the \fIOracle Linux DTrace Guide\fR for more information about DTrace versioning features. In conjunction with \fB\-v\fR, also reports information on the version of the \fBdtrace\fR(1) tool and associated library.
+Report the highest D programming interface version supported by \fBdtrace\fP. The version information is printed to \fBstdout\fP and the \fBdtrace\fP command exits. Refer to the \fIOracle Linux DTrace Guide\fP for more information about DTrace versioning features. In conjunction with \fB\-v\fP, also reports information on the version of the \fBdtrace\fP(1) tool and associated library.
 .TP
 \fB\-w\fP
-Permit destructive actions in D programs specified using the \fB\-s\fR, \fB\-P\fR, \fB\-m\fR, \fB\-f\fR, \fB\-n\fR, or \fB\-i\fR options. If the \fB\-w\fR option is not specified, \fBdtrace\fR does not permit the compilation or enabling of a D program that contains destructive actions.
+Permit destructive actions in D programs specified using the \fB\-s\fP, \fB\-P\fP, \fB\-m\fP, \fB\-f\fP, \fB\-n\fP, or \fB\-i\fP options. If the \fB\-w\fP option is not specified, \fBdtrace\fP does not permit the compilation or enabling of a D program that contains destructive actions.
 .TP
 \fB\-x\fP \fIarg\fP [\fI=val\fP]
-Enable or modify a DTrace runtime option or D compiler option. The list of options is found in the \fIOracle Linux DTrace Guide\fR. Boolean options are enabled by specifying their name. Options with values are set by separating the option name and value with an equals sign (\fB=\fR).
+Enable or modify a DTrace runtime option or D compiler option. The list of options is found in the \fIOracle Linux DTrace Guide\fP. Boolean options are enabled by specifying their name. Options with values are set by separating the option name and value with an equals sign (\fB=\fP).
 .TP
 \fB\-Z\fP
-Permit probe descriptions that match zero probes. If the \fB\-Z\fR option is not specified, \fBdtrace\fR reports an error and exits if any probe descriptions specified in D program files (\fB\-s\fR option) or on the command line (\fB\-P\fR, \fB\-m\fR, \fB\-f\fR, \fB\-n\fR, or \fB\-i\fR options) contain descriptions that do not match any known probes.
+Permit probe descriptions that match zero probes. If the \fB\-Z\fP option is not specified, \fBdtrace\fP reports an error and exits if any probe descriptions specified in D program files (\fB\-s\fP option) or on the command line (\fB\-P\fP, \fB\-m\fP, \fB\-f\fP, \fB\-n\fP, or \fB\-i\fP options) contain descriptions that do not match any known probes.
 .
 .SH OPERANDS
 .LP
-You can specify zero or more additional arguments on the \fBdtrace\fR command line to define a set of macro variables (\fB$1\fR, \fB$2\fR, and so forth). The additional arguments can be used in D programs specified using the \fB\-s\fR option or on the command line. The use of macro variables is described further in the \fIOracle Linux DTrace Guide\fR.
+You can specify zero or more additional arguments on the \fBdtrace\fP command line to define a set of macro variables (\fB$1\fP, \fB$2\fP, and so forth). The additional arguments can be used in D programs specified using the \fB\-s\fP option or on the command line. The use of macro variables is described further in the \fIOracle Linux DTrace Guide\fP.
 .
 .SH EXIT STATUS
 .LP
@@ -159,12 +159,12 @@ The following exit values are returned:
 .B 0
 Successful completion. 
 .IP
-For D program requests, an exit status of \fB0\fR indicates that programs were successfully compiled, probes were successfully enabled, or anonymous state was successfully retrieved. \fBdtrace\fR returns \fB0\fR even if the specified tracing requests encountered errors or drops.
+For D program requests, an exit status of \fB0\fP indicates that programs were successfully compiled, probes were successfully enabled, or anonymous state was successfully retrieved. \fBdtrace\fP returns \fB0\fP even if the specified tracing requests encountered errors or drops.
 .TP
 .B 1
 An error occurred.
 .IP
-For D program requests, an exit status of \fB1\fR indicates that program compilation failed or that the specified request could not be satisfied.
+For D program requests, an exit status of \fB1\fP indicates that program compilation failed or that the specified request could not be satisfied.
 .TP
 .B 2
 Invalid command line options or arguments were specified.
@@ -180,7 +180,7 @@ Print CTF type library debugging output on standard error.
 .IP DTRACE_OPT_*
 Set a given DTrace option.
 .IP
-Options set this way are overridden both by options specified via \fB\-x\fR on the command line, and by \fBsetopt\fR statements.
+Options set this way are overridden both by options specified via \fB\-x\fP on the command line, and by \fBsetopt\fP statements.
 .
 .SH SEE ALSO
 .BR cpp (1),
@@ -191,4 +191,4 @@ Options set this way are overridden both by options specified via \fB\-x\fR on t
 .
 .SH USAGE
 .LP
-When using the \fB\-p\fR flag, \fBdtrace\fR stops the target processes while it is inspecting them and reporting results. A process can do nothing while it is stopped. This means that, if, for example, the X server is inspected by \fBdtrace\fR running in a window under the X server's control, the whole window system can become deadlocked, because the \fBdtrace\fR tool would be attempting to display its results to a window that cannot be refreshed. In such a case, logging in from another system using \fBssh\fR(1) and killing the offending \fBdtrace\fR tool clears the deadlock.
+When using the \fB\-p\fP flag, \fBdtrace\fP stops the target processes while it is inspecting them and reporting results. A process can do nothing while it is stopped. This means that, if, for example, the X server is inspected by \fBdtrace\fP running in a window under the X server's control, the whole window system can become deadlocked, because the \fBdtrace\fP tool would be attempting to display its results to a window that cannot be refreshed. In such a case, logging in from another system using \fBssh\fP(1) and killing the offending \fBdtrace\fP tool clears the deadlock.
-- 
2.46.0.278.g36e3a12567

Re: [PATCH 14/14] man: \fP-ize

[Kris Van Hees]

On Thu, Oct 24, 2024 at 12:37:58PM +0100, Nick Alcock wrote:
> This adjusts everything to use \fN...\fP rather than \fN...\fR everywhere:
> the few places that were using \fP (usually \fB\fIfilename\fP.ext\fR) were
> re-expressed into \fIfilename\fP\fB.ext\fP. \& was added in the instances
> of this pattern that weren't using it (about half were).
> 
> No effect on terminal or typeset output, other than very slightly improved
> layout around the filename stuff above.
> 
> Signed-off-by: Nick Alcock <nick.alcock@oracle.com>

Reviewed-by: Kris Van Hees <kris.van.hees@oracle.com>

> ---
>  cmd/dtrace.8 | 72 ++++++++++++++++++++++++++--------------------------
>  1 file changed, 36 insertions(+), 36 deletions(-)
> 
> diff --git a/cmd/dtrace.8 b/cmd/dtrace.8
> index 355484bd0d34..1f2d48a07531 100644
> --- a/cmd/dtrace.8
> +++ b/cmd/dtrace.8
> @@ -39,9 +39,9 @@ dtrace \- DTrace dynamic tracing compiler and tracing utility
>  .LP
>  DTrace is a comprehensive dynamic tracing framework for the Linux operating system. DTrace provides a powerful infrastructure that permits administrators, developers, and service personnel to concisely answer arbitrary questions about the behavior of the operating system and user programs. 
>  .LP
> -The \fIOracle Linux DTrace Guide\fR describes how to use DTrace to observe, debug, and tune system behavior. Refer to this book for a detailed description of DTrace features, including the bundled DTrace observability tools, instrumentation providers, and the D programming language.
> +The \fIOracle Linux DTrace Guide\fP describes how to use DTrace to observe, debug, and tune system behavior. Refer to this book for a detailed description of DTrace features, including the bundled DTrace observability tools, instrumentation providers, and the D programming language.
>  .LP
> -The \fBdtrace\fR command provides a generic interface to the essential services provided by the DTrace facility, including:
> +The \fBdtrace\fP command provides a generic interface to the essential services provided by the DTrace facility, including:
>  .RS +4
>  .IP o
>  Options that list the set of probes and providers currently published by DTrace
> @@ -57,100 +57,100 @@ Options that generate program stability reports
>  Options that modify DTrace tracing and buffering behavior and enable additional D compiler features
>  .RE
>  .LP
> -You can use \fBdtrace\fR to create D scripts by using it in a \fB#!\fR declaration to create an interpreter file. You can also use \fBdtrace\fR to attempt to compile D programs and determine their properties without actually enabling tracing using the \fB\-e\fR option. See \fBOPTIONS\fR. See the \fIOracle Linux DTrace Guide\fR for detailed examples of how to use the \fBdtrace\fR utility to perform these tasks.
> +You can use \fBdtrace\fP to create D scripts by using it in a \fB#!\fP declaration to create an interpreter file. You can also use \fBdtrace\fP to attempt to compile D programs and determine their properties without actually enabling tracing using the \fB\-e\fP option. See \fBOPTIONS\fP. See the \fIOracle Linux DTrace Guide\fP for detailed examples of how to use the \fBdtrace\fP utility to perform these tasks.
>  .SH OPTIONS
>  .LP
> -The arguments accepted by the \fB\-P\fR, \fB\-m\fR, \fB\-f\fR, \fB\-n\fR, and \fB\-i\fR options can include an optional D language \fIpredicate\fR enclosed in slashes \fB//\fR and optional D language \fIaction\fR statement list enclosed in braces \fB{}\fR. D program code specified on the command line must be appropriately quoted to avoid interpretation of meta-characters by the shell.
> +The arguments accepted by the \fB\-P\fP, \fB\-m\fP, \fB\-f\fP, \fB\-n\fP, and \fB\-i\fP options can include an optional D language \fIpredicate\fP enclosed in slashes \fB//\fP and optional D language \fIaction\fP statement list enclosed in braces \fB{}\fP. D program code specified on the command line must be appropriately quoted to avoid interpretation of meta-characters by the shell.
>  .LP
>  The following options are supported:
>  .TP
>  \fB\-b\fP \fIbufsz\fP
> -Set principal trace buffer size (\fIbufsz\fR). The trace buffer size can include any of the size suffixes \fBk\fR, \fBm\fR, \fBg\fR, or \fBt\fR. If the buffer space cannot be allocated, \fBdtrace\fR attempts to reduce the buffer size or exit depending on the setting of the \fBbufresize\fR property.
> +Set principal trace buffer size (\fIbufsz\fP). The trace buffer size can include any of the size suffixes \fBk\fP, \fBm\fP, \fBg\fP, or \fBt\fP. If the buffer space cannot be allocated, \fBdtrace\fP attempts to reduce the buffer size or exit depending on the setting of the \fBbufresize\fP property.
>  .TP
>  \fB\-c\fP \fIcmd\fP
> -Run the specified command \fIcmd\fR and exit upon its completion. If more than one \fB\-c\fR option is present on the command line, \fBdtrace\fR exits when all commands have exited, reporting the exit status for each child process as it terminates. The process-ID of the first command is made available to any D programs specified on the command line or using the \fB\-s\fR option through the \fB$target\fR macro variable. Refer to the \fIOracle Linux DTrace Guide\fR for more information on macro variables.
> +Run the specified command \fIcmd\fP and exit upon its completion. If more than one \fB\-c\fP option is present on the command line, \fBdtrace\fP exits when all commands have exited, reporting the exit status for each child process as it terminates. The process-ID of the first command is made available to any D programs specified on the command line or using the \fB\-s\fP option through the \fB$target\fP macro variable. Refer to the \fIOracle Linux DTrace Guide\fP for more information on macro variables.
>  .TP
>  \fB\-C\fP
> -Run the C preprocessor \fBcpp\fR(1) over D programs before compiling them. You can pass options to the C preprocessor using the \fB\-D\fR, \fB\-U\fR, \fB\-I\fR, and \fB\-H\fR options. You can select the degree of C standard conformance if you use the \fB\-X\fR option. For a description of the set of tokens defined by the D compiler when invoking the C preprocessor, see \fB\-X\fR.
> +Run the C preprocessor \fBcpp\fP(1) over D programs before compiling them. You can pass options to the C preprocessor using the \fB\-D\fP, \fB\-U\fP, \fB\-I\fP, and \fB\-H\fP options. You can select the degree of C standard conformance if you use the \fB\-X\fP option. For a description of the set of tokens defined by the D compiler when invoking the C preprocessor, see \fB\-X\fP.
>  .TP
>  \fB\-D\fP \fIname\fP \fB[=\fP\fIvalue\fP\fB]\fP
> -Define \fIname\fR when invoking \fBcpp\fR(1) (enabled using the \fB\-C\fR option). If you specify the equals sign (\fB=\fR) and additional \fIvalue\fR, the name is assigned the corresponding value. This option passes the \fB\-D\fR option to each \fBcpp\fR invocation.
> +Define \fIname\fP when invoking \fBcpp\fP(1) (enabled using the \fB\-C\fP option). If you specify the equals sign (\fB=\fP) and additional \fIvalue\fP, the name is assigned the corresponding value. This option passes the \fB\-D\fP option to each \fBcpp\fP invocation.
>  .TP
>  \fB\-e\fP
>  Exit after compiling any requests, but prior to enabling any probes. You can combine this option with D compiler options. This combination verifies that the programs compile without actually executing them and enabling the corresponding instrumentation.
>  .TP
>  \fB\-f\fP\fB[[\fP\fIprovider\fP\fB:]\fP\fImodule\fP\fB:]\fP\fIfunction\fP\fB[[\fP\fIpredicate\fP\fB]\fP\fIaction\fP\fB]]\fP
> -Specify function name to trace or list (\fB\-l\fR option). The corresponding argument can include any of the probe description forms \fIprovider:module:function\fR, \fImodule:function\fR, or \fIfunction\fR. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fIfunction\fR are specified in the description, all probes with the corresponding \fIfunction\fR are matched. The \fB\-f\fR argument can be suffixed with an optional D probe clause. You can specify more than one \fB\-f\fR option on the command line at a time.
> +Specify function name to trace or list (\fB\-l\fP option). The corresponding argument can include any of the probe description forms \fIprovider:module:function\fP, \fImodule:function\fP, or \fIfunction\fP. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fIfunction\fP are specified in the description, all probes with the corresponding \fIfunction\fP are matched. The \fB\-f\fP argument can be suffixed with an optional D probe clause. You can specify more than one \fB\-f\fP option on the command line at a time.
>  .TP
>  \fB\-F\fP
> -Coalesce trace output by identifying function entry and return. Function entry probe reports are indented and their output is prefixed with \fB->\fR. Function return probe reports are unindented and their output is prefixed with \fB<-\fR\&. System call entry probe reports are indented and their output is prefixed with \fB=>\fR. System call return probe reports are unindented and their output is prefixed with \fB<=\fR\&.
> +Coalesce trace output by identifying function entry and return. Function entry probe reports are indented and their output is prefixed with \fB->\fP. Function return probe reports are unindented and their output is prefixed with \fB<-\fP\&. System call entry probe reports are indented and their output is prefixed with \fB=>\fP. System call return probe reports are unindented and their output is prefixed with \fB<=\fP\&.
>  .TP
>  \fB\-G\fP
> -Generate an ELF file containing an embedded DTrace program. The DTrace probes specified in the program are saved inside of a relocatable ELF object which can be linked into another program. If the \fB\-o\fR option is present, the ELF file is saved using the pathname specified as the argument for this operand. If the \fB\-o\fR option is not present and the DTrace program is contained with a file whose name is \fB\fIfilename\fR.d\fR, then the ELF file is saved using the name \fB\fIfilename\fR.o\fR. Otherwise the ELF file is saved using the name \fBd.out\fR.
> +Generate an ELF file containing an embedded DTrace program. The DTrace probes specified in the program are saved inside of a relocatable ELF object which can be linked into another program. If the \fB\-o\fP option is present, the ELF file is saved using the pathname specified as the argument for this operand. If the \fB\-o\fP option is not present and the DTrace program is contained with a file whose name is \fIfilename\fP\fB\&.d\fP, then the ELF file is saved using the name \fIfilename\fP\fB\&.o\fP. Otherwise the ELF file is saved using the name \fBd.out\fP.
>  .TP
>  \fB\-H\fP
> -Print the pathnames of included files when invoking \fBcpp\fR(1) (enabled using the \fB\-C\fR option). This option passes the \fB\-H\fR option to each \fBcpp\fR invocation, causing it to display the list of pathnames, one for each line, to \fBstderr\fR.
> +Print the pathnames of included files when invoking \fBcpp\fP(1) (enabled using the \fB\-C\fP option). This option passes the \fB\-H\fP option to each \fBcpp\fP invocation, causing it to display the list of pathnames, one for each line, to \fBstderr\fP.
>  .TP
>  \fB\-h\fP
> -Generate a header file containing macros that correspond to probes in the specified provider definitions. This option should be used to generate a header file that is included by other source files for later use with the \fB\-G\fR option. If the \fB\-o\fR option is present, the header file is saved using the pathname specified as the argument for that option. If the \fB\-o\fR option is not present and the DTrace program is contained with a file whose name is \fIfilename\fR\fB\&.d\fR, then the header file is saved using the name \fIfilename\fR\fB\&.h\fR.
> +Generate a header file containing macros that correspond to probes in the specified provider definitions. This option should be used to generate a header file that is included by other source files for later use with the \fB\-G\fP option. If the \fB\-o\fP option is present, the header file is saved using the pathname specified as the argument for that option. If the \fB\-o\fP option is not present and the DTrace program is contained with a file whose name is \fIfilename\fP\fB\&.d\fP, then the header file is saved using the name \fIfilename\fP\fB\&.h\fP.
>  .TP
>  \fB\-i\fP \fIprobe-id\fP\fB[[\fP\fIpredicate\fP] \fIaction\fP\fB]\fP
> -Specify probe identifier (\fIprobe-id\fR) to trace or list (\fB\-l\fR option). You can specify probe IDs using decimal integers as shown by \fBdtrace\fR \fB\-l\fR. The \fB\-i\fR argument can be suffixed with an optional D probe clause. You can specify more than one \fB\-i\fR option at a time.
> +Specify probe identifier (\fIprobe-id\fP) to trace or list (\fB\-l\fP option). You can specify probe IDs using decimal integers as shown by \fBdtrace\fP \fB\-l\fP. The \fB\-i\fP argument can be suffixed with an optional D probe clause. You can specify more than one \fB\-i\fP option at a time.
>  .TP
>  \fB\-I\fP \fIpath\fP
> -Add the specified directory \fIpath\fR to the search path for \fB#include\fR files when invoking \fBcpp\fR(1) (enabled using the \fB\-C\fR option). This option passes the \fB\-I\fR option to each \fBcpp\fR invocation. The specified \fIpath\fR is inserted into the search path ahead of the default directory list.
> +Add the specified directory \fIpath\fP to the search path for \fB#include\fP files when invoking \fBcpp\fP(1) (enabled using the \fB\-C\fP option). This option passes the \fB\-I\fP option to each \fBcpp\fP invocation. The specified \fIpath\fP is inserted into the search path ahead of the default directory list.
>  .TP
>  \fB\-L\fP \fIpath\fP
> -Add the specified directory \fIpath\fR to the search path for DTrace libraries. DTrace libraries are used to contain common definitions that can be used when writing D programs. The specified \fIpath\fR is added after the default library search path. If it exists, a subdirectory of \fIpath\fR named after the minor version of the running kernel (e.g. 3.8) is searched immediately before \fIpath\fR. (But take note: dependency analysis is performed only within each directory, not across directories.)
> +Add the specified directory \fIpath\fP to the search path for DTrace libraries. DTrace libraries are used to contain common definitions that can be used when writing D programs. The specified \fIpath\fP is added after the default library search path. If it exists, a subdirectory of \fIpath\fP named after the minor version of the running kernel (e.g. 3.8) is searched immediately before \fIpath\fP. (But take note: dependency analysis is performed only within each directory, not across directories.)
>  .TP
>  \fB\-l\fP
> -List probes instead of enabling them. If the \fB\-l\fR option is specified, \fBdtrace\fR produces a report of the probes matching the descriptions given using the \fB\-P\fR, \fB\-m\fR, \fB\-f\fR, \fB\-n\fR, \fB\-i\fR, and \fB\-s\fR options. If none of these options are specified, this option lists all probes.
> +List probes instead of enabling them. If the \fB\-l\fP option is specified, \fBdtrace\fP produces a report of the probes matching the descriptions given using the \fB\-P\fP, \fB\-m\fP, \fB\-f\fP, \fB\-n\fP, \fB\-i\fP, and \fB\-s\fP options. If none of these options are specified, this option lists all probes.
>  .TP
>  \fB\-m\fP [[\fIprovider:\fP] \fImodule:\fP [[\fIpredicate\fP] \fIaction\fP]]
> -Specify module name to trace or list (\fB\-l\fR option). The corresponding argument can include any of the probe description forms \fIprovider:module\fR or \fImodule\fR. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fImodule\fR are specified in the description, all probes with a corresponding \fImodule\fR are matched. The \fB\-m\fR argument can be suffixed with an optional D probe clause. More than one \fB\-m\fR option can be specified on the command line at a time.
> +Specify module name to trace or list (\fB\-l\fP option). The corresponding argument can include any of the probe description forms \fIprovider:module\fP or \fImodule\fP. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fImodule\fP are specified in the description, all probes with a corresponding \fImodule\fP are matched. The \fB\-m\fP argument can be suffixed with an optional D probe clause. More than one \fB\-m\fP option can be specified on the command line at a time.
>  .TP
>  \fB\-n\fP [[[\fIprovider:\fP] \fImodule:\fP] \fIfunction:\fP] \fIname\fP [[\fIpredicate\fP] \fIaction\fP]
> -Specify probe name to trace or list (\fB\-l\fR option). The corresponding argument can include any of the probe description forms \fIprovider:module:function:name\fR, \fImodule:function:name\fR, \fIfunction:name\fR, or \fIname\fR. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fIname\fR are specified in the description, all probes with a corresponding \fIname\fR are matched. The \fB\-n\fR argument can be suffixed with an optional D probe clause. More than one \fB\-n\fR option can be specified on the command line at a time.
> +Specify probe name to trace or list (\fB\-l\fP option). The corresponding argument can include any of the probe description forms \fIprovider:module:function:name\fP, \fImodule:function:name\fP, \fIfunction:name\fP, or \fIname\fP. Unspecified probe description fields are left blank and match any probes regardless of the values in those fields. If no qualifiers other than \fIname\fP are specified in the description, all probes with a corresponding \fIname\fP are matched. The \fB\-n\fP argument can be suffixed with an optional D probe clause. More than one \fB\-n\fP option can be specified on the command line at a time.
>  .TP
>  \fB\-o\fP \fIoutput\fP
> -Specify the \fIoutput\fR file for the \fB\-G\fR, \fB\-h\fR, and \fB\-l\fR options, or for the traced data itself. If the \fB\-G\fR option is present and the \fB\-s\fR option's argument is of the form \fB\fIfilename\fR.d\fR and \fB\-o\fR is not present, the default output file is \fB\fIfilename\fR.o\fR. Otherwise the default output file is \fBd.out\fR.
> +Specify the \fIoutput\fP file for the \fB\-G\fP, \fB\-h\fP, and \fB\-l\fP options, or for the traced data itself. If the \fB\-G\fP option is present and the \fB\-s\fP option's argument is of the form \fIfilename\fP\fB\&.d\fP and \fB\-o\fP is not present, the default output file is \fIfilename\fP\fB\&.o\fP. Otherwise the default output file is \fBd.out\fP.
>  .TP
>  \fB\-p\fP \fIpid\fP
> -Grab the specified process-ID \fIpid\fR, cache its symbol tables, and exit upon its completion. If more than one \fB\-p\fR option is present on the command line, \fBdtrace\fR exits when all commands have exited, reporting the exit status for each process as it terminates. The first process-ID is made available to any D programs specified on the command line or using the \fB\-s\fR option through the \fB$target\fR macro variable. Refer to the \fIOracle Linux DTrace Guide\fR for more information on macro variables.
> +Grab the specified process-ID \fIpid\fP, cache its symbol tables, and exit upon its completion. If more than one \fB\-p\fP option is present on the command line, \fBdtrace\fP exits when all commands have exited, reporting the exit status for each process as it terminates. The first process-ID is made available to any D programs specified on the command line or using the \fB\-s\fP option through the \fB$target\fP macro variable. Refer to the \fIOracle Linux DTrace Guide\fP for more information on macro variables.
>  .TP
>  \fB\-P\fP \fIprovider\fP \fB[[\fP\fIpredicate\fP\fB]\fP \fIaction\fP]
> -Specify provider name to trace or list (\fB\-l\fR option). The remaining probe description fields module, function, and name are left blank and match any probes regardless of the values in those fields. The \fB\-P\fR argument can be suffixed with an optional D probe clause. You can specify more than one \fB\-P\fR option on the command line at a time.
> +Specify provider name to trace or list (\fB\-l\fP option). The remaining probe description fields module, function, and name are left blank and match any probes regardless of the values in those fields. The \fB\-P\fP argument can be suffixed with an optional D probe clause. You can specify more than one \fB\-P\fP option on the command line at a time.
>  .TP
>  \fB\-q\fP
> -Set quiet mode. \fBdtrace\fR suppresses messages such as the number of probes matched by the specified options and D programs and does not print column headers, the CPU ID, the probe ID, or insert newlines into the output. Only data traced and formatted by D program statements such as \fBtrace()\fR and \fBprintf()\fR is displayed to \fBstdout\fR.
> +Set quiet mode. \fBdtrace\fP suppresses messages such as the number of probes matched by the specified options and D programs and does not print column headers, the CPU ID, the probe ID, or insert newlines into the output. Only data traced and formatted by D program statements such as \fBtrace()\fP and \fBprintf()\fP is displayed to \fBstdout\fP.
>  .TP
>  \fB\-s\fP
> -Compile the specified D program source file. If the \fB\-e\fR option is present, the program is compiled but instrumentation is not enabled. If the \fB\-l\fR option is present, the program is compiled and the set of probes matched by it is listed, but instrumentation is not enabled. If none of \fB\-e\fR, \fB\-l\fR, or \fB\-G\fR are present, the instrumentation specified by the D program is enabled and tracing begins.
> +Compile the specified D program source file. If the \fB\-e\fP option is present, the program is compiled but instrumentation is not enabled. If the \fB\-l\fP option is present, the program is compiled and the set of probes matched by it is listed, but instrumentation is not enabled. If none of \fB\-e\fP, \fB\-l\fP, or \fB\-G\fP are present, the instrumentation specified by the D program is enabled and tracing begins.
>  .TP
>  \fB\-S\fP
> -Show D compiler intermediate code. The D compiler produces a report of the intermediate code generated for each D program to \fBstderr\fR.
> +Show D compiler intermediate code. The D compiler produces a report of the intermediate code generated for each D program to \fBstderr\fP.
>  .TP
>  \fB\-U\fP \fIname\fP
> -Undefine the specified \fIname\fR when invoking \fBcpp\fR(1) (enabled using the \fB-C\fR option). This option passes the \fB-U\fR option to each \fBcpp\fR invocation.
> +Undefine the specified \fIname\fP when invoking \fBcpp\fP(1) (enabled using the \fB-C\fP option). This option passes the \fB-U\fP option to each \fBcpp\fP invocation.
>  .TP
>  \fB\-v\fP
> -Set verbose mode. If the \fB\-v\fR option is specified, \fBdtrace\fR produces a program stability report showing the minimum interface stability and dependency level for the specified D programs. DTrace stability levels are explained in further detail in the \fIOracle Linux DTrace Guide\fR.
> +Set verbose mode. If the \fB\-v\fP option is specified, \fBdtrace\fP produces a program stability report showing the minimum interface stability and dependency level for the specified D programs. DTrace stability levels are explained in further detail in the \fIOracle Linux DTrace Guide\fP.
>  .TP
>  \fB\-V\fP
> -Report the highest D programming interface version supported by \fBdtrace\fR. The version information is printed to \fBstdout\fR and the \fBdtrace\fR command exits. Refer to the \fIOracle Linux DTrace Guide\fR for more information about DTrace versioning features. In conjunction with \fB\-v\fR, also reports information on the version of the \fBdtrace\fR(1) tool and associated library.
> +Report the highest D programming interface version supported by \fBdtrace\fP. The version information is printed to \fBstdout\fP and the \fBdtrace\fP command exits. Refer to the \fIOracle Linux DTrace Guide\fP for more information about DTrace versioning features. In conjunction with \fB\-v\fP, also reports information on the version of the \fBdtrace\fP(1) tool and associated library.
>  .TP
>  \fB\-w\fP
> -Permit destructive actions in D programs specified using the \fB\-s\fR, \fB\-P\fR, \fB\-m\fR, \fB\-f\fR, \fB\-n\fR, or \fB\-i\fR options. If the \fB\-w\fR option is not specified, \fBdtrace\fR does not permit the compilation or enabling of a D program that contains destructive actions.
> +Permit destructive actions in D programs specified using the \fB\-s\fP, \fB\-P\fP, \fB\-m\fP, \fB\-f\fP, \fB\-n\fP, or \fB\-i\fP options. If the \fB\-w\fP option is not specified, \fBdtrace\fP does not permit the compilation or enabling of a D program that contains destructive actions.
>  .TP
>  \fB\-x\fP \fIarg\fP [\fI=val\fP]
> -Enable or modify a DTrace runtime option or D compiler option. The list of options is found in the \fIOracle Linux DTrace Guide\fR. Boolean options are enabled by specifying their name. Options with values are set by separating the option name and value with an equals sign (\fB=\fR).
> +Enable or modify a DTrace runtime option or D compiler option. The list of options is found in the \fIOracle Linux DTrace Guide\fP. Boolean options are enabled by specifying their name. Options with values are set by separating the option name and value with an equals sign (\fB=\fP).
>  .TP
>  \fB\-Z\fP
> -Permit probe descriptions that match zero probes. If the \fB\-Z\fR option is not specified, \fBdtrace\fR reports an error and exits if any probe descriptions specified in D program files (\fB\-s\fR option) or on the command line (\fB\-P\fR, \fB\-m\fR, \fB\-f\fR, \fB\-n\fR, or \fB\-i\fR options) contain descriptions that do not match any known probes.
> +Permit probe descriptions that match zero probes. If the \fB\-Z\fP option is not specified, \fBdtrace\fP reports an error and exits if any probe descriptions specified in D program files (\fB\-s\fP option) or on the command line (\fB\-P\fP, \fB\-m\fP, \fB\-f\fP, \fB\-n\fP, or \fB\-i\fP options) contain descriptions that do not match any known probes.
>  .
>  .SH OPERANDS
>  .LP
> -You can specify zero or more additional arguments on the \fBdtrace\fR command line to define a set of macro variables (\fB$1\fR, \fB$2\fR, and so forth). The additional arguments can be used in D programs specified using the \fB\-s\fR option or on the command line. The use of macro variables is described further in the \fIOracle Linux DTrace Guide\fR.
> +You can specify zero or more additional arguments on the \fBdtrace\fP command line to define a set of macro variables (\fB$1\fP, \fB$2\fP, and so forth). The additional arguments can be used in D programs specified using the \fB\-s\fP option or on the command line. The use of macro variables is described further in the \fIOracle Linux DTrace Guide\fP.
>  .
>  .SH EXIT STATUS
>  .LP
> @@ -159,12 +159,12 @@ The following exit values are returned:
>  .B 0
>  Successful completion. 
>  .IP
> -For D program requests, an exit status of \fB0\fR indicates that programs were successfully compiled, probes were successfully enabled, or anonymous state was successfully retrieved. \fBdtrace\fR returns \fB0\fR even if the specified tracing requests encountered errors or drops.
> +For D program requests, an exit status of \fB0\fP indicates that programs were successfully compiled, probes were successfully enabled, or anonymous state was successfully retrieved. \fBdtrace\fP returns \fB0\fP even if the specified tracing requests encountered errors or drops.
>  .TP
>  .B 1
>  An error occurred.
>  .IP
> -For D program requests, an exit status of \fB1\fR indicates that program compilation failed or that the specified request could not be satisfied.
> +For D program requests, an exit status of \fB1\fP indicates that program compilation failed or that the specified request could not be satisfied.
>  .TP
>  .B 2
>  Invalid command line options or arguments were specified.
> @@ -180,7 +180,7 @@ Print CTF type library debugging output on standard error.
>  .IP DTRACE_OPT_*
>  Set a given DTrace option.
>  .IP
> -Options set this way are overridden both by options specified via \fB\-x\fR on the command line, and by \fBsetopt\fR statements.
> +Options set this way are overridden both by options specified via \fB\-x\fP on the command line, and by \fBsetopt\fP statements.
>  .
>  .SH SEE ALSO
>  .BR cpp (1),
> @@ -191,4 +191,4 @@ Options set this way are overridden both by options specified via \fB\-x\fR on t
>  .
>  .SH USAGE
>  .LP
> -When using the \fB\-p\fR flag, \fBdtrace\fR stops the target processes while it is inspecting them and reporting results. A process can do nothing while it is stopped. This means that, if, for example, the X server is inspected by \fBdtrace\fR running in a window under the X server's control, the whole window system can become deadlocked, because the \fBdtrace\fR tool would be attempting to display its results to a window that cannot be refreshed. In such a case, logging in from another system using \fBssh\fR(1) and killing the offending \fBdtrace\fR tool clears the deadlock.
> +When using the \fB\-p\fP flag, \fBdtrace\fP stops the target processes while it is inspecting them and reporting results. A process can do nothing while it is stopped. This means that, if, for example, the X server is inspected by \fBdtrace\fP running in a window under the X server's control, the whole window system can become deadlocked, because the \fBdtrace\fP tool would be attempting to display its results to a window that cannot be refreshed. In such a case, logging in from another system using \fBssh\fP(1) and killing the offending \fBdtrace\fP tool clears the deadlock.
> -- 
> 2.46.0.278.g36e3a12567
>