git: 242050278a37 - main - dtrace: Document the syscall provider
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Thu, 07 May 2026 09:57:23 UTC
The branch main has been updated by 0mp:
URL: https://cgit.FreeBSD.org/src/commit/?id=242050278a377f5ca6906545ddc924b60ad8aa58
commit 242050278a377f5ca6906545ddc924b60ad8aa58
Author: Mateusz Piotrowski <0mp@FreeBSD.org>
AuthorDate: 2026-05-05 12:57:53 +0000
Commit: Mateusz Piotrowski <0mp@FreeBSD.org>
CommitDate: 2026-05-07 09:57:03 +0000
dtrace: Document the syscall provider
MFC after: 1 week
Differential Revision: https://reviews.freebsd.org/D56831
---
cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 | 3 +-
lib/libsys/intro.2 | 5 +-
share/man/man4/Makefile | 1 +
share/man/man4/dtrace_syscall.4 | 87 ++++++++++++++++++++++++++++
share/man/man4/linux.4 | 3 +-
5 files changed, 95 insertions(+), 4 deletions(-)
diff --git a/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 b/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
index 5173074ee63e..45cb8c863f7a 100644
--- a/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
+++ b/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
@@ -20,7 +20,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd March 20, 2026
+.Dd May 7, 2026
.Dt DTRACE 1
.Os
.Sh NAME
@@ -1310,6 +1310,7 @@ in
.Xr dtrace_profile 4 ,
.Xr dtrace_sched 4 ,
.Xr dtrace_sctp 4 ,
+.Xr dtrace_syscall 4 ,
.Xr dtrace_tcp 4 ,
.Xr dtrace_udp 4 ,
.Xr dtrace_udplite 4 ,
diff --git a/lib/libsys/intro.2 b/lib/libsys/intro.2
index 008936b278ae..33dfecf648c5 100644
--- a/lib/libsys/intro.2
+++ b/lib/libsys/intro.2
@@ -28,7 +28,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd April 19, 2024
+.Dd May 7, 2026
.Dt INTRO 2
.Os
.Sh NAME
@@ -756,7 +756,8 @@ during a system boot.
.El
.Sh SEE ALSO
.Xr intro 3 ,
-.Xr perror 3
+.Xr perror 3 ,
+.Xr dtrace_syscall 4
.Sh HISTORY
The
.Nm Ns Pq 2
diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 60ab6e8bdab6..44671c564239 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -1029,6 +1029,7 @@ _dtrace_provs= dtrace_audit.4 \
dtrace_profile.4 \
dtrace_sched.4 \
dtrace_sctp.4 \
+ dtrace_syscall.4 \
dtrace_tcp.4 \
dtrace_udp.4 \
dtrace_udplite.4 \
diff --git a/share/man/man4/dtrace_syscall.4 b/share/man/man4/dtrace_syscall.4
new file mode 100644
index 000000000000..e154e4c6046b
--- /dev/null
+++ b/share/man/man4/dtrace_syscall.4
@@ -0,0 +1,87 @@
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.\" Copyright (c) 2026 Mateusz Piotrowski <0mp@FreeBSD.org>
+.\"
+.Dd May 7, 2026
+.Dt DTRACE_SYSCALL 4
+.Os
+.Sh NAME
+.Nm dtrace_syscall
+.Nd a DTrace provider for system calls
+.Sh SYNOPSIS
+.Nm syscall Ns Cm \&: Ns Ar abi Ns Cm \&: Ns Ar syscall Ns Cm :entry
+.Nm syscall Ns Cm \&: Ns Ar abi Ns Cm \&: Ns Ar syscall Ns Cm :return
+.Sh DESCRIPTION
+The
+.Nm syscall
+provider provides entry and return probes for system calls.
+.Pp
+The module in the probe's description is
+.Ar abi ,
+which indicates what system call ABI a
+.Ar syscall
+belongs to.
+.Nm
+supports the following system call ABIs:
+.Pp
+.Bl -tag -offset indent -width freebsd32 -compact
+.It Cm freebsd
+Native ABI.
+.It Cm freebsd32
+Non-native, 32-bit ABI.
+.It Cm linux
+Refer to
+.Xr linux 4 .
+.It Cm linux32
+Refer to
+.Xr linux 4 .
+.El
+.Pp
+The arguments to the
+.Cm entry
+probes are the arguments passed to the system call.
+.Pp
+The
+.Cm return
+probe stores the system call's return value in both
+.Fa arg0
+and
+.Fa arg1 .
+.Pp
+Inspect the
+.Xr d 7 Ap s
+.Va errno
+variable to check if a system call failed.
+.Sh EXAMPLES
+.Ss Example 1 : Count Up System Calls
+The following script traces all system calls and counts them for every process
+on the system.
+.Bd -literal -offset 2n
+syscall:::entry {
+ @[execname, pid] = count();
+}
+.Ed
+.Sh SEE ALSO
+.Xr dtrace 1 ,
+.Xr intro 2 ,
+.Xr tracing 7
+.Rs
+.%B The illumos Dynamic Tracing Guide
+.%O Chapter syscall Provider
+.%D 2008
+.%U https://illumos.org/books/dtrace/chp-syscall.html
+.Re
+.Rs
+.%A Brendan Gregg
+.%A Jim Mauro
+.%B DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD
+.%I Prentice Hall
+.%O Chapter Syscall Provider
+.%P pp. 315\(en327
+.%D 2011
+.%U https://www.brendangregg.com/dtracebook/
+.Re
+.Sh AUTHORS
+This manual page was written by
+.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org .
diff --git a/share/man/man4/linux.4 b/share/man/man4/linux.4
index 711ac11e8fce..ec8342efe705 100644
--- a/share/man/man4/linux.4
+++ b/share/man/man4/linux.4
@@ -22,7 +22,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd May 19, 2024
+.Dd May 7, 2026
.Dt LINUX 4
.Os
.Sh NAME
@@ -179,6 +179,7 @@ Linux kernel objects file system, see
.El
.Sh SEE ALSO
.Xr brandelf 1 ,
+.Xr dtrace_syscall 4 ,
.Xr fdescfs 4 ,
.Xr linprocfs 4 ,
.Xr linsysfs 4 ,