Chapter 1 Introduction to the API

A goal of Sun Microsystems is to define the architectural interfaces of the Solaris(TM) operating environment. There are two reasons:

• The system interface is an effective "contract" with customers. It is completely specified in Solaris 8 Reference Manual Collection.

• The interfaces in a particular version of the product are preserved in future versions of the product, which maintains upward compatibility in subsequent releases of the Solaris operating environment.

Programming Interface

Solaris offers many kinds of "interfaces", such as the programming interface, elements of the user interface, protocols, and rules about naming and the locations of objects in the file system. One of the most important interfaces to the system is the programming interface -- the one offered to developers. The programming interface has two major parts: one seen by developers of applications, which is the API, and one seen by developers of system components, such as device drivers and platform support modules, which is the SPI (system programming interface).

Each programming interface to Solaris is also "visible" to the developer at two levels: source level and binary. When you see the acronyms API and SPI, this indicates the source level programming interface to the system. The terms Application Binary Interface (ABI) and System Binary Interface (SBI) indicate the binary interfaces corresponding to the respective source level programming interfaces. (Because the phrase "the ABI" can be confused with other binary interfaces, the "Solaris ABI" is refered to only by name.)

Interface Functions

The SunOS 5.0 through 5.8 functions discussed in this manual are the interfaces between the services provided by the kernel and application programs. The functions described in man pages section 2: System Calls, man pages section 3: Basic Library Functions, man pages section 3: Curses Library Functions, man pages section 3: Extended Library Functions, man pages section 3: Library Interfaces and Headers, man pages section 3: Networking Library Functions, man pages section 3: Threads and Realtime Library Functions, are an application's interface to the SunOS 5.0 through 5.8 operating system. These functions are how an application uses facilities such as the file system, interprocess communication primitives, and multitasking mechanisms. This manual is one of a set that describe major elements of the API. Other manuals in the set are STREAMS Programming Guide, Multithreaded Programming Guide, Network Interface Guide, and so forth.

When you use the library routines described in sections 2 and 3 of the Solaris 8 Reference Manual Collection, the details of their implementation are transparent to the program. For example, the function read underlies the fread implementation in the standard C library.

A C program is automatically linked to the invoked functions when you compile the program. The procedure might be different for programs written in other languages. See the Linker and Libraries Guide for more information.

Libraries

Solaris provides both static and dynamic implementations of libraries. Static libraries do not provide an interface; they provide only an implementation. The application programming interface of Solaris is made available to developers through the shared libraries (also called shared objects). In the runtime environment, a dynamic executable and shared objects are processed by the runtime linker to produce a runnable process. The official API to the system is the interface between an application and the dynamic shared libraries.

Static Libraries

The traditional, static, implementation of libraries (.a files or archives), do not separate the application programming interface from its implementation (the contents of the library). When an application is linked to a static library, the object code that implements that library is bound into the executable object that results from the build. The source-level programming interface to the library can be preserved, but the application must be relinked to produce an executable that runs on a later version of an operating system. Future binary compatibility is assured only when shared libraries are used.

The presence of static libraries is a historical artifact and there is no mechanism to define their interfaces in a way that is separate from their implementation. For this reason, use of static libraries should be avoided by new applications.

Dynamic libraries

Unlike the static libraries, shared libraries do separate the application programming interface from the implementation. The interface is bound to an implementation of the library only at runtime. This allows SMI to evolve the library's implementation - such as changing internal interfaces, while maintaining the API and preserving binary compatibility with applications built against it.

Interface Taxonomy

The interface taxonomy classifies commitment level of an interface. The commitment level identifies who can, or how to, use the interface. Definitions:

Standard Classification

Standard interfaces are those whose specification is controlled by a group outside of Sun. This includes standards such as POSIX and ANSI C, as well as industry specifications from groups such as X/Open, the MIT X-Consortium, and the OMG.

Public Classification

These are interfaces whose specification is completely under Sun Microsystem's control. The specification of these interfaces and will remain compatible with the published specification.

Obsolete Classification

An interface no longer in general use. An existing interface can be downgraded from some other status (such as Public or Standard) to Obsolete through a standard program to communicate the change in commitment to customers.

A change in commitment requires one year's notice to the customer base and the Sun product development community of the intended obsoleting of the interface. A full year must elapse before delivering a product that contains a change incompatible with the present status of the interface.

Acceptable ways to notify customers includes letters to customers on support contracts, release notes or product documentation, or announcements to customer forums appropriate for the interface in question.

The notice of obsolescence is considered to be "public" information in that it is freely available to the customers. This should not require specific actions to "publish" the information, such as press releases or similar forms of publicity.