1LLVM-IFS(1) LLVM LLVM-IFS(1)
2
6 llvm-ifs - shared object stubbing tool
7
9 llvm-ifs [options] inputs
10
12 llvm-ifs is a tool that jointly produces human readable text-based
13 stubs (.ifs files) for shared objects and linkable shared object stubs
14 (.so files) from either ELF shared objects or text-based stubs. The
15 text-based stubs is useful for monitoring ABI changes of the shared ob‐
16 ject. The linkable shared object stubs can be used to avoid unnecessary
17 relinks when the ABI of shared libraries does not change.
18
20 Here is an example of the text representation (IFS) of a shared object
21 produced by the llvm-ifs:
22 --- !ifs-v1
24 IFSVersion: 3.0
25 SoName: libtest.so /* Optional */
26 Target: x86_64-unknown-linux-gnu /* Optional, format 1, same format as llvm target triple */
27 Target: { Arch: x86_64, Endianness: little, Bitwidth: 64 } /* Optional, format 2 */
28 NeededLibs:
29 - libc.so.6
30 Symbols:
31 - { Name: sym0, Type: Notype }
32 - { Name: sym1, Type: Object, Size: 0 }
33 - { Name: sym2, Type: Func, Weak: false }
34 - { Name: sym3, Type: TLS }
35 - { Name: sym4, Type: Unknown, Warning: foo }
36 ...
37 • IFSVersion: Version of the IFS file for reader compatibility.
39 • SoName (optional): Name of the shared object file that is being
41 stubbed.
42 • Target (optional): The architecture, endianness and bitwise informa‐
44 tion of this shared object. It can be either in explicit format or in
45 implicit LLVM triple format. It can be optional and can be overridden
46 from command line options.
47 • NeededLibs: The list of the external shared objects that this library
49 depends on.
50 • Symbols: A collection of all data needed to link objects for each
52 symbol, sorted by name in ascending order.
53 • Name: Symbol name.
55 • Type: Whether the symbol is an object, function, no-type, thread
57 local storage, or unknown. Symbol types not explicitly supported
58 are mapped as unknown to improve signal-to-noise ratio.
59 • Size: The size of the symbol in question, doesn't apply to func‐
61 tions, and is optional for NoType symbols.
62 • Undefined: Whether or not the symbol is defined in this shared ob‐
64 ject file.
65 • Weak: Whether or not the symbol should be treated as weak.
67 • Warning (optional): Warning text to output when this symbol is
69 linked against.
70 This YAML based text format contains everything that is needed to gen‐
72 erate a linkable ELF shared object as well as an Apple TAPI format
73 file. The ordering of symbols is sorted, so these files can be easily
74 compared using diff tools. If the content of the file changes, it in‐
75 dicates a potentially ABI breaking change.
76
78 A minimum ELF file that can be used by linker should have following
79 sections properly populated:
80 • ELF header.
82 • Section headers.
84 • Dynamic symbol table (.dynsym section).
86 • Dynamic string table (.dynstr section).
88 • Dynamic table (.dynamic section).
90 • DT_SYMTAB entry.
92 • DT_STRTAB entry.
94 • DT_STRSZ entry.
96 • DT_NEEDED entries. (optional)
98 • DT_SONAME entry. (optional)
100 • Section header string table (.shstrtab section)
102 This ELF file may have compatibility issues with ELF analysis tools
104 that rely on the program headers. Linkers like LLD work fine with such
105 a minimum ELF file without errors.
106
108 --input-format=[IFS|ELF|OtherObjectFileFormats]
109 Specify input file format. Currently, only text IFS files and
110 ELF shared object files are supported. This flag is optional as
111 the input format can be inferred.
112 --output-elf=<output-filename>
114 Specify the output file for ELF shared object stub.
115 --output-ifs=<output-filename>
117 Specify the output file for text IFS.
118 --output-tbd=<output-filename>
120 Specify the output file for Apple TAPI tbd.
121 --arch=[x86_64|AArch64|...]
123 This flag is optional and it should only be used when reading an
124 IFS file which does not define the Arch (architecture). This
125 flag defines the architecture of the output file, and can be any
126 string supported by ELF 'e_machine' field. If the value is con‐
127 flicting with the IFS file, an error will be reported and the
128 program will stop.
129 --endianness=[little|big]
131 This flag is optional and it should only be used when reading an
132 IFS file which does not define the Endianness. This flag defines
133 the endianness of the output file. If the value is conflicting
134 with the IFS file, an error will be reported and the program
135 will stop.
136 --bitwidth=[32|64]
138 This flag is optional and it should only be used when reading an
139 IFS file which does not define the BitWidth. This flag defines
140 the bit width of the output file. If the value is conflicting
141 with the input IFS file, an error will be reported and the pro‐
142 gram will stop.
143 --target=<target triple>
145 This flag is optional and should only be used when reading an
146 IFS file which does not define any target information. This flag
147 defines architecture, endianness and bit width of the output
148 file using llvm target triple. This flag cannot be used simul‐
149 taneously with other target related flags.
150 --hint-ifs-target=<target triple>
152 This flag is optional and should only be used when reading an
153 ELF shared object and generating an IFS file. by default,
154 llvm-ifs will use 'Arch, Endianness and BitWidth' fields to re‐
155 flect the target information from the input object file. Using
156 this flag will tell llvm-ifs the expected target triple in the
157 output IFS file. If the value matches the target information
158 from the object file, this value will be used in the 'Target:'
159 filed in the generated IFS. If it conflicts with the input ob‐
160 ject file, an error will be reported and the program will stop.
161 --hint-ifs-target
163 This flag is optional and should only be used when outputting an
164 IFS file. This flag strips the Arch field from the IFS file so
165 it can be overridden later.
166 --strip-ifs-endianness
168 This flag is optional and should only be used when outputting an
169 IFS file. This flag strips the Endianness field from the IFS
170 file so it can be overridden later.
171 --strip-ifs-bitwidth
173 This flag is optional and should only be used when outputting an
174 IFS file. This flag strips the BitWidth field from the IFS file
175 so it can be overridden later.
176 --strip-ifs-target
178 This flag is optional and should only be used when outputting an
179 IFS file. This flag strips the Target field from the IFS file
180 so it can be overridden later.
181 --write-if-changed
183 When this flag is set, llvm-ifs will only write the output file
184 if it does not already exist or the content will be different
185 from the existing file.
186 --strip-size
188 When this flag is set, llvm-ifs will remove the size field from
189 the output ifs file. This is useful for shared objects that only
190 intend to be linked against position independent code which
191 doesn't need copy relocations, or where the size of an object is
192 not a useful part of the abi to track.
193
195 If llvm-ifs succeeds, it will exit with 0. Otherwise, if an error oc‐
196 curs, it will exit with a non-zero value.
197
199 Maintained by the LLVM Team (https://llvm.org/).
200
202 2003-2023, LLVM Project
20317 2023-11-28 LLVM-IFS(1)