This section provides an overview of the programming interfaces available to applications developed for ChorusOS systems. The programming interface may differ from one application to another, depending on:
Application type - whether it is a POSIX process, a ChorusOS actor, or an embedded actor.
Execution mode - whether running in user or supervisor space.
Execution structure - whether it contains one or more threads.
Library names used in the ChorusOS operating system adhere to the following conventions with regard to their suffixes:
.u.a | These static libraries can only be used to build actors that will be loaded in a user address space. |
.s.a | These static libraries can only be used to build actors that will be loaded in the supervisor address space. |
.a | These static libraries can be used to build either user or supervisor actors or processes. |
.so |
These libraries are shared or dynamic and can be used to build either user or supervisor actors or processes. |
All header file and library pathnames listed in the following subsections are related to the installation path of your ChorusOS system, typically, install_dir/chorus-target.
The programming environment of ChorusOS actors consists of the following interfaces:
Microkernel API
Private Data API
Standard-C API
Console I/O API
The ChorusOS actor APIs enable you to build two kinds of applications:
Embedded actors
Standard actors
Embedded user actors use the embedded library:
kernel/lib/embedded/libebd.u.a
Embedded supervisor actors use the embedded library:
kernel/lib/embedded/libebd.s.a
Standard actors not linked to the embedded library use the library:
os/lib/libc.a
Note that this is the same library used by POSIX processes.
The programming environment of POSIX processes includes the standard POSIX APIs and a number of POSIX extensions that can be accessed directly by any process.
Certain libraries (libc and libstdc++, for example) are implicitly provided when you select the appropriate Imakefile rule (see "The imake Environment"). Other libraries must be explicitly stated in the Imakefile.
The libraries to which a process has access may be either static (.a) or shared (.so). Whether the process uses a static or shared library depends on the rule selected in the Imakefile. Shared processes use libc.so.
The following sections describe all libraries that can be used by a process. Note that the libraries can be accessed by either a user or supervisor actor or process.
The os/lib/libc.a and os/lib/libc.so libraries are automatically included by any process or actor and include the following APIs:
Private Data API
LAP API
MIPC API
IPC API
Standard C API
POSIX I/O API
POSIX Network API
C++ actors or processes have access to the same APIs through the C++ library (os/lib/libstdc++.a).
The following libraries can be accessed by either a supervisor or user process or actor. These libraries must be explicitly included in your Imakefile and contain the full pathname.
To add a library to an Imakefile, $(OS_DIR)/lib/lib<libraryname>.a or $(OS_DIR)/lib/lib<libraryname>.so to the relevant rule.
Table 5-1 Static libraries (.a)
Using the libsysevent.a library dictates that you use the libnvpair.a, librpc.a and libpthreads.a libraries too.
Library name and path |
Description |
---|---|
os/lib/libldap.so |
LDAP library |
os/lib/libnsl.so |
Network services library (symbolic link to libresolv.so) |
os/lib/libpam.so |
Interface library for PAM |
os/lib/libpthreads.so |
POSIX pthread library |
os/lib/libresolv.so |
Network services library |
os/lib/librpc.so |
RPC library |
The extensions to the standard POSIX APIs can be divided into two groups:
Restricted microkernel calls
POSIX-like extended services
The restricted microkernel calls are directly available from the libc.a or libc.so libraries and include the following APIs:
MIPC
IPC
LAP
To add POSIX-like extended services, you must specify the required library in your Imakefile. These services include the following APIs:
Blackbox
SysEvent
LDAP
The embedded libraries (libebd.u.a and libebd.s.a) and the libc.a and libstdc++.a libraries have been made thread-safe to support multithreaded actors. Multithreading is managed by the library in the following way:
Protecting shared variables with mutexes.
Using the Private Data library to maintain private variables per thread (for errno management, see the next section).
Defining errno as a single global variable for an actor is not suitable for multithreaded actors. Situations can arise where a thread, when examining errno on return from a failed system call, concludes that the call failed for the wrong reason (because the global errno was changed by another system call in another thread in the meantime). Some programs also test errno rather than system call return values to detect errors.
To prevent global errno changes by another system call, the header file errno.h (which is exported by the POSIX environment) should be included in any source file using errno. This will result in a separate value of errno for each thread.
Routines implemented in the mathematical API can be used by actors that use the microkernel API and by processes that use the POSIX API.
The mathematical API is located in kernel/lib/libm.
The mathematical library is libm.a.