Manual Pages for UNIX Operating System command usage for man pvs

User Commands                                              pvs(1)



NAME
     pvs - display the internal version  information  of  dynamic
     objects

SYNOPSIS
     pvs [-Cdlnorsv] [-I index-expr] [-N name] file...


DESCRIPTION
     The pvs utility displays any  internal  version  information
     contained  within  an  ELF  file.  Commonly, these files are
     dynamic executables and shared objects, and  possibly  relo-
     catable  objects. This version information can fall into one
     of two categories:

         o    version definitions

         o    version dependencies


     Version definitions describe the interfaces  that  are  made
     available by an ELF file. Each version definition is associ-
     ated to a set of global symbols provided by the file.   Ver-
     sion  definitions can be assigned to a file during its crea-
     tion by the link-editor using the -M option and the  associ-
     ated  mapfile directives. See the Linker and Libraries Guide
     for more details.


     Version dependencies describe the  binding  requirements  of
     dynamic  objects  on  the  version definitions of any shared
     object dependencies. When a dynamic object is built  with  a
     shared  object,  the  link-editor records information within
     the dynamic object indicating that the shared  object  is  a
     dependency.  This  dependency  must be satisfied at runtime.
     If the shared object also contains version definitions, then
     those  version  definitions  that  satisfy the global symbol
     requirements of the dynamic object are also recorded in  the
     dynamic object being created. At process initialization, the
     runtime linker uses any version dependencies as a  means  of
     validating the interface requirements of the dynamic objects
     used to construct the process.

OPTIONS
     The following options are supported. If neither the -d or -r
     options are specified, both are enabled.

     -C                Demangles C++ symbol names.


     -d                Prints version definition information.




SunOS 5.11          Last change: 25 Sep 2008                    1






User Commands                                              pvs(1)



     -I  index-expr    Qualifies the versions to examine  with  a
                       specific version index or index range. For
                       example, the version with index  3  in  an
                       object can be displayed using:

                         example% pvs -I 3 filename


                       An index-expr can be a single non-negative
                       integer  value  that  specifies a specific
                       version, as shown in the previous example.
                       Alternatively,  an  index-expr can consist
                       of two such values separated  by  a  colon
                       (:),  indicating  a range of versions. The
                       following example displays the versions 3,
                       4, and 5 in a file:

                         example% pvs -I 3:5 filename


                       When specifying an index range, the second
                       value can be omitted to indicate the final
                       item in the file. For example, the follow-
                       ing  statement lists all versions from the
                       tenth to the end:

                         example% pvs -I 10: filename


                       See Matching Options for additional infor-
                       mation  about  the  matching  options (-I,
                       -N).


     -l                Prints any symbols that have been  reduced
                       from  global  to local binding due to ver-
                       sioning.  By  convention,   these   symbol
                       entries  are  located  in the .symtab sec-
                       tion, and fall  between  the  FILE  symbol
                       representing the output file, and the FILE
                       symbol representing the first  input  file
                       used  to  generate the output file.  These
                       reduced symbol entries  are  assigned  the
                       fabricated  version definition _LOCAL_. No
                       reduced symbols will  be  printed  if  the
                       file  has been stripped (see strip(1)), or
                       if the symbol entry convention  cannot  be
                       determined.

                       Use of the -l  option  implicitly  enables
                       the -s option




SunOS 5.11          Last change: 25 Sep 2008                    2






User Commands                                              pvs(1)



     -n                Normalizes version definition information.
                       By default, all version definitions within
                       the object are displayed. However, version
                       definitions   can  inherit  other  version
                       definitions. Under normalization, only the
                       head   of   each   inheritance   list   is
                       displayed.


     -N name           When used with the -d  option,  -N  prints
                       only the information for the given version
                       definition name and any of  its  inherited
                       version definitions.

                       When used with the -r  option,  -N  prints
                       only  the information for the given depen-
                       dency file name. It is possible to qualify
                       a  specific  version  from  the dependency
                       file   by   including   the   version   in
                       parenthesis following the file name:

                         example% pvs -N 'dependency (version)' filename


                       See Matching Options for additional infor-
                       mation  about  the  matching  options (-I,
                       -N).


     -o                Creates one-line version  definition  out-
                       put.  By  default,  file,  version defini-
                       tions, and any symbol output  is  indented
                       to ease human inspection. This option pre-
                       fixes each output line with the  file  and
                       version  definition  name  and can be more
                       useful for analysis with automated  tools.


     -r                Prints version  dependency  (requirements)
                       information.


     -s                Prints the symbols  associated  with  each
                       version  definition. Any data symbols from
                       versions defined by the object are  accom-
                       panied  with  the  size,  in bytes, of the
                       data item.


     -v                Verbose output. Indicates any weak version
                       definitions,  and  any  version definition
                       inheritance. When used with the -N and  -d



