| blob | 8304261cd3bcf6b6dd57bd980a42462ae4001dc1 |
1 '\" te
2 .\" Copyright (c) 2008, Sun Microsystems, Inc.
3 .\" All Rights Reserved
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH PVS 1 "Sep 25, 2008"
8 .SH NAME
9 pvs \- display the internal version information of dynamic objects
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fBpvs\fR [\fB-Cdlnorsv\fR] [\fB-I\fR \fIindex-expr\fR] [\fB-N\fR \fIname\fR] \fIfile\fR...
14 .fi
16 .SH DESCRIPTION
17 .sp
18 .LP
19 The \fBpvs\fR utility displays any internal version information contained
20 within an \fBELF\fR file. Commonly, these files are dynamic executables and
21 shared objects, and possibly relocatable objects. This version information can
22 fall into one of two categories:
23 .RS +4
24 .TP
25 .ie t \(bu
26 .el o
27 version definitions
28 .RE
29 .RS +4
30 .TP
31 .ie t \(bu
32 .el o
33 version dependencies
34 .RE
35 .sp
36 .LP
37 Version \fIdefinitions\fR describe the interfaces that are made available by an
38 \fBELF\fR file. Each version definition is associated to a set of global
39 symbols provided by the file. Version definitions can be assigned to a file
40 during its creation by the link-editor using the \fB-M\fR option and the
41 associated \fImapfile\fR directives. See the \fILinker and Libraries Guide\fR
42 for more details.
43 .sp
44 .LP
45 Version \fIdependencies\fR describe the binding requirements of dynamic objects
46 on the version definitions of any shared object dependencies. When a dynamic
47 object is built with a shared object, the link-editor records information
48 within the dynamic object indicating that the shared object is a dependency.
49 This dependency must be satisfied at runtime. If the shared object also
50 contains version \fIdefinitions\fR, then those version definitions that satisfy
51 the global symbol requirements of the dynamic object are also recorded in the
52 dynamic object being created. At process initialization, the runtime linker
53 uses any version \fIdependencies\fR as a means of validating the interface
54 requirements of the dynamic objects used to construct the process.
55 .SH OPTIONS
56 .sp
57 .LP
58 The following options are supported. If neither the \fB-d\fR or \fB-r\fR
59 options are specified, both are enabled.
60 .sp
61 .ne 2
62 .na
63 \fB\fB-C\fR\fR
64 .ad
65 .RS 18n
66 Demangles C++ symbol names.
67 .RE
69 .sp
70 .ne 2
71 .na
72 \fB\fB-d\fR\fR
73 .ad
74 .RS 18n
75 Prints version definition information.
76 .RE
78 .sp
79 .ne 2
80 .na
81 \fB\fB-I\fR \fIindex-expr\fR\fR
82 .ad
83 .RS 18n
84 Qualifies the versions to examine with a specific version index or index range.
85 For example, the version with index 3 in an object can be displayed using:
86 .sp
87 .in +2
88 .nf
89 example% \fBpvs -I 3 \fIfilename\fR\fR
90 .fi
91 .in -2
92 .sp
94 An \fIindex-expr\fR can be a single non-negative integer value that specifies a
95 specific version, as shown in the previous example. Alternatively, an
96 \fIindex-expr\fR can consist of two such values separated by a colon (:),
97 indicating a range of versions. The following example displays the versions 3,
98 4, and 5 in a file:
99 .sp
100 .in +2
101 .nf
102 example% \fBpvs -I 3:5 \fIfilename\fR\fR
103 .fi
104 .in -2
105 .sp
107 When specifying an index range, the second value can be omitted to indicate the
108 final item in the file. For example, the following statement lists all versions
109 from the tenth to the end:
110 .sp
111 .in +2
112 .nf
113 example% \fBpvs -I 10: \fIfilename\fR\fR
114 .fi
115 .in -2
116 .sp
118 See Matching Options for additional information about the matching options
119 (\fB-I\fR, \fB-N\fR).
120 .RE
122 .sp
123 .ne 2
124 .na
125 \fB\fB-l\fR\fR
126 .ad
127 .RS 18n
128 Prints any symbols that have been reduced from global to local binding due to
129 versioning. By convention, these symbol entries are located in the
130 \fI\&.symtab\fR section, and fall between the \fIFILE\fR symbol representing
131 the output file, and the \fIFILE\fR symbol representing the first input file
132 used to generate the output file. These reduced symbol entries are assigned
133 the fabricated version definition \fB_LOCAL_\fR. No reduced symbols will be
134 printed if the file has been stripped (see \fBstrip\fR(1)), or if the symbol
135 entry convention cannot be determined.
136 .sp
137 Use of the \fB-l\fR option implicitly enables the \fB-s\fR option
138 .RE
140 .sp
141 .ne 2
142 .na
143 \fB\fB-n\fR\fR
144 .ad
145 .RS 18n
146 Normalizes version definition information. By default, all version definitions
147 within the object are displayed. However, version definitions can inherit other
148 version definitions. Under normalization, only the head of each inheritance
149 list is displayed.
150 .RE
152 .sp
153 .ne 2
154 .na
155 \fB\fB-N\fR \fIname\fR\fR
156 .ad
157 .RS 18n
158 When used with the \fB-d\fR option, \fB-N\fR prints only the information for
159 the given version definition \fIname\fR and any of its inherited version
160 definitions.
161 .sp
162 When used with the \fB-r\fR option, \fB-N\fR prints only the information for
163 the given dependency file \fIname\fR. It is possible to qualify a specific
164 version from the dependency file by including the version in parenthesis
165 following the file name:
166 .sp
167 .in +2
168 .nf
169 example% \fBpvs -N 'dependency (version)' \fIfilename\fR\fR
170 .fi
171 .in -2
172 .sp
174 See Matching Options for additional information about the matching options
175 (\fB-I\fR, \fB-N\fR).
176 .RE
178 .sp
179 .ne 2
180 .na
181 \fB\fB-o\fR\fR
182 .ad
183 .RS 18n
184 Creates one-line version definition output. By default, file, version
185 definitions, and any symbol output is indented to ease human inspection. This
186 option prefixes each output line with the file and version definition name and
187 can be more useful for analysis with automated tools.
188 .RE
190 .sp
191 .ne 2
192 .na
193 \fB\fB-r\fR\fR
194 .ad
195 .RS 18n
196 Prints version dependency (requirements) information.
197 .RE
199 .sp
200 .ne 2
201 .na
202 \fB\fB-s\fR\fR
203 .ad
204 .RS 18n
205 Prints the symbols associated with each version definition. Any data symbols
206 from versions defined by the object are accompanied with the size, in bytes, of
207 the data item.
208 .RE
210 .sp
211 .ne 2
212 .na
213 \fB\fB-v\fR\fR
214 .ad
215 .RS 18n
216 Verbose output. Indicates any weak version definitions, and any version
217 definition inheritance. When used with the \fB-N\fR and \fB-d\fR options, the
218 inheritance of the base version definition is also shown. When used with the
219 \fB-s\fR option, the version symbol definition is also shown.
220 .RE
222 .SH OPERANDS
223 .sp
224 .LP
225 The following operands are supported.
226 .sp
227 .ne 2
228 .na
229 \fB\fIfile\fR\fR
230 .ad
231 .RS 8n
232 The \fBELF\fR file about which internal version information is displayed.
233 .RE
235 .SH USAGE
236 .SS "Matching Options"
237 .sp
238 .LP
239 The \fB-I\fR and \fB-N\fR options are collectively referred to as the
240 \fBmatching options\fR. These options are used to narrow the range of versions
241 to examine, by index or by name.
242 .sp
243 .LP
244 Any number and type of matching option can be mixed in a given invocation of
245 \fBpvs\fR. In this case, \fBpvs\fR displays the superset of all versions
246 matched by any of the matching options used. This feature allows for the
247 selection of complex groupings of items using the most convenient form for
248 specifying each item.
249 .SH EXAMPLES
250 .LP
251 \fBExample 1 \fRDisplaying version definitions
252 .sp
253 .LP
254 The following example displays the version definitions of \fBlibelf.so.1\fR:
256 .sp
257 .in +2
258 .nf
259 % \fBpvs -d /lib/libelf.so.1\fR
260 libelf.so.1;
261 SUNW_1.1
262 .fi
263 .in -2
264 .sp
266 .LP
267 \fBExample 2 \fRCreating a one-liner display
268 .sp
269 .LP
270 A normalized, one-liner display, suitable for creating a \fImapfile\fR version
271 control directive, can be created using the \fB-n\fR and \fB-o\fR options:
273 .sp
274 .in +2
275 .nf
276 % \fBpvs -don /lib/libelf.so.1\fR
277 /lib/libelf.so.1 - SUNW_1.1;
278 .fi
279 .in -2
280 .sp
282 .LP
283 \fBExample 3 \fRDisplaying version requirements
284 .sp
285 .LP
286 The following example displays the version requirements of \fBldd\fR and
287 \fBpvs\fR:
289 .sp
290 .in +2
291 .nf
292 % \fBpvs -r /usr/bin/ldd /usr/bin/pvs\fR
293 /usr/bin/ldd:
294 libelf.so.1 (SUNW_1.1);
295 libc.so.1 (SUNW_1.1);
296 /usr/bin/pvs:
297 libelf.so.1 (SUNW_1.1);
298 libc.so.1 (SUNW_1.1);
299 .fi
300 .in -2
301 .sp
303 .LP
304 \fBExample 4 \fRDetermining a dependency symbol version
305 .sp
306 .LP
307 The following example displays the shared object from which the \fBldd\fR
308 command expects to find the printf function at runtime, as well as the version
309 it belongs to:
311 .sp
312 .in +2
313 .nf
314 % \fBpvs -ors /usr/bin/ldd | grep ' printf'\fR
315 /usr/bin/ldd - libc.so.1 (SYSVABI_1.3): printf;
316 .fi
317 .in -2
318 .sp
320 .LP
321 \fBExample 5 \fRDetermine all dependency symbols from a specific version
322 .sp
323 .LP
324 The \fB-N\fR option can be used to obtain a list of all the symbols from a
325 dependency that belong to a specific version. To determine the symbols that
326 \fBldd\fR will find from version \fBSYSVABI_1.3\fR of \fBlibc.so.1\fR:
328 .sp
329 .in +2
330 .nf
331 % \fBpvs -s -N 'libc.so.1 (SYSVABI_1.3)' /usr/bin/ldd\fR
333 libc.so.1 (SYSVABI_1.3):
334 _exit;
335 strstr;
336 printf;
337 __fpstart;
338 strncmp;
339 lseek;
340 strcmp;
341 getopt;
342 execl;
343 close;
344 fflush;
345 wait;
346 strerror;
347 putenv;
348 sprintf;
349 getenv;
350 open;
351 perror;
352 fork;
353 strlen;
354 geteuid;
355 access;
356 setlocale;
357 atexit;
358 fprintf;
359 exit;
360 read;
361 malloc;
362 .fi
363 .in -2
364 .sp
366 .sp
367 .LP
368 Note that the specific list of symbols used by \fBldd\fR may change between
369 Solaris releases.
371 .LP
372 \fBExample 6 \fRDisplay base defined version by index
373 .sp
374 .LP
375 By convention, the base global version defined by an object has the name of the
376 object. For example, the base version of \fBpvs\fR is named \fB\&'pvs'\fR. The
377 base version of any object is always version index 1. Therefore, the \fB-I\fR
378 option can be used to display the base version of any object without having to
379 specify its name:
381 .sp
382 .in +2
383 .nf
384 % \fBpvs -v -I 1 /usr/bin/pvs\fR
385 pvs [BASE];
386 .fi
387 .in -2
388 .sp
390 .SH EXIT STATUS
391 .sp
392 .LP
393 If the requested version information is not found, a non-zero value is
394 returned. Otherwise, a \fB0\fR value is returned.
395 .sp
396 .LP
397 Version information is determined not found when any of the following is true:
398 .RS +4
399 .TP
400 .ie t \(bu
401 .el o
402 the \fB-d\fR option is specified and no version definitions are found.
403 .RE
404 .RS +4
405 .TP
406 .ie t \(bu
407 .el o
408 the \fB-r\fR option is specified and no version requirements are found.
409 .RE
410 .RS +4
411 .TP
412 .ie t \(bu
413 .el o
414 neither the \fB-d\fR nor \fB-r\fR option is specified and no version
415 definitions or version requirements are found.
416 .RE
417 .SH SEE ALSO
418 .sp
419 .LP
420 \fBelfdump\fR(1), \fBld\fR(1), \fBldd\fR(1), \fBstrip\fR(1), \fBelf\fR(3ELF),
421 \fBattributes\fR(5)
422 .sp
423 .LP
424 \fILinker and Libraries Guide\fR