This chapter contains a detailed description of each function in the Borland C++ library. The functions are listed in alphabetical order, although a few of the routines are grouped by "family" (the exeq ... and spawn ... functions, for example) because they perform similar or related tasks.
Each function entry provides certain standard information. For instance, the entry for free
• Tells you which header file(s) contains the prototype for free.
• Summarizes what free does.
• Gives the syntax for calling free.
• Gives a detailed description of how free is implemented and how it relates to the other memory-allocation routines.
• Lists other language compilers that include similar functions.
• Refers you to related Borland C++ functions.
The following sample library entry lists each entry section and describes the information it contains. The alphabetical listings start on page 27.
Sample function entry header file name
Function Syntax
The function is followed by the header file(s) containing the prototype for function or definitions of constants, enumerated types, and so on used by function.
Summary of what this function does.
function(modifier parameter[, ... J};
This gives you the declaration syntax for function; parameter names are italicized. The [/ ... J indicates that other parameters and their modifiers can follow.
Portability is indicated by marks (.) in the columns of the portability table.
A sample portability table is shown here:
Sample function entry
Remarks Return value See also
Example
DOS
Each entry in the portability table is described in the following table. Any additional restrictions are discussed in the Remarks section.
DOS UNIX Win 16
win 32
ANSI C
Available for DOS.
Available under UNIX andbr POSIX.
Compatible with 16-bit Windows programs running on Microsoft Windows 3.1 , Windows for Workgroups 3.1, and Windows for Workgroups 3.11. EasyWin users should see the Users Guide for information about using certain non-Windows functions (such as printf and scan~ in programs that run under Windows.
Available to 32-bit Windows programs running on Win32s 1.0, and Windows NT 3;1 applications.
Defined by the ANSI C Standard.
ANSI Ctt Included in the ANSI C++ proposal.
as / 2 Available for OS/2.
If more than one function is discussed and their portability features are identical, only one row is used. Otherwise, each function is represented in a separate row.
This section describes what function does, the parameters it takes, and any details you need to use function and the related routines listed.
The value that function returns (if any) is given here. If function sets any global variables, their values are also listed.
Routines related to function that you might want to read about are listed here. If a routine name contains an ellipsis, it indicates that you should refer to a family of functions (for example, exec ... refers to the entire family of exec functions: execl, execle, execlp, execlpe, execv, execve, execvp, and execvpe).
The function examples have been moved into online Help so that you can easily cut-and-paste them to your own applications.
abort
Function Syntax
Remarks
Return value See also
abs
Function Syntax
Remarks
Return value
See also
abort
stdlib.h
Abnormally terminates a program.
void abort(void)i
ANSI C++ OS/2
abort causes an abnormal program termination by calling -raise(SIGABRT). If there is no signal handler for SIGABRT, then abort writes a termination message ("Abnormal program termination") on stderr, then aborts the program by a call to _exit with exit code 3.
abort returns the exit code 3 to the parent process or to the operating system command processor.
assert, atexit, _exit, exit, raise, signal, spawn ...
stdlib.h
Returns the absolute value of an integer.
int abs (int x) i
abs returns the absolute value of the integer argument x. If abs is called when stdlib.h has been included, it's treated as a macro that expands to inline code.
If you want to use the abs function instead of the macro, include #undef abs in your program, after the #include <stdlib.h>.
This function can be used with bcd and complex types.
The abs function returns an integer in the range of 0 to INT_MAX, with the exception that an argument with the value INT_MIN is returned as INT_MIN. The values for INT_MAX and INT_MIN are defined in header file limi ts.h.
bcd, cabs, complex, tabs, labs
access
access
Function Syntax
Remarks
Return value
See also
Determines accessibility of a file.
int access (const char *filename, int amode)i
access checks the file named by filename to determine if it exists, and whether it can be read, written to, or executed.
The list of amode values is as follows:
06 Check for read and write permission 04 Check for read permission
02 Check for write permission 01 Execute (ignored)
00 Check for existence of file
io.h
. . Under DOS, OS/2, and Windows (16- and 32-bit) all existing files have read access (amode equals 04), so 00 and 04 give the same result. Similarly, amode values of 06 and 02 are equivalent because under DOS write access implies read access.
If filename refers to a directory, access simply determines whether the directory exists.
If the requested access is allowed, access returns 0; otherwise, it returns a value of -I, and the global variable errno is set to one of the following values:
EACCES ENOENT
Permission denied
Path or file name not found chmod, fstat, stat
acos, acosl math.h
Function Calculates the arc cosine.
Syntax
Remarks
Return value
See also
alloca
Function Syntax
Remarks
acos acosl
acos, acosl
double acos(double Xli
long double acosl(long double xl i
DOS UNIX Win 16 Win 32 ANSI C ANSI C++ OS/2
• • • • •
•
•• •
•
•acos returns the arc cosine of the input value. acosl is the long double version; it takes a long double argument and returns a long double result.
Arguments to acos and acosl must be in the range -1 to 1, or else acos and acosl return NAN and set the global variable errno to
EDOM Domain error
This function can be used with bcd and complex types.
acos and acosl of an argument between -1 and +1 return a value in the range
o
to pi. Error handling for these routines can be modified through the functions _matherr and _matherrl.asin, atan, atan2, bcd, complex, cos, _matherr, sin, tan
malloc.h
Allocates temporary stack space.
void *alloca(size_t sizel;
DOS UNIX
alloca allocates size bytes on the stack; the allocated space is automatically freed up when the calling function exits.
Because alloca modifies the stack pointer, do not place calls to alloca in an' expression that is an argument to a function.
The alloca function should not be used in the try/block of a C++ program. If an exception is thrown any values placed on the stack by alloca will be corrupted.
If the calling function does not contain any references to local variables in the stack, the stack will not be restored correctly when the function exits,
alloca
Return value See also
asctime
Function Syntax
Remarks
Return value
See also