usr/src/tools/scripts/find_elf.1onbld

   1 .\" Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved.
   2 .\"
   3 .\" CDDL HEADER START
   4 .\"
   5 .\" The contents of this file are subject to the terms of the
   6 .\" Common Development and Distribution License (the "License").
   7 .\" You may not use this file except in compliance with the License.
   8 .\"
   9 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  10 .\" or http://www.opensolaris.org/os/licensing.
  11 .\" See the License for the specific language governing permissions
  12 .\" and limitations under the License.
  13 .\"
  14 .\" When distributing Covered Code, include this CDDL HEADER in each
  15 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  16 .\" If applicable, add the following below this CDDL HEADER, with the
  17 .\" fields enclosed by brackets "[]" replaced with your own identifying
  18 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  19 .\"
  20 .\" CDDL HEADER END
  21 .\"
  22 .TH FIND_ELF 1ONBLD "Mar 25, 2010"
  23 .SH NAME
  24 find_elf \- Locate ELF shared objects and executables
  25 .SH SYNOPSIS
  26 \fBfind_elf [-afrs] path\fP
  27 .SH DESCRIPTION
  28 The
  29 .I find_elf
  30 command descends a directory hierarchy and produces one line
  31 of output on stdout for each ELF executable or shared object found.
  32 .SH OPTIONS
  33 .LP
  34 The following options are supported:
  35 .TP 4
  36 .B \-a
  37 Disable alias processing. Symbolic links are treated as independent
  38 files, each such link results in a separate OBJECT output line,
  39 and ALIAS lines are not issued.
  40 .TP 4
  41 .B \-f
  42 Fast Mode. When reading directories, the file name and modes are
  43 used to eliminate files from consideration and speed up the search:
  44 Directories with names that start with a '.' character are skipped.
  45 Executables must have the execute bit set, and
  46 shared objects must end with a .so extension. Files that do not
  47 meet these requirements are silently eliminated from consideration without
  48 further analysis.
  49 .TP 4
  50 .B \-r
  51 Report file names as relative paths, relative to the given file or directory,
  52 instead of fully qualified.
  53 .TP 4
  54 .B \-s
  55 Only report shared objects.
  56 .SH OUTPUT
  57 .LP
  58 .I find_elf
  59 produces a series of PREFIX, OBJECT, and ALIAS lines, which collectively
  60 describe the ELF objects located. Whitespace is used within each
  61 line to delimit the various fields of information provided.
  62 .P
  63 If the \fB-r\fP option is used to specify that file names be reported
  64 as relative paths, a PREFIX line is output to provide the base path from
  65 which the relative names should be interpreted.
  66 There can only be one PREFIX line, and it is output first, before any
  67 OBJECT or ALIAS lines.
  68 .sp
  69 .in +4
  70 .nf
  71 PREFIX path
  72 .fi
  73 .in -4
  74 .sp
  75 For each object found, an OBJECT line is produced to describe it:
  76 .sp
  77 .in +4
  78 .nf
  79 OBJECT [32 | 64] [DYN | EXEC] [VERDEF | NOVERDEF] object-path
  80 .fi
  81 .in -4
  82 .sp
  83 The first field provides the ELF class of the object, and will be
  84 either 32 or 64.
  85 The second field provides the type of object, either
  86 a shared object (DYN) or executable (EXEC).
  87 The third field will be VERDEF if the object contains ELF
  88 version definitions, and NOVERDEF if the object is not versioned.
  89 The final field gives the path to the object.
  90 .P
  91 Under Unix, a file can have multiple names. In the context of ELF
  92 objects, this often happens for one of two reasons:
  93 .RS +4
  94 .TP
  95 .ie t \(bu
  96 .el o
  97 Compilation symlinks, used to provide a non-versioned name for a shared object.
  98 .RE
  99 .RS +4
 100 .TP
 101 .ie t \(bu
 102 .el o
 103 Symlinks such as '32' and '64' used to provide alternative
 104 non-machine specific paths to objects.
 105 .RE
 106 .sp
 107 When
 108 .I find_elf
 109 identifies an object via such an aliased name, it issues an ALIAS line
 110 mapping it to the main name for the object:
 111 .sp
 112 .in +4
 113 .nf
 114 ALIAS object-path alias-path
 115 .fi
 116 .in -4
 117 .sp
 118 The \fB-a\fP option alters the handling of aliased names. When \fB-a\fP is
 119 specified, each file results in a separate OBJECT line, as if they were
 120 independent files rather than the same file with different names.
 121 .sp
 122 .SH EXAMPLES
 123 Assume the following hierarchy of files exist under /usr/lib/foo:
 124 .sp
 125 .in +4
 126 .nf
 127 % /bin/ls -alRF /usr/lib/foo
 128 /usr/lib/foo:
 129 total 111
 130 drwxr-xr-x  3 root root    7 Jul 16 17:35 ./
 131 drwxr-xr-x 34 root root   42 Jul 16 17:34 ../
 132 lrwxrwxrwx  1 root bin     1 Jul 16 17:34 32 -> ./
 133 lrwxrwxrwx  1 root bin     5 Jul 16 17:34 64 -> amd64/
 134 drwxr-xr-x  2 root bin     4 Jul 16 17:35 amd64/
 135 lrwxrwxrwx  1 root bin    11 Jul 16 17:35 libfoo.so -> libfoo.so.1*
 136 -rwxr-xr-x  1 root bin 49132 Jul 16 17:35 libfoo.so.1*
 137
 138 /usr/lib/foo/amd64:
 139 total 150
 140 drwxr-xr-x  2 root root   4 Jul 16 17:35 ./
 141 drwxr-xr-x  3 root root   7 Jul 16 17:35 ../
 142 lrwxrwxrwx  1 root bin    11 Jul 16 17:35 libfoo.so -> libfoo.so.1*
 143 -rwxr-xr-x  1 root bin 72536 Jul 16 17:35 libfoo.so.1*
 144 .fi
 145 .in -4
 146 .sp
 147 This hierarchy contains compilation symlinks (libfoo.so) and
 148 path alias symlinks (32, 64), as discussed in OUTPUT.
 149 .P
 150 .I find_elf
 151 produces the following output for the above hierarchy:
 152 .sp
 153 .in +4
 154 .nf
 155 % find_elf -r /usr/lib/foo
 156 PREFIX /usr/lib/foo
 157 OBJECT 64 DYN  VERDEF  amd64/libfoo.so.1
 158 ALIAS                  amd64/libfoo.so.1  64/libfoo.so
 159 ALIAS                  amd64/libfoo.so.1  64/libfoo.so.1
 160 ALIAS                  amd64/libfoo.so.1  amd64/libfoo.so
 161 OBJECT 32 DYN  VERDEF  libfoo.so.1
 162 ALIAS                  libfoo.so.1        32/libfoo.so
 163 ALIAS                  libfoo.so.1        32/libfoo.so.1
 164 ALIAS                  libfoo.so.1        libfoo.so
 165 .fi
 166 .in -4
 167 .sp
 168 Contrast this with the output when \fB-a\fP is used to treat
 169 each name as an independent file:
 170 .sp
 171 .in +4
 172 .nf
 173 % find_elf -ar /usr/lib/foo
 174 PREFIX /usr/lib/foo
 175 OBJECT 32 DYN  VERDEF  32/libfoo.so
 176 OBJECT 32 DYN  VERDEF  32/libfoo.so.1
 177 OBJECT 64 DYN  VERDEF  64/libfoo.so
 178 OBJECT 64 DYN  VERDEF  64/libfoo.so.1
 179 OBJECT 64 DYN  VERDEF  amd64/libfoo.so.1
 180 OBJECT 64 DYN  VERDEF  amd64/libfoo.so
 181 OBJECT 32 DYN  VERDEF  libfoo.so.1
 182 OBJECT 32 DYN  VERDEF  libfoo.so
 183 .fi
 184 .in -4
 185 .sp
 186 When
 187 .I find_elf
 188 is used to process an alias for which no target object is given,
 189 there will be no output. For example, using /lib/libc.so, which
 190 is a compilation symlink for /lib/libc.so.1:
 191 .sp
 192 .in +4
 193 .nf
 194 % find_elf /lib/libc.so
 195 .fi
 196 .in -4
 197 .sp
 198 In such situations, the \fB-a\fP option can be used to produce
 199 the desired output:
 200 .sp
 201 .in +4
 202 .nf
 203 % find_elf -a /lib/libc.so
 204 OBJECT 32 DYN  VERDEF   /lib/libc.so
 205 .fi
 206 .in -4
 207 .sp
 208 .PP
 209 .RS
 210 .nf
 211 .SH SEE ALSO
 212 .BR check_rtime (1ONBLD),
 213 .BR interface_check (1ONBLD),
 214 .BR interface_cmp (1ONBLD),
 215 .BR ld (1),
 216 .BR ldd (1),
 217 .BR elfdump (1),
 218 .BR pvs (1).
 219