Chapter 1 Introduction

POSIX 1.c Migration Guide

1c

Introduction

POSIX.1c Description

The POSIX.1c standard encompasses the threads option to the POSIX.1standard. POSIX.1c functionality includes thread management, scheduling, and cancellation, thread-specific data, fork, signal handling, mutexes, and condition variables.

This guide describes the differences between compiler flags in POSIX.4a Draft 4 and POSIX.1c.

For a guide to POSIX.1c programming style with LynxOS, please refer to the online example programs provided with the distribution and other documents.

The following definitions clarify how the various POSIX specifications interrelate.

POSIX.1 This is the basic operating system standard, also known as POSIX 1003.1. The current version of POSIX.1 was approved in 1996, and encompasses the 1988 version, as well as the final versions of POSIX.1b and POSIX.1c.

POSIX.1b This contains amendments to POSIX.1 for real-time systems. POSIX.1b was approved in 1993. It is also known as POSIX.4 Draft 14.

POSIX.1c (previously POSIX.4a)

Contains amendments to POSIX.1 defining thread primitives - thread creation, synchronization, scheduling, 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 that POSIX.1b requires. POSIX.4a Draft 8 was approved and renamed POSIX.1c.

LynxOS is compliant with the ISO/IEC 9945-1:1996
POSIX.1c standard.

In this guide, the term POSIX.1c refers to the Threads Option of the
POSIX.1 standard.

Note: Throughout the code examples in this document, 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 concise and emphasize migration. In order to simplify the examples, obvious include files (e.g., <stdio.h>) have not been shown.

Overview of Major Changes

The compilation environment now defaults to POSIX.1c, rather than POSIX.4a. To invoke POSIX.4a functionality, you must specify the option mthreads-pre1c when compiling your application.

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

It is not possible to mix the POSIX.4a and POSIX.1c standards in the same application. You must choose between the two with compile-time options. LynuxWorks recommends using the POSIX.1c standard for all future development.

Not all POSIX.4a features have corresponding equivalents in POSIX.1c. Some features have been discontinued.

There are new facilities in POSIX.1c not contained in POSIX.4a. For example, threads may be created in a detached state and can register fork handlers; mutexes and condition variables now have attributes and may be statically initialized.

Error reporting has been significantly revised. In POSIX.4a, pthreads library functions return 0 for success, or -1 to indicate an error and set the errno global to the specific error number. In POSIX.1c, most functions return 0 for success or the error number directly.

Library Structure & Compiler Option Changes

In this release of LynxOS, both POSIX.1c and POSIX.4a are supported. However, POSIX.1c is now the default compilation environment. This change has involved modifying the library structure and compile time options in LynxOS.

Library Routiness

All POSIX.1 library routines, including those for POSIX.1c, are merged into the library libc.a. This library exists in /lib and /lib/thread (for multithreads).

LynxOS includes a backward-compatibility library:

libposix-pre1c.a Contains support for POSIX.4a

Compiler Options Changes

POSIX.1c is the default for LynxOS. To compile an application with POSIX.4a functionality, you must compile with the mlegacy-threads option. This option signals the compiler to define D_THREADS_POSIX4ad4 and to link with the libposix-pre1c.a library. Thus, you do not need to change POSIX.4a source code, but you do need to recompile with the
mlegacy-threads option.

Also, you cannot mix POSIX.4a functionality with POSIX.1c 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 options.

Compiler Option Changes in LynxOS 4.0

POSIX Specification

LynxOS

gcc

POSIX 1003.1 C Language Standard

Default

POSIX 1003.1b Final version of 1003.4

Default

POSIX 1003.4a Draft 4 Thread Extensions

mlegacy-threads

POSIX.1c Final standard

mthreads

Note: If you specify the option mposix when compiling an application with either cc (x86 only) or gcc, the compiler displays an error message and aborts the compile. You must change compiler directives to invoke the options as listed in the table above.

Updating Applications

If you previously used mthreads to compile applications, there are two alternatives for updating to the new structure:

Make code POSIX.1c-compliant.

If compiling POSIX.4a-compliant code, change all mthreads compilation switches to mlegacy-threads.

Here are some simple shell scripts you can use to make these needed changes to your environment. The scripts assume that bash is the current shell.

To change mthreads to mlegacy-threads in all Makefiles
named Makefile:

bash$ for f in `find . -name Makefile -print`
> do
> cp $f $f.orig
> sed 's/-mthreads/-mlegacy-threads/' $f.orig > $f
> done

Other General Changes

Refer to the sysconf() man page for a list of new parameters that 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 included here. Refer to Table 2.5 and Table 2.10 of the POSIX.1 specification (ISO/IEC 9945-1:1996) for these lists.

Note: Throughout the code examples in this document, 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 concise and emphasize migration. In order to simplify the examples, obvious include files (e.g., <stdio.h>) have not been shown.

Compiler Option Changes in LynxOS 4.0
POSIX Specification	LynxOS gcc
POSIX 1003.1 C Language Standard	Default
POSIX 1003.1b Final version of 1003.4	Default
POSIX 1003.4a Draft 4 Thread Extensions	mlegacy-threads
POSIX.1c Final standard	mthreads

Note: If you specify the option mposix when compiling an application with either cc (x86 only) or gcc, the compiler displays an error message and aborts the compile. You must change compiler directives to invoke the options as listed in the table above.

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