lari man page on OpenIndiana

Man page or keyword search:  
man Server   20441 pages
apropos Keyword Search (all sections)
Output format
OpenIndiana logo
[printable version]

lari(1)				 User Commands			       lari(1)

NAME
       lari - link analysis of runtime interfaces

SYNOPSIS
       lari [-bCDsVv] [-a | -i | -o] file | directory...

       lari [-CDosv] [-m [-d mapdir]] file

DESCRIPTION
       The  lari  utility  analyzes  the interface requirements of dynamic ELF
       objects. Two basic modes of operation are  available.  The  first  mode
       displays	 runtime  interface  information.  The	second	mode generates
       interface definitions.

       Dynamic objects offer symbolic definitions that represent the interface
       that  the  object provides for external consumers. At runtime, bindings
       are established from the symbolic references of one object to the  sym‐
       bolic  definitions  of another object. lari analyzes both the interface
       definitions and runtime bindings of the specified objects.

       When displaying runtime interface information, lari can analyze a  num‐
       ber of files and/or directories. lari analyzes each file that is speci‐
       fied on the command line. lari recursively descends into each directory
       that  is	 specified  on	the command line, processing each file that is
       found.

       When generating interface definitions, lari can only process  a	single
       file specified on the command line.

       Without	the  -D option, lari processes files as dynamic ELF objects by
       using ldd(1). This processing uses the following options:

	 -r and -e LD_DEBUG=files,bindings,detail

       These options provide information on all bindings that are  established
       as  part of loading the object. Notice that by using ldd, the specified
       object is not  executed,	 and  hence  no	 user  controlled  loading  of
       objects,	 by  dlopen(3C)	 for  example,	occurs. To capture all binding
       information from an executing process, the following environment	 vari‐
       ables can be passed directly to the runtime linker, ld.so.1(1):

	 LD_DEBUG=files,bindings,detail LD_DEBUG_OUTPUT=lari.dbg
	 LD_BIND_NOW=yes

       The  resulting  debug  output,  lari.dbg.pid,  can be processed by lari
       using the -D option. Note: lari attempts to analyze  each  object  that
       has  been  processed  using  the path name defined in the debug output.
       Each object must therefore be accessible to lari for a complete,	 accu‐
       rate  analysis  to be provided. The debug output file must be generated
       in the C locale.

       When displaying interface information, lari analyzes the interfaces  of
       the processed dynamic objects and, by default, displays any interesting
       information. See Interesting Information	 under	EXTENDED  DESCRIPTION.
       The  information that is displayed is also suitable for piping to other
       tools. This capability can aid developers in analyzing process bindings
       or debugging complex binding scenarios.

       The  generation	of interface definitions by lari can be used to refine
       the interface requirements of the dynamic objects that  are  processed.
       When  creating  a  dynamic  object, you should define an explicit, ver‐
       sioned interface. This definition controls the symbol definitions  that
       are  available  to  external  users.  In addition, this definition fre‐
       quently reduces the overall  runtime  execution	cost  of  the  object.
       Interface  definitions can be assigned to an object during its creation
       by the link-editor using the  -M	 option	 and  the  associated  mapfile
       directives.  See	 the  Linker  and  Libraries Guide for more details on
       using mapfiles to version objects. An initial version of these mapfiles
       can be created by lari.

