1LLVM-IFS(1)                          LLVM                          LLVM-IFS(1)
2
3
4

NAME

6       llvm-ifs - shared object stubbing tool
7

SYNOPSIS

9       llvm-ifs [options] inputs
10

DESCRIPTION

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

IFS FORMATS

20       Here is an example of the text representation (IFS) of a shared  object
21       produced by the llvm-ifs:
22
23          --- !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
38IFSVersion: Version of the IFS file for reader compatibility.
39
40SoName  (optional):  Name  of  the  shared  object file that is being
41         stubbed.
42
43Target (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
48NeededLibs: The list of the external shared objects that this library
49         depends on.
50
51Symbols: A collection of all data needed to  link  objects  for  each
52         symbol, sorted by name in ascending order.
53
54Name: Symbol name.
55
56Type:  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
60Size:  The  size  of the symbol in question, doesn't apply to func‐
61           tions, and is optional for NoType symbols.
62
63Undefined: Whether or not the symbol is defined in this shared  ob‐
64           ject file.
65
66Weak: Whether or not the symbol should be treated as weak.
67
68Warning  (optional):  Warning  text  to  output when this symbol is
69           linked against.
70
71       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

ELF STUB FORMAT

78       A minimum ELF file that can be used by  linker  should  have  following
79       sections properly populated:
80
81       • ELF header.
82
83       • Section headers.
84
85       • Dynamic symbol table (.dynsym section).
86
87       • Dynamic string table (.dynstr section).
88
89       • Dynamic table (.dynamic section).
90
91DT_SYMTAB entry.
92
93DT_STRTAB entry.
94
95DT_STRSZ entry.
96
97DT_NEEDED entries. (optional)
98
99DT_SONAME entry. (optional)
100
101       • Section header string table (.shstrtab section)
102
103       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

OPTIONS

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
113       --output-elf=<output-filename>
114              Specify the output file for ELF shared object stub.
115
116       --output-ifs=<output-filename>
117              Specify the output file for text IFS.
118
119       --output-tbd=<output-filename>
120              Specify the output file for Apple TAPI tbd.
121
122       --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
130       --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
137       --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
144       --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
151       --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
162       --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
167       --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
172       --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
177       --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
182       --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
187       --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

EXIT STATUS

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

AUTHOR

199       Maintained by the LLVM Team (https://llvm.org/).
200
202       2003-2023, LLVM Project
203
204
205
206
20715                                2023-07-20                       LLVM-IFS(1)
Impressum