Tribblix: manual page: ctfdiff.1

CTFDIFF(1) User Commands CTFDIFF(1)

NAME

ctfdiff - compare two CTF containers

SYNOPSIS

ctfdiff [-afIloqt] [-F function] [-O object] [-p parent1] [-p parent2]
[-T type] file1 file2

DESCRIPTION

The ctfdiff utility identifies differences between the contents of the
CTF containers found in file1 and file2.

ctfdiff can find differences between two CTF container's labels,
functions, objects, and types. When no options are specified, ctfdiff
will only consider functions, objects, and types.

Two labels are the same if they have the same name. Two objects are
the same if they have the same name and the type of the object is the
same. Two functions are considered the same if they have the same
name, the same return type, the same number of arguments, and the types
of their arguments are the same.

Two types are considered the same if they have the same name, they
represent the same kind of thing, and the contents of the type are the
same. This varies for each specific kind, for example, two structs are
the same if they have the same members whose types, offsets, and names
are all the same. For more information on the specifics for what we
look at for each kind of type, and the kinds themselves, see the
information we use to encode them in ctf(5). If the option -I is
specified, then the names of basic integer types are ignored. For an
example of where this makes sense, see Example 4.

If the CTF container found inside of either file1 or file2 has been
uniquified (see ctf(5) for more on uniquification), then the parent CTF
container is also required for the diff to complete.

OPTIONS

The following options are supported:

-a
Diff labels, types, objects, and functions.

-f
Diff function type argument information.

-F function
When diffing functions, only consider the function function.
This option requires that the option -f be specified and can be
repeated multiple times.

-I
Ignore the names of integral types. This option is useful when
comparing types between two CTF containers that have different
programming models. In this case, when comparing integers, the
name of the type is not considered. This means that the ILP32
type long which is a 32-bit wide signed integer is the same as
the LP64 type int which is a 32-bit wide signed integer, even
though they have different names.

-l
Diff the labels contained inside the CTF containers.

-o
Diff type information for objects.

-O object
When diffing type information for objects, only compare if the
object is name object. This option requires -o to be specified
and can be repeated multiple times.

-p parent1
Specifies the path of file that is the parent of the CTF
container inside of file1 is parent1. This option is required
if file1 has been uniquified. For more information on
uniquification, see ctf(5).

-P parent2
Specifies the path of file that is the parent of the CTF
container inside of file2 is parent2. This option is required
if file1 has been uniquified. For more information on
uniquification, see ctf(5).

-q
Enables quiet mode. Standard output from the diff will not be
emitted. However, diagnostics messages will still be emitted
to standard error.

-t
Diff the type information sections in the CTF containers.

-T type
When diffing the types section, only consider it if the type is
name type. Types specified here do not impact the diffing of
objects or functions. Even with -T specified, other types will
be diffed as necessary for the evaluation of the named types;
however, the results of those intermediate differences will not
impact the results of ctfdiff, only named types are considered
when evaluating the exit status of ctfdiff.

EXIT STATUS

0
Execution completed successfully, no differences were detected
between file1 and file2.

1
Execution completed successfully, but differences were detected
between file1 and file2.

2
Invalid command line options were specified.

3
A fatal error occurred.

EXAMPLES

Example 1 Diffing Two CTF Containers

The following example compares two CTF containers using the default set
of comparisons: objects, functions, and types.

$ ctfdiff /usr/lib/libc.so.1 /usr/lib/libdtrace.so.1
ctf container /usr/lib/libc.so.1 type 37 is different
ctf container /usr/lib/libc.so.1 type 38 is different
ctf container /usr/lib/libc.so.1 type 39 is different
ctf container /usr/lib/libc.so.1 type 40 is different
ctf container /usr/lib/libc.so.1 type 41 is different
ctf container /usr/lib/libc.so.1 type 42 is different
ctf container /usr/lib/libc.so.1 type 43 is different
ctf container /usr/lib/libc.so.1 type 47 is different
ctf container /usr/lib/libc.so.1 type 48 is different
ctf container /usr/lib/libc.so.1 type 49 is different
...
Example 2 Diffing Types Between Two CTF Containers with Parents

The following example compares two CTF containers
/ws/rm/zlan/proto/kernel/drv/amd64/vnd and
/ws/rm/zlan/proto/kernel/drv/amd64/overlay that have been uniquified
against the same container /ws/rm/zlan/proto/kernel/amd64/genunix.

$ ctfdiff -t -p /ws/rm/zlan/proto/kernel/amd64/genunix \
-P /ws/rm/zlan/proto/kernel/amd64/genunix \
/ws/rm/zlan/proto/kernel/drv/amd64/vnd \
/ws/rm/zlan/proto/kernel/drv/amd64/overlay
ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32769 is different
ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32770 is different
ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32771 is different
ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32772 is different
ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32774 is different
ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32775 is different
ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32776 is different
ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32777 is different
ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32778 is different
ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32779 is different
...

Example 3 Diffing a Specific Function in Two CTF Containers

This example shows us looking for differences in the function
libzfs_core_init in two different version of the library
libzfs_core.so.1.

$ ctfdiff -f -F libzfs_core_init /usr/lib/libzfs_core.so.1 \
/ws/rm/ctf/proto/usr/lib/libzfs_core.so.1
$ echo $?

Example 4 Diffing Types to Find Differences Between Different Data
Models.

This example looks for differences between structures used in an ioctl
that the kernel wants to be bitness neutral by comparing a 32-bit and
64-bit library that consumes it. In this example, we'll use the
library libvnd.so.1 and the types vnd_ioc_attach_t, vnd_ioc_link_t,
vnd_ioc_unlink_t, vnd_ioc_buf_t, and vnd_ioc_info_t.

$ ctfdiff -t -I -T vnd_ioc_attach_t -T vnd_ioc_link_t \
-T vnd_ioc_unlink_t -T vnd_ioc_buf_t -T vnd_ioc_info_t \
i386/libvnd.so.1 amd64/libvnd.so.1
$ echo $?
0

INTERFACE STABILITY

The command syntax is Committed. The output format is Uncommitted.