symlookup.1

.\" symlookup manual page
.\" Copyright © 2007-2011 Andrew Savchenko
.\"
.\" This file is part of symlookup.
.\"
.\" symlookup is free software: you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License version 3 as
.\" published by the Free Software Foundation
.\"
.\" symlookup is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License version 3 for more details.
.\"
.\" You should have received a copy of the GNU General Public License version 3
.\" along with symlookup. If not, see <http://www.gnu.org/licenses/>.
.\"
.TH symlookup 1 "28 Oct 2011" "version 0.5.2" "Symbol Lookup Utility"
.SH NAME
symlookup \- search for symbols in object files
.SH SYNOPSIS

.B symlookup
.RI "[" options "] [" symbols "]"
.br
.B symlookup
[-h | --help]
.br
.B symlookup
[-V | --version]
.br
.\" ****************************************************************
.SH DESCRIPTION

.B symlookup
is an utility intended for object symbols search in dynamic or
static symbol libraries. It looks up for libraries where given
symbols are defined and optionally can find packages holding these
libraries.

By default a search is performed in the standard system paths
recursively, looking into dynamic libraries only, and omitting
symbolic links.
But a program's behaviour may be fully customized by the command line
options.
Default system paths are determined in the same way as
.BR ld (1)
does. Refer to
.B DEFAULT PATHS
below for detailed information.

You can use extended regular expressions for symbols definition (see
.BR grep (1)
for details). Another benefit of this program is a powerful sort
engine for obtained results, see
.B SORTING
below.

Optional support for package management systems is present, it is
configurable at a compile time.
Currently
.BR rpm (8)
and
.BR portage (5)
are supported.
Fore more details refer to
.BR "PACKAGE MANAGEMENT OPTIONS" .
.\" ****************************************************************
.SH QUERY OPTIONS
.TP
.BR -a ", " --ar
Search in the
.BR ar (1)
archives altogether with shared object libraries.
.TP
.BR -A ", " --ar-only
Search in the
.BR ar (1)
archives
.IR only .
.TP
.BR -d ", " --xdev
Stay on the same physical device as a search path directory.
Useful if you don't want to descend into other file systems
mounted inside root search directories.
.TP
.BR -F ", " --filename-repexp
Limit library file names by specified extended regular expression.
See 
.BR grep (1)
for syntax details.
Leading directory name is not affected by this filter.
Please note: extension check limitations are still active with this
option, use
.B -X
to disable them if you really want.
.TP
.BR -i ", " --ignorecase
Ignore case in symbol names or appropriate extended regular
expressions.
.TP
.BR -I ", " --filename-ignorecase
Ignore case in file name extended regular expression.
This option is useless without
.BR -F .
.P
.BR -p ", "
.BI "--path " <PATH1:PATH2:...>
.RS
Specify path(s) for a library search, this will override defaults,
not extend them. Each physical file will be analysed once, even
for overlapped paths or multiple hardlinks.
.RE
.TP
.BR -r ", " --repexp
Treat given symbols as extended regular expressions likewise
.BR grep (1)
instead of search for direct match.
.TP
.BR -s ", " --follow
Follow symbolic links instead of omitting them. Be careful: often
this is just waste of time, because symbolic links usually refer
to the libraries in the same directory.
.TP
.BR -X ", " --noext
Do not perform an extension check for files in question. By default
".*\\.so\\..*" and ".*\\.so$" patterns are checked for shared
objects and ".*\\.a$" for ar archives. (If these patterns confuse
you, look at
.BR grep (1)
manual to understand them.)
.TP
.I Note:
if
.B -a
and
.B -A
options are specified together, the last one will take an effect.
.\" ****************************************************************
.SH OUTPUT OPTIONS
.TP
.BR -H ", " --header
Show a header when results are displayed as a table.
Only valid with
.B -t
option.
.TP
.BR -q ", " --quiet
Be quiet. Show only fatal error messages with few exceptions. This
will also skip some non-mandatory sanity checks, thus making
program running a bit faster but less informative.
.TP
.BR -v ", " --verbose
Be more verbose than by default. This will enable some annoying
messages.
.P
.BR -S ", "
.BI "--sort " [field,...]
.RS
Sort search results. You can arrange collation subsequence order,
see
.B SORTING
below.
.RE
.TP
.BR -t ", " --table
Print search results as a table.
.TP
.I Note:
if
.B -q
and
.B -v
options are specified together, the last one will take an effect.
.\" ****************************************************************
.SH PACKAGE MANAGEMENT OPTIONS

.B symlookup
has optional support for
.BR rpm (8)
and
.BR portage (5)
package management systems.
It may be enabled or disabled via configure script.
It is OK to use several package management systems at once (thought
this kind of setup is rather rare).
Of course, the following options are only valid if program was
compiled with an appropriate package management support.

.I RPM OPTIONS
.TP
.BR -R ", " --rpm
Search for rpms owning found libraries.
.TP
.BR --rpm-root
Specify a path to the rpm root directory.
Please note, this is not a path to the rpm database directory, but
rather to a chroot directory holding this database; so this patch
will be prefixed to /var/lib/rpmdir or whatever is used by rpm on
your system.
.PP
.RB "An additional " rpm
search field is available for sort requests.
See
.B SORTING
below.
.PP
.B symlookup
honors rpm configuration files in the same way as
.BR rpm (8)
does, so you can attune its behaviour via rpm config files as well.

