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