>Excellent ideas... I can't claim any credit for them; Sun has been using a classification scheme and ABI validation tools for years. I've attached the Solaris attributes(5) man-page as a good summary of the notion of 'interface stability'; it also discusses how to classify libraries or interfaces in terms of their degree of internationalization (code-set independence) or MT-safety. >Colm Smyth <Colm Smyth ireland sun com> writes: >> First of all, I believe that source and binary compatability >> should only be required for stable *public* interfaces. >> >> If an interface is wholly private to an application (e.g. some >> functions in a library that are shared by two closely related >> programs, where those functions will never be needed elsewhere in >> GNOME), then there is no need to maintain compatability over >> releases. > >We need to be careful here. While some interfaces are genuinely >private and enforced, others are theoretically private but in reality >people are using them. (By "enforced" I mean for example that we don't >install the header file.) This "always" happens. I would suggest that the genuinely public interfaces are identified as such, while the private-but-publicly-used symbols (semi-private?!) are clearly listed as unstable. In an ideal world, it would be possible to identify the appropriate public symbol to match each private symbol so that applications have a clear migration path. If it's possible to identify the apps that use private symbols through the use of a tool (like the AppCert tool I mentioned), then it's easier for the maintainers to become compliant. I've attached an example of an ABI database file for a library that's part of CDE. As you can see, it identifies both private and public symbols as an aid to classifying symbol use in applications. >> It's possible to automatically validate an application >> by checking that there are only references to public >> symbols. By statically analyzing the dependent libraries >> of an application, it's possible to find all symbols that >> are defined within the application code and all symbols >> that are imported from public interfaces in GNOME libraries. >> Any symbol that is resolved from a GNOME library that is >> not part of a public interface can be highlighted as >> a binary compatibility violation. >> >> Actually this is exactly that a Solaris ABI validation tool >> called AppCert does. The hardest part is actually capturing >> all of the symbols that are part of the public interface >> of each library, although this too can be automated by >> taking the syntax-checking parts of a C compiler and >> outputting all symbols defined within the public header files >> of a library into a 'database' file for that public interface. >> >> If there is any interest in such a tool for GNOME, I can contact >> the team at Sun responsible for AppCert to see if they >> could contribute the AppCert tool-set to open-source >> for use in the GNOME project. >> > >It sounds useful, I think we'd be interested. You can find out more about AppCert and interface stability at Sun's ABI web site - http://www.sun.com/developers/tools/abi/tech.html. I'll contact the ABI tools team and see what we can do to make these tools available to the community, along with the tools we need to help generate an ABI database for GNOME libraries. >For GTK 2.0, another thing we're doing is renaming all the private >entry points with an underscore in front, and then we'll tell the >linker not to export those from the library (on linkers that support >that). This doesn't catch all private entry points, such as private >functions exported by GDK for use in GTK, but it does catch a lot of >them. Using underscore to mark private symbols that are used internally within a package is a good technique. As you mentioned, it's ideal if a mapfile can be provided to the linker to limit the symbols that are made global; this is a way to 'enforce' avoidance of private symbols, although for backwards compatibility reasons you may need to keep making "semi-private" symbols available for a release or two. >Havoc Colm.
Standards, Environments, and Macros attributes(5)
NAME
attributes, architecture, availability, CSI, stability, MT-
Level - characteristics of commands, utilities, and device
drivers
DESCRIPTION
The ATTRIBUTES man page section contains a table (see
below) defining attribute types and their corresponding
values.
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Architecture | SPARC |
|_____________________________|_____________________________|
| Availability | SUNWcsu |
|_____________________________|_____________________________|
| CSI | Enabled |
|_____________________________|_____________________________|
| Interface Stability | Unstable |
|_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
Architecture
Architecture defines processor or specific hardware. (See -p
option of uname(1)). In some cases, it may indicate required
adapters or peripherals.
Availability
This refers to the software package which contains the com-
mand or component being described on the man page. To be
able to use the command, the indicated package must have
been installed. For information on how to add a package see
pkgadd(1M).
Code Set Independence (CSI)
OS utilities and libraries which are free of dependencies on
the properties of any code sets are said to have Code Set
Independence (CSI). They have the attribute of being CSI
enabled. This is in contrast to many commands and utilities
in Solaris, for example, that work only with Extended Unix
Codesets (EUC), an encoding method that allows concurrent
support for up to four code sets and is commonly used to
represent Asian character sets.
However, for practical reasons, this independence is not
absolute. Certain assumptions are still applied to the
current CSI implementation:
o File code is a superset of ASCII.
SunOS 5.8 Last change: 3 June 1997 1
Standards, Environments, and Macros attributes(5)
o In order to support multi-byte characters and NULL-
terminated UNIX file names, the NULL and / (slash)
characters cannot be part of any multi-byte charac-
ters.
o Only "stateless" file code encodings are supported.
Stateless encoding avoids shift, locking shift, desig-
nation, invocation, and so forth, although single
shift is not excluded.
o Process code (wchar_t values) is implementation depen-
dent and can change over time or between implementa-
tions or between locales.
o Not every object in Solaris 2 and Solaris 7can have
names composed of arbitrary characters. The names of
the following objects must be composed of ASCII char-
acters:
o User names, group name, and passwords
o System name
o Names of printers and special devices
o Names of terminals (/dev/tty*)
o Process ID numbers
o Message queues, semaphores, and shared memory
labels.
o The following may be composed of ISO Latin-1 or
EUC characters:
o File names
o Directory names
o Command names
o Shell variables and environmental variable
names
o Mount points for file systems
o NIS key names and domain names
o The names of NFS shared files should be composed of
ASCII characters. Although files and directories may
have names and contents composed of characters from
non-ASCII code sets, using only the ASCII codeset
SunOS 5.8 Last change: 3 June 1997 2
Standards, Environments, and Macros attributes(5)
allows NFS mounting across any machine, regardless of
localization. For the commands and utilities that are
CSI enabled, all can handle single-byte and multi-byte
locales released in 2.6. For applications to get full
support of internationalization services, dynamic
binding has to be applied. Statically bound programs
will only get support for C and POSIX locales.
Interface Stability
Sun often provides developers with early access to new tech-
nologies, which allows developers to evaluate with them as
soon as possible. Unfortunately, new technologies are prone
to changes and standardization often results in interface
incompatibility from previous versions.
To make reasonable risk assessments, developers need to know
how likely an interface is to change in future releases. To
aid developers in making these assessments, interface sta-
bility information is included on some manual pages for
commands, entry-points, and file formats.
The more stable interfaces can safely be used by nearly all
applications, because Sun will endeavor to ensure that these
continue to work in future minor releases. Applications
that depend only on Standard and Stable interfaces should
reliably continue to function correctly on future minor
releases (but not necessarily on earlier major releases).
The less stable interfaces allow experimentation and proto-
typing, but should be used only with the understanding that
they might change incompatibly or even be dropped or
replaced with alternatives in future minor releases.
"Interfaces" that Sun does not document (for example, most
kernel data structures and some symbols in system header
files) may be implementation artifacts. Such internal inter-
faces are not only subject to incompatible change or remo-
val, but we are unlikely to mention such a change in release
notes.
Release Levels
Products are given release levels, as well as names, to aid
compatibility discussions. Each release level may also
include changes suitable for lower levels.
Release Version Significance
SunOS 5.8 Last change: 3 June 1997 3
Standards, Environments, and Macros attributes(5)
Major x.0 Likely to contain major feature addi-
tions; adhere to different, possibly
incompatible Standard revisions; and
though unlikely, could change, drop, or
replace Standard or Stable interfaces.
Initial product releases are usually 1.0.
Minor x.y Compared to an x.0 or earlier release
(y!=0), it's likely to contain: minor
feature additions, compatible Standard
and Stable interfaces, possibly incompa-
tible Evolving interfaces, or likely
incompatible Unstable interfaces.
Micro x.y.z Intended to be interface compatible with
the previous release (z!=0), but likely
to add bug fixes, performance enhance-
ments, and support for additional
hardware.
Classifications
The following table summarizes how stability level classif-
ications relate to release level. The first column lists the
Stability Level. The second column lists the Release Level
for Incompatable Changes, and the third column lists other
comments. For a complete discussion of individual classifi-
cations, see the appropriate subsection below.
Stability Release Comments
Standard Major (x.0) Actual or de facto.
Stable Major (x.0) Incompatibilities are exceptional.
Evolving Minor (x.y) Migration advice might accompany an
incompatibility.
Unstable Minor (x.y) Experimental or transitional: incompati-
bilities are common.
Obsolete Minor (x.y) Deprecated interface: likely to be
removed in a future minor release.
The interface stability levels described in this manual
page apply to both source and binary interfaces unless oth-
erwise stated. The stability level of each interface is
unknown unless explicitly stated.
Standard: organization_name, standard_name, version
The documented command or function complies with the
standard listed. Most of these interfaces are defined
by a formal standard, and controlled by a standards
organization. Changes will usually be made in accor-
dance with approved changes to that standard. his sta-
bility level can also apply to interfaces that have
been adopted (without a formal standard) by an
"industry convention."
SunOS 5.8 Last change: 3 June 1997 4
Standards, Environments, and Macros attributes(5)
Support is provided for only the specified version(s)
of a standard; support of later versions is not
guaranteed. If the standards organization approves a
non-upwards-compatible change to a Standard interface
that Sun decides to support, we will announce a compa-
tibility and migration strategy.
Stable
A Stable interface is a mature interface under Sun's
control. Sun will try to avoid non-upwards-compatible
changes to these interfaces, especially in minor or
micro releases.
If support of a Stable interface must be discontinued,
Sun will attempt to provide notification and the
stability level changes to Obsolete.
Evolving
An Evolving interface may eventually become Standard
or Stable but is still in transition.
Sun will make reasonable efforts to ensure compatibil-
ity with previous releases as it evolves. When non-
upwards compatible changes become necessary, they will
occur in minor and major releases; such changes will
be avoided in micro releases whenever possible. If
such a change is necessary, it will be documented in
the release notes for the effected release, and when
feasible, Sun will provide migration aids for binary
compatibility and continued source development.
Unstable
An Unstable interface is provided to give developers
early access to new or rapidly changing technology or
as an interim solution to a problem for which a more
stable solution is anticipated in the future.
For Unstable interfaces, Sun no claims about either
source or binary compatibility from one minor release
to another. Applications developed based on these
interfaces may not work in future minor releases.
Obsolete: Scheduled for removal after event
An Obsolete interface is supported in the current
release, but is scheduled to be removed in a future
(minor) release. When support of an interface is to
be discontinued, Sun will attempt to provide notifica-
tion before discontinuing support. Use of an Obsolete
interface may produce warning messages.
MT-Level
SunOS 5.8 Last change: 3 June 1997 5
Standards, Environments, and Macros attributes(5)
Libraries are classified into four categories which define
their ability to support multiple threads. Manual pages con-
taining routines that are of multiple or differing levels
show this within their NOTES or USAGEsection.
Safe Safe is an attribute of code that can be called from a
multithreaded application. The effect of calling into
a Safe interface or a safe code segment is that the
results are valid even when called by multiple
threads. Often overlooked is the fact that the result
of this Safe interface or safe code segment can have
global consequences that affect all threads. For
example, the action of opening or closing a file from
one thread is visible by all the threads within a pro-
cess. A multi-threaded application has the responsi-
bility for using these interfaces in a safe manner,
which is different from whether or not the interface
is Safe. For example, a multi-threaded application
that closes a file that is still in use by other
threads within the application is not using the
close(2) interface safely.
Unsafe
An Unsafe library contains global and static data that
is not protected. It is not safe to use unless the
application arranges for only one thread at time to
execute within the library. Unsafe libraries may con-
tain routines that are Safe; however, most of the
library's routines are unsafe to call.
The following table contains reentrant counterparts
for Unsafe functions. This table is subject to change
by Sun.
Reentrant functions for libc:
Unsafe Function Reentrant counterpart
ctime ctime_r
localtime localtime_r
asctime asctime_r
gmtime gmtime_r
ctermid ctermid_r
getlogin getlogin_r
rand rand_r
readdir readdir_r
strtok strtok_r
tmpnam tmpnam_r
MT-Safe
An MT-Safe library is fully prepared for multithreaded
SunOS 5.8 Last change: 3 June 1997 6
Standards, Environments, and Macros attributes(5)
access. It protects its global and static data with
locks, and can provide a reasonable amount of con-
currency. Note that a library can be safe to use, but
not MT-Safe. For example, surrounding an entire
library with a monitor makes the library Safe, but it
supports no concurrency so it is not considered MT-
Safe. An MT-Safe library must permit a reasonable
amount of concurrency. (This definition's purpose is
to give precision to what is meant when a library is
described as Safe. The definition of a Safe library
does not specify if the library supports concurrency.
The MT-Safe definition makes it clear that the library
is Safe, and supports some concurrency. This clari-
fies the Safe definition, which can mean anything from
being single threaded to being any degree of mul-
tithreaded.)
Async-Signal-Safe
Async-Signal-Safe refers to particular library rou-
tines that can be safely called from a signal handler.
A thread that is executing an Async-Signal-Safe rou-
tine will not deadlock with itself if interrupted by a
signal. Signals are only a problem for MT-Safe rou-
tines that acquire locks.
Signals are disabled when locks are acquired in
Async-Signal-Safe routines. This prevents a signal
handler that might acquire the same lock from being
called. The list of Async-Signal-Safe functions
includes:
_exit access aio_error
aio_return aio_suspend alarm
cfgetispeed cfgetospeed cfsetispeed
cfsetospeed chdir chmod
chown clock_gettime close
creat dup dup2
execle execve fcntl
fdatasync fork fstat
fsync getegid geteuid
getgid getgroups getpgrp
getpid getppid getuid
kill link lseek
mkdir mkfifo open
pathconf pause pipe
read rename rmdir
sem_post sema_post setgid
setpgid setsid setuid
sigaction sigaddset sigdelset
sigemptyset sigfillset sigismember
sigpending sigprocmask sigqueue
SunOS 5.8 Last change: 3 June 1997 7
Standards, Environments, and Macros attributes(5)
sigsuspend sleep stat
sysconf tcdrain tcflow
tcflush tcgetattr tcgetpgrp
tcsendbreak tcsetattr tcsetpgrp
thr_kill thr_sigsetmask time
timer_getoverrun timer_gettime timer_settime
times umask uname
unlink utime wait
waitpid write
MT-Safe with Exceptions
See the NOTES or USAGE sections of these pages for a
description of the exceptions.
Safe with Exceptions
See the NOTES or USAGE sections of these pages for a
description of the exceptions.
Fork1-Safe
A Fork1-Safe library releases the locks it had held
whenever fork1(2) is called in a Solaris thread pro-
gram, or fork(2) in a POSIX (see standards(5)) thread
program. Calling fork(2) in a POSIX thread program
has the same semantic as calling fork1(2) in a Solaris
thread program. All system calls, libpthread, and lib-
thread are Fork1-Safe. Otherwise, you should handle
the locking clean-up yourself (see
pthread_atfork(3THR)).
Cancel-Safety
If a multi-threaded application uses
pthread_cancel(3THR) to cancel (that is, kill) a
thread, it is possible that the target thread is
killed while holding a resource, such as a lock or
allocated memory. If the thread has not installed the
appropriate cancellation cleanup handlers to release
the resources appropriately (see
pthread_cancel(3THR)), the application is "cancel-
unsafe", that is, it is not safe with respect to can-
cellation. This unsafety could result in deadlocks due
to locks not released by a thread that gets cancelled,
or resource leaks; for example, memory not being freed
on thread cancellation. All applications that use
pthread_cancel(3THR) should ensure that they operate
in a Cancel-Safe environment. Libraries that have can-
cellation points and which acquire resources such as
locks or allocate memory dynamically, also contribute
to the cancel-unsafety of applications that are linked
with these libraries. This introduces another level of
safety for libraries in a multi-threaded program:
Cancel-Safety. There are two sub-categories of
SunOS 5.8 Last change: 3 June 1997 8
Standards, Environments, and Macros attributes(5)
Cancel-Safety: Deferred-Cancel-Safety, and
Asynchronous-Cancel-Safety. An application is con-
sidered to be Deferred-Cancel-Safe when it is Cancel-
Safe for threads whose cancellation type is
PTHREAD_CANCEL_DEFERRED. An application is considered
to be Asynchronous-Cancel-Safe when it is Cancel-Safe
for threads whose cancellation type is
PTHREAD_CANCEL_ASYNCHRONOUS. Deferred-Cancel-Safety is
easier to achieve than Asynchronous-Cancel-Safety,
since a thread with the deferred cancellation type can
be cancelled only at well-defined cancellation points,
whereas a thread with the asynchronous cancellation
type can be cancelled anywhere. Since all threads are
created by default to have the deferred cancellation
type, it may never be necessary to worry about asyn-
chronous cancel safety. Indeed, most applications and
libraries are expected to always be Asynchronous-
Cancel-Unsafe. An application which is Asynchronous-
Cancel-Safe is also, by definition, Deferred-Cancel-
Safe.
SEE ALSO
uname(1), pkgadd(1M), Intro(3), standards(5)
SunOS 5.8 Last change: 3 June 1997 9
Attachment:
libDtTerm.so.2.abi
Description: libDtTerm.so.2.abi