digitalmars.com                      
Last update Sat Jun 18 16:54:33 2011

Digital Mars C++ Runtime Library Reference

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:

Special Results table 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.

80x86
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.

BIOS
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.

Characters
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.
Character Conversion
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.

Complex
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.

Control-Break Handling
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.

Directory and Disk Drive
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.

Display
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.

DOS
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.

Environment
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.

Error Handling
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.

EMM Functions
F/V Description
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.

Files
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.

Handles
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.

Handle I/O
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.

Stream I/O
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.

DOS I/O
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.

Console I/O
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.

Interrupt Handling
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.

Interrupt Package
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.

Locale
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.
Math
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.

Memory Buffer
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:

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

Memory Management
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.

OS Memory Management
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.

Mouse
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.

Multibyte 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.

Multithreaded Processing
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.

OS and Windows Versions
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.

Page
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.

Paths
F/V Description
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.

Process Control
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.
sleep 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.

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.

Sorting and Searching
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.

Sound
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.

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.

String and Numeric Conversions
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.

Swap
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.

Tabs
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.

TSR
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.

Time and Date
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.

Variadic Function 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.

WINIO
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.

X Memory Model
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.
Home | Compiler & Tools | IDDE Reference | STL | Search | Download | Forums