SHLIB(8) BSD System Manager's Manual SHLIB(8)NAMEshlib - create statically linked shared libraries from library archives
SYNOPSISshlib [-[DIOU]*] [-E] [-L*] [-X excluded-file] [-b bootstrap-source] [-d
data-address] [-e except-file] [-i old-shared-image] [-larchive]
[-l archive-file] [-m shlib.map] [-n new-shared-image] [-s
new-stub-archive] -t text-address archive
DESCRIPTION
The shlib utility builds statically linked shared libraries from library
archive files. It is a low-level interface for shared library construc-
tion; for a high-level, more standardized interface, see mkshlib(8).
Statically linked shared libraries are binary files created by linking
together all of the objects in a normal archive library, along with a
jump table and an initialization routine. Programs that use shared li-
braries can load each required library binary into memory and use it to
execute library functions. Since the library binary is loaded on demand
and is shared between all processes that use it, both disk space in the
program and memory in running processes can be conserved. Programs are
linked against stub library archives, which are empty except for symbol
table entries describing the fixed addresses of the entry points and data
in the shared library binary. The library binary uses indirect entry
points grouped into a jump table, so that internal addresses of library
functions are hidden from programs that use them, and hence may be
changed without penalty when updating the shared library binary.
The flags and other arguments to shlib have the following form and mean-
ing:
-[DIOU*]
These C compile flags are passed to the C compiler when compiling
the bootstrap source.
-E Ignore the exceptions file (see -e below) and don't hide any sym-
bols. This feature is useful for libraries that require
widespread access to `hidden' symbols from user code via macros
or other tricks, such as the X11 and C++ libraries. Use of this
feature can reduce the likelihood that a library will be compati-
ble with the previous version when it gets rebuilt.
-L* This link path argument is passed to the linker when linking the
shared library.
-X file
Exclude the named archive member from the shared library. In
rare cases, an object file in an archive may cause problems for a
shared library. This flag allows such files to be excluded se-
lectively.
-b file
The given file is a pathname to the bootstrap source code for the
given library. The default bootstrap source is
/usr/lib/loader.c.
-d address
The address of the data segment of the shared library image is
given in hexadecimal (no 0x prefix). If this option is omitted,
it defaults to the text address plus 400000 hex.
-e file
The given file contains a list of symbols that are exceptions to
the usual conventions for exporting names, one name per line.
The usual conventions are that names in the file that do not be-
gin with an underscore are all exported, while all other names
are suppressed. If programs must link against a library name
that starts with an underscore, or must be protected from a name
that does not start with an underscore, that name must appear in
the exceptions list. This flag is ignored when using the -E
flag.
-i file
Produce a shared library image that is as compatible as possible
with a given older shared library image file. The shlib utility
will arrange the jump table and exported data in the new image so
that all the initial jump table slots and exported data items are
in the same order as in the old image. This maximizes the like-
lihood that programs linked for the old image will still work
with the new image. New jump table entries and exported data are
appended to the old ones. If this option is omitted, shlib will
choose its own order for jump table entries and exported data,
which might not be compatible with older images.
-larchive
When linking the new shared library image, shlib will link
against the given shared library stub archive to resolve symbols
that aren't defined by the library image it is building. It is
an error for a library to have unresolved symbols. Shlib looks
up the given -larchive flag in the shlib.map file to identify the
standard shared library that it corresponds to. The stub library
is found in the same directory as the source archive for the
shared library, but its name is the same as the library image
with a .a suffix.
-l archive
The stub library archive may also be named by an explicit path-
name.
-m file
The given file is a pathname for an alternate shlib.map file con-
taining specifications for standard shared libraries. Shlib uses
this file only to get the default stub archive name; see mksh-
lib(8) for more details about it.
-n file
The new shared library image will be placed in the given file. By
default, the image will be placed in the current directory with a
name that is the same as the source archive's name with the .a
suffix removed and _s appended.
-s file
The new shared library stub archive will be placed in the given
file. By default, the stub archive will be placed in the current
directory with a name that is the same as the source archive's
name with _s inserted before the .a suffix. A source archive
libfoo.a will yield by default an image named libfoo_s and a stub
archive named libfoo_s.a.
-t address
The address of the text segment of the shared library image is
given in hexadecimal (no 0x prefix). This flag and argument are
mandatory.
archive
The given source archive is linked together to form the shared
library image. This argument is mandatory.
The shlib utility prints messages about unexpected, undesirable or erro-
neous features of libraries that it constructs. Some of the messages
come from shlib itself, while other messages may be printed by programs
that shlib invokes, such as cc(1) to build the initialization code, as(1)
to build the stub library or ld(1) to link the shared library image. The
error messages should be self-explanatory; they report fatal problems in
building the library, such as unresolved symbols (undefined functions or
data). The warnings may suggest ways to improve a library to promote (or
achieve) compatibility. Here is a list of some of the more important
warnings:
Deleted entry points
This warning lists exported functions that were in a previous
version of a library which will not be present or exported in the
new version. If you replace the old library with the new one,
existing programs that use the deleted entry points will fail,
dumping core files. If the functions were omitted by mistake,
for example due to an error in the exception file, then you
should fix the error and try again. If you really do want to re-
move exported functions, it is often best to create a new version
of the shared library and let old programs use the old library.
Added entry points
This warning lists newly present or exported functions. Check
the list to be sure that you really did want to export all of
these functions. If you did not, then you can edit the exception
file to suppress some or all of them.
Deleted exported const data
New exported const data
Deleted exported data
New exported data
Exported data is the primary cause of incompatibility between
versions of a shared library. Because it must stay at the same
address when you update a library, you must take a great deal of
care when changing library files that export data. Deleting ex-
ported data is often fatal, while adding exported data greatly
increases the chances that new library updates will be incompati-
ble. If you see any warnings about new or deleted exported data
or const data, you should look at the listed names and consider
changes to restore the status quo.
You should also check exported data to be sure that you are not
polluting the namespace of programs. Exported names that do not
begin with an underscore should all be documented parts of the
programming interface. Undocumented symbols should not be ex-
ported.
WARNING: incompatibilities in global data addresses
Check [files] for changes in sizes or layout
These warnings are very serious. They list the names of exported
data and const data that will have an incompatible address in the
updated shared library. Any data that is at a different address
in the updated shared library will not be accessed correctly by
programs that were built with the previous library. You should
almost never install a library that has these problems. The
shlib utility will provide the names of a couple of library files
where you can start looking for incompatible changes.
Note that you can take defensive programming measures that great-
ly decrease the risk of incompatibility.
o Find ways to avoid exporting data. If some helper pro-
gram needs access to internal library data, then you
should return a pointer to that data using a function
call, rather than exporting the data directly.
o Put each exported data item in its own source file.
o Put padding at the end of data to allow for expansion
that won't change the size of the data.
o Try to avoid mixing variable length character strings
with exported const data. Character strings are allocat-
ed into the const data section, and changing the length
of a string may change the addresses of exported const
data items. Note that files that don't export any const
data are not affected by this problem; you can change
their variable length character strings without a penal-
ty. Thus a file that contains (say) a const array of
character strings may often be improved by making the ar-
ray non-const.
The shlib utility treats the C library specially. If the name of the
source library is libc.a, shlib links in a special version of the shared
library initialization routine which sets some well-known global vari-
ables such as environ, loads a list of other shared libraries passed in
from the program, and executes the program's main() routine.
FILES
/shlib directory for shared libraries used by root bina-
ries
/shlib/lib*_s* typical shared library images
/usr/lib/lib*_s*.a typical stub libraries
/usr/lib/lib*.except typical standard exception symbol list
/usr/lib/shlicrt0.o private data used for bootstrapping
/usr/lib/loader.c generic shared library initialization routine
/etc/shlib.map map of standard shared libraries
SEE ALSOmkshlib(8), ld(1), shlicc(1)BUGS
Don't be confused -- this program has nothing to do with dynamic shared
libraries, whose names end in `.so'. See the ld(1) manual page for infor-
mation on building dynamic shared libraries.
In BSD/OS 4.1, the format of the exception file changed. Older versions
of shlib required a.out(5)-style initial underscores; these are no
longer used. This change is a major incompatibility, but it also removes
a significant source of error.
In BSD/OS 4.1, the -c flag disappeared. The shlib utility can now iden-
tify const data using elf(5) features.
The file format for statically linked shared libraries starting with
BSD/OS 4.0 has switched to elf(5). Older a.out(5) format shared li-
braries cannot be updated using the new software.
Shlib won't take extraordinary measures to ensure that exported data ap-
pears at the same offset in a new image; it simply arranges for all the
objects containing exported data to be loaded at the beginning in the
same order as in the original image. If data address mismatches appear,
you must insert padding or trim data yourself.
In exceptional circumstances, a library may need to match the address of
an exported function with the address seen by a user program. (The Xt
library is an example.) To defeat jump table indirection for a function,
you should declare the function using the GCC extension __attribute__
((__section__ ".rodata")) so that its code goes into the .rodata read-on-
ly data section. This is bad because any change in the size of the func-
tion may ruin compatibility, but it's better than failing code.
See the BUGS section of the shlicc(1) page for more problems with shared
libraries.
BSD/OS October 8, 1999 5