shlib man page on BSDOS

Man page or keyword search:  
man Server   6284 pages
apropos Keyword Search (all sections)
Output format
BSDOS logo
[printable version]

SHLIB(8)		  BSD System Manager's Manual		      SHLIB(8)

NAME
     shlib - create statically linked shared libraries from library archives

SYNOPSIS
     shlib [-[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 ALSO
     mkshlib(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
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server BSDOS

List of man pages available for BSDOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net