www.digitalmars.com [Home] [Search] [CTG] [RTL] [IDDE]

Last update Sep 16, 2002


Overview of Digital Mars C++ Runtime Library

The runtime library contains a comprehensive set of functions and classes that support program development in C and C++. The library supports 16 and 32-bit protected mode applications, as well as 32-bit DOS-extended applications.

The library includes functions typically defined by ANSI standard or UNIX C libraries, plus enhancements to the standard set. It includes C++ classes for working with streams and for performing mathematical computations.

C functions can be called from either C or C++ programs, but the C++ classes can be used only with C++ programs.

Synonym Usage

Many of the names for functions, variables, or other values can have a synonym. For example, the _access function has a synonym:
	Name:		_access
	Synonym:	access
The synonym and name are interchangeable in an application; one can be substituted for the other. Thus, if the prototype for the _access function is:
	int _access(char *path, int mode); 
Using its synonym yields:
	int access(char *path, int mode); 

Math Function Results

Some function descriptions have a Special Results table that describes how the function handles certain kinds of arguments. In these tables, the column headings have the following meanings:
Heading Meaning
value of x The value of x for this condition to exist.
value of y The value of y for this condition to exist.
value of *ptr The value stored through ptr for x (possibly y).
return value The value returned.
invalid? Will the FE_INVALID exception be raised?
div by 0? Will the FE_DIVBYZERO exception be raised?

All of these functions return a NaN if one of its arguments is a NaN. If the argument is a signalling NaN, the function will also raise the FE_INVALID exception.

Compatibility with other Platforms
Each name in this chapter has a section that lists available platforms. If a name is not compatible with a platform, a line is drawn through the platform. Platforms are: DOS, Windows 3.x, Phar Lap, DOSX, and Win32.

Using Wildcard Expansion
Digital Mars C++ supports wildcard expansion in command line arguments via the EXPAND_WILDCARDS macro. The following program shows the use of wildcard expansion. It prints all of its argument. If you invoke this program with "*.*" or other wildcarded arguments, it will print all of the files that match the specified arguments. This program can be compiled and linked normally; no additional object files are necessary.

	/* argsdemo.c */
	/* --Invoke with wildcards in the arguments */ 


	#include <stdio.h>
	#include <dos.h>
	 
	EXPAND_WILDCARDS;      // use wildcard support 

	int main(int argc, char *argv[])
	{   
	    int i;
	    for (i = 0; i < argc; ++i) 
		printf("argv[%d] = '%s'\n", i, argv[i]);
	    return 0;
	} 
For more information see the definition of the EXPAND_WILDCARDS macro in dos.h, and the code in the \dm\src\core\_main.c.

Names, by Category 2

This chapter groups related functions and variables into categories. Missing from the categories are the functions in the Iostream Library.

Table heading F/V means Function/Variable.

80x86

These functions provide easy access from C to 80x86 registers, ports, and segmented memory.

F/V Description
_cpumode Determines if the CPU is in real or protected mode.
cputype Returns the type of 80x86 CPU in the computer.
_FP_OFF Returns the offset portion of a far pointer.
_FP_SEG Returns the segment portion of a far pointer.
getDS Returns the 80x86 data segment register.
_inp, _inpw, inpl Reads from an 80x86 hardware port.
_int86, int86_real, _int86x, int86x_real Generates an 80x86 interrupt, setting and returning registers.
_MK_FP Creates a far pointer from a segment and offset.
_movedata Copies data between segments.
_outp, outpw, outpl Outputs to an 80x86 hardware port.
peek, peekb, peekbytes Gets data from another segment.
poke, pokeb, pokebytes Puts data into another segment.
_segread Gets the current values of the 80x86 segment registers.

BIOS

These functions directly access the ROM BIOS routines that are built into every PC compatible computer.

F/V Description
bioscom, _bios_serialcom Specifies a COM port to use for serial I/ O.
_bios_disk, biosdisk Controls disk and drive handling.
biosequip, _bios_equiplist Returns what equipment is connected to the system.
bioskey, _bios_keybrd Checks keyboard interrupts.
biosmemory, _bios_memsize Returns RAM size.
biosprint, _bios_printer Performs printer control.
biostime, _bios_timeofday Gets/sets the BIOS time.

Character Classification and Manipulation

These functions classify characters into a number of useful categories, and provide conversions from one category to another.

F/V Determines if a character...
isalnum is alphanumeric.
isalpha is alphabetic.
__isasci is ASCII.
iscntrl is a control character.
__iscsym is a letter, underscore, or digit.
__iscsymf is a letter or underscore.
isdigit is a digit.
isgraph is printable (excluding spaces).
islower is lowercase.
isprint is a printable (including spaces).
ispunct is punctuation.
isspace is white space.
isupper is uppercase.
isxdigit is a hexadecimal digit.

F/V Converts a character...
__toascii to ASCII.
_tolower, tolower to lowercase.
_toupper, toupper to uppercase.

Complex Class Library

These functions perform mathematics on complex numbers. The functions also treat complex numbers like real numbers or integers.

