README.mapfiles revision f808c858fa61e7769218966759510a8b1190dfcf
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte# CDDL HEADER START
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte# The contents of this file are subject to the terms of the
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte# Common Development and Distribution License (the "License").
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte# You may not use this file except in compliance with the License.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte# See the License for the specific language governing permissions
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte# and limitations under the License.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte# When distributing Covered Code, include this CDDL HEADER in each
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte# file and include the License file at usr/src/OPENSOLARIS.LICENSE.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte# If applicable, add the following below this CDDL HEADER, with the
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte# fields enclosed by brackets "[]" replaced with your own identifying
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte# information: Portions Copyright [yyyy] [name of copyright owner]
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte# CDDL HEADER END
570de38f63910201fdd77246630b7aa8f9dc5661Surya Prakki# Copyright 2006 Sun Microsystems, Inc. All rights reserved.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte# Use is subject to license terms.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte# ident "%Z%%M% %I% %E% SMI"
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteMapfiles and versioning in ON
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte=============================
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte1.0 Objective of this README
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteThis README describes the engineering practices of creating and updating
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortevisible library interfaces. It describes various kinds of actions that
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortetypically occur as libraries are evolved, and shows how interface
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortespecifications are affected or updated in accordance. It tells you what
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteyou must do as a shared library developer if you:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte 1. Make interface additions to an existing library
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte - add a Public interface
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte - add a Private interface
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte 2. Update an interface in an existing library
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte - remove an existing interface
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte - promote a Private interface to Public
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte - scope a Private interface to local
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte - move an interface from one library to another
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte - copy interfaces which are part of the standard to a new or
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte existing library
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte 3. Introduce a new library
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte - source directory hierarchy
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte - creation of the "mapfile-vers" file
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte 4. Make an entire library obsolete before end-of-life
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte - introduce SUNWobsolete to the "mapfile-vers" file
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte-------------------------------------------------------------------------------
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte2.0 What's a mapfile?
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteMapfiles are used to tell the link editor ("ld") all sorts of things about
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortehow to generate an executable file or a shared object from a collection of
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forterelocatable objects, such as generated by a compiler. For all the gory
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortedetails, see the Solaris Linker and Libraries Guide, which can be found
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteHere, we are only concerned with specifying externally-visible interfaces
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortefor shared libraries (shared objects) and with specifying their versions
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortefor ABI (Application Binary Interface) purposes. For these purposes, we
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteonly need to deal with a subset of the mapfile interfaces.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteThere should be a "mapfile-vers" file associated with every shared library
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteand it should reside in the common source directory for that library, most
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteoften in a "common" directory. This is the usual layout of a library's
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortetop-level directory (usr/src/lib/libwombat):
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte Makefile amd64/ i386/ sparcv9/
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte Makefile.com common/ sparc/
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteThe "common" directory contains the source files and other common files
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortefor the library:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteThe mapfile's name is, by convention, "mapfile-vers" because it is used
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortefor only two purposes: to specify externally-visible interface names while
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortesuppressing visibility of all other names, and to specify their respective
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteunique version names.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte-------------------------------------------------------------------------------
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte3.0 Contents of mapfile-vers
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteThe structure of mapfile-vers is best explained by an example
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte(the license notification and copyright notice is omitted here
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortefor brevity):
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteSUNW_1.2 { # update to libwombat, Solaris 10
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteSUNW_1.1 { # first release of libwombat, Solaris 9
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteSUNWprivate { # private libwombat symbols
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteThe SUNW_1.* names are the Public version names for the library.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteThere should be at most one version name for each release of Solaris,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortewith the minor number incremented by one over the previous version.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteIf no update to the Public-visible names in the library is made
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortein a given Solaris release, no new version name should be generated
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortefor that release. If multiple updates are made to the library at
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortedifferent points in the development of a given release of Solaris,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteonly one version should be used for the entire release.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteSo, for example, if an update to libwombat is made in Solaris 11,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteyou would add "SUNW_1.3" at the start of the mapfile:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteSUNW_1.3 { # update to libwombat, Solaris 11
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteEach version must inherit all symbols from its preceding version,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortespecified at the ending "}" for each version. SUNW_1.1 does not
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteinherit any symbols. SUNWprivate, if present, stands alone.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteThe two lines in SUNWprivate:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteensure that no symbols other than those listed in the mapfile are
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortevisible to clients of the library. If there is no SUNWprivate,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortethese two lines should appear in SUNW_1.1.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteFor maintainability, the list of names in each version block should
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortebe sorted in dictionary order (sort -d). Please comply.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteIn addition to the common mapfile:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortesome libraries require ISA-specific supplemental mapfiles, one in each
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteof the ISA directories:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteThis is necessary only if there are ISA-specific library interfaces not
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortecommon to all instances of the library. For example, see libproc, or,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteif you are masochistic, libc or libnsl.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteThe ISA-specific mapfiles look like the common mapfile, except that only
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortethe ISA-specific names appear. The version names are the same as those
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortein the common mapfile, but only non-empty version instances are present
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteand no inheritance specification is present.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte-------------------------------------------------------------------------------
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte4.0 Making interface additions to an existing library
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte4.1 Adding a Public interface
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteThe first engineer to update the existing mapfile-vers file in a release needs
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteto identify the current highest version name and properly increment the minor
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteversion number by 1 to be the new version name. If this is the first Public
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteinterface in the shared object, a new SUNW_1.1 version name must be introduced.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteThe major revision number is incremented whenever an incompatible change is
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortemade to an interface. This could be the case if an API changes so dramatically
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteas to invalidate dependencies. This rarely occurs in practice. It also
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forterequires changing the suffix of the shared object from, say, .so.1 to .so.2
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteand introducing code to continue to ship the .so.1 version of the library.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteThe minor revision number is incremented whenever one or more new interfaces
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteis added to a library. Note that the minor number is not incremented on every
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteputback that makes an interface addition to the library. Rather, it is
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteincremented at most once per (external to Sun) release of the library.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte4.2 Adding a Private interface
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn FortePrivate interfaces are the non-ABI interfaces of the library. Unlike
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteintroducing a Public interface, a new entry is simply added to the
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteSUNWprivate version. No minor number increment is necessary.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteIf this interface happens to be the first Private interface introduced
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteinto the library, the SUNWprivate version must be created (no major.minor
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteversion numbers). It inherits nothing and nothing inherits from it.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteIf the library already has Private interfaces, they may have numbered version
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortenames like SUNWprivate_m.n (due to errors of the past). If so, just use the
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortehighest numbered private version name to version the new interface. There
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteis no need to introduce a new private version name. Be careful not to use
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortea lower numbered private version name; doing so can cause runtime errors
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte(as opposed to load time errors) when running an application with older
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteversions of the library.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte4.3 Adding new public interfaces in an update release
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteAdding new public interfaces in an update release requires careful
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortecoordination with the next marketing release currently under development.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteMultiple updates ship during the period before the next marketing release
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteships, and since it is generally impossible to know the full set of new
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteinterfaces in the next marketing release until late in its development
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte(after multiple updates have shipped) it must be assumed that not all
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteinterfaces added to the next marketing release will be added to an update.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteConsequently, the new version number for an update cannot be a minor
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteincrement, but must be a micro increment. For example, if Release N
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortehas version number SUNW_1.3 and Release N+1 will have SUNW_1.4, then
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteinterfaces added to an update of Release N must have micro numbers such
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteas SUNW_1.3.1, SUNW_1.3.2, etc. (note that the micro number is not
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortedirectly tied to the update number: SUNW_1.3.1 may appear in Update 2).
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteThe micro versions form an inheritance chain that is inserted between
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortetwo successive minor versions. For example, the mapfile-vers file for
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteminor release "N+1" to reflect its inclusion of micro releases will
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortelook like the following:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteSUNW_1.4 { # release N+1
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte} SUNW_1.3.2;
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteSUNW_1.3.2 { # micro release 2 (e.g., release NU3)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte} SUNW_1.3.1;
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteSUNW_1.3.1 { # micro release 1 (e.g., release NU2)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteSUNW_1.3 { # release N
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteSUNW_1.2 { # release N-1
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteSUNW_1.1 { # first release
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteSUNW_private { # same in all releases
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteThe corresponding update/patch mapfile-vers file will be identical
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteexcept for the exclusion of SUNW_1.4.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteThose interfaces which are only present in Release N+1 are always put
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteinto the next minor version set, SUNW_1.4.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteThus when adding a new public interface to an update, both the mapfiles
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteof the update release and next marketing release must be modified to be
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteconsistent. The update versions should not be added to the marketing
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forterelease until the putback to the update release has occurred, to avoid
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortetiming problems with the update releases (it's all too easy for projects
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteto slip out of updates, or to change ordering).
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte-------------------------------------------------------------------------------
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte5.0 How to update an interface in an existing library
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte5.1 Removing an existing interface
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte5.1.1 Moving a Public interface
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteNo Public interfaces should ever be removed from any mapfile.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteTo move an interface from one library to (say) libc, the code has to be
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortedeleted from the library and added to libc, then the mapfile for the
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortelibrary has to have the interface's entry changed from:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte getfoobar = FUNCTION FILTER libc.so.1;
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteSee, for example, libnsl's common/mapfile-vers file.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteFollow the rules for adding a new interface for the necessary changes
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteto libc's mapfile to accommodate the moved interface. In particular,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortethe new interface must be added to the current highest libc version.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteTo move an entire library into libc, look at what has already been done
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortefor libthread, libaio, and librt.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte5.1.2 Removing a Private interface
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteDeletion of Private interfaces is allowed, but caution should be taken;
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteit should first be established that the interface is not being used.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteTo remove a Private interface, simply delete the corresponding entry
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortefor that symbol from the mapfile's SUNWprivate section.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteDo not forget to delete these Public or Private interfaces from the library's
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteheader files as well as from the code that implements the interfaces.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte5.2 Promoting a Private interface to Public
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteThis is similar to what's done when adding a Public interface. Promoting an
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteexisting Private interface to a Public one only requires a change to the
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteexisting interface definition. Private interfaces have the symbol version name
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte"SUNWprivate" associated with them. To make the interface a Public one, the
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteinterface must be put into a set associated with the current Public release
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortelevel of the library.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteAs an example, if we were modifying libwombat.so.1 and its version in the
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortelast release of Solaris was SUNW_1.23, any new ABI introduced in the next
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forterelease would be put into a version called SUNW_1.24. Therefore, whether
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteyou wish to promote an existing Private interface to Public, or to introduce
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortea new Public interface, this (next successive minor numbered version level)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortewould be the version that it would be associated with.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte5.3 Scoping a Private interface local
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteAny interfaces not present in the mapfile-vers file will automatically be
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortescoped local (i.e., they will not be visible outside the library). Simply
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteremove the Private interface from the mapfile-vers file and the header file
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteto prevent it from being exported. This may require moving the Private
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteinterface into a library-private header file. Scope reduction of Public
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteinterfaces is not allowed.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteFor the interface to be used in more than one file within the library, it
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteshould be in a header file that can be included by each file in the library
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortethat uses the interface. For example:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte5.4 How to copy interfaces which are part of a standard to a new or existing
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteSYSVABI and SISCD are reserved version names for interfaces listed in the
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteSystem V Interface Definition and the Sparc Compliance Definition. Avoid using
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortethese version names when copying the implementation of standard interfaces to
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteanother library. Instead, use SUNW_1.1 for a new library, and SUNW_m.n for
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortean existing library (where m.n is the next release version; i.e., if the
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortelast version was SUNW_1.18, then you should version the interfaces with
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte-------------------------------------------------------------------------------
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte6.0 Introducing a new library
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte6.1 Directories
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteThe normal discipline for introducing a new library in OS/Net is to create a
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortenew subdirectory of /usr/src/lib. The interface definition discipline is to
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortecreate a common/mapfile-vers file for the new library. If we were introducing
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortea new foo library, libfoo, we'd create /usr/src/lib/libfoo containing:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte Makefile amd64/ i386/ sparcv9/
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte Makefile.com common/ sparc/
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteThe common subdirectory would contain the normal source files plus the
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortemapfile-vers file. See usr/src/lib/README.Makefiles for directions on
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortehow to organize the Makefiles.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte6.2 The mapfile
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteThe new common/mapfile-vers file would contain:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteSUNW_1.1 { # first release of libfoo
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteSUNWprivate {
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteIf there are no Public interfaces, the SUNW_1.1 section would be omitted.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteIf there are no Private interfaces, the SUNWprivate section would be
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteomitted and the two lines:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortewould be moved into SUNW_1.1
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteTo decide which interfaces are Public (part of the ABI) and which are Private
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte(unstable interfaces not intended to be used by third party applications or
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteunbundled products), the heuristic which works to a first approximation is
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortethat if it has a man page then it's Public. Also, it is really the ARC case
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortefor the new interfaces that prescribes which interfaces are Public and
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortewhich are not (hence, which interfaces have man pages and which do not).
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteFor maintainability, the list of names in each version block should
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortebe sorted in dictionary order (sort -d). Please comply.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte-------------------------------------------------------------------------------
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte7.0 Make an entire library obsolete
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte7.1 Introduce SUNWobsolete version
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteUse this version name not for specific interfaces but for marking an entire
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortelibrary as obsolete. The existing public/private version names are left
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forteunchanged, but a new SUNWobsolete version is created with no symbols in it.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteThis becomes a tag by which the obsolescence of the library can be recognized.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteThere is no numbering of this version name.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteSUNWobsolete {
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte SUNWobsolete; # This is the only way to do it.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte-------------------------------------------------------------------------------
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte8.0 Documentation
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteFor further information, please refer to the following documents:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte "Solaris Linker and Libraries Guide", http://docs.sun.com
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteFor information on the now-obsolete spec files, used in Solaris releases
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte7 through 10, see: