mkshlib(CP) 6 January 1993 mkshlib(CP) Name mkshlib - create a shared library Syntax mkshlib -s specfil -t target [-h host] [-n] [-L dir ...] [-q] Description mkshlib builds both the host and target shared libraries. A shared library is similar in function to a normal, non-shared library, except that programs that link with a shared library will share the library code during execution, whereas programs that link with a non-shared library will get their own copy of each library routine used. The host shared library is an archive that is used to link-edit user pro- grams with the shared library (see ar(FP)). A host shared library can be treated exactly like a non-shared library and should be included on cc(CP) command lines in the usual way (see cc(CP)). Further, all opera- tions that can be performed on an archive can also be performed on the host shared library. The target shared library is an executable module that is bound into the user's address space during execution of a program using the shared library. The target shared library contains the code for all the rou- tines in the library and must be fully resolved. The target will be brought into memory during execution of a program using the shared library, and subsequent processes that use the shared library will share the copy of code already in memory. The text of the target is always shared, but each process will get its own copy of the data. The user interface to mkshlib consists of command line options and a shared library specification file. The shared library specification file describes the contents of the shared library. The mkshlib command invokes other tools such as the archiver, ar(CP), the assembler, as(CP), and the link editor, ld(CP). Tools are invoked through the use of execvp (see exec(S)), which searches directories in the user's PATH. Also, prefixes to mkshlib are passed in the same manner as prefixes to the rcc(CP) command, and invoked tools are given the pre- fix, where appropriate. For example, i386mkshlib will invoke i386ld. mkshlib recognizes the following command line options: -s specfil Specifies the shared library specification file, specfil. This file contains the information necessary to build a shared library. Its contents include the branch table specifications for the target, the path name in which the target should be installed, the start addresses of text and data for the target, the initialization specifications for the host, and the list of object files to be included in the shared library (see details below). -t target Specifies the output filename of the target shared library being created. It is assumed that this file will be installed on the target machine at the location given in the specifica- tion file (see the #target directive below). If the -n option is used, then a new target shared library will not be gen- erated. -h host Specifies the output filename of the host shared library being created. If this option is not given, then the host shared library will not be produced. -n Do not generate a new target shared library. This option is useful when producing only a new host shared library. The -t option must still be supplied since a version of the target shared library is needed to build the host shared library. -L dir ... Change the algorithm of searching for the host shared libraries specified with the #objects noload directive to look in dir before looking in the default directories. The -L option can be specified multiple times on the command line in which case the directories given with the -L options are searched in the order given on the command line before the default directories. -q Quiet warning messages. This option is useful when warning messages are expected but not desired. The shared library specification file contains all the information neces- sary to build both the host and target shared libraries. The contents and format of the specification file are given by the directives listed below. All directives that can be followed by multi-line specifications are valid until the next directive or the end of the file. #address sectname address Specifies the start address, address, of section sectname for the target. This directive typically is used to specify the start addresses of the .text and .data sections. One #address per section name is valid. A #address directive must be given exactly once for the .text section and once for the .data sec- tion. #target pathname Specifies the absolute path name, pathname, at which the target shared library will be installed on the target machine. The operating system uses this path name to locate the shared library when executing a.out files that use this shared library. This directive must be specified exactly once per specification file. #branch Specifies the start of the branch table specifications. The lines following this directive are taken to be branch table specification lines. Branch table specification lines have the following format: funcname <white space> position where funcname is the name of the symbol given a branch table entry and position specifies the position of funcname's branch table entry. position may be a single integer or a range of integers of the form position1-position2. Each position must be greater than or equal to one, the same position can not be specified more than once, and every position, from one to the highest given position, must be accounted for. If a symbol is given more than one branch table entry by asso- ciating a range of positions with the symbol or by specifying the same symbol on more than one branch table specification line, then the symbol is defined to have the address of the highest associated branch table entry. All other branch table entries for the symbol can be thought of as ``empty'' slots and can be replaced by new entries in future versions of the shared library. Only functions should be given branch table entries, and those functions must be external symbols. This directive must be specified exactly once per shared library specification file. #objects The lines following this directive are taken to be the list of input object files in the order they are to be loaded into the target. The list simply consists of each path name followed by a newline character. This list is also used to determine the input object files for the host shared library, but the order for the host is given by running the list through lorder(CP) and tsort(CP). This directive must be specified exactly once per shared library specification file. #objects noload The #objects noload is followed by a list of host shared libraries. These libraries are searched in the order listed to resolve undefined symbols from the library being built. During the search it is considered an error if a non-shared version of a symbol is found before a shared version of the symbol. Each name given is assumed to be a path name to a host or an argument of the form -lX, where libX.a is the name of a file in LIBDIR or LLIBDIR. This behavior is identical to that of ld, and the -L option can be used on the command line to specify other directories in which to locate these archives. Note that if a host shared library is specified using #objects noload, any cc command that links to the shared library being built will need to specify that host also. #hide linker [*] This directive changes symbols that are normally external into static symbols, local to the library being created. A regular expression may be given (see sh(C), find(C)), in which case all external symbols matching the regular expression are hidden; the #export directive (see below) can be used to counter this effect for specified symbols. The optional * is equivalent to the directive #hide linker * and causes all external symbols to be made into static symbols. All symbols specified in #init and #branch directives are assumed to be external symbols, and cannot be changed into static symbols using the #hide directive. #export linker [*] Symbols given in the #export directive are external symbols (global among files) that, because of a regular expression in a #hide directive, would otherwise have been made static. For example, #hide linker * #export linker one two causes all symbols except one, two, and those used in #branch and #init entries to be tagged as static. #init object Specifies that the object file, object, requires initialization code. The lines following this directive are taken to be ini- tialization specification lines. Initialization specification lines have the following format: ptr <white space> import ptr is a pointer to the associated imported symbol, import, and must be defined in the current specified object file, object. The initialization code generated for each such line is of the form: ptr = &import; All initializations for a particular object file must be given once and multiple specifications of the same object file are not allowed. #ident string Specifies a string, string, to be included in the .comment sec- tion of the target shared library. ## Specifies a comment. All information on the line beginning with ## is ignored. Files TEMPDIR/* Temporary files. TEMPDIR is usually /usr/tmp but can be re-defined by setting the environment variable TMPDIR (see tempnam() in tmpnam(S)). LIBDIR Usually /lib. LLIBDIR Usually /usr/lib. Notes The -n option cannot be used with the #objects noload directive. If mkshlib is asked to create a host library and a host of that name already exists, mkshlib will update the host using ar -ru. This means that you should always remove the host before rebuilding whenever an object file previously included in the library is removed or renamed. If the address specified with the #address directive is outside user space, the library build may look successful, but if you try to use it, it might not work. See also a.out(FP), ar(CP), ar(FP), as(CP), cc(CP), chkshlib(CP), ld(CP), lorder(CP), rcc(CP), tsort(CP)