POSIX 1.b Migration Guide

Introduction

POSIX.1b Description

The POSIX.1b standard encompasses real-time extensions to the POSIX.1 standard. POSIX.1b functionality includes shared memory, messages, real-time signals, clocks and timers, scheduling, semaphores, memory locking, synchronized I/O, and asynchronous I/O.

This Guide acts as a tutorial and describes the differences in compiler flags between POSIX.4 Draft 9 and POSIX.1b.

Note: Throughout the example code, error checking is not performed; function calls for which error checking is not executed are assumed to be successful. The reader should not accept this as a programming style. Error checking is omitted in order to keep this document at a reasonable size and to place emphasis on the migration-the purpose of this document. In order to simplify the examples, obvious include files (i.e., <stdio.h>) have not been shown.

For a guide to POSIX.1b programming style with LynxOS, please refer to the
on-line example programs provided with the distribution and to other
related documents.

The following definitions clarify how the various POSIX specifications interrelate:

POSIX.1 The basic operating system standard, also known as POSIX 1003.1 - POSIX.1 was approved in 1988.

POSIX.1b Amendments to POSIX.1 for real-time systems - POSIX.1b was approved in 1993. Also known as POSIX.4 Draft 14.

POSIX.4a (now POSIX.1c) Amendments to POSIX.1 defining thread primitives - thread creation, synchronization, destruction, etc. The POSIX.4 committee decided that keeping threads in the POSIX.1b standard would delay approval, due to the complexity of the threads issue. Also, a separate POSIX specification for the threads interface allows vendors the option to exclude the other real-time support, which POSIX.1b requires. POSIX.4a Draft 8 was approved and renamed POSIX.1c. LynxOS supports POSIX.4a Draft 4.

Draft 9 In this Guide, "Draft 9" refers to Draft 9 of the POSIX 1003.4 standard. Draft 9 is an intermediate draft leading to POSIX.1b. Draft 9 has been the target for LynxOS since version 2.0. However, LynxOS event handling is based on Draft 10.

Draft 10 The next intermediate draft after Draft 9, which, among other things, made some important and useful changes to event handling

The POSIX support in LynxOS has been targeted (mostly) for Draft 9 of the then-evolving POSIX.4 standard, and for the approved POSIX.1 standard. POSIX.4 changed significantly between Draft 9 and Draft 14; Draft 14 is the version which was approved as the POSIX.1b standard.

The POSIX.1 standard, when amended by POSIX.4, became the POSIX.1b standard, and included all of the facilities specified in both documents. LynxOS meets the POSIX.1b standard, and also supports Draft 4 of the POSIX.4a standard.

In this Guide, "POSIX.1b," means the POSIX.1b standard as approved by the IEEE. "Draft num" refers to the num draft of the POSIX.4 standard.

Overview of Major Changes

• The compilation environment now defaults to POSIX.1b, rather than POSIX.4 Draft 9 (referred to as "Draft 9" or "P4D9"). To invoke Draft 9 functionality, you must specify the option mposix4d9 when compiling an application. For more information, see the LynxOS Release Notes.

• Significant library structure changes have been made in this release of LynxOS. Please see "Library Structure and Compiler Option Changes" in this chapter for more information.

• It is not possible to mix the Draft 9 and POSIX.1b standard versions in the same application. Users must choose between the two with compile-time options. LynuxWorks recommends using the POSIX.1b standard for all future development.

• Not all Draft 9 features have corresponding equivalents in POSIX.1b. Some features have been discontinued.

• POSIX.1b does not include real-time files. Draft 9 programs using this facility have no migration equivalent in POSIX.1b. Draft 9 real-time file support still exists, and LynuxWorks will continue to support this interface as a proprietary feature in future releases.

• Message queues have changed significantly from Draft 9 to POSIX.1b. Some facilities, such as determining the ID of the sender of a message, and buffer management, are no longer available. The new message queue support is streamlined, with better performance.

• The events facility from Draft 9 has been abandoned. The equivalent to this interface is the real-time signals facility.

• Semaphores have changed from binary semaphores in Draft 9 to counting semaphores in POSIX.1b.

• Draft 9 support for named semaphores, shared memory, and message queues makes use of a file system. LynxOS's POSIX.1b support uses simple strings as names for these objects. There is no
  file system involvement.

