What's in a Function Description?

Updated: April 19, 2023

The entry for each function in this reference typically includes the following sections:

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

The synopsis might include synonyms for the standard types for exact-width integers (e.g., _Uint16t or _uint16t instead of uint16_t), but the synonyms correspond in a fairly obvious way to the standard types.

Arguments:

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

Library:

This 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 QNX 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.

If this section says that a function returns a certain value if an error occurred, but doesn't say what it returns on success (or the other way around), don't make any assumptions about the value returned for the undocumented case. For example, if a function is only documented as returning -1 on error, don't assume that it returns 0 on success. Instead of writing this:

if ( some_function() == EOK) {
  /* Everything's OK */
}

write this:

if ( some_function() == -1) {
  /* An error occurred; handle it appropriately */
} else {
  /* Everything's OK */
}

Errors:

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

Note: This section doesn't necessarily list all of the values that the function could set errno to or return. For example, because QNX Neutrino is a microkernel, much of the C library is built on top of MsgSend(), so its error codes might apply to functions that use it. If a function interacts with a server, and the server replies with MsgError(), the server can return any error code that it wants to.

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.
C11
These functions or macros are defined by the ISO/IEC 9899:2011 standard.
Large-file support
These functions and data types support 64-bit file offsets. They're stopgap measures that you might need to use until the default file offsets are 64 bits long:
  • If you want to use 64-bit file offsets everywhere, set _FILE_OFFSET_BITS=64 when you compile, and then use off_t and the normal functions (e.g., open() instead of open64()). Use fseeko() and ftello() instead of fseek() and ftell().
  • If you need to use both 32- and 64-bit file offsets in a program, set _FILE_OFFSET_BITS=32 and define _LARGEFILE64_SOURCE when you compile, and then use the large-file support functions when you need to use 64-bit offsets.
  • If you're porting source that uses the large-file support functions, define _LARGEFILE64_SOURCE when you compile.

In header files and code, don't refer directly to _FILE_OFFSET_BITS or _LARGEFILE64_SOURCE; use __OFF_BITS__ and __EXT_LF64SRC instead.

Note: In QNX Neutrino 6.6 or later, the large-file support functions and data types appear in the name space only if you define _LARGEFILE64_SOURCE when you compile your code. In earlier versions of the OS, these functions appeared in the default name space, but not in others such as POSIX_C_SOURCE.
NetBSD
These functions are part of the NetBSD free, open-source system. For more information, see http://netbsd.org/.
OpenBSD
These functions are part of the OpenBSD free, open-source system. For more information, see http://openbsd.org/.
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.

Note: For information about the many POSIX drafts and standards, see the IEEE website at http://www.ieee.org/.

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
CPT Process CPU-Time Clocks
CX Extension to the ISO C standard
FSC File Synchronization
MC1 Non-Robust Mutex Priority Protection or Non-Robust Mutex Priority Inheritance or Robust Mutex Priority Protection or Robust Mutex Priority Inheritance
ML Process Memory Locking
MLR Range Memory Locking
MSG Message Passing
OB Obsolescent
PS Process Scheduling
RPP Robust Mutex Priority Protection
SHM Shared Memory Objects
SIO Synchronous Input/Output
SPN Spawn
TCT Thread CPU-Time Clocks
TPI Non-Robust Mutex Priority Inheritance
TPP Non-Robust Mutex Priority Protection
TPS Thread Execution Scheduling
TSA Thread Stack Address Attribute
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 Neutrino
These functions or macros are neither ANSI nor POSIX. They perform a function related to the QNX Neutrino RTOS. They may be found in other implementations of C for personal computers with the QNX Neutrino RTOS. 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.
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. If a function isn't flagged as interrupt-safe, don't use it in an interrupt handler.

If you use TraceEvent() to add a dynamic rules filter, the only library functions that you can call in your event handler are those that are safe to call from an interrupt handler.

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.
Note:
  • The “safety” designations documented in this manual are valid for the current release and could change in future versions.
  • (QNX Neutrino 7.1 or later) The kernel saves the FPU context on entering Interrupt Service Routines (ISRs), signal handlers, and trace event handlers, and restores the FPU context on leaving them. This means that it's safe to use floating-point operations in ISRs, signal handlers, and trace event handlers.

For a summary, see the Full Safety Information appendix.

See also:

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