OPTIONS
       The following options are supported.

       -a	    Displays  all  interface  information for the objects ana‐
		    lyzed. Note: The output from this option can  be  substan‐
		    tial,  but	is  often  useful for piping to other analysis
		    tools.

       -b	    Limits the interface information  to  those	 symbols  that
		    have  been	explicitly  bound to. Note: Symbols defined as
		    protected might have been bound to from within the	defin‐
		    ing	 object.  This	binding is satisfied at link-edit time
		    and is therefore not visible to the	 runtime  environment.
		    Protected symbols are displayed with this option.

       -C	    Demangles C++ symbol names. This option is useful for aug‐
		    menting runtime  interface	information.  When  generating
		    interface  definitions,  demangled	names are added to the
		    mapfiles as comments.

       -d mapdir    Defines the directory, mapdir, in which mapfiles are  cre‐
		    ated. By default, the current working directory is used.

       -D	    Interprets any input files as debugging information rather
		    than as dynamic objects.

       -i	    Displays interesting interface binding  information.  This
		    mode  is the default if no other output controlling option
		    is supplied. See Interesting  Information  under  EXTENDED
		    DESCRIPTION.

       -m	    Creates  mapfiles  for  each  dynamic  object that is pro‐
		    cessed. These mapfiles reflect the interface  requirements
		    of	each  object  as required by the input file being pro‐
		    cessed.

       -o	    Limits the interface information to those symbols that are
		    deemed  an	overhead. When creating mapfiles, any overhead
		    symbols are itemized as local symbols. See Overhead Infor‐
		    mation under EXTENDED DESCRIPTION.

       -s	    Saves  the	bindings  information produced from ldd(1) for
		    further analysis. See FILES.

       -V	    Appends interesting symbol visibilities. Symbols that  are
		    defined  as singleton or are defined protected are identi‐
		    fied with this option.

       -v	    Ignores any objects that are already versioned.  Versioned
		    objects  have  had	their interfaces defined, but can con‐
		    tribute to the interface information displayed. For	 exam‐
		    ple,  a versioned shared object might reveal overhead sym‐
		    bols for a particular process.  Shared  objects  are  fre‐
		    quently  designed  for use by multiple processes, and thus
		    the interfaces these objects provide can extend beyond the
		    requirements  of any one process. The -v option therefore,
		    can reduce noise when displaying interface information.

       The runtime interface information produced from lari has the  following
       format:

	 [information]: symbol-name [demangled-name]: object-name

       Each  line  describes  the interface symbol, symbol-name, together with
       the object, object-name, in which the symbol is defined. If the	symbol
       represents a function, the symbol name is followed by (). If the symbol
       represents a data object, the symbol name is followed  by  the  symbols
       size,  enclosed within []. If the -C option is used, the symbol name is
       accompanied by the symbols demangled name, demangled-name. The informa‐
       tion  field  provides one or more of the following tokens that describe
       the symbol's use:

       cnt:bnd	  Two decimal values indicate the symbol count, cnt,  and  the
		  number  of bindings to this object, bnd. The symbol count is
		  the number of occurrences of	this  symbol  definition  that
		  have	been  found  in the objects that are analyzed. A count
		  that is greater than 1 indicates  multiple  instances	 of  a
		  symbol  definition. The number of bindings indicate the num‐
		  ber of objects that have been bound to this  symbol  defini‐
		  tion by the runtime linker.

       E	  This	symbol	definition  has been bound to from an external
		  object.

       S	  This symbol definition has  been  bound  to  from  the  same
		  object.

       D	  This symbol definition has been directly bound to.

       I	  This	symbol	definition  provides  for  an  interposer.  An
		  object that explicitly identifies itself  as	an  interposor
		  defines all global symbols as interposers. See the -z inter‐
		  pose	option	of  ld(1),  and	 the  LD_PRELOAD  variable  of
		  ld.so.1(1).  Individual  symbols within a dynamic executable
		  can be defined as interposers by using the INTERPOSE mapfile
		  directive.

       C	  This symbol definition is the reference data of a copy-relo‐
		  cation.

       F	  This symbol definition resides in a filtee.

       P	  This symbol is defined as protected. This symbol might  have
		  an  internal	binding from the object in which the symbol is
		  declared. Any internal bindings with this attribute can  not
		  be interposed upon by another symbol definition.

       A	  This symbol definition is the address of a procedure linkage
		  table entry within a dynamic executable.

       U	  This symbol lookup originated from a user request, for exam‐
		  ple, dlsym(3C).

       R	  This	symbol	definition is acting as a filter, and provides
		  for redirection to a filtee.

       r	  A binding to this symbol was rejected at some point during a
		  symbol  search.  A rejection can occur when a direct binding
		  request finds a symbol  that	has  been  tagged  to  prevent
		  direct  binding.  In	this  scenario,	 the  symbol search is
		  repeated using a default search model. The binding can still
		  resolve  to  the  original, rejected symbol. A rejection can
		  also occur when a non-default symbol search finds  a	symbol
		  identified  as  a  singleton.	 Again,	 the  symbol search is
		  repeated using a default search model.

       N	  This symbol definition explicitly prohibits directly binding
		  to the definition.

       See  the	 Linker	 and  Libraries Guide for more details of these symbol
       classifications.