• There are new facilities in POSIX.1b which do not exist in Draft 9. The mmap facility (which allows files, devices, and shared memory objects to be mapped into memory) is new. The mmap facility works only for shared memory objects in the first release.

Library Structure and Compiler Option Changes

In this release of LynxOS, both POSIX.1b and POSIX.4 Draft 9 (referred to as "4D9") are supported. However, POSIX.1b is now the default compilation environment. This change that involved modifying the library structure and compile time options from previous LynxOS releases.

Library Structure Changes

To use the POSIX library routine calls, compiler command line instructions had to contain the mposix switch (for gcc) or the X switch (for cc). These options instructed the linker to link with lc_p.

The POSIX library routines for POSIX.1a and POSIX.1b have been merged into the library libc.a. The libc.a library exists in /lib and /lib/thread (for multithreads). Two new libraries have also been added:

• liblynx.a
  Contains some LynxOS-specific library calls (not conforming to any standard)

• libposix4d9.a
  Contains support for POSIX.4 Draft 9

Compiler Option Changes

In this new structure, to compile an application with 4D9 functionality, you must compile with the mposix4d9 option. This option signals the compiler to define D__POSIX4_D9__ and to link with the libposix4d9.a library. Thus, you do not need to change 4D9 source code with the new library structure, but you will need to recompile with the mposix4d9 option. Also, you cannot mix 4D9 functionality with POSIX.1b in a single application. Your application may fail to link or may exhibit unpredictable results at run-time.

The following table summarizes the changes to the compiler command
line options.

Compiler Option Changes in LynxOS  

POSIX Specification	LynxOS
	cc (x86)	gcc
POSIX 1003.1 C Language Standard	Default	Default
POSIX 1003.1b Final version of 1003.4	Default	Default
POSIX 1003.4a Draft 4 Thread Extensions	m	mthreads
POSIX 1003.4 Draft 9 Real-Time Extensions	mposix4d9	mposix4d9

New Library Structure Issues

Name Conflicts Between liblynx.a and libc.a

With the library reorganization, it has been necessary to remove from the library libc.a some non-POSIX functions that have the same names as POSIX functions. These functions are now contained in the liblynx.a library and each has an interface that is either LynxOS-specific or is BSD-compatible.

The following is a description of each of these functions and how its interface differs from the POSIX interface:

1. getgroups()

This function differs in its arguments. The POSIX version (now in libc.a) has the following prototype:

int getgroups(int, gid_t *);

The LynxOS version (now in liblynx.a) is BSDcompatible:

int getgroups(int *, gid_t *);

2. getpgrp()

This function differs in its arguments. The POSIX version (now in libc.a) has the following prototype:

pid_t getpgrp(void);

The LynxOS version (now in liblynx.a) is BSDcompatible:

pid_t getpgrp(pid_t);

3. LynxOS semaphore functions

These functions include sem_count(), sem_delete(), sem_get(), sem_nsignal(), sem_reset(), sem_signal(), and sem_wait(). Only one of these functions, sem_wait(), has a name conflict with POSIX, but because the functions are expected to be used as a group, the whole set has been moved to liblynx.a. The POSIX version of sem_wait() (now in libc.a) has the following prototype:

int sem_wait(sem_t *);

The LynxOS version (now in liblynx.a) is LynxOS-specific:

int sem_wait(int);

4. sigaction()

This function differs in its functionality. When the POSIX version (in libc.a) is used to set up a signal handler for a particular signal, and that signal subsequently interrupts a system call in progress, then after returning from the handler, the system call aborts and errno sets
to EINTR.

When the LynxOS version (now in liblynx.a) is used in the same fashion, and the signal subsequently interrupts a system call in progress (as above), then after returning from the handler, the system call is resumed where it has been left off.

Either version can be made to mimic the behavior of the other with the appropriate flag. The POSIX version can be made to behave like the LynxOS version by using the SA_NOABORT flag. The LynxOS version can be made to behave like the POSIX version by using the SA_ABORT flag.

BSD behavior is not supported by LynxOS. BSD differs from both POSIX and LynxOS in that under BSD, a system call is restarted after it is interrupted by a signal.

