What's in a Function Description?

The description of each function in this refernce contains the following sections:

• Synopsis
• Arguments
• Library
• Description
• Returns
• Errors
• See also
• Examples
• Classification
• Function safety

Synopsis:

This section gives the header files that should be included within a source file that references the function or macro. It also shows an appropriate declaration for the function or for a function that could be substituted for a macro. This declaration isn't included in your program; only the header file(s) should be included.

When a pointer argument is passed to a function that doesn't modify the item indicated by that pointer, the argument is shown with const before the argument. For example, the following indicates that the array pointed at by string isn't changed:

const char *string

Arguments:

This section gives a brief description of the arguments to the function.

Library:

The section indicates the library that you need to bind with your application in order to use the function.

To link against a library, use the -l option to qcc, omitting the lib prefix and any extension from the library's name. For example, to link against libsocket, specify -l socket. For more information, see the Compiling and Debugging chapter of the Neutrino Programmer's Guide.

Description:

This section describes the function or macro.

Returns:

This section gives the return value (if any) for the function or macro.

Errors:

This section describes the special values that the function might assign to the global variable errno.

---

This section doesn't necessarily list all of the values that the function could set errno to.

---

See also:

This optional section provides a list of related functions or macros as well as pertinent docs to look for more information.

Examples:

This optional section gives one or more examples of the use of the function. The examples are often just code snippets, not complete programs.

Classification:

This section tells where the function or macro is commonly found, which may be helpful when porting code from one environment to another. Here are the classes:

ANSI

These functions or macros are defined by the ANSI C99 standard.

Large-file support

These functions support 64-bit offsets.

POSIX 1003.1

These functions are specified in the document Information technology — Portable Operating System Interface (IEEE Std 1003.1, 2004 Edition).

This standard incorporates the POSIX 1003.2-1992 and 1003.1-1996 standards, the approved drafts (POSIX 1003.1a, POSIX 1003.1d, POSIX 1003.1g and POSIX 1003.1j) and the Standard Unix specification. A joint technical working group — the Austin Common Standards Revision Group (CSRG) — was formed to merge these standards.

---

For an up-to-date status of the many POSIX drafts/standards documents, see the PASC (Portable Applications Standards Committee of the IEEE Computer Society) report at http://www.pasc.org/standing/sd11.html.

---

A classification of “POSIX 1003.1” can be followed by one or more codes that indicate which option or options the functions belong to. The codes include the following:

Code	Meaning
ADV	Advisory Information
AIO	Asynchronous Input/Output
BAR	Barriers
CPT	Process CPU-Time Clocks
CS	Clock Selection
CX	Extension to the ISO C standard
FSC	File Synchronization
MF	Memory Mapped Files
ML	Process Memory Locking
MLR	Range Memory Locking
MPR	Memory Protection
MSG	Message Passing
OB	Obsolescent
PS	Process Scheduling
RTS	Realtime Signals Extension
SEM	Semaphores
SHM	Shared Memory Objects
SIO	Synchronous Input/Output
SPI	Spin Locks
TCT	Thread CPU-Time Clocks
THR	Threads
TMO	Timeouts
TMR	Timers
TPI	Thread Priority Inheritance
TPP	Thread Priority Protection
TPS	Thread Execution Scheduling
TSA	Thread Stack Address Attribute
TSF	Thread-Safe Functions
TSH	Thread Process-Shared Synchronization
TSS	Thread Stack Size Attribute
TYM	Typed Memory Objects
XSI	X/Open Systems Interfaces Extension
XSR	XSI Streams

If two codes are separated by a space, you need to use both options; if the codes are separated by a vertical bar (|), the functionality is supported if you use either option.

For more information, see the Standard for Information Technology — Portable Operating System Interface: Base Definitions.

QNX 4

These functions or macros are neither ANSI nor POSIX. They perform a function related to the QNX OS version 4. They may be found in other implementations of C for personal computers with the QNX 4 OS. Use these functions with caution if portability is a consideration.

---

Any QNX 4 functions in the C library are provided only to make it easier to port QNX 4 programs. Don't use these in QNX Neutrino programs.

---

QNX Neutrino

These functions or macros are neither ANSI nor POSIX. They perform a function related to the QNX Neutrino OS. They may be found in other implementations of C for personal computers with the QNX OS. Use these functions with caution if portability is a consideration.

RFC 2292

Based on W. Stevens and M. Thomas, Advanced Sockets API for IPv6, RFC 2292, February 1998.

SNMP

Simple Network Management Protocol is a network-management protocol whose base document is RFC 1067. It's used to query and modify network device states.

SOCKS

These functions are part of the SOCKS package consisting of a proxy server, client programs (rftp and rtelnet), and a library (libsocks) for adapting other applications into new client programs. For more information, see the appendix SOCKS — A Basic Firewall.

Unix

These Unix-class functions reside on some Unix systems, but are outside of the POSIX or ANSI standards.

We've created the following Unix categories to differentiate:

Legacy Unix

Functions included for backwards compatibility only. New applications shouldn't use these functions.

Unix

Other Unix functions.

Function safety:

This section summarizes whether or not it's safe to use the C library functions in certain situations:

Cancellation point

Indicates whether calling a function may or may not cause the thread to be terminated if a cancellation is pending.

Interrupt handler

An interrupt-safe function behaves as documented even if used in an interrupt handler. Functions flagged as interrupt-unsafe shouldn't be used in interrupt handlers.

Signal handler

A signal-safe function behaves as documented even if called from a signal handler even if the signal interrupts a signal-unsafe function.

Some of the signal-safe functions modify errno on failure. If you use any of these in a signal handler, asynchronous signals may have the side effect of modifying errno in an unpredictable way. If any of the code that can be interrupted checks the value of errno (this also applies to library calls, so you should assume that most library calls may internally check errno), make sure that your signal handler saves errno on entry and restores it on exit.

All of the above also applies to signal-unsafe functions, with one exception: if a signal handler calls a signal-unsafe function, make sure that signal doesn't interrupt a signal-unsafe function.

Thread

A thread-safe function behaves as documented even if called in a multi-threaded environment.

Most functions in the QNX Neutrino libraries are thread-safe. Even for those that aren't, there are still ways to call them safely in a multi-threaded program (e.g. by protecting the calls with a mutex). Such cases are explained in each function's description.

---

The “safety” designations documented in this manual are valid for the current release and could change in future versions. Floating-point functions aren't safe to use in interrupt handlers or signal handlers.

---

For a summary, see the Summary of Safety Information appendix.