EXTENDED DESCRIPTION
   Interesting Information
       By default, or specifically using the -i option, lari filters any  run‐
       time  interface information to present interesting events. This filter‐
       ing is carried out mainly to reduce the amount of information that  can
       be  generated from large applications. In addition, this information is
       intended to be the focus in debugging complex  binding  scenarios,  and
       often  highlights  problem areas. However, classifying what information
       is interesting for any particular application is	 an  inexact  science.
       You  are	 still	free  to  use  the -a option and to search the binding
       information for events that are unique to the application being	inves‐
       tigated.

       When  an interesting symbol definition is discovered, all other defini‐
       tions of the same symbol are output.

       The focus of interesting interface information is the existence of mul‐
       tiple  definitions  of  a  symbol.  In  this case, one symbol typically
       interposes on one or more other symbol definitions. This	 interposition
       is  seen	 when  the  binding count, bnd, of one definition is non-zero,
       while the binding count of all other definitions is zero. Interposition
       that  results from the compilation environment, or the linking environ‐
       ment, is not characterized as interesting. Examples of these interposi‐
       tion occurrences include copy relocations ([C]) and the binding to pro‐
       cedure linkage addresses ([A]).

       Interposition is	 often	desirable.  The	 intent	 is  to	 overload,  or
       replace, the symbolic definition from a shared object. Interpositioning
       objects can be explicitly tagged ([I]), using the -z  interpose	option
       of ld(1). These objects can safely interpose on symbols, no matter what
       order the objects are loaded in a process. However,  be	cautious  when
       non-explicit interposition is employed, as this interposition is a con‐
       sequence of the load-order of the objects that make up the process.

       User-created, multiply-defined symbols are output from lari  as	inter‐
       esting.	In  this  example,  two definitions of interpose1() exist, but
       only the definition in main is referenced:

	 [2:1E]: interpose1(): ./main
	 [2:0]: interpose1(): ./libA.so

       Interposition can also be an undesirable and surprising	event,	caused
       by  an  unexpected  symbol  name clash. A symptom of this interposition
       might be that a function is never called although you know a  reference
       to  the	function exists. This scenario can be identified as a multiply
       defined symbol, as covered in the previous  example.  However,  a  more
       surprising  scenario  is	 often encountered when an object both defines
       and references a specific symbol.

       An example of this scenario is if two dynamic objects define and refer‐
       ence  the  same	function,  interpose2().  Any reference to this symbol
       binds to the first dynamic object loaded	 with  the  process.  In  this
       case,  the  definition of interpose2() in object libA.so interposes on,
       and hides, the definition of interpose2() in object libB.so. The output
       from lari might be:

	 [2:2ES]: interpose2(): ./libA.so
	 [2:0]: interpose2(): ./libB.so

       Multiply	 defined  symbols  can	also  be bound to separately. Separate
       bindings can be the case when direct bindings are in effect  ([D]),  or
       because	a  symbol  has	protected  visibility ([P]). Although separate
       bindings can be explicitly established, instances can  exist  that  are
       unexpected  and	surprising.  Directly  bound symbols, and symbols with
       protected visibility, are output as interesting information.

   Overhead Information
       When using the -o option, lari displays symbol definitions  that	 might
       be considered overhead.

       Global  symbols that are not referenced are considered an overhead. The
       symbol information that is provided  within  the	 object	 unnecessarily
       adds  to the size of the object's text segment. In addition, the symbol
       information can increase the processing required to  search  for	 other
       symbolic references within the object at runtime.

       Global  symbols	that are only referenced from the same object have the
       same characteristics. The runtime search for a symbolic reference, that
       results	in  binding  to the same object that made the reference, is an
       additional overhead.

       Both of these symbol definitions are candidates for reduction to	 local
       scope  by defining the object's interface. Interface definitions can be
       assigned to a file during its creation by the link-editor using the  -M
       option  and  the	 associated  mapfile  directives.  See	the Linker and
       Libraries Guide for more details on mapfiles.  Use  lari	 with  the  -m
       option to create initial versions of these mapfiles.

       If  lari	 is  used  to generate mapfiles, versioned shared objects will
       have mapfiles created indicating that their overhead symbols should  be
       reduced to locals. This model allows lari to generate mapfiles for com‐
       parison with existing interface	definitions.  Use  the	-v  option  to
       ignore versioned shared objects when creating mapfiles.

       Copy-relocations are also viewed as an overhead and generally should be
       avoided. The size of the copied data is a definition of its  interface.
       This  definition restricts the ability to change the data size in newer
       versions of the shared object  in  which	 the  data  is	defined.  This
       restriction,  plus  the	cost  of  processing a copy relocation, can be
       avoided by referencing data using a functional  interface.  The	output
       from lari for a copy relocation might be:

	 [2:1EC]: __iob[0x140]: ./main
	 [2:0]: __iob[0x140]: ./libA.so.1

       Notice  that  a number of small copy relocations, such as __iob used in
       the previous example, exist because of  historic	 programming  interac‐
       tions with system libraries.

       Another	example	 of  overhead  information is the binding of a dynamic
       object to the procedure linkage table entry of a dynamic executable. If
       a dynamic executable references an external function, a procedure link‐
       age table entry is created. This structure allows the reference binding
       to  be  deferred until the function call is actually made. If a dynamic
       object takes the address of the same referenced function,  the  dynamic
       object  binds to the dynamic executables procedure linkage table entry.
       An example of this type of event reveals the following:

	 [2:1EA]: foo(): ./main
	 [2:1E]: foo(): ./libA.so

       A small number of bindings of this type are  typically  not  cause  for
       concern.	 However,  a  large  number  of these bindings, perhaps from a
       jump-table programming technique, can contribute to start up  overhead.
       Address	relocation bindings of this type require relocation processing
       at application start up, rather than the deferred relocation processing
       used when calling functions directly. Use of this address also requires
       an indirection at runtime.

