API Introduction

Introduction to the MKS Toolkit UNIX APIs 

Introduction


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

Windows Error Code errno
ERROR_ACCESS_DENIED EACCES
ERROR_ACCOUNT_DISABLED EACCES
ERROR_ACCOUNT_RESTRICTION EACCES
ERROR_ALREADY_ASSIGNED EBUSY
ERROR_ALREADY_EXISTS EEXIST
ERROR_ARITHMETIC_OVERFLOW ERANGE
ERROR_BAD_COMMAND EIO
ERROR_BAD_DEVICE ENODEV
ERROR_BAD_DRIVER_LEVEL ENXIO
ERROR_BAD_EXE_FORMAT ENOEXEC
ERROR_BAD_FORMAT ENOEXEC
ERROR_BAD_LENGTH EINVAL
ERROR_BAD_PATHNAME ENOENT
ERROR_BAD_PIPE EPIPE
ERROR_BAD_UNIT ENODEV
ERROR_BAD_USERNAME EINVAL
ERROR_BROKEN_PIPE EPIPE
ERROR_BUFFER_OVERFLOW ENOMEM
ERROR_BUSY EBUSY
ERROR_BUSY_DRIVE EBUSY
ERROR_CALL_NOT_IMPLEMENTED ENOSYS
ERROR_CRC EIO
ERROR_CURRENT_DIRECTORY EINVAL
ERROR_DEVICE_IN_USE EBUSY
ERROR_DIR_NOT_EMPTY EEXIST
ERROR_DIRECTORY ENOENT
ERROR_DISK_CHANGE EIO
ERROR_DISK_FULL ENOSPC
ERROR_DRIVE_LOCKED EBUSY
ERROR_ENVVAR_NOT_FOUND EINVAL
ERROR_EXE_MARKED_INVALID ENOEXEC
ERROR_FILE_EXISTS EEXIST
ERROR_FILE_INVALID ENODEV
ERROR_FILE_NOT_FOUND ENOENT
ERROR_FILENAME_EXCED_RANGE ENAMETOOLONG
ERROR_GEN_FAILURE EIO
ERROR_HANDLE_DISK_FULL ENOSPC
ERROR_INSUFFICIENT_BUFFER ENOMEM
ERROR_INVALID_ACCESS EINVAL
ERROR_INVALID_ADDRESS EFAULT
ERROR_INVALID_BLOCK EFAULT
ERROR_INVALID_DATA EINVAL
ERROR_INVALID_DRIVE ENODEV
ERROR_INVALID_EXE_SIGNATURE ENOEXEC
ERROR_INVALID_FLAGS EINVAL
ERROR_INVALID_FUNCTION ENOSYS
ERROR_INVALID_HANDLE EBADF
ERROR_INVALID_LOGON_HOURS EACCES
ERROR_INVALID_NAME ENOENT
ERROR_INVALID_OWNER EINVAL
ERROR_INVALID_PARAMETER EINVAL
ERROR_INVALID_PASSWORD EPERM
ERROR_INVALID_PRIMARY_GROUP EINVAL
ERROR_INVALID_SIGNAL_NUMBER EINVAL
ERROR_INVALID_TARGET_HANDLE EIO
ERROR_INVALID_WORKSTATION EACCES
ERROR_IO_DEVICE EIO
ERROR_IO_INCOMPLETE EINTR
ERROR_LOCK_VIOLATION ETXTBSY
ERROR_LOCKED EBUSY
ERROR_LOGON_FAILURE EACCES
ERROR_MAPPED_ALIGNMENT EINVAL
ERROR_META_EXPANSION_TOO_LONG E2BIG
ERROR_MORE_DATA EPIPE
ERROR_NEGATIVE_SEEK ESPIPE
ERROR_NO_DATA EPIPE
ERROR_NO_MORE_SEARCH_HANDLES EIO
ERROR_NO_PROC_SLOTS EAGAIN
ERROR_NO_SUCH_PRIVILEGE EACCES
ERROR_NOACCESS EFAULT
ERROR_NONE_MAPPED EINVAL
ERROR_NOT_ENOUGH_MEMORY ENOMEM
ERROR_NOT_READY ENODEV
ERROR_NOT_SAME_DEVICE EXDEV
ERROR_OPEN_FAILED EIO
ERROR_OPERATION_ABORTED EINTR
ERROR_OUTOFMEMORY ENOMEM
ERROR_PASSWORD_EXPIRED EACCES
ERROR_PATH_BUSY EBUSY
ERROR_PATH_NOT_FOUND ENOTDIR
ERROR_PIPE_BUSY EBUSY
ERROR_PIPE_CONNECTED EPIPE
ERROR_PIPE_LISTENING EPIPE
ERROR_PIPE_NOT_CONNECTED EPIPE
ERROR_PRIVILEGE_NOT_HELD EACCES
ERROR_READ_FAULT EIO
ERROR_SEEK ESPIPE
ERROR_SEEK_ON_DEVICE ESPIPE
ERROR_SHARING_BUFFER_EXCEEDED ENFILE
ERROR_SHARING_VIOLATION ETXTBSY
ERROR_STACK_OVERFLOW ENOMEM
ERROR_SWAPERROR ENOENT
ERROR_TOO_MANY_MODULES EMFILE
ERROR_TOO_MANY_OPEN_FILES EMFILE
ERROR_UNRECOGNIZED_MEDIA ENXIO
ERROR_UNRECOGNIZED_VOLUME ENODEV
ERROR_WAIT_NO_CHILDREN ECHILD
ERROR_WRITE_FAULT EIO
ERROR_WRITE_PROTECT EROFS

