C Library Overview

This chapter lists the functions arranged by category and describes what's in a function description.

Functions arranged by categories

The functions in the Watcom C library can be organized into a number of categories:

• Character manipulation
• Console I/O
• Conversion
• Devices
• Directories
• File manipulation
• Heaps
• Intel 80x86 architecture-specific functions
• Math
• Memory allocation
• Memory manipulation
• Miscellaneous
• Mouse
• Multibyte-character manipulation
• Multibyte-character string manipulation
• O/S-level I/O
• POSIX message queues
• POSIX realtime timers
• POSIX semaphores
• POSIX shared memory
• POSIX terminal control
• Process environment
• Process primitives
• QNX low-level functions
• QNX messaging
• Searching
• Stream I/O functions
• String manipulation
• System databases
• System message log
• Time
• Variable-length argument lists

The sections that follow describe these function categories in more detail. Each function in the category is noted with a brief description of its purpose.

Character manipulation

These functions operate upon single characters of type char. The functions test characters in various ways and convert them between upper and lowercase:

Console I/O

These functions provide the capability to read and write data from the console. Data is read or written without any special initialization (devices are not opened or closed), since the functions operate at the hardware level.

The following functions are defined:

QNX also provides the following functions that deal with consoles:

Conversion

To and from strings

These functions perform conversions between objects of various types and strings:

See also:

• tolower(), _tolower()
• toupper(), _toupper()
• strlwr()
• strupr()

Devices

These QNX functions pertain to devices:

Directories

These functions manipulate directories:

File manipulation

These functions operate directly with files:

Heaps

These functions provide the ability to shrink and grow the heap, as well as find heap-related problems.

Intel 80x86 architecture-specific functions

These functions provide the capability to invoke Intel 80x86 processor-related functions directly from a program. Functions that apply to the Intel 8086 CPU apply to that family including the 80286, 80386, 80486 and Pentium processors. The following functions are defined:

Math

The mathematical functions perform mathematical computations such as the common trigonometric calculations. These functions operate with objects of type double, also known as floating-point numbers. The Intel 8087 processor (and its successor chips) is commonly used to implement floating-point operations on personal computers. Functions ending in "87" pertain to this specific hardware, and should be isolated in programs when portability is a consideration.

Memory allocation

These functions allocate and de-allocate blocks of memory.

The default data segment has a maximum size of 64K bytes. It may be less in a machine with insufficient memory, or when other programs in the computer already occupy some of the memory. The _nmalloc() function allocates space within this area.

In a small data model, the malloc(), calloc() and realloc() functions use the _nmalloc() function to acquire memory.

It is important to use the appropriate memory-deallocation function to free memory blocks:

• the _nfree() function should be used to free space acquired by the _ncalloc(), _nmalloc(), or _nrealloc() functions

The free() function uses the _nfree() function when the small data memory model is used.

The _nmalloc() function can be used in either data memory model.

The following functions are defined:

Memory manipulation

These functions manipulate blocks of memory. In each case, the address of the memory block and its size are passed to the function. Functions whose names begin with _f accept far pointers as their arguments, allowing manipulation of any memory location, regardless of which memory model your program has been compiled for.

See also:

• String manipulation

Miscellaneous

The following functions are defined:

Mouse

These functions provide access to the mouse and its driver:

Multibyte characters

These ANSI C functions provide capabilities for processing multibyte characters:

Multibyte-character-string manipulation

These functions manipulate strings of multibyte characters. A multibyte character is either a single-byte or double-byte character. The Chinese, Japanese and Korean character sets are examples of character sets containing both single-byte and double-byte characters.

What determines whether a character is a single-byte or double-byte character is the value of the lead byte in the sequence. For example, in the Japanese DBCS (double-byte character set), double-byte characters are those in which the first byte falls in the range 0x81 - 0x9F or 0xE0 - 0xFC and the second byte falls in the range 0x40 - 0x7E or 0x80 - 0xFC.

A string of multibyte characters must be scanned from the first byte (index 0) to the last byte (index n) in sequence in order to determine if a particular byte is part of a double-byte character. For example, suppose that a multibyte character string contains the following byte values:

0x31 0x40 0x41 0x81 0x41 // "1@A.." where .. is a DB char

Among other characters, it contains the letter A (the first 0x41) and a double-byte character (0x81 0x41). The second 0x41 isn't the letter A and that could only be determined by scanning from left to right starting with the first byte (0x31).

The following functions are defined:

See also:

• Conversion
• Time
• Memory manipulation

O/S-level I/O

These functions operate at the operating-system level, and are included for compatibility with other C implementations. It is recommended that the File Manipulation functions be used for new programs, as these functions are defined portably, and are part of the ANSI standard for the C language.

