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:

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

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

Copyright © 1999-2018 by Digital Mars ®, All Rights Reserved | Page generated by Ddoc.