.I PORTAGE OPTIONS
.TP
.BR -E ", " --ebuild
Search for ebuilds owning found libraries.
.TP
.BR --portage-db
Specify a path to the portage database root directory.
Usually this is /var/db/pkg, but may differ if you are using prefix
setup, or chroot or similar conditions.
.PP
.RB "An additional " ebuild
search field is available for sort requests.
See
.B SORTING
below.
.TP
.I Note:
Immediate output of unsorted results is not possible for ebuild
queries because portage data base implementation is highly
inefficient for ownership queries.
All matched files will be queried at once and results will be
output in the very end of the program execution.
.\" ****************************************************************
.SH GENERAL OPTIONS
.TP
.BR -h ", " --help
Show help message, usage information and exit.
.TP
.BR -V ", " --version
Display version information and exit.
.\" ****************************************************************
.SH SORTING

.B symlookup
provides a rather powerful sort system for matches found. Thus it
may be useful not only for a particular symbols definition search,
but also for an analysis of large library sets or an entire system.

Results collation is performed sequentially according to the list
of fields provided. Fields in the list must be separated by a comma,
no spaces, tabs and other delimiters are allowed. If short sort
option
.B -S
is used the list of fields must follow the option immediately
without any spaces. If long one is used, the list must immediately
follow the '=' sign or space.

Valid field values are:
.TP
.I match
Sort results separately for an each symbol pattern provided by the
user; if neither
.BR -i " nor " -r
is provided this option is useless and will be ignored, because
exact match search is performed in this case. It must be the first
sort field if provided.
.TP
.I name
Sort by symbol name (case sensitive).
.TP
.I file
Sort by file name containing matched symbols.
.TP
.I ebuild
Sort by ebuild owning matched file; it is useless if
.B -E
is unspecified and will be ignored. Option is valid only if program
is compiled with ebuild support.
.TP
.I rpm
Sort by rpm owning matched file; it is useless if
.B -R
is unspecified and will be ignored. Option is valid only if program
is compiled with rpm support.
.P
.RE
Default sort sequence is
.IR file[,ebuild][,rpm],symbol .
This also affects
.I match
sorting. If not all fields are specified, sane defaults will be
used to complete the sequence.

Be aware of memory usage required for sorting. It is directly
proportional to a number of matched results. So if you want to
use very general regexps together with sorting, you will need
much more memory than for ordinary execution.

For this stress test:
.RS
symlookup -arR --sort=rpm,file,symbol ".*"
.RE
a peak memory usage was about 137 MB on my system with about 7000
both dynamic and static libraries installed.

If you'll ever encounter "out of memory" problem, try to
particularize search pattern or disable sort at all.
.\" ****************************************************************
.SH DEFAULT PATHS

Default search paths are detected in the same way as
.B ld (1)
utility does this, so program will check all libraries available
for an ordinary application. The following search paths are used in
order:
.TP
.B 1.
The contents of "LD_RUN_PATH" environment variable.
.TP
.B 2.
The contents of "LD_LIBRARY_PATH" environment variable.
.TP
.B 3.
The contents of "DT_RUNPATH" environment variable. If "DT_RUNPATH"
is unset "DT_RPATH" entries are checked.
.TP
.B 4.
The default system directories
.IR /lib " and " /usr/lib .
.TP
.B 5.
If the file
.I /etc/ld.so.conf
exists, the list of directories found in that file or files 
included by that file.
.PP
Note: each physical file will be analysed once, even for overlapped
paths or multiple hardlinks.
.\" ****************************************************************
.SH SECURITY CONSIDERATION

You should 
.I not
run
.B symlookup
as a root.
Though this program was carefully developed to check all possible
error conditions and to ensure NULL-terminated strings whenever
possible, it still uses intensive string I/O and there is no
guaranty buffer overflow or alike problems will never occur.
Aside from that this program use external libraries which may have
their own security issues.

For almost all cases execution as a user is sufficient. In rare
occurrence some system libraries are not world readable. If you
really want to search inside them, you should copy these libraries
somewhere and make them user-readable.
.\" ****************************************************************
.SH EXIT STATUS
.TP
.B 0
Normal exit.
.TP
.B 1
Parse error. This means that some of provided options/arguments are
incorrect. Error message provides detailed information about the
reasons of an error.
.TP
.B 2
Input/output error. Extern media is broken, perhaps bad hardware,
pipe, network connection...
.TP
.B 3
Memory allocation error. Program is running out of memory. Try to
particularize search pattern or disable results sorting. If the
last way doesn't help and you have at least some MBs of virtual
memory available please report, this may be a bug.
.TP
.B 4
Fatal libelf error. Further processing is not possible. Most
probably reason is broken libelf library, try to upgrade.
.TP
.B 5
Fatal
.BR fts (3)
function set error. Further processing is not possible. Usually
this means problems with root search directory access or
insufficient memory for directory tree structure. See error message
for details.
.\" ****************************************************************
.SH BUGS

Object files > 2GB will be skipped on 32-bit systems. But such
cases seems to be impractical.
.\" ****************************************************************
.SH AUTHOR

.B symlookup
and this manual was written by Andrew Savchenko
<bircoph@users.sourceforge.net>, feel free to mail bug reports or
feature requests to this address.
.\" ****************************************************************
.SH SEE ALSO

.BR readelf (1),
.BR objdump (1),
.BR nm (1),
.BR ar (1)
are useful utilities for examining internals of object files.
.PP
.BR elf (5)
contains an elf file format specification.
.PP
.BR find (1),
.BR locate (1),
.BR xargs (1)
are handy utilities for finding files.
.PP
.BR grep (1)
contains a description of extended regular expressions syntax.
.PP
.BR rpm (8)
can be used for examination and manipulation of rpm files.
.PP
.BR portage (5)
describes Gentoo portage packaging system.
.PP
.BR emerge (1),
.BR ebuild (1),
.BR q (1)
are powerful portage manipulation utilities.
.PP
.BR dpkg (1),
.BR dpkg-deb (1)
are the main tools to manipulate and examine deb pakges.