The functions in this section reference opened files and devices using a file descriptor that's returned when the file is opened. The file descriptor is passed to the other functions. The following functions are defined:

These functions also operate at the operating-system level, but are specific to QNX:

POSIX message queues

These functions deal with message queues:

POSIX realtime timers

These functions provide realtime timer capabilities:

POSIX semaphores

These functions deal with semaphores:

POSIX shared memory

These functions provide memory mapping capabilities:

POSIX terminal control

These functions deal with terminal attributes, such as baud rate and terminal interface control functions. The following functions are defined:

Process environment

These functions deal with process identification, user identification, process groups, system identification, system time and process time, environment variables, terminal identification, and configurable system variables:

Process primitives

These functions deal with process creation, execution and termination, signal handling, and timer operations.

The QNX libraries aren't completely thread-safe. Before calling a function in a thread, check its Classification section to make sure it's safe to do so.

When a new process is started, it replaces the existing process in the following cases:

• P_OVERLAY is specified with the spawn...() functions
• the exec...() routines are invoked

The existing process may be suspended while the new process executes (control continues at the point following the place where the new process was started) in the following situations:

• P_WAIT is specified with the spawn...() functions
• system() is used

The following functions are defined:

There are eight spawn...() and exec...() functions each. The "..." is one to three letters:

• l or v (one is required) to indicate the way the process parameters are passed
• p (optional) to indicate that the PATH environment variable is searched to locate the program for the process
• e (optional) to indicate that the environment variables are being passed

QNX low-level functions

These functions provide the capability to invoke QNX functions directly from a program:

QNX messaging

These functions provide access to message passing:

Searching

These functions provide searching and sorting capabilities:

Stream I/O

These functions provide the "standard" functions to read and write files. Data can be transmitted as characters, strings, blocks of memory or under format control.

A stream is the name given to a file or device that has been opened for data transmission. When a stream is opened, a pointer to a FILE structure is returned. This pointer is used to reference the stream when other functions are subsequently invoked.

When a program begins execution, there are a number of streams already open for use:

stdin

Standard Input: input from the console

stdout

Standard Output: output to the console

stderr

Standard Error: output to the console (used for error messages)

These standard streams may be re-directed by use of the freopen() function.

The Operating System I/O functions may also be invoked (use the fileno() function to obtain the file descriptor). Since the stream functions may buffer input and output, these functions should be used with caution to avoid unexpected results.

See also:

• File manipulation
• Directories

String manipulation

A string is an array of characters (with type char) that is terminated with an extra null character ('\0'). Functions are passed only the address of the string, since the size can be determined by searching for the terminating character. The functions that begin with _f accept far pointers as their arguments, allowing manipulation of any memory location, regardless of which memory model your program has been compiled for.

See also:

• Conversion
• Time
• Memory manipulation

System databases

These functions allow an application to access group and user database information. The following functions are defined:

System message log

This set of functions controls the system log:

Time

These functions are concerned with dates and times.

Variable-length argument lists

Variable-length argument lists are used when a function doesn't have a fixed number of arguments. These macros provide the capability to access these arguments:

What's in a function description?

Each description consists of a number of subsections:

Synopsis:

This subsection 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 and that function 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

Description:

This subsection is a description of the function or macro.

Returns:

This subsection describes the return value (if any) for the function or macro.

Errors:

This subsection describes the possible values that the function might assign to the global variable errno.

Example:

This optional subsection consists of one or more examples of the use of the function. The examples are often just fragments of code (not complete programs) for illustrative purposes.

Classification:

This subsection provides an indication of where the function or macro is commonly found. The following notation is used:

ANSI

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

Intel

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

POSIX 1003.1

These functions or macros aren't defined by the ANSI C standard. They're specified in the document IEEE Standard Portable Operating System Interface for Computer Environments (IEEE Draft Standard 1003.1-1990).

POSIX 1003.2

These functions or macros aren't defined by the ANSI C standard. They're specified in the document Shell and Utility Application Interface for Computer Operating System Environments (IEEE Computer Society Working Group 1003.2).

POSIX 1003.4

These functions or macros aren't defined by the ANSI C standard. They're specified in the document Realtime Extensions for Computer Operating System Environments (IEEE Computer Society Working Group 1003.4).

QNX

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

UNIX

These functions exist on some UNIX systems, but are outside of the POSIX or ANSI standards.

WATCOM

These functions or macros are neither ANSI nor POSIX. They may be found in other implementations of the C language, but caution should be used if portability is a consideration.

The Classification section also indicates whether or not it's safe to use the function:

• in an interrupt handler
• in a signal handler
• in a multithreaded program

Caveats:

This optional subsection gives warnings about the function.

See Also:

This optional subsection provides a list of related functions or macros, or places to look for more information.