EXAMPLES
       Example 1 Analyzing a case of multiple bindings

       The following example shows the analysis of a process in which multiple
       symbol  definitions  exist. The shared objects libX.so and libY.so both
       call the function interpose(). This function exists in both the	appli‐
       cation  main,  and the shared object libA.so. Because of interposition,
       both references bind to the definition of interpose() in main.

       The shared objects libX.so and libY.so  also  both  call	 the  function
       foo().  This  function  exists  in the application main, and the shared
       objects libA.so, libX.so, and libY.so. Because both libX.so and libY.so
       were  built  with direct bindings enabled, each object binds to its own
       definition.

	 example% lari ./main
	 [3:0]: foo(): ./libA.so
	 [3:1SD]: foo(): ./libX.so
	 [3:1SD]: foo(): ./libY.so
	 [2:0]: interpose(): ./libA.so
	 [2:2EP]: interpose(): ./main

       To analyze binding information more thoroughly, the bindings  data  can
       be saved for further inspection. For example, the previous output indi‐
       cates that the function interpose() was called from two objects	exter‐
       nal  to main. Inspection of the binding output reveals where the refer‐
       ences to this function originated.

	 example% lari -s ./main
	 lari: ./main: bindings information saved as: /usr/tmp/lari.dbg.main
	 .....
	 example% fgrep foo /usr/tmp/lari.dbg.main
	 binding file=./libX.so to file=./main: symbol `interpose'
	 binding file=./libY.so to file=./main: symbol `interpose'

       Note: The bindings output is typically more extensive than shown	 here,
       as the output is accompanied with process identifier, address and other
       bindings information.

       Example 2 Generating an interface definition

       The following example creates interface definitions for an  application
       and  its dependency, while ignoring any versioned system libraries. The
       application main makes reference to the interfaces  one(),  two(),  and
       three() in foo.so:

	 example% lari -omv ./main
	 example% cat mapfile-foo.so
	 #
	 # Interface Definition mapfile for:
	 #	 Dynamic Object: ./foo.so
	 #	 Process:	 ./main
	 #

	 foo.so {
		 global:
			 one;
			 three;
			 two;
		 local:
			 _one;
			 _three;
			 _two;
			 *;
	 };

FILES
       $TMPDIR/lari.dbg.file	Binding output produced by ldd(1).

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Availability		     │developer/linker		   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Interface Stability	     │See below.		   │
       └─────────────────────────────┴─────────────────────────────┘

       The human readable output is Uncommitted. The options are Committed.

SEE ALSO
       ld(1), ldd(1), ld.so.1(1), dlopen(3C), dlsym(3C), attributes(5)

       Linker and Libraries Guide

SunOS 5.11			  28 Nov 2007			       lari(1)
[top]

List of man pages available for OpenIndiana

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net