F/V Description
complex:: operator= Assigns a value to a complex variable.
complex:: operator+= Adds a value and assigns the result to the complex variable.
complex:: operator-= Subtracts a value and assigns the result to the complex variable.
complex:: operator*= Multiplies a value and assigns the result to the complex variable.
complex:: operator/= Divides the variable and assigns the result to the complex variable.
complex:: operator- Returns the negtaive number.
complex:: operator! Logically negates a number.
operator+ Returns the sum.
operator- Returns the difference.
operator* Returns the product.
operator/ Returns the quotient.
operator&& Performs a logical AND.
operator|| Performs a logical OR.
operator! Tests for inequality.
operator== Tests for equality.
operator<< Reads from the stream.
arg Returns the argument in radians.
complex::imag Returns the imaginary portion of a complex number.
complex:: real Returns the real portion of a complex number.
conj Returns the conjugate.
imag Returns the imaginary portion of a complex number.
modulus Returns the absolute value.
norm Returns the square of the absolute value.
polar Returns the polar coordinates.
real Returns the real portion.
acos Returns the arccosine.
asin, asinh Returns the arcsine or hyperbolic arcsine.
atan, atanh Returns the arctangent or hyperbolic arctangent.
cos, cosh Returns the cosine or hyperbolic cosine.
sin, sinh Returns the sine or hyperbolic sine.
tan, tanh Returns the tangent or hyperbolic tangent.
abs Returns the absolute value.
exp Returns the exponential value.
log, log10 Returns the logarithm base or base 10.
pow Returns a raised number to complex or vice versa.
sqrt Returns the square root.

Control-Break Handling

Normally, the user of a DOS program can press control-c to immediately terminate execution of a program. These functions allow the program to control what happens when control-c is pressed.

F/V Description
controlc_close Removes a user control-break handler.
controlc_open Installs a user control-break handler.
ctrlbrk Installs a user control-break handler.
dos_get_ctrl_break Gets the OS control-break checking status.
dos_set_ctrl_break Turns control-break checking on or off.
getcbrk Gets the current control-break setting.
setcbrk Sets the control-break setting.

Directory and Disk Drive

These functions manipulate directories and disk drives.

F/V Description
_chdir Changes the current directory.
_chdrive, _dos_setdrive, setdisk Sets the current drive.
_dos_getdrive, getdisk, _getdrive Gets the current disk drive.
getcurdir, _getdcwd Gets the current directory for a drive.
_getcwd Gets the current directory for the current drive.
_mkdir Creates a new directory.
_rmdir Deletes a directory.

Display Package

These functions write directly into screen memory. They are suitable for use only on IBM compatible displays (or BIOS) and only in text mode. Using them in graphics mode is not recommended; erratic behavior can occur. If a machine has a BIOS that is IBM compatible, but has a display that is not totally IBM compatible, use the function disp_usebios to force the other disp_functions to access screens through the BIOS. The functions work correctly with the DOSX extender and with Win32. See disp.h.

F/V Description
disp_box Draws a box.
disp_close Closes the display.
disp_eeol Erases to the end of current line.
disp_eeop Erases to the end of the page.
disp_endstand Ends reverse video mode.
disp_fillbox Fills the box.
disp_flush Moves the cursor to coincide with output position.
disp_getattr Gets display attributes.
disp_getmode Gets the current video mode.
disp_hidecursor Hides the cursor.
disp_move Moves the display.
disp_open Initializes the display.
disp_peekbox Stores a defined rectangular area.
disp_peekw Reads the information at specified position defined by row/ column.
disp_pokebox Restores a previously defined rectangular area.
disp_pokew Puts an attribute/ character into a specified row/ column.
disp_printf Writes to the screen.
disp_putc Writes a character to an output location.
disp_puts Writes a string to an output location.
disp_reset43 Resets the display to 80-by-25 mode.
disp_scroll Scrolls the screen up.
disp_set43 Sets the display to 80-by-43 EGA text mode (80-by-50 VGA).
disp_setattr Sets display attributes for characters.
disp_setcursortype Modifies cursor appearance.
disp_setmode Sets video mode.
disp_showcursor Restores previously hidden cursor.
disp_startstand Prints characters in reverse video.
disp_usebios Sets up to write to the screen.

DOS-Specific

These functions access miscellaneous features and data structures that are only available from the DOS operating system.

F/V Description
absread,dos_abs_disk_read Reads disk sectors from a drive.
abswrite,dos_abs_disk_write Writes data to specific disk sectors.
_bdos Calls DOS with DX and AL arguments.
bdosptr, bdosx Calls DOS with DS: DX and AL arguments.
_dosexterr, dos_exterr Retrieves OS extended error information.
_dos_getdiskfree, _getdiskfree Gets disk information and amount of free space.
dos_getdiskfreespace Gets free space remaining on a disk.
_dos_get_verify, getverify Gets the OS verify status.
_dos_keep Installs a TSR program.
dos_set_verify setverify Sets read-after-write verification on or off.
getdta Gets the DOS disk transfer address.
getfat Gets file allocation table information for a drive.
getfatd Gets file allocation table information for the current drive.
int21h Calls DOS via interrupt 21.
_intdos, _intdosx Calls DOS via interrupt 21, setting and returning registers.
setdta Sets the disk transfer address.

Environment Variables and Functions

Environment variables are a set of named string values maintained by the operating system. An example of an environment variable is the PATH variable, which tells the operating system where to look for programs.

When a program starts, it is given a copy of the previous program's environment (usually the OS environment); any changes the program makes to its copy are discarded when the program exits. However, if a program creates a child process, the child receives the parent's environment, with any changes the parent process made to it.

These variables and functions allow a program to access and modify environment variables. See also the spawn and exec functions.

