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