History log of /freebsd-head/lib/libsysdecode/sysdecode.3
Revision Date Author Comments
ae6222b0c3494c3ec754ff9dd42367f813087472 06-Mar-2019 jhb <jhb@FreeBSD.org> Drop "All rights reserved" from my copyright statements.

Reviewed by: rgrimes
MFC after: 1 month
Differential Revision: https://reviews.freebsd.org/D19485
ee7ec2c7d842c10a3abe0bec99e3b1e478d2f5a9 26-Apr-2018 emaste <emaste@FreeBSD.org> libsysdecode: support errno and syscalls for arm64 Linux

Sponsored by: Turing Robotic Industries Inc.
aab0289ab1e1680ac2abeee8477c3e97f43ce1d4 15-Jan-2018 tuexen <tuexen@FreeBSD.org> Add support for decoding the type of a cmsg.
dc1ea661c79a876985c0680fb5106f731164e051 14-Jan-2018 tuexen <tuexen@FreeBSD.org> Add a function is decode the sinfo_flags of struct sctp_sndrcvinfo.
118522df7e441e11f6914286a976da2675501935 16-Dec-2017 ed <ed@FreeBSD.org> libsysdecode: Add a new ABI type, SYSDECODE_ABI_CLOUDABI32.

In order to let truss(8) support tracing of 32-bit CloudABI
applications, we need to add a new ABI type to libsysdecode. We can
reuse the existing errno mapping table. Also link in the cloudabi32
system call table to translate system call names.

While there, remove all of the architecture ifdefs. There are not
needed, as the CloudABI data types and system call tables build fine on
any architecture. Building this unconditionally will make it easier to
do tracing for different compat modes, emulation, etc.

Reviewed by: jhb
Differential Revision: https://reviews.freebsd.org/D13516
bac78aa2a49020f1e67b0d1b05e5daf2213879ae 25-Nov-2017 jhb <jhb@FreeBSD.org> Decode kevent structures logged via ktrace(2) in kdump.

- Add a new KTR_STRUCT_ARRAY ktrace record type which dumps an array of

The structure name in the record payload is preceded by a size_t
containing the size of the individual structures. Use this to
replace the previous code that dumped the kevent arrays dumped for
kevent(). kdump is now able to decode the kevent structures rather
than dumping their contents via a hexdump.

