illumos: 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.