Introduction Introduction to the MKS Toolkit UNIX APIs	Introduction
	DESCRIPTION Standards Conformance Multithread Safety Level Error Numbers Signals Global System Variables Environment errno Values Supported Signals Windows Exceptions and Signals

---

DESCRIPTION

These reference pages describe the functions provided with the MKS Toolkit UNIX APIs. The page for each function describes the MKS Toolkit UNIX APIs implementation of that function. Any issues related to porting from a UNIX platform to Windows are discussed in the PORTING ISSUES section of that page.

This introductory page discusses some common topics, such as standards conformation, error code mapping, signal mapping, global system variables and the environment.

Standards Conformance

Each page lists the standard to which the MKS Toolkit UNIX APIs implementation was written. For most pages, the standard is one of the following:

MKS Toolkit UNIX APIs Extension 

A MKS Toolkit UNIX APIs extension to the standard APIs.

UNIX 98 

The Single UNIX Specification, Version 2, from The Open Group.

POSIX.1 (1996) 

The 1996 re-issue of the ISO/IEC 9945-1 standard (also ANSI/IEEE Std 1003.1), for the Portable Operating System Interface (Part 1: System Application Programming Interface). This encompasses the earlier 1988 release of POSIX.1, with the subsequently-standardized real-time and threading interfaces added.

POSIX.2 (1992) 

ANSI/IEEE Std 1003.2, for the Portable Operating System Interface (Part 2: Shell and Utilities).

ANSI/ISO 9899-1990 

The American National Standard for Programming Languages — C. This is the 1990 re-issue of the ANSI C language standard for alignment with the international standards body.

ANSI/ISO 9899-1990/AM 1-1995 

The American National Standard for Programming Languages — C — Amendment 1: C Integrity. This amendment to the C language standard specifies extensions to the language and library to support internationalized applications.

4.4BSD 

The 4.4BSD-Lite2 implementation of UNIX from The University of California at Berkeley.

SVR3 or SVR4 

Taken from the documentation for the System V Release 3 or System V Release 4 implementations of UNIX from AT&T.

The phrase "with exceptions" is used to indicate that the NuTCRACKER Platform implementation diverges from the listed standard, as discussed in the DESCRIPTION or PORTING ISSUES section of the reference page.

Multithread Safety Level

Each page lists the multithread safety level of the functions described on that page. The level is one of the following:

Unsafe: 

The function uses global or static state that is not protected. It is not safe to use unless the application ensures that only one thread at a time executes the function.

MT-safe: 

The function is prepared for multithreaded access. A multithreaded application can safely call the function from multiple threads; the function will provide any necessary concurrency controls

Async-signal-safe: 

An async-signal-safe function is one that can be safely called from a signal handler. A thread that is executing an async-signal-safe function will not deadlock with itself if interrupted by a signal. Calling any function that is not marked as async-signal-safe from a signal handler results in undefined program behavior.

Async-cancel-safe: 

An async-cancel-safe function is one that can be safely called while asynchronous thread cancellation is enabled (refer to pthread_cancel() for more information on thread cancellation). Calling any function that is not marked as async-cancel-safe while asynchronous thread cancellation is enabled results in undefined program behavior.

Any exceptions to these definitions is noted for each function.

Error Numbers

For those calls that set errno (traditional UNIX system calls), the NuTCRACKER Platform maps the Windows error code to an errno value, where possible and appropriate. In the cases where it is not possible or appropriate to map the Windows error code, the NuTCRACKER Platform sets errno to the negative of the Windows error code. You can retrieve the Windows error string using the perror command or the perror() or strerror() functions. Table 1: Windows Error Code to errno Value Mapping shows the mapping of Windows error code to errno value.

Signals

Table 2: Supported Signals lists the set of signals supported by the NuTCRACKER Platform, and the default actions that are taken when no signal handler is installed. Refer to the documentation for the signal-related functions for more details, as well as to the Signals discussion in the Operating System Concepts chapter of the MKS Toolkit UNIX to Windows Porting Guide.

The NuTCRACKER Platform also maps Windows exceptions to UNIX signals. You may need to know the mapping to configure your debugger correctly. Table 3: Windows Exception to Signal Mapping shows the mapping of Windows exceptions to signal numbers.

Global System Variables

The NuTCRACKER Platform defines the standard UNIX global system variables such as environ, errno, and optarg. You must not declare these variables in your code: always include the appropriate MKS Toolkit UNIX APIs header file. Reference pages for each of the supported global variables can be found in the Miscellaneous section.

Environment

The NuTCRACKER Platform supports a standard UNIX environment which is discussed in the Environment Variables chapter of the MKS Toolkit UNIX to Windows Porting Guide. Using environment variables in NuTCRACKER Platform-ported applications is strongly discouraged, except for debugging purposes. If your application depends on an environment variable and you deploy the application on a target machine, problems could arise if the user installs another NuTCRACKER Platform-ported application which overrides the setting of the environment variable that your application uses.

errno Values

Table 1: Windows Error Code to errno Value Mapping

Supported Signals

Table 2: Supported Signals

Windows Exceptions and Signals

Table 3: Windows Exception to Signal Mapping