Table 1: Windows Error Code to errno Value Mapping

Supported Signals


Signal Type
Signal Number
Supported

Action

Meaning
SIGHUP 1 yes Exit Hang up
SIGINT 2 yes Exit interrupt
SIGQUIT 3 yes Core Quit
SIGILL 4 yes Core Illegal Instruction
SIGTRAP 5 yes Core Trace/Breakpoint Trap
SIGABRT
SIGIOT
6 yes Core Abort
SIGEMT 7 no Core Emulation Trap
SIGFPE 8 yes Core Arithmetic Exception
SIGKILL 9 yes Exit Killed
SIGBUS 10 yes Core Bus Error
SIGSEGV 11 yes Core Segmentation Fault
SIGSYS 12 no Core Bad System Call
SIGPIPE 13 yes Exit Broken Pipe
SIGALRM 14 yes Exit Alarm Clock
SIGTERM 15 yes Exit Terminated
SIGUSR1 16 yes Exit User Signal 1
SIGUSR2 17 yes Exit User Signal 2
SIGCHLD
SIGCLD
18 yes Ignore Child Status
SIGPWR 19 no Ignore Power Failure
SIGWINCH 20 no Ignore Window Size Change
SIGURG 21 yes Ignore Urgent Socket Condition
SIGIO
SIGPOLL
22 yes Ignore I/O Possible
SIGSTOP 23 no Stop Stopped (signal)
SIGTSTP 24 no Stop Stopped (user)
SIGCONT 25 no Ignore Continued
SIGTTIN 26 no Stop Stopped (tty input)
SIGTTOU 27 no Stop Stopped (tty output)
SIGVTALRM 28 no Exit Virtual Timer Expired
SIGPROF 29 no Exit Profiling Timer Expired
SIGXCPU 30 no Core CPU time limit exceeded
SIGXFSZ 31 no Core File size limit exceeded

Table 2: Supported Signals

Windows Exceptions and Signals

Windows Exception Signal
EXCEPTION_ACCESS_VIOLATION SIGSEGV
EXCEPTION_DATATYPE_MISALIGNMENT SIGBUS
STATUS_DATATYPE_MISALIGNMENT SIGBUS
EXCEPTION_BREAKPOINT SIGTRAP
EXCEPTION_SINGLE_STEP SIGTRAP
EXCEPTION_ARRAY_BOUNDS_EXCEEDED 0
EXCEPTION_FLT_DENORMAL_OPERAND SIGFPE
EXCEPTION_FLT_DIVIDE_BY_ZERO SIGFPE
EXCEPTION_FLT_INEXACT_RESULT SIGFPE
EXCEPTION_FLT_INVALID_OPERATION SIGFPE
EXCEPTION_FLT_OVERFLOW SIGFPE
EXCEPTION_FLT_STACK_CHECK SIGFPE
EXCEPTION_FLT_UNDERFLOW SIGFPE
EXCEPTION_INT_DIVIDE_BY_ZERO SIGFPE
EXCEPTION_INT_OVERFLOW SIGFPE
EXCEPTION_PRIV_INSTRUCTION SIGILL
EXCEPTION_IN_PAGE_ERROR 0
EXCEPTION_ILLEGAL_INSTRUCTION SIGILL
STATUS_BREAKPOINT SIGTRAP
STATUS_SINGLE_STEP SIGTRAP

Table 3: Windows Exception to Signal Mapping


PTC MKS Toolkit 10.2 Documentation Build 28.