1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright (c) 2015, Joyent, Inc. 13.\" 14.Dd Oct 4, 2014 15.Dt CTFDIFF 1 16.Os 17.Sh NAME 18.Nm ctfdiff 19.Nd compare two CTF containers 20.Sh SYNOPSIS 21.Nm ctfdiff 22.Op Fl afIloqt 23.Op Fl F Ar function 24.Op Fl O Ar object 25.Op Fl p Ar parent1 26.Op Fl p Ar parent2 27.Op Fl T Ar type 28.Ar file1 file2 29.Sh DESCRIPTION 30The 31.Nm 32utility identifies differences between the contents of the 33.Sy CTF 34containers found in 35.Em file1 36and 37.Em file2 . 38.Lp 39.Nm 40can find differences between two 41.Sy CTF 42container's 43.Sy labels , 44.Sy functions , 45.Sy objects , 46and 47.Sy types . 48When no options are specified, 49.Nm 50will only consider 51.Sy functions , 52.Sy objects, 53and 54.Sy types . 55.Lp 56Two 57.Sy labels 58are the same if they have the same name. 59Two 60.Sy objects 61are the same if they have the same name and the type of the 62object is the same. 63Two 64.Sy functions 65are considered the same if they have the same name, the same return 66type, the same number of arguments, and the types of their arguments are 67the same. 68.Lp 69Two 70.Sy types 71are considered the same if they have the same name, they represent the same 72kind of thing, and the contents of the type are the same. 73This varies for each specific kind, for example, two structs are the 74same if they have the same members whose types, offsets, and names are 75all the same. 76For more information on the specifics for what we look at 77for each kind of type, and the kinds themselves, see the information we 78use to encode them in 79.Xr ctf 4 . 80If the option 81.Fl I 82is specified, then the names of basic integer types are ignored. 83For an example of where this makes sense, see 84.Sy Example 4 . 85.Lp 86If the 87.Sy CTF 88container found inside of either 89.Em file1 90or 91.Em file2 92has been uniquified (see 93.Xr ctf 4 94for more on uniquification), then the parent 95.Sy CTF 96container is also required for the diff to complete. 97.Sh OPTIONS 98The following options are supported: 99.Bl -hang -width Ds 100.It Fl a 101.Bd -filled -compact 102Diff 103.Sy labels , 104.Sy types , 105.Sy objects , 106and 107.Sy functions . 108.Ed 109.It Fl f 110.Bd -filled -compact 111Diff 112.Sy function 113type argument information. 114.Ed 115.It Fl F Ar function 116.Bd -filled -compact 117When diffing 118.Sy functions , 119only consider the function 120.Em function . 121This option requires that the option 122.Fl f 123be specified and can be repeated multiple times. 124.Ed 125.It Fl I 126.Bd -filled -compact 127Ignore the names of integral types. 128This option is useful when comparing types between two 129.Sy CTF 130containers that have different programming models. 131In this case, when comparing integers, the name of the type is not 132considered. 133This means that the ILP32 type long which is a 32-bit wide signed 134integer is the same as the LP64 type int which is a 32-bit wide signed 135integer, even though they have different names. 136.Ed 137.It Fl l 138.Bd -filled -compact 139Diff the 140.Sy labels 141contained inside the 142.Sy CTF 143containers. 144.Ed 145.It Fl o 146.Bd -filled -compact 147Diff type information for 148.Sy objects . 149.Ed 150.It Fl O Ar object 151.Bd -filled -compact 152When diffing type information for 153.Sy objects , 154only compare if the object is name 155.Em object . 156This option requires 157.Fl o 158to be specified and can be repeated multiple times. 159.Ed 160.It Fl p Ar parent1 161.Bd -filled -compact 162Specifies the path of file that is the parent of the 163.Sy CTF 164container inside of 165.Em file1 166is 167.Em parent1 . 168This option is required if 169.Em file1 170has been uniquified. 171For more information on uniquification, see 172.Xr ctf 4 . 173.Ed 174.It Fl P Ar parent2 175.Bd -filled -compact 176Specifies the path of file that is the parent of the 177.Sy CTF 178container inside of 179.Em file2 is 180.Em parent2 . 181This option is required if 182.Em file1 183has been uniquified. 184For more information on uniquification, see 185.Xr ctf 4 . 186.Ed 187.It Fl q 188.Bd -filled -compact 189Enables quiet mode. 190Standard output from the diff will not be emitted. 191However, diagnostics messages will still be emitted to standard error. 192.Ed 193.It Fl t 194.Bd -filled -compact 195Diff the 196.Sy type 197information sections in the 198.Sy CTF 199containers. 200.Ed 201.It Fl T Ar type 202.Bd -filled -compact 203When diffing the 204.Sy types 205section, only consider it if the type is name 206.Em type . 207Types specified here do not impact the diffing of 208.Sy objects 209or 210.Sy functions . 211Even with 212.Fl T 213specified, other types will be diffed as necessary for the evaluation of 214the named types; however, the results of those intermediate differences 215will not impact the results of 216.Nm , 217only named types are considered when evaluating the exit status of 218.Nm . 219.Ed 220.El 221.Sh EXIT STATUS 222.Bl -inset 223.It Sy 0 224.Bd -filled -offset indent -compact 225Execution completed successfully, no differences were detected 226between 227.Em file1 228and 229.Em file2 . 230.Ed 231.It Sy 1 232.Bd -filled -offset indent -compact 233Execution completed successfully, but differences were detected 234between 235.Em file1 236and 237.Em file2 . 238.Ed 239.It Sy 2 240.D1 Invalid command line options were specified. 241.It Sy 3 242.D1 A fatal error occurred. 243.El 244.Sh EXAMPLES 245.Sy Example 1 246Diffing Two 247.Sy CTF 248Containers 249.Lp 250The following example compares two 251.Sy CTF 252containers using the default set 253of comparisons: 254.Sy objects , 255.Sy functions , 256and 257.Sy types . 258.Bd -literal -offset 6n 259$ ctfdiff /usr/lib/libc.so.1 /usr/lib/libdtrace.so.1 260ctf container /usr/lib/libc.so.1 type 37 is different 261ctf container /usr/lib/libc.so.1 type 38 is different 262ctf container /usr/lib/libc.so.1 type 39 is different 263ctf container /usr/lib/libc.so.1 type 40 is different 264ctf container /usr/lib/libc.so.1 type 41 is different 265ctf container /usr/lib/libc.so.1 type 42 is different 266ctf container /usr/lib/libc.so.1 type 43 is different 267ctf container /usr/lib/libc.so.1 type 47 is different 268ctf container /usr/lib/libc.so.1 type 48 is different 269ctf container /usr/lib/libc.so.1 type 49 is different 270\&... 271.Ed 272.Sy Example 2 273Diffing Types Between Two 274.Sy CTF 275Containers with Parents 276.Lp 277The following example compares two 278.Sy CTF 279containers 280.Sy /ws/rm/zlan/proto/kernel/drv/amd64/vnd 281and 282.Sy /ws/rm/zlan/proto/kernel/drv/amd64/overlay 283that have been uniquified against the same container 284.Sy /ws/rm/zlan/proto/kernel/amd64/genunix . 285.Bd -literal -offset 6n 286$ ctfdiff -t -p /ws/rm/zlan/proto/kernel/amd64/genunix \\ 287 -P /ws/rm/zlan/proto/kernel/amd64/genunix \\ 288 /ws/rm/zlan/proto/kernel/drv/amd64/vnd \\ 289 /ws/rm/zlan/proto/kernel/drv/amd64/overlay 290ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32769 is different 291ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32770 is different 292ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32771 is different 293ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32772 is different 294ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32774 is different 295ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32775 is different 296ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32776 is different 297ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32777 is different 298ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32778 is different 299ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32779 is different 300\&... 301.Ed 302.Lp 303.Sy Example 3 304Diffing a Specific Function in Two 305.Sy CTF 306Containers 307.Lp 308This example shows us looking for differences in the function 309.Sy libzfs_core_init 310in two different version of the library 311.Sy libzfs_core.so.1 . 312.Bd -literal -offset 6n 313$ ctfdiff -f -F libzfs_core_init /usr/lib/libzfs_core.so.1 \\ 314 /ws/rm/ctf/proto/usr/lib/libzfs_core.so.1 315$ echo $? 316.Ed 317.Lp 318.Sy Example 4 319Diffing Types to Find Differences Between Different Data Models. 320.Lp 321This example looks for differences between structures used in an ioctl 322that the kernel wants to be bitness neutral by comparing a 32-bit and 32364-bit library that consumes it. 324In this example, we'll use the library 325.Sy libvnd.so.1 326and the types 327.Sy vnd_ioc_attach_t , 328.Sy vnd_ioc_link_t , 329.Sy vnd_ioc_unlink_t , 330.Sy vnd_ioc_buf_t , 331and 332.Sy vnd_ioc_info_t . 333.Bd -literal -offset 6n 334$ ctfdiff -t -I -T vnd_ioc_attach_t -T vnd_ioc_link_t \\ 335 -T vnd_ioc_unlink_t -T vnd_ioc_buf_t -T vnd_ioc_info_t \\ 336 i386/libvnd.so.1 amd64/libvnd.so.1 337$ echo $? 3380 339.Ed 340.Sh INTERFACE STABILITY 341The command syntax is 342.Sy Committed . 343The output format is 344.Sy Uncommitted . 345.Sh SEE ALSO 346.Xr ctfdump 1 , 347.Xr diff 1 , 348.Xr ctf 4 349