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

---

DESCRIPTION

These reference pages describe the functions provided with the PTC MKS Toolkit UNIX APIs. The page for each function describes the PTC 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, the environment, and clocks and timers.

Standards Conformance

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

PTC MKS Toolkit UNIX APIs Extension 

A PTC MKS Toolkit UNIX APIs extension to the standard APIs.

UNIX 98 

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

UNIX 03 

The Single UNIX Specification, Version 3, 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 PTC 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 PTC 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 PTC 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.

Clocks and Timers

The NuTCRACKER Platform implements a complete set of POSIX clocks and timers. These clocks include:

CLOCK_MONOTONIC 

Returns seconds since the epoch (January 1, 1970, 12:00 a.m.) and has one second resolution. This clock can be used with the clock_nanosleep() function.

CLOCK_REALTIME 

Has a resolution of 100 nanoseconds. This clock can be used with the clock_nanosleep() function and is the only one that can be adjusted with the clock_settime(). It is also the only clock that may be used as the basis for a timer.

CLOCK_PROCESS_CPUTIME 

Is based on the Win32 GetProcessTimes() API and has millisecond accuracy.

CLOCK_THREAD_CPUTIME_ID 

Is based on the Win32 GetThreadTimes() API and has millisecond accuracy.

CLOCK_HIGHRES 

Is a non-standard clock that gives you access to the Windows Performance Counters. Its resolution depends upon the speed of your processor.

As mentioned earlier, only CLOCK_REALTIME may be used as the basis for a timer. Timers are implemented in terms of Windows waitable timers. The resolution on the first interval of such a timer is 100 nanoseconds and the resolution of the repeat interval is milliseconds.

Note:

Windows waitable timers sometimes expire early for the first interval (which is compensated for such that you never receive a signal too early) and not as regularly as one might imagine for the remaining intervals. As a result, if you try to count the number of signal overruns (timer_getoverruns()) this implementation delivers, you may find it to be fewer than you might have expected over a given interval.

Here is an example of using CLOCK_HIGHRES to measure time differences accurately:

#define _XOPEN_SOURCE 600
#include <stdio.h>
#include <sys/types.h>
#include <time.h>
#include <winnutc.h>

/* A simple routine to convert struct timespec to a tick count in int64_t */
int64_t Convert(struct timespec *ts)
{
	LARGE_INTEGER li;

	li.HighPart = ts->tv_sec;
	li.LowPart = ts->tv_nsec;
	return li.QuadPart;
}

/* Convert ticks to a count of the number of 100nano seconds */
u_int64_t TicksTohNanoSeconds(int64_t ticks, int64_t frequency)
{
	return (u_int64_t)((((double)ticks/(double) frequency)*10000000.0)+0.5);
}

/* A routine to print out the time difference in nanoseconds */
void difftm(struct timespec *tm1, struct timespec *tm2)
{
	int64_t start, end, elapsed;
	int64_t frequency;
	struct timespec res;

	start = Convert(tm1);
	end = Convert(tm2);
	clock_getres(CLOCK_HIGHRES, &res);

	frequency = Convert(&res);
	start = TicksTohNanoSeconds(start, frequency) * 100;
	end = TicksTohNanoSeconds(end, frequency) * 100;
	elapsed = end - start;

	printf("%qu\n", elapsed);
}

void main(void)
{
	struct timespec tm1, tm2;
	struct timespec tt1, tt2;

	tt1.tv_sec = 0;
	tt1.tv_nsec = 40000000;

	clock_gettime(CLOCK_HIGHRES, &tm1);
	clock_nanosleep(CLOCK_REALTIME, 0, &tt1, &tt2);
	clock_gettime(CLOCK_HIGHRES, &tm2);

	difftm(&tm1, &tm2);
}

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

---

PTC MKS Toolkit 10.4 Documentation Build 39.