F/V Description
_environ A list of pointers to the environment variables.
_envptr A block of memory containing the environment variables.
getenv Gets the value of a specified environment variable.
_putenv Sets the value of an environment variable.

Error Handling

These functions and variables are related to the trapping, identification, and reporting of errors in programs.

F/V Description
assert Internal program consistency check.
cerror_close Removes a user critical-error handler.
cerror_open Installs a user critical-error handler.
_chkstack Checks for stack overflow.
_doserrno Contains the OS error code for the last error that occurred.
errno Contains the C error code for the last error that occurred.
_harderr Installs a critical error handler.
_hardresume Resumes DOS handling of a critical error.
_hardretn Returns directly to the program from a critical error handler.
perror Prints a message corresponding to the last error that occurred.
_strerror Returns a description of the last error, prepending a user message.
strerror Returns a description of the last error.
_sys_errlist The list of all C error descriptions.
_sys_nerr The number of C error descriptions.

Expanded Memory Manager

Expanded Memory Manager (EMM) functions can be used as an alternative to, or at the same time as, the __handle pointer system and offer more control of an application's expanded memory usage.

F/V
emm_allocpages Allocates expanded memory pages.
emm_deallocpages Frees expanded memory pages.
emm_gethandlecount Gets the number of active handles.
emm_gethandlespages Gets the number of pages allocated to each handle.
emm_getpagemap Gets the page mapping context.
emm_getpagemapsize Gets the buffer size of page mapping.
emm_getsetpagemap Gets the value of the page mapping context and sets it to a new value.
emm_gettotal Gets the number of logical pages.
emm_getunalloc Gets the number of unallocated logical pages.
emm_getversion Gets the version of the EMM.
emm_init Tests if EMM installed.
emm_maphandle Maps the logical page onto the physical page in the emm page frame.
emm_physpage Gets starting address of emm page.
emm_restorepagemap Restores handle's mapping context.
emm_savepagemap Saves page mapping context for the handle.
emm_setpagemap Sets a new page mapping context.
emm_term Terminates EMM.

File Management and File Searching

These functions manage and search for files but do not change a file's contents.

F/V Description
_access Detrmines if and how a file can be accessed.
_chmod Changes the read/ write access of anamed file.
_chsize Changes the size of a file.
_dos_findfirst,findfirst Searches for the first matching file.
_dos_findnext, findnext Searches for succeeding matching files.
_dos_getfileattr Gets the attributes of the named file.
_dos_getftime Gets the time a file was last written to.
_dos_setfileattr Sets the attributes of a file.
filesize Returns the size of a named file.
_fmode The default file translation mode, text or binary.
remove Deletes the named file.
rename Renames the named file.
_searchenv Searches for a file using directories in an environment variable.
searchpath Searches for a file using directories in the PATH environment variable.
_stat Returns information about the named file.
_umask Sets the default read/ write permissions for new files.
_unlink Deletes the named file.
_utime Sets the modified time of a named file.

Handle Package

These functions use the __handle pointer to dynamically allocate, use, and free memory.

F/V Description
handle_calloc Clears and allocates memory.
handle_free Frees memory.
handle_ishandle Tests for a __handle pointer.
handle_malloc Allocates memory.
handle_realloc Reallocates memory.
handle_strdup Allocates memory; duplicates the string pointed to by __handle.

Input and Output

I/ O management for C can be grouped into four general areas: unbuffered, handle-based routines; buffered, stream-based routines; operating system I/ O; and console I/ O routines.

Unbuffered, Handle-Based I/ O These functions provide low-level access to files and devices. Files are accessed via a handle, which is an integer. Note that file handles used with DOS INT 21 calls and Win32 calls are not necessarily the same as handles used with the unbuffered, handle-based I/ O functions, and should not be interchanged.

F/V Description
_close Closes an unbuffered file handle.
_commit Forces the OS to flush a file to disk.
_creat Creates a file and returns a handle to it for unbuffered I/ O.
creatnew Same as _creat, but returns an error if the file already exists.
creattemp Same as _creat, but creates a temporary file.
_dup Creates another unbuffered file handle for an open file.
_cup2 Changes the file that a handle is associated with.
_eof True if the handle's file position is at the end of the file.
_filelength Returns the size of the file associated with a handle.
_fstat Returns the modification time for the file associated with a handle.
_isatty True if a handle is associated with a device rather than a file.
lock Locks a section of a file.
_locking Locks/ unlocks a section of a file, with retry.
_lseek Sets the file position of a handle.
_open Opens a file for unbuffered access and returns a handle to it.
_read,_readx Performs an unbuffered read from a file.
setftime Sets modification date of the file associated with a handle.
_setmode Sets the translation mode of the file associated with a handle.
_sopen Same as _open, but allows setting of access controls.
_tell Returns the position of the file associated with a handle.
unlock Releases file sharing locks on a handle's file.
_write, _writex Performs an unbuffered write to a file.

Buffered Stream I/ O

Buffering means that data are read from and written to files and devices in chunks, rather than one byte at a time. Each chunk is stored in a memory buffer. This method reduces the number of disk accesses needed and speeds up I/ O.

For example, suppose a program needs to read a file a byte at a time. The buffered stream functions retrieve each byte from the buffer in memory, avoiding a disk access for each read operation. Only when the buffer is empty do the functions fetch another chunk from the disk.

Rather than using an integer handle, these functions use a pointer to a structure that contains information about the status of the buffers.

