xref: /titanic_51/usr/src/man/man1/ctfdiff.1 (revision a29e56d91db891741f1af9f6bbd3e3c3cac5f19b) 
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