Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
LLVM-IFS(1)			      LLVM			     LLVM-IFS(1)

NAME
     llvm-ifs - shared object stubbing tool

SYNOPSIS
     llvm-ifs [options] inputs

DESCRIPTION
     llvm-ifs  is  a  tool that jointly produces human readable text-based stubs
     (.ifs files) for shared objects  and  linkable  shared  object  stubs  (.so
     files)  from  either ELF shared objects or text-based stubs. The text-based
     stubs is useful for monitoring ABI changes of the shared object. The  link-
     able  shared object stubs can be used to avoid unnecessary relinks when the
     ABI of shared libraries does not change.

IFS FORMATS
     Here is an example of the text representation (IFS) of a shared object pro-
     duced by the llvm-ifs:

	--- !ifs-v1
	IFSVersion: 3.0
	SoName: libtest.so /* Optional */
	Target: x86_64-unknown-linux-gnu   /* Optional, format 1, same format as llvm target triple */
	Target: { Arch: x86_64, Endianness: little, Bitwidth: 64 } /* Optional, format 2 */
	NeededLibs:
	  - libc.so.6
	Symbols:
	  - { Name: sym0, Type: Notype }
	  - { Name: sym1, Type: Object, Size: 0 }
	  - { Name: sym2, Type: Func, Weak: false }
	  - { Name: sym3, Type: TLS }
	  - { Name: sym4, Type: Unknown, Warning: foo }
	...

     * IFSVersion: Version of the IFS file for reader compatibility.

     * SoName (optional): Name of the shared object file that is being stubbed.

     * Target (optional): The architecture, endianness and  bitwise  information
       of this shared object. It can be either in explicit format or in implicit
       LLVM triple format. It can be optional and can be overridden from command
       line options.

     * NeededLibs: The list of the external shared objects that this library de-
       pends on.

     * Symbols: A collection of all data needed to link objects for each symbol,
       sorted by name in ascending order.

       * Name: Symbol name.

       * Type:	Whether the symbol is an object, function, no-type, thread local
	 storage, or unknown. Symbol types not explicitly supported  are  mapped
	 as unknown to improve signal-to-noise ratio.

       * Size:	The  size of the symbol in question, doesn't apply to functions,
	 and is optional for NoType symbols.

       * Undefined: Whether or not the symbol is defined in this  shared  object
	 file.

       * Weak: Whether or not the symbol should be treated as weak.

       * Warning  (optional):  Warning text to output when this symbol is linked
	 against.

     This YAML based text format contains everything that is needed to	generate
     a	linkable ELF shared object as well as an Apple TAPI format file. The or-
     dering of symbols is sorted, so these files can be  easily  compared  using
     diff tools.  If the content of the file changes, it indicates a potentially
     ABI breaking change.

ELF STUB FORMAT
     A	minimum  ELF  file that can be used by linker should have following sec-
     tions properly populated:

     * ELF header.

     * Section headers.

     * Dynamic symbol table (.dynsym section).

     * Dynamic string table (.dynstr section).

     * Dynamic table (.dynamic section).

       * DT_SYMTAB entry.

       * DT_STRTAB entry.

       * DT_STRSZ entry.

       * DT_NEEDED entries. (optional)

       * DT_SONAME entry. (optional)

     * Section header string table (.shstrtab section)

     This ELF file may have compatibility issues with ELF  analysis  tools  that
     rely  on the program headers.  Linkers like LLD work fine with such a mini-
     mum ELF file without errors.

OPTIONS
     --input-format=[IFS|ELF|OtherObjectFileFormats]
	    Specify input file format. Currently, only text IFS  files	and  ELF
	    shared  object files are supported. This flag is optional as the in-
	    put format can be inferred.

     --output-elf=<output-filename>
	    Specify the output file for ELF shared object stub.

     --output-ifs=<output-filename>
	    Specify the output file for text IFS.

     --output-tbd=<output-filename>
	    Specify the output file for Apple TAPI tbd.

     --arch=[x86_64|AArch64|...]
	    This flag is optional and it should only be used when reading an IFS
	    file which does not define the Arch (architecture).  This  flag  de-
	    fines  the	architecture  of  the output file, and can be any string
	    supported by ELF 'e_machine' field. If the value is conflicting with
	    the IFS file, an error will be reported and the program will stop.

     --endianness=[little|big]
	    This flag is optional and it should only be used when reading an IFS
	    file which does not define the Endianness. This flag defines the en-
	    dianness of the output file. If the value is  conflicting  with  the
	    IFS file, an error will be reported and the program will stop.

     --bitwidth=[32|64]
	    This flag is optional and it should only be used when reading an IFS
	    file  which  does not define the BitWidth. This flag defines the bit
	    width of the output file. If the value is conflicting with the input
	    IFS file, an error will be reported and the program will stop.

     --target=<target triple>
	    This flag is optional and should only be used when	reading  an  IFS
	    file which does not define any target information. This flag defines
	    architecture, endianness and bit width of the output file using llvm
	    target  triple.   This flag cannot be used simultaneously with other
	    target related flags.

     --hint-ifs-target=<target triple>
	    This flag is optional and should only be used when	reading  an  ELF
	    shared  object and generating an IFS file. by default, llvm-ifs will
	    use 'Arch, Endianness and BitWidth' fields to reflect the target in-
	    formation from the input object file.  Using  this	flag  will  tell
	    llvm-ifs  the  expected target triple in the output IFS file. If the
	    value matches the target information  from	the  object  file,  this
	    value  will  be used in the 'Target:' filed in the generated IFS. If
	    it conflicts with the input object file, an error will  be	reported
	    and the program will stop.

     --hint-ifs-target
	    This flag is optional and should only be used when outputting an IFS
	    file.   This  flag strips the Arch field from the IFS file so it can
	    be overridden later.

     --strip-ifs-endianness
	    This flag is optional and should only be used when outputting an IFS
	    file.  This flag strips the Endianness field from the IFS file so it
	    can be overridden later.

     --strip-ifs-bitwidth
	    This flag is optional and should only be used when outputting an IFS
	    file.  This flag strips the BitWidth field from the IFS file  so  it
	    can be overridden later.

     --strip-ifs-target
	    This flag is optional and should only be used when outputting an IFS
	    file.  This flag strips the Target field from the IFS file so it can
	    be overridden later.

     --write-if-changed
	    When  this	flag is set, llvm-ifs will only write the output file if
	    it does not already exist or the content will be different from  the
	    existing file.

     --strip-size
	    When  this flag is set, llvm-ifs will remove the size field from the
	    output ifs file. This is useful for shared objects that only  intend
	    to	be  linked  against position independent code which doesn't need
	    copy relocations, or where the size of an object  is  not  a  useful
	    part of the abi to track.

EXIT STATUS
     If  llvm-ifs  succeeds, it will exit with 0. Otherwise, if an error occurs,
     it will exit with a non-zero value.

AUTHOR
     Maintained by the LLVM Team (https://llvm.org/).

COPYRIGHT
     2003-2026, LLVM Project

19				   2026-07-30			     LLVM-IFS(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=llvm-ifs&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>

home | help