.im cfunmacs
.*
.chap C Library Overview
.*
.np
The C library provides much of the power usually associated with the C
language.
This chapter introduces the individual functions (and macros) that
comprise the &company C library.
The chapter
.us Library Functions and Macros
describes each function and macro in complete detail.
.np
Library functions are called as if they had been defined within the
program.
When the program is linked, the code for these routines is incorporated
into the program by the linker.
.np
Strictly speaking, it is not necessary to declare most library
functions since they return
.id int
values for the most part.
It is preferred, however, to declare all functions by including the
header files found in the synopsis section with each function.
Not only does this declare the return value, but also the type
expected for each of the arguments as well as the number of arguments.
This enables the &company C and C++ compilers to check the arguments
coded with each function call.
.*======================================================================
.section Classes of Functions
.*
.np
.ix 'function classification'
The functions in the &company C library can be organized into a number
of classes:
.begnote
.*
.note Character Manipulation Functions
.sk 0
These functions deal with single characters.
.if &unifnc eq 1 .do begin
.np
A set of functions that deal with Unicode characters is also provided.
A Unicode character is a 16-bit item (unsigned short).
The Unicode character set is capable of representing 65536 unique
characters.
.do end
.*
.note Wide Character Manipulation Functions
.sk 0
These functions deal with wide characters.
.*
.note Multibyte Character Manipulation Functions
.sk 0
These functions deal with multibyte characters.
.*
.note Memory Manipulation Functions
.sk 0
These functions manipulate blocks of memory.
.*
.note String Manipulation Functions
.sk 0
These functions manipulate strings of characters.
A character string is an array of zero or more adjacent characters
followed by a null character
.mono ('\0')
which marks the end of the string.
.if &unifnc eq 1 .do begin
.np
A set of functions that manipulate strings of Unicode characters is
also provided.
A Unicode character string is an array of zero or more adjacent
16-bit Unicode characters followed by a 16-bit null character
.mono (L'\0')
which marks the end of the string.
.do end
.*
.note Wide String Manipulation Functions
.sk 0
These functions manipulate strings of wide characters.
A wide character string is an array of zero or more adjacent wide
characters followed by a null wide character
.mono (L'\0')
which marks the end of the wide string.
.*
.note Multibyte String Manipulation Functions
.sk 0
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.
.np
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.
.millust begin
0x31 0x40 0x41 0x81 0x41 // "1@A.." where .. is a DB char
.millust end
.pc
Among other characters, it contains the letter "A" (the first 0x41)
and a double-byte character (0x81 0x41).
The second 0x41 is not the letter "A" and that could only be
determined by scanning from left to right starting with the first byte
(0x31).
.*
.note Conversion Functions
.sk 0
These functions convert values from one representation to another.
Numeric values, for example, can be converted to strings.
.if &unifnc eq 1 .do begin
A set of functions that convert to and from Unicode character strings
is also provided.
.do end
.*
.note Memory Allocation Functions
.sk 0
These functions are concerned with allocating and deallocating memory.
.*
.note Heap Functions
.sk 0
These functions provide the ability to shrink and grow the heap,
as well as, find heap related problems.
.*
.note Math Functions
.sk 0
The mathematical functions perform mathematical computations
such as the common trigonometric calculations.
These functions operate on
.id double
values, also known as floating-point values.
.*
.note Searching Functions
.sk 0
These functions provide searching and sorting capabilities.
.*
.note Time Functions
.sk 0
These functions provide facilities to obtain and manipulate
times and dates.
.*
.note Variable-length Argument Lists
.sk 0
These functions provide the capability to process a variable number of
arguments to a function.
.*
.note Stream I/O Functions
.sk 0
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.
.*
.note Wide Character Stream I/O Functions
.sk 0
These functions provide the "standard" functions to read and write
files of wide characters.
Data can be transmitted as wide characters, wide character strings,
blocks of memory or under format control.
.*
.note Process Primitive Functions
.sk 0
.if '&machsys' eq 'QNX' .do begin
These functions deal with process creation, execution and termination,
signal handling, and timer operations.
.do end
.el .do begin
These functions deal with process creation, execution and termination,
signal handling, and timer operations.
.do end
.*
.note Process Environment
.sk 0
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.
.*
.note Directory Functions
.sk 0
These functions provide directory services.
.*
.note Operating System I/O Functions
.sk 0
.if '&machsys' eq 'QNX' .do begin
These functions are described in the "IEEE Standard Portable Operating
System Interface for Computer Environments" (POSIX 1003.1).
The POSIX input/output functions provide the capability to perform I/O
at a "lower level" than the C Language "stream I/O" functions (e.g.,
.kw fopen
.ct,
.kw fread
.ct,
.kw fwrite
.ct,
and
.kw fclose
.ct ).
.do end
.el .do begin
These "non-standard" file operations are more primitive than the
"standard" functions in that they are directly interfaced to the
operating system.
They are included to provide compatibility with other C implementations
and to provide the capability to directly use operating-system
file operations.
.do end
.if &unifnc eq 1 .do begin
.np
A set of functions that handle a file system based upon Unicode
filenames is also provided.
.do end
.*
.note File Manipulation Functions
.sk 0
These functions operate directly on files, providing facilities such
as deletion of files.
.if &unifnc eq 1 .do begin
.np
A set of functions that handle a file system based upon Unicode
filenames is also provided.
.do end
.*
.note Console I/O Functions
.sk 0
These functions provide the capability to directly read and write
characters from the console.
.*
.note Default Windowing Functions
.sk 0
These functions provide the capability to manipulate various dialog
boxes in &company's default windowing system.
.*
.if '&machsys' eq 'QNX' .do begin
.note POSIX Realtime Timer Functions
.sk 0
These functions provide realtime timer capabilities.
.do end
.*
.if '&machsys' eq 'QNX' .do begin
.note POSIX Shared Memory Functions
.sk 0
These functions provide memory mapping capabilities.
.do end
.*
.if '&machsys' eq 'QNX' .do begin
.note POSIX Terminal Control Functions
.sk 0
These functions deal with terminal attributes such as baud rate
and terminal interface control functions.
.do end
.*
:cmt. .if '&machsys' eq 'QNX' .do begin
:cmt. .note QNX Terminal Functions
:cmt. .sk 0
:cmt. These functions provide terminal I/O control, cursor movement,
:cmt. character and line insertion/deletion, menus, saving/restoring
:cmt. portions of the screen, etc.
:cmt. .do end
.*
.if '&machsys' eq 'QNX' .do begin
.note System Database Functions
.sk 0
These functions allow an application to access group and user database
information.
.do end
.*
.if '&machsys' eq 'QNX' .do begin
.note Miscellaneous QNX Functions
.sk 0
These functions provide access to a variety of QNX functions such as
message passing.
.do end
.*
.if '&machsys' eq 'QNX' .do begin
.note QNX Low-level Functions
.sk 0
These functions provide access to low-level QNX facilities.
.do end
.*
.if '&machsys' ne 'QNX' .do begin
.if '&machsys' ne 'WIN32' .do begin
.note BIOS Functions
.sk 0
This set of functions allows access to services provided by the BIOS.
.do end
.do end
.*
.if '&machsys' ne 'QNX' .do begin
.note DOS-Specific Functions
.sk 0
This set of functions allows access to DOS-specific functions.
.do end
.*
.note Intel 80x86 Architecture-Specific Functions
.sk 0
This set of functions allows access to Intel 80x86 processor-related
functions.
.*
.note Intel Pentium Multimedia Extension Functions
.sk 0
This set of functions allows access to Intel Architecture Multimedia
Extensions (MMX).
.*
:cmt. QNX will do later .if '&machsys' eq 'QNX' .do begin
:cmt. QNX will do later .note UNIX portability Functions
:cmt. QNX will do later .sk 0