F/V Description
clearerr Clears the error and EOF flags for a stream.
fclose Closes a buffered stream file.
_fcloseall Closes all open buffered streams.
_fdopen Associates an unbuffered file with a buffered stream.
feof True if the stream is at the end of its file.
ferror True if an error was on a stream.
fflush Flushes the buffer associated with a stream.
fgetc Reads the next character from a stream.
_fgetchar Reads the next character from the stdin stream.
fgetpos Saves the current position in the file of a stream.
fgets Reads a string from a stream.
_fileno Returns the unbuffered file handle associated with a stream.
_flushall Flushes the buffers of all open streams.
fopen Opens a file as a buffered stream.
fprintf Formats and outputs a string to a stream.
fputc Writes a character to a stream.
_fputchar Writes a character to the stdout stream.
fputs Writes a string to a stream.
fread Reads an array from a stream.
freopen Closes a stream then reopens it with a new file.
fscanf Reads values from a stream and formats them into a string.
fseek Sets the position of a stream in its file.
fsetpos Resets the position of a stream to a saved value.
_fsopen Like fopen, but allows file sharing controls to be set.
ftell Returns the current position of a stream's file.
fwrite Writes an array to a stream.
getc Reads a character from a stream.
getchar Reads a character from the stdin stream.
gets Reads a string from the stdin stream.
_getw Reads an int from a stream.
printf Formats and prints a string to the stdout stream.
putc Writes a character to a stream.
putchar Writes a character to the stdout stream.
puts Writes a string to the stdout stream.
_putw Writes an int to a stream.
rewind Positions the file associated with the stream at the beginning.
_rmtmp Deletes all temp files created with tmpfile.
setbuf setvbuf Changes the buffer for a stream.
stdaux A stream over the standard auxiliary output.
stderr A stream over the standard error output.
stdin A stream over the standard input.
stdout A stream over the standard output.
stdprn A stream over the standard print output.
tmpfile Creates a temporary file and opens a stream over it.
ungetc Puts a character back into a stream.

Direct Operating System I/O

These functions are similar to the unbuffered, handle-based I/ O functions, but use more direct calls to DOS or Win32. As noted before, DOS INT 21 and Win32 handles must not be interchanged with handles used by direct operating system I/ O functions, nor should handles from these functions be used with the unbuffered, handle-based functions.

F/V Description
_dos_close Calls the OS directly to close a file.
_dos_commit Forces the OS to flush its buffers for a file to disk.
_dos_creat, dos_creat Calls the OS directly to create a file.
_dos_creatnew Same as _dos_creat, but fails if the file exists.
_dos_lock Calls the OS to restrict access to a section of a file.
_dos_open dos_open Calls the OS to open a file.
_dos_read Calls the OS directly to read from a file.
_dos_seek Calls the OS to move the file pointer to a given position.
_dos_setftime Sets the modification time of a file.
_dos_write Calls the OS directly to write to a file.

Console I/O

These low level functions give the program access to the computer display and keyboard, also known as the console. The stream and handle based I/O functions can also be used to read and write from the display and keyboard devices, but the console I/O functions provide more direct control over whether characters are echoed on input, whether a key is available in the keyboard buffer, etc.

There is one DOS console. Windows NT provides any number of consoles. Windows 3.x provides no console; console I/O functions are not available for Windows 3.x.

F/V Description
_kbhit Determines if a keyboard key was pressed.
_ungetch Puts a character back into the keyboard buffer.
_getch Reads a character directly from the console, without echo.
_getche Reads a character directly from the console, with echo.
_putch Writes a character directly to the console.
_cgets Gets a string directly from the console.
_cprintf Formats and prints a string directly to the console.
_cputs Outputs a string directly to the console.
_cscanf Reads and formats values directly from the console.

Interrupt Handling

These functions allow programs to generate and trap 80x86 interrupts. See also the Interrupt Package category.

F/V Description
_chain_intr Passes control from one interrupt handler to another.
_disable Executes the x86 CLI instruction, disabling interrupts.
_dos_getvect, getvect Returns the interrupt handler for the given vector.
_dos_setvect, setvect, Sets the interrupt handler for a given vector.
_enable Executes the x86 STI instruction, enabling interrupts.
geninterrupt Generates a software interrupt.

Interrupt Package

These functions, from Digital Mars, handle interrupts, signals, and errors. An interrupt function can create a stack of a specified size that conforms to constraints of the memory model used. See also the Interrupt Handling category.

F/V Description
int_gen Generates a standard Intel 80x86 interrupt.
int_getvector Gets the interrupt vector.
int_intercept Links a standard C function to an interrupt vector.
int_off Clears the interrupt flag.
int_on Sets the interrupt flag.
int_prev Calls the standard interrupt handler from a previously installed handler.
int_restore Unlinks an interrupt handler.
int_setvector Sets the interrupt vector.

Locale These functions allow programs to easily adapt to the different conventions used in different parts of the world.

F/V Description
country Returns information about a country
localeconv Returns information about the current locale.
setlocale Sets the locale for a category of locale-dependent values.
strcoll Compares two strings based on the current locale's collating sequence.
strftime Formats the date and time for the current locale.
strxfrm Recollates a string for a locale.

Math

Digital Mars C++ provides a large library of math functions.