Note: Please see Appendix A, "Functions Callable from Signal Handlers" for a list of functions, including sigaction(), required in POSIX.1b to be callable by signal handlers. This is to prevent corruption of the state of a library or any other subtle failure.

5. signal()

POSIX does not specify the signal() function, and strictly adhering POSIX applications should not use it. However, LynxOS does provide a "POSIX-like" signal() in libc.a that can be used if necessary.

The LynxOS version of signal() (now in /lib/liblynx.a) differs in its functionality the same way that sigaction() does (see Item 4, above). Unlike sigaction(), however, there are no flags passed to signal(), so there is no way to make the "POSIX-like" version mimic LynxOS behavior or vice-versa.

6. sleep(), susleep(), usleep()

LynxOS provides two versions of these functions. One is LynxOS-specific and is similar to BSD sleep(). (For more information about this version, see the man page for sleep().)

The other version complies with the POSIX.1 standard. The functions susleep() and usleep() are not specified in the POSIX.1 standard, but because they are closely related to sleep(), LynxOS provides two separate versions of them as well, found in libc.a and liblynx.a.

Of the above functions, the ones users need to be most concerned about are getgroups(), getpgrp(), and the LynxOS semaphore functions, because using unintended versions of these functions always produces incorrect results.

For getgroups(), the POSIX version provides the same level of functionality as the LynxOS version, so it may be easier to convert the source code to the POSIX version. For getpgrp(), the LynxOS version provides more functionality than the POSIX version, because it allows the user to obtain the process group of a given process ID. If this usage is not needed, however, then users may consider converting the code to the POSIX version.

For sigaction() and signal(), the differences are less noticeable, and in many cases do not matter. When converting to the POSIX version, be aware that using the POSIX version usually requires more error checking around system calls to handle the case when they are interrupted by a signal handler.

For sleep(), the differences between the LynxOS and POSIX versions often do not matter. Converting from LynxOS sleep() to POSIX sleep() depends on how a given application uses this function.

Identifying Function Usage in Applications

To identify the usage of these functions in executables or object files, use the nm and grep utilities as follows:

$ nm file | grep -w function

For an executable, the output line from the command above should show a T, meaning external text symbol. For an object file, it should show a U, meaning unresolved symbol.

To identify the function usage in source files, use the grep utility.

Other Functions in liblynx.a

The following functions are temporarily included in liblynx.a as well:

lsbrk()

mkcontig()

smem_create()

smem_get()

smem_remove()

vmtopm()

Users may need to link with the liblynx.a library if their applications use these functions, even though this has not been necessary in previous releases.

Using Parts of liblynx.a in an Application

Sometimes an application needs to use a mixture of the LynxOS and POSIX versions of functions discussed in this section (for example, needs LynxOS getpgrp(), but needs POSIX sem_wait()). To achieve this, users must extract the object files that contain the needed LynxOS functions from liblynx.a and link with these objects directly instead of liblynx.a. Alternatively, users may put the extracted objects into their own smaller library. Users should then link the application with this smaller library instead of liblynx.a.

Note: Some of the objects in liblynx.a contain more than one function (for example sleep(), susleep(), and usleep() are combined into one object), so it is not possible to use the LynxOS version of one such function and the POSIX version of another.

Other General Changes

Refer to the sysconf() man pages for a list of new parameters which can be passed to the sysconf() function. Also, refer to the pathconf() and fpathconf() man pages for a list of new parameters that can be passed to these two functions.

The lists of run-time invariant values and compile-time symbolic constants have changed. Due to their length, these lists are not reproduced here. Refer to Table 2.5 and Table 2.10 of the POSIX.1b specification (IEEE 1003.1b) for these lists.

Changes in Errno Values  

Draft 9	POSIX.1b
EINPROG	EINPROGRESS
EFTYPE	EINVAL
No Equivalent	EBADMSG
No Equivalent	EMSGSIZE
EFAIL	No Equivalent
ENWAIT	No Equivalent

Change in Compile Time Symbolic Constant  

Draft 9	POSIX.1b
_POSIX_BINARY_SEMAPHORES	_POSIX_SEMAPHORES

LynuxWorks, Inc. 855 Branham Lane East San Jose, CA 95138 http://www.lynuxworks.com 1.800.255.5969