One change from before is that the 'changes' and 'events' arrays are
not marked with separate 'read' and 'write' annotations in kdump
output. Instead, the first array is the 'changes' array, and the
second array (only present if kevent doesn't fail with an error) is
the 'events' array. For kevent(), empty arrays are denoted by an
entry with an array containing zero entries rather than no record.

- Move kevent decoding tables from truss to libsysdecode.

This adds three new functions to decode members of struct kevent:
sysdecode_kevent_filter, sysdecode_kevent_flags, and

kdump uses these helper functions to pretty-print kevent fields.

- Move structure definitions for freebsd11 and freebsd32 kevent
structures to <sys/event.h> so that they can be shared with userland.
The 32-bit structures are only exposed if _WANT_KEVENT32 is defined.
The freebsd11 structures are only exposed if _WANT_FREEBSD11_KEVENT is
defined. The 32-bit freebsd11 structure requires both.

- Decode freebsd11 kevent structures in truss for the compat11.kevent()
system call.

- Log 32-bit kevent structures via ktrace for 32-bit compat kevent()
system calls.

- While here, constify the 'void *data' argument to ktrstruct().

Reviewed by: kib (earlier version)
MFC after: 1 month
Differential Revision: https://reviews.freebsd.org/D12470
838d4edd0a38d39d1c1edd8a2b03c5deaf6c8535 03-Jun-2017 dim <dim@FreeBSD.org> Merge ^/head r319480 through r319547.
f26dbec8ca1c7ccd572505a060176c168c9a5908 03-Jun-2017 jhb <jhb@FreeBSD.org> Add a cross-reference to sysdecode_socket_protocol(3).
27ec61a4375f38949fd0636093b5d362ddd043a8 17-Oct-2016 jhb <jhb@FreeBSD.org> Move mksubr from kdump into libsysdecode.

Restructure this script so that it generates a header of tables instead
of a source file. The tables are included in a flags.c source file which
provides functions to decode various system call arguments.

For functions that decode an enumeration, the function returns a pointer
to a string for known values and NULL for unknown values.

For functions that do more complex decoding (typically of a bitmask), the
function accepts a pointer to a FILE object (open_memstream() can be used
as a string builder) to which decoded values are written. If the
function operates on a bitmask, the function returns true if any bits
were decoded or false if the entire value was valid. Additionally, the
third argument accepts a pointer to a value to which any undecoded bits
are stored. This pointer can be NULL if the caller doesn't care about
remaining bits.

Convert kdump over to using decoder functions from libsysdecode instead of
mksubr. truss also uses decoders from libsysdecode instead of private
lookup tables, though lookup tables for objects not decoded by kdump remain
in truss for now. Eventually most of these tables should move into
libsysdecode as the automated table generation approach from mksubr is
less stale than the static tables in truss.

Some changes have been made to truss and kdump output:
- The flags passed to open() are now properly decoded in that one of
O_RDONLY, O_RDWR, O_WRONLY, or O_EXEC is always included in a decoded
- Optional arguments to open(), openat(), and fcntl() are only printed
in kdump if they exist (e.g. the mode is only printed for open() if
O_CREAT is set in the flags).
- Print argument to F_GETLK/SETLK/SETLKW in kdump as a pointer, not int.
- Include all procctl() commands.
- Correctly decode pipe2() flags in truss by not assuming full
open()-like flags with O_RDONLY, etc.
- Decode file flags passed to *chflags() as file flags (UF_* and SF_*)
rather than as a file mode.
- Fix decoding of quotactl() commands by splitting out the two command
components instead of assuming the raw command value matches the
primary command component.

In addition, truss and kdump now build without triggering any warnings.
All of the sysdecode manpages now include the required headers in the

Reviewed by: kib (several older versions), wblock (manpages)
MFC after: 2 months
Differential Revision: https://reviews.freebsd.org/D7847
00d578928eca75be320b36d37543a7e2a4f9fbdb 27-May-2016 grehan <grehan@FreeBSD.org> Create branch for bhyve graphics import.
ca284988772507a1b799a619df4b7041a4dc9369 23-Feb-2016 jhb <jhb@FreeBSD.org> Add handling for non-native error values to libsysdecode.

Add two new functions, sysdecode_abi_to_freebsd_errno() and
sysdecode_freebsd_to_abi_errno(), which convert errno values between
the native FreeBSD ABI and other supported ABIs. Note that the
mappings are not necessarily perfect meaning in some cases multiple
errors in one ABI might map to a single error in another ABI. In that
case, the reverse mapping will return one of the errors that maps, but
which error is non-deterministic.

Change truss to always report the raw error value to the user but
use libsysdecode to map it to a native errno value that can be used
with strerror() to generate a description. Previously truss reported
the "converted" error value. Now the user will always see the exact
error value that the application sees.

Change kdump to report the truly raw error value to the user. Previously
kdump would report the absolute value of the raw error value (so for
Linux binaries it didn't output the FreeBSD error value, but the positive
value of the Linux error). Now it reports the real (i.e. negative) error
value for Linux binaries. Also, use libsysdecode to convert the native
FreeBSD error reported in the ktrace record to the raw error used by the
ABI. This means that the Linux ABI can now be handled directly in
ktrsysret() and removes the need for linux_ktrsysret().

Reviewed by: bdrewery, kib
Helpful notes: wblock (manpage)
Differential Revision: https://reviews.freebsd.org/D5314
377cdb0ab1f7d246659c637faafe7c54af0665e5 30-Jan-2016 jhb <jhb@FreeBSD.org> Add a SYSDECODE_ABI_ prefix to the ABI enums to avoid potential collisions.

Suggested by: jmallett
Reviewed by: bdrewery, jmallett
Differential Revision: https://reviews.freebsd.org/D5123
cd4a0ee266068abaf08833b8d76b0ad8b0cea721 26-Jan-2016 jhb <jhb@FreeBSD.org> Add support to libsysdecode for decoding system call names.

A new sysdecode_syscallname() function accepts a system call code and
returns a string of the corresponding name (or NULL if the code is
unknown). To support different process ABIs, the new function accepts a
value from a new sysdecode_abi enum as its first argument to select the
ABI in use. Current ABIs supported include FREEBSD (native binaries),
FREEBSD32, LINUX, LINUX32, and CLOUDABI64. Note that not all ABIs are
supported by all platforms. In general, a given ABI is only supported
if a platform can execute binaries for that ABI.

To simplify the implementation, libsysdecode's build reuses the
existing pre-generated files from the kernel source tree rather than
duplicating new copies of said files during the build.

kdump(1) and truss(1) now use these functions to map system call
identifiers to names. For kdump(1), a new 'syscallname()' function
consolidates duplicated code from ktrsyscall() and ktrsyscallret().
The Linux ABI no longer requires custom handling for ktrsyscall() and
linux_ktrsyscall() has been removed as a result.

Reviewed by: bdrewery
Differential Revision: https://reviews.freebsd.org/D4823
b665ac07581ab1fbd0d71db29a027b4a39734789 22-Dec-2015 jhb <jhb@FreeBSD.org> Move the mkioctls script to libsysdecode and use it to generate a
sysdecode_ioctlname() function. This function matches the behavior
of the truss variant in that it returns a pointer to a string description
for known ioctls. The caller is responsible for displaying unknown
ioctl requests. For kdump this meant moving the logic to handle unknown
ioctl requests out of the generated function and into an ioctlname()
function in kdump.c instead.

Differential Revision: https://reviews.freebsd.org/D4610
fea0add70e97d3866543fe397202ecc6d1413e65 15-Dec-2015 jhb <jhb@FreeBSD.org> Start on a new library (libsysdecode) that provides routines for decoding
system call information such as system call arguments. Initially this
will consist of pulling duplicated code out of truss and kdump though it
may prove useful for other utilities in the future.

This commit moves the shared utrace(2) record parser out of kdump into
the library and updates kdump and truss to use it. One difference from
the previous version is that the library version treats unknown events
that start with the "RTLD" signature as unknown events. This simplifies
the interface and allows the consumer to decide how to handle all
non-recognized events. Instead, this function only generates a string
description for known malloc() and RTLD records.

Reviewed by: bdrewery
Differential Revision: https://reviews.freebsd.org/D4537