Calculates n x 2exp.
F/V Description
_8087 Tells if and what kind of floating-point coprocessor is present.
abs Returns the absolute value of an integer.
acos, acosf, acosl Calculates the arc cosine.
arg Determines the angle of a number in a complex plane
asin, asinf, asinl Calculates the arcsine.
atan, atanf, atanl Calculates arc tangent.
atan2, atan2f, atan2l Calculates arc tangent of y/ x.
_cabs, _cabsl Calculates the absolute value of a complex number.
ceil, ceilf, ceill Returns a number rounded up.
_clear87 Returns and clears the floating-point coprocessor status
_control87 Gets and sets the floating-point coprocessor status.
copysign, copysignf, copysignl Copies the sign bit of one number to another.
cos, cosf, cosl Calculates the cosine.
cosh, coshf, coshl Calculates the hyperbolic cosine.
div Calculates the quotient and remainder of division.
exp, expf, expl Calculates the value of e raised to the power of x.
expm1, expm1f, expmll Calclulates the value of e raised to the power of x-1.
fabs, fabsf, _fabsl Returns the absolute value of a floating-point number.
feclearexcept Clears the specified exception.
fegetenv Gets the current floating-point environment.
fegetexcept Gets the exception.
fegetprec Returns the current precision mode.
fegetround Returns the current rounding mode.
feprocentry Resets the floating-point environment to the start-up state.
feprocexit Saves and raises the exceptions.
feraiseexcept Raises the specified exception.
fesetenv Sets the current floating-point environment.
fesetexcept Sets the exception flag.
fesetprec Sets the precision mode
fesetround Sets the rounding mode.
fetestexcept Determines if an exception was raised.
floor, floorf, floorl Returns a number rounded down.
fmod, fmodf, fmodl Calculates the floating-point remainder.
_fpreset Reinitializes floating-point functions.
frexp, frexpf, _frexpl Breaks a number into mantisa and exponent.
_hypot, _hypotl Calculates the length of a hypotenuse.
labs Returns the absolute value of a long integer.
ldexp, ldexpf, _ldexpl
ldiv Returns the quotient and remainder of division of long integers.
log, logf, logl Calculates the natural logarithm.
log10, log10f, log10l Calculates the base-10 logarithm.
log1p, log1pf, log1pl Calculates the natural logarithm of 1 + x.
_lrot Returns the binary left rotation of a long integer.
_lrotr Returns the binary right rotation of a long integer.
matherr, _matherrl Handles math errors; is user-written.
__max Returns the larger of two numbers.
__min Returns the smaller of two numbers.
modf, modff, _modfl Breaks a number into its integral and fractional parts.
nearbyint, nearbyintf, nearbyintl Rounds a number to the nearest integer.
nextafter, nextafterf, nextafterl Calculates the next representable value after a number.
norm Calculates the square of an absolute.
polar Returns a complex number of magnitude and angle.
poly, polyl Evaluates a polynomial.
pow, powf, powl Calculates xraised to a power of y.
remainder, remainderf, remainderl Calculates the remainder of x/ y.
remquo, remquof, remquol Same as remainder but also computes the quotient.
rint, rintf, rintl Rounds to the nearest integer.
rndtol, rndtonl Rounds a double to a long.
_rotl, _rotr Returns the binary left or right rotation of an integer.
round, roundf, roundl Rounds to the nearest integer.
scalb, scalbf, scalbl Calculates x * FLT_RADIXn.
scanf Reads and formats values from the stdin stream.
signbit Returns the sign bit of a floating-point number.
sin, sinf, sinl Calculates the sin.
sinh, sinhf, sinhl Calculates the hyperbolic sine.
sqrt, sqrtf, sqrtl Returns the square root.
_status87 Gets the floating-point status word
tan, tanf, tanl Calculates the tangent.
tanh, tanhf, tanhl Calculates the hyperbolic tangent.
trunc, truncf, truncl Truncates the fractional portion of a number.

Memory Buffer These functions operate on arrays of characters, much like the string functions, but do not assume a terminating null character.

F/V Description
_memccpy, _fmemccpy Copies one buffer to another up to a particular character.
memchr, _fmemchr Returns the index of a character in a buffer.
memcmp, _fmemcmp Compares two buffers.
memcpy, _fmemcpy, movmem Copies one buffer to another.
_memicmp, _fmemicmp, _nmemicmp Compares two buffers, ignoring case.
memmove, _fmemmove Copies one buffer to another correctly even if they overlap.
memset, _fmemset, setmem Fills a buffer with a value.

Memory Management

Digital Mars C++ provides two kinds of memory management, program memory management and operating system memory management.

Program Memory Management
A C program can provide its own memory management, separate from the operating system. The program memory management functions obtain only large chunks of memory from the operating system. They then dole it out in smaller blocks as needed by the application. This is faster because it avoids the overhead of making a call to the operating system for each little bit of memory needed. The program's pool of memory is called a heap.

For DOS and Windows 3. x programs, the situation is complicated by the 80x86 architecture, which has two kinds of pointers to memory: near pointers and far pointers. Near pointers are small and efficient but can access only 64K bytes at a time. Far pointers are less efficient but can access the entire memory space, up to one MB for real mode. Because of this, DOS and Windows 3. x have two heaps: a smaller near one and a larger far one. Phar Lap and Win32 programs have only one heap.

DOS and Windows 3.x usually have three versions of each memory management function:

° A plain function that accesses whichever heap, near or far, is the default for the memory model. An example is malloc, which allocates from one heap or the other, depending on the memory model. The default for the S and M models is near; the default for L and C is far.

