1abicheck(1) General Commands Manual abicheck(1)
2
6 abicheck - check application binaries for calls to private or evolving
7 symbols in libraries and for static linking of some system libraries.
8
10 abicheck [-h] [-k] [-a] [-I] [-v] [-f listfile] [-o outfile] [-p pat‐
11 tern] [-e pattern] [-j njobs] [-l library] [-L ldpath] [(-s|-S) dbfile]
12 [(-d|-D) dbfile] [-O dbfile] [-A listfile] files
13
15 abicheck is run on application binaries and issues warnings whenever
16 any of the following three conditions are detected:
17 · Private symbol usage. Private symbols are functions or data vari‐
19 ables in a library package that are internal to that package. They are
20 used by the libraries in the package for internal communication and are
21 not part of the API/ABI that application developers should use.
22 · Evolving symbol usage. Evolving symbols are functions or data vari‐
24 ables in a library package that are intended for developer consumption,
25 but have been marked as "evolving" or "unstable" in the sense that they
26 may become incompatible or disappear on a later release of the library
27 package.
28 · Static linking. Static linking of system libraries (for example,
30 libc.a) into an application is generally not a good idea because the
31 system library code it "locks" into the application binary may become
32 incompatible with later releases of the system. abicheck attempts to
33 detect static linking of a few system libraries.
34 The default behavior is, for each binary object checked, to examine
36 direct calls from that binary object only. The -l option allows the
37 libraries the binary object brings in to have their calls checked as
38 well.
39
41 The following options are supported:
42 -k Keep on checking binaries even if there are serious errors
44 (dynamic linker reports unresolved symbols, ldd(1) failures, no
45 symbols detected).
46 -h Print out long form of help.
48 -v Verbose. Print out additional information.
50 -f listfile
52 The listfile is a file containing a list of binary objects to
53 check, one per line. This list is appended to any files provided
54 as arguments on the command line. If listfile is "-", then
55 stdin is used.
56 -o outfile
58 Write output to outfile instead of stdout.
59 -p pattern
61 Modify the version name pattern match labelling private version
62 sets. Default is /private/ using a case-insensitive match.
63 If a component of the regex pattern contains two colons in a
65 row: patt1::patt2, then symbol-level matching will be activated
66 by checking whether version::symbol or library::symbol matches
67 pattern (where the symbol name, version (if any), and library
68 basename are substituted for symbol, version, and library). For
69 example,
70 -p 'FOO_VERS.*::_foopriv'
72 or
73 -p 'libfoo.so.*::_foopriv'
74 -e pattern
76 Same as -p but for "evolving" interfaces.
77 -L ldpath
79 Set the LD_LIBRARY_PATH environment variable to ldpath before
80 invoking dynamic linker. Use -L "" to unset LD_LIBRARY_PATH.
81 If one of the components of ldpath is the string "find", then
83 all shared libraries in files are found and their paths inserted
84 into the "find" location. Note that the order will random.
85 -l library
87 Add the basename or full pathname of the shared library library
88 to the list of objects to be checked for making private calls.
89 This option may occur more than once on the command line and is
90 additive. By default, only direct calls from a binary to the
91 system libraries are checked. The -l switch allows checking of
92 indirect calls e.g.: app -> supportlib -> systemlib.
93 -a Loop through all of the binaries before checking and collect the
95 list of all shared objects. Take the basename of each shared
96 object found and act as though it was specified with the -l
97 option option and then run the abicheck checks. This way, calls
98 from all "application internal" objects are checked rather than
99 just the direct calls. (Useful when shared objects do not have
100 their dependencies recorded.)
101 -I Ignore shared libraries in checking, only check executables.
103 Compatible with -a, libraries will be searched for first but
104 then not checked.
105 -d dbfile, -D dbfile
107 Specify fallback flat-file symbol database for the dynamic (pub‐
108 lic vs. private) test. These classifications will be used if
109 the library is not versioned (i.e. classification does not exist
110 in the library itself). Use -D to indicate that only informa‐
111 tion from dbfile should be used. Lines in dbfile can be of one
112 of these forms:
113 library|symbol
115 library|class|symbol
116 library|FILE=path
117 library must be the full path to the library to be specified (it
119 cannot be a basename).
120 The first form marks symbol as private.
122 The second form marks symbol with class where class may be pub‐
124 lic, private, or evolving.
125 The third form indicates the file path should be opened on
127 demand when library is first encountered. File path contains
128 lines of the first two forms except for the library field. The
129 third form is a speedup to avoid processing many classification
130 lines for libraries never encountered in the run.
131 -O dbfile
133 Specify an override file to modify the symbol classification for
134 the dynamic (public vs. private) test. The format for the over‐
135 ride file is like:
136 library|symbol|class
138 The library can be the full path or basename. If library is
140 "__SKIP__" the symbol will be ignored for any library it is
141 found in. The class can be "public", "private", "evolving", or
142 "deleted". The "deleted" class is special-cased, means the sym‐
143 bol was deleted from the library on some release. The symbol
144 "__ALL__" for the "deleted" class means the entire library was
145 deleted or is otherwise unstable to use.
146 Examples:
148 libfoo.so.1|__bar|private
150 /lib/libxyz.so.1|baz|public
151 __SKIP__|__fputwc_xpg5
152 These settings override any classification inside the library
154 (from library versioning, obtainable from pvs(1), etc).
155 -A listfile
157 Set the ABI libraries of interest to the libraries listed in
158 listfile (full pathnames, one per line). Only calls into these
159 libraries will be checked; all other library calls will be
160 ignored.
161 -s dbfile, -S dbfile
163 Specify more extensive symbol databases for the static linking
164 test. dbfile may be a comma separated list of files. If a file
165 is a static archive (lib*.a) it is processed to extract the sym‐
166 bols. Otherwise it is a database file consisting of lines of
167 the form symbol|library:module for example:
168 shmat|/usr/lib/libc.a:shmsys.o
170 shmctl|/usr/lib/libc.a:shmsys.o
171 shmdt|/usr/lib/libc.a:shmsys.o
172 shmget|/usr/lib/libc.a:shmsys.o
173 ...
174 When all symbols in a module.o are defined in the application,
176 static linking of that module (and corresponding library ar‐
177 chive) is assumed. Use -S to indicate that only the static link
178 test should be performed.
179 Use -S int to do only the static link check and using the
181 internal database.
182 Use -s none or -S none to skip the static linking check
184 entirely.
185 -j njobs
187 Run njobs in parallel as separate processes. Implies -k. Pri‐
188 marily intended for multiple CPU machines where njobs should be
189 close to the number of processors. Output is collected in tmp
190 files and printed all at once near the end of the run as each
191 job finishes.
192 If njobs is "-", "detect", or "n", then njobs will be set to a
194 number depending on the number of processors on the current
195 machine (if that can be determined).
196
198 The following operands are supported:
199 files A list of application binary objects to check.
201
203 There is one line per problem (there may be multiple problems per
204 binary checked) which look like the following:
205 If no problems were found:
207 filename: OK
208 If private symbol usage:
210 filename: PRIVATE (library:private_version) private_sym
211 If evolving symbol usage:
213 filename: EVOLVING (library:evolving_vers) evolving_sym
214 If file statically linked in a system archive library:
216 filename: STATIC_LINK (archive)
217 If checking of the file was skipped:
219 filename: SKIP (reason)
220 Under use of the deleted class in the -O override file option, these
223 problems may be found:
224 If a symbol has been deleted from the library on some release:
226 filename: DELETED_SYM: symbol/library
227 (library will be "unbound" if the symbol was unbound)
229 If an entire library has been deleted on some release or is oth‐
231 erwise unstable to use:
232 filename: UNSTABLE_LIB: library-soname = library-path
233 (library-path may be "file not found" if the library could not
235 be found)
236 The following problems will cause a fatal error unless the -k option is
239 used:
240 If the dynamic linker could not resolve N symbols when ldd -r
242 was run:
243 filename: UNBOUND_SYMBOLS: N
244 If the dynamic linker found no dynamic bindings:
246 filename: NO_BINDINGS
247 If ldd -r with LD_DEBUG=files,bindings failed:
249 filename: LDD_ERROR
250 In these latter three cases run ldd -r on the binary file for more
252 information on what went wrong (note that abicheck runs ldd -r with
253 LD_DEBUG=files,bindings set). On some systems the dynamic linker will
254 not process SUID programs with LD_DEBUG set (this usually results in
255 NO_BINDINGS in the abicheck output).
256 Note that if you are running abicheck on a shared library (for example,
258 libfoo.so) that has not been built with -l lib flags to record its
259 library dependencies, then the "unbound symbols" problem is very
260 likely. There is not much that can be done besides rebuilding the
261 library or checking an application binary that uses the library and
262 using the -l option of abicheck.
263
265 The following exit values are returned:
266 0 No errors and no problems found.
268 1 A fatal error occurred.
270 2 No fatal errors occurred, but some binaries had problems
272 detected.
273
275 Only ELF objects are checked.
276 In the -s -S -d and -O dbfiles the '#' character starts a comment line
278 in the usual way.
279 Unless one is using the "::" custom matches supplied via the -p or -e
281 flags, abicheck can only check against system libraries that have had
282 symbol versioning applied to them (i.e. the private and/or evolving
283 information recorded for each symbol in the library itself). For more
284 info about symbol versioning, see the "Solaris Linker and Libraries
285 Guide" answerbook at the URL http://docs.sun.com/ab2/coll.45.13 and the
286 Commands/Version-Script section of the GNU linker "ld" info page.
287 The default symbol version name matching patterns are case insensitive
289 matches to the strings "private" and "evolving" for the private and
290 evolving cases, respectively.
291 Odd filenames containing the single-quote character or newline will be
293 skipped; such characters interfere with calling commands via the shell.
294 To recurse directories use find(1) and either collect the output to a
296 file for use with the -f option, or in a pipe in via:
297 find ... | abicheck -f - ...
299
301 The program is dependent on the form of the runtime linker's debug out‐
302 put. Since this output is intended to be human readable rather than
303 machine readable, abicheck will break whenever the output format
304 changes. On Solaris it is possible that the Link Auditing C interface
305 could be used to avoid this problem.
306 On Linux when ldd(1) is run on a SUID binary, it (ldd and the dynamic-
308 linker) will sometimes actually run the binary. On Linux SUID/SGID
309 binaries are currently skipped even if the user is root; test unprivi‐
310 leged copies instead.
311
313 ld(1), ldd(1),
314 26 August 2003 abicheck(1)