diff --git a/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 b/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
index f09cbe1ac27b..456a9e319987 100644
--- a/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
+++ b/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
@@ -1,1320 +1,1321 @@
.\" CDDL HEADER START
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\" CDDL HEADER END
.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
.\"
.\" $FreeBSD$
.\"
-.Dd November 3, 2025
+.Dd November 4, 2025
.Dt DTRACE 1
.Os
.Sh NAME
.Nm dtrace
.Nd dynamic tracing compiler and tracing utility
.Sh SYNOPSIS
.Nm
.Op Fl 32 | Fl 64
.Op Fl aACdeFGhHlOqSvVwZ
.Op Fl -libxo
.Op Fl b Ar bufsz
.Op Fl c Ar cmd
.Op Fl D Ar name Op Ns = Ns value
.Op Fl I Ar path
.Op Fl L Ar path
.Op Fl o Ar output
.Op Fl s Ar script
.Op Fl U Ar name
.Op Fl x Ar arg Op Ns = Ns value
.Op Fl X Cm a | c | s | t
.Op Fl p Ar pid
.Op Fl P Ar provider Oo Oo Ar predicate Oc Ar action Oc
.Op Fl m Oo Ar provider : Oc Ar module Oo Oo Ar predicate Oc Ar action Oc
.Op Fl f Oo Oo Ar provider : Oc Ar module : Oc Ar function Oo Oo Ar predicate \
Oc Ar action Oc
.Op Fl n Oo Oo Oo Ar provider : Oc Ar module : Oc Ar function : Oc Ar name \
Oo Oo Ar predicate Oc Ar action Oc
.Op Fl i Ar probe-id Oo Oo Ar predicate Oc Ar action Oc
.Sh DESCRIPTION
DTrace is a comprehensive dynamic tracing framework ported from Solaris.
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.
.Pp
The
.Nm
command provides a generic interface to the essential services provided by the
DTrace facility, including:
.Bl -bullet -offset indent
.It
Options that list the set of probes and providers currently published by DTrace
.It
Options that enable probes directly using any of the probe description
specifiers (provider, module, function, name)
.It
Options that run the D compiler and compile one or more D program files or
programs written directly on the command line
.It
Options that generate anonymous tracing programs
.It
Options that generate program stability reports
.It
Options that modify DTrace tracing and buffering behavior and enable
additional D compiler features
.El
.Pp
You can use
.Nm
to create D scripts by using it in a shebang declaration to create an
interpreter file.
You can also use
.Nm
to attempt to compile D programs and determine their properties without
actually enabling traces using the
.Fl e
option.
.Sh OPTIONS
The arguments accepted by the
.Fl P ,
.Fl m ,
.Fl f ,
.Fl n ,
and
.Fl i
options can include an optional D language
.Ar predicate
enclosed in slashes and an optional D language
.Ar action
statement list enclosed in braces.
D program code specified on the command line must be appropriately quoted to
avoid interpretation of meta-characters by the shell.
.Pp
The following options are supported:
.Bl -tag -width indent
.It Fl 32 | Fl 64
The D compiler produces programs using the native data model of the operating
system kernel.
If the
.Fl 32
option is specified,
.Nm
forces the D compiler to compile a D program using the 32-bit data model.
If the
.Fl 64
option is specified,
.Nm
forces the D compiler to compile a D program using the 64-bit data model.
These options are typically not required as
.Nm
selects the native data model as the default.
The data model affects the sizes of integer types and other language properties.
D programs compiled for either data model can be executed on both 32-bit and
64-bit kernels.
The
.Fl 32
and
.Fl 64
options also determine the
.Xr elf 5
file format (ELF32 or ELF64) produced by the
.Fl G
option.
.It Fl a
Claim anonymous tracing state and display the traced data.
You can combine the
.Fl a
option with the
.Fl e
option to force
.Nm
to exit immediately after consuming the anonymous tracing state rather than
continuing to wait for new data.
.It Fl A
Generate directives for anonymous tracing and write them to
.Pa /boot/dtrace.dof .
This option constructs a set of dtrace configuration file directives to enable
the specified probes for anonymous tracing and then exits.
By default,
.Nm
attempts to store the directives to the file
.Pa /boot/dtrace.dof .
This behavior can be modified using the
.Fl o
option to specify an alternate output file.
.It Fl b Ar bufsz
Set the principal trace buffer size to
.Ar bufsz .
The trace buffer size can include any of the size suffixes k, m, g, or t.
If the buffer space cannot be allocated,
.Nm dtrace
attempts to reduce the buffer size or exit depending on the setting of the
bufresize property.
.It Fl c Ar cmd
Run the specified command
.Ar cmd
and exit upon its completion.
If more than one
.Fl c
option is present on the command line,
.Nm dtrace
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
.Fl s
option through the
.Li $target
macro variable.
.It Fl C
Run the C preprocessor
.Xr cpp 1
over D programs before compiling them.
You can pass options to the C preprocessor using the
.Fl D ,
.Fl U ,
.Fl I ,
and
.Fl H
options.
You can select the degree of C standard conformance if you use the
.Fl X
option.
For a description of the set of tokens defined by the D compiler when invoking
the C preprocessor, see
.Fl X .
.It Fl d
Dump the D script to standard output, after syntactic transformations have been
applied.
For example, if-statements in D are implemented using such transformations: a
conditional clause in a probe body is replaced at compile-time by a separate
probe predicated on the original condition.
.It Fl D Ar name Op Ns = Ns value
Define
.Ar name
when invoking
.Xr cpp 1
(enabled using the
.Fl C
option).
If you specify an additional
.Ar value ,
the name is assigned the corresponding value.
This option passes the
.Fl D
option to each
.Xr cpp 1
invocation.
.It Fl e
Exit after compiling any requests and consuming anonymous tracing state
.Fl ( a
option) but prior to enabling any probes.
You can combine this option with the
.Fl a
option to print anonymous tracing data and exit.
You can also combine this option with D compiler options.
This combination verifies that the programs compile without actually executing
them and enabling the corresponding instrumentation.
.It Fl f Oo Oo Ar provider : Oc Ar module : Oc Ar function Oo Oo Ar predicate \
Oc Ar action Oc
Specify function name to trace or list
.Fl ( l
option).
The corresponding argument can include any of the probe description forms
.Ar provider:module:function ,
.Ar module:function ,
or
.Ar function .
Unspecified probe description fields are left blank and match any probes
regardless of the values in those fields.
If no qualifiers other than
.Ar function
are specified in the description, all probes with the corresponding
.Ar function
are matched.
The
.Fl f
argument can be suffixed with an optional D probe clause.
You can specify more than one
.Fl f
option on the command line at a time.
.It Fl F
Coalesce trace output by identifying function entry and return.
Function entry probe reports are indented and their output is prefixed with
.Ql -> .
Function return probe reports are unindented and their output is prefixed with
.Ql <- .
System call entry probe reports are indented and their output is prefixed with
.Ql => .
System call return probe reports are unindented and their output is prefixed
with
.Ql <= .
.It Fl G
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
.Fl o
option is present, the ELF file is saved using the pathname specified as the
argument for this operand.
If the
.Fl o
option is not present and the DTrace program is contained with a file whose name
is
.Ar filename.d ,
then the ELF file is saved using the name
.Ar filename.o .
Otherwise the ELF file is saved using the name d.out.
.It Fl h
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
.Fl G
option.
If the
.Fl o
option is present, the header file is saved using the pathname specified as the
argument for that option.
If the
.Fl o
option is not present and the DTrace program is contained within a file whose
name is
.Ar filename.d ,
then the header file is saved using the name
.Ar filename.h .
.It Fl H
Print the pathnames of included files when invoking
.Xr cpp 1
(enabled using the
.Fl C
option).
This option passes the
.Fl H
option to each
.Xr cpp 1
invocation, causing it to display the list of pathnames, one for each line, to
standard error.
.It Fl i Ar probe-id Op Oo Ar predicate Oc Ar action
Specify probe identifier
.Ar ( probe-id )
to trace or list
.Ar ( l
option).
You can specify probe IDs using decimal integers as shown by `dtrace -l`.
The
.Fl i
argument can be suffixed with an optional D probe clause.
You can specify more than one
.Fl i
option at a time.
.It Fl I Ar path
Add the specified directory
.Ar path
to the search path for #include files when invoking
.Xr cpp 1
(enabled using the
.Fl C
option).
This option passes the
.Fl I
option to each
.Xr cpp 1
invocation.
The specified
.Ar path
is inserted into the search path ahead of the default directory list.
.It Fl l
List probes instead of enabling them.
If the
.Fl l
option is specified,
.Nm
produces a report of the probes matching the descriptions given using the
.Fl P , m , f , n , i ,
and
.Fl s
options.
If none of these options are specified, this option lists all probes.
.It Fl L Ar path
Add the specified directory
.Ar path
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
.Ar path
is added after the default library search path.
.It Fl -libxo
Generate output via
.Xr libxo 3 .
This option is the same as specifying
.Sy oformat .
.It Fl m Oo Ar provider : Oc Ar module Oo Oo Ar predicate Oc Ar action Oc
Specify module name to trace or list
.Fl ( l
option).
The corresponding argument can include any of the probe description forms
.Ar provider:module
or
.Ar module .
Unspecified probe description fields are left blank and match any probes
regardless of the values in those fields.
If no qualifiers other than
.Ar module
are specified in the description, all probes with a corresponding
.Ar module
are matched.
The
.Fl m
argument can be suffixed with an optional D probe clause.
More than one
.Fl m
option can be specified on the command line at a time.
.It Fl n Oo Oo Oo Ar provider : Oc Ar module : Oc Ar function : Oc Ar name \
Oo Oo Ar predicate Oc Ar action Oc
Specify probe name to trace or list
.Fl ( l
option).
The corresponding argument can include any of the probe description forms
.Ar provider:module:function:name , module:function:name , function:name ,
or
.Ar name .
Unspecified probe description fields are left blank and match any probes
regardless of the values in those fields.
If no qualifiers other than
.Ar name
are specified in the description, all probes with a corresponding
.Ar name
are matched.
The
.Fl n
argument can be suffixed with an optional D probe clause.
More than one
.Fl n
option can be specified on the command line at a time.
.It Fl O
This option causes
.Nm
to print all the aggregations upon exiting if
.Sy oformat
or
.Fl -libxo
are specified.
.It Fl o Ar output
Specify the
.Ar output
file for the
.Fl A , G ,
and
.Fl l
options, or for the traced data itself.
If the
.Fl A
option is present and
.Fl o
is not present, the default output file is
.Pa /boot/dtrace.dof .
If the
.Fl G
option is present and the
.Fl s
option's argument is of the form
.Ar filename.d
and
.Fl o
is not present, the default output file is
.Ar filename.o .
Otherwise the default output file is
.Ar d.out .
.It Fl p Ar pid
Grab the specified process-ID
.Ar pid ,
cache its symbol tables, and exit upon its completion.
If more than one
.Fl p
option is present on the command line,
.Nm
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
.Fl s
option through the
.Li $target
macro variable.
.It Fl P Ar provider Oo Oo Ar predicate Oc Ar action Oc
Specify provider name to trace or list
.Fl ( l
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
.Fl P
argument can be suffixed with an optional D probe clause.
You can specify more than one
.Fl P
option on the command line at a time.
.It Fl q
Set quiet mode.
.Nm
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
.Ql dtrace()
and
.Ql printf()
is displayed to standard output.
.It Fl s Ar script
Compile the specified D program source file.
If the
.Fl e
option is present, the program is compiled but instrumentation is not enabled.
If the
.Fl l
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
.Fl e , l , G ,
or
.Fl A
are present, the instrumentation specified by the D program is enabled and
tracing begins.
.It Fl S
Show D compiler intermediate code.
The D compiler produces a report of the intermediate code generated for each D
program to standard error.
.It Fl U Ar name
Undefine the specified
.Ar name
when invoking
.Xr cpp 1
(enabled using the
.Fl C
option).
This option passes the
.Fl U
option to each
.Xr cpp 1
invocation.
.It Fl v
Set verbose mode.
If the
.Fl v
option is specified,
.Nm
produces a program stability report showing the minimum interface stability and
dependency level for the specified D programs.
.It Fl V
Report the highest D programming interface version supported by
.Nm .
The version information is printed to standard output and the
.Nm
command exits.
.It Fl w
Permit destructive actions in D programs specified using the
.Fl s , P , m , f , n ,
or
.Fl i
options.
If the
.Fl w
option is not specified,
.Nm
does not permit the compilation or enabling of a D program that contains
destructive actions.
.Pp
Set the
.Va security.bsd.allow_destructive_dtrace
.Xr loader 8
tunable
to
.Ql 0
to disallow the possibility of enabling destructive actions system-wide at any point at all.
Any attempts to enable destructive actions will cause
.Nm
to exit with a runtime error.
.It Fl x Ar arg Op Ns = Ns value
Enable or modify a DTrace runtime option or D compiler option.
Boolean options are enabled by specifying their name.
Options with values are set by separating the option name and value with an
equals sign (=).
.Pp
A
.Ar size
argument may be suffixed with one of
.Cm K ,
.Cm M ,
.Cm G
or
.Cm T
(either upper or lower case) to indicate a multiple of
Kilobytes, Megabytes, Gigabytes or Terabytes
respectively.
.Pp
A
.Ar time
argument may be suffixed with one of
.Cm ns ,
.Cm nsec ,
.Cm us ,
.Cm usec ,
.Cm ms ,
.Cm msec ,
.Cm s ,
.Cm sec ,
.Cm m ,
.Cm min ,
.Cm h ,
.Cm hour ,
.Cm d ,
.Cm day ,
.Cm hz .
If no suffix is specified
.Cm hz
will be used as the unit.
.Bl -tag -width indent
.It Sy aggrate Ns = Ns Ar time
Rate of aggregation reading.
.It Sy aggsize Ns = Ns Ar size
Size of the aggregation buffer.
.It Sy bufpolicy Ns = Ns Cm fill Ns | Ns Cm switch Ns | Ns Cm ring
Specifies the buffer policy for the principal buffer.
.It Sy bufresize Ns = Ns Cm auto Ns | Ns Cm manual
Buffer resizing policy.
.It Sy bufsize Ns = Ns Ar size
Size of the per-CPU principal buffer.
Same as the
.Fl b
flag.
.It Sy cleanrate Ns = Ns Ar time
Cleaning rate.
Must be specified in number-per-second with the
.Dq Li hz
suffix.
.It Sy cpu Ns = Ns Ar scalar
Specifies the CPU on which to enable tracing.
.It Sy cpp
Run a C preprocessor over input files.
Same as the
.Fl C
flag.
.It Sy cpppath Ns = Ns Ar path
Use the specified path for the C preprocessor rather than
searching for
.Dq cpp
in
.Ev PATH .
.It Sy defaultargs
Allow references to unspecified macro arguments.
.It Sy destructive
Allow destructive actions.
Same as the
.Fl w
flag.
.It Sy dynvarsize Ns = Ns Ar size
Size of the dynamic variable space.
.Sm off
.It Sy evaltime = Cm exec | preinit | postinit | main
.Sm on
Process create mode.
When using
.Fl c Ar cmd
to start a command,
.Nm
will first stop the newly started
.Ar cmd ,
evaluate the
.Xr d 7
program,
and then resume the
.Ar cmd .
The
.Cm evaltime
option controls the exact moment when this happens.
.Pp
The following table describes supported modes.
.Bl -column -offset indent "postinit" "D Program Evaluation Time"
.It Sy Mode Ta Sy D Program Evaluation Time
.It Cm exec Ta
Right at the first instruction of the command
.Ar cmd
execution.
.It Cm preinit Ta
Before
.Xr elf 5 Ap s
.Dq .init
sections.
.It Cm postinit Ta
After
.Xr elf 5 Ap s
.Dq .init
sections.
Default on
.Fx .
.It Cm main Ta
Before the first instruction of the
.Fn main
function.
.El
.Pp
Usually, there is no reason to change the default mode,
but it might be handy in situations such as shared library tracing.
.It Sy flowindent
Turn on flow indentation.
Same as the
.Fl F
flag.
.It Sy grabanon
Claim anonymous state.
Same as the
.Fl a
flag.
.It Sy jstackframes Ns = Ns Ar scalar
Number of default stack frames for
.Fn jstack .
.It Sy jstackstrsize Ns = Ns Ar scalar
Default string space size for
.Fn jstack .
.It Sy ldpath Ns = Ns Ar path
When
.Fl G
is specified, use the specified path for a static linker
rather than searching for
.Dq "ld"
in
.Ev PATH .
.It Sy libdir Ns = Ns Ar path
Add a directory to the system library path.
.It Sy nspec Ns = Ns Ar scalar
Number of speculations.
.It Sy nolibs
Do not load D system libraries.
.It Sy quiet
Set quiet mode.
Same as the
.Fl q
flag.
.It Sy specsize Ns = Ns Ar size
Size of the speculation buffer.
.It Sy strsize Ns = Ns Ar size
Maximum size of strings.
.It Sy stackframes Ns = Ns Ar scalar
Maximum number of kernelspace stack frames to unwind when executing the
.Fn stack
action.
.It Sy stackindent Ns = Ns Ar scalar
Number of whitespace characters to use when indenting
.Fn stack
and
.Fn ustack
output.
.It Sy oformat Ns = Ns Ar format
Specify the format to use for output.
Setting
.Sy oformat
to
.Ql text
makes
.Nm
use regular human-readable output which is its default behavior.
The options passed to
.Sy oformat
are directly forwarded to
.Xr libxo 3 .
Some of the supported formatters include
.Ql json ,
.Ql xml
and
.Ql html .
Note that this option will cause
.Nm
to not produce any output unless printing functions are explicitly called,
or the
.Fl O
flag is specified.
For more information see
.Sx STRUCTURED OUTPUT .
.It Sy statusrate Ns = Ns Ar time
Rate of status checking.
.It Sy switchrate Ns = Ns Ar time
Rate of buffer switching.
.It Sy syslibdir Ns = Ns Ar path
Path to system libraries.
Defaults to
.Pa /usr/lib/dtrace .
.It Sy ustackframes Ns = Ns Ar scalar
Maximum number of userspace stack frames to unwind when executing the
.Fn ustack
action.
.El
.It Fl X Cm a | c | s | t
Specify the degree of conformance to the ISO C standard that should be selected
when invoking
.Xr cpp 1
(enabled using the
.Fl C
option).
The
.Fl X
option argument affects the value and presence of the __STDC__ macro depending
upon the value of the argument letter.
.sp
The
.Fl X
option supports the following arguments:
.Bl -tag -width indent
.It a
Default.
ISO C plus K&R compatibility extensions, with semantic changes required by ISO
C.
This is the default mode if
.Fl X
is not specified.
The predefined macro __STDC__ has a value of 0 when
.Xr cpp 1
is invoked in conjunction with the
.Fl Xa
option.
.It c
Conformance.
Strictly conformant ISO C, without K&R C compatibility extensions.
The predefined macro __STDC__ has a value of 1 when
.Xr cpp 1
is invoked in conjunction with the
.Fl \&Xc
option.
.It s
K&R C only.
The macro __STDC__ is not defined when
.Xr cpp 1
is invoked in conjunction with the
.Fl Xs
option.
.It t
Transition.
ISO C plus K&R C compatibility extensions, without semantic changes required by
ISO C.
The predefined macro __STDC__ has a value of 0 when
.Xr cpp 1
is invoked in conjunction with the
.Fl Xt
option.
.El
.Pp
As the
.Fl X
option only affects how the D compiler invokes the C preprocessor, the
.Fl Xa
and
.Fl Xt
options are equivalent from the perspective of D and both are provided only to
ease re-use of settings from a C build environment.
.Pp
Regardless of the
.Fl X
mode, the following additional C preprocessor definitions are always specified
and valid in all modes:
.Bl -bullet -offset indent
.It
__sun
.It
__unix
.It
__SVR4
.It
__sparc (on SPARC systems only)
.It
__sparcv9 (on SPARC systems only when 64-bit programs are compiled)
.It
__i386 (on x86 systems only when 32-bit programs are compiled)
.It
__amd64 (on x86 systems only when 64-bit programs are compiled)
.It
__`uname -s`_`uname -r` (for example,
.Ql FreeBSD_9.2-RELEASE .
.It
__SUNW_D=1
.It
.No __SUNW_D_VERSION=0x Ns Ar MMmmmuuu
.Pp
Where
.Ar MM
is the major release value in hexadecimal,
.Ar mmm
is the minor release value in hexadecimal, and
.Ar uuu
is the micro release value in hexadecimal.
.El
.It Fl Z
Permit probe descriptions that match zero probes.
If the
.Fl Z
option is not specified,
.Nm
reports an error and exits if any probe descriptions specified in D program
files
.Fl ( s
option) or on the command line
.Fl ( P , m , f , n ,
or
.Fl i
options) contain descriptions that do not match any known probes.
.El
.Sh STRUCTURED OUTPUT
.Nm
supports structured output using
.Xr libxo 3 .
The output will always have a top-level object called
.Dq dtrace ,
followed by a list of objects
.Dq probes .
Each of the probe objects will to have a timestamp which is generated at
output time rather than probe firing time, an identifier for the CPU on
which the probe was executed, and the probe's full specification:
.Bd -literal
{
"dtrace": {
"probes": [
{
"timestamp": ...,
"cpu": ...,
"id": ...,
"provider": ...,
"module": ...,
"function": ...,
"name": ...,
"output": [
... (script-specific output)
]
}
]
}
}
...
...
...
...
...
...
...
.Ed
.Pp
It is also possible for XML output to take the following form if some
of the fields are empty (in this example, module and function values
are absent):
.Bd -literal
...
...
.Ed
.Pp
Similarly,
.Sy oformat
can be used to generate HTML:
.Bd -literal
...
...
...
...
...
...
...
...
.Ed
.Pp
Unlike JSON and XML, the
.Dq output
array is not present.
Instead, data is simply formatted into a div of class
.Dq data
and a data-tag is associated with each of the keys.
.Pp
The
.Dq output
array's contents depend on the probes' actions and is explained below.
The examples here are presented in JSON form as opposed to XML or HTML,
however the conversion explained above applies for all output formats.
.Pp
Any scalar output, such as output produced by the
.Fn trace
action is of form:
.Bd -literal
{
"value": ...
}
.Ed
.Pp
The
.Fn printf
action begins with an object containing the formatted output of the
.Fn printf
action.
Subsequent objects contains the value of each of the arguments to
.Fn printf
in its raw form as if the
.Fn trace
action was used instead.
A
.Fn printf
statement which contains no arguments other than the message will only have
one object following the message object and its value will always be 0.
This is an artefact of the implementation and can safely be ignored.
.Bd -literal
# dtrace --libxo json,pretty -n 'BEGIN { printf("... %Y, ..", walltimestamp); }'
{
"message": "... 2023 Sep 7 16:49:02, .."
},
{
"value": 1694105342633402400
},
{
...
}
.Ed
.Pp
Scalar aggregations are aggregations which produce a single value for a given
key.
These aggregations include
.Fn count ,
.Fn min ,
.Fn max ,
.Fn stddev
and
.Fn sum .
Each one of them is represented by the key containing their name.
For example, the output of a
.Fn stddev
aggregation will contain a key
.Dq stddev
inside an
.Dq aggregation-data
object:
.Bd -literal
{
"aggregation-data": [
{
"keys": [
...
],
"stddev": ...
}
],
"aggregation-name": ...
}
.Ed
.Pp
The
.Dq keys
field remains consistent across all aggregations, however
.Fn quantize ,
.Fn lquantize
and
.Fn llquantize
need to be treated differently.
.Sy oformat
will create a new array of objects called
.Dq buckets .
Each of the objects contains a
.Dq value
and a
.Dq count
field which are
the left-hand side and the right-hand side of human-readable
.Nm
output respectively.
The full object has the following format:
.Bd -literal
{
"aggregation-data": [
...
{
"keys": [
...
],
"buckets": [
{
"value": 32,
"count": 0
},
{
"value": 64,
"count": 17
},
...
],
},
...
]
"aggregation-name": ...
}
.Ed
.Pp
Similar to scalar aggregations, named scalar actions such as
.Fn mod ,
.Fn umod ,
.Fn usym ,
.Fn tracemem
and
.Fn printm
will output an object with the key being equal to the
name of the action.
For example,
.Fn printm
output would produce the following object:
.Bd -literal
{
"printm": "0x4054171100"
}
.Ed
.Pp
.Fn sym
is slightly different.
While it will create a
.Dq sym
field which contains its value, in some cases it will also create additional
fields
.Dq object ,
.Dq name
and
.Dq offset :
.Bd -literal
# dtrace -x oformat=json,pretty -On 'BEGIN { sym((uintptr_t)&`prison0); }'
{
"sym": "kernel`prison0",
"object": "kernel",
"name": "prison0"
}
# dtrace --libxo json,pretty -On 'BEGIN { sym((uintptr_t)curthread); }'
{
"sym": "0xfffffe00c18d2000",
"offset": "0xfffffe00c18d2000"
}
.Ed
.Pp
.Fn stack
and
.Fn ustack
actions unroll each of the stack frames into its own object in an array.
The only real difference between them is that the
.Fn stack
action will produce a list called
.Dq stack-frames
while
.Fn ustack
will produce one called
.Dq ustack-frames .
The following is an example of their
.Sy oformat
output:
.Bd -literal
{
"stack-frames": [
{
"symbol": "dtrace.ko`dtrace_dof_create+0x35",
"module": "dtrace.ko",
"name": "dtrace_dof_create",
"offset": "0x35"
},
{
"symbol": "dtrace.ko`dtrace_ioctl+0x81c",
"module": "dtrace.ko",
"name": "dtrace_ioctl",
"offset": "0x81c"
},
...
]
}
{
"ustack-frames": [
{
"symbol": "libc.so.7`ioctl+0xa",
"module": "libc.so.7",
"name": "ioctl",
"offset": "0xa"
},
{
"symbol": "libdtrace.so.2`dtrace_go+0xf3",
"module": "libdtrace.so.2",
"name": "dtrace_go",
"offset": "0xf3"
},
...
]
}
.Ed
.Pp
The
.Fn print
action produces a
.Dq type
list in the following form:
.Bd -literal
{
"type": [
{
"object-name": "kernel",
"name": "struct thread",
"ctfid": 2372
},
{
"member-name": "td_lock",
"name": "struct mtx *volatile",
"ctfid": 2035,
"value": "0xffffffff82158440"
},
...
}
.Ed
.Pp
If the type is invalid, a
.Dq warning
object will be produced containing the diagnostic message as well as two
possible optional fields:
.Dq type-identifier
which contains the CTF identifier of the type and
.Dq size containing the size of an integer, enum or float.
The fields generated will depend on the kind of error that was encountered
while processing the trace data.
.Pp
Finally,
.Sy oformat
provides a special pseudo-probe to represent drops.
As
.Nm
polls for various kinds of drops
.Sy oformat
will produce output similar to the following in order to represent drops:
.Bd -literal
{
"cpu": -1,
"id": -1,
"provider": "dtrace",
"module": "INTERNAL",
"function": "INTERNAL",
"name": "DROP",
"timestamp": ...,
"count": ...,
"total": ...,
"kind": 2,
"msg": "... dynamic variable drops\n"
}
.Ed
.Sh OPERANDS
You can specify zero or more additional arguments on the
.Nm
command line to define a set of macro variables and so forth).
The additional arguments can be used in D programs specified using the
.Fl s
option or on the command line.
.Sh FILES
.Bl -tag -width /boot/dtrace.dof -compact
.It Pa /boot/dtrace.dof
File for anonymous tracing directives.
.El
.Sh EXIT STATUS
The following exit statuses are returned:
.Bl -tag -width indent
.It 0
Successful completion.
.Pp
For D program requests, an exit status of 0 indicates that programs were
successfully compiled, probes were successfully enabled, or anonymous state
was successfully retrieved.
.Nm
returns 0 even if the specified tracing requests encountered errors or drops.
.It 1
An error occurred.
.Pp
For D program requests, an exit status of 1 indicates that program compilation
failed or that the specified request could not be satisfied.
.It 2
Invalid command line options or arguments were specified.
.El
.Sh DIAGNOSTICS
.Bl -diag
.It dtrace: could not enable tracing: Permission denied
This can happen when
.Nm
fails to enable destructive actions because
.Va security.bsd.allow_destructive_dtrace
is set to
.Ql 0
in
.Xr loader.conf 5 .
.El
.Sh SEE ALSO
.Xr cpp 1 ,
.Xr dwatch 1 ,
.Xr dtrace_audit 4 ,
+.Xr dtrace_callout_execute 4 ,
.Xr dtrace_dtrace 4 ,
.Xr dtrace_fbt 4 ,
.Xr dtrace_io 4 ,
.Xr dtrace_ip 4 ,
.Xr dtrace_kinst 4 ,
.Xr dtrace_lockstat 4 ,
.Xr dtrace_proc 4 ,
.Xr dtrace_profile 4 ,
.Xr dtrace_sched 4 ,
.Xr dtrace_sctp 4 ,
.Xr dtrace_tcp 4 ,
.Xr dtrace_udp 4 ,
.Xr dtrace_udplite 4 ,
.Xr dtrace_vfs 4 ,
.Xr elf 5 ,
.Xr d 7 ,
.Xr tracing 7 ,
.Xr SDT 9
.Rs
.%T Solaris Dynamic Tracing Guide
.Re
.Sh HISTORY
The
.Nm
utility first appeared in
.Fx 7.1 .
diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 95618227a010..34edf6ad455d 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -1,1140 +1,1141 @@
.include
MANGROUPS= MAN
MANPACKAGE= kernel-man
# If you add a new file here, please consider adding an entry to the
# hardware notes template (website/archetypes/release/hardware.adoc in
# the doc repository); otherwise the automatically generated hardware
# notes will not include your driver.
# If you enable a driver for a different architecture, please remember
# to update the arch specifier in the document title of the manual.
MAN= aac.4 \
aacraid.4 \
acpi.4 \
${_acpi_asus.4} \
${_acpi_asus_wmi.4} \
${_acpi_dock.4} \
${_acpi_fujitsu.4} \
${_acpi_hp.4} \
${_acpi_ibm.4} \
${_acpi_panasonic.4} \
${_acpi_rapidstart.4} \
${_acpi_sony.4} \
acpi_ged.4 \
acpi_thermal.4 \
acpi_battery.4 \
${_acpi_toshiba.4} \
acpi_video.4 \
${_acpi_wmi.4} \
ada.4 \
adm6996fc.4 \
ads111x.4 \
ae.4 \
${_aesni.4} \
age.4 \
agp.4 \
ahc.4 \
ahci.4 \
ahd.4 \
${_aibs.4} \
aio.4 \
alc.4 \
ale.4 \
alpm.4 \
altq.4 \
amdpm.4 \
${_amdsbwd.4} \
${_amdsmb.4} \
${_amdsmn.4} \
${_amdtemp.4} \
${_bxe.4} \
${_aout.4} \
${_apic.4} \
arcmsr.4 \
arswitch.4 \
${_asmc.4} \
at45d.4 \
ata.4 \
ath.4 \
ath_hal.4 \
atkbd.4 \
atkbdc.4 \
${_atopcase.4} \
atp.4 \
${_atrtc.4} \
${_attimer.4} \
audit.4 \
auditpipe.4 \
aue.4 \
${_aw_gpio.4} \
${_aw_mmc.4} \
${_aw_rtc.4} \
${_aw_sid.4} \
${_aw_spi.4} \
${_aw_syscon.4} \
axe.4 \
axge.4 \
axp.4 \
bce.4 \
bcm5974.4 \
bcma.4 \
bfe.4 \
bge.4 \
${_bhyve.4} \
bhnd.4 \
bhnd_chipc.4 \
bhnd_pmu.4 \
bhndb.4 \
bhndb_pci.4 \
blackhole.4 \
bnxt.4 \
boottrace.4 \
bpf.4 \
bridge.4 \
bwi.4 \
bwn.4 \
${_bytgpio.4} \
capsicum.4 \
cardbus.4 \
carp.4 \
cas.4 \
cc_cdg.4 \
cc_chd.4 \
cc_cubic.4 \
cc_dctcp.4 \
cc_hd.4 \
cc_htcp.4 \
cc_newreno.4 \
cc_vegas.4 \
${_ccd.4} \
ccr.4 \
cd9660.4 \
cd.4 \
cdce.4 \
cdceem.4 \
cfi.4 \
cfumass.4 \
${_cgem.4} \
ch.4 \
chromebook_platform.4 \
${_chvgpio.4} \
ciss.4 \
${_coretemp.4} \
cp2112.4 \
${_cpuctl.4} \
cpufreq.4 \
crypto.4 \
ctl.4 \
cue.4 \
cxgb.4 \
cxgbe.4 \
cxgbev.4 \
cyapa.4 \
da.4 \
dc.4 \
dcons.4 \
dcons_crom.4 \
ddb.4 \
devctl.4 \
devfs.4 \
disc.4 \
disk.4 \
divert.4 \
${_dpms.4} \
ds1307.4 \
ds3231.4 \
${_dtrace_provs} \
dummymbuf.4 \
dummynet.4 \
edsc.4 \
ehci.4 \
em.4 \
ena.4 \
enc.4 \
enic.4 \
epair.4 \
est.4 \
et.4 \
etherswitch.4 \
eventtimers.4 \
exca.4 \
ext2fs.4 \
e6000sw.4 \
e6060sw.4 \
fd.4 \
fdc.4 \
fdescfs.4 \
fdt.4 \
fdt_pinctrl.4 \
fdtbus.4 \
ffclock.4 \
ffs.4 \
filemon.4 \
firewire.4 \
${_ftgpio.4} \
${_ftwd.4} \
full.4 \
fusefs.4 \
fwe.4 \
fwip.4 \
fwohci.4 \
fxp.4 \
gdb.4 \
gem.4 \
genet.4 \
genetlink.4 \
geom.4 \
geom_linux_lvm.4 \
geom_uzip.4 \
gif.4 \
${_gve.4} \
gpio.4 \
gpioiic.4 \
gpiokeys.4 \
gpioled.4 \
gpioths.4 \
gre.4 \
h_ertt.4 \
hconf.4 \
hcons.4 \
hgame.4 \
hidbus.4 \
hidquirk.4 \
hidraw.4 \
hkbd.4 \
hms.4 \
hmt.4 \
hpen.4 \
hpet.4 \
${_hpt27xx.4} \
${_hptiop.4} \
${_hptmv.4} \
${_hptnr.4} \
${_hptrr.4} \
hsctrl.4 \
htu21.4 \
${_hv_kvp.4} \
${_hv_netvsc.4} \
${_hv_storvsc.4} \
${_hv_utils.4} \
${_hv_vmbus.4} \
${_hv_vss.4} \
hwpmc.4 \
${_hwt.4} \
${_hwpstate_intel.4} \
i2ctinyusb.4 \
iavf.4 \
ice.4 \
ichsmb.4 \
${_ichwd.4} \
icmp.4 \
icmp6.4 \
ida.4 \
ietp.4 \
if_ipsec.4 \
iflib.4 \
ifmib.4 \
ig4.4 \
igmp.4 \
iic.4 \
iic_gpiomux.4 \
iicbb.4 \
iicbus.4 \
iichid.4 \
iicmux.4 \
iicsmb.4 \
${_igc.4} \
${_imcsmb.4} \
inet.4 \
inet6.4 \
intpm.4 \
intro.4 \
${_io.4} \
${_ioat.4} \
ip.4 \
ip17x.4 \
ip6.4 \
ipfirewall.4 \
ipheth.4 \
${_ipmi.4} \
ips.4 \
ipsec.4 \
ipw.4 \
ipwfw.4 \
isci.4 \
isl.4 \
ismt.4 \
isp.4 \
ispfw.4 \
${_itwd.4} \
iwi.4 \
iwifw.4 \
iwm.4 \
iwmfw.4 \
iwn.4 \
iwnfw.4 \
iwlwifi.4 \
iwlwififw.4 \
${_iwx.4} \
ix.4 \
ixl.4 \
jedec_dimm.4 \
jme.4 \
kbdmux.4 \
kcov.4 \
keyboard.4 \
kld.4 \
ksyms.4 \
ksz8995ma.4 \
ktls.4 \
ktr.4 \
kue.4 \
${_kvmclock.4} \
lagg.4 \
le.4 \
led.4 \
lge.4 \
lindebugfs.4 \
linprocfs.4 \
linsysfs.4 \
${_linux.4} \
linuxkpi.4 \
linuxkpi_wlan.4 \
liquidio.4 \
lm75.4 \
lo.4 \
lp.4 \
lpbb.4 \
lpt.4 \
ltc430x.4 \
mac.4 \
mac_biba.4 \
mac_bsdextended.4 \
mac_ddb.4 \
mac_do.4 \
mac_ifoff.4 \
mac_ipacl.4 \
mac_lomac.4 \
mac_mls.4 \
mac_none.4 \
mac_ntpd.4 \
mac_partition.4 \
mac_portacl.4 \
mac_priority.4 \
mac_seeotheruids.4 \
mac_stub.4 \
mac_test.4 \
malo.4 \
max44009.4 \
md.4 \
mdio.4 \
me.4 \
mem.4 \
mfi.4 \
${_mgb.4} \
miibus.4 \
mld.4 \
mlx.4 \
mlx4en.4 \
mlx5en.4 \
mmc.4 \
mmcsd.4 \
mod_cc.4 \
mos.4 \
mouse.4 \
mpi3mr.4 \
mpr.4 \
mps.4 \
mpt.4 \
mqueuefs.4 \
mrsas.4 \
msdosfs.4 \
msk.4 \
mtio.4 \
mtkswitch.4 \
multicast.4 \
muge.4 \
mvs.4 \
mwl.4 \
mwlfw.4 \
mx25l.4 \
mxge.4 \
my.4 \
net80211.4 \
netdump.4 \
netfpga10g_nf10bmac.4 \
netgdb.4 \
netgraph.4 \
netintro.4 \
netlink.4 \
netmap.4 \
${_nfe.4} \
nfslockd.4 \
${_nfsmb.4} \
ng_async.4 \
ng_bpf.4 \
ng_bridge.4 \
ng_btsocket.4 \
ng_car.4 \
ng_checksum.4 \
ng_cisco.4 \
ng_deflate.4 \
ng_device.4 \
nge.4 \
ng_echo.4 \
ng_eiface.4 \
ng_etf.4 \
ng_ether.4 \
ng_ether_echo.4 \
ng_frame_relay.4 \
ng_gif.4 \
ng_gif_demux.4 \
ng_hci.4 \
ng_hole.4 \
ng_hub.4 \
ng_iface.4 \
ng_ipfw.4 \
ng_ip_input.4 \
ng_ksocket.4 \
ng_l2cap.4 \
ng_l2tp.4 \
ng_lmi.4 \
ng_macfilter.4 \
ng_mppc.4 \
ng_nat.4 \
ng_netflow.4 \
ng_one2many.4 \
ng_patch.4 \
ng_pipe.4 \
ng_ppp.4 \
ng_pppoe.4 \
ng_pptpgre.4 \
ng_pred1.4 \
ng_rfc1490.4 \
ng_socket.4 \
ng_source.4 \
ng_split.4 \
ng_tag.4 \
ng_tcpmss.4 \
ng_tee.4 \
ng_tty.4 \
ng_ubt.4 \
ng_UI.4 \
ng_vjc.4 \
ng_vlan.4 \
ng_vlan_rotate.4 \
nmdm.4 \
${_ntb.4} \
${_ntb_hw_amd.4} \
${_ntb_hw_intel.4} \
${_ntb_hw_plx.4} \
${_ntb_transport.4} \
${_nda.4} \
${_if_ntb.4} \
null.4 \
nullfs.4 \
numa.4 \
nvd.4 \
${_nvdimm.4} \
nvme.4 \
nvmf.4 \
nvmf_tcp.4 \
nvmft.4 \
${_nvram.4} \
oce.4 \
ocs_fc.4\
ohci.4 \
openfirm.4 \
orm.4 \
${_ossl.4} \
ow.4 \
ow_temp.4 \
owc.4 \
ovpn.4 \
${_padlock.4} \
p9fs.4 \
pass.4 \
pca954x.4 \
pccard.4 \
pccbb.4 \
pcf.4 \
pcf8574.4 \
pcf8591.4 \
${_pchtherm.4} \
pci.4 \
pcib.4 \
pcic.4 \
pcm.4 \
${_pf.4} \
${_pflog.4} \
${_pflow.4} \
${_pfsync.4} \
pim.4 \
pms.4 \
polling.4 \
ppbus.4 \
ppc.4 \
ppi.4 \
procdesc.4 \
procfs.4 \
proto.4 \
ps4dshock.4 \
psm.4 \
pst.4 \
pt.4 \
ptnet.4 \
pts.4 \
pty.4 \
puc.4 \
pwmc.4 \
${_pvscsi.4} \
${_qat.4} \
${_qat_c2xxx.4} \
${_qlxge.4} \
${_qlxgb.4} \
${_qlxgbe.4} \
${_qlnxe.4} \
ral.4 \
random.4 \
rctl.4 \
re.4 \
rgephy.4 \
rights.4 \
rl.4 \
rndtest.4 \
route.4 \
rtnetlink.4 \
rtsx.4 \
rtw88.4 \
rtw89.4 \
rtwn.4 \
rtwnfw.4 \
rtwn_pci.4 \
rue.4 \
sa.4 \
safe.4 \
safexcel.4 \
sbp.4 \
sbp_targ.4 \
scc.4 \
sched_4bsd.4 \
sched_ule.4 \
screen.4 \
scsi.4 \
sctp.4 \
sdhci.4 \
sem.4 \
send.4 \
ses.4 \
${_sfxge.4} \
sg.4 \
sge.4 \
siba.4 \
siftr.4 \
siis.4 \
simplebus.4 \
sis.4 \
sk.4 \
${_smartpqi.4} \
smb.4 \
smbfs.4 \
smbios.4 \
smbus.4 \
smp.4 \
smsc.4 \
snd_als4000.4 \
snd_atiixp.4 \
snd_cmi.4 \
snd_cs4281.4 \
snd_csa.4 \
snd_dummy.4 \
snd_emu10k1.4 \
snd_emu10kx.4 \
snd_envy24.4 \
snd_envy24ht.4 \
snd_es137x.4 \
snd_fm801.4 \
snd_hda.4 \
snd_hdsp.4 \
snd_hdspe.4 \
snd_ich.4 \
snd_maestro3.4 \
snd_neomagic.4 \
snd_solo.4 \
snd_spicds.4 \
snd_t4dwave.4 \
snd_uaudio.4 \
snd_via8233.4 \
snd_via82c686.4 \
snd_vibes.4 \
sndstat.4 \
snp.4 \
spigen.4 \
${_spkr.4} \
splash.4 \
ste.4 \
stf.4 \
stge.4 \
${_sume.4} \
${_superio.4} \
sym.4 \
syncache.4 \
syncer.4 \
syscons.4 \
sysmouse.4 \
tap.4 \
tarfs.4 \
targ.4 \
tcp.4 \
tcp_bbr.4 \
tcp_rack.4 \
tdfx.4 \
termios.4 \
textdump.4 \
thunderbolt.4 \
ti.4 \
timecounters.4 \
tmpfs.4 \
${_tpm.4} \
tslog.4 \
tty.4 \
tun.4 \
tws.4 \
u2f.4 \
udp.4 \
udplite.4 \
${_ufshci.4} \
unionfs.4 \
ure.4 \
vale.4 \
vga.4 \
vge.4 \
viapm.4 \
${_viawd.4} \
virtio.4 \
virtio_balloon.4 \
virtio_blk.4 \
virtio_console.4 \
virtio_gpu.4 \
virtio_random.4 \
virtio_scsi.4 \
${_vmci.4} \
vkbd.4 \
vlan.4 \
vxlan.4 \
${_vmd.4} \
${_vmm.4} \
${_vmx.4} \
vr.4 \
vt.4 \
vte.4 \
vtnet.4 \
watchdog.4 \
${_wbwd.4} \
${_wdatwd.4} \
wg.4 \
witness.4 \
wlan.4 \
wlan_acl.4 \
wlan_amrr.4 \
wlan_ccmp.4 \
wlan_gcmp.4 \
wlan_tkip.4 \
wlan_wep.4 \
wlan_xauth.4 \
wmt.4 \
${_wpi.4} \
wsp.4 \
xb360gp.4 \
${_xen.4} \
xhci.4 \
xl.4 \
${_xnb.4} \
xpt.4 \
zero.4
MLINKS= ads111x.4 ads1013.4 \
ads111x.4 ads1014.4 \
ads111x.4 ads1015.4 \
ads111x.4 ads1113.4 \
ads111x.4 ads1114.4 \
ads111x.4 ads1115.4
MLINKS+=ae.4 if_ae.4
MLINKS+=age.4 if_age.4
MLINKS+=agp.4 agpgart.4
MLINKS+=alc.4 if_alc.4
MLINKS+=ale.4 if_ale.4
MLINKS+=altq.4 ALTQ.4
MLINKS+=ath.4 if_ath.4
MLINKS+=aue.4 if_aue.4
MLINKS+=axe.4 if_axe.4
MLINKS+=bce.4 if_bce.4
MLINKS+=bfe.4 if_bfe.4
MLINKS+=bge.4 if_bge.4
MLINKS+=bnxt.4 if_bnxt.4
MLINKS+=bridge.4 if_bridge.4
MLINKS+=bwi.4 if_bwi.4
MLINKS+=bwn.4 if_bwn.4
MLINKS+=${_bxe.4} ${_if_bxe.4}
MLINKS+=cas.4 if_cas.4
MLINKS+=cdce.4 if_cdce.4
MLINKS+=cfi.4 cfid.4
MLINKS+=crypto.4 cryptodev.4
MLINKS+=cue.4 if_cue.4
MLINKS+=cxgb.4 if_cxgb.4
MLINKS+=cxgbe.4 if_cxgbe.4 \
cxgbe.4 vcxgbe.4 \
cxgbe.4 if_vcxgbe.4 \
cxgbe.4 cxl.4 \
cxgbe.4 if_cxl.4 \
cxgbe.4 vcxl.4 \
cxgbe.4 if_vcxl.4 \
cxgbe.4 cc.4 \
cxgbe.4 if_cc.4 \
cxgbe.4 vcc.4 \
cxgbe.4 if_vcc.4
MLINKS+=cxgbev.4 if_cxgbev.4 \
cxgbev.4 cxlv.4 \
cxgbev.4 if_cxlv.4 \
cxgbev.4 ccv.4 \
cxgbev.4 if_ccv.4
MLINKS+=dc.4 if_dc.4
MLINKS+=disc.4 if_disc.4
MLINKS+=edsc.4 if_edsc.4
MLINKS+=em.4 if_em.4 \
em.4 igb.4 \
em.4 if_igb.4 \
em.4 lem.4 \
em.4 if_lem.4
MLINKS+=enc.4 if_enc.4
MLINKS+=epair.4 if_epair.4
MLINKS+=et.4 if_et.4
MLINKS+=ext2fs.4 ext4fs.4
MLINKS+=fd.4 stderr.4 \
fd.4 stdin.4 \
fd.4 stdout.4
MLINKS+=fdt.4 FDT.4
MLINKS+=firewire.4 ieee1394.4
MLINKS+=fwe.4 if_fwe.4
MLINKS+=fwip.4 if_fwip.4
MLINKS+=fxp.4 if_fxp.4
MLINKS+=gem.4 if_gem.4
MLINKS+=genet.4 if_genet.4
MLINKS+=geom.4 GEOM.4
MLINKS+=gif.4 if_gif.4
MLINKS+=gpio.4 gpiobus.4
MLINKS+=gpioths.4 dht11.4
MLINKS+=gpioths.4 dht22.4
MLINKS+=gre.4 if_gre.4
MLINKS+=hpet.4 acpi_hpet.4
MLINKS+=${_hv_netvsc.4} ${_hn.4} \
${_hv_netvsc.4} ${_if_hn.4}
MLINKS+=${_hptrr.4} ${_rr232x.4}
MLINKS+=${_attimer.4} ${_i8254.4}
MLINKS+=ip.4 rawip.4
MLINKS+=ipfirewall.4 ipaccounting.4 \
ipfirewall.4 ipacct.4 \
ipfirewall.4 ipfw.4
MLINKS+=ice.4 if_ice.4
MLINKS+=ipheth.4 if_ipheth.4
MLINKS+=ipw.4 if_ipw.4
MLINKS+=iwi.4 if_iwi.4
MLINKS+=iwlwifi.4 if_iwlwifi.4
MLINKS+=iwm.4 if_iwm.4
MLINKS+=iwn.4 if_iwn.4
MLINKS+=ix.4 if_ix.4
MLINKS+=ix.4 if_ixgbe.4
MLINKS+=ix.4 ixgbe.4
MLINKS+=ixl.4 if_ixl.4
MLINKS+=iavf.4 if_iavf.4
MLINKS+=jme.4 if_jme.4
MLINKS+=kue.4 if_kue.4
MLINKS+=lagg.4 trunk.4
MLINKS+=lagg.4 if_lagg.4
MLINKS+=le.4 if_le.4
MLINKS+=lge.4 if_lge.4
MLINKS+=lo.4 loop.4
MLINKS+=lp.4 plip.4
MLINKS+=malo.4 if_malo.4
MLINKS+=mem.4 kmem.4
MLINKS+=mfi.4 mfi_linux.4 \
mfi.4 mfip.4
MLINKS+=mlx5en.4 mce.4
MLINKS+=mos.4 if_mos.4
MLINKS+=msdosfs.4 msdos.4
MLINKS+=msk.4 if_msk.4
MLINKS+=mwl.4 if_mwl.4
MLINKS+=mxge.4 if_mxge.4
MLINKS+=my.4 if_my.4
MLINKS+=netfpga10g_nf10bmac.4 if_nf10bmac.4
MLINKS+=netintro.4 net.4 \
netintro.4 networking.4
MLINKS+=${_nfe.4} ${_if_nfe.4}
MLINKS+=nge.4 if_nge.4
MLINKS+=openfirm.4 openfirmware.4
MLINKS+=ow.4 onewire.4
MLINKS+=pccbb.4 cbb.4
MLINKS+=pcm.4 snd.4 \
pcm.4 sound.4
MLINKS+=pms.4 pmspcv.4
MLINKS+=ptnet.4 if_ptnet.4
MLINKS+=ral.4 if_ral.4
MLINKS+=re.4 if_re.4
MLINKS+=rl.4 if_rl.4
MLINKS+=rtw88.4 if_rtw88.4
MLINKS+=rtw89.4 if_rtw89.4
MLINKS+=rtwn.4 if_rtwn.4
MLINKS+=rue.4 if_rue.4
MLINKS+=scsi.4 cam.4
MLINKS+=scsi.4 scbus.4
MLINKS+=scsi.4 SCSI.4
MLINKS+=sge.4 if_sge.4
MLINKS+=sis.4 if_sis.4
MLINKS+=sk.4 if_sk.4
MLINKS+=smp.4 SMP.4
MLINKS+=smsc.4 if_smsc.4
MLINKS+=snd_envy24.4 snd_ak452x.4
MLINKS+=${_spkr.4} ${_speaker.4}
MLINKS+=splash.4 screensaver.4
MLINKS+=ste.4 if_ste.4
MLINKS+=stf.4 if_stf.4
MLINKS+=stge.4 if_stge.4
MLINKS+=syncache.4 syncookies.4
MLINKS+=syscons.4 sc.4
MLINKS+=tap.4 if_tap.4 \
tap.4 vmnet.4 \
tap.4 if_vmnet.4
MLINKS+=tdfx.4 tdfx_linux.4
MLINKS+=ti.4 if_ti.4
MLINKS+=tun.4 if_tun.4
MLINKS+=ure.4 if_ure.4
MLINKS+=vge.4 if_vge.4
MLINKS+=vlan.4 if_vlan.4
MLINKS+=vxlan.4 if_vxlan.4
MLINKS+=${_vmx.4} ${_if_vmx.4}
MLINKS+=vr.4 if_vr.4
MLINKS+=vte.4 if_vte.4
MLINKS+=vtnet.4 if_vtnet.4
MLINKS+=watchdog.4 SW_WATCHDOG.4
MLINKS+=wg.4 if_wg.4
MLINKS+=wlan.4 wifi.4
MLINKS+=${_wpi.4} ${_if_wpi.4}
MLINKS+=xl.4 if_xl.4
.if ${MACHINE_CPUARCH} == "amd64" || ${MACHINE_CPUARCH} == "i386"
_acpi_asus.4= acpi_asus.4
_acpi_asus_wmi.4= acpi_asus_wmi.4
_acpi_dock.4= acpi_dock.4
_acpi_fujitsu.4=acpi_fujitsu.4
_acpi_hp.4= acpi_hp.4
_acpi_ibm.4= acpi_ibm.4
_acpi_panasonic.4=acpi_panasonic.4
_acpi_rapidstart.4=acpi_rapidstart.4
_acpi_sony.4= acpi_sony.4
_acpi_toshiba.4=acpi_toshiba.4
_acpi_wmi.4= acpi_wmi.4
_aesni.4= aesni.4
_aout.4= aout.4
_apic.4= apic.4
_atrtc.4= atrtc.4
_attimer.4= attimer.4
_aibs.4= aibs.4
_amdsbwd.4= amdsbwd.4
_amdsmb.4= amdsmb.4
_amdsmn.4= amdsmn.4
_amdtemp.4= amdtemp.4
_asmc.4= asmc.4
_atopcase.4= atopcase.4
_bxe.4= bxe.4
_bytgpio.4= bytgpio.4
_chvgpio.4= chvgpio.4
_coretemp.4= coretemp.4
_cpuctl.4= cpuctl.4
_dpms.4= dpms.4
_ftgpio.4= ftgpio.4
_ftwd.4= ftwd.4
_hn.4= hn.4
_hpt27xx.4= hpt27xx.4
_hptiop.4= hptiop.4
_hptmv.4= hptmv.4
_hptnr.4= hptnr.4
_hptrr.4= hptrr.4
_hv_kvp.4= hv_kvp.4
_hv_netvsc.4= hv_netvsc.4
_hv_storvsc.4= hv_storvsc.4
_hv_utils.4= hv_utils.4
_hv_vmbus.4= hv_vmbus.4
_hv_vss.4= hv_vss.4
_hwpstate_intel.4= hwpstate_intel.4
_i8254.4= i8254.4
_ichwd.4= ichwd.4
_if_bxe.4= if_bxe.4
_if_hn.4= if_hn.4
_if_nfe.4= if_nfe.4
_if_urtw.4= if_urtw.4
_if_wpi.4= if_wpi.4
_igc.4= igc.4
_imcsmb.4= imcsmb.4
_io.4= io.4
_itwd.4= itwd.4
_kvmclock.4= kvmclock.4
_mgb.4= mgb.4
_nda.4= nda.4
_nfe.4= nfe.4
_nfsmb.4= nfsmb.4
_if_ntb.4= if_ntb.4
_ntb.4= ntb.4
_ntb_hw_amd.4= ntb_hw_amd.4
_ntb_hw_intel.4= ntb_hw_intel.4
_ntb_hw_plx.4= ntb_hw_plx.4
_ntb_transport.4=ntb_transport.4
_nvram.4= nvram.4
_pchtherm.4= pchtherm.4
_qat.4= qat.4
_qat_c2xxx.4= qat_c2xxx.4
_rr232x.4= rr232x.4
_speaker.4= speaker.4
_spkr.4= spkr.4
_superio.4= superio.4
_tpm.4= tpm.4
_urtw.4= urtw.4
_viawd.4= viawd.4
_vmci.4= vmci.4
_vmd.4= vmd.4
_wbwd.4= wbwd.4
_wdatwd.4= wdatwd.4
_wpi.4= wpi.4
_xen.4= xen.4
_xnb.4= xnb.4
.endif
.if ${MACHINE_CPUARCH} == "amd64"
_ioat.4= ioat.4
_iwx.4= iwx.4
_nvdimm.4= nvdimm.4
_qlxge.4= qlxge.4
_qlxgb.4= qlxgb.4
_qlxgbe.4= qlxgbe.4
_qlnxe.4= qlnxe.4
_sfxge.4= sfxge.4
_smartpqi.4= smartpqi.4
_sume.4= sume.4
MLINKS+=iwx.4 if_iwx.4
MLINKS+=qlxge.4 if_qlxge.4
MLINKS+=qlxgb.4 if_qlxgb.4
MLINKS+=qlxgbe.4 if_qlxgbe.4
MLINKS+=qlnxe.4 if_qlnxe.4
MLINKS+=sfxge.4 if_sfxge.4
MLINKS+=sume.4 if_sume.4
.if ${MK_BHYVE} != "no"
_bhyve.4= bhyve.4
_vmm.4= vmm.4
.endif
.endif
.if ${MACHINE_CPUARCH} == "i386"
_padlock.4= padlock.4
.endif
.if ${MACHINE_CPUARCH} == "amd64" || ${MACHINE_CPUARCH} == "aarch64"
_hwt.4= hwt.4
.if ${MACHINE_CPUARCH} == "amd64"
MLINKS+=hwt.4 intel_pt.4
.endif
.if ${MACHINE_CPUARCH} == "aarch64"
MLINKS+=hwt.4 coresight.4
MLINKS+=hwt.4 spe.4
.endif
.endif
.if ${MACHINE_CPUARCH} == "amd64" || ${MACHINE_CPUARCH} == "aarch64"
_ufshci.4= ufshci.4
.endif
.if ${MACHINE_CPUARCH} == "amd64" || ${MACHINE_CPUARCH} == "i386" || \
${MACHINE_CPUARCH} == "aarch64"
_gve.4= gve.4
_if_vmx.4= if_vmx.4
_ipmi.4= ipmi.4
_linux.4= linux.4
_ossl.4= ossl.4
_pvscsi.4= pvscsi.4
_vmx.4= vmx.4
.endif
.if ${MACHINE_CPUARCH} == "arm" || ${MACHINE_CPUARCH} == "aarch64" || \
${MACHINE_CPUARCH} == "riscv"
_aw_gpio.4= aw_gpio.4
_aw_mmc.4= aw_mmc.4
_aw_rtc.4= aw_rtc.4
_aw_sid.4= aw_sid.4
_aw_spi.4= aw_spi.4
_aw_syscon.4= aw_syscon.4
_cgem.4= cgem.4
MLINKS+=cgem.4 if_cgem.4
.endif
.if empty(MAN_ARCH) || ${MAN_ARCH} == "all"
__arches= ${:!/bin/sh -c "/bin/ls -d ${.CURDIR}/man4.*"!:E}
.else
__arches= ${MAN_ARCH}
.endif
.for __arch in ${__arches:O:u}
.if exists(${.CURDIR}/man4.${__arch})
SUBDIR+= man4.${__arch}
.endif
.endfor
.if ${MK_AUTOFS} != "no"
MAN+= autofs.4
.endif
.if ${MK_BLUETOOTH} != "no"
MAN+= ng_bluetooth.4
.endif
.if ${MK_CCD} != "no"
_ccd.4= ccd.4
.endif
.if ${MK_CDDL} != "no"
_dtrace_provs= dtrace_audit.4 \
+ dtrace_callout_execute.4 \
dtrace_dtrace.4 \
dtrace_fbt.4 \
dtrace_io.4 \
dtrace_ip.4 \
dtrace_kinst.4 \
dtrace_lockstat.4 \
dtrace_proc.4 \
dtrace_profile.4 \
dtrace_sched.4 \
dtrace_sctp.4 \
dtrace_tcp.4 \
dtrace_udp.4 \
dtrace_udplite.4 \
dtrace_vfs.4
MLINKS+= dtrace_audit.4 dtaudit.4
.endif
.if ${MK_EFI} != "no"
MAN+= efidev.4
MLINKS+= efidev.4 efirtc.4
.endif
.if ${MK_ISCSI} != "no"
MAN+= cfiscsi.4
MAN+= iscsi.4
MAN+= iser.4
.endif
.if ${MK_OFED} != "no"
MAN+= mlx4ib.4
MAN+= mlx5ib.4
.endif
.if ${MK_MLX5TOOL} != "no"
MAN+= mlx5io.4
.endif
.if ${MK_TESTS} != "no"
MANGROUPS+= TESTS
ATF= ${SRCTOP}/contrib/atf
.PATH: ${ATF}/doc
TESTS= atf-test-case.4
TESTSPACKAGE= tests
.endif
.if ${MK_PF} != "no"
_pf.4= pf.4
_pflog.4= pflog.4
_pflow.4= pflow.4
_pfsync.4= pfsync.4
.endif
.if ${MK_USB} != "no"
MAN+= \
mtw.4 \
otus.4 \
otusfw.4 \
rsu.4 \
rsufw.4 \
rtwn_usb.4 \
rum.4 \
run.4 \
runfw.4 \
u3g.4 \
uark.4 \
uart.4 \
uath.4 \
ubsa.4 \
ubser.4 \
ubtbcmfw.4 \
uchcom.4 \
ucom.4 \
ucycom.4 \
udav.4 \
udbc.4 \
udbp.4 \
udl.4 \
uep.4 \
ufoma.4 \
uftdi.4 \
ugen.4 \
ugold.4 \
uhci.4 \
uhid.4 \
uhso.4 \
uipaq.4 \
ukbd.4 \
uled.4 \
ulpt.4 \
umass.4 \
umb.4 \
umcs.4 \
umct.4 \
umodem.4 \
umoscom.4 \
ums.4 \
unix.4 \
upgt.4 \
uplcom.4 \
ural.4 \
urio.4 \
urndis.4 \
${_urtw.4} \
usb.4 \
usb_quirk.4 \
usb_template.4 \
usbhid.4 \
usfs.4 \
uslcom.4 \
uvisor.4 \
uvscom.4 \
veriexec.4 \
zyd.4
MLINKS+=mtw.4 if_mtw.4
MLINKS+=otus.4 if_otus.4
MLINKS+=rsu.4 if_rsu.4
MLINKS+=rtwn_usb.4 if_rtwn_usb.4
MLINKS+=rum.4 if_rum.4
MLINKS+=run.4 if_run.4
MLINKS+=u3g.4 u3gstub.4
MLINKS+=uath.4 if_uath.4
MLINKS+=udav.4 if_udav.4
MLINKS+=upgt.4 if_upgt.4
MLINKS+=ural.4 if_ural.4
MLINKS+=urndis.4 if_urndis.4
MLINKS+=${_urtw.4} ${_if_urtw.4}
MLINKS+=zyd.4 if_zyd.4
.endif
.include
diff --git a/share/man/man4/dtrace_callout_execute.4 b/share/man/man4/dtrace_callout_execute.4
new file mode 100644
index 000000000000..1154ed066b97
--- /dev/null
+++ b/share/man/man4/dtrace_callout_execute.4
@@ -0,0 +1,68 @@
+.\"
+.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org>
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.Dd November 4, 2025
+.Dt DTRACE_CALLOUT_EXECUTE 4
+.Os
+.Sh NAME
+.Nm dtrace_callout_execute
+.Nd a DTrace provider for the callout API
+.Sh SYNOPSIS
+.Nm callout_execute Ns Cm :kernel::callout_start
+.Nm callout_execute Ns Cm :kernel::callout_end
+.Sh DESCRIPTION
+The
+.Nm callout_execute
+provider allows for tracing the
+.Xr callout 9
+mechanism.
+.Pp
+The
+.Nm callout_execute Ns Cm :kernel::callout_start
+probe fires just before a callout.
+.Pp
+The
+.Nm callout_execute Ns Cm :kernel::callout_end
+probe fires right after a callout.
+.Pp
+The only argument to the
+.Nm callout_execute
+probes,
+.Fa args[0] ,
+is a callout handler
+.Ft struct callout *
+of the invoked callout.
+.Sh EXAMPLES
+.Ss Example 1: Graph of Callout Execution Time
+The following
+.Xr d 7
+script generates a distribution graph of
+.Xr callout 9
+execution times:
+.Bd -literal -offset 2n
+callout_execute:::callout_start
+{
+ self->cstart = timestamp;
+}
+
+callout_execute:::callout_end
+{
+ @length = quantize(timestamp - self->cstart);
+}
+.Ed
+.Sh SEE ALSO
+.Xr dtrace 1 ,
+.Xr tracing 7 ,
+.Xr callout 9 ,
+.Xr SDT 9
+.Sh AUTHORS
+.An -nosplit
+The
+.Nm callout_execute
+provider was written by
+.An Robert N. M. Watson Aq Mt rwatson@FreeBSD.org .
+.Pp
+This manual page was written by
+.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org .
diff --git a/share/man/man9/callout.9 b/share/man/man9/callout.9
index 0e59ef8ab2b1..637049ec1ef5 100644
--- a/share/man/man9/callout.9
+++ b/share/man/man9/callout.9
@@ -1,884 +1,886 @@
.\" $NetBSD: timeout.9,v 1.2 1996/06/23 22:32:34 pk Exp $
.\"
.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Paul Kranenburg.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd January 22, 2024
+.Dd November 4, 2025
.Dt CALLOUT 9
.Os
.Sh NAME
.Nm callout_active ,
.Nm callout_deactivate ,
.Nm callout_drain ,
.Nm callout_init ,
.Nm callout_init_mtx ,
.Nm callout_init_rm ,
.Nm callout_init_rw ,
.Nm callout_pending ,
.Nm callout_reset ,
.Nm callout_reset_curcpu ,
.Nm callout_reset_on ,
.Nm callout_reset_sbt ,
.Nm callout_reset_sbt_curcpu ,
.Nm callout_reset_sbt_on ,
.Nm callout_schedule ,
.Nm callout_schedule_curcpu ,
.Nm callout_schedule_on ,
.Nm callout_schedule_sbt ,
.Nm callout_schedule_sbt_curcpu ,
.Nm callout_schedule_sbt_on ,
.Nm callout_stop ,
.Nm callout_when
.Nd execute a function after a specified length of time
.Sh SYNOPSIS
.In sys/types.h
.In sys/callout.h
.Bd -literal
typedef void callout_func_t (void *);
.Ed
.Ft int
.Fn callout_active "struct callout *c"
.Ft void
.Fn callout_deactivate "struct callout *c"
.Ft int
.Fn callout_drain "struct callout *c"
.Ft void
.Fn callout_init "struct callout *c" "int mpsafe"
.Ft void
.Fn callout_init_mtx "struct callout *c" "struct mtx *mtx" "int flags"
.Ft void
.Fn callout_init_rm "struct callout *c" "struct rmlock *rm" "int flags"
.Ft void
.Fn callout_init_rw "struct callout *c" "struct rwlock *rw" "int flags"
.Ft int
.Fn callout_pending "struct callout *c"
.Ft int
.Fo callout_reset
.Fa "struct callout *c"
.Fa "int ticks"
.Fa "callout_func_t *func"
.Fa "void *arg"
.Fc
.Ft int
.Fo callout_reset_curcpu
.Fa "struct callout *c"
.Fa "int ticks"
.Fa "callout_func_t *func"
.Fa "void *arg"
.Fc
.Ft int
.Fo callout_reset_on
.Fa "struct callout *c"
.Fa "int ticks"
.Fa "callout_func_t *func"
.Fa "void *arg"
.Fa "int cpu"
.Fc
.Ft int
.Fo callout_reset_sbt
.Fa "struct callout *c"
.Fa "sbintime_t sbt"
.Fa "sbintime_t pr"
.Fa "callout_func_t *func"
.Fa "void *arg"
.Fa "int flags"
.Fc
.Ft int
.Fo callout_reset_sbt_curcpu
.Fa "struct callout *c"
.Fa "sbintime_t sbt"
.Fa "sbintime_t pr"
.Fa "callout_func_t *func"
.Fa "void *arg"
.Fa "int flags"
.Fc
.Ft int
.Fo callout_reset_sbt_on
.Fa "struct callout *c"
.Fa "sbintime_t sbt"
.Fa "sbintime_t pr"
.Fa "callout_func_t *func"
.Fa "void *arg"
.Fa "int cpu"
.Fa "int flags"
.Fc
.Ft int
.Fn callout_schedule "struct callout *c" "int ticks"
.Ft int
.Fn callout_schedule_curcpu "struct callout *c" "int ticks"
.Ft int
.Fn callout_schedule_on "struct callout *c" "int ticks" "int cpu"
.Ft int
.Fo callout_schedule_sbt
.Fa "struct callout *c"
.Fa "sbintime_t sbt"
.Fa "sbintime_t pr"
.Fa "int flags"
.Fc
.Ft int
.Fo callout_schedule_sbt_curcpu
.Fa "struct callout *c"
.Fa "sbintime_t sbt"
.Fa "sbintime_t pr"
.Fa "int flags"
.Fc
.Ft int
.Fo callout_schedule_sbt_on
.Fa "struct callout *c"
.Fa "sbintime_t sbt"
.Fa "sbintime_t pr"
.Fa "int cpu"
.Fa "int flags"
.Fc
.Ft int
.Fn callout_stop "struct callout *c"
.Ft sbintime_t
.Fo callout_when
.Fa "sbintime_t sbt"
.Fa "sbintime_t precision"
.Fa "int flags"
.Fa "sbintime_t *sbt_res"
.Fa "sbintime_t *precision_res"
.Fc
.Sh DESCRIPTION
The
.Nm callout
API is used to schedule a call to an arbitrary function at a specific
time in the future.
Consumers of this API are required to allocate a callout structure
.Pq struct callout
for each pending function invocation.
This structure stores state about the pending function invocation including
the function to be called and the time at which the function should be invoked.
Pending function calls can be cancelled or rescheduled to a different time.
In addition,
a callout structure may be reused to schedule a new function call after a
scheduled call is completed.
.Pp
Callouts only provide a single-shot mode.
If a consumer requires a periodic timer,
it must explicitly reschedule each function call.
This is normally done by rescheduling the subsequent call within the called
function.
.Pp
Callout functions must not sleep.
They may not acquire sleepable locks,
wait on condition variables,
perform blocking allocation requests,
or invoke any other action that might sleep.
.Pp
Each callout structure must be initialized by
.Fn callout_init ,
.Fn callout_init_mtx ,
.Fn callout_init_rm ,
or
.Fn callout_init_rw
before it is passed to any of the other callout functions.
The
.Fn callout_init
function initializes a callout structure in
.Fa c
that is not associated with a specific lock.
If the
.Fa mpsafe
argument is zero,
the callout structure is not considered to be
.Dq multi-processor safe ;
and the Giant lock will be acquired before calling the callout function
and released when the callout function returns.
.Pp
The
.Fn callout_init_mtx ,
.Fn callout_init_rm ,
and
.Fn callout_init_rw
functions initialize a callout structure in
.Fa c
that is associated with a specific lock.
The lock is specified by the
.Fa mtx ,
.Fa rm ,
or
.Fa rw
parameter.
The associated lock must be held while stopping or rescheduling the
callout.
The callout subsystem acquires the associated lock before calling the
callout function and releases it after the function returns.
If the callout was cancelled while the callout subsystem waited for the
associated lock,
the callout function is not called,
and the associated lock is released.
This ensures that stopping or rescheduling the callout will abort any
previously scheduled invocation.
.Pp
A sleepable read-mostly lock
.Po
one initialized with the
.Dv RM_SLEEPABLE
flag
.Pc
may not be used with
.Fn callout_init_rm .
Similarly, other sleepable lock types such as
.Xr sx 9
and
.Xr lockmgr 9
cannot be used with callouts because sleeping is not permitted in
the callout subsystem.
.Pp
These
.Fa flags
may be specified for
.Fn callout_init_mtx ,
.Fn callout_init_rm ,
or
.Fn callout_init_rw :
.Bl -tag -width ".Dv CALLOUT_RETURNUNLOCKED"
.It Dv CALLOUT_RETURNUNLOCKED
The callout function will release the associated lock itself,
so the callout subsystem should not attempt to unlock it
after the callout function returns.
.It Dv CALLOUT_SHAREDLOCK
The lock is only acquired in read mode when running the callout handler.
This flag is ignored by
.Fn callout_init_mtx .
.El
.Pp
The function
.Fn callout_stop
cancels a callout
.Fa c
if it is currently pending.
If the callout is pending and successfully stopped, then
.Fn callout_stop
returns a value of one.
If the callout is not set, or
has already been serviced, then
negative one is returned.
If the callout is currently being serviced and cannot be stopped,
then zero will be returned.
If the callout is currently being serviced and cannot be stopped, and at the
same time a next invocation of the same callout is also scheduled, then
.Fn callout_stop
unschedules the next run and returns zero.
If the callout has an associated lock,
then that lock must be held when this function is called.
.Pp
The function
.Fn callout_drain
is identical to
.Fn callout_stop
except that it will wait for the callout
.Fa c
to complete if it is already in progress.
This function MUST NOT be called while holding any
locks on which the callout might block, or deadlock will result.
Note that if the callout subsystem has already begun processing this
callout, then the callout function may be invoked before
.Fn callout_drain
returns.
However, the callout subsystem does guarantee that the callout will be
fully stopped before
.Fn callout_drain
returns.
.Pp
The
.Fn callout_reset
and
.Fn callout_schedule
function families schedule a future function invocation for callout
.Fa c .
If
.Fa c
already has a pending callout,
it is cancelled before the new invocation is scheduled.
These functions return a value of one if a pending callout was cancelled
and zero if there was no pending callout.
If the callout has an associated lock,
then that lock must be held when any of these functions are called.
.Pp
The time at which the callout function will be invoked is determined by
either the
.Fa ticks
argument or the
.Fa sbt ,
.Fa pr ,
and
.Fa flags
arguments.
When
.Fa ticks
is used,
the callout is scheduled to execute after
.Fa ticks Ns No /hz
seconds.
Non-positive values of
.Fa ticks
are silently converted to the value
.Sq 1 .
.Pp
The
.Fa sbt ,
.Fa pr ,
and
.Fa flags
arguments provide more control over the scheduled time including
support for higher resolution times,
specifying the precision of the scheduled time,
and setting an absolute deadline instead of a relative timeout.
The callout is scheduled to execute in a time window which begins at
the time specified in
.Fa sbt
and extends for the amount of time specified in
.Fa pr .
If
.Fa sbt
specifies a time in the past,
the window is adjusted to start at the current time.
A non-zero value for
.Fa pr
allows the callout subsystem to coalesce callouts scheduled close to each
other into fewer timer interrupts,
reducing processing overhead and power consumption.
These
.Fa flags
may be specified to adjust the interpretation of
.Fa sbt
and
.Fa pr :
.Bl -tag -width ".Dv C_DIRECT_EXEC"
.It Dv C_ABSOLUTE
Handle the
.Fa sbt
argument as an absolute time since boot.
By default,
.Fa sbt
is treated as a relative amount of time,
similar to
.Fa ticks .
.It Dv C_DIRECT_EXEC
Run the handler directly from hardware interrupt context instead of from the
softclock thread.
This reduces latency and overhead, but puts more constraints on the callout
function.
Callout functions run in this context may use only spin mutexes for locking
and should be as small as possible because they run with absolute priority.
.It Fn C_PREL
Specifies relative event time precision as binary logarithm of time interval
divided by acceptable time deviation: 1 -- 1/2, 2 -- 1/4, etc.
Note that the larger of
.Fa pr
or this value is used as the length of the time window.
Smaller values
.Pq which result in larger time intervals
allow the callout subsystem to aggregate more events in one timer interrupt.
.It Dv C_PRECALC
The
.Fa sbt
argument specifies the absolute time at which the callout should be run,
and the
.Fa pr
argument specifies the requested precision, which will not be
adjusted during the scheduling process.
The
.Fa sbt
and
.Fa pr
values should be calculated by an earlier call to
.Fn callout_when
which uses the user-supplied
.Fa sbt ,
.Fa pr ,
and
.Fa flags
values.
.It Dv C_HARDCLOCK
Align the timeouts to
.Fn hardclock
calls if possible.
.El
.Pp
The
.Fn callout_reset
functions accept a
.Fa func
argument which identifies the function to be called when the time expires.
It must be a pointer to a function that takes a single
.Fa void *
argument.
Upon invocation,
.Fa func
will receive
.Fa arg
as its only argument.
The
.Fn callout_schedule
functions reuse the
.Fa func
and
.Fa arg
arguments from the previous callout.
Note that one of the
.Fn callout_reset
functions must always be called to initialize
.Fa func
and
.Fa arg
before one of the
.Fn callout_schedule
functions can be used.
.Pp
The callout subsystem provides a softclock thread for each CPU in the system.
Callouts are assigned to a single CPU and are executed by the softclock thread
for that CPU.
Initially,
callouts are assigned to CPU 0.
The
.Fn callout_reset_on ,
.Fn callout_reset_sbt_on ,
.Fn callout_schedule_on
and
.Fn callout_schedule_sbt_on
functions assign the callout to CPU
.Fa cpu .
The
.Fn callout_reset_curcpu ,
.Fn callout_reset_sbt_curpu ,
.Fn callout_schedule_curcpu
and
.Fn callout_schedule_sbt_curcpu
functions assign the callout to the current CPU.
The
.Fn callout_reset ,
.Fn callout_reset_sbt ,
.Fn callout_schedule
and
.Fn callout_schedule_sbt
functions schedule the callout to execute in the softclock thread of the CPU
to which it is currently assigned.
.Pp
Softclock threads are not pinned to their respective CPUs by default.
The softclock thread for CPU 0 can be pinned to CPU 0 by setting the
.Va kern.pin_default_swi
loader tunable to a non-zero value.
Softclock threads for CPUs other than zero can be pinned to their
respective CPUs by setting the
.Va kern.pin_pcpu_swi
loader tunable to a non-zero value.
.Pp
The macros
.Fn callout_pending ,
.Fn callout_active
and
.Fn callout_deactivate
provide access to the current state of the callout.
The
.Fn callout_pending
macro checks whether a callout is
.Em pending ;
a callout is considered
.Em pending
when a timeout has been set but the time has not yet arrived.
Note that once the timeout time arrives and the callout subsystem
starts to process this callout,
.Fn callout_pending
will return
.Dv FALSE
even though the callout function may not have finished
.Pq or even begun
executing.
The
.Fn callout_active
macro checks whether a callout is marked as
.Em active ,
and the
.Fn callout_deactivate
macro clears the callout's
.Em active
flag.
The callout subsystem marks a callout as
.Em active
when a timeout is set and it clears the
.Em active
flag in
.Fn callout_stop
and
.Fn callout_drain ,
but it
.Em does not
clear it when a callout expires normally via the execution of the
callout function.
.Pp
The
.Fn callout_when
function may be used to pre-calculate the absolute time at which the
timeout should be run and the precision of the scheduled run time
according to the required time
.Fa sbt ,
precision
.Fa precision ,
and additional adjustments requested by the
.Fa flags
argument.
Flags accepted by the
.Fn callout_when
function are the same as flags for the
.Fn callout_reset
function.
The resulting time is assigned to the variable pointed to by the
.Fa sbt_res
argument, and the resulting precision is assigned to
.Fa *precision_res .
When passing the results to
.Fa callout_reset ,
add the
.Va C_PRECALC
flag to
.Fa flags ,
to avoid incorrect re-adjustment.
The function is intended for situations where precise time of the callout
run should be known in advance, since
trying to read this time from the callout structure itself after a
.Fn callout_reset
call is racy.
.Ss "Avoiding Race Conditions"
The callout subsystem invokes callout functions from its own thread
context.
Without some kind of synchronization,
it is possible that a callout
function will be invoked concurrently with an attempt to stop or reset
the callout by another thread.
In particular, since callout functions typically acquire a lock as
their first action, the callout function may have already been invoked,
but is blocked waiting for that lock at the time that another thread
tries to reset or stop the callout.
.Pp
There are three main techniques for addressing these
synchronization concerns.
The first approach is preferred as it is the simplest:
.Bl -enum -offset indent
.It
Callouts can be associated with a specific lock when they are initialized
by
.Fn callout_init_mtx ,
.Fn callout_init_rm ,
or
.Fn callout_init_rw .
When a callout is associated with a lock,
the callout subsystem acquires the lock before the callout function is
invoked.
This allows the callout subsystem to transparently handle races between
callout cancellation,
scheduling,
and execution.
Note that the associated lock must be acquired before calling
.Fn callout_stop
or one of the
.Fn callout_reset
or
.Fn callout_schedule
functions to provide this safety.
.Pp
A callout initialized via
.Fn callout_init
with
.Fa mpsafe
set to zero is implicitly associated with the
.Va Giant
mutex.
If
.Va Giant
is held when cancelling or rescheduling the callout,
then its use will prevent races with the callout function.
.It
The return value from
.Fn callout_stop
.Po
or the
.Fn callout_reset
and
.Fn callout_schedule
function families
.Pc
indicates whether or not the callout was removed.
If it is known that the callout was set and the callout function has
not yet executed, then a return value of
.Dv FALSE
indicates that the callout function is about to be called.
For example:
.Bd -literal -offset indent
if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) {
if (callout_stop(&sc->sc_callout)) {
sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING;
/* successfully stopped */
} else {
/*
* callout has expired and callout
* function is about to be executed
*/
}
}
.Ed
.It
The
.Fn callout_pending ,
.Fn callout_active
and
.Fn callout_deactivate
macros can be used together to work around the race conditions.
When a callout's timeout is set, the callout subsystem marks the
callout as both
.Em active
and
.Em pending .
When the timeout time arrives, the callout subsystem begins processing
the callout by first clearing the
.Em pending
flag.
It then invokes the callout function without changing the
.Em active
flag, and does not clear the
.Em active
flag even after the callout function returns.
The mechanism described here requires the callout function itself to
clear the
.Em active
flag using the
.Fn callout_deactivate
macro.
The
.Fn callout_stop
and
.Fn callout_drain
functions always clear both the
.Em active
and
.Em pending
flags before returning.
.Pp
The callout function should first check the
.Em pending
flag and return without action if
.Fn callout_pending
returns
.Dv TRUE .
This indicates that the callout was rescheduled using
.Fn callout_reset
just before the callout function was invoked.
If
.Fn callout_active
returns
.Dv FALSE
then the callout function should also return without action.
This indicates that the callout has been stopped.
Finally, the callout function should call
.Fn callout_deactivate
to clear the
.Em active
flag.
For example:
.Bd -literal -offset indent
mtx_lock(&sc->sc_mtx);
if (callout_pending(&sc->sc_callout)) {
/* callout was reset */
mtx_unlock(&sc->sc_mtx);
return;
}
if (!callout_active(&sc->sc_callout)) {
/* callout was stopped */
mtx_unlock(&sc->sc_mtx);
return;
}
callout_deactivate(&sc->sc_callout);
/* rest of callout function */
.Ed
.Pp
Together with appropriate synchronization, such as the mutex used above,
this approach permits the
.Fn callout_stop
and
.Fn callout_reset
functions to be used at any time without races.
For example:
.Bd -literal -offset indent
mtx_lock(&sc->sc_mtx);
callout_stop(&sc->sc_callout);
/* The callout is effectively stopped now. */
.Ed
.Pp
If the callout is still pending then these functions operate normally,
but if processing of the callout has already begun then the tests in
the callout function cause it to return without further action.
Synchronization between the callout function and other code ensures that
stopping or resetting the callout will never be attempted while the
callout function is past the
.Fn callout_deactivate
call.
.Pp
The above technique additionally ensures that the
.Em active
flag always reflects whether the callout is effectively enabled or
disabled.
If
.Fn callout_active
returns false, then the callout is effectively disabled, since even if
the callout subsystem is actually just about to invoke the callout
function, the callout function will return without action.
.El
.Pp
There is one final race condition that must be considered when a
callout is being stopped for the last time.
In this case it may not be safe to let the callout function itself
detect that the callout was stopped, since it may need to access
data objects that have already been destroyed or recycled.
To ensure that the callout is completely finished, a call to
.Fn callout_drain
should be used.
In particular,
a callout should always be drained prior to destroying its associated lock
or releasing the storage for the callout structure.
.Sh RETURN VALUES
The
.Fn callout_active
macro returns the state of a callout's
.Em active
flag.
.Pp
The
.Fn callout_pending
macro returns the state of a callout's
.Em pending
flag.
.Pp
The
.Fn callout_reset
and
.Fn callout_schedule
function families return a value of one if the callout was pending before the new
function invocation was scheduled.
.Pp
The
.Fn callout_stop
and
.Fn callout_drain
functions return a value of one if the callout was still pending when it was
called, a zero if the callout could not be stopped and a negative one is it
was either not running or has already completed.
+.Sh SEE ALSO
+.Xr dtrace_callout_execute 4
.Sh HISTORY
.Fx
initially used the long standing
.Bx
linked list
callout mechanism which offered O(n) insertion and removal running time
but did not generate or require handles for untimeout operations.
.Pp
.Fx 3.0
introduced a new set of timeout and untimeout routines from
.Nx
based on the work of
.An Adam M. Costello
and
.An George Varghese ,
published in a technical report entitled
.%T "Redesigning the BSD Callout and Timer Facilities"
and modified for inclusion in
.Fx
by
.An Justin T. Gibbs .
The original work on the data structures used in that implementation
was published by
.An G. Varghese
and
.An A. Lauck
in the paper
.%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility"
in the
.%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" .
.Pp
.Fx 3.3
introduced the first implementations of
.Fn callout_init ,
.Fn callout_reset ,
and
.Fn callout_stop
which permitted callers to allocate dedicated storage for callouts.
This ensured that a callout would always fire unlike
.Fn timeout
which would silently fail if it was unable to allocate a callout.
.Pp
.Fx 5.0
permitted callout handlers to be tagged as MPSAFE via
.Fn callout_init .
.Pp
.Fx 5.3
introduced
.Fn callout_drain .
.Pp
.Fx 6.0
introduced
.Fn callout_init_mtx .
.Pp
.Fx 8.0
introduced per-CPU callout wheels,
.Fn callout_init_rw ,
and
.Fn callout_schedule .
.Pp
.Fx 9.0
changed the underlying timer interrupts used to drive callouts to prefer
one-shot event timers instead of a periodic timer interrupt.
.Pp
.Fx 10.0
switched the callout wheel to support tickless operation.
These changes introduced
.Vt sbintime_t
and the
.Fn callout_reset_sbt*
family of functions.
.Fx 10.0 also added
.Dv C_DIRECT_EXEC
and
.Fn callout_init_rm .
.Pp
.Fx 10.2
introduced the
.Fn callout_schedule_sbt*
family of functions.
.Pp
.Fx 11.0
introduced
.Fn callout_async_drain .
.Fx 11.1
introduced
.Fn callout_when .
.Fx 13.0
removed
.Vt timeout_t ,
.Fn timeout ,
and
.Fn untimeout .