° A near function that accesses the near heap (and begins with _n). An example is _nmalloc.

° A far function that accesses the far heap (and begins with _f). An example is _fmalloc.

Phar Lap and Win32 have only a plain function. For example, malloc allocates from the heap. Functions _nmalloc and _fmalloc are not available.

F/V/Description
_alloca
Dynamically allocates memory on the program stack.
calloc
Allocates and clears memory for an array. coreleft Returns amount of RAM not in use.
_expand
Increases the size of a memory block if possible.
_fcalloc
Allocates and clears memory for an array in the far program heap.
_ffree
Releases a block back to the far program heap.
_fmalloc
Allocates memory from the far program heap.
_fmsize
Returns the size of a far program heap memory block.
free
Releases a block back to the program heap.
_freect
Returns the number of blocks available in the near heap.
_halloc
Allocates a huge block of memory.
_hfree
Releases a huge block back to the program heap.
hugeptr_add
Adds a value to a huge pointer.
hugeptr_cmp
Compares two huge pointers.
hugeptr_diff
Returns the difference of two huge pointers.
malloc
Allocates a block of memory from the program heap.
_memavl
Returns the memory available in the near program heap.
_memmax
Returns the size of the largest free block in the program's near heap.
_msize
Returns the size of an allocated block in the program heap.
_ncalloc
Allocates an array from the near program heap and clears it.
_nfree
Releases a block back to the near program heap.
_nmalloc
Allocates a block from the near program heap.
realloc
Resizes an allocated block in the program heap.
_set_new_handler
Sets a user routine for handling failures of the C++ new operator.
_stackavail
Returns the amount of stack space available from _alloca.
_strdup, _fstrdup
Allocates memory for a string and copies the string to it.

Operating System (OS) Memory Management
These functions call the operating system (DOS, Phar Lap, Windows 3. x, or Win32) directly to dynamically allocate and free memory blocks. The function descriptions list compatible operating systems.
F/V/Description
allocmem
Allocates a memory block from the OS.
dos_alloc, _dos_allocmem
Allocates a memory block from the OS.
dos_avail
Returns the amount of memory available from the OS.
dos_calloc
Allocates, clears a memory block from the OS.
dos_free, _dos_freemem
Frees a memory block allocated from the OS.
_dos_setblock, dos_setblock, setblock
Calls the OS to resize a block of memory.
farcalloc
Allocates and clears an array from the OS far heap.
farcoreleft
Returns the largest memory block left in the OS far heap.
farfree
Frees memory allocated from the OS far heap.
farmalloc
Allocates memory from the OS far heap.
farrealloc
Resizes a memory block allocated from the OS far heap.
freemem
Releases an OS memory block.

Mouse Package

These functions interface to the Microsoft mouse and require that a Microsoft compatible mouse driver be installed. See the manual that accompanies the mouse. Two of the functions enable the mouse to emulate a lightpen.

F/ V Description
msm_condoff
Defines a rectangular area of the screen in which the mouse cursor is hidden.
msm_getpress
Gets button press information.
msm_getrelease
Gets button release information.
msm_getstatus
Gets status of the mouse cursor.
msm_hidecursor
Hides the cursor.
msm_init
Initializes the mouse driver.
msm_lightpenoff
Disables light pen emulation mode.
msm_lightpenon
Enables light pen emulation mode.
msm_readcounters
Reads mouse motion counters.
msm_setareax
Sets cursor's minimum and maximum horizontal position.
msm_setareay
Sets cursor's minimum and maximum vertical position.
msm_setcurpos
Sets cursor position.
msm_setgraphcur
Sets graphic cursor.
msm_setratio
Sets the motion counter/ pixel ratio (mouse sensitivity).
msm_settextcur
Sets text cursor.
msm_setthreshhold
Sets the speed threshhold.
msm_showcursor
Shows the cursor.
msm_signal
Sets input mask.
msm_term
Terminates mouse drive.

Multi-byte Characters

These functions provide conversions between multi-byte characters and wide characters.

F/ V Description
mblen, _fmblen
Returns the number of bytes in a multi-byte string.
mbstowcs, _fmbstowcs
Converts a multi-byte character string to a wide character string.
mbtowc, _fmbtowc
Converts a multi-byte character to a wide character.
wcstombs, _fwcstombs
Converts a wide character string to a multi-byte string.
wctomb, _fwctomb
Converts a wide character to a multi-byte character.

Multi-Threaded Processing

These functions and multi-threaded processing are available for Win32 programs only.

F/ V Description

_beginthread
Begins execution of a new program thread.
_endthread
Destroys a program thread.
_threadid
The current thread identification.

Operating System and Windows Versions

These variables contain the version number of the operating system and Windows under which the program is running.

Variable/Description
_osmajor
The major portion of the OS version number
_osminor
The minor portion of the OS version number.
_osmode
What OS is running: DOS or Windows.
_osver, _osversion
The major and minor portions of the OS version number.
_winmajor
The major portion of the Windows version number.
_winminor
The minor portion of the Windows version number.
_winver
The major and minor portions of the Windows version number.

Page Package

These functions create and manipulate memory from the page heap. They require a far pointer to the page heap.

F/V/Description
page_calloc
Clears and allocates memory.
page_free
Frees memory.
page_initialize
Initializes memory.
page_malloc
Allocates memory.
page_maxfree
Determines the largest free block.
page_realloc
Reallocates memory.
page_size
Determines size of block.
page_toptr
Converts a pointer to a page heap.