SunOS 5.11          Last change: 25 Sep 2008                    3






User Commands                                              pvs(1)



                       options,  the inheritance of the base ver-
                       sion definition is also shown.  When  used
                       with  the  -s  option,  the version symbol
                       definition is also shown.


OPERANDS
     The following operands are supported.

     file    The  ELF file about which internal version  informa-
             tion is displayed.


USAGE
  Matching Options
     The -I and -N options are collectively referred  to  as  the
     matching options. These options are used to narrow the range
     of versions to examine, by index or by name.


     Any number and type of matching option can  be  mixed  in  a
     given  invocation  of  pvs.  In  this case, pvs displays the
     superset of all versions matched  by  any  of  the  matching
     options  used. This feature allows for the selection of com-
     plex groupings of items using the most convenient  form  for
     specifying each item.

EXAMPLES
     Example 1 Displaying version definitions


     The following example displays the  version  definitions  of
     libelf.so.1:


       % pvs -d /lib/libelf.so.1
            libelf.so.1;
            SUNW_1.1



     Example 2 Creating a one-liner display


     A normalized, one-liner display,  suitable  for  creating  a
     mapfile  version control directive, can be created using the
     -n and -o options:


       % pvs -don /lib/libelf.so.1
       /lib/libelf.so.1 -  SUNW_1.1;




SunOS 5.11          Last change: 25 Sep 2008                    4






User Commands                                              pvs(1)



     Example 3 Displaying version requirements


     The following example displays the version  requirements  of
     ldd and pvs:


       % pvs -r /usr/bin/ldd /usr/bin/pvs
       /usr/bin/ldd:
            libelf.so.1 (SUNW_1.1);
            libc.so.1 (SUNW_1.1);
       /usr/bin/pvs:
            libelf.so.1 (SUNW_1.1);
            libc.so.1 (SUNW_1.1);



     Example 4 Determining a dependency symbol version


     The following example displays the shared object from  which
     the  ldd command expects to find the printf function at run-
     time, as well as the version it belongs to:


       % pvs -ors /usr/bin/ldd | grep ' printf'
       /usr/bin/ldd -  libc.so.1 (SYSVABI_1.3): printf;



     Example 5 Determine all dependency symbols from  a  specific
     version


     The -N option can be used to obtain a list of all  the  sym-
     bols from a dependency that belong to a specific version. To
     determine the  symbols  that  ldd  will  find  from  version
     SYSVABI_1.3 of libc.so.1:


       % pvs -s -N 'libc.so.1 (SYSVABI_1.3)' /usr/bin/ldd

              libc.so.1 (SYSVABI_1.3):
                      _exit;
                      strstr;
                      printf;
                      __fpstart;
                      strncmp;
                      lseek;
                      strcmp;
                      getopt;
                      execl;



SunOS 5.11          Last change: 25 Sep 2008                    5






User Commands                                              pvs(1)



                      close;
                      fflush;
                      wait;
                      strerror;
                      putenv;
                      sprintf;
                      getenv;
                      open;
                      perror;
                      fork;
                      strlen;
                      geteuid;
                      access;
                      setlocale;
                      atexit;
                      fprintf;
                      exit;
                      read;
                      malloc;




     Note that the specific list  of  symbols  used  by  ldd  may
     change between Solaris releases.


     Example 6 Display base defined version by index


     By convention, the base global version defined by an  object
     has the name of the object. For example, the base version of
     pvs is named 'pvs'. The base version of any object is always
     version  index  1.  Therefore,  the -I option can be used to
     display the base version of any  object  without  having  to
     specify its name:


       % pvs -v -I 1 /usr/bin/pvs
              pvs [BASE];



EXIT STATUS
     If the requested version information is not  found,  a  non-
     zero value is returned. Otherwise, a 0 value is returned.


     Version information is determined not found when any of  the
     following is true:

         o    the  -d  option  is  specified   and   no   version



SunOS 5.11          Last change: 25 Sep 2008                    6






User Commands                                              pvs(1)



              definitions are found.

         o    the -r option is specified and no version  require-
              ments are found.

         o    neither the -d nor -r option is  specified  and  no
              version  definitions  or  version  requirements are
              found.

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



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | developer/linker            |
    |_____________________________|_____________________________|


SEE ALSO
     elfdump(1),  ld(1),  ldd(1),  strip(1),  elf(3ELF),   attri-
     butes(5)


     Linker and Libraries Guide



























SunOS 5.11          Last change: 25 Sep 2008                    7