Path Names

These functions manipulate path names.

fnmerge, _makepath
Builds a path name from a drive, directory, filename, and extension.
fnsplit, _splitpath
Breaks a pathname into a drive, directory, filename, and extension.
_fullpath
Converts a relative path name to a fully qualified path name.
_mktemp, _tempname, tmpnam
Generates a unique temporary filename.
parsfnm
Breaks a path name into a file control block.

Process Control

These functions and variables control execution of processes.

F/V/Description
abort
Terminates the currently executing process.
atexit, _fatexit, _onexit, _fonexit
Specifies a function to be called on program exit.
_c_exit
Performs partial C runtime termination without exiting.
_cexit
Performs full C runtime termination without exiting.
_execl, _execle, _execlp, _execlpe, _execv, _execve, _execvp, _execvpe
Replaces the current process with a new child process.
exec_showget
Gets whether a child Windows process will show.
exec_showreset
Resets whether a child Windows process will show.
exec_showset
Sets whether a child Windows process will show.
_exit
Performs partial C runtime termination and exits.
exit
Performs full C runtime termination and exits.
exit_popstate, exit_pushstate
Converts a stand-alone program to a subroutine.
_fileinfo
If true, current open file information passes to the child processes.
_getpid
Returns the current process identification.
getpsp
Returns the program segment prefix of the current process.
longjmp
Jumps to an earlier point in the program.
msleep
Suspends a process for a number of milliseconds.
_pgmptr
The pathname of the executing program.
_psp
The program segment prefix of the process.
raise
Raises a signal to the process.
response_expand
Expands command line arguments that reference files.
setjmp
Sets a point in the program to jump back to.
signal
Defines how signals are handled.
Suspends process execution for a number of seconds.
_spawnl,_spawnle, _spawnlp, _spawnlpe, _spawnv,_spawnve, _spawnvp, _spawnvpe
Starts a new child process and waits for it to exit.
system
Passes a string to the OS for execution.
usleep
Suspends execution of the program for a number of microseconds.
wait
Returns the code of a child process.

Random Numbers

These functions return, initialize, or set random numbers.

F/V/Description

rand, random
Returns a rand number.
randomize
Initializes the random number seed to the current time.
srand
Sets the random number see.

Sorting and Searching

These functions sort and search tables.

F/V/Description
bsearch
Performs a binary search of a sorted array.
_lfind
Performs a linear search of an array.
_lsearch
Performs a linear search of an array, with automatic insert.
qsort
Performs a quick-sort of a table.

Sound

These functions output sound from the PC speaker. They work only on machines that are compatible with the IBM PC hardware and software.

F/V/Description
sound_beep
Outputs a beep.
sound_click
Outputs a click.
sound_note, sound_tone
Outputs a tone.
Strings, Null-terminated

These functions operate on null-terminated strings.

F/V/Description

_snprintf
Formats values into a string of fixed size.
sprintf
Formats values into a string.
sscanf
Reads and formats values from a string.
stpcpy
Copies one string to another and returns the result.
strcat, _fstrcat, strncat, _fstrncat
Concatenates strings.
strchr, _fstrchr, strcspn, _fstrcspn
Returns the index of a character in a string.
strcmp, _fstrcmp, strncmp, _fstrncmp
Compares two strings.
_strcmpi, strcmpl, _fstrcmpl, _stricmp, _fstricmp, strncmpi, strncmpl, _strnicmp, _fstrnicmp
Compares two strings, ignoring case.
strcpy, _fstrcpy, strncpy, _fstrncpy
Copies one string to another.
strlen, _fstrlen
Returns the string length.
_strlwr, _fstrlwr
Converts uppercase characters to lowercase.
_strnset, _fstrnset, _strset, _fstrset
Fills a string with the specified character.
strpbrk, _fstrpbrk
Searches for characters from one string in another.
strrchr, _fstrrchr
Returns the last of a character in a string.
_strrev, _fstrrev
Reverses a string.
strspn, _fstrspn
Searches for characters from one string that are not in another.
strstr, _fstrstr
Returns the index of one string within another.
strtok, _fstrtok
Breaks a string into tokens.
_strupr, _fstrupr
Converts lowercase characters to uppercase.
_swab
Swaps bytes in a string.
unmangle_ident
Unmangles a C++ mangled identifier.

String and Numeric Conversions

These functions convert between various C numeric types and strings:

F/V/Description
atof
Converts a string to a double.
atoi
Converts a string to an integer.
atol
Converts a string to a long.
_atold
Converts a string a long double.
_ecvt, _fcvt, _gcvt
Converts a double to a string.
_itoa
Converts an integer to a string.
_ltoa
Converts a long to a string.
strtod
Converts a string to a double.
strtof
Converts a string to a float.
strtol
Converts a string to a long integer.
_strtold
Converts a string to a long double.
strtoul
Converts a string to an unsigned long.
_ultoa
Converts an unsigned long to a string.

Swap Package

These functions move a spawned program's memory image to a temporary disk file.

F/V/Description
swap_clearkeyboardoff, swap_clearkeyboardon
Turns clear keyboard buffer feature off/ on.
swap_freeparagraphs
Frees paragraph memory for a spawned process.
swap_freeparagraphsoff, swap_freeparagraphson
Turns swap_freeparagraphs function off/ on.
swap_isclearkeyboardon, swap_isfreeparagraphson, swap_ison, swap_ispipeon, swap_istempcheckon, swap_istrapcbreakon, swap_iswindowon
Returns the flag status of configurable features.
swap_off, swap_on
Turns swapping off/ on.
swap_pipe
Copies the output of a spawned program to a specified file.
swap_pipeoff, swap_pipeon
Turns swap_pipe off/ on.
swap_tempcheckoff, swap_tempcheckon
Checks the TEMP or TMP environment variable which points to the directory that saves a memory image.
swap_trapcbreakoff, swap_trapcbreakon
Turns control-c trapping off/ on.
swap_window
Specifies a screen area to display output from a spawned program.
swap_windowoff, swap_windowon
Turns swap_window off /on.

Tab Package

These functions control the tab size.

F/V/Description
tab_sizeget
Gets current setting of global tab size.
tab_sizegetenv
Gets the tab environment variable.
tab_sizeputenv
Defines the tab environment variable.
tab_sizeset
Sets the global tab size.

Terminate and Stay Resident Package

The Terminate and Stay Resident (TSR) functions are useful in programs that can optionally reside in memory or run as a background process.

F/V/Description
tsr_install
Loads the program into memory.
tsr_service
Provides compatibility with other TSRs.
tsr_uninstall
Removes the program from memory.

Time and Date

These functions and variables access the system time, convert from one time format to another, and perform other operations regarding the time and date. UCT is Universal Coordinated Timezone.

F/V/Description
asctime
Formats a time as a string.
clock
Returns the time since the program started.
ctime
Formats a time value as a string.
_daylight
True if the current time zone has a daylight savings time.
difftime
Returns the difference of two times.
_dos_setdate
Sets the system date.
_dos_settime
Sets the system time.
_ftime,_dos_gettime, gettime
Returns the current system time.
getdate, _dos_getdate
Returns the current system date.
gmtime
Returns the current time in the UCT.
localtime
Converts a time to the local time.
mktime
Converts a local time to a time.
stime
Sets the systems date and time.
_strdate
Formats the date as a string.
_strtime
Formats the time as a string.
time
Returns elapsed time in seconds from a standard point in time.
_timezone
The difference in seconds between UCT and the current time zone.
_tzname
The name of the current time zone and daylight saving timezone.
_tzset
Resets _tzname, _daylight, _timezone.

Variable Numbers of Function Arguments

Any C function declared __cdecl (the default) can potentially have a variable number of arguments. C functions declared __pascal cannot. The following functions access variable arguments.

F/V/Description
va_arg, va_end, va_start
Allows access to variable numbers of arguments to a function.
vfprintf
Formats and prints a variable argument list to a stream.
vprintf
Formats and prints a variable argument list to the stdout stream.
_vsnprintf
Formats a variable argument list to a string of set length.
vsprintf
Formats a variable argument list to a string.

WINIO (WINDOS) Package

WINIO functions provide a DOS-like procedure based wrapper over event-driven Windows 3 application code. WINIO is sometimes called WINDOS. See also Appendix D, The WINIO Library.

F/V/Description
fail
Displays message/ terminates WINIO.
ungets
Pushes a string into the input stream.
winio_about
Edits an About dialog text.
winio_bufsize
Gets a window's buffer size.
winio_clear
Clears a window's buffer size.
winio_close
Closes the window.
winio_closeall
Closes all WINIO application windows.
winio_current
Gets the current window's handle.
winio_defwindowsize
Sets default window size.
winio_end
Signals that task is terminating.
winio_getinfo
Gets window information.
winio_hmenufile
Modifies File menu.
winio_hmenuhelp
Modifies Help menu.
winio_hmenumain
Modifies main menu.
winio_home
Positions cursor to home.
winio_init
Initializes WINIO.
winio_onclose
Handles window closings.
winio_onpaintentry
Initializes Graphic Display Interface.
winio_onpaintexit
Releases Display Context.
winio_openwindows
Returns number of open windows.
winio_resetbusy
Releases cursor.
winio_setbufsize
Sets the window's buffer size.
winio_setbusy
Blocks user input.
winio_setcurrent
Changes the current window.
winio_setecho
Controls echoing to stdout.
winio_setfont
Sets a window's font.
winio_setlinefn
Installs a handler invoked by double-clicking line of text.
winio_setmenufunc
Installs a handler invoked by selecting a menu item.
winio_setpaint
Turns on/ off automatic display update.
winio_settitle
Changes title bar text.
winio_warn
Displays message box.
winio_window
Creates additional windows.
wmhandler_create
Initializes WM_handler table.
wmhandler_destroy
Frees memory allocated by wmhandler_create.
wmhandler_get
Gets message handling function.
wmhandler_hwnd
Creates internal WMHANDLER window.
wmhandler_set
Installs message handler.
wmhandler_wndproc
Implements message switching protocol.
wmhandler_yield
Receives and sends messages.

X Memory Model

The X386 functions are implemented for the X memory model only.

F/V/Description
_x386_coreleft
Returns largest free memory block.
_x386_free_protected_ptr
Frees a protected pointer.
_x386_get_abs_address
Gets the absolute address.
_x386_map_physical_address
Maps the physical address.
_x386_memlock
Locks memory region in virtual memory environment.
_x386_memunlock
Unlocks memory region in virtual memory environment.
_x386_mk_protected_ptr
Returns a protected pointer.

Copyright © 1995-2001 Digital Mars. All Rights Reserved.