Borland C++ Help Contents

Click the icon above to open all folders. Click an icon below to open a folder or click the underlined text to see a specific topic.

	What's New? presents new features of this version of Borland C++.
	Integrated Development Environment provides Help on using the Borland C++ IDE.
	Tools Reference that includes both Windows and command-line utilities.
	Tasks with step-by-step directions for using Borland C++ tasks and its utilities.
	Language Reference for Borland C++ language elements and error messages.
Shortcut:	Use the Search and Search All buttons at the top of the Help window if you are ready to look for an item by name.


Borland C++ Help Contents

Click the icon above to open all folders. Click an icon below to open or close a folder. Click the underlined text to see a specific topic.

	What's New? presents new features of this version of Borland C++.
	Integrated Development Environment provides Help on using the Borland C++ IDE. AppExpert Browser ClassExpert Editor Environment Options Error Messages and Warnings Integrated Debugger Keyboard Menu Commands Message Window Project Hierarchy Project Options SpeedBar SpeedMenus Style Sheets
	Tools Reference that includes both Windows and command-line utilities.
	Tasks with step-by-step directions for using Borland C++ tasks and its utilities.
	Language Reference for Borland C++ language elements and error messages.
Shortcut:	Use the Search and Search All buttons at the top of the Help window if you are ready to look for an item by name.


Borland C++ Help Contents

Click the icon above to open all folders. Click an icon below to open or close a folder. Click the underlined text to see a specific topic.

	What's New? presents new features of this version of Borland C++.
	Integrated Development Environment provides Help on using the Borland C++ IDE.
	Tools Reference that includes both Windows and command-line utilities. Compiling and Linking Customizing the Editor Building Resources Debugging Utilities Miscellaneous Utilities
	Tasks with step-by-step directions for using Borland C++ tasks and its utilities.
	Language Reference for Borland C++ language elements and error messages.
Shortcut:	Use the Search and Search All buttons at the top of the Help window if you are ready to look for an item by name.


Borland C++ Help Contents

Click the icon above to open all folders. Click an icon below to open or close a folder. Click the underlined text to see a specific topic.

	What's New? presents new features of this version of Borland C++.
	Integrated Development Environment provides Help on using the Borland C++ IDE.
	Tools Reference that includes both Windows and command-line utilities.
	Tasks with step-by-step directions for using Borland C++ tasks and its utilities. How To Using the Integrated Debugger Working with Projects
	Language Reference for Borland C++ language elements and error messages.
Shortcut:	Use the Search and Search All buttons at the top of the Help window if you are ready to look for an item by name.


Borland C++ Help Contents

Click the icon above to open all folders. Click an icon below to open or close a folder. Click the underlined text to see a specific topic.

	What's New? presents new features of this version of Borland C++.
	Integrated Development Environment provides Help on using the Borland C++ IDE.
	Tools Reference that includes both Windows and command-line utilities.
	Tasks with step-by-step directions for using Borland C++ tasks and its utilities.
	Language Reference for Borland C++ language elements and error messages. Global Language Elements ObjectWindows Library Standard Libraries DOS only Error Messages and Warnings
Shortcut:	Use the Search and Search All buttons at the top of the Help window if you are ready to look for an item by name.


Borland C++ Help Contents

Click any icon to close all folders or click the underlined text to see a specific topic.

	What's New? presents new features of this version of Borland C++.
	Integrated Development Environment provides Help on using the Borland C++ IDE. AppExpert Browser ClassExpert Editor Environment Options Error Messages and Warnings Integrated Debugger Keyboard Menu Commands Message Window Project Hierarchy Project Options SpeedBar SpeedMenus Style Sheets
	Tools Reference that includes both Windows and command-line utilities. Compiling and Linking Customizing the Editor Building Resources Debugging Utilities Miscellaneous Utilities
	Tasks with step-by-step directions for using Borland C++ tasks and its utilities. How To Using the Integrated Debugger Working with Projects
	Language Reference for Borland C++ language elements and error messages. Global Language Elements ObjectWindows Library Standard Libraries DOS only Error Messages and Warnings
Shortcut:	Use the Search and Search All buttons at the top of the Help window if you are ready to look for an item by name.


Essentials

How to Use Help

Using Help in Borland C++

What Has Changed in This Release

OpenHelp changes what you know as Windows Help into a flexible tool. You can Search for Topics in more than one Help file, even Help files you've created. By configuring OpenHelp, you can search through everything or just select a range of Help files that meets your immediate need. Finally, a Windows Help engine that bridges the barriers of traditional Windows Help.

What Is New in This Release

TargetExpert now offers you two new standard library choices:

OLE 2 - an operating system extension that lets applications achieve a high degree of integration. OLE provides a set of standard interfaces so that any OLE program can interact fully with any other OLE program.

OCF (ObjectComponents Framework) - ObjectComponents classes for simplifying the creation of OLE 2 applications in C++. ObjectComponents implements a set of high-level interfaces on top of OLE.

The new Quad Word Alignment option (Options|Project|16-bit Compiler or 32-bit Compiler|Processor) tells Borland C++ to align non-character data (within structs and unions only) at 64-bit word (8-byte) boundaries. Command-line users can use -a8.

The new User-defined warnings option lets you display user-defined messages in the IDE's Message Window. Messages or warnings are introduced with #pragma message. From the command-line, use -wmsg to turn on and off the user-defined messages.

Choose the Pentium option (Options|Project|32-bit Compiler|Processor) to generate Pentium instructions running in enhanced-mode Windows.

The Treat 'far' classes as 'huge' option option was added (Options|Project|32-bit Compiler|Processor) to let users instruct the compiler to treat all __far classes as __huge.

Use ClassExpert to automate your existing applications with OLE 2 automation.

Use AppExpert to generate OLE 2 server and container applications.


Language Reference (by Category)
Language Reference

Global Language Elements

Class Diagnostic Macros

Exception Handling (C Structured Exceptions)

Exception Handling (C++)

Dynamic-link Libraries

Global Variables

Header Files

Keywords

main( )/WinMain( ) function

Operators

Predefined Macros

Preprocessor Directives

Run-time Support

Templates

Utility Classes

Virtual Classes

Virtual Functions

ObjectWindows Library

ObjectWindows 2.5 informational topics

ObjectWindows Library

ObjectWindows Library Constants

ObjectWindows Library Macros

ObjectWindows Library Typedefs

ObjectWindows Library Functions

ObjectWindows Library Enums

Standard Libraries

Container Classes

Default Run-time Libraries

Dynamic-link Libraries

Function Cross Reference

Functions by Name

I/O Streams

International API

Mathematical Classes

Reasons to Access the Run-time Library Source Code

Static Run-time Libraries

Streamable Classes

DOS only

Functions

Global Variables

Graphics Routines (Borland Graphics Interface)

Interface Routines

Memory Routines

Miscellaneous DOS Routines

Run-time Libraries

Error Messages and Warnings

Error Messages

Shortcut: 	Use the Search button at the top of this Help window if you are ready to look for something by name.


Tasks

How To:

Browse through your code

Build libraries

Convert DOS applications to Windows

Create a large library

Create extended dictionaries

Debug in the IDE

Deleting a Class with ClassExpert

Do exception handling in C++

Generate Windows applications

Importing a Class with ClassExpert

Increase TLINK capacity

Manage classes in Windows applications

Moving a Class with ClassExpert

Rearrange application windows

Rebuild your project database

Rebuilding the .APX Database File

Renaming an AppExpert Element

Switch to another application

Use case-sensitive symbols in a library

Use IMPDEF The Module-Definition File Manager

Use IMPLIB

Use ObjectWindows 2.5

Use Style Sheets

Use templates

Use TLIB response files

Use TLIB

Using Rescan to Rebuild Your Project Database

Using the Integrated Debugger

Evaluating expressions

Examining register values

Fixing syntax errors

Generating debugging information

Inspecting data elements

Modifying variables

Setting breakpoints

Stepping over code

Tracing into code

Watching

Working with Projects

Add a new target

Build part of a project

Close a project

Compile a project

Convert old projects

Create a multiple target project

Create a new project

Create an AppExpert project

Display or not display node information

Display or not display nodes

Edit the project hierarchy

Generate a MAKE file for a project

MAKE all targets

Manage a project

Open a project

Rebuild files in a project

Rebuild your project database

Reference copy nodes

Set build attributes for a node

Set local options

Set node attributes

Share Style Sheets

Share Tools

Specify target types

Use source pools

Use the project hierarchy

View option settings


Integrated Development Environment

AppExpert

Browser

ClassExpert

Editor

Environment Options

Error Messages and Warnings

Integrated Debugger

Keyboard

Managing Projects

Menu Commands

Message Window

Project Options

SpeedBar

SpeedMenus

Style Sheets


Tools

Compiling and Linking

BCC & BCC32 (command-line compilers)

CPP and CPP32 (command-line preprocessors)

IMPDEF

IMPLIB

TLIB (Turbo Librarian)

TLINK and TLINK32 (command-line linkers)

Customizing the Editor

Keymapper

Building Resources

Resource Compiler

Resource Linker

Resource Shell

Resource Workshop

Debugging Utilities

OBJXREF

WinSight

WinSpector

Miscellaneous Utilities

GREP (text search utility)

BGIOBJ (BGI utility)

TRIGRAPH (character generation utility)

VBXGEN (VBX control header file creation utility)


Using Help in Borland C++


What's New in Version 4.5?

See Also

Borland C++ 4.5 provides a variety of new tools and technologies to make your application development even easier and more productive:

OLE 2 Support

ObjectWindows 2.5 adds complete support for OLE 2.0 with high-level classes that build upon ObjectComponents.

ObjectComponents lets you easily enable your applications for linking, embedding, and automation. ObjectComponents supports both OLE 2 containers and servers, radically simplifiing OLE programming for C++ applications, and making it easy to migrate existing applications without rewriting your code from the ground up.

AppExpert has been updated to exploit OLE 2.0.  Use AppExpert to generate OLE 2 server and container applications automatically.

ClassExpert has been updated to exploit OLE 2.0.  Add OLE automation to your existing AppExpert applications. You can now instantiate classes with a right-click of your mouse.

Borland now provides Autogen, a utility for OLE 2.0 automation. Autogen automatically generates a C++ interface for controlling other OLE 2.0 servers from within your applications.

New 32-Bit VBX Support

Migrate your applications to 32-bits without leaving your 16-bit VBX controls behind. Be ready for the next generation of Windows with even less effort!

OpenHelp

OpenHelp changes what you know as Windows Help into a flexible tool. You can Search for Topics in more than one Help file, even Help files you've created. By configuring OpenHelp, you can search through everything or just select a range of Help files that meets your immediate need. Finally, a Windows Help engine that bridges the barriers of traditional Windows Help.

Run Windows Programs from DOS with WinRun

WinRun is a utility that lets you run a Windows program in a DOS box. This utility is especially useful if you need to run Windows programs from a DOS box in order to build certain ObjectWindows OLE-enabled applications. It requires Windows 3.1 Enhanced mode.

Online Documentation

View the entire Borland C++ documentation set online using DynaText. Faster and more powerful than previous online manuals.

Turbo Profiler

Turbo Profiler is back by popular demand! Find bottlenecks in your 16-bit Windows and DOS applications. This new version of Turbo Profiler has an even greater capacity than previous versions.

Optimized Turbo Linker

The Turbo Linker provides new optimizations that produce smaller, higher-performance .EXEs for both 16-bit DOS and Windows.

Improved 32-Bit Compiler

Our improved 32-bit compiler generates code that is up to 50% faster than before.

Just-In-Time Debugging

Just-In-Time Debugging gives TD32 the ability to trap application exceptions (under Windows NT), even when TD32 is not running. If your application encounters an exception, the Windows NT Program Registry can automatically launch TD32. TD32 then displays the source line where the exception occurred.

Compiler Enhancements

The new Quad Word Alignment option  tells Borland C++ to align non-character data (within structs and unions only) at 64-bit word (8-byte) boundaries in 32-bit programs. Command-line users can use -a8.

The new User-Defined Warnings option lets you display user-defined messages in the IDE's Message Window. Messages or warnings are introduced with #pragma message. From the command-line, use -wmsg to turn on and off the user-defined messages.

The Treat 'far' classes as 'huge' option option was added to let users instruct the compiler to treat all __far classes as __huge. (This new option makes it even easier to compile Microsoft Foundation Classes [MFC] using Borland C++.)


See Also

Changes from Version 3.1 to Version 4.0


Changes from Version 3.1 to Version 4.0

See Also

What's Changed in Version 4.0

Borland C++ IDE Menu commands

New and revised keyboard handling

Turbo Debuggers

Keymapper replaces the Turbo Editor Macro Compiler (TEMC)

New and revised Project Manager

What's New in Version 4.0

The IDE now provides SpeedMenus that are available in the following places. Click your right mouse button for easy access to BC4 commands.

Breakpoints Window SpeedMenu

Browser SpeedMenu

Call Stack SpeedMenu

Data Inspector SpeedMenu

Edit Window SpeedMenu

Event Log SpeedMenu

Message Window SpeedMenu

Options Window SpeedMenu

Project Window SpeedMenu

Register Window SpeedMenu

Watch Window SpeedMenu

The Options|Project and Options|Environment commands open a new dialog box where you can set options that affect your project or the IDE.

Projects now utilize Style Sheets. These are sets of options that are either default project settings (the Default Project Options Style Sheet) or settings for individual components of your project.

You can create ObjectWindows-based applications using AppExpert to generate all of the C++ code you need to quickly produce Windows applications.

Use the ClassExpert to manage your ObjectWindows-based  applications. ClassExpert allows to you add, delete, and manage all of the classes and events you want to use in your application.

You can now debug your 16-bit windows programs within the IDE using the Integrated Debugger.

There are now two Turbo Debuggers, one for 16-bit debugging (TDW) and one for 32-bit debugging (TD32). Consult the Turbo Debugger User's Guide and Turbo Debugger online Help for details on specific features. Select TDW and TD32 features for a brief overview of what is new.

Streamable objects (persistent streams), which were previously only available in OWL, are now part of the Borland C++ class library.  They include the following classes:

fpbase

ifpstream

ipstream

ofpstream

opstream

pstream

TStreamableBase (new)

TStreamableClass

TStreamer (new)

The following new classes and functions support exception handling as defined in ANSI:

Bad_cast class

Bad_typeid class

set_new_handler

set_terminate

set_unexpected

terminate

typeinfo class

unexpected

xalloc class

xmsg class

The following new functions have been added to the run time libraries:

_beginthread

_beginthreadNT

cwait

_expand

_fmemmove

_get_osfhandle

_dos_commit

_heapadd

_heapmin

_endthread

_msize

_open_osfhandle

_pclose

_pipe

_popen

wait

Container Class Libraries have changed for Borland C++. All container classes now exploit the exciting templates feature of C++, providing enhanced flexibility in choosing the best underlying data structure for a given container application. You can fine-tune your application by varying the container implementation with minimum recoding.

If you have existing code which uses the non-template-based classes from 3.1, first change the include path to use the header files in \INCLUDE\OBSOLETE, then either use CLASSLIB.LIB from 3.1 or rebuild the old container class library using the makefile in \SOURCE\CLASSLIB.

The Tool menu now allows you to run other programs, tools, and utilities without leaving the Windows IDE. Programs can be standalone (like GREP, Turbo Debugger, or an editor), or they can be translators for nodes in your project. Arguments you specify are passed to the program.

The Options|Tools command now opens the Options Tools dialog box, where you can install or remove programs from the Tools menu, as well as enter parameters, program paths, and titles.

The Options|Style Sheet command accesses the Style Sheets dialog box. where you create, compose, copy, edit, rename, or delete from the list of Style Sheets that are available for your project.

Choose the Pentium option to generate Pentium instructions running in enhanced-mode Windows.

Online Help is available for command-line compiler and linker options.

ObjectWindows version 2.0 is an entirely new ObjectWindows. New features include:

-	Single source 16 to 32-bit portability.

-	Greater encapsulation of the Windows 3.1 and WIn32 API including GDI encapsulation.

-	Message cracking.

-	New high level objects including toolbars and status lines.

-	Exception based safe-guards.

-	Diagnostic options for increased debugging capabilities.

Online Help is available on ObjectWindows in two formats:

-	ObjectWindows Library Reference

-	ObjectWindows Task Topics


See Also

What's New in Version 4.5?


Turbo Debugger Features (New for Version 4.0)

There are three Turbo Debuggers:

Turbo Debugger for Windows for 16-bit Windows debugging

Turbo Debugger 32 for 32-bit Windows debugging

Turbo Debugger for 16-bit DOS debugging

New features include:

Session State Saving

C++ Exception handling

Remote debugging (new for TDW)

Operating system exceptions (TD32)

Attaching to a running process (TD32)

Debugging muti-threaded Windows NT applications (TD32)

Consult the Turbo Debugger documentation for details on specific features.


DPMI Project Platforms


DPMI Target Models


Turbo Vision Library


DPMI Compiler Switches


DPMI Linker Switches


DPMI Advanced New Project Options Defaults


DPMI Compiler Options and the _ _export Keyword


Menu Commands
Borland C++ Menu commands

See Also

The C++ IDE offers everything you need to write, edit, compile, link, run, manage, and debug your programs. The menu bar at the top of the desktop is the gateway to the menus.

To go to the menu bar, press F10 or click anywhere on it.

You can choose any of the following commands on the menu bar:

File menu

Edit menu

Search menu

View menu

Project menu

Debug menu

Tools menu

Options menu

Window menu

Help menu

In addtion to the menu bar, you can choose commands from the Control menu located in the upper left corner of the active window.

Shortcut:	Help for menu commands is also available by highlighting the menu command and pressing F1.


See Also

How to Use Menus

Keyboard


How to Use Menus

You can select a menu command the following ways::

Click the title of the menu you want to pull down, drag the mouse pointer over the menu command you want to choose, and then release the mouse button.

Click the title of the menu you want to pull down and then click the menu command you want to choose.

Press F10, then use the arrow keys to go to the menu you want and use them again to select a command. Press Enter to choose the selected command.

Press Alt and the underlined letter of the menu you want (such as Alt+F for the File menu), use the arrow keys to select a command, then press Enter to choose that command. You can also press the underlined letter of a menu name or command instead of using the arrow keys.

Menu commands are followed by either an ellipsis mark (...), an arrow, or a hot key:

The ellipsis displays a dialog box

The arrow displays another menu

The hot key initiates the command when pressed


OK button

Choose this button to save the selections you made.

If OK is the default button, you can just press Enter to choose it.


Undo Page button

The Undo Page button restores the current screen of options to the settings present when you selected the Options Settings dialog box.


Cancel button

Choose this button to close the dialog box and discard your changes. No changes are saved and no action occurs.

Esc is always a keyboard shortcut for Cancel even if a Cancel button is not available.


Close button

Choose this button to close the dialog box with the current settings.

Esc is always a keyboard shortcut for Close even if a Close button is not available.


Help button

Choose the Help button to get Help about the active window or dialog box.


Network button

Choose this button to connect to a network drive, if available.


Message dialog box

Choose OK to put this message window away.


Load dialog boxes

A load dialog box displays when you choose any of the following menu commands.

Command	Load Dialog Box

File|Open	Open a File

File|Save	Save File As (if a new file has not been saved)

File|Save As	Save File As

Project|AppExpert	New Project

Project|Open Project	Open Project File

Project|New Project	Specify project path, project name, or target name.

Write events to file	Write Event Log To Log File (accessed from the SpeedMenu on the Event Log).

In a Load dialog box, you can

type in a full file name in the File Name input box

display selected files in the File Name list box by choosing a type in the List Files of Type list box. (You can also choose files by typing a partial file name with * or ? wildcards in the File Name input box and pressing Enter.)

choose a selection from a history list of file specifications you entered earlier.

view the contents of different directories by selecting one from the Directories list box. (You can also change directories by typing a directory in the Files Names input box and pressing Enter.)

view the contents of different drives by selecting one in the Drives list box.

connect to a network drive by selecting Network.

File Name

The input box lets you enter the name of the file to open, or a file specification to limit the files that display in the list box.

The list box displays the names of files in the current directory that match the file specification in the input box.

List Files of Type

Lets you select which file types you want displayed.

Directories list box

Lets you select the directory by that contains the files you want.

Drives

Lets you select the drive that contains the files you want.


Load|File Name input box
File Name input box

Enter the name of a file, or supply a partial file name with ? or * wildcards to display selected files in the File Name list box.

This input box has a history list attached to it.

To select a file, choose any of the following actions:

Type in a file name and choose OK or press Enter.

Supply a file specification (such as a partial file name or type  with * and ? wildcards) to display selected files in the File Name list box.

Type in a directory followed by a file name or file specification.

Click the drop-down arrow next to the input box (or Press Alt+Down arrow) to choose a file specification from the history list.

If you are using your keyboard

Press Alt+N to return the cursor to the File Name input box.

Tab to the list box and use the arrow keys to select a file.


Files list box
File Name list box

This list box displays the files in the current diive and directory that match the file-specification in the File Name input box. .

To select a file, double-click on it.

If you are using the keyboard, tab to the File name list box and use the Up or Down arrow to reach the file you want, then press Enter.


List Files of Type

Lets you select which file types you want displayed.

To select a type, click on it.

If you are using your keyboard, press Alt+T and use the arrow keys to select one of the available types, then press Enter.


Directories

Use this list box to change the current directory location of the files displayed.

Double-click directories in the Directories list box to change the current drive.

If you are using your keyboard

Press Alt+D and the first directory in the Directories list box will be outlined.

Use the arrow keys to select the directory you want to open and choose OK or press Enter.

Note:	You can also enter a directory in the File Name input box, to change the current directory.


Directories list box
Drives

This list box displays the drives (and volume labels) available to you.

To select a drive, click on it.

If you are using your keyboard:

Press Alt+V and the first drive in the list box will be outlined.

Use the arrow keys to select the drive you want and press Enter.


History list

If there is a Down arrow icon to the right of an input box, a history list is attached to the input box.

You use the history list to re-enter text that you have already entered.

The history list displays the last 16 selections entered.

To choose an item from the history list, click the item to place it in the the input box, and press Enter.

You can edit any item that you have selected from the history list.

To exit the history list without making a selection, click the Down arrow again (or press Alt+Down arrow), or click anywhere in the desktop outside of the input box and history list.


Grep-like Regular Expressions

The symbols you can use to produce Grep-like regular expressions include:

 ^	A circumflex at the start of the string matches the start of a line.

 $	A dollar sign at the end of the expression matches the end of a line.

  .	A period matches any character.

 *	An asterisk after a string matches any number of occurrences of that string followed by any characters, including zero characters. For example, bo* matches bot, boo, and as well as bo.

 +	A plus sign after a string matches any number of occurrences of that string followed by any characters, except zero characters. For example, bo+ matches bot and boo, but not b or bo.

{ }	Characters or expressions in braces are grouped so that the evaluation of a search pattern can be controlled and so grouped text can be referred to by number.

[ ]	Characters in brackets match any one character that appears in the brackets, but no others. For example [bot] matches b, o, or t.

[^]	A circumflex at the start of the string in brackets means NOT. Hence, [^bot] matches any characters except b, o, or t.

[-]	A hyphen within the brackets signifies a range of characters. For example, [b-o] matches any character from b through o.

  \  	A backslash before a wildcard character tells the C++ IDE to treat that character literally, not as a wildcard. For example, \^ matches ^ and does not look for the start of a line.


Brief Regular Expressions

The symbols you can use to produce BRIEF regular expressions include:

 <	A less than at the start of the string matches the start of a line.

 %	A percent sign at the start of the string matches the start of a line.

 $	A dollar sign at the end of the expression matches the end of a line.

 >	A greater than at the end of the expression matches the end of a line.

  ?	A question mark matches any single character.

 @	An asterisk after a string matches any number of occurrences of that string followed by any characters, including zero characters. For example, bo@ matches bot, boo, and as well as bo.

 +	A plus sign after a string matches any number of occurrences of that string followed by any characters, except zero characters. For example, bo+ matches bot and boo, but not b or bo.

  |	A vertical bar matches either expression on either side of the vertical bar. For example, bar|car will match either bar or car.

  ~	A tilde matches any single character that is not a member of a set.

[ ]	Characters in brackets match any one character that appears in the brackets, but no others. For example [bot] matches b, o, or t.

[^]	A circumflex at the start of the string in brackets means NOT. Hence, [^bot] matches any characters except b, o, or t.

[-]	A hyphen within the brackets signifies a range of characters. For example, [b-o] matches any character from b through o.

{ }	Braces group characters or expressions. Groups can be nested, with the maximum number of 10 groups in a single pattern.

  \  	A backslash before a wildcard character tells the Borland C++ IDE to treat that character literally, not as a wildcard. For example, \^ matches ^ and does not look for the start of a line.


Go to Line Number Dialog Box

Use this dialog box to find a specific line number in your source file.

Enter New Line Number

Specify which line of source code you want to go to.

Enter a specific line number (or use the history list to select a number previously entered), then press Enter (or choose OK).

Note:	The current line number displays in the status line at the bottom of the IDE desktop.


Sorry, No Help Available for that term
Sorry, No Help is Available for that Term

You have attempted to get Language Help in an edit window for a term that the Help system does not recognize. For more information, see Searching for Keywords.


SpeedMenu

Press the right mouse button or press Alt-F10 to display (when available) a small menu of currently active commands.


Expand

To show hidden sub-topics associated with a topic.

A plus (+) sign next to a topic indicates that you can expand it one of the following ways:

click the +

double-click the topic

highlight the topic and press Enter

use the SpeedMenu commands

When expanded, the + changes to a minus (-) sign, and a list of sub-topics displays under the topic.


Collapse

To hide sub-topics displayed under a topic.

A minus (-) sign next to a topic indicates that you can expand it one of the following ways:

click the -

double-click the topic

highlight the topic and press Enter

use the SpeedMenu commands

When a topic is collapsed, the - changes to a plus (+) sign, and the list of sub-topics are hidden.


Control menu

The Control-menu box appears in the upper left corner of the active window. Click it once or press Alt+Spacebar to display the menu. The commands on this menu affect the active window in the Borland C++ IDE.

The desktop as well as each Edit window and dialog box has its own Control menu on which one or more of the following commands are available:

Restore

Move

Size

Minimize

Maximize

Close

Next

Switch to


Control|Restore command
Control | Restore

This command returns the active window to its previous size.

It is only available when the active window is maximized or minimized.


Control|Move command
Control | Move

Use this command to move the active window with the keyboard, rather than by dragging it with the mouse.

Use the arrow keys to move the window and press Enter when you are done.

It is not available when the active window is maximized.

You can also move the window by dragging its title bar.


Control|Size command
Control | Size

Use this command to change the size of the active window with your keyboard.

Use the arrow keys to move the window borders. Press Enter when you are satisfied with the window size.

It is not available if the active window is maximized.


Control|Minimize command
Control | Minimize

This command turns the active window into an icon on the Borland C++ IDE desktop.

It is not available if the active window is already minmized.


Control|Maximize command
Control | Maximize

This command enlarges the active window to full screen size.

It is not available if the active window is already maximized.


Control|Close command
Control | Close

This command closes the active window or, if chosen from the desktop, closes and unloads the C++ IDE from memory.

If you have modified an Edit window and not saved the file, a Save File dialog box appears asking you if you want to save the file before closing.


Control|Next command
Control | Next

This command makes the next open window or icon active.


Control|Switch To command
Control | Switch To

This command displays the Task List dialog box, where you can switch from one application to another and rearrange application windows.


"Save File?" dialog box

This dialog box asks if you want to save the file before closing.

Choose Yes if you want to save the file before closing.

Choose No if you do not want to save the file before closing.

Choose Cancel to cancel the operation and return to your active Edit window.


Task List dialog box

Use this dialog box to switch to another application and rearrange application windows.

Task List list box

All open applications are listed in this box.

Action Buttons

Use the buttons at the bottom of the dialog box to switch to other applications and rearrange application windows.


Task List list box

This window lists all open applications.

To choose an application using the mouse, double-click the application you want.

To choose an application using the keyboard, press the Up or Down arrow keys to highlight the application, then press Enter to choose it.

You can also use the Action Buttons at the bottom of the dialog box to switch to other applications and rearrange application windows.


Action Buttons

Action buttons switch to another application and rearrange application windows.

With the mouse, click the action button you want.

With the keyboard, press Tab to go to the action button, then press Enter.

Switch To

Switches to the application you have selected in the list box.

End Task

Closes the selected application in the list box.

Cancel

Closes the Task List dialog box.

Cascade

Arranges the application windows in an overlap style.

Tile

Arranges the application windows in a tile fashion (side-by-side).

Arrange Icons

Evenly spaces the icons across the bottom of the desktop.


File menu

The File menu provides commands for creating new files, opening existing files, saving files, printing files, and exiting the Borland C++ IDE.

New

Open

Save

Save as

Save all

Print

Printer Setup

Exit

List of closed files


File|New command
File | New

This command opens a new Edit window with the default name NONAMExx.CPP (the xx stands for a number from 00 to 31) and automatically makes the new Edit window active.

NONAME files are used as a temporary edit buffer and the Borland C++ IDE prompts you to supply a new name when saved.

If you load a file into an active edit window that contains an empty NONAME file, the contents of the edit window is replaced.


File|Open command
File | Open

This command displays the Open a File dialog box so you can select a file to load into the Borland C++ editor window. It works the same as the Open Source command on the edit window SpeedMenu.

You can have multiple files open at the same time in the editor, so the Open command does not close any of the editor windows that you have open. (Opening a file, however, replaces an empty NONAME file in an active edit window.)

If you load a file that is already open in an IDE editor window, the Open command loads the updated version and leaves a copy in its original editor window. Subsequent changes are maintained in the both copies.

If you load a file into an active edit window that contains an empty NONAME file, the contents of the edit window is replaced.


File|Save command
File | Save

This command saves the file in the active Edit window to disk. (This command is unavailable if no edit window is active.)

If the file has a default name (such as NONAME00.CPP), the Borland C++ IDE opens the Save File As dialog box so you can rename the file as well as save it in a different directory or on a different drive.

If you use an existing file name to name the file, the C++ IDE asks if you want to overwrite the existing file.

If you want to save all modified files, not just the file in the active Edit window, choose File|Save All.

This command is available only if an Edit window is currently active.


File|Save As command
File | Save As

This command displays the Save File As dialog box, where you can save the file in the active Edit window under a different name, in a different directory, or on a different drive. (This command is unavailable if no edit window is active.)

You can enter the new file name, including the drive and directory.

All windows containing this file are updated with the new name.

If you choose an existing file name, the Borland C++ IDE asks if you want to overwrite the existing file.

This command is available only if an Edit window is currently active.


File|Save All command
File | Save All

This command works just like the Save command except that it saves the contents of all modified files, not just the file in the active Edit window.

This command is disabled if no Edit windows are open.


File|Print command
File | Print

See Also

This command displays the Printer Options dialog box which lets you print the contents of the active edit window.

Printer Options

Header/Page Number	Includes the name of the file, current date, and page number at the top of each page.

Line Numbers	Places line numbers in the left margin.

Syntax Print	Uses bold, italic, and underline characters to indicate elements with syntax highlighting.

Use Color	Prints colors that match colors on the screen (requires a color printer).

Wrap Lines	Uses multiple lines to print characters beyond the page width. If not selected, code lines are truncated and characters beyond the page width do not print.

Left Margin	Specifies the distance between the left edge of the page and the beginning of each line. For example, enter

 	2	to print with a two-character left margin

 	5	to print with a five-character left margin

The Print command is disabled if an Edit window is not currently active or no printer can be detected.


See Also

SyntaxHighlighting


File|Printer Setup command
File | Printer Setup

This command displays the system Printer Setup dialog box where you select which printer you want to use for printing with the Borland C++ IDE.

This command is disabled if no printer can be detected.


File|Exit command
File | Exit

This command exits the Borland C++ IDE and removes it from memory.

If you modified a source file without saving it, the IDE prompts you to do so before exiting.


File|(List of closed files)
List of closed files (File menu)

The last five files closed during your editing session in the Borland C++ IDE appear at the bottom of the File menu so you can quickly reopen them.

Choose a file name at the bottom of the File menu to reopen it. When reopened, the file is removed from the list of closed files.

The IDE remembers screen placement and cursor location of files in the closed file list.


Edit menu

The Edit menu provides commands to undo, redo, cut, copy, paste, and clear text in edit windows. You can also open a Clipboard window to view or edit its contents, and copy text from Message, Output, and Help windows.

Undo command

Redo command

Cut command

Copy command

Paste command

Clear command

Select All

Buffer List


Edit|Undo command
Edit | Undo

This command restores the file in the current window to the way it was before your most recent edit or cursor movement.

Undo inserts any characters you deleted, deletes any characters you inserted, replaces any characters you overwrote, and moves your cursor back to a prior position.

If you undo a block operation, your file will appear as it was before you executed the block operation.

The Undo command will not change an option setting that affects more than one window or reverse any toggle setting that has a global effect; for example, Ins/Ovr.

This command is available only if an Edit window is currently active and there is something to undo.


Edit|Redo command
Edit | Redo

This command reverses the effect of the most recent Undo command.

Redo only has an effect immediately after an Undo command or another Redo command.

A series of Redo commands reverses the effects of a series of Undo commands.

This command is available only if an Edit window is currently active and there is something to redo.


Edit|Cut command
Edit | Cut

This command removes the selected text from your document and places the text in the Clipboard.

You can then choose Edit|Paste to paste the cut text into any other document (or somewhere else in the same document).

You can paste the cut text as many times as you want until you choose Edit|Cut or Edit|Copy.

This command is available only if an Edit window is currently active and text has been marked for selection.


Edit|Copy command
Edit | Copy

This command leaves the selected text intact and places an exact copy of it in the Clipboard.

To paste the copied text into any other document, choose Edit|Paste.

To copy text from a Help window, display the text you want to copy, then select Edit|Copy. The entire contents of the window is copied to the Clipboard.

If the Message window is the active window, the entire contents of the window gets copied to the Clipboard.

This command is only available if either

an Edit window is currently active and text has been marked for selection.

the Message window is currently active and contains one or more messages.


Edit|Paste command
Edit | Paste

This command inserts the contents of the Clipboard into the current window at the cursor position.

This command is available only if an Edit window is currently active and there is something to paste.


Edit|Clear command
Edit | Clear

This command removes the selected text but does not copy it to the Clipboard.

This means you cannot paste the text as you could if you had chosen Edit|Cut or Edit|Copy.

Although you cannot paste the cleared text, you can undo the Clear command with Edit|Undo.

Clear is useful if you want to delete text, but you do not want to overwrite text held in the Clipboard.

This command is available only if an Edit window is currently active and text has been marked for selection.


Edit|Select All command
Edit | Select All

This command selects the entire contents of the active Edit window.

You can then use Edit|Copy or Edit|Cut to copy it to the Clipboard, or perform any other editing action.

This command is available only if an Edit window is currently active.


Edit|Buffer List command
Edit | Buffer List

This command opens the Buffer List which lets you load a buffer into an edit window.

Buffer List

The Buffer List displays a list of buffers. If a file has been changed since it was last saved, the label (modified) appears after the filename.

Use the Buffer List to replace the contents of an edit window without closing the original file. If the file you replace is not loaded in another edit window, it is hidden. You can then later use the buffer list to load the hidden buffer into an edit window.

Use the buttons on the Buffer List to perform the following actions:

Edit	Opens the selected buffer in the active edit window, or

 	if an edit window is not active and

you select a buffer currently viewed in an edit window, that window is brought to the foreground. If the window is minimized, it is restored.

you select a buffer currently hidden, it is loaded into a new edit window.

Save	Writes the selected buffer to disk. Its status changes to unmodified and the label (modified) goes away.

Delete 	Removes the selected buffer from memory, unless it is loaded in an Edit window. If the buffer is loaded, the IDE prevents you from deleting it and the status line displays the message, Buffer is viewed or in use.

If the buffer is not loaded in an Edit window, but has been modified since it was last saved, the IDE prompts you to either save the file or delete it from the buffer list without saving.

Close	Closes the Buffer List dialog.

Help	Displays this Help topic.


Buffer

A file loaded into memory which may or may not be currently loaded in an edit window. Closing a window that contains the only view of a file also closes the buffer.


Search menu

The Search menu provides commands to search for text and error locations in your files.

Find

Replace

Search Again

Browse Symbol

Locate Function

Previous message

Next message


Search|Find command
Search | Find

This command displays the Find Text dialog box, where you type in the text you want to search for.

You can set several options in this dialog box that affect the search.

Dialog Box Options

Use the Find Text dialog box to specify the text you want to search for.

Text to Find

The Text to Find input box is where you enter the search string. Choose OK to begin the search, or choose Cancel to dismiss it.

Press the Down arrow key or press Alt+Down arrow to display the history list associated with the input box.

Options

This group of options governs the kind of strings that the editor searches for.

Direction options

The Direction options specify which way you want the editor to search, starting from the current cursor position. Forward (from the current position to the end of the file) is the default.

Scope

The Scope options determine how much of the file the editor searches in. Global (entire file) is the default scope.

Origin options

Origin specifies where the search should start.


Text to Find

Use this area to enter a search string.

To begin the search, choose OK; choose Cancel to dismiss it.

To enter a string that you've searched for previously, press Alt+Down arrow to show the history list,, then choose from that list.

You can also pick up the word that your cursor is currently on in the edit window and use it as the search string; simply invoke Find from the Search menu with your cursor on the word you want.


Find Text options

This group of options governs the kind of strings that the editor searches for.

Case sensitive (Default)

Whole words only

Regular expression


Case Sensitive option

When this option is on, the editor differentiates uppercase from lowercase when performing a search.

Case Sensitive On is the default.


Whole Words Only option

When this option is on, the editor searches for words only; the search string must have punctuation or space characters on both sides.

When the Whole Words Only option is off, the search might find the search string within longer words.


Regular Expression option

When this option is on, the editor recognizes GREP-like wildcards in the search string.

To use Brief Regular Expressions instead:

1.	Choose Options|Environment.

2.	Select Editor Options.

3.	Choose BRIEF Regular Expressions.


Direction options

Use these options to specify the direction you want the editor to search, starting from the Origin setting.

Forward	Searches toward the end of the file. (Default)

Backward 	Searches toward the beginning of the file.


Scope options

These options specify which part of the file you want to search in.

Global	Searches the entire file, in the direction specified by the Direction setting. (Default.)

Selected Text	Searches only in the block of marked text, in the direction specified by the Direction setting.

Use the mouse or block commands to mark a block of text.


Origin options

These options determine where the search begins.

From Cursor

Starts the search at the cursor's current position. The search then proceeds either forward to the end of the scope, or backward to the beginning of the scope depending on the Direction setting. (Default.)

Entire Scope

Searches either the entire block of selected text or the entire file (no matter where the cursor is in the file). The scope is defined by the Scope options.


Search|Replace command
Search | Replace

This command displays the Replace Text dialog box, where you type in the text you want to search for and the text you want to replace it with.

Dialog Box Options

The Replace Text dialog box is where you specify the text to search for and what to replace it with. Most components of the Replace Text dialog box are identical to those in the Find Text dialog box.

Text to Find

Enter the search string in the Text to Find input box, then choose OK or Change All to begin the search; or Cancel to stop it.

Press the Down-arrow key or press Alt+Down arrow to display the history list. associated with the input box.

New Text

Enter the replacement string in the New Text input box.

You can also use the history list to the right of the box to select a string you've used previously.

Find Text options

This group of options governs the kind of strings that the editor searches for, and whether the replacement is automatic.

Direction options

Use these options to specify which way you want the editor to search, starting from the current cursor position. Forward (from the current position to the end of the file) is the default.

Scope options

Use these options to determine how much of the file the editor searches in. Global (entire file) is the default scope.

Origin options

Use this option to specify where you want the search to start.

Change All button

Choose Change All if you want the editor to replace all occurrences of the search string defined by the Direction, Scope, and Origin options.


New Text

Ater you enter the text you want to search for in Text to Find, use this area to enter the text you want to replace it with.

Press the Down-arrow key or press Alt+Down arrow to display the history list. associated with the input box.

To use the word your cursor is currently on in the edit window as the search string; place the cursor on the word you want and then choose Replace from the Search menu .


Find Text options

This group of options governs the kind of strings that the editor searches for, and whether the replacement is automatic.

Case sensitive

Whole words only

Regular expression

Prompt on Replace


Prompt on Replace option

When this option is on, the editor asks you to confirm each replacement before it is made.

When this option is off, the editor replaces text matching the search string with the new text without confirmation.

When Prompt on Replace is off and you choose Change All, the editor replaces all occurences of the search string.


Change All button

After you enter a search string and replacement string, you can choose OK or Change All to begin the search; or choose Cancel to stop it.

If you choose Change All and the Prompt on Replace option is:

on	the editor asks you to confirm each replacement.

off 	the editor replaces all occurences of the search string.

If you want to enter a search string you used previously, press Alt+Down arrow to show a history list to choose from.


Search|Search Again command
Search | Search Again

The Search Again command repeats the last Find or Replace command.

The last settings made in the Find Text or Replace Text dialog box remain in effect when you choose Search Again.

In default keyboard mode, press F3 to search again.


Search|Browse Symbol command
Search | Browse Symbol

This command opens the Browse Symbol dialog box where you enter a symbol to display in the Browser.

When you choose this command from an open Edit window, the dialog box contains selected text, or if no text is selected, it contains the word at the cursor.

A symbol may be any class, function, or variable symbol which is defined in your source code (not only in the current file, but also in any source file which is compiled and linked as part of the same project).

Note:	The Browse Symbol dialog box also displays if you choose Browse Symbol from the Edit window SpeedMenu and there is no text at the cursor.


Search|Locate Function command
Search | Locate Function

This command opens the Locate Function dialog box which asks you to enter a function that you want to locate. Type in the name of the function you want to locate and choose OK or press Enter.

The IDE positions the cursor in an edit window at the line in the source code file that contains the function. If the file is not is loaded in an edit window, a new edit window opens with the file loaded.

This command is only available while you are using the integrated debugger and your program is not running. For example:

This command is available if

you are stepping or tracing through your code.

your program is stopped at a breakpoint.

you first choose Debug|Run and then choose Debug|Pause Program.

This command is not available if

debugging is not in progress.

your program is currently running.

you choose Debug|Run and then choose Debug|Terminate Program.


Search|Previous Message command
Search | Previous Message

This command displays an active Edit window and places the cursor on the line in your source code that generated the previous error or warning listed in the Message window. If the file is not currently loaded, the IDE opens it in a new Edit window.


Search|Next Message command
Search | Next Message

This command displays an active Edit window and places the cursor on the line in your source code that generated the next error or warning listed in the Message window. If the file is not currently loaded, the IDE opens it in a new Edit window.


View menu

The commands on the View menu let you choose which windows display in the IDE:

ClassExpert

Project

Message

Classes

Globals

Watch

Breakpoint

Call Stack

Register

Event Log

Information


View | ClassExpert

The View|ClassExpert command displays the ClassExpert window where you can add and manage classes in a AppExpert application.

This command is not available unless the current project is an AppExpert application that you generated by choosing the Project|AppExpert command.


View|Project command
View | Project

See Also

This command opens the Project Hierarchy where you can view a graphical representation of your project with project elements displayed as nodes (usually associated with files) in an collapsable/expandable hierarchy diagram.

This command is not available until you have a project loaded in the IDE. If the Project window is closed, you can reopen it again with this command.


See Also

Managing Projects

Project Window navigation keys

Project Hierarchy Reference

View Options Hierarchy


View|Message command
View | Message

This command opens the Message window which displays status, warnings, and error messages.

When you get error messages or run a tool like GREP from the Tool Menu, the Message window opens and displays the output. If the Message window has been closed, you can reopen it again with the View|Message command.

In the Message window, you can

scroll through the output messages

navigate to the program line referenced in the message

track messages (highlight one program line after another in the source code as you view messages in the Message window.)

To edit the program line:

Select the message that references the program line you want to edit and press Enter. The cursor moves to that program line in the source code.

To track program lines:

Select the message that references the program line you want to track first and press Spacebar.

How program lines are tracked depends on how you set the source tracking options in Environment|Preferences. If the file referenced is not in an edit window, the IDE opens the file and displays it either in a new edit window or in the current edit window.

To display the file in a new edit window, choose New Window as the Source Tracking option (the IDE default setting.) To replace the current file in the active edit window, choose Current Window as the Source Tracking option.


Message Window

The Message window displays status, warning, and error messages generated when the C++ IDE compiles and links.

Automatic Error Tracking

As you track up and down through the messages in the Message window, the cursor in the Edit window moves to the corresponding source file line.

Using the Message Window

When a message refers to a file that is not currently loaded in an Edit window, select the error and then press the Spacebar to load the file.

To view the source code location of a selected error in an Edit window while keeping the Message window active, press Spacebar.

To make the Edit window active and place the cursor on the line that caused the error, press Enter.

To close the Message window, choose Close from its Control menu.

You can also display transfer program output in the Message window.

User-Defined Warnings

The User-defined warnings compiler option allows user-defined warnings to appear in the IDE's Message Window. This option is on by default.

Note:	In addition to messages which you can introduce with the #pragma message compiler syntax, the User-Defined Warnings option allows warnings introduced in third party libraries to be displayed. Remember to contact the vendor of the header file that issued the warning should you require additional help on third party messages.


View|Classes command
View | Classes

See Also

This command opens the Browsing Objects window which displays all of the classes in your application, arranged in a horizontal tree that shows parent-child relationships. The window is automatically sized to display as much of your class hierarchy as possible.

You can highlight any class in the display by using the arrow keys, or by clicking directly on the class name. You can then go to the source code that defines the highlighted class, inspect the functions and data elements of the highlighted class, or print the source code.

If the program in the current Edit window or the first file in your project hasn not yet been compiled, the IDE must first compile your program before invoking the Browser.


See Also

Browser

Debugging in the IDE


View|Globals command
View | Globals

See Also

This command opens the Browsing Globals window which lists every variable in your program, in alphabetical order.

You can highlight any variable in the display by using the arrow keys, or by clicking directly on the variable name. You can then go to the source code that defines the highlighted variable or inspect the declaration of the highlighted variable.

If the program in the current Edit window or the first file in your project hasn not yet been compiled, the IDE must first compile your program before invoking the Browser.


View|Watch command
View | Watch

See Also

This command opens the Watches window which lists watch expressions that have been set and their changing values so you can monitor how your program evaluates key values.

You can also use the Set Watch command in the Edit window SpeedMenu to add or remove watches.


See Also

Watching

Watch window


View|Breakpoint command
View | Breakpoint

See Also

This command opens a window that lists each set breakpoint and its line number.


See Also

Setting Breakpoints

Breakpoint Properties dialog


View|Call Stack command
View | Call Stack

See Also

This command opens the Call Stack window, which shows the sequence of functions your program called to get to the function currently running.

Each entry displays the function name and the values of any parameters passed to it.


See Also

Call Stack window

Returning to Where a Function was Called


View|Register command
View | Register

See Also

This command opens the Registers window which displays CPU registers. Use it to debug inline ASM and TASM modules in the current project. (TASM is a tool which can be purchased separately.)


See Also

Examining Register Values

Registers window


View|Event Log command
View | Event Log

This command opens the Event Log window that displays the results of breakpoints, Windows messages, and output messages generated while you use the integrated debugger.


View|Information command
View | Information

This command displays the Information window which shows the current directory, operating system version numbers, memory, and system resources.


Project menu

See Also

The Project menu provides commands to create or modify a project, and to make, build, or compile your programs.

AppExpert

New Project

Open Project

Close Project

New Target

Compile

Make All

Build All

Generate Makefile


See Also

Converting Old Projects

Project Hierarchy Reference

Managing Projects

Project Hierarchy


Project|AppExpert command
Project | AppExpert

See Also

Use the Project|AppExpert command to automatically generate code for an OWL-based Windows application.

If you are generating a new application, choose the Project|AppExpert command and enter a name for the application.

To edit an existing AppExpert application, choose the View|AppExpert command.

AppExpert then displays the AppExpert multi-page dialog where you can set options for the application.


See Also

Managing Projects

Project Hierarchy


Project|New Project command
Project | New Project

See Also

The New Project command displays the New Target dialog box where you can create and name a new project. When a new project is created by the Project Manger, a skeleton project is created. After you create the initial target for your project, you can modify the skeleton to fit your needs.

Once your project is created, you can change Target Attributes by selecting TargetExpert from the SpeedMenu on the Project Hierarchy.

When a new project is created, it inherits the option settings of the project that was open when you chose Project|New Project. If you have not opened a project in your current Borland C++ session, the new project is given the settings of the Default Style Sheet.


New Target Dialog Box
New Target

The options on the New Target dialog box are:

Project Path and Name - the path and name for your project

Target Name - the name of the first target (output file) in your project

Target Type - type of target (output) file

Standard Libraries - which standard libraries to use in your application or which standard defines to use in your static library

Floating Point - (DOS applications)

Emulation - (DOS applications)

No Math Support - to link in the DOS math librarian

Alternate Startup - (DOS applications)

Platform - the desired platform for your project

Target Model - the memory model for your program

Advanced Options - change the default project skeleton that is generated for a selected target type


See Also

Creating multi-target projects

Project Hierarchy Reference

Managing Projects

Project Hierarchy


Project Path and Name

Project|New Project

Enter the path and an eight-character name for your project. You can also use the Browse button to select a path to the project file.

Note	If the directory you enter does not exist, it will be created.


Browse Button

Project|New Project

The Browse button opens a dialog box where you can search for path or filename information.


Target Name

Project|New Project

Type a name for the first target (output file) in your project. This is usually the name of the program you want to create (the .EXE or .DLL) and the last module of an application that is built. You can also use the Browse button to select a target file.


Target Types

Project|New Project

Select the type of target (output) file. The selected target type affects the resulting project skeleton that is created for your project. The selected node's extension will change to reflect the new target type.

Choose from the following.

Target Type	Explanation

Application (.exe)	standard application (.EXE)

Dynamic Library (.dll)	dynamic library (.DLL) file

EasyWin (.exe)	character-mode application that runs under Windows

Static Library (for .exe) [.lib]	static library (.LIB) file for an .exe

Static Library (for .dll) [.lib]	static library (.LIB) file for a .dll

Import Library (.lib)	import library (.LIB) file

Windows Help (.hpj)	Windows Help project (.HPJ) file


Standard Libraries

Project|New Project	Turbo Vision (Add On)

Depending upon the Target type and Platform, the available standard libraries or standard defines for the selected project type are displayed. Choose which libraries should be added to your project or which standard defines should be used if you are building a static library.

Dynamic, static, diagnostic, and multithread library versions can also be selected. If you select to use the Diagnostic versions of the OWL or Class libraries, you must build them.

Libraries

OWL (Object Windows library) - an object-oriented class library that encapsulates the behaviors (application-level and window-level) that Windows applications commonly perform. If OWL is selected, Class library and standard run-time library is automatically selected. (See Diagnostics below.)

Class library - a template-based container class library, that uses encapsulation so you can maximize container storage with a minimal amount of reprogramming. If Class library is selected, standard run-time library is automatically selected. When you select this option, the appropriate BIDSxxx.LIB or BIDSxxx.DLL libraries are linked into your program. (See Diagnostics below.)

Run-time  - classes, functions, and macros to call from within your C and C++ programs that perform a wide variety of tasks.

OCF - ObjectComponents classes for simplifying the creation of OLE 2 applications in C++. ObjectComponents implements a set of high-level interfaces on top of OLE.

OLE 2 - an operating system extension that lets applications achieve a high degree of integration. OLE provides a set of standard interfaces so that any OLE program can interact fully with any other OLE program.

BWCC (Borland Windows Custom Control Library) - an alternative graphical look to standard Windows controls.

VBX (Visual Basic Controls Support) - allows you to use VBX controls in your application.

BGI	searches in the BGI graphics library file for BGI graphics (not Windows-compatible).

Library Versions

Dynamic - the dynamic (.DLL) form of the selected libraries. This forces large model for 16-bit targets.

Static - the static (.LIB) form of the selected libraries.

Multithread - the 32-bit, multithreaded, flat model run-time library. Multithread is available only if your platform is Win32.

Diagnostic - diagnostic ObjectWindows or Class Libraries. Diagnostic libraries add debug information to the files. If you select Diagnostic, you must build these libraries. Both OWL and Class Library source are provided.

To build the OWL diagnostic libraries, use the following make line:

MAKE -DDIAGS.

Note:	See the ObjectWindows makefile for other options.

To build the Class Library diagnostic libraries, use the following make line:

MAKE -DDBG.

Note:	See the ClassLib makefile for other options.


Project Platform

See Also	Project|New Project	DPMI (Add On)

Select the desired platform for your project.

Windows 3.x (16)

Targets Windows 3.0 or 3.1 (16-bit).

Win32

Targets Win32.

DOS Standard

Targets DOS applications not designed to be safe for overlays.

DOS Overlay

Targets DOS applications that are overlay-safe.


See Also

Exception Handling and Overlays


Exception Handling and Overlays

Project|New Project

If you overlay a C++ program that contains exception-handling constructs, there are a number of situations that you must avoid. The following program elements cannot contain an exception-handling construct:

Inline functions that are not expanded inline

Template functions

Member functions of template classes

Exception-handling constructs include user-written try/catch and _ _try/_ _except blocks. In addition, the compiler can insert exception handlers for blocks with automatic class variables, exception specifications, and some new/delete expressions.

If you attempt to overlay any of the above exception-handling constructs, the linker identifies the function and module with the following message:

   Error: Illegal local public in function_name in module module_name

When this error is caused by an inline function, you can rewrite the function so that it is not inline. If the error is caused by a template function, you can do the following:

Remove all exception-handling constructs from the function

Remove the function from the overlay module

You need to pay special attention when overlaying a program that uses multiple inheritance. An attempt to overlay a module that defines or uses class constructors or destructors that are required for a multiple inheritance class can cause the linker to generate the following message:

   Error: Illegal local public in class_name:: in module module_name

When such a message is generated, the module identified by the linker message should not be overlaid.

The container classes (in the BIDS?.LIB) have the exception-handling mechanism turned off by default. However, the diagnostic version of BIDS throws exceptions and should not be used with overlays. By default, the string class can throw exceptions and should not be used in programs that use overlays. See the Library Reference for a discussion of BIDS and the string class.


Target Model

Project|New Project	DPMI (Add On)

Select the desired memory model.

For Windows 16-bit projects, choose between Small, Medium, Compact, or Large.

For 32-bit applications, choose between GUI and Console mode.

For DOS Standard, choose between Medium, Compact, Large, and Huge.

For DOS Overlay, choose between Medium, Large, and Huge.


Advanced Options Button

The advanced options button on the Project|New Project dialog box brings up the Advanced Options dialog box, where you specify changes to the default project skeleton that is generated for a selected target type.


Floating Point Option

Project|New Project

Command-line equivalent = -f87

If your program is going to run only on machines that have an 80X87 math coprocessor, you can save a small amount in your .EXE file size by omitting the 80X87 autodetection and emulation logic. Choose the 80X87 floating-point code-generation option. Borland C++ will then link your programs with FP87.LIB instead of with EMU.LIB.


Emulation Option

Project|New Project

Command-line equivalent = -f

The default Borland C++ code-generation is emulation. This option is for programs that might or might not have floating point, and for machines that might or might not have an 80X87 math coprocessor.

With the emulation option, the compiler will generate code as if the 80X87 were present, but will also link in the emulation library (EMU>LIB). When the program runs, it uses the 80X87 if it is present; if no coprocessor is present at run time, it uses special software that emulates the 80X87. This software uses 512 bytes of your stack, so make allowances for it when using the emulation option and set your stack size accordingly.


No Math Support Option

Project|New Project

If there is no floating-point code in your program, you can save a small amount of link time by choosing No Math Support for the floating-point code-generation option. Then Borland C++ will not link with EMU.LIB, FP87.LIB, OR MATHx.LIB.


Alternate Startup Option

Project|New Project

The Alternate Startup option adds DOS Library to target node. With that library in place, all models are compiled to SS=DS.


ObjectWindows Library

Project|New Project

ObjectWindows is an object-oriented class library that encapsulates the behaviors (application-level and window-level) that Windows applications commonly perform. It provides an exciting way to develop applications for Microsoft Windows by providing:

a consistent, intuitive, and simplified interface to Windows

supplied behavior for window management and messasge-processing

a basic framework for structuring a Windows application

You inherit this base functionality, which leaves you free to concentrate your efforts on the unique requirements of your application.

Diagnostic Version

If you select to use the Diagnostic version of the ObjectWindows library, you must build it. Source is provided.

To build the OWL diagnostic libraries, use the following make line:

MAKE -DDIAGS.

Note:	See the ObjectWindows makefile for other options.


Class Library

See Also	Project|New Project

Borland C++  includes a template-based container class library, that uses encapsulation so you can maximize container storage with a minimal amount of reprogramming. When you select this option, the appropriate BIDSxxx.LIB or BIDSxxx.DLL libraries are linked into your program.

These classes build containers from ADTs (abstract data types), and use FDS (fundamental data structure) as an underlying data structure. Together ADTs and FDSs determine a containers storage stategy.

FDS are low-level containers you can instantiate. FDSs are the underlying data structures upon which you build containers and they do not necessarily need an accompanying ADT.

ADTs are high-level containers which have at least one pure virtual function. The existance of a pure virtual function means that the ADT container classes cannot be instantiated without an underlying FDS.

Diagnostic Version

If you select to use the Diagnostic version of the Class library, you must build it. Source is provided.

To build the Class Library diagnostic libraries, use the following make line:

MAKE -DDBG.

Note:	See the ClassLib makefile for other options.


See Also

Container Classes

Container Classes Summary

Container Classes by Category

Dynamic-link Libraries

Static Run-time Libraries


ObjectComponents Library

Project|New Project

ObjectComponents library (OCF) contains a framework of classes for creating OLE 2 applications in C++. ObjectComponents is designed to make linking and embedding easier.

Microsoft's OLE operating system extensions require a programmer to implement a variety of interfaces depending on the tasks an application undertakes. To simplify programming, Borland implements a smaller set of high-level interfaces on top of OLE. The simplified interfaces reside in a support library called BOCOLE.DLL. This support library provides default implementations for many standard OLE interfaces.

For More Information

To learn more about the Borland ObjectComponents library and Borland C++ support for OLE, select from the following topics.

OCF Task Information

OCF Language Reference

Support for OLE in Borland C++


OLE Library

Project|New Project

OLE (object linking and embedding) is an operating system extension that lets applications achieve a high degree of integration. OLE provides a set of standard interfaces so that any OLE program can interact fully with any other OLE program. No program needs to have any built-in knowledge of its possible partners.

For More Information

To learn more about the Borland support for the OLE library and the ObjectComponents library that is provided to simplify OLE programming, select from the following topics.

Support for OLE in Borland C++

ObjectComponents Task Information

OCF Language Reference


BWCC Library

Project|New Project

The Borland Windows Custom Control Library (BWCC) is a collection of classes, functions and bitmap buttons that you can link into your program for an alternative graphical look to standard Windows controls.


VBX Library

Project|New Project

The VBX Library option allows you to use Visual Basic controls in your applications. This option is available for both 16- and 32-bit Windows applications.


Borland Graphics Interface (BGI) Library

Project|New Project

The BGI library option controls the automatic searching of the Borland Graphics Interface library. When this option is checked, you can build and run single-file graphics programs without using a project file. Unchecking this option speeds up the link step because the linker doesn't have to search in the BGI graphics library file.

The BGI library is not Windows-compatible. You can uncheck this option and still build programs that use BGI graphics, provided you add the name of the BGI library (GRAPHICS.LIB) to your project list.


Advanced Options

See Also	DPMI (Add On)

When a new project is created, a skeleton project hierarchy is created for the project and displayed in the Project Hierarchy. What nodes are present in that skeleton, depends upon the settings in the Advanced Options dialog box.

System Default Target Options

The system default target options for the Application, Dynamic Library, and EasyWin Target types are:

Application (.exe) with Windows 3.x (16) Platform chosen - generates a .exe file and by default creates a .cpp node, .rc file, and .def file in the project skeleton

Application (.exe) with Win32 Platform chosen - generates a .exe file and by default creates a .cpp node, .rc file, and .def file in the project skeleton

Application (.exe) with DOS Standard Platform chosen - generates a .exe file and by default creates a .cpp node in the project skeleton

Application (.exe) with DOS Overlay Platform chosen - generates a .exe file and by default creates a .cpp node in the project skeleton

Dynamic Library (.dll) with Windows 3.x (16) Platform chosen -generates a .dll file and by default creates a .cpp node, .rc file, and .def file in the project skeleton

Dynamic Library (.dll) with Win32 Platform chosen -generates a .dll file and by default creates a .cpp node, .rc file, and .def file in the project skeleton

EasyWin (.exe) - generates a .exe file and by default creates a .cpp node, .rc file, and .def file in the project skeleton

Changing Advanced Options

To change the project skeleton that is created for a particular target type:

1.	Select a target type in the New Project dialog box

2.	Press the Advanced button to access the Advanced Options dialog box

3.	Select the combination of nodes you want present in a new project of the specified target type.

When Advanced Options are changed, that setting becomes the default Advanced Options for the specified target type. Subsequent new projects of that target type are created with a skeleton project hierarchy containing the newly defined default set of project nodes.

Initial Nodes

Select from these initial nodes:

Extension	File Type

.cpp node	C++ source file

.c node	C source file

No source node

.rc	resource file

.def	module definition file used by the linker


See Also

Project Hierarchy Reference

Managing Projects

Project Hierarchy


Project|Open Project command
Project | Open Project

See Also

This command displays the Open Project File dialog box, where you select and load an existing project file.

The project manager can load and use projects from previous versions of Borland C++. Once an old project is loaded into the Project Hierarchy, it is converted to the new project format.


See Also

Project Hierarchy Reference

Managing Projects

Project Hierarchy


Project|Close Project command
Project | Close Project

See Also

The Close Project command unloads your current project and closes the Project Hierarchy Window.


See Also

Managing Projects

Project Hierarchy


Project|New Target command
Project | New Target

See Also

This command displays the Add Target dialog box where you add a new target node and specfiy target information for it.

The node you create is added to the current project and placed at the bottom of the project hierarchy. This new node is created as a stand alone target. You can move it or make it a child of another node in the project hierarchy by using the Alt+UpArrow/Alt+DownArrow, or Alt+LeftArrow/Alt+RightArrow keys.

The options on the Add Target dialog box are:

Target Name

Enter the name for the new target node.

Target Type

Select from the following Target types:

AppExpert

Automatically generated code for an OWL-based application.

Standard

An Application (.exe) project with the current default project skeleton for that target type. If the target type is Standard, the Add Target dialog box appears where you further define your target.

Source Pool

A collection of nodes in the project that are typically marked "exclude from parent" and not built. Source Pools act as a model or template from which you can create reference copies of code for use throughout your project. By using Source Pools, you can let different targets use common source code. If the target type is Source Pool, the target is added to the project and you can add nodes to it immediately.


See Also

Project Hierarchy Reference

Advanced Options

Managing Projects

Project Hierarchy


Project|Compile command
Project | Compile

See Also

Project|Compile translates the file or selected project node.

When an editor window is selected, the Project Hierarchy translates the file (i.e., if you have a .rc file open, it'll do a resource compile on it, if it's a .c or .cpp file, then a C or C++ compile on it).

When the Project Hierarchy is in view and a node is selected, the Project Hierarchy translates only the selected node (not the whole project). The type of translation that takes place depends on what type of node is selected.

When the selected node is a .cpp node, a C++ Compile takes place. To accomplish the same results, double-click on the node or use SpeedMenu|C++ Compile. SpeedMenu|C++ Compile is the same as the -c command-line compiler option (compile and assemble, but do not link).

When the selected node is an .exe node, the linker is called. To accomplish the same results, use SpeedMenu|Link.

When the selected node is a .lib node, the librarian is invoked. To accomplish the same results, use SpeedMenu|Special|Create Library.

If a C or C++ compile is invoked with Project|Compile, a Compile Status information box displays the compilation progress and results. Choose OK when compilation is complete. If any errors occurred, the Message window becomes active and displays and highlights the first error or warning.


See Also

Building Part Of A Project

Project MakeAll

Managing Projects

Project Hierarchy


Compile Status information box

The Compile Status information box displays the compilation status and results.


Project|Make All command
Project | Make All

See Also

This command makes the targets of the current project.

If you choose Make All, the Project Hierarchy will MAKE all targets. It checks file dates and times to see if they have been updated. If so, the Project Hierarchy rebuilds those files, then moves up the project tree and checks the next nodes' file dates and times. The project manger checks all the nodes in a project and builds all of the out-of-date files.

The .EXE file name is fully spelled out in the Project Hierarchy for target names. If no project is loaded, the .EXE name is derived from the Editor Window.

The Make all command rebuilds only the files that are not current.


See Also

Building Part Of A Project

Managing Projects

Project Hierarchy

Project|Compile


Project|Build All command
Project | Build All

See Also

The Build all command rebuilds all the files in the current project, regardless of whether they are out of date.

This option is similar to Project|Make All, except that Build All rebuilds all the files in the project whether or not they are current.

Build All builds the project using the Default Project Options Style Sheet unless you have attached a different Style Sheet to a node or overridden the options locally.

For example, if you have a project with an .EXE target that is dependent on a .CPP file, and the .CPP is dependent on two .H files, the Project Hierarchy checks the dependencies for the two .H files first, then it compiles the .CPP file to an .OBJ, and finally, the project uses the new .OBJ file to link the .EXE.

Build All:

1.	Deletes the appropriate precompiled header (.CSM) file, if it exists.

2.	Deletes any cached autodependency information in the project.

3.	Does a rebuild of the node.

If you abort a Build command by pressing Esc or choosing Cancel, or if you get errors that stop the build, you must explicitly select the nodes to be rebuilt.


See Also

Building Part Of A Project

Managing Projects

Project Hierarchy

Project MakeAll


Project| Generate Makefile command
Project | Generate Makefile

See Also

This command generates a make file for the current project. It gathers information from the currently loaded project and produces a MAKE file named <projectfilename>.MAK. You cannot convert makefiles to project files.

The IDE displays the new makefile in an editor window.


See Also

Managing Projects

Project Hierarchy


Compile Information box

The Compile Information box displays the following fields:

Current directory

Current file

Lines compiled

Number of warnings issued

Number of errors generated

Available memory

The information here is for display only; you can't change any of the settings in the Information dialog box.

After reviewing the information in the box, choose OK to remove it.


Register or Unregister OLE Server

The Special|Register OLE Server and Special|Unregister OLE Server commands on the Project Window SpeedMenu alter the operating system's OLE registration database.

Register OLE Server

Use Special|Register OLE Server to identify a selected file as an OLE server and add information about it to the registration database. Using Special|Register OLE Server makes it unnecessary to run an application simply for registration purposes and makes it possible to register a DLL.

Unregister OLE Server

Use Special|Unregister OLE Server to delete a selected file from the OLE registration database.


Debug menu

The Debug menu provides commands to run your program and use the Integrated debugger:

Run

Step Over

Trace Into

Toggle Breakpoint

Find Execution Point

Pause Program

Terminate Program

Add Watch

Add Breakpoint

Evaluate/Modify

Inspect

Load Symbol Table


Debug|Run command
Debug | Run

See Also

This command executes your program. If the source code has been modified since the last compilation, the IDE recompiles and links your program.

This command is not available if

your pogram is currently running.

the target is not executable.

the debugger is stopped at an unrecoverable error.


See Also

Debugging in the IDE

Editor Files

Environment


Debug|Step Over command
Debug | Step Over

See Also

This command executes the next statement in your program which is the one highlighted by the execution point.

It does not trace into calls to lower-level functions, even if they are accessible to the debugger. Use Step Over to run the program you are currently debugging, one statement at a time, without branching off into other functions.

This command is not available if

your program is currently running.

the target is not executable.

the debugger is stopped at an unrecoverable error.

you are using Windows NT.


Debug|Trace Into command
Debug | Trace Into

See Also

This command runs your program statement-by-statement, but if the debugger encounters a function call, it stops on the first line of the function instead of executing the function as a single step.

If the executing statement

contains a call to a function accessible to the debugger, Trace Into halts at the beginning of the function definition.

does not contain a call to a function accessible to the debugger, Trace Into stops at the next executable statement.

Use the Trace Into command to move the execution point into a function called by the one you are currently debugging. Subsequent Trace Into or Step Over commands run the statements within in the function. When the debugger leaves the function, it resumes evaluating the statement that contains the call.

Note:	The Trace Into command only recognizes functions defined in a source file that has been compiled with the following options selected:

Debug Information in OBJs in Compiler|Debugging

Include Debug Information in Linker|General

This command is not available if

your program is currently running.

the target is not executable.

the debugger is stopped at an unrecoverable error.

you are using Windows NT.


See Also

Stepping Over Code

Tracing Into Code

Debugging in the IDE


Debug|Toggle Breakpoint command
Debug | Toggle Breakpoint

See Also

This command inserts an unconditional breakpoint on the line at the cursor position in the active Edit window, or removes a breakpoint if one is set on the line at the cursor location.

You can also use the Toggle Breakpoint command on the Edit window SpeedMenu which works the same way.


See Also

Adding Breakpoints

Setting Breakpoints


Debug|Find Execution Point command
Debug | Find Execution Point

See Also

This command positions the cursor at the execution point in an Edit window. If you closed the Edit window containing the execution point, the IDE opens an Edit window displaying the source code at the execution point.

This command is only available while you are using the integrated debugger and your program is not running.

For example:

This command is available if

you are stepping or tracing through your code.

your program is stopped at a breakpoint.

you first choose Debug|Run and then choose Debug|Pause Program.

This command is not available if

your program is currently running.

you choose Debug|Run and then choose Debug|Terminate Program.

debugging is not in progress.


See Also

Debugging in the IDE

Setting Breakpoints


Debug|Program Reset command
Debug | Pause Program

See Also

This command halts execution of an application running in a debugging session.

This command is only available while you are using the integrated debugger and your program is running.


See Also

Debugging in the IDE

Starting Over


Debug|Program Reset command
Debug | Terminate Program

See Also

This command

Stops the current debugging session.

Releases memory your program has allocated and some of the memory used for debugging information.

Closes any open files that your program was using.

This command is only available while you are using the integrated debugger.

For example:

This command is available if

you first choose Debug|Run.

you are stepping or tracing through your code.

your program is stopped at a breakpoint.

This command is not available if:

your program is currently running.

you choose choose Debug|Run and then choose Debug|Terminate Program.

debugging is not in progress.


See Also

Debugging in the IDE

General Protection Exception

Starting Over


Debug|Add Watch command
Debug | Add Watch

See Also

This command opens the Watch Properties dialog box which lets you set a watch expression.

When you choose this command from an active Edit window, the dialog box contains selected text, or if no text is selected, it contains the word at the cursor.

After you add the watch, the Watch window displays.

This command is not available if the debugger is stopped at an unrecoverable error.


See Also

Watching

Debugging in the IDE


Debug|Add Breakpoint command
Debug | Add Breakpoint

See Also

This command opens the Breakpoint Properties dialog box which lets you enter a conditional or unconditional breakpoint.

When you choose this command from an active Edit window, the dialog box contains the name of the flie loaded in the active Edit window and the line number at the cursor location.

This command is not available if the debugger is stopped at an unrecoverable error.


See Also

Adding Breakpoints

Setting Breakpoints


Debug|Evaluate command
Debug | Evaluate/Modify

See Also

The Evaluate/Modify command opens the Expression Evaluator dialog box that lets you:

Evaluate a variable or expression.

View the value of any variable or other data item.

Alter the value of simple data items.

Use the Expression Evaluator as a calculator at any time.


See Also

Evaluating Expressions

Modifying Variables


Debug|Inspect command
Debug | Inspect

See Also

This command opens the Inspect Expression box that lets you enter a variable or expression you want to examine while debugging your program.

This command is only available while you are using the integrated debugger and your program is not running.

For example:

This command is available if

you are stepping or tracing through your code.

your program is stopped at a breakpoint.

you first choose Debug|Run and then choose Debug|Pause Program.

This command is not available if

your program is currently running.

you choose Debug|Run and then choose Debug|Terminate Program.

debugging is not in progress.


See Also

Inspecting Data Elements

Setting Breakpoints


Debug | Load Symbol Table

See Also

This command opens the Load Symbol Table dialog box that lets you

see the symbol table currently loaded into memory

view other symbol tables available to your program

load another symbol table into memory

This command is only available while you are using the integrated debugger and your program is not running.

For example:

This command is available if

you are stepping or tracing through your code.

your program is stopped at a breakpoint.

you first choose Debug|Run and then choose Debug|Pause Program.

This command is not available if

your program is currently running.

you choose Debug|Run and then choose Debug|Terminate Program.

debugging is not in progress.


See Also

Debugging Dynamic-link Libraries

Debugging in the IDE


Tool Menu

The Tool menu lets you run programs, tools, and utilities without leaving the IDE. To run a program from the Tool Menu, choose the program you want from the list of available tools.

The Tool List shows preinstalled or user-installed programs.


Tools List
Tool List

See Also

The programs in the Tool List can be standalone programs (like GREP, Turbo Debugger, or an alternate editor), they can be used to build nodes in the project, or they can be viewers used to view the contents of a particular project node (file). Some tools are preinstalled. You can install other tools with the Options|Tools dialog box.

When you choose a program from the menu, control transfers to it. Some programs, such as GREP and Turbo Debugger, transfer control back to the IDE after the program is through running.

Program arguments are specified in the Options|Tools dialog box and are passed when the program is invoked. If a program requires arguments be entered at runtime, you are prompted for transfer arguments.


See Also

Options|Tools

Sharing Tools


Sharing Tools

There are two ways to share tools between projects.

Inheriting Tools

When you create or assign tools, those tools remains with the project for which they were created; they don't get added to the list of predefined tools. However, if you want a new project to use one of your custom Tools, you can do so by letting a new project inherit tools from another project.

To pass user defined tools (and Style Sheets) from an existing project to a new project, edit your BCW.INI file to make sure it includes the following line:

[project] inherit=1

This allows tools to be inherited from an open project.

Next, open a project that contains the tools you want to pass to a new project. Choose Project|New Project to create a new project. At creation, the new project inherits the option settings and user defined tools of the project that was open.

Editing the Project Description Language files

You can also share tools across projects by editing the Project Description Language files (.PDL) associated with your projects.

Note:	Be careful if you choose to edit .PDL files. If a .PDL file is corrupted, the project hierarchy will not be able to read it. You may want to make a backup copy of the .PDL file before you begin making changes.

A .PDL file is a text file that contains information about the Style Sheets and Tools used in your project. Style sheet and Tools information can be copied from one .PDL file to another, allowing you to quickly modify Style Sheet and tools for your projects.

Note:	.PDL files are only generated when SaveAsText=1 and ReadAsText=1 entries are present in the Project section of your BCW.INI file.

To edit the .PDL file:

1.	Open the .PDL file containing the Tool you want to share. You can open the .PDL file using any text editor.

2.	Search for the Subsystem = Tool

3.	Copy the text for the tool you wish to share. You can copy more than one Tool or the entire Tool subsection if you like.

4.	Open the .PDL file that is going to use the copied Tool.

5.	Find the Subsystem = <tool>, then paste the copied text into the Tool subsection or replace the Tool subsection if you copied it all.

6.	Open the .PDL file that is going to use the copied Style Sheet.

7.	Find the section for tools, then paste the copied text to the end of the existing tools list.

8.	Save the .PDL file that received the copied Tool. When you open a project file, the project manager checks the date of the .PDL file with the same name as the .IDE file. If the .PDL file is newer than the .IDE file, the contents of the .PDL file is added to the .IDE file.


Options menu

The Options menu contains commands for changing various default settings for both your Project and your Environment (integrated development environment), installing or modify tools, working with any Style Sheets that are available for your project, and specifying what gets saved when you exit BCW.

Most of the commands in this menu lead to a dialog box. The Project and Environment commands both open a dialog box that lets you set options that affect your program and programming environment.

The commands on the Options menu are:

Project

Environment

Tools

Style Sheets

Save


Options|Project command
Options | Project

This command displays the Project Options dialog box, where you set options  for your entire project.

The available topics are:

Directories

Compiler

16-Bit Compiler

32-Bit Compiler

C++ Options

Optimizations

Messages

Linker

Librarian

Resources

Make


Options|Environment command
Options | Environment

Environment Options Dialog Box

This command displays the Project Options dialog box, where you set options for the IDE in general.

This command works the same as the Set Options command on the edit window SpeedMenu.

The available topics are:

Editor

Syntax Highlighting

Browser

Debugger

SpeedBar

Preferences

Project View


Setting Options

The Style Sheet Options, Options|Project, and Local Options dialog boxes contain options that affect the active project. The Options|Environment dialog box contains options that affect your authoring environment.

How to Set Options

Options dialog boxes use a dual window format.

Topics in the left window expand and collapse. (When you first open an Options dialog box, the list of topics is collapsed.)

To set individual options, choose the sub-topic and options display on the right. You can change settings on one or several pages, without leaving the Options dialog box. Options are initially set to their default values.

Any settings you make take place immediately.

Choose...	If You Want To...

OK	Accept changes to all options and close return to the Project Window.

Undo Page	Restore the current screen of options to the settings present when you selected the Options Settings dialog box.

Cancel	Restore all options to the settings present when you opened the Options Settings dialog box. (Same as close box.)

Help	See context-sensitive online Help. The Help button gives a summary for the current screen of options. For Help on an individual option, select (highlight) an option and press F1.


Options|Tools command
Options | Tools

See Also

The Options|Tools command opens the Tools dialog box, where you can install, delete or modify the tools listed under the Tool menu. The Tool menu lets you run programming tools of your choice without leaving the Borland C++ IDE.

Tools can be standalone programs (like GREP, Turbo Debugger, or an alternate editor), or they can be translators that are used for each file (or node) in a project. You can run a DOS program with the Windows IDE transfer.

Dialog Box Options

Tools

The Tools list box displays all of the available tools.

New button

Press the New button to define a new tool and add it to the list of available tools. Pressing this button displays the Tool Options dialog box.

Copy button

Press the Copy button to define a new tool that has the same properties as the tool currently selected in the Tools list box. Pressing this button displays the Tool Options dialog box.

Edit button

Press the Edit button to edit the properties of the tool currently selected in the Tools list box. Pressing this button displays the Tool Options dialog box.

Delete button

Press the Delete button to remove the tool currently selected in the Tools list box from the list.


See Also

How to Add a Transfer Program

Options Menu

Sharing Tools

Tool Options dialog box

Transfer macros


Tool Options dialog box

See Also

Use the Tool Options dialog box to enter or edit the properties for a tool.

Name

The Name input box is where you type in a short description of the tool you're adding. This is the name that appears on the Tool list. If a tool in the Name list box is highlighted when you select Edit, the IDE automatically fills in the other input boxes; otherwise, they are blank.

Path

The Program Path input box is where you enter the program name. You can include the full path to the program, but the path is optional. Press the Browse button to search your drives and directories to locate the path and file name associated with the tool.

Command Line

The Command Line input box is where you type in any parameters or macro commands you want passed to the program.

Menu Text

Enter the text you want to appear on the SpeedMenu and on the Tools main menu for the tool. If you want to assign a shortcut key to the item, precede the accelerator key character with an ampersand (&). For example, Compile &Help file. This letter will appear underlined in the menu. If you want an ampersand in your menu text, use two (&&Test appears as &Test in the menu).

Help Hint

Enter the text you want to have appear in the help hint space at the bottom of the Tools dialog box. Help hint text appears in the status line when you select the menu item.

Advanced button

Press the Advanced button to display the Advanced Tool dialog box.


See Also

Sharing Tools


Advanced Tool dialog box

Use the Advanced Tool dialog box to set the options for a tool. These options determine the menu on which the tool will appear and with which nodes in the Project Hierarchy the tool is used.

Tool Type

Simple Transfer

Translator

Viewer

Translator / Viewer Details

Translate From/Applies To

Translate To

Default For

Tool Usage

Place on Tools Menu

Place on SpeedMenu

Target Translator


Simple Transfer

Select the Simple Transfer option to make the tool a simple transfer item. A simple transfer item is a general-purpose tool that can only be placed on the Tools menu.


Translator

See Also

Select the Translator option to make the tool a translator that can be used for each file (or node) in a project.

A translator can be any program that changes (translates) one file type to another. For example, the compiler is a translator that uses .C and .CPP files to create .OBJs, and TLINK is a translator that uses .OBJ files to produce an .EXE file.


See Also

ManagingProjects

Project Hierarchy


Viewer

See Also

Select the Viewer option to make the tool a viewer that will let you see the contents of a node  selected in the Project Hierarchy.

For example, an editor is a viewer that lets you examine the code in a .CPP file. On the local menu for a .CPP node, you'll see the Text Edit command. The default editor for the Text Edit view is the IDE editor.

Other node types have other viewers available. For example, Resource Workshop can view .RC files. You can't view an .EXE node in a text editor, but you can choose to view it using the integrated debugger, Turbo Debugger for Windows, the Browser, or even as an executing program.


See Also

ManagingProjects

Project Hierarchy


Translate From / Applies To

Use the Translate From (Translator) / Applies To (Viewer) input box to enter the file extensions for the types of nodes that can use the tool.

You can enter more than one file extension by separating them with semicolons (;).


Translate To

Use the Translate To input box to enter the file extension for the type of node that results from applying the tool to the node types listed in the Translate From input box.


Default For

Use the Default For input box to enter the file extensions for the types of nodes that use this tool as the default viewer/translator.

You can enter more than one file extension by separating them with semicolons (;).


Place On Tools Menu

Select the Place On Tools Menu option to place the tool on Tools menu.

The text in the Menu Text input box on the Tool Options dialog box is what will appear on the menu.


Place On SpeedMenu

Select the Place On Tools SpeedMenu option to place the tool on the Project Hierarchy SpeedMenu.

The text in the Menu Text input box on the Tool Options dialog box is what will appear on the menu.


Target Translator

If the Tool Type is:

Translator

Check Target translator if you want the translator to work on targets. When you use this translator, the node becomes a target and the translated file is saved to the Final directory. If you don't check Target translator, the translated file is saved in the Intermediate directory.

Viewer

Selecting the Target Translator option specifies that the tool can view only specific project node types.


How to Add a Transfer Program
Adding Translators and Viewers

Use the Options|Tools commands to display the Tool Options dialog box. Use the fields in the Tool Options dialog box to add a tool.


Options|Style Sheet command
Options | Style Sheets

This commnad displays the Style Sheet dialog box where you can specify default compile and run time option settings associated with a project. Style Sheet are predefined sets of options that can be associated with a node.


Style Sheets Dialog Box

See Also

You can create, compose, copy, edit, rename, or delete Style Sheets (predefined sets of options) in the Style Sheets dialog box.

Access this dialog box by choosing Options|Style Sheets on the main menu. You can also edit Style Sheets by clicking the Styles button on the Edit node attributes dialog box.

The following options are available:

Create

Enter a name for the new Style Sheet.

Compose

Select from available Style Sheets to create a Style Sheet that contains the combined options from one or more Style Sheets. You must first create a new Style Sheet, then click Compose. Select a Style Sheet you want included in your new Style Sheet, then click Add. Continue adding Style Sheets, then click OK when you're finished.

The Add button is available when a Style Sheet in the Available Style Sheets window is highlighted. First select a Style Sheet, then press the Add button. The Style Sheet and its option settings are added to the composite Style Sheet.

The Remove button is available when a Style Sheet in the composite Style Sheet is highlighted. First select the Style Sheet that you wish to remove, then press the Remove button. The Style Sheet and its option settings are removed from the composite Style Sheet.

Note that you cannot edit a composed Style Sheet, but you can click Compose again to add or delete Style Sheets from the Composed one.

Copy

Select a Style Sheet from the Available Style Sheets list, then press the copy button. Enter a name for the new Style Sheet, then click OK. You can now click Edit to change any of the copied options. Copying is a fast way to create a Style Sheet that closely resembles another--you only have to change the options you want.

Edit

Select Edit to display the Style Sheet Options dialog box where you can reset options for a particular Style Sheet.

Rename

Enter a new name for a selected Style Sheet, then click OK.

Delete

Delete removes the selected Style Sheet from the available Style Sheets list. Warning! Once a Style Sheet is deleted, it can not be restored.


See Also

ManagingProjects

Project Hierarchy

Sharing Style Sheets

Style Sheets


Setting Style Sheet Options

The Style Sheet Options dialog box displays when you select Options|Style Sheet which displays the Style Sheet dialog box and then you choose to edit an existing style sheet or create a new style sheet.

This dialog box contains the same set of options that the Options|Project dialog box, but offers one additional option - the Include box.

The Include Box

The Include box allows you to include or exclude selected options from a style sheet. Click on an option to set it and the Include box is automatically checked. Click on an option to unset it and the Include box is automatically unchecked.

The Include box is grayed if no option is selected (highlighted). You can tab over to an option if you want to see if the Include box is checked, but do not want to change the setting or affect the Include box for that option.

The Include box is checked if an option is changed from the Borland default option settings (by you or TargetExpert). For Borland default settings, the Include box is not checked, but default settings are automatically inherited and will be part of a style sheet unless you use the Include box to explicitly exclude options from it. For example, if you want a Style Sheet to handle only where directories are located, you can go through the rest of the dialog box and click on all of the other preset options, then explicitly uncheck the Include box.

The Include box can also help you recover if you become confused about what options are on and what options are off for a particular Style Sheet. Just edit the Style Sheet and explicitly set and Include or Exclude the desired options.

Setting Options

For information on setting options, see Setting Options.


Options|Save command
Options | Save

The Save command opens the Save Options dialog box, where you save settings you have made for the C++ environment, desktop, and current project.


Save Options dialog box

You use this dialog box to specify which IDE settings will be saved to a file (or files).

Environment

The Environment option stores all environment information to a file.

Desktop

The Desktop option saves the desktop files.

Project

The Project option saves your project files.


Node-Specific Tools

See Also

This selection from the Project Hierarchy SpeedMenu is a node-specific tool. Node-specific tools are either translators or viewers.

Translators

Translators are programs that change (translate) one file type into another file type. For example, the compiler is a translator that uses .C and .CPP files to create .OBJs, and TLINK is a translator that uses .OBJ files to produce an .EXE file.

Viewers

Viewers let you see the contents of a selected node. For example, an editor is a viewer that lets you examine the code in a .CPP file. On the local menu for a .CPP node, you'll see the Text Edit command. The default editor for the Text Edit view is the IDE editor.

Other node types have other viewers available. For example, Resource Workshop can view .RC files. You can't view an .EXE node in a text editor, but you can choose to view it using the integrated debugger, Turbo Debugger for Windows, the Browser, or even as an executing program.

Adding Tools to the SpeedMenu

Use the Options|Tools commands to display the Tool Options dialog box. Use the fields in the Tool Options dialog box to add a tool.


See Also

ManagingProjects

Project Hierarchy

Sharing Tools


Window menu

The Window menu contains window management commands.

Most of the windows you manage from this menu have all the standard window elements, such as scroll bars, Minimize and Maximize buttons, and a Control menu box.

To open windows, use the File|Open or File|New commands.

These are the Window menu commands:

Cascade

Tile Horizontal

Tile Vertical

Arrange Icons

Close All

Minimize All

Restore All

List of open windows

More Windows


Window|Cascade command
Window | Cascade

This command stacks all open edit windows and overlaps them so that each is the same size as all others and only part of each underlying window is visible.


Window|Tile Horizontal command
Window | Tile Horizontal

This command arranges your open windows from top to bottom so that they cover the entire width of the desktop without overlapping one another. If there are more than three open windows, the IDE arranges them in a manner that allows more width than height.


Window|Tile Vertical command
Window | Tile Vertical

This command arranges your open windows from left to right so that they display next to each other. If there are more than three open windows, the IDE arranges them in a manner that allows more height than width.


Window|Arrange Icons command
Window | Arrange Icons

This command rearranges any icons on the desktop. The rearranged icons are evenly spaced, beginning at the lower left corner of the desktop.

This command is useful when you resize your desktop that has minimized windows. It is unavailable when no windows are minimized.


Window|Close All command
Window | Close All

This menu provides commands to close some or all open windows.

Windows

Debugger Windows

Browser Windows

Editor Windows

If you modified the contents of a window since it was last saved, the C++ IDE opens a dialog box that asks if you want to save before closing.

When prompted to save:

and you choose...	the IDE...

No	closes all editor windows; changes are not saved

Yes	prompts you to save the changed file

Cancel	leaves the window open with your changes


Window|Close All|Windows command
Window | Close All | Windows

This command closes all open windows.


Window|Close All|Debugger windows command
Window | Close All | Debugger windows

This command closes all open debugger windows.


Window|Close All|Browser windows command
Window | Close All | Browser windows

This command closes all open Browser windows.


Window|CloseAll|Editor windows command
Window | Close All | Editor windows

This command closes all open Edit windows.

If you modified the contents of a window since it was last saved, the C++ IDE opens a dialog box that asks if you want to save before closing.

When prompted to save:

and you choose	the IDE

No	closes all editor windows; changes are not saved

Yes	prompts you to save the changed file

Cancel	leaves the window open with your changes


Window|Minimize All command
Window | Minimize All

This menu provides commands to minimize all or some open windows:

Windows

Debugger Windows

Browser Windows

Editor Windows


Window|Minimize All|Windows command
Window | Minimize All | Windows

This command minimize open windows.


Window|Minimize All|Debugger windows command
Window | Minimize All | Debugger Windows

This command minimizes all open debugger windows.


Window|Minimize All|Browser windows command
Window | Minimize All | Browser Windows

This command minimizes all open Browser windows.


Window|Minimize All|Editor windows command
Window | Minimize All | Editor Windows

This command minimizes all open Edit windows.


Window|Restore All command
Window | Restore All

This menu provides commands to restore some or all minimized windows to their former size:

Windows

Debugger Windows

Browser Windows

Editor Windows


Window|Restore All|Windows command
Window | Restore All | Windows

This command restores all minimized debugger windows to their former size.


Window|Restore All|Debugger windows command
Window | Restore All | Debugger Windows

This command restores all minimized debugger windows to their former size.


Window|Restore All|Browser windows command
Window | Restore All | Browser Windows

This command restores all minimized Browser windows to their former size.


Window|Restore All|Editor windows command
Window | Restore All | Editor Windows

This command restores all minimized Edit windows to their former size.


Edit window

See Also

Edit windows are where you type in and edit your C or C++ code. You can also perform the following actions in an Edit window:

compile your programs

run your programs

read from disk files

save to disk files

Opening Edit Windows

To open an Edit window, choose File|Open. You can open the same file in more than one window.


See Also

Using the editor

Search|Find command

Search|Replace command

Edit menu

File|Save command

File|Save As command


List of open windows
Window | List of open windows

See Also

The IDE displays a list of currently open windows at the bottom of the Window menu.

When you choose an open window, you make that window active. A check mark appears in front of the active window.


See Also

Edit|Buffer List command

More Windows


More Windows
Window | More windows

Use this command to list additional open windows in the IDE not listed at the bottom of the Window menu.


Help menu

The Help menu provides access to online Help, which displays in a special Help window. The Help system provides information on virtually all aspects of the Borland IDE (integrated development environment) and the Borland C++ language, libraries, and so on.

Note:	One-line menu and dialog-box hints appear on the status line whenever you select a menu command or dialog box item.

For more information, see Using Help in Borland C++.

If you do not know how to use Help in Windows, choose Using Help from the Help menu.

The Help menu provides the following commands:

Contents

Keyword Search

Keyboard

Using Help

Windows API

OWL API

About


Help|Index command
Help | Contents

This command displays the Borland C++ online Help contents. It provides a comprehensive list that summarizes the organization of topics in the Help system.

For more information, see Using Help in Borland C++.

If you do not know how to use Help in Windows, choose Using Help from the Help menu.


Help|Topic Search command
Help | Keyword Search

Place your cursor on a word (a "token") in the active Edit window and press F1 (or choose Help|Keyword Search) to get either

Help about that token.

a list of available topics when there are multiple topics to choose from.

a dialog displaying the closest match if no related topics are found.

This command works the same as the Go to Help Topic command on the edit window SpeedMenu.

You can get Help this way for most Borland C++ language elements such as

reserved words

global variables

functions in the standard run-time, class, and ObjectWindows libraries

Windows API

For more information, see Using Help in Borland C++.

If you do not know how to use Help in Windows, choose Using Help from the Help menu.


Help|Topic Search command
Help | Keyboard

Use this command to get Help about hot keys, keyboard commands, and keyboard shortcuts.

For more information, see Using Help in Borland C++.

If you do not know how to use Help in Windows, choose Using Help from the Help menu.


Help|Using Help command
Help | Using Help

This command displays information on how to use the Borland C++ Help system in Windows.

If you do not know how to use Help in Windows, choose Using Help from the Help menu or press F1 from an active Help window.


Help|API
Help | Windows API

Use this command to get information on using the Windows Application Program Interface. It opens the Borland Windows API Help file and displays the Windows API online Help contents. At any time while viewing API Help, you can use the buttons at the top of the Help window to quickly access Help for Borland C++ or OWL (Object Windows Library).


Help|OWL
Help | OWL API

Use this command to get information on using OWL (Object Windows Library). It opens the OWL Help file and displays the OWL online Help contents. At any time while viewing OWL Help, you can use the buttons at the top of the Help window to quickly access Help for Borland C++ or Windows API.


Help|About Borland C++ command
Help | About

This command displays the About Borland C ++  window that shows copyright and version information.


About C++ dialog box
About Borland C++

This window displays copyright and version information.

Click OK, press Esc, or press Enter to close it.


OK Button

Press Enter or click OK to put this message window away and return to the Borland C++ IDE.


SpeedMenus
SpeedMenus offer quick access to currently available commands. To display a SpeedMenu, click the right mouse button (or press Alt-F10).

SpeedMenus are available in the following parts of the Borland C++ IDE:

Breakpoints Window SpeedMenu

Browser SpeedMenu

Call Stack SpeedMenu

Classes pane SpeedMenu (ClassExpert)

Data Inspector SpeedMenu

Edit pane SpeedMenu (ClassExpert)

Edit Window SpeedMenu

Event Log SpeedMenu

Events pane SpeedMenu (ClassExpert)

Message Window SpeedMenu

Options Window SpeedMenu

Project Window SpeedMenu

Register Window SpeedMenu

Watch Window SpeedMenu


Breakpoints Window SpeedMenu
The Breakpoints Window SpeedMenu provides commands to change breakpoint properties, to inspect or edit source code at breakpoints, or to add,remove,disable or enable breakpoints.

Properties

View Source

Edit Source

Remove Breakpoint

Add Breakpoint

Disable Selected Breakpoints

Enable Selected Breakpoints

Remove All Breakpoints

Disable All Breakpoints

Enable All Breakpoints


Inspect Source (Breakpoints Window SpeedMenu)
View Source (Breakpoints Window SpeedMenu)

This command brings up a non-active Edit window displaying the line in your source on which the highlighted breakpoint is set. If the file is not currently loaded, the IDE opens it in a new Edit window.

This SpeedMenu command has no equivalent command on the menu bar.


Edit Source (Breakpoints Window SpeedMenu)

This command brings up an active Edit window with the cursor positioned on the line in your source code highlighted breakpoint is set. If the file is not currently loaded, the IDE opens it in a new Edit window.

Double-click on the breakpoint in the Breakpoints window to achieve the same results.


Browser Window SpeedMenu
Browser SpeedMenu
This SpeedMenu provides the following commands to use the Browser.

Edit Source

Browse Symbol

Browse References

Browse Class Hierarchy

Return to Previous View

Print Class Hierachy

Toggle Window Mode

Set Options


Edit Source (Browser SpeedMenu)

This command brings up an active Edit window with the cursor positioned on the line in your source code that references the highlighted symbol. If the file is not currently loaded, the IDE opens it in a new Edit window.


Browse Symbol (Browser SpeedMenu)

This command displays the declaration of the selected symbol in a Browser window.

Double-click on the symbol to achieve the same results.

The symbol may be any class, function, or variable symbol which is defined in your source code (not only in the current file, but also in any source file which is compiled and linked as part of the same project).

This command is disabled if the current target does not exist.


Browse References (Browser SpeedMenu)

This command lists all references to the selected symbol.


Browse Class Hierarchy (Browser SpeedMenu)

This command displays all the members of the selected class arranged in a horizontal tree structure to show parent-child relationships.


Return to Previous View (Browser SpeedMenu)

This command takes the Browser back to the previous view.

This command is disabled when the Browser is in single window mode or there is no previous view for the active Browser window.

To change the Browser window mode, choose Toggle Window Mode on the Browser SpeedMenu.


Print Class Hierachy (Browser SpeedMenu)

This command prints the horizontal tree structure displayed in the Browsing Objects window that shows parent-child relationships of members of the selected class.


Toggle Window Mode (Browser SpeedMenu)

Lets you switch between single or multiple Browser window mode.

Mode	Description

Single Window	Lets you open only one Browser view at a time. (It also disables the Return to Previous View commnad on the Browser SpeedMenu.) The next time you select a Browser action, the Browser replaces the view you currently have open.

Multiple Window	Lets you open multiple Browser views at the same time. Each time you select a new Browser action, an additional Browser view opens.


Set Options (Browser SpeedMenu)

This command displays the Environment Options dialog box where you set options that affect the IDE in general.

It works the same as the Options|Environment command on the menu bar.


Watch Window SpeedMenu
The Watch Window SpeedMenu provides commands to change watch properties, add or delete watchs, and disable or enable watches.

Properties

Remove Watch

Add Watch

Disable Selected Watch

Enable Selected Watch

Remove All Watches

Disable All Watches

Enable All Watches


Call Stack Window SpeedMenu
Call Stack SpeedMenu
The Call Stack Window SpeedMenu provides the following commands:

Inspect Source	Brings up a non-active Edit window displaying your source code at the line where the selected function was called. If the source file is not currently loaded, the IDE opens it in a new Edit window.

Edit Source	Brings up an active Edit window with the cursor positioned on the line in your source code where the selected function was called. If the source file is not currently loaded, the IDE opens it in a new Edit window. Double-click on the function in the Call Stack to achieve the same results.


Data Inspector SpeedMenu
See Also

This SpeedMenu provides the following commands that are available when you inspect data elements:

Inspect Object	Isolates the view of elements such as classes, structures, and arrays.

New Expression	Lets you inspect a new expression.

Set Range	Lets you assign a range of values to an array.

Change Value	Lets you assign a new value to a data item.

View Source	Displays a non-active Edit window that showing the line in your source code that references the element you are inspecting. If the source file is not currently loaded, the IDE opens it in a new Edit window.


See Also

Inspecting Data Elements


Edit Window SpeedMenu
The Edit window SpeedMenu provides commands to open a file, search for a symbol, access keyword search, go to a line number or a cursor location, add a breakpoint or watch, inspect data elements, or change settings active for the Edit window.

Open source

Browse Symbol

Go to Help topic

Go to Line

Toggle Breakpoint

Run to Cursor

Set Watch

Inspect Object

Target Expert

Link

Edit Local Options


Open source
Open source ( Edit window SpeedMenu)

This command displays the Open a File dialog box so you can select a file to load into the Borland C++ editor window. It works the same as the File|Open command on the menu bar.

You can have multiple files open at the same time in the editor, so the Open command does not close any of the editor windows that you have open. (Opening a file, however, replaces an empty NONAME file in an active Edit window.)

If you load a file that is already open in an IDE editor window, the Open command loads the updated version and leaves a copy in its original editor window. Subsequent changes are maintained in the both copies.

If you load a file into an active Edit window that contains an empty NONAME file, the contents of the Edit window is replaced.


Go to Line (Edit window SpeedMenu)

Use this command to position the cursor on a specific line in the source code in the active Edit window. It displays the Go To Line Number dialog box which asks to enter the line number you want to find.

Type the number of the line you want (or pick a previously entered line number from the history list), then press Enter (or choose OK).

Note:	The current line number displays in the status line at the bottom of the IDE desktop.

This SpeedMenu command has no equivalent command on the menu bar.


Go to Help topic (Edit window SpeedMenu)

Place your cursor on a word (a "token") in the active Edit window and then choose this command (or press F1) to get Help about it.

This SpeedMenu command works the same as the Help|Keyword Search command on the menu bar.

You can get Help this way for most Borland's C++ language elements such as

reserved words

global variables

functions in the standard run-time, class, and ObjectWindows libraries

Windows API


Browse Symbol (Edit window SpeedMenu)

This command opens the Symbol Inspection window for the highlighted symbol or the symbol where the cursor is currently located in the active Edit window. If there is no text at the cursor, a dialog box displays that prompts you to enter a symbol.

The symbol may be any class, function, or variable symbol which is defined in your source code (not only in the current file, but also in any source file which is compiled and linked as part of the same project).


Toggle Breakpoint (Edit window SpeedMenu)

See Also

This command inserts an unconditional breakpoint on the line at the cursor position in the active Edit window, or removes a breakpoint if one is set on the line at the cursor location.

This SpeedMenu command works the same as the Debug|Toggle Breakpoint command on the menu bar.


Run to Cursor (Edit window SpeedMenu)

This command tells the debugger to execute your program normally (not step-by-step) until it reaches the line in your code on which the cursor is located.

1.	In an Edit window, position the cursor on the line where you want to resume debugging control.

2.	Choose Run to Cursor on the Edit window SpeedMenu.

You can use Run to Cursor as a way to restart your debugging session after you have already been stepping over or tracing into your code.

This SpeedMenu command has no equivalent command on the menu bar.


Set Watch (Edit window SpeedMenu)

This command sets a watch on the symbol at the insertion point, then opens the Watch window where you can view it as you use the integrated debugger.


Inspect Object (Edit window SpeedMenu)

This command opens the Inspector window and displays the data element at the cursor location in the acive Edit window.

This command is only available while you are using the integrated debugger, such as stepping or tracing through your code.


TargetExpert (Edit window SpeedMenu)

This command opens the Borland C++ TargetExpert which lets you specify a target type for the program loaded in the active Edit window.

This command is only available when no project is loaded in the IDE.


Link (Edit window SpeedMenu)

See Also

This command links the file loaded in the active Edit window using the default values.

This command is only available when no project is loaded in the IDE.


See Also

Options|Tools command

Options|Tools dialog box

Transfer arguments


Edit Local Options (Edit window SpeedMenu)

This command opens the Local Options dialog box which lets you overrride options set in the current Style Sheet.

This command is only available when no project is loaded in the IDE.


Event Log SpeedMenu
This SpeedMenu provides the following commands available on the Event Log.

Clear Events	Erases the events currently displayed in the Event Log.

Save Events To File	Writes the contents of the Event Log to a file. (To save a file without including the lines already in the Log window, first choose Clear Events.)

Add Comment	Lets you add a comment in the Event Log. Comments in the Event Log are enclosed in angle brackets (> <).

Set Options	Displays the Environment Options dialog box where you can set options that affect your programming environment.


Message Window SpeedMenu
The Message window SpeedMenu provides commands to view or edit source code where an error has been identified.

Edit Source

Inspect Source

Remove All Messages


Edit Source (Message window SpeedMenu)

This command brings up an active Edit window with the cursor positioned on the line in your source code that caused the highlighted warning or error. If the file is not currently loaded, the IDE opens it in a new Edit window.

Double-click on the message in the Message window to achieve the same results.

This SpeedMenu command has no equivalent command on the menu bar.


View Source (Message window SpeedMenu)

This command brings up a non-active Edit window displaying your source code at the line that caused the warning or error. If the file is not currently loaded, the IDE opens it in a new Edit window.

This SpeedMenu command has no equivalent command on the menu bar.


Remove All Messages (Message window SpeedMenu)

This command clears all messages from the Message window.

This SpeedMenu command has no equivalent command on the menu bar.


Project Window SpeedMenu
The SpeedMenus on the Project window provide most of the commands you need in the IDE.

Which SpeedMenu displays depends on the node selected and the the commands available for that node. For example, if you select a .CPP source file in the Project window, the SpeedMenu displays commands appropriate for that node type, such as C++ Complile, Build Node, View|Text Edit, and so forth.

The Project window SpeedMenu provides the following commands, depending on the active node:

View|Run	Add Node	Special|C++ (or C) to Assembler
View|Debug	Delete Node	Special|C++ (or C) via Assembler
View|Browse Classes	Make Node	Special|Create Library
View|Browse Globals	Build Node	Special|Preprocess
View|Turbo Debugger	Link	Register or Unregister OLE Server
View|Resource Workshop	Resource Compile	TargetExpert
View|Text Edit	C++ Compile	Edit Node Attributes
View|Brief	View|options hierarchy	Edit Local Options


Register Window SpeedMenu
See Also

This SpeedMenu provides commands to select the register values display format:

Show Hexadecimal

Show Decimal

Show Word

Show Double Word


See Also

Examining Register Values


Options Window SpeedMenu
This SpeedMenu provides commands to expand and collapse the nodes and branches in the options outliner.

Command	Accelorator Key	Function

Expand/collapse node	Spacebar	Opens or closes the catagories (branches) beneath a node (top level)

Expand branch	+	Opens levels beneath a branch

Collapse branch	-	Closes levels beneath a branch

Expand all	*	Displays all options (all levels beneath all nodes and branches)

Collapse all	/	Collapses all sublevels (all levels beneath all nodes and branches)

Outliner Symbols

+	indicates a collapsed node or branch (sublevel catagories not displayed)

- 	indicates a fully expanded node or branch


Browsing Through Your Code

See Also

The Browser lets you search through your object hierarchies, classes, functions, variables, types, constants, and labels that your program uses. The Browser also lets you:

Graphically view the hierarchies in your application, then select the object of your choice and view the functions and symbols it contains.

List the variables your program uses, then select one and view its declaration, list all references to it in your program, or go to where it is declared in your source code.

List all the classes your program uses, then select one and list all the symbols in its interface part. From this list, you can select a symbol and browse as you would with any other symbol in your program.

Using the Browser

If the program in the current Edit window or the first file in your project has not yet been compiled, the IDE must first compile your program before invoking the Browser.

If you try to browse a class definition (or any symbol that does not have symbolic debug information), the IDE displays an error message.

If you changed the following default settings on the Project Options dialog box, before you use the Browser, be sure to:

1.	Choose Options|Project.

2.	Choose Compiler|Debugging and check

Browser Info in OBJs

Debug Info in OBJs

3.	Choose Linker|General and check Include Debug Information.

4.	Compile your application.

Browser Views

The Browser provides the following types of views:

Global Symbols

Objects (Class Overview)

Symbol Declaration

Class Inspection

References


See Also

Browsing Symbols in Your Code

Browsing Global Symbols

Browsing Objects (Class Overview)

Browser Filters and Letter Symbols

Customizing the Browser

Starting the Browser

Debugging in the IDE


Browsing Symbols in Your Code

See Also

You can browse any symbol in your code without viewing object hierarchies or lists of symbols first.

To do so, highlight or place your cursor on the symbol in your code and choose either

Search|Browse symbol from the main menu

Browse Symbol from the Edit window SpeedMenu

If the symbol you select to browse is a structured type, the Browser shows you all the symbols in the scope of that type. You can then choose to inspect any of these further. For example, if you choose an object type, you will see all the symbols listed that are within the scope of the object.


See Also

Browser Filters and Letter Symbols

Customizing the Browser

Starting the Browser


Starting the Browser

See Also

You can start browsing through your code the following ways:

Place your cursor on a symbol in your code and choose Browse Symbol from the Edit window SpeedMenu.

From the main menu or the SpeedBar and choose one of the following commands

Search|Browse Symbol

View|Classes

View|Globals


See Also

Browsing Symbols in Your Code

Customizing the Browser


Customizing the Browser

See Also

Use the Environment Options dialog box to select the Browser options you want to use.

1.	Choose Options|Environment.

2.	Choose Browser.

3	Specify the types of symbols you want to have visible in the Browser using the Visible Symbols option.

4.	Specify how many Browser views you can have open at one time. See single or multiple Browser window mode in the Browser Window Behavior option.


See Also

Browsing Symbols in Your Code

Starting the Browser


Browsing Objects (Class Overview)

See Also

Choose View|Classes to see an overall view of the object hierarchies in your application, as well as the small details.

The Browser draws your objects and shows their ancestor-descendant relationships in a horizontal tree. The red lines in the hierarchy help you see the immediate ancestor-descendant relationships of the currently selected object more clearly.

To see more detail about a particular object, double-click it. (If you are not using a mouse, select the object by using your arrow cursor keys and press Enter.) The Browser lists the symbols (the procedures, functions, variables, and so on) used in the object.

One or more letters appear to the left of each symbol in the object that describe what kind of symbol it is. See Browser Filters and Letter Symbols.

Browser SpeedMenu

Once you select the global symbol you are interested in, you can use the following commands on the Browser SpeedMenu:

Edit Source

Browse Symbol

Browse References

Return to Previous View

Print Class Hierarchy

Toggle Window Mode

Set Options


See Also

Browser Filters and Letter Symbols

Browsing Global Symbols

Customizing the Browser

Debugging in the IDE


Browsing Global Symbols

See Also

Choose View|Globals to open a window that lists every global symbol in your application in alphabetical order.

To see the declaration of a particular symbol listed in the Browser, use one of the following methods:

Double-click the symbol

Select the symbol and press Enter

Select the symbol, choose Browse Symbol from the SpeedMenu

Search

The Search input box at the bottom of the window lets you quickly search through the list of global symbols by typing the first few letters of the symbol name. As you type, the highlight bar in the list box moves to a symbol that matches the typed characters.

Browser SpeedMenu

Once you select the global symbol you are interested in, you can use the following commands on the Browser SpeedMenu:

Edit Source

Browse Symbol

Browse References

Return to Previous View

Toggle Window Mode

Set Options


See Also

Browser Filters and Letter Symbols

Browsing Global Symbols

Customizing the Browser

Debugging in the IDE


Symbol Declaration Window

See Also

This Browser window shows the declaration of the selected symbol.

You can use the following commands on the Browser SpeedMenu:

Edit Source

Browse References

Browse Class Hierarchy

Return to Previous View

Toggle Window Mode

Set Options


See Also

Browser Filters and Letter Symbols

Browsing Symbols in Your Code

Customizing the Browser

Debugging in the IDE


Class Inspection Window

See Also

This Browser window shows the symbols (functions and variables) used in the selected class.

Once you select the symbol you are interested in, you can use the following commands on the Browser SpeedMenu:

Edit Source

Browse Symbol

Browse References

Browse Class Hierarchy

Return to Previous View

Toggle Window Mode

Set Options


Browser Filters
Browser Filters and Letter Symbols

See Also

When you browse a particular symbol, the same letters that appear on the left that identify the symbol appear in a Filters matrix at the bottom of the Browser window. The Filters matrix has a column for each letter which can appear in the top or bottom row of the column.

Use the filters to select the type of symbols you want to see listed. (You can also use the Browser Options settings to specify the types of symbols you want to see listed.)

Letter	Symbol

F	Function

T	Type

V	Variable

C	Integral constants

?	Debuggable

I	Inherited from an ancestor

v	Virtual method

Note:	In some cases, more than one letter appears next to a symbol. Additional letters appear to the right of the letter identifying the type of symbol and further describe the symbol:

To view all instances of a particular type of symbol,

Click the top cell of the column.

For example, to view all the variables in the currently selected object, click the top cell in the V column. All the variables used in the object appear.

To hide all instances of a particular type of symbol,

Click the bottom cell of the letter column.

For example, to view only the functions and procedures in an object, you need to hide all the variables. Click the bottom cell in the V column, and click the top cells in the F and P columns.

To change several filter settings at once,

Drag your mouse over the cells you want to select in the Filters matrix.


See Also

Browsing Symbols in Your Code

Browsing Global Symbols

Browsing Objects (Class Overview)

Customizing the Browser

Debugging in the IDE


Browsing References

See Also

This Browser window shows the references to the selected symbol.

You can use the following commands on the Browser SpeedMenu:

Edit Source

Browse Class Hierarchy

Return to Previous View

Toggle Window Mode

Set Options


See Also

Browsing Symbols in Your Code

Browsing Global Symbols

Browsing Objects (Class Overview)

Customizing the Browser

Debugging in the IDE


The Borland C++ for Windows Editor
Borland C++ Editor

See Also

There are many ways to get into an open Edit window (make it active):

Click it.

Press Alt+hyphen to display the active Edit window's Control menu. Then choose the Next command to go to the open Edit window.

Press Crtl+F6 to cycle though the open windows.

Choose the window from the list of open windows on the Window menu.

Once in the Edit window, you enter text just as if you were using a typewriter. When you want to end a line, press Enter.

The maximum number of lines allowed in a file is 2,147,483,647. You can have approximately 6MB open across all files, subject to available swap space.

The maximum line width in an Edit window is 1024 characters; the computer will beep if you try to type past that.

To cut, copy, or paste blocks of text, you first need to select a block.


See Also

Editor Options

Keyboard Commands


Selecting Text

See Also

You can select (highlight) text either with keyboard commands or a mouse.

From the keyboard:

Press Shift while pressing any key that moves the cursor.

With a mouse:

Drag the mouse pointer over the desired text. To continue the selection past a window edge, just drag off the side. The window will scroll.

To select a single line, double-click anywhere in the line.

To select line-by-line, click once and press the mouse button again and begin to drag.

To extend or reduce the selecting, hold Shift and click.

Once you've selected text, the commands in the Edit menu become available.


Keyboard

Default	IDE Classic	Brief	Epsilon	TDW

The Borland C++ keyboard shortcuts are two- or three-key combinations you can press to perform a menu command or access a dialog box directly, without pulling down any menus. The function of specific keyboard shortcuts depends on which keystroke mapping scheme you have selected.

There are two different ways you can map your keyboard:

Use the Keystroke Mapping option in the Editor|File settings to select the Keystroke Mapping you want to use. (You can use the Keymapper utility to customize these existing keystroke mappings or create one of your own.)

Use one of the four SpeedSettings in the Editor settings to have the Borland C++ IDE editor emulate one of four popular programming editors.

Note:	Using Keymapper, the Keystroke Mapping option, or the Editor SpeedSettings to change the mapping of your keystrokes can create conflicts with standard Windows keyboard commands.

For example, the Brief keystroke mapping defines Alt+E as File|Open, while the standard Windows action for Alt+E is to activate the Edit menu. The mapped key takes precedence so that Alt+E allows you to open a file.


Debugger Keystroke Mapping

Default	IDE Classic	Brief	Epsilon	TDW

Breakpoints Window 	Command

Ctrl+P 	Edit Breakpoint

Ctrl+I 	View Source

Ctrl+E 	Edit Source

Ctrl+R 	Delete Breakpoint

Ctrl+A 	Add Breakpoint

Call Stack

Ctrl+I 	View Source

Ctrl+E 	Edit Source

Data Inspector

Ctrl+I 	Inspect Object

Ctrl+N 	New Expression

Ctrl+R 	Set Range

Ctrl+C 	Change Value

Event Log

Ctrl+E 	Clear Events

Ctrl+C 	Save Events To File

Ctrl+A 	Add Comment

Ctrl+O 	Set Options

Register Window

Ctrl+H 	Show Hexadecimal

Ctrl+D 	Show Decimal

Ctrl+W 	Show Word

Ctrl+U 	Show Double Word

Watch View

Ctrl+P 	Edit Watch

Ctrl+A 	Add Watch

Ctrl+R 	Delete Watch


Message Window Keystroke Mapping

Default	IDE Classic	Brief	Epsilon	TDW

Enter	Edit Source

Esc	Window|Close

Space	Inspect Source


Pane Management Keystroke Mapping

Default	IDE Classic	TDW

Ctrl+O+E	Moves to the pane above the current pane

Ctrl+O+X	Moves to the pane below the current pane

Ctrl+O+S	Moves to the pane to the left of the current pane

Ctrl+O+D	Moves to the pane to the right of the current pane

Ctrl+O+UpArrow	Creates a new pane above the current pane

Ctrl+O+DownArrow	Creates a new pane below the current pane

Ctrl+O+LeftArrow	Creates a new pane to the left of the current pane

Ctrl+O+RightArrow	Creates a new pane to the right of the current pane

Ctrl+Shift+O+E	Moves the pane splitter bar above the current pane

Ctrl+Shift+O+X	Moves the pane splitter bar below the current pane

Ctrl+Shift+O+S	Moves the pane splitter bar to the left of the current pane

Ctrl+Shift+O+D	Moves the pane splitter bar to the right of the current pane

Ctrl+Shift+O+UpArrow	Deletes the pane above the current pane

Ctrl+Shift+O+DownArrow	Deletes the pane below the current pane

Ctrl+Shift+O+LeftArrow	Deletes the pane to the left of the current pane

Ctrl+Shift+O+RightArrow	Deletes the pane to the right of the current pane


Project Window Keystroke Mapping

Default	Brief	Epsilon	TDW

Enter	Performs the default action for a node

Plus	Expands a node

Minus	Collapse a node

Spacebar	Collapses an expanded node; expands a collapsed node

Esc	Ends a node search

UpArrow	Moves up a node in the project

DownArrow	Moves down a node in the project

Home	Goes to the first (topmost) node in a project

End	Goes to the last (bottom) node in a project

PgUp	Scrolls down one screen in the project window

PgDn	Scrolls up one screen in the project window

Alt+LeftArrow	Promotes a node one level

Alt+RightArrow	Demotes a node one level

Alt+UpArrow	Moves a node up in the project

Alt+DownArrow	Moves a node down in the project


Editor Keystroke Mapping (Block Commands)

Default	IDE Classic

Ctrl+K+B	marks the beginning of a block

Ctrl+K+C	copy a selected block

Ctrl+K+H	hides/shows a selected block

Ctrl+K+I	indents a block by the amount specified by the Block Indent option

Ctrl+K+K	marks the end of a block

Ctrl+K+L	marks the current line as a block

Ctrl+K+N	changes a block to uppercase

Ctrl+K+O	changes a block to lowercase

Ctrl+K+P	prints a selected block

Ctrl+K+R	reads a block from a file

Ctrl+K+T	marks a word as a block

Ctrl+K+U	outdents a block by the amount specified by the Block Indent option

Ctrl+K+V	moves a selected block

Ctrl+K+W	writes a selected block to a file

Ctrl+K+Y	deletes a selected block

Ctrl+O+C  	toggles a column block; use Shift and arrow keys to mark the remainder of the block

Ctrl+O+I  	toggles an inclusive block at the cursor position; use Shift and arrow keys to mark the remainder of the block

Ctrl+O+K  	toggles an non-inclusive block at the cursor position; use Shift and arrow keys to mark the remainder of the block

Ctrl+O+L  	toggles a line as a block at the cursor position; use Shift and arrow keys to mark the remainder of the block

Ctrl+Q+B	move to the beginning of a block

Ctrl+Q+K	moves to the end of a block


Editor Keystroke Mapping (Bookmark Operations)

Default	IDE Classic

Ctrl+K+0 	sets bookmark 0

Ctrl+K+1 	sets bookmark 1

Ctrl+K+2 	sets bookmark 2

Ctrl+K+3 	sets bookmark 3

Ctrl+K+4 	sets bookmark 4

Ctrl+K+5 	sets bookmark 5

Ctrl+K+6 	sets bookmark 6

Ctrl+K+7 	sets bookmark 7

Ctrl+K+8 	sets bookmark 8

Ctrl+K+9 	sets bookmark 9

Ctrl+Q+0 	go to bookmark 0

Ctrl+Q+1 	go to bookmark 1

Ctrl+Q+2 	go to bookmark 2

Ctrl+Q+3 	go to bookmark 3

Ctrl+Q+4 	go to bookmark 4

Ctrl+Q+5 	go to bookmark 5

Ctrl+Q+6 	go to bookmark 6

Ctrl+Q+7 	go to bookmark 7

Ctrl+Q+8 	go to bookmark 8

Ctrl+Q+9 	go to bookmark 9


Editor Keystroke Mapping (Cursor Movement)

Default	IDE Classic

Ctrl+Q+C	moves to end of a file

Ctrl+Q+D	moves to the end of a line

Ctrl+Q+P	moves cursor to previous position

Ctrl+Q+R	moves to the top of a file

Ctrl+Q+S	moves to the beginning of a line

Ctrl+Q+T	moves the current to the top of the window

Ctrl+Q+U	moves the current to the bottom of the window


Editor Keystroke Mapping (Miscellaneous Commands)

Default	IDE Classic

Ctrl+K+D	accesses the menu bar

Ctrl+K+E	changes a word to lowercase

Ctrl+K+F	changes a word to uppercase

Ctrl+K+S	File|Save

Ctrl+Q+A	Search|Replace

Ctrl+Q+F	Search|Find

Ctrl+Q+Y	deletes to the end of a line

Ctrl+Q+[ 	finds the matching delimiter (forward)

Ctrl+Q+] 	finds the matching delimiter (backward)

Ctrl+O+A  	opens the filename at the cursor

Ctrl+O+B  	Search|Browse Symbol

Ctrl+O+G  	Go To Line

Ctrl+O+O  	toggles the case of a selection


Keyboard Mapping
Keystroke Mapping

See Also

Keymapper (KEYMAPR.EXE) is a macro compiler for the IDE. It processes a script file that defines macros and key bindings, and produces a file that is read by the IDE to define the effect of keystrokes in the IDE.

Syntax

Keymapper is invoked from the DOS command line. Enter:

keymapr <script file> <output file>

The IDE expects output files to have the .CKB extension.

Available Keyboard Mappings

The file INTERNAL.KB contains the default macro definitions and key bindings built into the IDE. The IDE also ships with 4 additional keystroke bindings:

Classic	key bindings that match the Borland C++ 3.1 DOS IDE

Brief	key bindings that emulate most of the standard BRIEF keystrokes

Epsilon	key bindings that emulate a a large part of the EPSILON editor.

TDW	key bindings that mimic Turbo Debugger for Windows

These keyboard mappings are also good sources of sample scripts.

Note:	Changing the mapping of your keyboard using Keymapper, the Keystroke Mapping option in the EditorFile settings, or one of the four SpeedButtons on the Editor settings page can cause keyboard conflicts with standard Windows keyboard commands.

For example, the Brief keyboard mapping defined Alt+E as File|Open, while the standard Windows action for this key is to activate the Edit menu.


See Also

Keyboard Shortcuts

Key Codes

Keymapper Macro Syntax

Named Keyboards

Named Keys

Predefined Editor Commands


Keymapper Macro Syntax

See Also	Keyboard Mapping

The syntax to define a macro is:

MACRO <macroname>

  <command1>;

[ <command2>; ... ]

END;

<macroname> may consist of anything that is a legal C symbol, and <command> may be either the name of another macro, a predefined KEYMAPR command or an IF statement.

If statements are defined as follows:

IF [NOT]<command> THEN

  <command>

[ELSE

  <command>]

ENDIF

To execute multiple statements inside if clause, wrap the statement sequence with BEGIN ... END

KEYMAPR primitives that may be used as conditionals are distinguished by the prefix "Inq".

Unlike its predecessor, KEYMAPR requires that key assignments be wrapped up into named keyboards:

KEYBOARD <keyboard-name>

  <key-assignment1>

 [<key-assignment2>]

 [...]

END;

When you define your macro, the following points are valid:

1.	A statement defines either a named macro or a keyboard.

2.	Spaces and new lines are optional.

3.	Comments are in C-style /* ... */ pairs.

4.	Unlike C, the KEYMAPR language is case insensitive.

5.	Some of the predefined primitives have a syntax that looks like a C function call with one argument. For example,

SetMark(5);

Depending on the command, the argument is either a decimal integer constant, a character constant, or a string literal. All are specified using C syntax.

The syntax to define a key binding is

<key-sequence>: <command>; [: <hot-key-name>]

or

<key-sequence>:

BEGIN

  <command1>;

[ <command2>; ... ]

END; [<hot-key-name>]

The <key-sequence> is either a key (a character optionally preceded by Ctrl or Alt), or a series of keys separated by a plus sign (+). Note that the specification of the key characters themselves is case sensitive. For example, Ctrl-k+B is different than Ctrl-k+b, even though the latter is the same as CTRL- K+b.

The IDE associates message ID's with primitive names. The optional ": <hot key>" tells the IDE to add a help hint string (describing <key-sequence>) whenever a menu contains an item with the associated message ID is opened. Primitive names that may also be used as hot keys are tagged in the master list below.

Whitespace is allowed between the key-sequence and the colon, and each <command> can be either the name of a previously defined macro, or one of the predefined KEYMAPR primitives.

Note:	Changing the mapping of your keyboard using Keymapper, the Keystroke Mapping option in the EditorFile settings, or one of the four SpeedButtons on the Editor settings page can cause keyboard conflicts with standard Windows keyboard commands.

For example, the Brief keyboard mapping defined Alt+E as File|Open, while the standard Windows action for this key is to activate the Edit menu.


See Also

Keyboard Shortcuts

Key Codes

Named Keyboards

Named Keys

Predefined Editor Commands


Keymapper Key Codes

See Also	Keyboard Mapping

The IDE makes use of an extended character set that includes key combinations not normally available to DOS programs. Key codes can be specified in a script through any combination of the symbols "Ctrl-", "Shift-" "Alt-" and a character.

Some keys cannot be entered directly into a KEYMAPR script. To use these keys (called named keys), you must refer to them by their names.

Any key in a sequence--except the first key--can be preceded by one of the characters ^ or @. The caret (^) indicates that any combination of case and "Ctrl" can be used to type the key; that is, lowercase, uppercase, or control characters. The @ sign is used to indicate that case is insignificant for the following character, although "Ctrl" is not accepted.

For example:

Ctrl-k+b specifies a Ctrl-K followed by a lowercase b.

Ctrl-k+^b specifies a Ctrl-K followed by any of b, B, or Ctrl-B.

Ctrl-k+@B specifies Ctrl-K followed by either b or B.


See Also

Keyboard Shortcuts

Keymapper Macro Syntax

Named Keyboards

Named Keys

Predefined Editor Commands


Keymapper Named Keys

See Also	Keyboard Mapping

Key are specified as letters, numbers, or characters, optionally preceded by one or more of Ctrl-, Alt- or Shift-. The following names specify keys that cannot be typed as themselves in the KEYMAPR syntax.

Key name	Notes

Home

End

PgUp

PgDn

LfAr	Left arrow

RgAr	Right arrow

UpAr	Up arrow

DnAr	Down arrow

Ins

Del

Enter

Return	Same as Enter

BkSp	Backspace

Tab

Esc

Star	* key on the numeric keypad

Minus	- key on the numeric keypad

Plus	+ key on the numeric keypad

Space	Spacebar

PrtSc

Dash	- key on the main keyboard

F1 to F10	Function keys


See Also

Keyboard Shortcuts

Key Codes

Keymapper Macro Syntax

Named Keyboards

Predefined Editor Commands


Keymapper Named Keyboards

See Also	Keyboard Mapping

The IDE requires that several keystroke groups called keyboards be present in the script. A list of all required keyboards follows:

Keyboard Name	Notes

System	always active, put global key assignments here

Editor

MessageWindow

ProjectWindow

BreakpointView

CallStack

DataInspector

DebugLog

RegisterView

WatchView


See Also

Keyboard Shortcuts

Key Codes

Keymapper Macro Syntax

Named Keys

Predefined Editor Commands


Keymapper Predefined Editor Commands

See Also	Keyboard Mapping

KEYMAPR lets you use built-in editor commands and user-defined macros as commands within macros interchangeably, as long as you don't create any loops by having two macros calling each other, even via intermediate macros.

Note:	Changing the mapping of your keyboard using Keymapper, the Keystroke Mapping option in the EditorFile settings, or one of the four SpeedButtons on the Editor settings page can cause keyboard conflicts with standard Windows keyboard commands.

For example, the Brief keyboard mapping defined Alt+E as File|Open, while the standard Windows action for this key is to activate the Edit menu.

Keymapper Commands	Description

AddWatch	This command is in the IDE's main debug menu and opens a watch detail dialog for adding a watch. The name may be used as a hot key name.

AddWatchAtCursor	This command is in the editor's speed menu and adds a watch for the symbol under the caret. The name may be used as a hot key name.

BackspaceDelete	Deletes the character to the left of the caret. If the caret is at the start of a line, the line break is deleted.

BackTab	Moves the caret to the previous tab stop.

BottomOfScreen	Moves the caret to the line at the bottom of the pane leaving the column unchanged. If CursorPastEOL is off, this primitive will not move the caret past file end.

BrowseSymbolAtCursor	This command is in the editor's speed menu and calls up the browser on the symbol under the caret. The name may also be used as a hot key name.

BufferList	This command is in the IDE's main edit menu and opens a dialog containing a list of all open files. The name may be used as a hot key name.

CenterFixScreenPos	Adjusts the screen display to ensure the caret is visible. If any adjustment is necessary, adjust the display so the caret is close to being centered in the pane.

CenterLineInWindow	Scrolls the pane so that the caret line is centered vertically.

ClipAppendNextCut	Tells the editor to append the marked block to the clipboard when ClipMaybeAppendCut is called.

ClipClear	This name may be used as a hot key but is not a primitive

ClipCopy	Copies the selected text to the clipboard. This name may be used as a hot key.

ClipCut	Copies the currently marked block to the clipboard and deletes the block. This name may be used as a hot key.

ClipMaybeAppendCut	If ClipAppendNextCut was called, this function appends the marked block before invoking ClipCut.

ClipPaste	Copies the clipboard content into the editor at the caret position. This name may be used as a hot key.

ClipReplaceNextCut	Tells the editor not to append to the clipboard when ClipMaybeAppendCut is called.

CloseWindow	Closes the current window. This name may be used as a hot key.

CompileFile	Compiles the current editor file. This name may be used as a hot key.

CopyBlock	If there is a valid and highlighted (selected) text block, then at the caret location, inserts a copy of the characters that are selected and makes that the new selected text location.

CreatePane	This primitive creates a new editor pane. It takes a numeric argument that indicates a direction to create the pane. (0=up, 1=down, 2=left, 3=right)

CursorCharLeft	Moves caret left one character. This primitive will skip over tab virtual space and if the caret is at the beginning of a line, will move to the previous line. CursorCharRight Moves caret right one character. This primitive will skip over tab virtual space and if the caret is at the end of a line, will move to the next line.

CursorDown	Moves caret to next line without changing the current column.

CursorLeft	Moves caret one column to the left unless the caret is at the start of a line.

CursorLeftSkipWhite	Moves caret left skipping over white space characters (space and tab), stopping at line breaks.

CursorLeftSkipWord	Moves caret left skipping over word characters (e.g. '_', a-z and A-Z), stopping at line breaks.

CursorLeftSkipWordStream	Moves caret left skipping over word characters (e.g. '_', a-z and A-Z).

CursorLeftSkipNonWhite	Moves caret left skipping over non-white space characters (space and tab), stopping at line breaks.

CursorLeftSkipNonWord	Moves caret left skipping over non-word characters (e.g. '_', a-z and A-Z), stopping at line breaks.

CursorLineToWindowTop	Scrolls the pane so that the caret line is at the top of the pane.

CursorLineToWindowBottom	Scrolls the pane (if possible) so that the caret line is at the bottom of the pane.

CursorRight	Moves caret one column to the right unless the caret is at maximum line length (1024).

CursorRightSkipWhite	Moves caret right skipping over white space characters (space and tab), stopping at line breaks.

CursorRightSkipWord	Moves caret right skipping over word characters (e.g. '_', a-z and A-Z), stopping at line breaks.

CursorRightSkipWordStream	Moves caret right skipping over word characters (e.g. '_', a-z and A-Z).

CursorRightSkipNonWhite	Moves caret right skipping over non-white space characters (space and tab), stopping at line breaks.

CursorRightSkipNonWord	Moves caret right skipping over non-word characters (e.g. '_', a-z and A-Z), stopping at line breaks.

CursorSwitchedLeft	Like CursorLeft, but pays attention to caret through tab option setting (see SetCursorThroughTabMode).

CursorSwitchedRight	Like CursorRight, but pays attention to caret through tab option setting (see SetCursorThroughTabMode).

CursorUp	Moves the caret up one line (unless the caret is on line 1) without changing the column position.

DebugMenu	Sets the focus on the Debug submenu of the IDE's main menu

The following Debug.. primitives exist so that customers may assign their own hot keys to debug local menu items.

DebugAddAtLineBreakList

DebugAddWatchList

DebugAddWinMsgBreakList

DebugCaptureLog

DebugChange

DebugCommentLog

DebugDecimalReg

DebugDescend

DebugDetailBreakList

DebugDetailWatchList

DebugDWordReg

DebugEditBreakList

DebugEditCallStack

DebugEraseLog

DebugHexReg

DebugInspectBreakList

DebugInspectCallStack

DebugInspectData

DebugLogOptions

DebugNewExpr

DebugRangeInspect

DebugRemoveBreakList

DebugRemoveWatchList

DebugTypecast

DebugWordReg

DeleteBlock	If there is a valid and highlighted (selected) text block, deletes the characters that are in it.

DeleteBuffer	Removes the buffer associated with the active pane and replaces all views of that pane with the next one in the buffer list. If only one buffer exists, then no action is taken.

DeleteChar	Deletes the character at the current caret location.

DeletePane	This primitive deletes an existing editor pane. It takes a numeric argument that indicates a direction to delete the pane. (0=up, 1=down, 2=left, 3=right) If the argument is 4, the primitive deletes the current pane. if the argument is 5, the primitive deletes all but one of the panes in the window.

DeleteTempBlock	Deletes the temporary block as defined by SetTempPos and SetTempEndPos.

EditMenu	Sets the focus on the Edit submenu of the IDE's main menu

EndCursor	Moves caret to end of file buffer.

ExtendBlockBeg	Start marking a block of text.

ExtendBlockEnd	Finish marking a block of text (See ExtendBlockBeg.)

FileMenu	Sets the focus on the Edit submenu of the IDE's main menu

FirstNonBlank	Moves caret to first non-blank character on the current line

FixCursorPos	Move the caret so it is visible in the pane.

FixScreenPos	Scroll the pane so the caret is visible.

ForeTab	Move the caret to the next tab stop.

FullPaintScreen	Forces a full repaint of the editor pane.

GetFindString	Opens the search dialog. This name may be used as a hot key.

GoToLine	Opens the GoToLine dialog. This name may be used as a hot key.

GotoWindow1	Activates window #1

GotoWindow2	Activates window #2

GotoWindow3	Activates window #3

GotoWindow4	Activates window #4

GotoWindow5	Activates window #5

GotoWindow6	Activates window #6

GotoWindow7	Activates window #7

GotoWindow8	Activates window #8

GotoWindow9	Activates window #9

Help	Opens the help window. This name may be used as a hot key. HelpMenu Sets the focus on the Help submenu of the IDE's main menu

HelpKeywordSearch	Searches the help file for the symbol under the caret. This name may be used as a hot key.

HideBlock	Stop highlighting the selected text.

HighlightBlock	Start highlighting the selected text.

HomeCursor	Move the caret to the first character in the file.

IncrementalSearch	Start incremental search.

IndentBlock	Indent the marked block by the number of columns specified in the Editor Options page of the Multi-Page dialog.

InqAutoIndent	Returns TRUE if auto-indent mode is on.

InqAutoOutdent	Returns TRUE if auto-outdent mode is on.

InqColumnBlock	Returns TRUE if column block mode is on.

InqCursorAtBOL	Returns TRUE if caret is at column 1.

InqCursorAtBOW	Returns TRUE if caret is on the first line of a pane.

InqCursorAtEOL	Returns TRUE if caret is on end of the line.

InqCursorAtEOW	Returns TRUE if caret is on last line of a pane.

InqCursorInBlock	Returns TRUE if caret is inside the marked block.

InqCursorOnChar	Returns TRUE if caret is on a character

InqCursorPastEOL	Returns TRUE if caret is to the right the line end

InqCursorPastEOF	Returns TRUE if caret is past the end of the file

InqCursorPastRightMargin	Returns TRUE if caret is to the right of the right margin

InqEmptyLine	Returns TRUE if caret line is empty

InqInclusiveBlock	Returns TRUE if editor is in inclusive marking mode

InqLineBlock	Returns TRUE if editor is in line marking mode

InqNonInclusiveBlock	Returns TRUE if editor is in non-inclusive marking mode

InqOvertype	Returns TRUE if editor is in overtype mode

InqValidBlock	Returns TRUE if marked block is valid and visible

InqValidEmptyBlock	Returns TRUE if marked block is valid and visible or empty and visible

InqValidTempBlock	Returns TRUE if temp block is valid

InsertText	Inserts the literal "string" in the buffer at the current caret location. Use the syntax InsertText(string) to call this command.

Inspect	Opens a debug inspector window. This name may be used as a hot key.

InspectAtCursor	Opens a debug inspector window and initializes its edit field with the symbol under the caret. This name may be used as a hot key.

LeftOfLine	Moves caret to beginning of the current line.

LeftOfScreen	Moves caret to left edge of the pane

LiteralChar	Inserts the character at the current caret location, without doing any special processing for newline, tab characters, etc. Use the syntax LiteralChar(c), where c is a character or integer value.

LocalMenu	Opens the local menu for the window accepting keystrokes

LowerCaseBlock	Sets all characters in the marked block to lower case.

MakeProject	Makes project. This name may be used as a hot key.

MatchPairBackward	Same as MatchPairForward except if the caret is on a ' or ", searches backward for the matching character.

MatchPairForward	If the caret is on one of the characters (, ), {, }, [, ], or on the first character of one of the pairs /* or */, searches in the appropriate direction for the closest instance of the matching delimiter. If the caret is on the character ' or ", searches forward for the matching character. If a match is found, places the caret there.

Menu	Highlights top menu bar.

Modify	Evaluates expression/modify variable. This name may be used as a hot key.

MoveBlock	Like CopyBlock, but also deletes the original selected text.

MovePaneEdge	This primitive starts the process of moving a pane edge. It takes a numeric argument that indicates an edge to move. (0=up, 1=down, 2=left, 3=right)

if the argument is 4, the pane is made taller by one line,

if the argument is 5, the pane is made wider by one column,

if the argument is 6, the pane is made shorter by one line,

if the argument is 7, the pane is made thinner by one column.

MoveToBlockBeg	Moves caret to the location marked as the beginning of the selected text.

MoveToBlockEnd	Moves caret to the location marked as the end of the selected text.

MoveToMark	Moves the caret to the location saved with SetMark(n) command. Use the syntax MoveToMark(n), where n is a one-digit number, 0-9.

MoveToPane	This primitive moves the caret to the next pane. It takes a numeric argument that indicates which direction to move. (0=up, 1=down, 2=left, 3=right)

MoveToPrevPos	Moves the caret to the location specified by the "previous position marker."

MoveToRightMargin	Moves the caret to the right margin

MoveToTempEnd	Moves the caret to the saved temporary end marker.

MoveToTempPos	Moves the caret to the saved temporary marker.

MsgEditSrc	Navigates to the error line in a edit pane. This name may be used as a hot key.

MsgViewSrc	Shows the error line in a edit pane but leaves focus in the message window. This name may be used as a hot key.

NextBuffer	Show the previous buffer in the current edit pane.

NextError	Moves to next item in message window. This name may be used as a hot key.

NextWindow	Activates the next MDI window (puts the top window to the bottom of this list)

NullCmd	No operation. Calls the editor, but performs no function. Can be used to cause a keystroke to have no effect.

OpenFile	Opens the FileOpen dialog. This name may be used as a hot key.

OpenFileAtCursor	Reads the text under the caret and tries to open a file with that name. If the file open fails, the FileOpen dialog is opened. This name may be used as a hot key.

OpenFileInPane	Opens a file and places its contents in the active pane rather than opening a new window.

OutdentBlock	Deletes a leading space, if any, from the beginning of each line in the highlighted (selected) text.

PageDown	Moves caret down by number of lines in the window.

PageScreenDown	Scrolls screen down by number of lines in the window, leaving caret position unchanged.

PageScreenUp	Scrolls screen up by number of lines in the window, leaving caret position unchanged.

PageUp	Moves caret up by number of lines in the window.

PaintScreen	Forces editor to mark current pane dirty so once the keymap processor is finished, it will be completely re-drawn.

Pause	Takes one parameter that specifies how many milliseconds to wait.

PlaybackKeyMacro	Playback a saved keystroke macro.

PrevBuffer	Show the previous buffer in the current edit pane.

PrevError	Moves to previous item in message window. This name may be used as a hot key.

PrevWindow	Activates the previous MDI window (pulls the bottom to the top)

ProjectCollapseNode	Hide subtree under project element.

ProjectDemoteNode	Move current element one level farther from the root.

ProjectExpandNode	Show subtree under project element.

ProjectEndNodeSearch	Finish project window incremental search.

ProjectFirstNode	Move to first project element.

ProjectLastNode	Move to last project element.

ProjectMenu	Sets the focus on the Project submenu of the IDE's main menu

ProjectMoveUp	Scroll project view upward by one line.

ProjectMoveDown	Scroll project view downward by one line.

ProjectNextPage	Scroll to next project page.

ProjectNodeAction	Execute default project element action.

ProjectNodeDown	Move current element focus down one line.

ProjectNodeToggle	Collapses/expands a node in the project tree.

ProjectNodeUp	Move current element focus up one line.

ProjectPrevPage	Scroll to previous project page.

ProjectPromoteNode	Move current element one level closer to the root.

Quit	Exits the IDE, This name may be used as a hot key.

ReadBlock	Opens dialog box requesting a file name to be read into the buffer at the caret location and marked as selected text.

RecordKeyMacro	Start or stop recording a keystroke macro.

ReDo	Performs an Redo operation. Exactly what happens depends on the option settings. This name may be used as a hot key.

RepeatSearch	Searches again using previous settings. This name may be used as a hot key.

Replace	Opens the Replace dialog. This name may be used as a hot key.

TerminateProgram	Terminates the application being debugged. This name may be used as a hot key.

ReverseSearch	Search backward.

RightOfLine	Moves caret to end of current line.

RightOfScreen	Moves caret to right edge of the pane.

RunProgram	Makes and runs current executable. This name may be used as a hot key.

RunToHere	Runs program until statement at caret. This name may be used as a hot key.

SaveAll	Saves all edit buffers. This name may be used as a hot key.

SaveFile	Saves current editor buffer. This name may be used as a hot key.

SaveFileAs	Opens SeaveAs dialog. This name may be used as a hot key.

ScrollScreenDown	Scrolls screen down one line, leaving caret position unchanged.

ScrollScreenUp	Scrolls screen up one line, leaving caret position unchanged.

SearchMenu	Sets the focus on the Search submenu of the IDE's main menu

SetAutoIndent	Sets the Auto Indent option On.

SetAutoOutdent	Sets the Backspace Unindents option On.

SetBlockBeg	Sets the beginning of the selected text to be the character at the current caret location.

SetBlockEnd	Sets the end of the selected text to be the character at the current caret location.

SetColumnBlock	Set Column block marking mode.

SetCursorThroughTabMode	Sets the Cursor Through Tabs option On.

SetInclusiveBlock	Set Inclusive block marking mode.

SetInsertMode	Sets Insert/Overwrite option to Insert.

SetLineBlock	Set Line block marking mode.

SetMark	Sets a marker to point to the character at the current caret location, so a later MoveToMark(n) comand can restore the caret. Use the syntax SetMark(n), where n is a one digit number, 0-9.

SetNonInclusiveBlock	Set NonInclusive block marking mode.

SetOptimalFillMode	Sets Optimal Fill option On.

SetPrevPos	Sets a marker (the previous position marker) to point to the character at the current caret location. This marker location changes only by a call to SetPrevPos or SwapPrevPos.

SetSearchDirection	Sets the search direction based on the parameter sent: 0 - backward, 1 - forward.

SetSearchCase	Sets case-sensitive search based on the parameter sent: 0 - not case-sensitive, 1 - case-sensitive.

SetTabbingMode	Sets Use Tab Char option On.

SetTempEndPos	Saves the caret location in a temporary marker. This marker is similar to the end of a marked block and its mate is TempPos. This marker pair is used to do block operations without interferring with the user's marked block.

SetTempPos	Saves the caret location in a temporary marker. This marker is similar to the start of a marked block and its mate is TempEndPos. This marker pair is used to do block operations without interferring with the user's marked block.

SmartTab	Moves the cursor to the next column position based on the content of the previous line.

Step	Step over. This name may be used as a hot key.

SwapPrevPos	Exchanges the values of the caret and the "previous position marker."

SyntaxHighlight	Set syntax highlight on or off. Takes an argument, 0 is off, 1 is on.

ToggleAutoIndent	Toggles the state of the Auto Indent option.

ToggleAutoOutdent	Toggles the state of the Backspace Unindents option.

ToggleBreakpoint	Sets/Clears a breakpoint at the caret location. This name may be used as a hot key.

ToggleCase	Toggles the shift state of all characters in the marked block.

ToggleCaseSensitive	Toggles the Case Sensitive check box in the search dialog.

ToggleCursorThroughTabMode	Toggles the state of the Cursor Through Tabs option.

ToggleHideBlock	Toggles the state of the highlight (selected) text flag (see HighlightBlock).

ToggleInsert	Toggles state of Insert/Overwrite option.

ToggleMarginMarker	Toggles visiblity of the editor's right margin marker.

ToggleOptimalFillMode	Toggles state of Optimal Fill option.

ToggleRegExp	Toggles the Regular Expression check box in the search dialog.

ToggleTabbingMode	Toggles state of Use Tab Char option.

TopOfScreen	Moves caret to the top line currently displayed in the window, leaving column unchanged.

Trace	Trace into. This name may be used as a hot key.

UnDo	Performs an Undo operation. Exactly what happens depends on the option settings. This name may be used as a hot key.

UndoGroupWithAny	Place at start of macro when the effect of the macro is to be grouped with any other operation for undo purposes. This primitive is effective only when GroupUndo is on.

UndoGroupWithCursor	Place at start of macro when the effect of the macro is to be grouped with other cursor operations for undo purposes. This primitive is effective only when GroupUndo is on.

UndoGroupWithDelete	Place at start of macro when the effect of the macro is to be grouped with other delete operations for undo purposes. This primitive is effective only when GroupUndo is on.

UndoGroupWithInsert	Place at start of macro when the effect of the macro is to be grouped with other insert operations for undo purposes. This primitive is effective only when GroupUndo is on.

UndoGroupWithNone	Place at start of macro when the effect of the macro is to be grouped with no other operations for undo purposes. This primitive is effective only when GroupUndo is on.

UpperCaseBlock	Sets all characters in the marked block to upper case.

ViewCallStack	Open debugger's Call Stack window.

WindowCascade	Cascades the open windows. This name may be used as a hot key.

WindowList	Displays window list. This name may be used as a hot key.

WindowMenu	Sets the focus on the Window submenu of the IDE's main menu

WindowTileHorz	Horizontally tiles the open windows. This name may be used as a hot key.

WindowTileVert	Vertically tiles the open windows. This name may be used as a hot key.

WriteBlock	Opens dialog box requesting a file name to which the selected text will be written.

ZoomWindow	Maximizes/Restores the current window. This name may be used as a hot key.


See Also

Keyboard Shortcuts

Key Codes

Keymapper Macro Syntax

Named Keyboards

Named Keys


System Keystroke Mapping (Default)

Default Keyboard

F1	display context-sensitive Help

F4	Run to Cursor

F5	Debug|Add Breakpoint

F7	Debug|Trace Into

F8	Debug|Step Over

F9	Project|Build All

Shift+F4	Window|Tile Horizontal

Shift+F5	Window|Cascade

Alt+F5	Debug|Inspector

Alt+F7	Search|Previous Message

Alt+F8	Search|Next Message

Alt+F9	Project|Compile

Alt+F10	displays a SpeedMenu

Ctrl+F1	Help|Keyword Search

Ctrl+F2	Debug|Program Terminate

Ctrl+F3	View|Call Stack

Ctrl+F5	Debug|Add Watch

Ctrl+F7	Debug|Evaluate/Modify

Ctrl+F9	Debug|Run

Ctrl+Shift+P	playback a key macro

Ctrl+Shift+R	record a key macro

Ctrl+K+D	accesses the menu bar

Ctrl+K+S	File|Save


Clipboard Control (Default)

Default Keyboard

Ctrl+Ins	Edit|Copy

Shift+Del	Edit|Cut

Shift+Ins	Edit|Paste

Ctrl+C	Edit|Copy

Ctrl+V	Edit|Paste

Ctrl+X	Edit|Cut


Editor Keystroke Mapping (Default)

See Also	Default Keyboard

F3	Edit|Search Again

Ctrl+I	inserts a tab character

Ctrl+N	inserts a new line

Ctrl+P	causes next character to be interpreted as an ASCII sequence

Ctrl+S	search for next occurence of selection

Ctrl+T	deletes a word

Ctrl+Y	deletes a line

Ctrl+Z	scrolls up one screen

Ctrl+Shift+I	indent block

Ctrl+Shift+U	outdent block

Ctrl+Shift+Y	deletes to the end of a line

Shift+Ctrl+0	sets bookmark 0

Shift+Ctrl+1	sets bookmark 1

Shift+Ctrl+2	sets bookmark 2

Shift+Ctrl+3	sets bookmark 3

Shift+Ctrl+4	sets bookmark 4

Shift+Ctrl+5	sets bookmark 5

Shift+Ctrl+6	sets bookmark 6

Shift+Ctrl+7	sets bookmark 7

Shift+Ctrl+8	sets bookmark 8

Shift+Ctrl+9	sets bookmark 9

Ctrl+0	go to bookmark 0

Ctrl+1	go to bookmark 1

Ctrl+2	go to bookmark 2

Ctrl+3	go to bookmark 3

Ctrl+4	go to bookmark 4

Ctrl+5	go to bookmark 5

Ctrl+6	go to bookmark 6

Ctrl+7	go to bookmark 7

Ctrl+8	go to bookmark 8

Ctrl+9	go to bookmark 9

Alt+[	finds the matching delimiter (forward)

Alt+]	finds the matching delimiter (backward)

End 	moves to the end of a line

Home	moves to the start of a line

Enter	inserts a carriage return

Ins 	turns insert mode on/off

Del 	deletes the character to the right of the cursor

Tab 	inserts a tab

Space	inserts a blank space

Ctrl+Left Arrow	moves one word left

Ctrl+Right Arrow	moves one word right

Ctrl+Tab 	inserts a tab character

Ctrl+Backspace	deletes the word to the right of the cursor

Ctrl+Home	moves to the top of a file

Ctrl+End 	moves to the end of a file

Ctrl+Del 	deletes a currently selected block

Ctrl+Space	inserts a blank space

Ctrl+PgDn	moves to the bottom of a screen

Ctrl+PgUp	moves to the top of a screen

Shift+Tab 	deletes the character to the left of the cursor

Shift+Backspace	deletes the character to the left of the cursor

Shift+Left Arrow	selects the character to the left of the cursor

Shift+Right Arrow	selects the character to the right of the cursor

Shift+Up Arrow	moves the cursor up one line and selects from the left of the starting cursor position

Shift+Down Arrow	moves the cursor down one line and selects from the right of the starting cursor position

Shift+PgUp	moves the cursor up one screen and selects from the left of the starting cursor position

Shift+PgDn	moves the cursor down one line and selects from the right of the starting cursor position

Shift+End 	selects from the cursor position to the end of the current line

Shift+Home	selects from the cursor position to the start of the current line

Shift+Space	inserts a blank space

Shift+Enter	inserts a new line with a carriage return

Ctrl+Shift+Left Arrow	selects the word to the left of the cursor

Ctrl+Shift+Right Arrow	selects the word to the right of the cursor

Ctrl+Shift+Home	selects from the cursor position to the start of the current file

Ctrl+Shift+End 	selects from the cursor position to the end of the current file

Ctrl+Shift+PgDn	selects from the cursor position to the bottom of the screen

Ctrl+Shift+PgUp	selects from the cursor position to the top of the screen

Alt+Backspace	Edit|Undo

Alt+Shift+Backspace	Edit|Redo


Debugger Keystroke Mapping (Default)

Default Keyboard

Breakpoints Window 	Command

Ctrl+P 	Edit Breakpoint

Ctrl+I 	View Source

Ctrl+E 	Edit Source

Ctrl+R 	Delete Breakpoint

Ctrl+A 	Add Breakpoint

Call Stack

Ctrl+I 	View Source

Ctrl+E 	Edit Source

Data Inspector

Ctrl+I 	Inspect Object

Ctrl+N 	New Expression

Ctrl+R 	Set Range

Ctrl+C 	Change Value

Event Log

Ctrl+E 	Clear Events

Ctrl+C 	Save Events To File

Ctrl+A 	Add Comment

Ctrl+O 	Set Options

Register Window

Ctrl+H 	Show Hexadecimal

Ctrl+D 	Show Decimal

Ctrl+W 	Show Word

Ctrl+U 	Show Double Word

Watch View

Ctrl+P 	Edit Watch

Ctrl+A 	Add Watch

Ctrl+R 	Delete Watch


Message Window Keystroke Mapping (Default)

Default Keyboard

Enter	Edit Source

Esc	Window|Close

Space	Inspect Source


Pane Management Keystroke Mapping (Default)

Default Keyboard

Ctrl+O+E	Moves to the pane above the current pane

Ctrl+O+X	Moves to the pane below the current pane

Ctrl+O+S	Moves to the pane to the left of the current pane

Ctrl+O+D	Moves to the pane to the right of the current pane

Ctrl+O+UpArrow	Creates a new pane above the current pane

Ctrl+O+DownArrow	Creates a new pane below the current pane

Ctrl+O+LeftArrow	Creates a new pane to the left of the current pane

Ctrl+O+RightArrow	Creates a new pane to the right of the current pane

Ctrl+Shift+O+E	Moves the pane splitter bar above the current pane

Ctrl+Shift+O+X	Moves the pane splitter bar below the current pane

Ctrl+Shift+O+S	Moves the pane splitter bar to the left of the current pane

Ctrl+Shift+O+D	Moves the pane splitter bar to the right of the current pane

Ctrl+Shift+O+UpArrow	Deletes the pane above the current pane

Ctrl+Shift+O+DownArrow	Deletes the pane below the current pane

Ctrl+Shift+O+LeftArrow	Deletes the pane to the left of the current pane

Ctrl+Shift+O+RightArrow	Deletes the pane to the right of the current pane


Project Window Keystroke Mapping (Default)

Default Keyboard

Enter	Performs the default action for a node

Plus	Expands a node

Minus	Collapse a node

Spacebar	Collapses an expanded node; expands a collapsed node

Esc	Ends a node search

UpArrow	Moves up a node in the project

DownArrow	Moves down a node in the project

Home	Goes to the first (topmost) node in a project

End	Goes to the last (bottom) node in a project

PgUp	Scrolls down one screen in the project window

PgDn	Scrolls up one screen in the project window

Alt+LeftArrow	Promotes a node one level

Alt+RightArrow	Demotes a node one level

Alt+UpArrow	Moves a node up in the project

Alt+DownArrow	Moves a node down in the project


Editor Keystroke Mapping: Block Commands (Default)

See Also	Default Keyboard

Ctrl+K+B	marks the beginning of a block

Ctrl+K+C	copy a selected block

Ctrl+K+H	hides/shows a selected block

Ctrl+K+I	indents a block by the amount specified by the Block Indent option

Ctrl+K+K	marks the end of a block

Ctrl+K+L	marks the current line as a block

Ctrl+K+N	changes a block to uppercase

Ctrl+K+O	changes a block to lowercase

Ctrl+K+P	prints a selected block

Ctrl+K+R	reads a block from a file

Ctrl+K+T	marks a word as a block

Ctrl+K+U	outdents a block by the amount specified by the Block Indent option

Ctrl+K+V	moves a selected block

Ctrl+K+W	writes a selected block to a file

Ctrl+K+Y	deletes a selected block

Ctrl+O+C  	toggles a column block; use Shift and arrow keys to mark the remainder of the block

Ctrl+O+I  	toggles an inclusive block at the cursor position; use Shift and arrow keys to mark the remainder of the block

Ctrl+O+K  	toggles an non-inclusive block at the cursor position; use Shift and arrow keys to mark the remainder of the block

Ctrl+O+L  	toggles a line as a block at the cursor position; use Shift and arrow keys to mark the remainder of the block

Ctrl+Q+B	move to the beginning of a block

Ctrl+Q+K	moves to the end of a block


Editor Keystroke Mapping: Bookmark Operations (Default)

See Also	Default Keyboard

Ctrl+K+0 	sets bookmark 0

Ctrl+K+1 	sets bookmark 1

Ctrl+K+2 	sets bookmark 2

Ctrl+K+3 	sets bookmark 3

Ctrl+K+4 	sets bookmark 4

Ctrl+K+5 	sets bookmark 5

Ctrl+K+6 	sets bookmark 6

Ctrl+K+7 	sets bookmark 7

Ctrl+K+8 	sets bookmark 8

Ctrl+K+9 	sets bookmark 9

Ctrl+Q+0 	go to bookmark 0

Ctrl+Q+1 	go to bookmark 1

Ctrl+Q+2 	go to bookmark 2

Ctrl+Q+3 	go to bookmark 3

Ctrl+Q+4 	go to bookmark 4

Ctrl+Q+5 	go to bookmark 5

Ctrl+Q+6 	go to bookmark 6

Ctrl+Q+7 	go to bookmark 7

Ctrl+Q+8 	go to bookmark 8

Ctrl+Q+9 	go to bookmark 9


Editor Keystroke Mapping: Cursor Movement (Default)

See Also	Default Keyboard

Ctrl+Q+C	moves to end of a file

Ctrl+Q+D	moves to the end of a line

Ctrl+Q+P	moves cursor to previous position

Ctrl+Q+R	moves to the top of a file

Ctrl+Q+S	moves to the beginning of a line

Ctrl+Q+T	moves the current to the top of the window

Ctrl+Q+U	moves the current to the bottom of the window


Editor Keystroke Mapping: Miscellaneous Commands (Default)

See Also	Default Keyboard

Ctrl+Q+C	moves to end of a file

Ctrl+Q+D	moves to the end of a line

Ctrl+Q+P	moves cursor to previous position

Ctrl+Q+R	moves to the top of a file

Ctrl+Q+S	moves to the beginning of a line

Ctrl+Q+T	moves the current to the top of the window

Ctrl+Q+U	moves the current to the bottom of the window


Default Keystroke Mapping

Clipboard Control

Debugger

Editor

Message Window

Pane Management

Project Window

System


See Also

Block Operations

Bookmark Operations

Cursor Movement

Miscellaneous Commands


System Keystroke Mapping (IDE Classic)

IDE Classic

F1	Displays context-sensitive Help

F2	File|Save

F3	File|Open

F4	Run to Cursor

F5	Control|Maximize

F6	Control|Next Window

F7	Debug|Trace Into

F8	Debug|Step Over

F9	Project|Build All

Alt+F3	Control|Close

Alt+F5	Debug|Inspector

Alt+F7	Search|Previous Message

Alt+F8	Search|Next Message

Alt+F9	Project|Compile

Alt+F10	Displays a SpeedMenu

Alt+X 	File|Exit

Ctrl+F1	Help|Keyword Search

Ctrl+F2	Debug|Program Terminate

Ctrl+F3	View|Call Stack

Ctrl+F4	Debug|Evaluate/Modify

Ctrl+F7	Debug|Add Watch

Ctrl+F8	Debug|Add Breakpoint

Ctrl+F9	Debug|Run

Ctrl+Shift+P	Plays back a keyboard macro

Ctrl+Shift+R	Records a keyboard macro

Ctrl+K+D	Accesses the menu bar

Ctrl+K+S	File|Save


Clipboard Control (IDE Classic)

IDE Classic

Ctrl+Ins	Edit|Copy

Shift+Del	Edit|Cut

Shift+Ins	Edit|Paste


Editor Keystroke Mapping (IDE Classic)

See Also	IDE Classic

Ctrl+A	Moves one word left

Ctrl+C	Scrolls down one screen

Ctrl+D	Moves the cursor right one column, accounting for the autoindent setting

Ctrl+E	Moves the cursor up one line

Ctrl+F	Moves one word right

Ctrl+G	Deletes the character to the right of the cursor

Ctrl+H	Deletes the character to the left of the cursor

Ctrl+I	Inserts a tab

Ctrl+L	Edit|Search Again

Ctrl+N	Inserts a new line

Ctrl+P	Causes next character to be interpreted as an ASCII sequence

Ctrl+R	Moves up one screen

Ctrl+S	Moves the cursor left one column, accounting for the autoindent setting

Ctrl+T	Deletes a word

Ctrl+V	Turns insert mode on/off

Ctrl+W	Moves down one screen

Ctrl+X	Moves the cursor down one line

Ctrl+Y	Deletes a line

Ctrl+Z	Moves the cursor up one line

Ctrl+Shift+S	Performs an incremental search

End 	Moves to the end of a line

Home	Moves to the start of a line

Enter	Inserts a new line with a carriage return

Ins 	Turns insert mode on/off

Del 	Deletes the character to the right of the cursor

Tab 	Inserts a tab

Space	Inserts a blank space

Ctrl+Left Arrow	Moves one word left

Ctrl+Right Arrow	Moves one word right

Ctrl+Home	Moves to the top of a file

Ctrl+End 	Moves to the end of a file

Ctrl+PgDn	Moves to the bottom of a screen

Ctrl+PgUp	Moves to the top of a screen

Ctrl+Backspace	Move one word to the right

Ctrl+Del 	Deletes a currently selected block

Ctrl+Space	Inserts a blank space

Shift+Tab 	Deletes the character to the left of the cursor

Shift+Backspace	Deletes the character to the left of the cursor

Shift+Left Arrow	Selects the character to the left of the cursor

Shift+Right Arrow	Selects the character to the right of the cursor

Shift+Up Arrow	Moves the cursor up one line and selects from the left of the starting cursor position

Shift+Down Arrow	Moves the cursor down one line and selects from the right of the starting cursor position

Shift+PgUp	Moves the cursor up one screen and selects from the left of the starting cursor position

Shift+PgDn	Moves the cursor down one line and selects from the right of the starting cursor position

Shift+End 	Selects from the cursor position to the end of the current line

Shift+Home	Selects from the cursor position to the start of the current line

Shift+Space	Inserts a blank space

Shift+Enter	Inserts a new line with a carriage return

Ctrl+Shift+Left Arrow	Selects the word to the left of the cursor

Ctrl+Shift+Right Arrow	Selects the word to the right of the cursor

Ctrl+Shift+Home	Selects from the cursor position to the start of the current file

Ctrl+Shift+End 	Selects from the cursor position to the end of the current file

Ctrl+Shift+PgDn	Selects from the cursor position to the bottom of the screen

Ctrl+Shift+PgUp	Selects from the cursor position to the top of the screen

Alt+Backspace	Edit|Undo

Alt+Shift+Backspace	Edit|Redo


Debugger Keystroke Mapping (IDE Classic)

IDE Classic

Breakpoints Window 	Command

Ctrl+P 	Edit Breakpoint

Ctrl+I 	View Source

Ctrl+E 	Edit Source

Ctrl+R 	Delete Breakpoint

Ctrl+A 	Add Breakpoint

Call Stack

Ctrl+I 	View Source

Ctrl+E 	Edit Source

Data Inspector

Ctrl+I 	Inspect Object

Ctrl+N 	New Expression

Ctrl+R 	Set Range

Ctrl+C 	Change Value

Event Log

Ctrl+E 	Clear Events

Ctrl+C 	Save Events To File

Ctrl+A 	Add Comment

Ctrl+O 	Set Options

Register Window

Ctrl+H 	Show Hexadecimal

Ctrl+D 	Show Decimal

Ctrl+W 	Show Word

Ctrl+U 	Show Double Word

Watch View

Ctrl+P 	Edit Watch

Ctrl+A 	Add Watch

Ctrl+R 	Delete Watch


Message Window Keystroke Mapping (IDE Classic)

IDE Classic

Enter	Edit Source

Esc	Window|Close

Space	Inspect Source


Pane Management Keystroke Mapping (IDE Classic)

IDE Classic

Ctrl+O+E	Moves to the pane above the current pane

Ctrl+O+X	Moves to the pane below the current pane

Ctrl+O+S	Moves to the pane to the left of the current pane

Ctrl+O+D	Moves to the pane to the right of the current pane

Ctrl+O+UpArrow	Creates a new pane above the current pane

Ctrl+O+DownArrow	Creates a new pane below the current pane

Ctrl+O+LeftArrow	Creates a new pane to the left of the current pane

Ctrl+O+RightArrow	Creates a new pane to the right of the current pane

Ctrl+Shift+O+E	Moves the pane splitter bar above the current pane

Ctrl+Shift+O+X	Moves the pane splitter bar below the current pane

Ctrl+Shift+O+S	Moves the pane splitter bar to the left of the current pane

Ctrl+Shift+O+D	Moves the pane splitter bar to the right of the current pane

Ctrl+Shift+O+UpArrow	Deletes the pane above the current pane

Ctrl+Shift+O+DownArrow	Deletes the pane below the current pane

Ctrl+Shift+O+LeftArrow	Deletes the pane to the left of the current pane

Ctrl+Shift+O+RightArrow	Deletes the pane to the right of the current pane


Project Window Keystroke Mapping (IDE Classic)

IDE Classic

Enter	Performs the default action for a node

Plus	Expands a node

Minus	Collapse a node

Spacebar	Collapses an expanded node; expands a collapsed node

Esc	Ends a node search

UpArrow	Moves up a node in the project

Ctrl+E	Moves up a node in the project

DownArrow	Moves down a node in the project

Ctrl+X	Moves down a node in the project

Ctrl+PgUp	Goes to the first (topmost) node in a project

Ctrl+PgDn	Goes to the last (bottom) node in a project

PgUp	Scrolls down one screen in the project window

PgDn	Scrolls up one screen in the project window

Alt+LeftArrow	Promotes a node one level

Alt+RightArrow	Demotes a node one level

Alt+UpArrow	Moves a node up in the project

Alt+DownArrow	Moves a node down in the project


Editor Keystroke Mapping: Block Commands (IDE Classic)

See Also	IDE Classic

Ctrl+K+B	marks the beginning of a block

Ctrl+K+C	copy a selected block

Ctrl+K+H	hides/shows a selected block

Ctrl+K+I	indents a block by the amount specified by the Block Indent option

Ctrl+K+K	marks the end of a block

Ctrl+K+L	marks the current line as a block

Ctrl+K+N	changes a block to uppercase

Ctrl+K+O	changes a block to lowercase

Ctrl+K+P	prints a selected block

Ctrl+K+R	reads a block from a file

Ctrl+K+T	marks a word as a block

Ctrl+K+U	outdents a block by the amount specified by the Block Indent option

Ctrl+K+V	moves a selected block

Ctrl+K+W	writes a selected block to a file

Ctrl+K+Y	deletes a selected block

Ctrl+O+C  	toggles a column block; use Shift and arrow keys to mark the remainder of the block

Ctrl+O+I  	toggles an inclusive block at the cursor position; use Shift and arrow keys to mark the remainder of the block

Ctrl+O+K  	toggles an non-inclusive block at the cursor position; use Shift and arrow keys to mark the remainder of the block

Ctrl+O+L  	toggles a line as a block at the cursor position; use Shift and arrow keys to mark the remainder of the block

Ctrl+Q+B	move to the beginning of a block

Ctrl+Q+K	moves to the end of a block


Editor Keystroke Mapping: Bookmark Operations (IDE Classic)

See Also	IDE Classic

Ctrl+K+0 	sets bookmark 0

Ctrl+K+1 	sets bookmark 1

Ctrl+K+2 	sets bookmark 2

Ctrl+K+3 	sets bookmark 3

Ctrl+K+4 	sets bookmark 4

Ctrl+K+5 	sets bookmark 5

Ctrl+K+6 	sets bookmark 6

Ctrl+K+7 	sets bookmark 7

Ctrl+K+8 	sets bookmark 8

Ctrl+K+9 	sets bookmark 9

Ctrl+Q+0 	go to bookmark 0

Ctrl+Q+1 	go to bookmark 1

Ctrl+Q+2 	go to bookmark 2

Ctrl+Q+3 	go to bookmark 3

Ctrl+Q+4 	go to bookmark 4

Ctrl+Q+5 	go to bookmark 5

Ctrl+Q+6 	go to bookmark 6

Ctrl+Q+7 	go to bookmark 7

Ctrl+Q+8 	go to bookmark 8

Ctrl+Q+9 	go to bookmark 9


Editor Keystroke Mapping: Cursor Movement (IDE Classic)

See Also	IDE Classic

Ctrl+Q+C	moves to end of a file

Ctrl+Q+D	moves to the end of a line

Ctrl+Q+P	moves cursor to previous position

Ctrl+Q+R	moves to the top of a file

Ctrl+Q+S	moves to the beginning of a line

Ctrl+Q+T	moves the current to the top of the window

Ctrl+Q+U	moves the current to the bottom of the window


Editor Keystroke Mapping: Miscellaneous Commands (IDE Classic)

See Also	IDE Classic

Ctrl+Q+C	moves to end of a file

Ctrl+Q+D	moves to the end of a line

Ctrl+Q+P	moves cursor to previous position

Ctrl+Q+R	moves to the top of a file

Ctrl+Q+S	moves to the beginning of a line

Ctrl+Q+T	moves the current to the top of the window

Ctrl+Q+U	moves the current to the bottom of the window


IDE Classic Keystroke Mapping

Clipboard Control

Debugger

Editor

Message Window

Pane Management

Project Window

System


See Also

Block Operations

Bookmark Operations

Cursor Movement

Miscellaneous Commands


System Keystroke Mapping (Brief)

Brief Keyboard

F7	playback a key macro

F8	record a key macro

F9	Project|Make All

F10	access menu bar

Shift+F4	Window|Tile Horizontal

Alt+F2	Debug|Add Watch

Alt+F3	Debug|Inspector

Alt+F7	Run to Cursor

Alt+F9	access SpeedMenu

Alt+F10	Project|Compile

Ctrl+F1	Help|Keyword Search

Ctrl+F2	Debug|Program Terminate

Ctrl+F3	View|Call Stack

Ctrl+F7	Debug|Evaluate/Modify

Ctrl+F8	Debug|Add Breakpoint

Ctrl+F9	Debug|Run

Ctrl+N	Search|Next Message

Ctrl+P	Search|Previous Message

Alt+E	File|Open

Alt+H	display context-sensitive Help

Alt+O	File|Save As

Alt+W	File|Save

Alt+X	File|Exit

Alt+Z	access the File menu


Pane Management Keystroke Mapping (Brief)

Brief Keyboard

F1+Up Arrow	Moves to the pane above the current pane

F1+Down Arrow	Moves to the pane below the current pane

F1+Left Arrow	Moves to the pane to the left of the current pane

F1+Right Arrow	Moves to the pane to the right of the current pane

F2+Up Arrow	Moves the pane splitter bar above the current pane

F2+Down Arrow	Moves the pane splitter bar below the current pane

F2+Left Arrow	Moves the pane splitter bar to the left of the current pane

F2+Right Arrow	Moves the pane splitter bar to the right of the current pane

F3+Up Arrow	Creates a new pane above the current pane

F3+Down Arrow	Creates a new pane below the current pane

F3+Left Arrow	Creates a new pane to the left of the current pane

F3+Right Arrow	Creates a new pane to the right of the current pane

F4+Up Arrow	Deletes the pane above the current pane

F4+Down Arrow	Deletes the pane below the current pane

F4+Left Arrow	Deletes the pane to the left of the current pane

F4+Right Arrow	Deletes the pane to the right of the current pane


Clipboard Control (Brief)

Brief Keyboard

Ins	Edit|Paste

Plus (+)	Edit|Copy

Minus (-)	Edit|Cut


Editor Keystroke Mapping (Brief)

See Also	BRIEF KEYBOARD

F5	Search|Find (forward from cursor position)

F6	Search|Replace (forward from cursor position)

Alt+F2	Control|Maximize

Alt+F5	Search|Find (backward from cursor position)

Alt+F6	Search|Replace (backward from cursor position)

Shift+F5	Edit|Search Again

Shift+F6	Repeats the last Search|Replace operation

Esc	Cancels a command at a prompt or enters an escape character at the cursor

Del	Deletes a character or block at the cursor

Star	Edit|Undo

BackSpace	Deletes the character to the left of the cursor

Shift+BackSpace	Deletes the character to the left of the cursor

Tab	Inserts a tab character

Enter	Inserts a new line with a carriage return

Ctrl+-	Removes the buffer associated with the active pane

Ctrl+K	Deletes to the beginning of a line

Ctrl+M	Inserts a new line with a carriage return

Ctrl+S	Performs an incremental search

Ctrl+U	Edit|Redo

Ctrl+Backspace	Deletes the word to the left of the cursor

Ctrl+Enter	Inserts an empty new line

Alt+B	Displays a list of open files

Alt+D	Deletes a  line

Alt+G	Go To Line

Alt+K	Deletes of the end of a line

Alt+N	Displays the contents of the next file buffer

Alt+Q	Causes next character to be interpreted as an ASCII sequence

Alt+S	Search|Find

Alt+T	Search|Replace

Alt+U	Edit|Undo

Alt+BackSpace	Deletes the word to the right of the cursor

Alt+Hyphen	Displays the contents of the previous file buffer

Ctrl+Q+[	Finds the matching delimiter (forward)

Ctrl+Q+Ctrl+[	Finds the matching delimiter (forward)

Ctrl+Q+]	Finds the matching delimiter (backward)

Ctrl+Q+Ctrl+]	Finds the matching delimiter (backward)

Ctrl+O+A  	Opens the filename at the cursor

Ctrl+O+B  	Search|Browse Symbol

Ctrl+O+G  	Go To Line

Ctrl+O+O  	Toggles the case of a selection


Editor Keystroke Mapping: Bookmark Operations (Brief)

See Also	Brief Keyboard

Alt+0	sets bookmark 0

Alt+1	sets bookmark 1

Alt+2	sets bookmark 2

Alt+3	sets bookmark 3

Alt+4	sets bookmark 4

Alt+5	sets bookmark 5

Alt+6	sets bookmark 6

Alt+7	sets bookmark 7

Alt+8	sets bookmark 8

Alt+9	sets bookmark 9

Alt+J+0	go to bookmark 0

Alt+J+1	go to bookmark 1

Alt+J+2	go to bookmark 2

Alt+J+3	go to bookmark 3

Alt+J+4	go to bookmark 4

Alt+J+5	go to bookmark 5

Alt+J+6	go to bookmark 6

Alt+J+7	go to bookmark 7

Alt+J+8	go to bookmark 8

Alt+J+9	go to bookmark 9


Editor Keystroke Mapping: Block Commands (Brief)

See Also	Brief Keyboard

Alt+A	Marks an non-inclusive block

Alt+C	Marks a column as a block

Alt+L	Marks a line as a block

Alt+M	Marks an inclusive block

Alt+P	Prints the contents of a block

Alt+R	Reads a block from a file


Editor Keystroke Mapping: Cursor Movement (Brief)

See Also	Brief Keyboard

UpArrow	moves up one line in the same column position

DownArrow	moves down one line in the same column position

Home	moves to the start of a line

End	moves to the end of a line

Ctrl+T	Moves the current line to the center of the window

Shift+Tab	moves backward one tab stop

Left Arrow	moves to character to the left

Right Arrow	moves to character to the right

Ctrl+Left Arrow	moves to word to the left

Ctrl+Right Arrow	moves to word to the right

Ctrl+PgDn	moves to the end of a file

Ctrl+PgUp	moves to the beginning of a file

PgDn	moves down one screen in the current window

PgUp	moves up one screen in the current window

Shift+Home	moves to the first column in a window

Shift+End	moves to the last column in a window

Ctrl+Home	moves to the top of a screen in the same column position

Ctrl+End	moves to the bottom of a screen in the same column position

Ctrl+B	moves the current to the bottom of the window

Ctrl+C	moves the current to the center of the window

Ctrl+D	scrolls down one screen

Ctrl+E	scrolls down one screen


Editor Keystroke Mapping: Option Control (Brief)

See Also	Brief Keyboard

Alt+I	Toggles insert mode

Alt+Shift+I	Toggles insert mode

Ctrl+F5	Toggles case-sensitive searching

Ctrl+F6	Toggles regular expression searching


Debugger Keystroke Mapping (Brief)

Brief Keyboard

Breakpoints Window 	Command

Ctrl+P 	Edit Breakpoint

Ctrl+I 	View Source

Ctrl+E 	Edit Source

Ctrl+R 	Delete Breakpoint

Ctrl+A 	Add Breakpoint

Call Stack

Ctrl+I 	View Source

Ctrl+E 	Edit Source

Data Inspector

Ctrl+I 	Inspect Object

Ctrl+N 	New Expression

Ctrl+R 	Set Range

Ctrl+C 	Change Value

Event Log

Ctrl+E 	Clear Events

Ctrl+C 	Save Events To File

Ctrl+A 	Add Comment

Ctrl+O 	Set Options

Register Window

Ctrl+H 	Show Hexadecimal

Ctrl+D 	Show Decimal

Ctrl+W 	Show Word

Ctrl+U 	Show Double Word

Watch View

Ctrl+P 	Edit Watch

Ctrl+A 	Add Watch

Ctrl+R 	Delete Watch


Message Window Keystroke Mapping (Brief)

Brief Keyboard

Enter	Edit Source

Esc	Window|Close

Space	Inspect Source


Project Window Keystroke Mapping (Brief)

Brief Keyboard

Enter	Performs the default action for a node

Plus	Expands a node

Minus	Collapse a node

Spacebar	Collapses an expanded node; expands a collapsed node

Esc	Ends a node search

UpArrow	Moves up a node in the project

DownArrow	Moves down a node in the project

Home	Goes to the first (topmost) node in a project

End	Goes to the last (bottom) node in a project

PgUp	Scrolls down one screen in the project window

PgDn	Scrolls up one screen in the project window

Alt+LeftArrow	Promotes a node one level

Alt+RightArrow	Demotes a node one level

Alt+UpArrow	Moves a node up in the project

Alt+DownArrow	Moves a node down in the project


Brief Keystroke Mapping

Clipboard Control

Debugger

Editor

Message Window

Pane Management

Project Window

System


See Also

Block Operations

Bookmark Operations

Cursor Movement

Option Control


System Keystroke Mapping (Epsilon)

Epsilon Keyboard

F1	display context-sensitive Help

F5	Debug|Add Breakpoint

F8	Debug|Step Over

F9	Project|Make All

Shift+F4	Window|Tile Horizontal

Alt+F5	Debug|Inspector

Alt+F7	Search|Previous Message

Alt+F8	Search|Next Message

Alt+F9	Project|Compile

Alt+F10	displays a SpeedMenu

Ctrl+F2	Debug|Program Terminate

Ctrl+F5	Debug|Add Watch

Ctrl+F7	File|Save As

Ctrl+F9	Debug|Run

Ctrl+X+(	starts keyboard macro recording mode

Ctrl+X+)	ends keyboard macro recording mode

Ctrl+X+e	plays back the the last keyboard macro recorded

Ctrl+X+E	plays back the the last keyboard macro recorded

Ctrl+X+Ctrl+S	File|Save

Ctrl+X+Ctrl+W	File|Save


Clipboard Control (Epsilon)

Epsilon Keyboard

Alt+w	Edit|Copy

Alt+Y	Displays the Windows Clipboard

Ctrl+Alt+w	Edit|Copy (appends to current contents)

Ctrl+Y	Edit|Paste

Esc+Ctrl+w	Edit|Copy (appends to current contents)

Esc+w	Edit|Copy

Esc+Y	Displays the Windows Clipboard


Pane Management Keystroke Mapping (Epsilon)

Epsilon Keyboard

Alt+End	Moves the focus from the current pane to the next pane

Alt+Home	Moves the focus from the current pane to the previous pane

Alt+PgUp	Increases the width of the current window by one character

Alt+PgDn	Reduces the width of the active window by one character

Ctrl+Home	Moves the focus from the current pane to the previous pane

Ctrl+PgUp	Enlarge the current pane vertically

Ctrl+PgDn	Shrink the current pane vertically

Esc+End	Moves the focus from the current pane to the next pane

Esc+Home	Changes focus to the previous window in the buffer list

Ctrl+X+0	Closes the most recently opened pane

Ctrl+X+1	Causes the original pane to be the only one displayed in the edit window

Ctrl+X+2	Splits the current pane into two panes

Ctrl+X+5	Splits the current pane vertically into two panes

Ctrl+X+n	Moves the focus from the current pane to the next pane

Ctrl+X+N	Moves the focus from the current pane to the next pane

Ctrl+X+p	Moves the focus from the current pane to the previous pane

Ctrl+X+P	Moves the focus from the current pane to the previous pane


Editor Keystroke Mapping (Epsilon)

See Also	Epsilon Keyboard

Alt+&	Search|Replace

Alt+)	Locates the next matching delimiter (cursor must be on ')', '}' or ']')

Alt+*	Search|Replace (using regular expressions)

Alt+?	Displays context-sensitive help

Alt+\	Deletes spaces and tabs around the cursor on the same line

Alt+Backspace	Deletes the word to the left of the current cursor position

Alt+c	Capitalizes the current word

Alt+d	Deletes to word to the right of the cursor

Alt+Del	Deletes all text in the block between the cursor and the previous matching delimiter (cursor must be on ')', '}' or ']')

Alt+l	Converts the current word to lowercase

Alt+t	Transposes the two words on either side of the cursor

Alt+Tab	Indents to the current line to the text on the previous line

Alt+U	Converts a word to all uppercase

Alt+x	Invokes the specified command or macro

Backspace	Deletes the character to the left of the current cursor position

Ctrl+_	Displays context-sensitive help

Ctrl+Alt+B	Locates the next matching delimiter (cursor must be on ')', '}' or ']')

Ctrl+Alt+F	Locates the previous matching delimiter (cursor must be on ')', '}' or ']')

Ctrl+Alt+H	Deletes the word to the left of the current cursor position

Ctrl+Alt+K	Deletes all text in the block between the cursor and the next matching delimiter (cursor must be on ')', '}' or ']')

Ctrl+Alt+R	Search|Find (using regular expressions; backward from cursor)

Ctrl+Alt+S	Search|Find (using regular expressions)

Ctrl+D	Deletes the currently selected character or character to the right of the cursor

Ctrl+F10	Edit|Redo

Ctrl+F9	Edit|Undo

Ctrl+H	Deletes the character to the left of the current cursor position

Ctrl+K	Deletes to the end of the line, but does not remove the line separator or kills the empty line. At the end of line, it deletes just the line separator. Use two Ctrl+K's to completely delete a non-empty line.

Ctrl+L	Centers the active window

Ctrl+M	Inserts a carriage return

Ctrl+O	Inserts a new line after the cursor

Ctrl+Q	Interpret next character as an ASCII code

Ctrl+R	Incrementally searches backward through the current file

Ctrl+S	Incrementally searches for a string entered from the keyboard

Ctrl+T	Transposes the two characters on either side of the cursor

Ctrl+X+,	Search|Browse Symbol

Ctrl+X+(	Starts recording macro from the keyboard

Ctrl+X+)	Ends recording of a keyboard macro

Ctrl+X+.	Goes to the specified bookmark

Ctrl+X+0	Deletes the contents of the current window

Ctrl+X+Ctrl+E	Invoke a command processor

Ctrl+X+Ctrl+F	File|Open

Ctrl+X+Ctrl+N	Search|Next Message

Ctrl+X+Ctrl+R	Edit|Redo

Ctrl+X+Ctrl+S	File|Save

Ctrl+X+Ctrl+T	Transposes the two lines on either side of the cursor

Ctrl+X+Ctrl+U	Edit|Undo

Ctrl+X+Ctrl+W	File|Save

Ctrl+X+Ctrl+X	Exchanges the locations of the cursor position and a bookmark

Ctrl+X+E	Plays back the last macro recorded from the keyboard

Ctrl+X+e	Plays back the last macro recorded from the keyboard

Ctrl+X+G	Go To Line

Ctrl+X+g	Go To Line

Ctrl+X+I	Inserts the contents of a file at the cursor

Ctrl+X+i	Inserts the contents of a file at the cursor

Ctrl+X+M	Project|Make All

Ctrl+X+m	Project|Make All

Ctrl+X+P	Displays the previous window in the buffer list

Ctrl+X+p	Displays the previous window in the buffer list

Ctrl+X+R	Edit|Redo

Ctrl+X+r	Edit|Redo

Ctrl+X+S	File|SaveAll

Ctrl+X+s	File|SaveAll

Ctrl+X+U	Edit|Undo

Ctrl+X+u	Edit|Undo

Del	Deletes the currently selected character or character to the right of the cursor

Esc+%	Search|Replace

Esc+&	Search|Replace

Esc+)	Locates the next matching delimiter (cursor must be on ')', '}' or ']')

Esc+*	Search|Replace (using regular expressions)

Esc+?	Displays context-sensitive help

Esc+\	Deletes spaces and tabs around the cursor on the same line

Esc+c	Capitalizes the current word

Esc+d	Deletes to word to the right of the cursor

Esc+l	Converts the current word to lowercase

Esc+x	Invokes the specified command or macro

Esc+BackSpace	Deletes the word to the left of the current cursor position

Esc+Ctrl+B	Locates the next matching delimiter (cursor must be on ')', '}' or ']')

Esc+Ctrl+F	Locates the previous matching delimiter (cursor must be on ')', '}' or ']')

Esc+Ctrl+H	Deletes the word to the left of the current cursor position

Esc+Ctrl+K	Deletes all text in the block between the cursor and the next matching delimiter (cursor must be on ')', '}' or ']')

Esc+Ctrl+R	Search|Find (using regular expressions; backward from cursor)

Esc+Ctrl+S	Search|Find (using regular expressions)

Esc+Del	Deletes all text in the block between the cursor and the previous matching delimiter (cursor must be on ')', '}' or ']')

Esc+Home	Displays the previous window in the buffer list

Esc+T	Transposes the two words on either side of the cursor

Esc+t	Transposes the two words on either side of the cursor

Esc+Tab	Indents to the current line to the text on the previous line

Esc+U	Converts a word to all uppercase

F10	Edit|Redo

F2	Invokes the specified command or macro

F9	Edit|Undo


Editor Keystroke Mapping: Bookmark Operations (Epsilon)
Editor Keystroke Mapping (Bookmark Operations)

See Also	Epsilon Keyboard

Ctrl+@	Sets a bookmark at the current cursor position

Alt+@	Sets a bookmark at the current cursor position

Esc+@@	Sets a bookmark at the current cursor position


Editor Keystroke Mapping: Block Commands (Epsilon)
Editor Keystroke Mapping (Block Commands)

See Also	Epsilon Keyboard

Ctrl+Alt+\	Indents a block

Ctrl+W	Cuts a block and places its contents in the Clipboard

Ctrl+X+Ctrl+I	Indents a block

Ctrl+X+Tab	Indents a block

Ctrl+X+W	Writes a block to a file

Ctrl+X+w	Writes a block to a file

Esc+Ctrl+\	Indents a block


Editor Keystroke Mapping: Cursor Movement (Epsilon)
Editor Keystroke Mapping (Cursor Movement)

See Also	Epsilon Keyboard

Alt+,	Moves to the top of the current window

Alt+<	Goes to the start of the file

Alt+>	Goes to the end of the file

Alt+b	Moves the left one word

Alt+f	Moves to the right one word

Alt+LeftArrow	Moves to the beginning of the current line

Alt+m	Moves the cursor to the end of the indentation

Alt+RightArrow	Moves to the end of the current line

Alt+v	Moves up one page in the current file

Alt+Z	Scrolls the contents of the active window down a line

Ctrl+A	Moves to the beginning of the current line

Ctrl+B	Moves to the left one character

Ctrl+E	Moves to the end of the current line

Ctrl+End	Goes to the end of the file

Ctrl+F	Moves to the right one character

Ctrl+Home	Goes to the start of the file

Ctrl+LeftArrow	Moves the left one word

Ctrl+N	Moves the cursor down a line

Ctrl+P	Moves the cursor up a line

Ctrl+RgAr	Moves to the right one word

Ctrl+V	Moves down one page in the current file

Ctrl+Z	Scrolls the contents of the active window up a line

Esc+,	Moves to the top of the current window

Esc+.	Moves to the bottom of the current window

Esc+<	Goes to the start of the file

Esc+>	Goes to the end of the file

Esc+@b	Moves the left one word

Esc+@f	Moves to the right one word

Esc+@v	Moves up one page in the current file

Esc+LeftArrow	Moves to the beginning of the current line

Esc+M	Moves the cursor to the end of the indentation

Esc+m	Moves the cursor to the end of the indentation

Esc+RightArrow	Moves to the end of the current line

Esc+Z	Scrolls the contents of the active window down a line

DownArrow	Moves the cursor down a line

End	Moves to the bottom of the current window

Home	Moves to the top of the current window

Left Arrow	Moves to the left one character

PgDn	Moves down one page in the current file

PgUp	Moves up one page in the current file

RightArrow	Moves to the right one character

UpArrow	Moves the cursor up a line


Editor Keystroke Mapping: Option Control (Epsilon)
Editor Keystroke Mapping (Option Control)

See Also	Epsilon Keyboard

Ins	Toggles insert mode on/off


Debugger Keystroke Mapping (Epsilon)

Epsilon Keyboard

Breakpoints Window 	Command

Ctrl+P 	Edit Breakpoint

Ctrl+I 	View Source

Ctrl+E 	Edit Source

Ctrl+R 	Delete Breakpoint

Ctrl+A 	Add Breakpoint

Call Stack

Ctrl+I 	View Source

Ctrl+E 	Edit Source

Data Inspector

Ctrl+I 	Inspect Object

Ctrl+N 	New Expression

Ctrl+R 	Set Range

Ctrl+C 	Change Value

Event Log

Ctrl+E 	Clear Events

Ctrl+C 	Save Events To File

Ctrl+A 	Add Comment

Ctrl+O 	Set Options

Register Window

Ctrl+H 	Show Hexadecimal

Ctrl+D 	Show Decimal

Ctrl+W 	Show Word

Ctrl+U 	Show Double Word

Watch View

Ctrl+P 	Edit Watch

Ctrl+A 	Add Watch

Ctrl+R 	Delete Watch


Message Window Keystroke Mapping (Epsilon)

Epsilon Keyboard

Enter	Edit Source

Esc	Window|Close

Space	Inspect Source


Project Window Keystroke Mapping (Epsilon)

Epsilon Keyboard

Enter	Performs the default action for a node

Plus	Expands a node

Minus	Collapse a node

Spacebar	Collapses an expanded node; expands a collapsed node

Esc	Ends a node search

UpArrow	Moves up a node in the project

DownArrow	Moves down a node in the project

Home	Goes to the first (topmost) node in a project

End	Goes to the last (bottom) node in a project

PgUp	Scrolls down one screen in the project window

PgDn	Scrolls up one screen in the project window

Alt+LeftArrow	Promotes a node one level

Alt+RightArrow	Demotes a node one level

Alt+UpArrow	Moves a node up in the project

Alt+DownArrow	Moves a node down in the project


Epsilon Keystroke Mapping

Clipboard Control

Debugger

Editor

Message Window

Pane Management

Project Window

System


See Also

Block Operations

Bookmark Operations

Cursor Movement

Option Control


System Keystroke Mapping (TDW)

TDW Keyboard

F1	display context-sensitive Help

F2	Debug|Toggle Breakpoint

F4	Run to Cursor

F5	Window|Maximize

F7	Debug|Trace Into

F8	Debug|Step Over

F9	Debug|Run

F10	access the main menu bar

Alt+F3	Window|Close

Alt+F10	access the local menu

Ctrl+F4	Debug|Evaluate/Modify

Ctrl+F7	Debug|Add Watch

Alt+X 	File|Exit


Clipboard Control Keystroke Mapping (TDW)

TDW Keyboard

Shift+F3	Edit|Copy

Shift+F4	Edit|Paste


Editor Keystroke Mapping (TDW)

TDW Keyboard

Alt+F6	Edit|Undo

Ctrl+F	Edit|Buffer List

Ctrl+I	Debug|Inspect

Ctrl+L	Go To Line

Ctrl+N	Search|Search Again

Ctrl+P	moves the cursor to its previous position

Ctrl+S	Search|Find

Ctrl+W	Debug|Add Watch

Ctrl+Z	Edit|Undo


Debugger Keystroke Mapping (TDW)

TDW Keyboard

Breakpoints Window 	Command

Ctrl+P 	Edit Breakpoint

Ctrl+I 	View Source

Ctrl+E 	Edit Source

Ctrl+R 	Delete Breakpoint

Ctrl+A 	Add Breakpoint

Call Stack

Ctrl+I 	View Source

Ctrl+E 	Edit Source

Data Inspector

Ctrl+I 	Inspect Object

Ctrl+N 	New Expression

Ctrl+R 	Set Range

Ctrl+C 	Change Value

Event Log

Ctrl+E 	Clear Events

Ctrl+C 	Save Events To File

Ctrl+A 	Add Comment

Ctrl+O 	Set Options

Register Window

Ctrl+H 	Show Hexadecimal

Ctrl+D 	Show Decimal

Ctrl+W 	Show Word

Ctrl+U 	Show Double Word

Watch View

Ctrl+P 	Edit Watch

Ctrl+A 	Add Watch

Ctrl+R 	Delete Watch


Message Window Keystroke Mapping (TDW)

TDW Keyboard

Enter	Edit Source

Esc	Window|Close

Space	Inspect Source


Pane Management Keystroke Mapping (TDW)

TDW Keyboard

Ctrl+O+E	Moves to the pane above the current pane

Ctrl+O+X	Moves to the pane below the current pane

Ctrl+O+S	Moves to the pane to the left of the current pane

Ctrl+O+D	Moves to the pane to the right of the current pane

Ctrl+O+UpArrow	Creates a new pane above the current pane

Ctrl+O+DownArrow	Creates a new pane below the current pane

Ctrl+O+LeftArrow	Creates a new pane to the left of the current pane

Ctrl+O+RightArrow	Creates a new pane to the right of the current pane

Ctrl+Shift+O+E	Moves the pane splitter bar above the current pane

Ctrl+Shift+O+X	Moves the pane splitter bar below the current pane

Ctrl+Shift+O+S	Moves the pane splitter bar to the left of the current pane

Ctrl+Shift+O+D	Moves the pane splitter bar to the right of the current pane

Ctrl+Shift+O+UpArrow	Deletes the pane above the current pane

Ctrl+Shift+O+DownArrow	Deletes the pane below the current pane

Ctrl+Shift+O+LeftArrow	Deletes the pane to the left of the current pane

Ctrl+Shift+O+RightArrow	Deletes the pane to the right of the current pane


Project Window Keystroke Mapping (TDW)

TDW Keyboard

Enter	Performs the default action for a node

Plus	Expands a node

Minus	Collapse a node

Spacebar	Collapses an expanded node; expands a collapsed node

Esc	Ends a node search

UpArrow	Moves up a node in the project

DownArrow	Moves down a node in the project

Home	Goes to the first (topmost) node in a project

End	Goes to the last (bottom) node in a project

PgUp	Scrolls down one screen in the project window

PgDn	Scrolls up one screen in the project window

Alt+LeftArrow	Promotes a node one level

Alt+RightArrow	Demotes a node one level

Alt+UpArrow	Moves a node up in the project

Alt+DownArrow	Moves a node down in the project


Turbo Debugger for Windows Keystroke Mapping

Clipboard Control

Debugger

Editor

Message Window

Pane Management

Project Window

System


Command-Line Options

See Also	DPMI (Add On)

Code Generation

Option	Description

+filename	Use alternate configuration file named filename

@filename	Read compiler options from the response file filename

-1-	Generate 8086 compatible instructions.

-1	Generate the 80186/286 compatible instructions (16-bit only).

-2	Generate 80286 protected-mode compatible instructions (16-bit compiler only) (Default for 16-bit)

-3	Generate 80386 protected-mode compatible instructions. (Default for 32-bit compiler)

-4	Generate 80386/80486 protected-mode compatible instructions.

-5	Generate Pentium protected-mode compatible instructions.

-a	Byte alignment. (Default: -a- do not use byte-aligning.)

-A	Use only ANSI keywords. (Extentions like the far and near modifier no longer recognized.)

-AK	Use only Kernigham and Ritchie keywords.

-an	Align to n. 1=byte, 2=word (2 bytes), 4=double word (4 bytes\2 words 32 bit target only), 8=quad word (8 bytes\4 words 32 bit target only)

-AT	Use Borland C++ keywords (Alternately specified by -A-)

-AU	Use UNIX V keywords. (Extentions like the far and near modifier no longer recognized.)

-B	Compiles assembly and calls TASM or TASM32. If you don't have TASM in your path, checking this option generates an error. Also, old versions of TASM might have problems with 32-bit generated assembler code.

-b	Make enums always integer-sized. (Default: -b- make enums byte-sized when possible.) Note: Changing this default is not recommended.

-c	Compiles and assembles the named source files, but does not execute a link command.

-C	Turn nested comments on. (Default: -C- turn nested comments off.)

-d	Merge duplicate strings. (Default)

-dc	Move string literals from data segment to code segment (16-bit compiler only)

-Didentifier	Define identifier to the null string.

-Didentifier=string	Define identifier to string.

-efilename	Derives the executable program's name from filename by adding the file extension .EXE (the program name is then filename.EXE). filename must immediately follow the -e, with no intervening whitespace. Without this option, the linker derives the .EXE file's name from the name of the first source or object file in the file name list.

-Efilename	Use filename as the name of the assembler to use. (Default = TASM)

-f	Emulate floating point. (Default)

-f-	No Floating Point

-f287	Use 80287 hardware instructions (16-bit compiler only).

-F	Uses fast huge pointers.

-Fc	Generate COMDEFs (16-bit compiler only).

-Ff	Create far variables automatically.

-ff	Fast floating point. (Default)

-Ff=size	Create far variables automatically; set the threshold to size, where size is 0 to 65535 (16-bit target only).

-Ff=1	Array variable 'identifier' is near warning. (Default)

-Fm	Enables all the other -F options (-Fc, -Ff, and -Fs). Use this to quickly port code from other 16-bit compilers.

-Fs	Assume DS=SS in all memory models (16-bit compiler only).

-G	Optimize code for speed. (Default: -G- optimize code for size.)

-gn	Stop compiling after n messages. (Default: 100.)

-H	Generate and use precompiled headers. (Default)

-Hfilename	Sets the name of the file for precompiled headers

-h	This option offers an alternative method of calculating huge pointer expressions; this method is much faster than the standard method, but must be used with caution. When you use this option, huge pointers are normalized only when a segment wraparound occurs in the offset part. This causes problems with huge arrays if any array elements cross a segment boundary.

-H=filename	Set the name of the file for precompiled headers to filename.

-Hc	Cache precompiled headers. Use with -H, -Hxxx, -Hu, or -Hfilename. This option is useful when compiling more than one precompiled header. (32-bit compiler only)

-Hu	Use but do not generate precompiled headers.

-in	Make significant identifier length to be n, where n is between 8 and 250. (Default)

-Ipath	Set search path for directories for include files to path.

-Jg	Generate definitions for all template instances and merge duplicates. (Default)

-Jgd	Generate public definitions for all template instances; duplicates result in redefinition errors.

-Jgx	Generate external references for all template instances.

-jn	Errors: stop after n messages. (Default = 25)

-K	Default character type unsigned. (Default: -K- default character type signed.)

-k	Turn on standard stack frame. (Default)

-K2	Allow only two character types (signed and unsigned). Char is treated as signed. Allows compatibility with Borland C++ 3.1 and earlier.

-Lpath	Set search path for library files.

-lx	Pass option x to the linker (TLINK for BCC and TLINK32 for BCC32). More than one option can appear after the -l (which is a lowercase L).

-M	Instruct linker to create a full link map.

-mc	Compile using compact memory model (16-bit compiler only).

-mh	Compile using huge memory model.

-ml	Compile using large memory model (16-bit compiler only).

-mm	Compile using medium memory model (16-bit compiler only).

-mm!	Compile using medium memory model;assume DS!=SS (16-bit compiler only). (Note: there is no space between the -mm and the !.)

-ms	Compile using small memory model (16-bit compiler only). (Default)

-ms!	Compile using small memory model; assume DS! = SS (16-bit compiler only). (Note: there is no space between the -ms and the !.)

-mt	Compile using tiny memory model.

-mt!	Compile using tiny memory model. (Note: there is no space between the -mt and the !.)

-N	Check for stack overflow.

-npath	Set the output directory to path.

-O	Optimize jumps.

-O1	Generate smallest possible code (same as using -O, -Ob, -Oe, -Og, -Oi, -Ol, -Om, -Op, -Ot, -Ov, -k-, -Oc, and -Z).

-O2	Generate fastest possible code.

-Oa	Optimize assuming pointer expressions are not aliased on common subexpression evaluation.

-Ob	Eliminate dead code.

-Oc	Eliminate duplicate expressions within basic blocks.

-Od	Disable all optimizations.

-Oe	Allocate global registers and analyze variable live ranges.

-ofilename	Compile source file to filename.OBJ.

-Og	Eliminate duplicate expressions within functions.

-Oi	Expand common intrinsic functions.

-Ol	Compact loops.

-Om	Move invariant code out of loops.

-Op	Propagate copies.

-Ot	Generate fastest code (executable speed); Microsoft compatible.

-Ov	Enable loop induction variable and strength reduction.

-OW	Suppress the inc bp/dec bp on windows far functions (16-bit compiler only).

-Ox	Generate fastest code (executable speed); Microsoft compatible.

-P	Perform a C++ compile regardless of source file extension. (Default when extention is not specified. This is an uppercase P.)

-p	Use Pascal calling convention. (This is a lowercase p.)

-pc	Use C calling convention. (Default same as -pc or -p-)

-Pext	Perform a C++ compile regardless of source file extension and set the default extension to ext. This option is available because some programmers use .C or another extension as their default extension for C++ code.

-po	Use fastthis calling convention for passing this parameter in registers (16-bit compiler only).

-pr	Use fastcall calling convention for passing parameters in registers.

-ps	Use stdcall calling convention (32-bit compiler only).

-R	Include browser information in generated .OBJ files.

-r	Use register variables. (Default)

-rd	Allow only declared register variables to be kept in registers.

-RT	Enable runtime type information. (Default)

-S	Generate assembler source compiles the named source files and produces assembly language output files (.ASM), but does not assemble. When you use this option, Borland C++ includes the C or C++ source lines as comments in the produced .ASM file.

-T-	Remove all previous assembler options.

-Tstring	Pass string as an option to TASM, TASM32, or assembler specified with -E.

-tW	Make the target a Windows .EXE with all functions exportable. (Default)

-tWC	Make the target a console .EXE.

-tWCD	Make the target a console .DLL, all functions exportable

-tWCDE	Make the target a console .DLL, explicit functions exportable

-tWD	Make the target a Windows .DLL with all functions exportable.

-tWDE	Make the target a Windows .DLL with explicit functions exportable.

-tWE	Make the target a Windows .EXE with explicit functions exportable.

-tWM	Make a multithreaded application or DLL.

-tWS	Make the target a Windows .EXE that uses smart callbacks (16-bit compiler only).

-tWSE	Make the target a Windows .EXE that uses smart callbacks, with explicit functions exportable and exported (16-bit compiler only).

-u	Generate underscores for symbols. (Default)

-Uname	Undefines any previous definitions of the named identifier name.

-v	Turn on source debugging.

-V	Create smart C++ virtual tables. (Default)

-V0	Create external C++ virtual tables.

-V1	Create public C++ virtual tables.

-Va	Pass class arguments by reference to a temporary variable (16-bit compiler only).

-Vb	Make virtual base class pointer the same size as the 'this' pointer of the class (16-bit compiler only). (Default)

-Vc	Do not add the hidden members and code to classes with pointers to virtual base class members (16-bit compiler only).

-Vf	Far C++ virtual tables (16-bit compiler only).

-Vh	Treat 'far' classes as 'huge' (16-bit compiler only) When on, the compiler treats all __far classes as __huge.

-vi	Turn on inline expansion (-vi- turns off inline expansion).

-Vmd	Use the smallest representation for member pointers.

-Vmm	Member pointers support multiple inheritance.

-Vmp	Honor the declared precision for all member pointer types.

-Vms	Member pointers support single inheritance.

-Vmv	Member pointers have no restrictions (most general representation). (Default)

-Vo	Set all backward compatible switches. Use this when linking with libraries built with an older version of Borland C++.

-Vp	Pass the 'this' parameter to 'pascal' member functions as the first.

-Vs	Local C++ virtual tables.

-Vt	Place the virtual table pointer after nonstatic data members (16-bit compiler only).

-Vv	This option directs the compiler not to change the layout of any classes (which it needs to do to allow pointers to virtual base class members, which were not supported in previous versions of Borland C++). If this option is used, the compiler will not be able to create a pointer to a member of a base class that can be reached only from the derived class through two or more levels of virtual inheritance.

-W	Creates a Windows GUI application.

-w	Display warnings on.

-w!	Do not compile to .OBJ if warnings were found. (Note: there is no space between the -w and the !.)

-wamb	Ambiguous operators need parentheses.

-wamp	Superfluous & with function.

-wasm	Unknown assembler instruction.

-waus	'identifier' is assigned a value that is never used. (Default)

-wbbf	Bit fields must be signed or unsigned int.

-wbei	Initializing 'identifier' with 'identifier'. (Default)

-wbig	Hexadecimal value contains more than three digits. (Default)

-WC	Creates a 32-bit console mode application.

-wccc	Condition is always true OR Condition is always false. (Default)

-WCD	Creates a 32-bit console mode DLL with all functions exportable and exported.

-WCDE	Creates a 32-bit console mode DLL with explicit functions exportable and exported.

-wcln	Constant is long.

-wcpt	Nonportable pointer comparison. (Default)

-WD	Creates a GUI DLL with all functions exportable.

-WDE	Creates a GUI DLL with explicit functions exportable and exported.

-wdef	Possible use of 'identifier' before definition.

-wdpu	Declare type 'type' prior to use in prototype (Default)

-wdsz	Array size for 'delete' ignored. (Default)

-wdup	Redefinition of 'macro' is not identical (Default)

-WE	Make the target a Windows .EXE with explicit functions exportable and exported.

-weas	'type' assigned to 'enumeration'. (Default)

-weff	Code has no effect. (Default)

-wext	'identifier' is declared as both external and static (Default)

-whch	Handler for '<type1>' Hidden by Previous Handler for '<type2>'

-whid	'function1' hides virtual function 'function2' (Default)

-wibc	Base class '<base1>' is also a base class of '<base2>' (Default)

-will	Ill-formed pragma. (Default)

-winl	Functions containing reserved words are not expanded inline (Default)

-wlin	Temporary used to initialize 'identifier'. (Default)

-wlvc	Temporary used for parameter 'parameter' in call to 'function' (Default)

-WM	Make a multithreaded application or DLL.

-wmpc	Conversion to type fails for members of virtual base class base. (Default)

-wmpd	Maximum precision used for member pointer type type. (Default)

-wmsg	User-defined warnings . This option allows user-defined messages to appear in the IDE message window.

-wnak	Non-ANSI Keyword Used: '<keyword>' (Note: Use of this option is a requirement for ANSI conformance.)

-wncf	Non-const function 'function' called for const object. (Default)

-wnci	The constant member 'identifier' is not initialized. (Default)

-wnod	No declaration for function 'function'

-wnsf	Declaration of static function 'func(...)' ignored.

-wnst	Use qualified name to access nested type 'type' (Default)

-wntd	Use '> >' for nested templates instead of '>>'. (Default)

-wnvf	Non-volatile function function called for volatile object. (Default)

-wobi	Base initialization without a class name is now obsolete (Default)

-wobs	Identifier is obsolete. (Default)

-wofp	Style of function definition is now obsolete. (Default)

-wovl	Overload is now unnecessary and obsolete. (Default)

-wpar	Parameter 'parameter' is never used. (Default)

-wpch	Cannot create precompiled header: header. (Default)

-wpia	Possibly incorrect assignment. (Default)

-wpin	Initialization is only partially bracketed.

-wpre	Overloaded prefix operator 'operator' used as a postfix operator.

-wpro	Call to function with no prototype. (Default)

-wrch	Unreachable code. (Default)

-wret	Both return and return of a value used. (Default)

-wrng	Constant out of range in comparison. (Default)

-wrpt	Nonportable pointer conversion. (Default)

-wrvl	Function should return a value. (Default)

-WS	Make the target a Windows .EXE that uses smart callbacks (16-bit compiler only).

-WSE	Make the target a Windows .EXE that uses smart callbacks, with explicit functions exportable (16-bit compiler only).

-wsig	Conversion may lose significant digits.

-wstu	Undefined structure 'structure'

-wstv	Structure passed by value.

-wsus	Suspicious pointer conversion. (Default)

-wucp	Mixing pointers to different 'char' types.

-wuse	'identifier' declared but never used.

-wvoi	Void functions may not return a value. (Default)

-wxxx	Enable xxx warning message. (Default)

-wzdi	Division by zero (Default)

-X	Disable compiler autodependency output. (Default: -X- use compiler autodependency output.)

-x	Enable exception handling. (Default)

-xc	Enable compatible exception handling.

-xd	Enable destructor cleanup. (Default)

-xf	Enable fast exception prologs.

-xp	Enable exception location information.

-Y	Generate overlay-compatible code. (16-bit compiler only)

-Yo	Overlay compiled files. (16-bit compiler only)

-y	Line numbers on.

-Z	Enable register load suppression optimization.

-zAname	Code class set to name.

-zBname	BSS class set to name.

-zCname	Code segment class set to name.

-zDname	BSS segment set to name.

-zEname	Far segment set to name (16-bit compiler only).

-zFname	Far class set to name (16-bit compiler only).

-zGname	BSS group set to name.

-zHname	Far group set to name (16-bit compiler only).

-zPname	Code group set to name.

-zRname	Data segment set to name.

-zSname	Data group set to name.

-zTname	Data class set to name.

-zVname	Far virtual segment set to name (16-bit compiler only).

-zWname	Far virtual class set to name (16-bit compiler only).

-zX*	Use default name for X. For example, -zA assigns the default class name CODE to the code segment class.


See Also

Command-Line Options By Function

Entering Directories for Command-Line Options

File-search Algorithms

Option Precedence Rules

Using Configuration Files

Using Response Files

Using the Command-line Compilers


Using the Command-line Compilers

See Also

Two command-line compilers (BCC.EXE and BCC32.EXE) are provided with Borland C++. BCC.EXE is a 16-bit application that generates 16-bit code. BCC32.EXE is a 32-bit application that generates 32-bit code. BCC and BCC32 work the same, but have different defaults and generate different code. Unless specified, instructions and options for BCC also apply to BCC32.

Entering BCC.EXE commands

You can use BCC to send files to TLINK (.OBJ files) or TASM (.ASM files if you have TASM installed on your machine). The general syntax for BCC.EXE is

BCC [option [option...]] filename [filename...]

To see a list of common compiler options, type BCC at the command line (without any options or file names), then press Enter.

The BCC command and each option and file name must be separated by at least one space. Precede each option by either a hyphen (-) or a forward slash (/); for example,

BCC -Ic:\code\hfiles

Options and file names entered on the command line override settings in configuration files.

Default settings

BCC.EXE and BCC32.EXE have options that are on by default. These are indicated in the Command-Line Options list. To turn off a default option or to override options in a configuration file, type BCC -option-.

Files without extensions and files with the .CPP extension compile as C++ files. Files with a .C extension or with extensions other than .CPP, .OBJ, .LIB, or .ASM compile as C files.

BCC tries to link with a module-definition file with the same name as the executable. To link with a module-definition file with a different name, specify the name on the compiler command line. You must include the .DEF extension. You cannot link with more than one module-definition file.


See Also

Command Line Options

Command-Line Options By Function

Using Configuration Files

Entering Directories for Command-Line Options

File-search Algorithms

Option Precedence Rules

Using Response Files


Using Configuration Files

See Also

If you repeatedly use a certain set of options, you might want to list them in a configuration file (a standard ASCII text file). You must separate options by spaces; options can appear on one or more lines.

TURBOC.CFG configures BCC.EXE

BCC32.CFG configures BCC32.EXE

By default, BCC.EXE and BCC32.EXE use a configuration file called TURBOC.CFG. BCC looks for TURBOC.CFG first in the directory where you typed BCC, then in the directory where BCC.EXE or BCC32.EXE is stored.

You can create multiple configuration files or modify TURBOC.CFG. To use a configuration file, type:

+[path]filename

in the BCC command line.

For example, to use a configuration file called MYCONFIG.CFG, you could use the following command line:

BCC +C:\MYCONFIG.CFG mycode.cpp

Options typed on the BCC command line override configuration files.


See Also

Command Line Options

Command-Line Options By Function

Entering Directories for Command-Line Options

File-search Algorithms

Option Precedence Rules

Using Response Files

Using the Command-line Compilers


Using Response Files

See Also

To specify multiple options or files on the command line, place them in a response file (a standard ASCII text file). Response files let you have a longer command line than most operating systems allow. Options typed at the command line override any option or file name in a response file.

Type the command-line options you want to use in a file and save the file. Response files shipped with Borland C++ have the .RSP extension. Options can appear on one or more lines in the file, separated by spaces.

The syntax for using a single response file is:

BCC @[path]respfile.txt.

The syntax for using multiple response files is:

BCC @[path]respfile.txt @[path]otheresp.txt


See Also

Command Line Options

Command-Line Options By Function

Entering Directories for Command-Line Options

File-search Algorithms

Option Precedence Rules

Using Configuration Files

Using the Command-line Compilers


Option Precedence Rules

See Also

BCC.EXE and BCC32.EXE evaluate options from left to right, and follows these rules:

If you duplicate any option except -D, -U,  -I, or -L, the last option typed overrides any earlier one. (-D, -U,  -I, and -L are cumulative.)

Options typed at the command line override configuration and response file options.


See Also

Command Line Options

Command-Line Options By Function

Entering Directories for Command-Line Options

File-search Algorithms

Using Configuration Files

Using the Command-line Compilers

Using Response Files


Command-Line Options by Function

See Also	DPMI (Add On)

Configuration Files

@filename	Read compiler options from the response file "filename"

Response Files

+filename	Use alternate configuration file "filename"

Compiler|Defines

-Dname	Define "name" to the null string.

-Dname=string	Define "name" to "string".

-Uname	Undefine any previous definitions of "name".

Compiler|Code Generation

-b	Make enums always integer-sized. (Default: -b- make enums byte-sized when possible.)

-d	Merge duplicate strings. (Default)

-K	Default character type unsigned. (Default: -K- default character type signed.)

-po	Use fastthis calling convention for passing this parameter in registers (16-bit compiler only).

-r	Use register variables. (Default)

-rd	Allow only declared register variables to be kept in registers.

-Y	Generate overlay-compatible code.

-Yo	Overlay compiled files.

Compiler|Floating Point

-f	Emulate floating point. (Default)

-ff	Fast floating point. (Default)

-fp	Correct Pentium FDIV Flaw

Compiler|Compiler Output

-Fc	Generate COMDEFs (16-bit compiler only).

-u	Generate underscores. (Default)

-X	Disable compiler autodependency output. (Default: -X- use compiler autodependency output.)

Compiler|Source

-A	Use only ANSI keywords.

-AK	Use only Kernigham and Ritchie keywords.

-AT	Use Borland C++ keywords (also -A-)

-AU	Use only UNIX V keywords.

-C	Turn nested comments on. (Default: -C- turn nested comments off.)

-in	Make significant identifier length to be "n". (Default)

Compiler|Debugging

-k	Turn on standard stack frame. (Default)

-N	Check for stack overflow.

-R	Include browser information in generated .OBJ files.

-v	Turn on source debugging.

-vi	Control expansion of inline functions.

-y	Line numbers on.

Compiler|Precompiled Headers

-H	Generate and use precompiled headers. (Default)

-Hfilename	Sets the name of the file for precompiled headers

-H=filename	Set the name of the file for precompiled headers.

-Hu	Use but do not generate precompiled headers.

16-bit Compiler|Processor

-1-	Generate 8086 compatible instructions.

-1	Generate the 80186/286 compatible instructions (16-bit only).

-2	Generate 80286 protected-mode compatible instructions (16-bit compiler only) (Default for 16- bit)

-3	Generate 80386 protected-mode compatible instructions. (Default for 32-bit)

-4	Generate 80386/80486 protected-mode compatible instructions.

-a	Align byte. (Default: -a- use byte-aligning.)

-an	Align to "n". 1=byte, 2=word (16-bit = 2 bytes), 4=Double word (32-bit compiler only, 4 bytes)

16-bit Compiler|Calling Convention

-p	Use Pascal calling convention.

-pc	Use C calling convention. (Default: -pc, -p-.)

-po	Use fastthis calling convention for passing this parameter in registers.

-pr	Use fastcall calling convention for passing parameters in registers.

16-bit Compiler|Memory Model

-dc	Move string literals from data segment to code segment (16-bit compiler only)

-F	Uses fast huge pointers.

-Ff	Create far variables automatically.

-Ff=size	Create far variables automatically; set the threshold to "size" (16-bit compiler only).

-Fs	Assume DS=SS in all memory models (16-bit compiler only).

-mc	Compile using compact memory model (16-bit compiler only).

-mh	Compile using huge memory model.

-ml	Compile using large memory model (16-bit compiler only).

-mm	Compile using medium memory model (16-bit compiler only).

-mm!	Compile using medium memory model;assume DS!=SS (16-bit compiler only). (Note: there is no space between the -mm and the !.)

-ms	Compile using small memory model (16-bit compiler only). (Default)

-ms!	Compile using small memory model; assume DS! = SS (16-bit compiler only). (Note: there is no space between the -ms and the !.)

-Vf	Far C++ virtual tables (16-bit compiler only).

16-bit Compiler|Segment Names Data

-zBname	BSS class set to "name".

-zDname	BSS segment set to "name".

-zGname	BSS group set to "name".

-zRname	Data segment set to "name".

-zSname	Data group set to "name".

-zTname	Data class set to "name".

16-bit Compiler|Segment Names Far Data

-zEname	Far segment set to "name".

-zFname	Far class set to "name".

-zHname	Far group set to "name".

-zVname	Far virtual segment set to "name" (16-bit compiler only).

-zWname	Far virtual class set to "name" (16-bit compiler only).

16-bit Compiler|Segment Names Code

-zAname	Code class set to "name".

-zCname	Code segment class set to "name".

-zPname	Code group set to "name".

16-bit Compiler|Entry/Exit Code

-tW	Make the target a Windows .EXE with all functions exportable. (Default)

-tWD	Make the target a Windows .DLL with all functions exportable.

-tWDE	Make the target a Windows .DLL with explicit functions exportable.

-tWE	Make the target a Windows .EXE with explicit functions exportable.

-tWS	Make the target a Windows .EXE that uses smart callbacks (16-bit compiler only).

-tWSE	Make the target a Windows .EXE that uses smart callbacks, with explicit functions exportable (16-bit compiler only).

-W	Make the target a Windows .EXE with all functions exportable. (Default) (Note: there is no space between the -W and the !.)

-WD	Make the target a Windows .DLL with all functions exportable.

-WDE	Make the target a Windows .DLL with explicit functions exportable.

-WE	Make the target a Windows .EXE with explicit functions exportable.

-WS	Make the target a Windows .EXE that uses smart callbacks (16-bit compiler only).

-WSE	Make the target a Windows .EXE that uses smart callbacks, with explicit functions exportable (16-bit compiler only).

32-bit Compiler|Processor

-3	Generate 80386 protected-mode compatible instructions. (Default for 32-bit)

-4	Generate 80386/80486 protected-mode compatible instructions.

-5	Generate Pentium protected-mode compatible instructions.

32-bit Compiler|Calling Convention

-p	Use Pascal calling convention.

-pc	Use C calling convention. (Default: -pc, -p-.)

-pr	Use fastcall calling convention for passing parameters in registers.

-ps	Use stdcall calling convention (32-bit compiler only).

C++ Options|Member Pointer

-Vmd	Use the smallest representation for member pointers.

-Vmm	Member pointers support multiple inheritance.

-Vmp	Honor the declared precision for all member pointer types.

-Vms	Member pointers support single inheritance.

-Vmv	Member pointers have no restrictions (most general representation). (Default)

C++ Options|C++ Compatibility

-K2	Allow only two character types (signed and unsigned). Char is treated as signed. Compatibility with Borland C++ 3.1 and earlier.

-Va	Pass class arguments by reference to a temporary variable (16-bit compiler only).

-Vb	Make virtual base class pointer same size as 'this' pointer of the class (16-bit compiler only). (Default)

-Vc	Do not add the hidden members and code to classes with pointers to virtual base class members (16-bit compiler only).

-Vp	Pass the 'this' parameter to 'pascal' member functions as the first.

-Vt	Place the virtual table pointer after nonstatic data members (16-bit compiler only).

C++ Options|Virtual Tables

-V	Use smart C++ virtual tables. (Default)

-V0	External C++ virtual tables.

-V1	Public C++ virtual tables.

-Vs	Local C++ virtual tables.

C++ Options|Templates

-Jg	Generate definitions for all template instances and merge duplicates. (Default)

-Jgd	Generate public definitions for all template instances; duplicates result in redefinition errors.

-Jgx	Generate external references for all template instances.

C++ Options|Exception Handling

-RT	Enable runtime type information. (Default)

-x	Enable exception handling. (Default)

-xc	Enable compatible exception handling.

-xd	Enable destructor cleanup. (Default)

-xf	Enable fast exception prologs.

-xp	Enable exception location information.

Optimizations

-Od	Disable all optimizations.

Optimizations|Specific

-O1	Generate smallest possible code (same as using -O, -Ob, -Oe, -Og, -Oi, -Ol, -Om, -Op, -Ot, -Ov, -k-, -Oc, and -Z)

-O2	Generate fastest possible code.

-Oa	Optimize assuming pointer expressions are not aliased on common subexpression evaluation.

-Oc	Eliminate duplicate expressions within basic blocks.

-Og	Eliminate duplicate expressions within functions.

-Ox	Generate fastest code; Microsoft compatible.

Optimizations|Size

-O	Optimize jumps.

-Ob	Eliminate dead code.

-Oe	Allocate global registers and analyze variable live ranges.

-Ol	Compact loops.

-OW	Suppress the inc bp/dec bp on windows far functions (16-bit compiler only).

-Z	Enable register load suppression optimization.

Optimizations|Speed

-Oi	Expand common intrinsic functions.

-Om	Move invariant code out of loops.

-Op	Propagate copies.

-Ov	Enable loop induction variable and strength reduction.

Messages

-gn	Warnings: stop after "n" messages. (Default: 255.)

-jn	Errors: stop after "n" messages. (Default)

-w	Display warnings on.

-wxxx	Enable "xxx" warning message. (Default)

Messages|Portability

-wcln	Constant is long.

-wcpt	Nonportable pointer comparison. (Default)

-wrng	Constant out of range in comparison. (Default)

-wrpt	Nonportable pointer conversion. (Default)

-wsig	Conversion may lose significant digits

-wucp	Mixing pointers to different 'char' types

Messages|ANSI Violations

-wbbf	Bit fields must be signed or unsigned int.

-wbig	Hexadecimal value contains more than three digits. (Default)

-wdpu	Declare type 'type' prior to use in prototype (Default)

-wdup	Redefinition of 'macro' is not identical (Default)

-wext	'identifier' is declared as both external and static (Default)

-wnak	Non-ANSI Keyword Used: '<keyword>' (Note: Use of this option is a requirement for ANSI conformance.)

-wpin	Initialization is only partially bracketed.

-wret	Both return and return of a value used. (Default)

-wstu	Undefined structure 'structure'

-wsus	Suspicious pointer conversion. (Default)

-wvoi	Void functions may not return a value. (Default)

-wzdi	Division by zero (Default)

Messages|Obsolete C++

-wobi	Base initialization without a class name is now obsolete (Default)

-wofp	Style of function definition is now obsolete (Default)

-wovl	Overload is now unnecessary and obsolete. (Default)

-wpre	Overloaded prefix operator 'operator' used as a postfix operator.

Messages|Potential C++ Errors

-wbei	Initializing 'identifier' with 'identifier'. (Default)

-wdsz	Array size for 'delete' ignored. (Default)

-whchHandler for '<type1>' Hidden by Previous Handler for '<type2>'

-whid	'function1' hides virtual function 'function2' (Default)

-wibc	Base class 'base1' is inaccessible because also in 'base2' (Default)

-wmpc	Conversion to type fails for members of virtual base class base. (Default)

-wmpd	Maximum precision used for member pointer type type. (Default)

-wncf	Non-const function 'function' called for const object. (Default)

-wnci	The constant member 'identifier' is not initialized. (Default)

-wnst	Use qualified name to access nested type 'type' (Default)

-wntd	Use '> >' for nested templates instead of '>>'. (Default)

-wnvf	Non-volatile function function called for volatile object. (Default)

Messages|Inefficient C++ Coding

-winl	Functions containing reserved words are not expanded inline (Default)

-wlin	Temporary used to initialize 'identifier'. (Default)

-wlvc	Temporary used for parameter 'parameter' in call to 'function' (Default)

Messages|Potential Errors

-wamb	Ambiguous operators need parentheses.

-wccc	Condition is always true OR Condition is always false. (Default)

-wdef	Possible use of 'identifier' before definition.

-wnod	No declaration for function 'function'

-wpia	Possibly incorrect assignment. (Default)

-wpro	Call to function with no prototype. (Default)

-wrvl	Function should return a value. (Default)

Messages|Inefficient Coding

-waus	'identifier' is assigned a value that is never used. (Default)

-weff	Code has no effect. (Default)

-wpar	Parameter 'parameter' is never used. (Default)

-wrch	Unreachable code. (Default)

-wstv	Structure passed by value.

-wuse	'identifier' declared but never used.

Messages|General

-Ff=1	Array variable 'identifier' is near. (Default)

-wamp	Superfluous & with function.

-wasm	Unknown assembler instruction.

-will	Ill-formed pragma. (Default)

-wpch	Cannot create precompiled header: header. (Default)

Command-Line Only Options

-B	Compiles assembly and calls TASM or TASM32. If TASM isn't in your path, checking this option generates an error. Also, old versions of TASM might have problems iwth 32-bit code.

-c	Compiles and assembles the named .C, .CPP, and .ASM files, but does not execute a link command.

-efilename	Derives the executable program's name from filename by adding the file extension .EXE (the program name is then filename.EXE). filename must immediately follow the -e, with no intervening whitespace. Without this option, the linker derives the .EXE file's name from the name of the first source or object file in the file name list.

-Efilename	Use "filename" as the name of the assembler to use. By default, TASM is used.

-Fm	Enables all the other -F options (-Fc, -Ff, and -Fs). You can use it as a handy shortcut when porting code from other compilers.

-h	This option offers an alternative method of calculating huge pointer expressions; this method is much faster than the standard method, but must be used with caution. When you use this option, huge pointers are normalized only when a segment wraparound occurs in the offset part. This causes problems with huge arrays if any array elements cross a segment boundary.

-Hc	Cache precompiled headers. Use with -H, -Hxxx, -Hu, or -Hfilename. This option is useful when compiling more than one precompiled header. (32-bit compiler only)

-lx	Pass option "x" to the linker (TLINK for BCC and TLINK32 for BCC32). More than one option can appear after the -l (which is a lowercase L).

-ofilename	Compile source file to "filename".OBJ.

-P	Perform a C++ compile regardless of source file extension. (Default)

-Pext	Perform a C++ compile regardless of source file extension and set the default extension to "ext". This option is available because some programmers use .C or another extension as their default extension for C++ code.

-S	Generate assembler source compiles the named source files and produces assembly language output files (.ASM), but does not assemble. When you use this option, Borland C++ includes the C or C++ source lines as comments in the produced .ASM file.

-T-	Remove all previous assembler options.

-Tstring	Pass "string" as an option to TASM, TASM32, or assembler specified with -E.

-tWM	Make a multithreaded application or DLL.

-Uname	Undefines any previous definitions of the named identifier "name".

-Vo	This option is a "master switch" that sets on all of the backward-compatibility options listed in this section. It can be used as a handy shortcut when linking with libraries built with older versions of Borland C++.

-Vv	This option directs the compiler not to change the layout of any classes (which it needs to do to allow pointers to virtual base class members, which were not supported in previous versions of Borland C++). If this option is used, the compiler will not be able to create a pointer to a member of a base class that can be reached only from the derived class through two or more levels of virtual inheritance (16-bit compiler only).

-W	Creates a Windows GUI application.

-WC	Creates a 32-bit console mode application.

-WCD	Creates a 32-bit console mode DLL with all functions exportable and exported.

-WCDE	Creates a 32-bit console mode DLL with explicit functions exportable and exported.

-WD	Creates a GUI DLL with all functions exportable.

-WDE	Creates a GUI DLL with explicit functions exportable and exported.

-weas	'type' assigned to 'enumeration'. (Default)

-WM	Make a multithreaded application or DLL.

-zX*	Use default name for X. For example, -zA assigns the default class name CODE to the code segment class.


See Also

Command Line Options

Entering Directories for Command-Line Options

File-search Algorithms

Option Precedence Rules

Using Configuration Files

Using the Command-line Compilers

Using Response Files


Entering Directories for Command-Line Options

See Also

Borland C++ can search multiple directories for include and library files. This means that the syntax for the library directories (-L) and include directories (-I) command-line options, like that of the #define option (-D), allows multiple listings of a given option. Here is the syntax for these options:

-Ldirname[;dirname;...]

-Idirname[;dirname;...]

The parameter dirname used with -L and -I can be any directory or directory path. You can enter these multiple directories on the command line in the following ways:

You can stack multiple entries with a single -L or -I option by using a semicolon:

BCC.EXE -Ldirname1;dirname2;dirname3 -Iinc1;inc2;inc3 myfile.c

You can place more than one of each option on the command line, like this:

BCC.EXE -Ldirname1 -Ldirname2 -Ldirname3 -Iinc1 -Iinc2 -Iinc3 myfile.c

You can mix listings:

BCC.EXE -Ldirname1;dirname2 -Ldirname3 -Iinc1;inc2 -Iinc3 myfile.c

If you list multiple -L or -I options on the command line, the result is cumulative: The compiler searches all the directories listed, in order from left to right.

Note:	The IDE also supports multiple library directories.


See Also

Command Line Options

Command-Line Options By Function

File-search Algorithms

Option Precedence Rules

Using Configuration Files

Using the Command-line Compilers

Using Response Files


File-search Algorithms

See Also

#include-file search algorithms

The Borland C++ include-file search algorithms search for the header files listed in your source code in the following way:

If you put an #include <somefile.h> statement in your source code, Borland C++ searches for "somefile.h" only in the specified include directories.

If, on the other hand, you put an #include "somefile.h" statement in your code, Borland C++ searches for "somefile.h" first in the current directory; if it does not find the header file there, it then searches in the include directories specified in the command line.

Library file search algorithms

The library file search algorithms are similar to those for include files:

Implicit libraries: Borland C++ searches for implicit libraries only in the specified library directories; this is similar to the search algorithm for #include <somefile.h>. Implicit library files are the ones Borland C++ automatically links in and the start-up object file (C0x.OBJ).

Explicit libraries: Where Borland C++ searches for explicit (user-specified) libraries depends in part on how you list the library file name. Explicit library files are ones you list on the command line or in a project file; these are file names with a .LIB extension.

If you list an explicit library file name with no drive or directory (like this: mylib.lib), Borland C++ searches for that library in the current directory first. Then (if the first search was unsuccessful), it looks in the specified library directories. This is similar to the search algorithm for #include "somefile.h".

If you list a user-specified library with drive and/or directory information (like this: c:mystuff\mylib1.lib), Borland C++ searches only in the location you explicitly listed as part of the library path name and not in the specified library directories.


See Also

Command Line Options

Command-Line Options By Function

Entering Directories for Command-Line Options

Option Precedence Rules

Using Configuration Files

Using the Command-line Compilers

Using Response Files


Borland C++ Environment Command-Line

The command-line options for the Borland C++ environment (BCW.EXE) include

Option	What it means

/b	Invoke Borland C++ batch build mode

/m	Do a make, not a build

To specify either of these options,

Select the Borland C++ icon in the Program Manager.

Choose File |Run.

Add the command-line option you want to use in the command-line text box and choose OK.

When you use either of these options, your messages are appended to a file. The file is named the same as your project file except it has the extension .MSG.


/b option

The /b option causes Borland C++ to recompile and link all the files in your project and write the compiler messages to the standard output device.

This option allows you to invoke the Borland C++ environment from a batch file so you can automate builds of projects.

Before the build, Borland C++ will load a default project file or one given on the command line.

Borland C++ determines what .EXE to build based on the project file or, if no project file is found, on the file currently loaded in the Edit window.

The command line option is equivalent to the Project|Build (or Project|Make) commands. They build (or make) the ENTIRE project. If the project consists of multiple targets, all targets will be built or brought up to date.

Enter the BCW command with the /b switch. For example,

BCW /b

BCW myproj.ide /b

Unless a project file is loaded, you can specify the name of a program to be compiled and linked on the command line. In that case, type in the program name after the BCW command, followed by /b.

See Also

/m option


/m option

The /m option does a make rather than a build (that is, only outdated source files in your project are recompiled and linked).

Follow the instructions for the /b option, but use /m instead.

See Also

/b option


SpeedBar

The SpeedBar is a row of icons in the Borland C++ IDE that represents menu commands. Clicking one of the icons is a quicker alternative to choosing a command from the menu.

The icons that appear on the SpeedBar depend on your active window. Not all icons are available at all times.

The windows for which there are SpeedBars available include:

Edit Window SpeedBar

Browser SpeedBar

Debugger SpeedBar

Project Window SpeedBar

Message Window SpeedBar

IDE Desktop Speedbar

ClassExpert Speedbar

The default placement of the SpeedBar is horizontally under the menu bar.

To change its appearance:

1.	Choose Options|Environment.

2.	Choose SpeedBar to select your SpeedBar Orientation..

3.	Choose Customize to select your SpeedBar Options.


Debugging in the IDE

See Also

No matter how careful you are when you code, your program is likely to have errors (bugs) that prevent it from running the way you intended. Debugging is the process of locating and fixing program errors that prevent your program from operating correctly. Borland C++ provides debugging features, collectively referred to as the integrated debugger, that let you debug your program from within the IDE.

Types Of Errors

There are three basic types of program errors:

Compile-time

Run-time

Logic

Using the Integrated Debugger

All execution in the integrated debugger is based on lines of source code. You run your program one line at a time; the next line will not execute until you tell the debugger to continue.

There are many ways to use the integrated debugger, but you will generally use the following process:

1.	Fix any syntax errors. See Fixing Syntax Errors.

2.	Compile your program with debugging information generated in the .OBJ and .EXE files. See Generating Debugging Information.

3.	Step, trace, or run your program until you reach the spot in your code where a problem occurs. See Stepping Over Code, Tracing Into Code. and Setting Breakpoints.

4.	Examine the state of the program and its data, and view the program output and the values of its variables. See Watching, Examining Register Values, and Inspecting Data Elements.

5.	Evaluate and modify expressions and variables in your program to help isolate the problem. See Evaluating Expressions and Modifying Variables.

6.	Tell the debugger to execute the next line.

Each time you tell the debugger to step or trace, the execution point moves to the next line.

Note:	If you are debugging a program that requires as much memory as possible to compile, choose Debug|Program Terminate at the end of a debugging session.


See Also

Changing the Color of the Execution point

Choosing which Warnings Display in the Message Window

Browsing Through Your Code

Debugging Dynamic-Link Libraries

Debugging in Soft and Hard Mode

Debugging With Program Arguments

Examining Values

General Protection Exception

Generating Debugging Information

Logging Events

Preferences settings

Stopping a Program

Viewing Program Output


Examining Values

See Also

Stepping and tracing through your code can help you find problems in program flow, but you will usually want to watch what happens to the values of variables while you step. For example, as you step through a for loop, it is helpful to know the value of the index variable.

The IDE provides the following tools to help you examine the contents of your program variables:

The Watch window lets you track the value of a variable or expression.

The Expression Evaluator dialog box lets you evaluate any expression meaningful to the program you are debugging, and lets you change the value of a variable while you are debugging your program.

The Inspector window lets you examine and modify the value in a data element.


See Also

Debugging in the IDE

Evaluating Expressions

Examining Register Values

Inspecting Data Elements

Modifying Variables

Setting Breakpoints

Stepping Over Code

Tracing Into Code

Watching


Fixing Syntax Errors

See Also

If your code has compile-time (syntax) errors and you try to compile it, the Message window opens and displays the errors and warnings generated.

To correct a problem in your code,

1.	In the message window, double-click on the error or warning that you want to fix.

The IDE positions your cursor on the line in your source code that caused the problem.

2.	Make your correction.

3.	If your code has more than one problem, double-click on another error or warning in the Message window and continue correcting errors until you have fixed them all.

4.	Choose Project|Make All to compile your program.

5.	Choose Debug|Run to verify that your program is operating correctly.


See Also

Choosing which Warnings Display in the Message Window

Debugging in the IDE


Choosing which Warnings Display in the Message Window

See Also

To choose which type of warnings you want to see in the Message window,

1.	Choose Options|Project and select Messages.

The IDE displays all the various categories of messages and, on the right, settings that affect all messages.

2.	Choose one of the following options:

Check Selected and the IDE displays only the selected warning messages. (You will select the messages in Step 4.)

Check All and the IDE displays all warning messages, not just the ones you selected.

Check None and the IDE displays no warnings.

3.	Limit the number of error and warning messages displayed in the Message window.

In the Stop After boxes, specify the maximum number of error messages and warning messages you want displayed each time you compile. The number can be 0 to 255.

If you enter 0, the IDE will not limit the number of messages or warnings it displays in the Message window.

4.	Select a category under messages and then choose the available types of errors or warnings you want.

For example, if you want the compiler to warn you about suspicious pointer conversions that might violate the ANSI standard, select ANSI Violations and then check the Suspicious Pointer Conversion option.


See Also

Debugging in the IDE

Fixing Syntax Errors

Generating Debugging Information


Generating Debugging Information

See Also

To debug run-time errors and logic errors in your program, you must first compile and link your program so that debugging information is generated in your .OBJ and .EXE files. (Before you can compile your program, you must first fix all compile-time errors.)

To add debugging information to your .OBJ files,

1.	Choose Options|Project to open the Option Settings dialog box.

2.	Expand Compiler and select Debugging.

3.	Choose Debug Information in OBJs. This is the default setting.

To include debugging information in your .EXE files,

1.	Choose Options|Project to open the Option Settings dialog box.

2.	Expand Linker and select General.

3.	Choose Include debug information. This is the default setting.

Now when you compile the program, the compiler generates a symbol table so that debugging can take place.

Turn Off Debugging Information

When you have fully debugged your program, compile it with debugging information turned off to reduce the size of your program files.


See Also

Choosing which Warnings Display in the Message Window

Disable all optimizations

Jump Optimization

Options|Debugging

Preferences settings


Debugging With Program Arguments

See Also

To debug a program that requires arguments,

1.	Choose Options|Environment|Debugger.

2.	In the Run Arguments box, enter the arguments you want passed to the program.


See Also

Debugging in the IDE


Stepping Over Code

See Also	Overview of Stepping and Tracing

Stepping is the simplest way to move through your code a little bit at a time. Stepping lets you run your program one line at a time; the next line will not execute until you tell the debugger to continue. You can step until you reach the line in your code that contains the error and then examine the state of the program and its data, view the program output and the value of its variables, or modify or evaluate expressions in your program before you tell the debugger to execute the next line.

To step over your code,

Choose Debug|Step over or press F8.

The IDE executes the code highlighted by the execution point including any functions it might call before returning control to you. The execution point then indicates the next complete line.

Example

The following example helps explain how stepping over works. Suppose that these are the first lines of a program loaded into an Edit window:

BOOL InitApplication ( HINSTANCE hInstance )

{

  WNDCLASS  wc;

  wc.style       = CS_HREDRAW | CS_VREDRAW;

  wc.lpfnWndProc = (long (FAR PASCAL*)())MainWndProc;

  wc.cbClsExtra  = 0;

  wc.cbWndExtra  = 0;

   ...

  return ( RegisterClass ( &wc ) );

}

  ...

int PASCAL WinMain ( HINSTANCE hInstance, HINSTANCE hPrevInstance,

LPSTR lpCmdLine, int nCmdShow )

{

  MSG msg;

  if ( !hPrevInstance )

  if ( !InitApplication ( hInstance ) )

    return ( FALSE );

  if ( !InitInstance ( hInstance, nCmdShow ) )

    return ( FALSE );

  ...

}

In this example, InitApplication is a function defined in a module that has been compiled with debugging information. Each time you choose Debug|Step Over (or press F8), the debugger executes the line highlighted by the execution point and then advances the execution point to the next line.

If you choose Step Over when the execution point reaches the statement

if ( !InitApplication ( hInstance ) )

the debugger executes the InitApplication function and returns a Boolean value, but you do not see the execution point move through the actual InitApplication function. Instead, the debugger steps over the function and returns control to you when the function finishes.

As you debug, you can choose to trace into some functions and step over others, depending upon your needs.


See Also

Debugging Class Member Functions

Debugging External Code

Debugging in the IDE

Locating a Function

Returning to the Execution point

Returning to Where a Function was Called

Running to the Cursor

Starting Over

Stopping a Program

Tracing Into Code

Viewing Program Output


Tracing into Code

See Also	Overview of Stepping and Tracing

Tracing into code is very much like stepping over code, except that when you come to a line that calls a function, tracing into the code moves the execution point into the code in the function.

If the executing statement

contains a call to a function accessible to the debugger, Trace Into stops at the beginning of the function definition.

does not contain a call to a function accessible to the debugger, Trace Into stops at the next executable statement.

To trace into your code,

Choose Debug|Trace Into or press F7.

If the executing statement calls a function, the Trace Into command moves the execution point into the function. Subsequent Trace Into or Step Over commands run the statements in the function definition.

When the debugger leaves the function, it resumes evaluating the statement that contains the call and the execution point indicates the next executable statement in your program.

Example

The following example helps explain how tracing into works. Suppose that these are the first lines of a program loaded into an Edit window:

BOOL InitApplication ( HINSTANCE hInstance )

{

  WNDCLASS  wc;

  wc.style       = CS_HREDRAW | CS_VREDRAW;

  wc.lpfnWndProc = (long (FAR PASCAL*)())MainWndProc;

  wc.cbClsExtra  = 0;

  wc.cbWndExtra  = 0;

   ...

  return ( RegisterClass ( &wc ) );

}

  ...

int PASCAL WinMain ( HINSTANCE hInstance, HINSTANCE hPrevInstance,

LPSTR lpCmdLine, int nCmdShow )

{

  MSG msg;

  if ( !hPrevInstance )

  if ( !InitApplication ( hInstance ) )

    return ( FALSE );

  if ( !InitInstance ( hInstance, nCmdShow ) )

    return ( FALSE );

  ...

}

In this example, InitApplication is a function defined in a module that has been compiled with debugging information. If you choose Debug|Trace Into (or press F7) to execute each statement, when the debugger reaches the statement that evaluates the return value of InitApplication, the execution point jumps to the code that implements the InitApplication function .

As you debug, you can choose to trace into some functions and step over others, depending upon your needs.


Stepping and Tracing

A line of code is the smallest unit of execution in the debugger. To control the rate of debugging to the level of a single line of source code, place each statement on a single line:

If you string several statements together on one line, you cannot debug those statements individually.

If you spread out a single statement over multiple lines for debugging purposes, it still executes as a single step.

There are two ways to execute your code one line at a time:

Step over	If the debugger encounters a function call, the function executes as if it were a single line of code.

Trace into	If the debugger encounters a function call, the execution point moves into the code of the function and the debugger executes each line of code that implements the function, one line at a time.


See Also

Debugging in the IDE

Debugging Class Member Functions

Debugging External Code

Locating a Function

Returning to the Execution point

Returning to Where a Function was Called

Running to the Cursor

Starting Over

Stepping Over Code

Stopping a Program

Viewing Program Output


Debugging Class Member Functions

If you use classes in your programs, you can still use the integrated debugger to step over or trace into code. The debugger handles member functions the same way it would step or trace functions in a program that is not object-oriented.


Debugging External Code

If you link external code into your program, you can step over or trace into that code if the .OBJ file you link in contains debugging information.

You can debug external code written in any language, including C, C++, Pascal, and assembly language. As long as the code meets all the requirements for external linking and contains full Borland symbolic debugging information, the integrated debugger can step or trace through it.


Viewing Program Output

As you step over or trace into your program, you can view your program output in its application window. Arrange your windows so that you can see both your source code and your application window as you step and trace.

Note:	If the IDE desktop window and your application window overlap as you debug, you will see some flickering in your application window. If you arrange these windows so they do not overlap, program execution will be quicker and display better.

You can also use Alt+TAB to view your program (as long as your program is not running in Hard Mode). If your program is stopped, however, you can view it but you cannot not make changes to it. You can then use Alt+TAB again to switch back to the IDE.


Running to the Cursor

You can tell the debugger you want to execute your program normally (not step-by-step) until a certain spot in your code is reached:

1.	In an Edit window, position the cursor on the line where you want to resume debugging control.

2.	Choose Run to Cursor on the Edit window SpeedMenu.

You can use Run to Cursor as a way to restart your debugging session or after you have already been stepping over or tracing into your code.


Locating a Function

See Also

To quickly locate a function in your program,

1.	Choose Search|Locate function.

2.	Select an expression from the history list or type one in.

3.	Press OK.

The IDE positions the cursor on the line in the file where the function is defined.

Note:	This command is available only after you have complied your program with debug information included.


See Also

Browsing Through Your Code

Generating Debugging Information

View Globals command


Returning to the Execution point

While you are debugging, you can

browse through any file in any Edit window

go to any place in your file

open and close files

To quickly return to the location of the execution point from anywhere in the IDE, choose

Debug|Find Execution point or use [image] on the SpeedBar.

The debugger positions the cursor at the execution point (or CS:IP). If you closed the Edit window containing the execution point, the IDE opens a new Edit window displaying the source code at the execution point.


Returning to Where a Function was Called

See Also

Use the Call Stack window to see the sequence of function calls that brought your program to its current state and the arguments passed to each function.

To view the Call Stack

Choose View|Call Stack.

To view or edit the source code of a function in the Call Stack,

Double-click a call in the Call Stack window.

or

Select a function and choose Inspect Source or Edit Source from the Call Stack SpeedMenu.

Stepping Over a Function that you Traced into Accidentally

The Call Stack is particularly useful if you accidentally trace into code you want to step over. Use it to step back and then resume stepping or tracing where you originally intended:

1.	Double-click the call that called the function you traced into by mistake. It will be the second call from the top in the Call Stack.

 	The Call Stack window disappears and the Edit window becomes the active window with your cursor positioned at the location of the call.

2.	Move the cursor in the Edit window to a position completely past the call.

3.	Choose Run to Cursor on the Edit window SpeedMenu.


See Also

Starting Over


Starting Over

See Also

Occasionally while debugging, you might want to start over from the beginning.

To restart your program

Choose Debug|Terminate Program.

The IDE

resets the integrated debugger so that running, stepping, or tracing begin at the start of the main program.

does not change the location of the source code displayed in the Edit window so that you can easily position the cursor to run your program to the line you were on when you reset it.

Usage

The Debug|Terminate Program command is useful if

You have executed past the place where you think there is a bug.

You suspended your application with the program interrupt key and you want to restart it from the beginning.

Note:	Do not interrupt the execution of your program within Windows kernel code.


See Also

Returning to Where a Function was Called

Stopping a Program


Stopping a Program

See Also

Instead of stepping over or tracing through code, you can use a simpler technique to pause your program:

Choose Debug|Pause Program and your program will stop executing.

You can then examine the value of variables and inspect data at this state of the program. When you are done, choose Debug|Run to continue the execution of your program.

Note:	If for some reason your program assumes control and wil not allow you to return to the debugger (if it is in an infinite loop, for example), to stop your program, press:

 	Ctrl+Alt+Sys Req

General Protection Exception

If a general protection exception (GP exception) occurs while you run your program in the IDE, see General Protection Exception.


See Also

Debugging in the IDE


Watching

See Also

If you want to monitor the value of a variable or expression while you debug your code, add a watch to the Watch window. The Watch window displays the current value of the watch expression based on the scope of the execution point.

To view watches in your program,

Choose View|Watch to display the Watch window.

If you have not added any watches yet, the Watch window is blank.

Note:	If the execution point steps out of the scope of a watch expression, the watch expression is undefined. When the execution point re-enters the scope of the expresion, the Watch window again displays the current value of the expression.


See Also

Adding a Watch

Deleting a Watch

Disabling Watches

Changing Watch Properties

Evaluating Expressions

Modifying Variables

Browsing Through Your Code

Browsing Symbols in Your Code

Browsing Global Symbols

Browsing Objects


Adding a Watch

Sea Also

You can add a watch the following ways.

In an Edit window,

Choose Set Watch on the Edit window SpeedMenu.

 	The IDE adds a watch on the word at the cursor.

or

Choose Debug|Add Watch to open the Watch Properties dialog box.

On the Watch window,

1.	Choose View|Watch to open the Watch window.

2.	Choose Add Watch on the Watch window SpeedMenu to open the Watch Properties dialog box.

On the Watch Properties dialog box,

1.	Select an expression from the history list or type one in the Expression input box.

2.	If you want to change the display format of the result, select one of the Radix and Display as options. See Radix and Display As.


See Also

Deleting a Watch

Disabling Watches

Watching Data Elements


Disabling Watches
Disabling and Enabling Watches

Evaluating many watch expressions can slow down the process of debugging. Disable a watch expression when you prefer not to view it in the Watch window, but want to save it for later use.

To disable a watch,

1.	Choose View|Watch to open the Watch window.

2.	Clear the checkbox next to the watch.

To enable a watch,

To enable a watch, click the checkbox next to it.

To disable selected watches,

1.	Hold down the Shift or Ctrl key and click on one or more watches in the Watch window.

2.	Choose Disable Selected watches on the Watch window SpeedMenu.

To enable selected watches,

1.	Hold down the Shift or Ctrl key and click on one or more watches in the Watch window.

2.	Choose Disable Selected watches from the Watch window SpeedMenu.

To disable all watches,

Choose Disable All Watches on the Watch window SpeedMenu.

To enable all watches,

Choose Enable All Watches on the Watch window SpeedMenu.


Deleting a Watch

You can delete a watch the following ways:

1.	Choose View|Watch to display the Watch window.

2.	Select a watch.

3.	Choose Remove Watch on the SpeedMenu.

To delete all watches,

1.	Choose View|Watch to display the Watch window.

2.	Choose Remove All Watches on the SpeedMenu.


Changing Watch Properties

See Also

To change the properties of a watch

1.	Choose View|Watch.

2.	Double-click a watch in the Watch window.

3.	Enter the new information on the Watch Properties dialog box.

4.	Choose OK. Changes take effect immediately.


See Also

Adding a Watch


Evaluating Expressions

See Also

In addition to watching variables as your program executes, you can

evaluate a watch expression at any time

modify the values of a variable at run time

To evaluate an expression,

1.	Choose Debug|Evaluate/Modify.

 	The Expression Evaluator dialog box displays.

2.	Select an expression from the history list or type one in.

3.	Choose Evaluate.

The Result box shows the current value of the expression in the Expression box.

You can evaluate any valid C or C++ expressions except those that contain

symbols or macros defined with #define

local or static variables not in the scope of the function being executed

function calls (or expressions that contain function calls)

Display Format

To change the display format of an expression, see Expression Evaluator Format Specifiers.


See Also

Modifying Variables

Browsing Through Your Code

Browsing Symbols in Your Code

Browsing Global Symbols

Browsing Objects


Expression Evaluator Format Specifiers

See Also

By default, the debugger displays the result in the format that matches the data type of the expression. Integer values, for example, normally display in decimal form. To change the display format, type a comma (,) followed by a format specifier after the expression.

Example

Suppose the Expression box contains the integer value z and you want to display the result in hexadecimal:

1.	In the Expression box, type z,h

2.	Choose Evaluate.

Format Specifiers

The following table describes the Expression Evaluator format specifiers.

Specifier	Types affected	Description

,C	Characters and strings	Character. Shows special display characters for ASCII 0 to 31. By default, such characters are shown using the appropriate C escape sequences (\n, \t, and so on).

,S	Char, strings	String. Shows ASCII 0 to 31 as C escape sequences. Use only to modify memory dumps.

,D	Integers	Decimal. Shows integer values in decimal form, including those in data structures.

,H or ,X	Integers	Hexadecimal. Shows integer values in hexadecimal with the 0x prefix, including those in data structures.

,Fn	Floating point	Floating point. Shows n significant digits where n can be from 2 -18. For example, to display the first four digits of a floating point value, type

,F4

If n is not specified, the default is 7.

,P	Pointers	Pointer. Shows pointers in segment:offset notation with additional information about the address pointed to. It tells you the region of memory in which the segment is located and, if applicable, the name of the variable at the offset address.

,R	Structures and unions	Structure/Union. Shows field names and unions as well as values such as X:1;Y:10;Z:5.

,nM	All	Memory dump. Shows n bytes starting at the address of the indicated expression. For example, to display the first four bytes starting at the memory address, type

,4M

If n is not specified, it defaults to the size in bytes of the type of the variable. By default, each byte displays as two hex digits. Use memory dump with the C, D, H, and S format specifiers to change the byte formatting.


See Also

Modifying Variables


Modifying Variables

While debugging, you can change the value of a variable in your program by using the Expression Evaluator dialog box.

To change the value of a variable,

1.	Choose Debug|Evaluate/Modify.

 	The Expression Evaluator dialog box displays.

2.	Select an expression from the history list or type one in.

3.	Choose Evaluate.

 	The result box displays the current value of the expression.

4.	Enter a value in the New Value input box.

If you do not want to modify the variable, choose Close. You cannot undo a change to a variable after you choose Modify. To restore a value, however, you can enter the previous value in the New Value input box and modify the expression again.

5.	To change the value of the variable, choose Modify.

 	The new value takes effect immediately.

6.	When you are finished, choose Close.

Usage

When you change the values of variables,

You can change individual variables or elements of arrays or structures, but not arrays or structures themselves.

The expression in the New Value box must evaluate to a result that is assignment-compatible with the variable you want to assign it to. A good rule of thumb is if the assignment would cause a compile-time or run-time error, it is not a legal modification value.

You cannot directly modify untyped arguments passed into a function, but you can typecast them and then assign new values.

Warning:	Modifying values, especially pointer values and array indexes, can have undesirable effects because you might overwrite other variables and data structures that are not immediately apparent.


Inspecting Data Elements

See Also

You can examine the values in a data element the following ways:

To display an Inspector window directly from the Edit window,

1.	Position your cursor on the data element you want to inspect.

2.	Choose Inspect Object on the Edit window SpeedMenu.

To inspect a data element from the menu bar,

1.	Choose Debug|Inspect to display the Inspect Expression dialog box.

2.	Type in the expression you want to inspect.

Scope

Unlike a watch expresion, the scope of a data element is fixed at the time you open it in the Inspector window and never changes:

If you use the SpeedMenu command, the data element is always evaluated within the scope of the line on which the data element appears.

If you use the menu bar command, the data element is evaluated within the scope of the execution point.

 	If the execution point is in the scope of the expression you are inspecting, the value appears in the Data Inspector window. If the execution point is outside the scope of the expression, the value is undefined.

Data Types

The number of panes and the appearance of the data in the Inspector window depends on which of the following types of data you inspect:

arrays

classes

constants

functions

objects

pointers

scalar variables (int, float, and so on)

structures and unions

For example, if you inspect an array, you will see a line for each member of the array with the array index of the member. The value of the member follows in its display format, followed by the value in hexadecimal.


See Also

Changing the Value of Inspector Items

Isolating the View in an Inspector Window

Selecting a Range of Data Items

Browsing Through Your Code

Browsing Symbols in Your Code

Browsing Global Symbols

Browsing Objects


Isolating the View in an Inspector Window

You can more closely inspect certain elements (such as classes, structures, and arrays) in the Inspector window to isolate the view to the member level:

1.	Select an item in the Inspector window.

2.	Choose Inspect Object on the Inspector window SpeedMenu.

The scope of the data element remains the same as it was when opened on the Inspector window.

To view the source code that references the element you are inspecting,

Choose View Source from the Inspector window SpeedMenu.


Changing the Value of Inspector Items

To change a single data inspector item,

1.	Select an item in the Inspector window.

2.	Choose Change on the Inspector window SpeedMenu.

3.	Type in a new value and choose OK.


Selecting a Range of Data Items

If you are inspecting a data structure, it is possible the number ofitems displayed might be so great that you will have to scroll in the Inspector window to see data you want. For easier viewing, narrow the display to a range of data items.

1.	Select an item in the Inspector window.

2.	Choose Range on the Inspector window SpeedMenu.

3.	Type in the new range of values and choose OK.


Inspect Error

See Also

The symbol you are trying to inspect is not recognized by the debugger. For example, it may be an invalid symbol or out of scope.


See Also

Inspecting Data Elements


Examining Register Values

While debugging, you can use the Registers window to display the values in the data, pointer, index, segment, and instruction pointer registers, as well as the settings of the status word or flags.

To display the Registers window,

Choose View|Register.

To change the display format of register values,

Choose one of the following options on the Registers window SpeedMenu:

hexadecimal

decimal

word (2-byte hexadecimal numbers)

double word (4-byte hexadecimal numbers)


Setting Breakpoints

See Also

Using a breakpoint is similar to using the Run to Cursor command in that the program runs at full speed until it reaches a certain point. But unlike Run to Cursor, you can have multiple breakpoints and you can choose to stop at a breakpoint only under certain conditions.

The IDE keeps track of all your breakpoints during a debugging session and associates them with your current project. You can maintain all your breakpoints from a single window and not have to search through your source code files to look for them.

Debugging With Breakpoints

When you run your program from the IDE, it will stop whenever the debugger reaches the line highlighted as a breakpoint, but before it executes the line. The line containing the breakpoint appears in the Edit window highlighted by the execution point. At this point, you can perform any other debugging actions.

Setting Breakpoints After Program Execution Begins

While your program is running, you can switch to the debugger (just like you switch to any Windows application) and set a breakpoint. When you return to your application, the new breakpoint is set, and your application will halt when it reaches the breakpoint.

Using Conditional Breakpoints

Sometimes, you will not want a breakpoint to activate every time it is encountered, especially if the line containing the breakpoint is executed many times before the actual occurrence you are interested in. Likewise, you may not always want a breakpoint to pause program execution. In these cases, use a conditional breakpoint.


See Also

Adding Breakpoints

Changing the Color of Breakpoint Lines

Changing the Color of the Execution point

Creating Conditional Breakpoints

Debugging in Soft and Hard Mode

Disabling and Enabling Breakpoints

Inspecting and Editing Code at a Breakpoint

Modifying Breakpoint Properties

Removing Breakpoints

Resetting Invalid Breakpoints


Adding Breakpoints

See Also

You can add a breakpoint the following ways:

To set an unconditional breakpoint,

Place the cursor on the line where you want to set the breakpoint and then take one of the following actions:

Press F5.

Choose Toggle Breakpoint on the Edit window SpeedMenu.

Choose Debug|Toggle Breakpoint.

To set a conditional breakpoint

Place the cursor on the line where you want to set the breakpoint and then choose Debug|Add Breakpoint. See Creating Conditional Breakpoints.

To view the breakpoints set in your code

Choose View|Breakpoint to display the Breakpoints window.


See Also

Creating Conditional Breakpoints

Setting Breakpoints


Creating Conditional Breakpoints

See Also

Use a conditional breakpoint when you want the debugger to activate a breakpoint only under certain conditions. A conditional breakpoint differs from an unconditional breakpoint in that the debugger does not activate the breakpoint every time it reaches the line of code on which the breakpoint is set, but only when a specified condition is met.

To create a conditional breakpoint,

1.	Choose Debug|Add Breakpoint, or choose Add Breakpoint on the Breakpoints window SpeedMenu.

2	In the Breakpoint Properties dialog box, enter a file name and line number to tell the debugger where you want to set the breakpoint.

If you choose the Debug|Add Breakpoint command from an active Edit window, the Breakpoint Properties window displays with the line number at the insertion point and the name of the file that was loaded in the Edit window. You can keep these settings or type in new information.

3.	Check Enable Conditional Breakpoint. If Enable Conditional Breakpoint is unchecked, the debugger activates the breakpoint every time it reaches the breakpoint line (and satisfies the Pass Count, if specified) and ignores anything in the Conditional Expression input box.

4.	Enter a conditional expression that tells the debugger when to trigger the breakpoint. If the condition is not met, the debugger ignores the breakpoint along with any of its actions. See Conditional Expression.

5	Enter the number of passes you want to take place before the debugger activates the breakpoint. See Pass count.

6.	Check Break (the default) if you want your program to stop each time the debugger activates the breakpoint. If Break is unchecked, your program will not stop when the debugger activates the breakpoint.

7	If you want the debugger to write a message to the Event Log when the breakpoint is activated, check Log Expression. If Log Expression is unchecked, a message is not written and the debugger ignores any information in the Expression To Log input box.

8.	If you want to record the value of a variable or expression at the time the breakpoint is activated, enter it in the Expression To Log input box. You must also check Log Expression. See Actions.

To view breakpoints set in your code

Choose View|Breakpoint to display the Breakpoints window.


See Also

Debugging in the IDE

Debugging in Soft and Hard Mode

Debugging Dynamic-link Libraries

Logging Events


Changing Breakpoint Properties
Modifying Breakpoint Properties

See Also

To change the properties of a breakpoint

1.	Choose View|Breakpoint.

2.	Double-click on a breakpoint in the Breakpoints window or choose Edit Breakpoint on the Breakpoint windows SpeedMenu.

3.	Type in the new information. See Creating Conditional Breakpoints.

4.	Choose OK. Changes take effect immediately.


See Also

Setting Breakpoints


Removing Breakpoints

See Also

You can remove a breakpoint the following ways:

1.	In an Edit window, place the cursor on the line containing the breakpoint.

2	Choose Toggle Breakpoint from the Debug menu or the Edit window SpeedMenu (or press F5).

or

1.	Choose View|Breakpoint to display the Breakpoints window.

2.	Select a breakpoint.

3.	Choose Remove Breakpoint on the Breakpoints window SpeedMenu.

To remove all breakpoints,

Choose Remove All Breakpoints on the Breakpoints window SpeedMenu.


See Also

Disabling and Enabling Breakpoints

Resetting Invalid Breakpoints


Disabling and Enabling Breakpoints

See Also

Disable a breakpoint when you prefer not to activate it the next time you run your program, but want to save it for later use. The breakpoint remains listed in the Breakpoints window available for you to enable when you want.

To disable a breakpoint

1.	Choose View|Breakpoint to open the Breakpoints window.

2.	Clear the checkbox next to the breakpoint.

To enable a breakpoint

To enable a breakpoint, click the checkbox again.

To disable selected breakpoints

1.	In the Breakpoints window, click and drag over a block of breakpoints or hold down Shift or Ctrl as you select multiple breakpoints.

2.	Choose Disable Selected breakpoints on the SpeedMenu.

To enable selected breakpoints

1.	In the Breakpoints window, click and drag over a block of breakpoints or hold down Shift or Ctrl while you click to select multiple breakpoints.

2.	Choose Disable Selected breakpoints from the Breakpoints window SpeedMenu.

To disable all breakpoints

Choose Disable All Breakpoints on the Breakpoints window SpeedMenu.

To enable all breakpoints

Choose Enable All Breakpoints on the Breakpoints window SpeedMenu.


See Also

Removing Breakpoints

Resetting Invalid Breakpoints


Inspecting and Editing Code at a Breakpoint

Even if a breakpoint is not in your current Edit window, you can quickly locate it in your source code.

To view the code where a breakpoint is set,

1.	Choose Vew|Breakpoint to display the Breakpoints window.

2.	Select a breakpoint.

3.	Choose Inspect Source on the Breakpoints window SpeedMenu.

The source code displays in an Edit window at the breakpoint line and the Breakpoints window remains active. If the source code is not currently open in an Edit window, the IDE opens a new Edit window.

To edit the code where a breakpoint is set,

1.	Choose Vew|Breakpoint to display the Breakpoints window.

2.	Select a breakpoint.

3.	Choose Edit Source on Breakpoints window SpeedMenu.

The source code displays in an active Edit window with your cursor positioned on the breakpoint line, ready for you to edit. If the source code is not currently open in an Edit window, the IDE opens a new Edit window.


Resetting Invalid Breakpoints

See Also

A breakpoint must be set on executable code, otherwise it is invalid. For example, a breakpoint set on a comment, a blank line, or a declaration is invalid. A common error is to set a breakpoint on code that is conditionalized out.

If you set an invalid breakpoint and run your program, the debugger displays an Invalid Breakpoint dialog box.

To reset an invalid breakpoint,

1.	Close the Invalid Breakpoint dialog box.

2.	Open the Breakpoints window.

3.	Find the invalid breakpoint and delete it.

4.	Set the breakpoint in a proper location and continue to run your program.

Note:	If you ignore the Invalid Breakpoint (by dismissing the dialog box) and then choose Run, the IDE executes your program and disables the invalid breakpoint.


See Also

Disabling and Enabling Breakpoints

Removing Breakpoints


Changing the Color of Breakpoint Lines

See Also

To use colors to indicate if a breakpoint is enabled, disabled, or invalid,

1.	Choose Options|Environment.

2.	Select Syntax Highlighting and choose Customize.

3.	From the Element list, select the following breakpoint options you want to change:

Enabled Break

Disabled Break

Invalid Break

4.	Select the background (BG) and foreground (FG) colors you want.


Changing the Color of the Execution point

See Also

To change the color of the execution point,

1.	Choose Options|Environment.

2.	Select Syntax Highlighting and choose Customize.

3.	From the Element list, select Execution point.

4.	Select the background (BG) and foreground (FG) colors you want.


See Also

Debugging in the IDE


Logging Events

See Also

In addition to recording a breakpoint, you can also use the Event Log to track the following events:

Windows messages

output messages

To select which events you want to log

1.	Choose Options|Environment and select Debugger.

 	or

2.	Choose View|Event Log to display the Event Log and then choose Set options from the SpeedMenu.

3.	Under Capture Events, choose the options you want to track.


See Also

Adding a Comment to the Event Log

Clearing the Contents of the Event Log

Event Capture option settings

Saving the Contents of the Event Log to Disk


Adding a Comment to the Event Log

To add a comment to the Event Log entry,

1.	Choose View|Event Log to display the Event log.

2.	Choose Comment on the Event Log SpeedMenu.

3.	Enter a line of text at the prompt.

The IDE inserts the text next to the current entry in the Event Log.


Clearing the Contents of the Event Log

If you want to start writing events to a file without including the lines already in the Event Log window,

1.	Choose View|Event Log to display the Event log.

2.	Choose Clear All on the Event log SpeedMenu to erase the events currently displayed in the Event Log .


Saving the Contents of the Event Log to Disk

See Also

To write the contents of the Event Log to a file you can examine later,

1.	Choose View|Event Log to display the Event log.

2.	Choose Save Events To File from the Event log SpeedMenu.

3.	Supply a file name in the Write Event Log To Log File dialog box.


See Also

Logging Events


Event Log : Add Comment to Log Dialog Box
Event Log : Add Comment to Log

Enter a comment you want to add to the Event Log. Comments that display in the Event Log are enclosed in angle brackets (> <).


Debugging Dynamic-link Libraries

See Also

When you step over or trace into a DLL used by your program, the debugger automatically loads the symbol table belonging to the DLL.

Because only one symbol table can be loaded into memory at a time, when you load a DLL symbol into memory, your .EXE symbol table is unloaded. While you debug a DLL, you can watch variables, inspect data, and so on in the DLL, but not in the source code of the .EXE.

To see which symbol table the debugger is using,

Choose Debug|Load Symbol Table.

The IDE displays the current symbol table and lists others that are available to your program. For example, if your .EXE is named MYAPP.EXE that uses MYDLL.DLL, as you step through the DLL, MYDLL.DLL is the current symbol table and MYAPP.EXE is listed as available.

To switch between symbol tables,

1.	Choose Debug|Load Symbol Table.

2.	Choose the symbol table you want to load from the Available list.

For example, if you are stepping in MYDLL.DLL and want to examine the value of a variable that is in MYAPP.EXE, you can do so by loading the MYAPP.EXE symbol table.

After you have examined the variable and want to resume stepping, you must switch back to the other symbol table.


See Also

Debugging in the IDE

Stepping Over Code

Tracing Into Code


General Protection Exception

If a general protection exception (GP exception) occurs while running your program in the IDE, your program halts and a General Protection Exception dialog box appears. If you choose OK to close the dialog box, the debugger displays the code that is responsible for the GP exception in the Edit window. The execution point marks the offending code.

When this situation occurs, to prevent your program from crashing you must:

1.	Choose Debug|Terminate Program.

2.	Correct the error that caused the problem before you run your program again.

Although the debugger can catch most GP exceptions, it might fail to catch all of them, depending on the cause of the exception.


Debugging in Soft and Hard Mode

See Also

Windows is continually processing and generating messages and any executing Windows program, such as Borland C++ , must do the same. When you run your own Windows programs, they also send messages and process messages they receive.

When you set a breakpoint in your code, however, you want your program to stop executing (or to activate the breakpoint) when the debugger reaches the breakpoint line. But in the Windows environment, doing such things as resizing a window, opening a dialog box, moving the mouse cursor, or opening a menu will generate Windows messages that are sent to your executing program. Unless the debugger handles these messages for you, the messages could force your program to execute or possibly lock up your system.

Fortunately, the integrated debugger handles these situations in the majority of cases, and you can debug your program while using the full functionality of the Windows environment. For this reason the debugger runs in one of two modes: hard or soft.

Running in hard mode only

Occasionally, you might need to stop all other Windows programs and ensure that the debugger always runs in hard mode.

1.	Choose Options|Environment and select Debugger.

2.	Under Windows Debugging Mode, select Hard Mode On All Stops.

Using the Smart option

When the Smart option is selected, the debugger chooses hard or soft mode, depending on what events are occurring on the system.

1.	Choose Options|Environment and select Debugger.

2.	Under Windows Debugging Mode, select Smart. This is the default setting and the one you will want to use most often.


See Also

Debugging in the IDE


Breakpoint

A place in your code where you want the program to pause or perform an action so that you can examine the current values of program variables and data structures. There are two types of breakpoints:

Unconditional. The breakpoint is activated whenever the debugger reaches the line containing the breakpoint.

Conditional. The breakpoint is activated only under certain conditions.

A breakpoint must be set on a line that contains executable code. For example, you cannot set a breakpoint on a blank line, comment, or declaration.


Compile-Time Error

An error that violates a rule of C or C++ syntax. Borland C++  cannot compile your program unless it contains valid C or C++ statements.

The most common causes of compile-time (syntax) errors are

typographical mistakes

omitted semicolons

references to undeclared variables

wrong number or type of arguments passed to a function

wrong type of values assigned to a variable


CS:IP

Code segment instruction pointer. In a debugging session, the instruction in the instruction pointer register (IP) of the code segment (CS) is the next one to be executed. It is also the location of the execution point in the Edit window.


Execution point

The highlighted line that marks your place in the program you are debugging. The line highlighted by the execution point is the next line to be executed.


Expression

Part of a statement that consists of constants, variables, and data structures combined with operators.

As you debug your code, watching, evaluating, and inspecting operate at the level of expressions. Almost anything you can use as the right side of an assignment statement can be used as a debugging expression.


Hard Mode

Stops all Windows programs except the integrated debugger from executing. When the debugger is in hard mode, you cannot use the full functionality of the Windows environment. For example, you will not be able to switch to another task. The debugger will behave as if it is the only program in memory, much like a program running in the DOS environment.

Use hard mode to debug programs that send intertask messages such as DDE messages, and to perform other low-level debugging.

Because of limitations in Windows, occasionally you might need to stop all other Windows programs except the debugger from executing. This state is called hard mode.

When the debugger is in hard mode, you will not be able to use the functionality of the Windows environment.


Logic Error

An error in design or implementation that does not prevent your program from compiling, but causes it to not do what you intended. For example, logic errors can result in variables with incorrect or unexpected values, graphic images that display incorrectly, or code that does not execute when expected.

Logic errors are often hard to track down because the IDE cannot find them automatically. The Borland C++ IDE, however, includes debugging features, collectively referred to as the integrated debugger, that can help you locate logic errors.


Run-Time Error

An error that does not prevent your program from compiling, but causes it to fail when you try to run it. Your program contains legal statements, but the statements do not execute properly.

For example, if your program attempts to open a file that does not exist or tries to divide by zero, the operating system detects the situation and it stops your program from running.


Soft Mode

The integrated debugger attempts to handle messages from other applications. When the debugger is in soft mode, you can use the full functionality of the Windows environment.


Symbol Table

A list of the identifiers used by the debugger to track all variables, constants, types, and function names used in a program. Each executable program and DLL has its own symbol table. Only one symbol table can be loaded into memory at a time.


Warning

A message that appears in the Message window that does not stop your code from compiling, but indicates areas you might want to examine for problems. For example, a warning can alert you to code that

is inefficient

is not portable

violates the ANSI standard


Watch

An expression that lets you track the value of a variable or expression while you step over or trace into your code. Use the Watch window to view watches.

As you step through your program, the value of the watch expression changes when the program does something to change it.


Breakpoints Window

See Also

The Breakpoints window lists the breakpoints set in the source code associated with the current project (or the file in the active Edit window if a project is not open).

Check the checkbox beside a breakpoint to enable it.

Clear the checkbox to disable the breakpoint.

If you have not added any breakpoints yet, the Breakpoints window is empty.

To display the Breakpoints window,

Choose View|Breakpoint.

Use the Breakpoint Properties window to change the following options:

Filename

Shows the name of the source code file in which the breakpoint is set.

Line

Shows the line number location in the file where the breakpoint is set.

State

Shows the current state of the breakpoint:

Verified	The breakpoint is legal and generated successfully during compilation.

Unverified	The program has not been compiled since you added the breakpoint.

Invalid	The breakpoint is illegal. The line on which you set the breakpoint does not contain executable code (such as a blank line, comment, or declaration) and the debugger will ignore it.

Pass

Shows the number of times the debugger must reach the breakpoint line before activating the breakpoint.


See Also

Creating Conditional Breakpoints

Disabling and Enabling Breakpoints

Setting Breakpoints


Breakpoint Properties Dialog Box
Breakpoint Properties

See Also

Use this dialog box to

Create a conditional breakpoint.

Modify an existing breakpoint.

Set options that control breakpoint behavior while debugging.

To display the Breakpoint Properties dialog box,

Choose one of the following methods:

To set a Breakpoint at the current cursor location, choose Debug|Add Breakpoint.

To add a breakpoint at any location in your program, choose Add Breakpoint on the Breakpoints window SpeedMenu to display an empty Breakpoint Properties dialog box.

To modify an existing breakpoint, open the Breakpoint window and then double-click a breakpoint or select a breakpoint and choose Properties on the Breakpoints window SpeedMenu.

To view breakpoints set in your code,

Choose View|Breakpoint to display the Breakpoints window.

Filename

Name of the file which contains the breakpoint.

Line Number

Line number location in the source file where the breakpoint is set.

State

Shows the current status of the breakpoint:

Verified	The breakpoint is legal and generated successfully during compilation.

Unverified	The program has not been compiled since you added the breakpoint.

Invalid	The breakpoint is illegal. The line on which you set the breakpoint does not contain executable code (such as a blank line, comment, or declaration) and the debugger will ignore it.

Enable Conditional Breakpoint

Check the checkbox to enable the breakpoint.

Clear the checkbox to disable the breakpoint.

Conditional Expression

Check the Enable conditional expression checkbox and enter an expression that tells the debugger when to activate the breakpoint. If Enable Conditional Breakpoint is unchecked, the debugger ignores any information in this input box.  (The debugger activates the breakpoint every time it reaches the breakpoint line and satisfies the pass count, if specified.) See Conditional Expression.

Pass count

Indicates the number of times the debugger encounters the breakpoint line before it activates the breakpoint. If a you specify a condition, the pass count determines the number of times a condition is satisfied upon reaching the breakpoint line before it is activated. See Pass Count.

Break

Check Break (the default) to stop program execution when the debugger activates the breakpoint. If Break is unchecked, your program will not stop when the debugger activates the breakpoint.

Log Expression

Check Log Expression to have a message written to the Event Log when the breakpoint is activated.

Expression to Log

Enter an expression you want to evaluate or pick one from the history list. The IDE writes a message to the Event Log that records the current value of the expression at the time the debugger activates the breakpoint. See Actions.


See Also

Debugging in the IDE

Setting Breakpoints


Breakpoint Properties File Name
Filename

Enter the name of the file in which you want to set a breakpoint.


Line Number Input Box
Line Number

Enter the line number in the source code file on which you want to set a breakpoint.


State status box
State

Shows the current status of the breakpoint.

Verified	The breakpoint is legal and generated successfully during compilation.

Unverified	The program has not been compiled since you added the breakpoint.

Invalid	The breakpoint is illegal. The line on which you set the breakpoint does not contain executable code and the debugger will ignore it. For example, you cannot set a breakpooint on a line that contains a blank line, a comment, or a declaration.


Enabled checkbox
Enable Conditional Breakpoint

Disables or enables a breakpoint.

Check the checkbox to enable the conditional breakpoint.

Clear the checkbox to disable the breakpoint.

If Enable Conditional Breakpoint is not checked, the debugger activates the breakpoint every time it reaches the breakpoint line and ignores anything in the Conditional Expression input box.


Conditions Input Box
Conditional Expression

See Also

Check Enable Conditional Brealkpoint to set a conditional breakpoint. If Enable Conditional Breakpoint is unchecked, the debugger ignores any information in this input box. The debugger activates the breakpoint every time it reaches the breakpoint line (and satisfies the Pass Count, if specified).

In the input box, enter an expression that tells the debugger when to activate the breakpoint. If the condition is not met, the debugger ignores the breakpoint as well as any of its actions. You can enter a Boolean expression that, for example, tests if a value falls within a certain range or if a flag has been set.

Example

Suppose Enable Conditional Breakpoint is checked and you enter the following conditional expression:

x > 3

When the debugger reaches the breakpoint line, your program stops only if the current value of x is greater than 3. Otherwise, the breakpoint is ignored.


See Also

Operators

Pass count


Pass Count

Lets you enter the number of times you want the debugger to encounter the line on which a breakpoint is set before it activates the breakpoint. If a you specify a conditional expression, the pass count determines how many times the conditional expression must be satisfied when the debugger reaches the breakpoint line before it is activated.

Unconditional Breakpoint Example

Suppose Break is checked, and

Enable Conditional Breakpoint is unchecked

in the Pass Count box you enter 2

In this case, your program does not stop until the second time the debugger reaches the breakpoint line.

Conditional Breakpoint Example

Suppose Enable Conditional Breakpoint and Break are checked, and

in the Conditional Expression input box you enter x>3

in the Pass Count box you enter 2

In this case, your program does not stop until the second time the debugger reaches the breakpoint line when the value of x is greater than 3.


Actions Group Box
Actions

See Also

The Breakpoint Properties actions provide the following options:

Break

Check Break (the default) if you want your program to stop when the debugger activates the breakpoint. If Break is unchecked, your program will not stop when the breakpoint is activated.

Log Expression

Check Log Expression if you want the debugger to write a message you can view in the Event Log when the breakpoint is activated.

Expression To Log

Enter an expression you want to evaluate or pick one from the history list. The IDE writes a message to the Event Log that records the current value of the expression at the time the debugger activates the breakpoint.


See Also

Creating Conditional Breakpoints


Call Stack window

See Also

Shows you the sequence of function calls that brought your program to its current state. It deciphers all active functions and their argument values and displays them in a readable format.

The most recently called function displays at the top of the list, followed by its caller and the previous caller to that. The list continues to the first function in the calling sequence which displays at the bottom.

The Call Stack window also lets you view the arguments passed to each function.

Note:	Functions called from DLLs and Windows kernel code also display in the Call Stack window even though they might not have symbolic names associated with them.


See Also

Debugging Dynamic-link Libraries

Returning to Where a Function was Called


Event Log

See Also

Use the Event log to display the results of breakpoints, Windows messages, and output messages that are generated while you use the integrated debugger.

To display the Event log,

Choose View|Event Log.


See Also

Logging Events

Setting Breakpoints


Expression Evaluator Dialog Box
Expression Evaluator

See Also

Lets you

Evaluate an expression in your code.

Modify a variable as you run your program.

Expression

Enter the expression you want to evaluate or pick one from the history list and then choose Evaluate.

Result

Displays the current value of the expression in the Expression box.

New Value

Enter a value you want to assign to the expression in the Expression box and then choose Modify. The change takes effect immediately.

To cancel,

Choose Close to cancel at any time before you modify an expression. You cannot undo a change to a value after you choose Modify. To restore a value, however, you can enter the previous value in the New Value input box and modify the expression again.


See Also

Browsing Through Your Code

Evaluating Expressions

Modifying Variables


Expression (Expression Evaluator)
Expression

Enter the expression you want to evaluate or pick one from the history list and then choose Evaluate.

You can evaluate any valid C or C++ expressions except those that contain

symbols or macros defined with #define

local or static variables not in the scope of the function being executed

function calls (or expressions that contain function calls)

Display Format

To change the display format of an expression, see Expression Evaluator Format Specifiers.


Result

Displays the current value of the expression in the Expression box.

You must first enter an expression in the Expression box and choose Evaluate.


New Value

Enter a value you want to assign to the expression in the Expression box and then choose Modify. The change takes effect immediately.

You must first evaluate an expression.


Evaluate button

Enter an expression and then choose Evaluate to display its current value in the Result box.


Modify button

Enter a value in the New Value input box and then choose Modify to change the current value of the expression in the Expression input box. You must first evaluate an expression.

Note:	The change takes effect immediately and you cannot undo or cancel the change after you choose Modify. To restore a value, however, you can enter the previous value in the New Value input box and modify the expression again.


Close Button
Close

Choose Close to dismiss the Expression Evaluator dialog box. You cannot undo a change to a variable after you choose Modify.


Inspector window

See Also

Use this window to examine the value of a data element.

To display the Inspector window,

1.	In an Edit window, position the cursor on the data element you want to inspect.

2.	Choose View|Inspect from the Edit window SpeedMenu.

or

1.	Choose Debug|Inspect to display the Inspect Expression dialog box.

2.	Type in the expression you want to inspect.

3.	Choose Inspect.

The number of panes and the appearance of the data in the Inspector window depends on the type of data you inspect. You can inspect the following types of data:

arrays

classes

constants

functions

pointers

scalar variables (int, float, and so on)

structures and unions


See Also

Inspecting Data Elements

Debugging in the IDE

Browsing Through Your Code


Inspect Expression Dialog Box
Inspect Expression

See Also

Enter a data element you want to inspect. It must be a program variable or expression available to the debugger.

Scope

Unlike a watch expresion, the scope of a data element is fixed at the time you open it in the Inspector window and never changes:

If you use the SpeedMenu command, the data element is always evaluated within the scope of the line on which the data element appears.

If you use the menu bar command, the data element is evaluated within the scope of the execution point.

 	If the execution point is in the scope of the expression you are inspecting, the value appears in the Data Inspector window. If the execution point is outside the scope of the expression, the value is undefined.

Data Types

The number of panes and the appearance of the data in the Inspector window depends on which of the following types of data you inspect:

arrays

classes

constants

functions

objects

pointers

scalar variables (int, float, and so on)

structures and unions

For example, if you inspect an array, you will see a line for each member of the array with the array index of the member. The value of the member follows in its display format, followed by the value in hexadecimal.


See Also

Inspecting Data Elements

Debugging in the IDE

Browsing Through Your Code


Set Index Range Dialog Box
Set Index Range

See Also

Lets you change the values of an array displayed in an Inspector window.

If you are inspecting a data structure, it is possible the number of items displayed might be so great that you will have to scroll in the Inspector window to see the data you are want. For easier viewing, narrow the display to a range of data items.

Starting Index

Enter a new value for the first element in the array.

Count

Enter the number of elements in the array you want to change.


See Also

Changing the Value of Inspector Items

Inspecting Data Elements


Change Value Dialog Box
Change Value

See Also

Enter a new value for the data elment displayed in an Inspector window.


See Also

Inspecting Data Elements


Registers window

See Also

Displays the values in the data, pointer, index, segment, and instruction pointer registers, as well as the settings of the status word or flags.

The Registers window contains two panes:

	Click on an area for a description.


Registers window

See Also

Displays the values in the data, pointer, index, segment, and instruction pointer registers, as well as the settings of the status word or flags.

The Registers window contains two panes:

Registers pane

The left side of the widow shows the registers in memory.

Flags pane

The right side of the widow shows the state of the eight CPU flags indicated by a corresponding letter.

Letter	Flag name

c	Carry

z	Zero

s	Sign

o	Overflow

p	Parity

a	Auxiliary carry

i	Interrupt enable

d	Direction


See Also

Examining Register Values

Debugging in the IDE


Registers pane

Shows the registers in memory.


Flags pane

The Flags pane shows the state of the eight CPU flags indicated by a corresponding letter.

Letter	Flag name

c	Carry

z	Zero

s	Sign

o	Overflow

p	Parity

a	Auxiliary carry

i	Interrupt enable

d	Direction


See Also

Examining Register Values


Watch window

See Also

This window lists the watches you are currently monitoring.

Check the checkbox beside a watch to enable it.

Clear the checkbox to disable the watch.

If you have not added any watches yet, the Watch window is blank.

To display the Watch window,

Choose View|Watch.


See Also

Watching

Debugging in the IDE


Watch Properties Dialog Box
Watch Properties

See Also

Use this dialog box to either

Create a watch.

Modify watch properties.

Expression

Enter the name of the program variable or expression you want to watch.

Radix

Choose to display integers in decimal or hexadecimal format. See Radix.

Display as

Choose the display format of the watch. See Display As.

Repeat Count

If you are watching an array, enter the number of elements you want to display.

Significant

If you are watching a floating point variable, enter the number of significant digits you want to display. You can specify a number from 2-18. The default is 7.


Expression (Watch Properties)
Expression

Enter the name of the program variable or expression you want to watch.


Radix

See Also

Choose one of the following options to specify the display format of integers in a watch expression.

Option	Types affected	Description

Decimal 	Integers	Shows integer values in decimal form, including those in data structures.

Hexadecimal 	Integers	Shows integer values in hexadecimal with the 0x prefix, including those in data structures.


See Also

Display As

Adding a Watch

Watching Expressions

Watching Data Elements


Display As

See Also

By default, the debugger displays the result of a watch in the format that matches the data type of the expression.

For example, integer values normally display in decimal form. If you select the Hexadecimal button on the Watch Properties dialog box for an integer type expression, the IDE changes the display format from decimal to hexadecimal.

The following table describes the Watch Properties dialog box Display As options and their effects.

Option	Types affected	Description

Default	All	Shows the result in the display format that matches the data type of the expression.

Structure	Structures and unions	Shows field names and unions as well as values such as X:1;Y:10;Z:5.

Memory dump	All	Shows the size in bytes starting at the address of the indicated expression. By default, each byte displays two hex digits. Use the memory dump with the character, decimal, hexadecimal, and string options to change the byte formatting.

Character	Characters and strings	Shows special display characters for ASCII 0 to 31. By default, such characters are shown using the appropriate C escape sequences (\n, \t, and so on).

Pointer	Pointers	Shows pointers in segment:offset notation with additional information about the address pointed to. It tells you the region of memory in which the segment is located and, if applicable, the name of the variable at the offset address.

String	Char, strings	Shows ASCII 0 to 31 as C escape sequences. Use only to modify memory dumps.

Floating point	Floating point	Shows the significant digits specified; from 2-18. The default is 7.


See Also

Adding a Watch

Watching Expressions

Watching Data Elements

Browsing Through Your Code

Browsing Symbols in Your Code

Browsing Global Symbols

Browsing Objects


Repeat Count

See Also

If you are watching an array, enter the number of elements you want to display.


See Also

Watching Data Elements


Significant

See Also

If you are watching a floating point variable, enter the number of significant digits you want to display. You can specify a number from 2-18. The default is 7.

See Watching Data Elements


See Also

Watching Data Elements

Browsing Through Your Code


Watching Data Elements

See Also

If you are watching a data element such as an array, you can display the values of the consecutive data elements.

For example, for an array of five integers named xarray, type the number 5 in the Repeat Count box of a Watch Properties window to see all five values of the array. An expression used with a repeat count must represent a single data element.

The integrated debugger views the data element as the first element of an array if it is not a pointer, or as a pointer to an array if it is.

Floating Point Display As option

If you select the Floating Point display option, you can also indicate the number of significant digits you want displayed in the watch expression result. Specify the number of digits, from 2-18, in the Significant box. The default is 7.


See Also

Debugging in the IDE

Event Log

Browsing Through Your Code

Browsing Symbols in Your Code

Browsing Global Symbols

Browsing Objects


Load Symbol Table

See Also

Use this window to

see the symbol table currently loaded into memory.

view the names of other symbol tables available to your program.

load another symbol table into memory.

Only one symbol table can be loaded into memory at a time.

To switch between symbol tables,

1.	Choose Debug|Load Symbol Table.

2.	Choose the symbol table you want to load from the Available list.

Current

Shows the symbol table currently loaded into memory.

Available

Lists the symbol tables available to your program.


See Also

Debugging Dynamic-link Libraries

Debugging in the IDE


Current

Shows the symbol table currently loaded into memory.


Available

Lists the symbol tables available to your program.


Building Applications with AppExpert

See Also

AppExpert lets you create ObjectWindows-based Windows applications with features such as a tool bar, a status bar, a menu structure, online Help, and MDI windows. You can also select options to support printing, print preview, and document/view. AppExpert works with Resource Workshop, ObjectWindows classes, and the IDE's project manager to form a visual approach to application generation.

Creating applications with AppExpert consists of four steps:

1.	Use AppExpert to define the user interface and application features and to generate the code.

2.	Use ClassExpert to add classes and event handlers, to implement virtual functions, to navigate to existing class source code, and automate classes. ClassExpert can also associate Resource Workshop objects (such as menus and dialog boxes) with classes or handlers.

3.	Use Resource Workshop to edit or add resources.

4.	Use the Project Hierarchy to build your application.

AppExpert always creates the following files for each application:

A database file for the AppExpert source (.APX) that ClassExpert uses

A main header file (.H)

A main source file (.CPP)

A project file (.IDE)

A resource header file (.RH)

A resource script file (.RC)

Depending on which options you choose, AppExpert can create the following files:

Help source files (.RTF)

A Help project file (.HPJ)

Icon and bitmap files (.ICO and .BMP)


See Also

Creating an Application with AppExpert


Steps for Creating an Application with AppExpert

To create an AppExpert application:

1.	Start the IDE and choose Project|AppExpert. A dialog box appears.

2.	Type a name for your project file. By default, most generated files (including the .EXE) are derived from the target name (for example, <targetname>.CPP). Select a path where you want the AppExpert project and source files to be stored. AppExpert will create the directory if it does not already exist. Click OK. The AppExpert Application Generation Options dialog box appears.

3.	The Application Generation Options dialog box contains a list of topics on the left and a brief description of the topic on the right. You can change options in the dialog box to customize the type of application you want generated.

4.	Click the Generate button at the bottom of the Options dialog box.

5.	The Generate dialog box appears, asking you to confirm that you want the code generation for your application to begin. Click Yes to generate the code for your application. While AppExpert is generating your application, a message box displays the current status.

6.	The project window appears, listing some of the files required for your application (files for bitmaps, icons, and help text are not displayed). You can use ClassExpert to modify your application or you can build it first. To build your application, choose either Project|Make All  or Project|Build All.

Hint: The application generates and builds faster, if you uncheck unneeded options.

Note:	With AppExpert, you choose your application options once, then generate the code. After you generate the code and resources, you can edit and add to them, but you cannot go back to AppExpert and change options. For example, if you use AppExpert to generate an application that does not contain a status line and then decide to add one. You will need to write code to add that functionality.


AppExpert
AppExpert Application Generation Options

See Also

The AppExpert Application Generation Options affect the code generation for your application.

Subtopics

Application

Main Window

MDI Child/View


See Also

Building Applications with AppExpert


Application options

Use the AppExpert|Application options to define the specific characteristics of the application you want to generate.

Options

Window Model

Features to Include

Customize Application button

Use the Customize Application button to open the group (if necessary) and go to the first option in the first subtopic available for the Application section of the AppExpert options.

Generate button

If you simply want to use the default options, you can generate your application now by pressing the Generate button.

Subtopics

Basic Options

OLE 2 Options

Code Gen Control

Admin Options


Application | Window Model

The Application|Window Model options to determine which model to use for your application and how application objects will be handled.

MDI (Multiple Document Interface)

The MDI option sets the style of your application to follow the Multiple Document Interface (MDI) model. This model causes child windows to be constrained within the boundaries of the application window.

SDI (Single Document Interface)

The SDI option sets the style of your application to follow the Single Document Interface (SDI) model. This model supports child windows that can exist outside of the constraints of the application window without being clipped.

Dialog Client

The Dialog Client option sets the style of your application so that the main (and only) window of your application is a dialog window, making the client area of the application a dialog box.

Document/View

The Document/View option determines whether your application supports the Document/View model for handling application objects. The Document/View model breaks data handling into two discrete parts: data storage and control, in the document class (derived from TDocument), and data display and manipulation, in the view class (derived from TView).

You can use the Document/View option with either SDI or MDI applications.


Application|Features
Application | Features to Include

Use the Application|Features to Include options to specify which additional user interface elements your application supports.

Toolbar

Turn on the Toolbar option to place a toolbar at the top of your application's main window.

Status Line

Turn on the Status Line option to place a status line at the bottom of your application's main window. The code generated will display help hints in the status line when menu items are highlighted.

Drag/Drop

Turn on the Drag/Drop option to have code generated so that your application will support drag-and-drop actions.

Printing

Turn on the Printing option if you want your application to support printing-related activities. The code generated will handle the Print Setup, Print Preview, and Print commands.


Application | Basic Options

The Application|Basic Options options define the general characteristics of the application you are going to generate, such as the initial state of the application's main window, and the generation of help files, as well as the directories where files will be stored.

If you simply want to use the default options, you can generate your application now by pressing the Generate button.

Target Name

Use Target Name to define the name of the AppExpert target you want to create within the IDE project.

Base Directory

Use the Base Directory to set the base directory path from which all of the AppExpert project directories will be located.

Include Help File Support

Use the Include Help File Support option to determine whether help source and project files are generated for the project.

Help File Name

Use Help File Name to specify the name of the help file associated with your application. This is also the name of the node associated with the help file in your AppExpert project.

Application Startup State

Use the Application Startup State options to set the initial state of the application's main window.

Control Style

Use the Control Style options to determine which type of controls the application will use.


Target Name

Use Application|Basic Options|Target Name to name the AppExpert target that will be used to build your application. This name is the basis for the default names of other elements in your project (e.g., header files, class database, application class, and source files).

The default name is the same as the IDE project. You can use this name or enter your own.


Base Directory

Use Application|Basic Options|Base Directory to define the main project directory. All other directories associated with the project are placed relatively to this directory.

You can enter a directory by entering it yourself or press the Browse button to select one from the Select Directory dialog box.

The default base directory is the one you choose in the New AppExpert Project dialog box. The name of this directory is passed to the Project Manager for the new AppExpert target.


Include Help File Support

If you select the Application|Basic Options|Include Help File Support option, AppExpert will generate RTF source files and a Help project file when it generates your application. The Help project file will be added to the Project Manager project and automatically built with the target application.

This Help file contains placeholder text for the menus and menu options present in the generated application.


Help File Name

Use Application|Basic Options|Help File Name to specify the name of the help file associated with your application. This file name identifies the source and Help project files.

The default value for the file name is the same as the application project. You can also enter your own file name.


Application | Basic Options | Application Startup State

Use the Application|Basic Options|Application Startup State options to set the initial state of the application's main window.

Normal (sizeable)

Turn on the Normal option to set the application window to start in a default size. This is the default setting.

Minimized (iconic)

Turn on the Minimized option to set the application window to start in a minimized state (as an icon on the Windows desktop).

Maximized (entire screen)

Turn on the Maximized option to set the application window to fill the entire Windows desktop when it starts running.


Application | Basic Options | Control Style

Use the Application|Basic Options|Control Style options to determine which type of controls the application will use.

Standard Windows

Turn on the Standard Windows option to specify that the application will use standard Windows controls. This is the default setting.

Borland BWCC

Turn on the Borland BWCC option to specify that the application will use the Borland custom control style.

MS Control 3D

Turn on the MS Control 3D option to specify that the application will use the new three-dimensional Windows controls.


Application | OLE 2 Options

Use the Application|OLE 2 Options options to set the behavior of your OLE 2 application.

OLE 2 Container Options

Choose whether or not you want your application to be an OLE 2 container application.

OLE 2 Server Options

Choose whether you want your application to be an OLE 2 Server DLL, EXE, or not a server at all.

Enable Automation in the Application

Select the Enable Automation in the Application option if you want your application to be an OLE 2 automation server.

Server ID

If you set your application to be an OLE 2 Server, use the Server ID field to specify the identifier for your application.


Application | Code Generation Control

Use the Application|Code Generation Control options to control various aspects of the code generation process.

Target Name

Displays the name of the project as defined in Basic Options|Target Name.

Base Directory

Displays the base directory for the project as defined in Basic Options|Base Directory.

Source Directory

Use Source Directory to specify the directory where the source files for the application will be placed during code generation.

Header Directory

Use Header Directory to specify the directory where the header files for the application will be placed during code generation.

Main Source File

Use Main Source File to name the main application source file. The default filename is the name of the project: <TargetName>app.CPP. AppExpert will parse and shorten the project name if it is longer than eight characters.

Main Header File

Use Main Header File to name the main application header file. The default filename is the name of the project: <TargetName>app.H. AppExpert will parse and shorten the project name if it is longer than eight characters.

Application Class

Use Application Class to name the class that AppExpert will derive from TApplication. The default class name is <TargetName>App.

About Dialog Class

Use About Dialog Class to name the class that AppExpert will derive from TDialog. The default class name is <TargetName>AboutDlg.

Comments

Use the Comments options to specify how the generated code is documented.


Source Directory

See Also

Use Application|Code Generation Control|Source Directory to specify the directory where the source files for the application will be placed during code generation. This path is relative to the directory specified as the Base Directory. If an absolute path is specifed, it is converted to a path relative to the Base Directory.

You can enter a directory or press the Browse button to select one from the Select Directory dialog box. The default value for the Source Path is the current directory, which is the directory specified in Base Directory.


See Also

Code Gen Control|Header Directory


Header Directory

See Also

Use Application|Code Generation Control|Header Directory to specify the directory where the header files for the application will be placed during code generation. This path is relative to the directory specified as the Base Directory. If an absolute path is specifed, it is converted to a path relative to the Base Directory.

You can enter a directory or press the Browse button to select one from the Select Directory dialog box. The default value for the Header Path is ".\" which causes source files to be placed in the current directory.


See Also

Code Gen Control|Source Directory


Application | Code Gen Control | Comments

Use the Application|Code Generation Control|Comments options to specify how much of the generated code is documented.

Terse

Turn on the Terse option to sparsely comment the generated code.

Verbose

Turn on the Verbose option to heavily comment the generated code.


Application | Administrative Options

Use the Application|Administrative Options to specify identifying information that will be placed in a comment block at the beginning of all of the generated project files. Some of the information is also displayed in the About... dialog box of the application.

Version Number

Use Version Number to provide the version number for the project. This value will be displayed in the application's "About . . ." dialog box. The default version number is "1.0".

Copyright

Use Copyright to provide the copyright information for your application. This value will be displayed in the application's "About . . ." dialog box and will be placed in all of the comment blocks generated by AppExpert.

Description

Use Description to provide a description of your application. This value will be displayed in the application's "About . . ." dialog box. The default value is the name of the project.

Author

Use Author to provide the name of the programmer who generated the source code. This will be placed in all of the comment blocks generated by AppExpert.

Company

Use Company to provide the name of the programmer's company. This will be placed in all of the comment blocks generated by AppExpert.


Main Window settings
Main Window options

Use the AppExpert|Main Window options to control the appearance and operation of the main window of the generated application.

Options

Window Title

Use Window Title to specify the name that will be displayed as the caption for the application's main window.

Background Color button

Use the Set Background Color button to set the background color of the application's main window. Pressing this button displays the Color dialog box.

Customize Main Window button

Use the Customize Main Window button to open the group (if necessary) and go to the first option in the first subtopic available for the Main Window section of the AppExpert options.

Generate button

If you want to simply use the default options, you can generate your application now by pressing the Generate button.

Subtopics

Basic Options

SDI Client

MDI Client

Dialog Client


Main Window | Basic Options

Use the Main Window|Basic Options to control the general appearance of the main window of your application.

Window Styles

Use the Window Styles options to control the appearance of the application's main window, specifying its border style and whether it contains system and control menus.

Caption

Turn on the Caption radio button to create a single, thin border and a title bar where a caption can be displayed.

Border

Turn on the Border option to get a single, thin border without a caption for the application's main window.

Max Box

Turn on the Max Box option to add a maximize button to the right side of the application's main window caption.

Min Box

Turn on the Min Box option to add a minimize button to the right side of the application's main window caption.

Vertical Scroll

Turn on the Vertical Scroll option to add a vertical scroll bar to the right side of the application's main window.

Horizontal Scroll

Turn on the Horizontal Scroll option to add a horizontal scroll bar to the bottom of the application's main window.

System Menu

Turn on the System Menu option to add a system menu button on the left side of the application's main window caption.

Visible

Turn on the Visible option to make the application's main window visible. This is the default setting. When this option is off, the WS_VISIBLE style is changed to NOT WS_VISIBLE.

Disabled

Turn on the Disabled option to disable the application's main window.

Thick Frame

Turn on the Thick Frame option to place a double border around the application's main window. If this option if off, users cannot resize the main window.

Clip Siblings

Turn on the Clip Siblings option to protect the siblings of the application's main window. Painting is restricted to that window.

Clip Children

Turn on the Clip Children option to protect child windows from being repainted by the application's main window.


Color dialog box

Use the Color dialog box to select the background color you want for the background of your main application window.


Main Window|SDI Client
Main Window | SDI Client Window

Use the Main Window|SDI Client Window options to define the class that represents the client area of the Single Document Interface main window. These options are only applicable if you select the Single Document Interface option from Application|Window Model options.

Client/View Class

Use Client/View Class to name the class of the SDI client area window or view.

Document Class

Use Document Class to name the class of the default document. If the Doc/View option in the Application|Window Model options is selected, the default value is TFileDocument; otherwise, Document Class is blank.

Description

Use Description to describe the class of files associated with the Files of Type List in Windows common file dialog boxes. The default value is "All Files (*.*)". This value serves as the description for the value entered in Filters.

Filters

Use Filters to list wildcard file specifications (separated by semicolons) for the file names you want the application to recognize. This value is passed to Windows common file dialog boxes to filter files displayed in the list box of those dialog boxes. The default value is "*.*". The values entered in Description serves as the explanation of this value.

Default Extension

Use Default Extension to specify the default filename extension. This value is passed to Windows common file dialog boxes and added to filenames without extensions. The default value is "TXT".

Class Name

Use Class Name to specify the name AppExpert uses for the class derived from Client/View Class that represents the client area of the SDI frame window. The default value is <ProjectName><Client/ViewClass> (without the leading "T").

Source File

Use Source File to name the source file that will store the implementation of the class named in Client/View Class. The default value is <ClassName>.CPP. AppExpert will parse and shorten the class name if it is larger than eight characters.

Header File

Use Header File to name the header file that will store the definition of the class named in Client/View Class. The default value is <ClassName>.H. AppExpert will parse and shorten the class name if it is larger than eight characters.


Client/View Class

Use Main Window|SDI Client|Client/View Class to name the class of the SDI client area or view. The interpretation of this value depends on whether you select the Doc/View option in the Application|Window Model options.

If the Doc/View option is not selected, Client/View Class selects the class of the client window; otherwise, Client/View Class selects the class of the view of the default document/view.

Doc/View

On	Off

TEditView (default)	TEditFile (default)

TListView	TListBox

TWindowView	TWindow

This value is automatically mapped to the Doc/View options. For example, if you turn off the Doc/View option, TListView is switched to TListBox. Conversely, if you select the Doc/View option, TListBox changes to TListView.


Main Window|MDI Client
Main Window | MDI Client Window

Use the Main Window|MDI Client Window options to describe the class that defines the client window of the Multiple Document Interface main window. These options are only applicable if you select the Multiple Document Interface option from Application|Window Model options.

Client Class

Use Client Class to specify the name AppExpert uses for the class derived from TMDIClient that represents the client area of the MDI frame window. The default value is <TargetName><ClientClass>.

Source File

Use Source File to name the source file that will store the implementation of the class named in Client Class. The default value is <ClientClass>.CPP. AppExpert will parse and shorten the client class name if it is larger than eight characters.

Header File

Use Header File to name the header file that will store the definition of the class named in Client Class. The default value is <ClientClass>.H. AppExpert will parse and shorten the client class name if it is larger than eight characters..


Main Window|Dialog Client
Main Window | Dialog Client Window

Use the Main Window|Dialog Client Window options to describe the characteristics of an application where the main window is a dialog window.

Client Class

Use Client Class to specify the name AppExpert uses for the class derived from TDialog that represents the main window of the application. The default value is <TargetName><ClientClass>.

Source File

Use Source File to name the source file that will store the implementation of the class named in Client Class. The default value is <ClientClass>.CPP. AppExpert will parse and shorten the project name if it is larger than eight characters.

Header File

Use Header File to name the header file that will store the definition of the class named in Client Class. The default value is <ClientClass>.H. AppExpert will parse and shorten the class name if it is larger than eight characters.

Dialog ID

Use Dialog ID to specify the identifier associated with the dialog that functions as the main window of your application.

Include a Menu Bar

Select Include a Menu Bar if you want a menu bar on your main window.


MDI Child/View settings
MDI Child/View options

Use the AppExpert|MDI Child/View options to define the class that will define a default child window or document/view of the Multiple Document Interface application. These options are only applicable if you select the Multiple Document Interface option from Application|Window Model options.

Options

MDI Child Class

Use MDI Child Class to name the class derived from TMDIChild that represents the frame of the default MDI child windows. The default value is <TargetName>MDIChild.

Source File

Use Source File to name the source file that will store the implementation of the class named in MDI Child. The default value is <MDIChildClass>.CPP. AppExpert will parse and shorten the child class name if it is larger than eight characters.

Header File

Use Header File to name the header file that will store the definition of the class named in Client Class. The default value is <MDIChildClass>.H. AppExpert will parse and shorten the child class name if it is larger than eight characters.

Customize Child and View button

Use the Customize Child and View button to open the group and go to the first set of options available for the MDI Child/View section of the AppExpert options. This is the same as double-clicking on the group name in the left pane when the section of the outline is collapsed.

Generate button

If you want to simply use the default options, you can generate your application now by pressing the Generate button.

Subtopics

Basic Options


MDI Child/View | Basic Options

Use the MDI Child/View|Basic Options to define the default child window of an MDI application.

MDI Client/View Class

Use MDI Client/View Class to name the class of the default MDI view.

Document Class

Use Document Class to name the class of the default document. If the Doc/View option in the Application|Window Model options is selected, the default value is TFileDocument.; otherwise, Document Class is blank.

Description

Use Description to describe the class of files associated with the Files of Type List in Windows common file dialog boxes. The default value is "All Files (*.*)". This value serves as the description for the value entered in Filters.

Filters

Use Filters to list wildcard file specifications (separated by semicolons) for the file names you want the application to recognize. This value is passed to Windows common file dialog boxes to filter files displayed in the list box of those dialog boxes. The default value is "*.*". The values entered in Description serves as the explanation of this value.

Default Extension

Use Default Extension to specify the default filename extension. This value is passed to Windows common file dialog boxes and added to filenames without extensions. The default value is "TXT".

Class Name

Use Class Name to specify the name AppExpert uses for the class derived from the MDI Client/View Class that represents the client area of the MDI frame window. The default value is <ProjectName><ClientViewClass> (without the leading "T").

Source File

Use Source File to name the source file that will store the implementation of the class entered in Class Name. The default value is <ClassName>.CPP. AppExpert will parse and shorten the project name if it is larger than eight characters.

Header File

Use Header File to name of the header file that will store the definition of the class entered in Class Name. The default value is <ClassName>.H. AppExpert will parse and shorten the class name if it is larger than eight characters.


MDI Client/View Class

Use MDI Child/View|Basic Options|MDI Client/View Class to name the class of the MDI client area or view. The interpretation of this value depends on whether you selected the Doc/View option in the Application|Window Model options.

If the Doc/View option is not selected, MDI Client/View Class selects the class of the client window; otherwise, MDI Client/View Class selects the class of the view of the default document/view.

Doc/View

On	Off

TEditView (default)	TEditFile (default)

TListView	TListBox

TWindowView	TWindow

This value is automatically mapped to the Doc/View options. For example, if you turn off the Doc/View option, TListView is switched to TListBox. Conversely, if you select the Doc/View option, TListBox changes to TListView.


Select Directory dialog box

Use the Select Directory dialog box to choose a directory for input boxes that require valid directory names and paths.

Directories

The Directories list box displays the directories available on the current drive.

Selected Path

The Selected Path display box shows the currently selected directory path.

New Subdirectory

Use the New Subdirectory input box to create a new subdirectory from the Selected Path.


Select Directory dialog box

Use the Select Directory dialog box to choose a directory for input boxes that require valid directory names and paths.

Directories

The Directories list box displays the directories available on the current drive.

Selected Path

The Selected Path display box shows the currently selected directory path.

New Subdirectory

Use the New Subdirectory input box to create a new subdirectory from the Selected Path.

Drives

Use the Drives list box to select a drive from the list of drives currently accessible from your system.


Customize button

Use the Customize button to open the group (if necessary) and go to the first option in the first subtopic available for the current section of the AppExpert options. From there, you can set specific options for the AppExpert application you are going to build.


Generate button

Use the Generate button to start AppExpert generating the code for your application. AppExpert displays the Generate dialog box and prompts for your confirmation before starting to generate code.


Browse button

Use the Browse button to display the Select Directory dialog box in which you can select a directory.


Network button

Use the Network button to access drives and directories available on your network.


Generate dialog box

The Generate dialog box is displayed when you press the Generate button. It prompts you for confirmation before starting to generate code.

Click Yes to begin building your AppExpert application.

Click No if you do not want your AppExpert application built. You will be returned to the AppExpert|Application options dialog box.

Before starting code generation, AppExpert verifies that options you have selected are valid. If any options are not valid, AppExpert returns you to the AppExpert Application Generation Options dialog box.


ClassExpert
Managing Your Classes with ClassExpert

See Also

ClassExpert lets you create new classes, edit and refine the implementation of classes, and navigate through the source code for existing classes in your AppExpert applications. You can use ClassExpert with Resource Workshop to associate classes to resources (for example, associating a TDialog class to a dialog resource). ClassExpert displays virtual functions and events for existing classes and checks the ones implemented in your application. You can also use ClassExpert to instantiate and automate classes in your AppExpert project.

To start ClassExpert:

1.	Open an AppExpert project file by choosing Project|Open Project.

2.	Double-click the AppExpert target node (ClassExpert is the default viewer for AppExpert targets), or choose View|ClassExpert or click the toolbar button. ClassExpert appears, listing the classes and their implementation for your application.

The ClassExpert contains three panes, each with a specific function:

Classes	displays the classes used in the application

Events	displays the events handled by the selected class

Edit	lets you view and edit the source associated with the selected class


See Also

Using Rescan to Rebuild Your Project Database


Using Rescan to Rebuild Your Project Database

Rescan is a special project tool that examines all the source code listed in your AppExpert project (.IDE file) and updates or rebuilds the project's database (the .APX file) according to what it finds in the source code. Rescan looks for special markers in the source code to reconstruct the AppExpert database file and then starts Resource Workshop to reconstruct information about project resources. If the rescan is successful, the original project database file is renamed to *.~AP and a new database file is created; otherwise, the original database is left as *.APX.

You can use Rescan to:

Delete a class

Move a class from one source file to another

Rename a class, handler, instance variable, or dialog ID

Import a class from another AppExpert project

Rebuild a lost or damaged project database (*.APX) file


Deleting a Class

To delete a class:

1.	Remove the class source file from the IDE project by selecting the source node, right-clicking the node, and choosing Delete Node. If the class shares a source file with other classes, delete the code related to the class from the source file and delete references to the class from other source files; otherwise, you will get errors during compilation.

2.	Select the AppExpert target in the project, right-click it, then choose Special|Rescan. Rescan scans the source files listed as dependencies for the AppExpert target. Resource Workshop scans and updates the resource files. When Rescan is complete, you will return to the updated project file where you can either build your application or use ClassExpert.

You can add the deleted class back to the project by adding the class source file (and its associated header file as a dependent node under the class source file ) as a dependent of the AppExpert target (use Add Node from the SpeedMenu), then rescanning.

3.	Look at the Classes pane in ClassExpert to see that the class is now omitted from the list.


Moving a Class

To move a class from one source file to another:

1.	Move (cut and paste) the code or definition of the class to the new source or header file. Be certain to also copy the comments generated by AppExpert or else ClassExpert will be unable to locate the correct location in the new source or header files where the class is referenced or defined.

Add the new source file if is not in the project (and its associated header file as a dependent node under the class source file) as a dependent node of the AppExpert target (use Add Node from the SpeedMenu). If the moved class was in its own source file, you can delete the now-empty source file from the project.

2.	Select the AppExpert target in the project, right-click it to view the SpeedMenu, then select Special|Rescan. When Rescan is finished, it returns you to the project window in the IDE.


Renaming an AppExpert Element

To rename a class, event handler function, instance variable, or dialog ID:

1.	Use the IDE editor to search and replace all occurrences of the original name with the new name. Be sure to check all source files associated with the project (.CPP, .H, .RC, and .RH files).

2.	In the project window, select the AppExpert target, right-click it, then choose Special|Rescan. When Rescan is finished, it returns you to the project window in the IDE.

Note:	After following this procedure, check your #include statements, as well as the #ifdef and #define statements that AppExpert created. Verify that none of these have changed as a result of searching and replacing the name of your class within the source files.


Importing a Class

To import a class from one AppExpert project to another:

1.	Move or copy the source and header file that defines the class to the source and header directory of the other project. All source files for a project must be in the project's source directory (.CPP files) or header directory (.H files). These directories were created when you first generated the AppExpert project. (Unless you specified a different source or header directory, your source and header files will be in the same directory as your project [.IDE] file.)

2.	Add the class source file as a dependent node under the AppExpert target in the IDE project (use Add Node from the SpeedMenu).

3.	Add the header file that contains the class definition as a dependent node under class source file in the AppExpert project (use Add Node from the SpeedMenu).

4.	In the project window, select the AppExpert target, right-click, then choose Special|Rescan.


Rebuilding the .APX Database File

To rebuild a lost or damaged database file (the .APX file):

1.	Open the project (.IDE) file that contains the AppExpert target and dependent nodes.

2.	Select the AppExpert target, right-click it, then choose Special|Rescan from the SpeedMenu. Rescan automatically creates a new database file using markers and the source code from the AppExpert application.


ClassExpert Classes pane
See Also	ClassExpert

The Classes pane lists the set of classes known to ClassExpert that are used in the current project. This includes all classes created during code generation and any classes you might have added afterward using ClassExpert.

Selecting a class from this list changes the contents displayed in the Events and Edit panes to show the events and source file associated with the selected class.


See Also

Classes pane SpeedMenu


ClassExpert Events and Functions pane
ClassExpert Events pane
See Also	ClassExpert

The Events pane contains an outliner list with several categories. The available categories depend on the derivation of the class currently selected in the Classes pane.

These are the categories that can be displayed:

Automation

Command Notifications

Control Notifications

Virtual Functions

Windows Messages


See Also

Events pane SpeedMenu


Events | Automation

See Also

The Events|Automation category lists all of the automation data, methods, and properties for the automated class currently selected in the Classes pane.


Events | Command Notifications

See Also

The Events|Command Notifications category lists all of the commands  inherited from the base class of the class currently selected in the Classes pane, as well as command events that can be generated by other objects in the application, such as menus. This list is dynamically updated to reflect any changes you might make to objects that generate commands in your application.

Each item in the Command Notifications category expands to two items: Command and Command Enabled. The Command handler causes the associated class to handle the command event, while the Command Enabled handler allows the associated class to control whether the command event is enabled or disabled (grayed).

A checkmark next to an event indicates that it is handled by the class currently selected in the Classes pane.


Events | Control Notifications

See Also

The Events|Control Notifications category appears only for classes derived from TDialog. This category lists the identifiers for all of the controls in the dialog associated with the class. Each control identifier expands to a list of messages it can send to or receive from the dialog class.

A checkmark next to an event indicates that it is handled by the class currently selected in the Classes pane. A light gray checkmark indicates that one or more of the child events are handled.


Events | Virtual Functions

See Also

The Events|Virtual Functions category lists all of the virtual functions inherited from the base class of the class currently selected in the Classes pane. The contents of this list is fixed for a given class.

A checkmark next to an event indicates that it is handled by the class currently selected in the Classes pane.


Events | Windows Messages

See Also

The Events|Windows Messages category lists the set of Windows messages. This set includes:

Basic Messages

Other Messages

Win32 Messages

OLE 2 Messages

A checkmark next to a message indicates that it is handled by the event currently selected in the Events pane.


ClassExpert Editor pane
ClassExpert Edit pane
See Also	ClassExpert

The Edit pane is an editor window that supports most of the features of the editor in the IDE. It contains the C++ source file associated with the class currently selected in the Classes pane.

You can freely edit the file displayed in the Edit pane, adding, deleting, and modifying code as needed.


See Also

Edit pane SpeedMenu


Classes pane SpeedMenu
Classes pane

Use the Classes pane SpeedMenu to access frequently used ClassExpert commands.

Add New Class

Automate Class

Delete Automation

View Document Types

View Class Options

Edit Dialog (dialog classes only)

Edit Menu

Edit Source

Edit Header


Add New Class

Use the Add New Class command from the Classes pane SpeedMenu to create a new class in your application. Choosing this option displays the Add New Class dialog box which you can use to define the new class you are creating.


Automate Class

Use the Automate Class command from the Classes pane SpeedMenu to expose existing classes in your application to OLE 2 automation. This will cause additional code to be added to your source files to support the automation of the class currently selected in the Classes pane. If the TApplication class is not already exposed, automating a class will automatically automate it.


Delete Automation

Use the Delete Automation command from the Classes pane SpeedMenu to remove the OLE 2 automation code from the class currently selected in the Classes pane.

Choosing this command displays a dialog box warning you that the class will be removed from automation. Click Yes to remove the automation code, or No to cancel the operation.

Note:	This command is only available if the class has already been automated.


View Document Types

Use the View Document Types command from the Classes pane SpeedMenu to create, delete, and view document and view pairings. Choosing this option displays the Document Types dialog box in which you can define the document types.

This option is only applicable if you selected the Document/View option from the Application|Window Model settings in AppExpert when you set the options for your application.


View Class Options

See Also

Use the View Class Options command from the Classes pane SpeedMenu to view a summary of the properties of the class currently selected in the Classes pane. Choosing this command displays the Class Options dialog box.

If the selected class is derived from TFrameWindow, you can also use this option to change the client class and view the window styles and background color.


See Also

Add New Class


Edit Source

See Also

Use the Edit Source command from the Classes pane SpeedMenu to edit the source file associated with the class currently selected in the Classes pane.

Choosing this option opens the source file in the IDE editor window (not in the ClassExpert Edit pane) and positions the cursor on the class constructor.


See Also

Edit Header


Edit Header

See Also

Use the Edit Header command from the Classes pane SpeedMenu to edit the header file associated with the class currently selected in the Classes pane.

Choosing this option opens the header file in the IDE editor window (not in the ClassExpert Edit pane) and positions the cursor on the class definition, not in the ClassExpert Edit pane.


See Also

Edit Source


Edit Dialog

See Also

Use the Edit Dialog command to edit the dialog template associated with the class currently selected in the Classes pane. Choosing this command starts Resource Workshop and loads the associated dialog resource into the Dialog Editor.

This option is only applicable if the currently selected class is derived from TDialog.


Edit Menu

See Also

Use the Edit Menu command to edit the menu resource associated with the class currently selected in the Classes pane. Choosing this command starts Resource Workshop and loads the associated menu resource into the Menu Editor.


See Also

Classes pane SpeedMenu

Edit pane SpeedMenu

Events pane SpeedMenu


Events and Functions pane SpeedMenu
Events pane SpeedMenu
Events pane

Use the Events pane SpeedMenu to access frequently used ClassExpert commands.

Add Handler

Delete Handler

Edit Menu

For dialog classes (those derived from TDialog), you will get these additional commands:

Add Instance Variable

Delete Instance Variable

Edit Dialog

For Automation events, you will get these additional commands:

Data	Methods	Properties

Add Data	Add Method	Add Property

Delete Data	Delete Method	Delete Property

View Data	View Method	View Property


Add Handler

Use the Add Handler option from the Events pane SpeedMenu to create a default member function skeleton in the source file for the class currently selected in the Classes pane. The source file will appear in the Edit pane.

If you add a handler for a Windows message, ClassExpert adds an entry to the response table whose name is defined by default. The function associated with the handler appears in the edit window with the appropriate default handling.

If you add a handler for a Virtual Function, the function associated with the handler appears in the edit window with the appropriate default handling.

If you add a handler for either Commands or Control Notifications, ClassExpert will prompt you for the function name before adding the entry to the response table.

This option is only applicable if the event currently selected in the Events pane is not already handled by a member function of the selected class. Unhandled events and non-overriden virtual functions will not have a checkmark next to them.


Delete Handler

Use the Delete Handler option from the Events pane SpeedMenu to delete a member function from the event currently selected in the Edit pane.

Note:	The member function is removed, but the code that implements the function is not deleted. You will be warned of this and will need to remove the code. For events, commands, and control notifications, the response table entries are removed.

This option is only applicable if the currently selected event has a member function associated with it; the handled event will have a checkmark next to it.


Add Instance Variable

Use the Add Instance Variable option from the Events pane SpeedMenu to add an instance variable for the item currently selected in the Events pane.

Choosing this option prompts you for the name of the variable. The type of the variable is fixed and determined by the associated control. ClassExpert then adds the following to your application code:

In the header file, a structure declaration is added with an entry for the instance variable.

In the source file,

1.	the instance variable is allocated in the class constructor (this associates the ObjectWindows class with the resource object).

2.	a static instance of the transfer structure is declared.

Notes:

This command is only available if:

the currently selected item is a control notification and does not already have an instance variable associated with it.

the class currently selected in the Classes pane is derived from TDialog.


Delete Instance Variable

Use the Delete Instance Variable option from the Events pane SpeedMenu to delete the instance variable associated with the item currently selected in the Events pane.

ClassExpert deletes the following from your code:

The entry from the structure

The pointer variable in the class declaration

The allocation of the class variable associated with the resource control in the constructor

If you delete all instance variables from your code, you will have an empty structure and the set transfer buffer call. This information does not affect the rest of your code, so you do not need to delete it manually.

Notes:

This command is only available if:

the currently selected item is a control notification and has an instance variable associated with it.

the class currently selected in the Classes pane is derived from TDialog.


Instance Variables

Instance variables let you handle many controls easily. When you create instance variables, ClassExpert adds a transfer buffer in your code for the controls that use them. This transfer buffer collects information at run time, so that you avoid creating code to check each check box.


Add Data

Use the Add Data command to add automation data to the class currently selected in the Classes pane. Choosing this command displays the Automate Data dialog box where you can enter information about the automation data.

Note:	This command is only available for classes that you have exposed to OLE 2 automation using the Automate Class command.


Delete Data

Use the Delete Data command to remove automation data from the class currently selected in the Classes pane.

Note:	The automation data is removed from the OLE 2 automation symbol table, but the code that implements the data is not deleted. You will be warned of this and will need to remove the code.

This option is only applicable if the currently selected class has automation data associated with it and you have selected a data member in the Events pane.


View Data

Use the View Data command to view the automation data for the class currently selected in the Classes pane. Choosing this command displays the Automate Data dialog box where you can view (but not change) the information about the selected automation data.

This option is only applicable if the currently selected class has automation data associated with it and you have selected a data variable in the Events pane.


Automate Data dialog box

The Automate Data dialog box lets you enter and view automation data members. If you chose View Data, you will only be able to view the information in each field and not change it.

Name

Use the Name input box to enter the name associated with the automation data member you are creating.

Type

Use the Type list box to select the type of automation data member you are creating.

Description

Use the Description to enter a description for the automation data member you are creating.


Add Method

Use the Add Method command to expose an automation method to OLE 2 automation in the class currently selected in the Classes pane. Choosing this command displays the Automate Method dialog box where you can enter information about the automation method.

Note:	This command is only available for classes that you have exposed to OLE 2 automation using the Automate Class command.


Delete Method

Use the Delete Method command to remove an exposed method selected in the Classes pane from the OLE 2 automation symbol table.

Note:	The automation method is removed from the OLE 2 automation symbol table, but the code that implements the method is not deleted. You will be warned of this and will need to remove the code.

This option is only applicable if the currently selected class has an automation method associated with it and you have selected a method in the Events pane.


View Method

Use the View Method command to view the automation method for the class currently selected in the Classes pane. Choosing this command displays the Automate Method dialog box where you can view the information (but not change it) about the selected automation method.

This option is only applicable if the currently selected class has an automation method associated with it and you have selected a method in the Events pane.


Automate Method dialog box

The Automate Method dialog box is lets you enter and view an automation method. If you chose View Method, you will only be able to view the information in each field and not change it.

Name

Use the Name list box to enter the name associated with the automation method you are creating. The list box will display all of the functions currently defined in your class. You can also enter a the name of a new method.

Return Value

Use the Return Value list box to select the type of the return value for the automation method you are creating.

Parameters

Use the Parameters input box to specify the parameters for the automation method you are creating. The format is (type1 name1, type2 name2, . . ., typen namen). The parentheses can be omitted. You can also leave out the names of the parameters, in which case ClassExpert will provide the names p1, p2, etc.

Description

Use the Description to enter a description for the automation method you are creating.


Add Property

Use the Add Property command to expose a property to OLE 2 automation of the class currently selected in the Classes pane. Choosing this command displays the Automate Property dialog box where you can enter information about the automation property.


Delete Property

Use the Delete Property command to remove an exposed automation property from the class currently selected in the Classes pane.

Note:	The automation property is removed from the OLE 2 automation symbol table, but the code that implements the property is not deleted. You will be warned of this and will need to remove the code.

This option is only applicable if the currently selected class has an automation property associated with it and you have selected a property in the Events pane.


View Property

Use the View Property command to view the automation property for the class currently selected in the Classes pane. Choosing this command displays the Automate Property dialog box where you can view information about the selected automation property.

This option is only applicable if the currently selected class has an automation property associated with it and you have selected a property in the Events pane.


Automate Property dialog box

The Automate Property dialog box lets you enter and view an automation property. If you chose View Property, you will only be able to view the information in each field and not change it.

Name

Use the Name input box to enter the name associated with the automation property you are creating.

Type

Use the Type list box to select the type of automation property you are creating.

Get

Use the Get checkbox to specify whether the property can be read. Selecting this option causes a C++ function to be created that returns the value of the property.

Set

Use the Set checkbox to specify whether the property can be written to. Selecting this option causes a C++ function to be created that passed a new value to the property.

Description

Use the Description inout box to enter a description for the automation property you are creating.


Edit pane SpeedMenu
Edit pane

Use the Edit pane SpeedMenu to access frequently used ClassExpert commands.

Open Source

Browse Symbol

Go to Help topic

Go to Line

Toggle Breakpoint

Run to Cursor

Set Watch

Inspect Object

Use Class


Use Class

Use the Use Class command to generate the code to instantiate a class in your application. Choosing this commands displays the Use Class dialog box that allows you to choose which class you want to instantiate.


Use Class dialog box

Use the Use Class dialog box to choose the class you want to instantiate in your application. The code that is generated (embedded in a comment) instantiates the class and a header file containing the class defintiion (if it is not already present) will be added to the source file. You will need to change the name of the class to a unique name and remove the comment specifiers.

Example:	// TheAboutDialog *xTheAboutDialog = new TheAboutDialog()

Class to Instantiate

Use the Class to Instantiate list box to select the class you want to instantiate. By default, all of the classes listed in the Classes pane will be displayed. If Use OWL Base Classes is selected, you will also see all OWL base classes in the list.

Type of Instantiation

Use the Type of Instantiation radio buttons to specify how you want the class instantiated.

Static

Choose Static to have the class instantiated statically.

Dymanic (new/delete)

Choose Dymanic to have the class instantiated dymanically, meaning that the new and delete operators are used.

Use OWL Base Classes

Select Use OWL Base Classes if you want the ObjectWindows base classes displayed in the Class to Instantiate list box.


Add New Class dialog box

Use the Add New Class dialog box to define the properties of a new class you are adding to your AppExpert application. Most of these properties cannot be changed after their values have been determined, except by directly modifying the source code that controls those properties.

Base Class

Use the Base Class combo box to select the base class from which the new class will be derived.

Class Name

Use Class Name to name the new class you are creating.

Source File

Use Source File to name the source file that will contain the implementation of the new class. The default value is <ClassName>.CPP. AppExpert will parse and reduce the class name to eight characters.

Header File

Use Header File to name the source file that will contain the definition of the new class. The default value is <ClassName>.H. AppExpert will parse and reduce the class name to eight characters.

Show All OWL Classes

Choose the Show All OWL Classes option if you want all of the available ObjectWindows classes displayed in the Base Class combo box. This allows you to select non-GUI classes for your application that are not derived from TEventHandler or TWindow.

Resource ID

Use Resource ID to specify the dialog template associated with the dialog class named in Base Class. You can select an existing dialog identifiers from the list or enter your own. If you enter a new identifier, a new default dialog template will be created and assigned that identifier. This option is only applicable if the value of Base Class is TDialog.

Client Class

Use Client Class to select the class of the client area of the new frame window. This is the only value that can be changed after you create the class. This option is only applicable if the value of Base Class is TFrameWindow or a class derived from TFrameWindow.

Set Window Properties button

Press the Set Window Properties button to set the properties for the new frame window. Pressing this button displays the Window Styles dialog box. This option is applicable for all windows derived from TWindow, except for those derived from TDialog.


Class Options dialog box

Use the Class Options dialog box to display the properties of the class you have selected in the Classes pane.

Base Class

Base Class displays the name of the base class of the currently selected class.

Class Name

Class Name displays the name of the currently selected class.

Source File

Source File displays the name of the source file that contains the implementation of the currently selected class.

Header File

Header File displays the name of the source file that contains the definition of the currently selected class.

Resource ID

Resource ID displays the dialog template associated with the dialog class named in Base Class. This value is only displayed if the value of Base Class is TDialog.

Background Color

The Background Color display box shows the current background color of the window.  This option is only applicable if the Base Class is TWindow or a class derived from TWindow.

Client Class

Client Class displays the class of the client area of the frame window. This is the only value that can be changed after you create the class. This option is only applicable if the value of Base Class is TFrameWindow or a class derived from TFrameWindow.

Window Styles

The Window Styles list box lists the properties for the frame window. This option is only applicable if the Base Class is TWindow or a class derived from TWindow.


Window Styles dialog box

Use the Window Styles dialog box to set the properties for a new window class.

Window Title

Use Window Title to specify the name to be displayed as the caption of the application's main window.

Background Color

The Background Color display box shows the current background color of the window.

Set Background Color

Use the Set Background Color button to set the background color of the window. Pressing this button displays the Color dialog box. Use the Background Color display box to see the current background color.

Caption

Turn on the Caption radio button to create a single, thin border and a title bar where a caption can be displayed.

Border

Turn on the Border option to get a single, thin border without a caption for the application's main window.

Maximize Box

Turn on the Maximize Box option to add a maximize button to the right side of the application's main window caption.

Minimize Box

Turn on the Minimize Box option to add a minimize button to the right side of the application's main window caption.

Vertical Scroll

Turn on the Vertical Scroll option to add a vertical scroll bar to the right side of the application's main window.

Horizontal Scroll

Turn on the Horizontal Scroll option to add a horizontal scroll bar to the bottom of the application's main window.

System Menu

Turn on the System Menu option to add a system menu button on the left side of the application's main window caption.

Visible

Turn on the Visible option to make the application's main window visible. This is the default setting. When this option is off, the WS_VISIBLE style is changed to NOT WS_VISIBLE.

Disabled

Turn on the Disabled option to disable the application's main window.

Thick Frame

Turn on the Thick Frame option to place a double border around the application's main window. If this option if off, users cannot resize the main window.

Clip Siblings

Turn on the Clip Siblings option to protect the siblings of the application's main window. Painting is restricted to that window.

Clip Children

Turn on the Clip Children option to protect child windows from being repainted by the application's main window.


Document Types dialog box

Use the Document Types dialog box to define which document and view pairs to use in your application.

View Class

Use View Class to name the class of the view. The values possible include any classes derived from TView.

Document Class

Use Document Class to name the class of the document. The values possible include any classes derived from TDocument.

Styles button

Press the Styles button to display the Document Styles dialog box, which lets you set the styles of the Document/View pair.

Description

Use Description to describe the class of files associated with the Files of Type List in Windows common file dialog boxes. The default value is "All Files (*.*)". This value serves as the description for the value entered in Filters.

Filters

Use Filters to list wildcard file specifications (separated by semicolons) for the file names you want the application to recognize. This value is passed to Windows common file dialog boxes to filter files displayed in the list box of those dialog boxes. The default value is "*.*". The values entered in Description serves as the explanation of this value.

Default Extension

Use Default Extension to specify the default filename extension. This value is passed to Windows common file dialog boxes and added to filenames without extensions. The default value is "TXT".

Add button

Use the Add button to create a new document/view pair based on the values you entered previously. This pair is added to the Existing Document/View Types list.

Existing Document/View Types

Existing Document/View Types lists the current set of document/view pairs available for your application.

Delete button

Use the Delete button to remove the document/view pair currently selected in the Existing Document/View Types list.


Document Styles dialog box

Use the Document Styles dialog box to define the document style for the document/view pair defined in the Document Types dialog box.

dtAutoDelete	Deletes the document when the last view is deleted.

dtNoAutoView	Does not automatically create the default view type.

dtSingleView	Provides only a single view for each document.

dtAutoOpen	Opens a document upon creation

dtUpdateDir	Updates the directory with the dialog directory.

dtHidden	Hides the template from the user's selection.

dtSelected	Indicates the last selected template.

dtReadOnly	Checks the Read Only check box when the dialog is created. (OFN_READONLY)

dtOverwritePrompt	When the Save As dialog is displayed, asks the users if its okay to overwrite the file. (OFN_OVERWRITEPROMPT)

dtHideReadOnly	Hides the Read Only check box. (OFN_HIDEREADONLY)

dtPathMustExist	Lets the user enter only existing file names in the File Name entry field. If an invalid file name is entered, causes a warning message to be displayed. (OFN_PATHMUSTEXIST)

dtFileMustExist	Lets the user enter only existing file names in the File Name entry field. If an invalid file name is entered, causes a warning message to be displayed. (OFN_FILEMUSTEXIST)

dtCreatePrompt	Prompts the user before creating a document that does not exist. (OFN_CREATEPROMPT)

dtNoReadOnly	Returns the specified as writeable. (OFN_NOREADONLYRETURN)


Managing Projects

See Also

Borland C++ Project offers several ways to manage project components.

Project menu	Through the Project Menu, you can Create, open, close, add a new target, make, build, compile, or generate a makefile of your projects.

Project Hierarchy	The Project hierarchy is displayed with the View|Project command and offers a collapsable / expandable, hierarchical display of the components (shown as nodes) in your project.

By manipulating the various node types and their settings, you can handle most project details, including review and make changes to settings at a project or node level, assign tools to nodes, add target (output file) nodes, or adjust dependencies by moving nodes within the project.

The Project Hierarchy also lets you add support nodes to your project. By using Source pools in your project, you can share common nodes, share Style Sheets between targets, or invoke a tool ... just at the right time!

View Options Hierarchy	The View Options Hierarchy command (Project Hierarchy SpeedMenu) opens a duel page dialog box. On one side is your project, on the other a list of node options, including any Style Sheets. Using View Options Hierarchy, you can make detailed or wide-sweeping changes to option settings.

Node attributes	The Edit Node Attributes command (Project Hierarchy SpeedMenu) gives you another way to control how each project node is handled at compile time, including what Style Sheet or what translator or tool is associated with each node.

Options|Tools	Use Options|Tools to install, delete or modify tools that you can use from the Tools menu or associate directly with a node in your project.

TargetExpert	The TargetExpert is displayed when you create a project or a new target node. When you define a target type, TargetExpert makes available the appropriate platform, model and libraries choices based on the target type selected.


See Also

Project Hierarchy Reference


Project Hierarchy

See Also	How to:

Each component of your project is graphically represented as a node on a "live" project tree. The project hierarchy supports incremental search, so you can find a specific node just by typing the first part of a node's name. When you select a node (double-click it) something happens. Just what happens depends upon which attributes are associated with the node you selected. For example, a viewer could be invoked if the node can be edited, or a translator might perform an action on the node.

The Project hierarchy supports drag and drop. Just select files from your File Manager, drag and drop them into place. Files added this way become children of the node on which they're dropped. By default, files are assigned relative path information, but you can move files into your project without relative path information.

Node Information

Project View options let you choose what information is displayed next to each node. You can display all or a subset of these choices: build translator, code size, data size, description, location, name, number of lines, node type, Style Sheet, output, run-time nodes, project node.

Colors in the Project hierarchy also gives information about the types of node and they originated.

Option Settings and Tools

Nodes are displayed hierarchically in the project tree. Options set for a parent node are inherited by their child node(s), unless you assign a different Style Sheet to a child node. Parent nodes are always the result of a translation of child node(s). Some options can also be set locally - specific for an individual node.

Along with Style Sheets and local option overrides, you can associate tools with nodes. Tools might be standalone programs (like GREP, Turbo Debugger, or an alternate editor), or they can be translators that are used for each node in a project. It can also be useful to add Source Pools that serve to activate a tool during the build process.


See Also

Project Hierarchy Reference

Managing Projects

View Options Hierarchy


How to: Use the Project Hierarchy

Project Hierarchy

Below is a list of common tasks you will perform in the Project Hierarchy. To view a complete list of editing tasks, select Project Hierarchy Reference.

Editing:

Add a Node	Move Cursor to Bottom
Change the Project View	Move Cursor to Top
Collapse a Node	Move Node(s) Up or Down
Collapse the Project	Open the SpeedMenu
Copy a Node	Page Through the Project
Default Action for Node	Promote a Node
Delete a Node	Reference Copy a Node
Demote a Node	Scroll Right or Left
Expand a Node	Search for a Node
Expand the Project	Select Contiguous Nodes
Find a Node	Select Non-Contiguous Nodes
	Select One Node
Management Tasks:

Add Targets	Set Node Attributes
Build Part of a Project	Share Style Sheets
Control Build Attributes for Nodes	Use Reference Copies of Nodes
Convert Old Projects	Use Source Pools
Create A Multiple Target Project	Use Style Sheets
Set Local Options	Use the TargetExpert to Create Target Types
	View Option Settings


Project Hierarchy Reference

See Also

The Project hierarchy diagram can be traversed with the mouse or the keyboard.

Note: You can also select a node by typing the node name.

Task	Keyboard	Mouse

Add Node	Insert

Collapse Hierarchy	- (hyphen)

Collapse node	Minus	Left Click

Collapse/Expand node	Spacebar

Copy Node	Ctrl+Left Click Drag

Default action for node	Enter	Double Click

Delete Node	Delete

Demote a node	Alt+RightArrow	Left Click Drag

End node search	Esc

Expand Hierarchy	* (asterisk)

Expand node	Plus	Left Click

Find a node	Incremental search (start typing)

Move down in project	DownArrow	Scroll Bar

Move node down	Alt+DownArrow	Left Click Drag

Move node up	Alt+UpArrow	Left Click Drag

Move to bottom of hierarchy	End	Scroll Bar

Move to top of hierarchy	Home	Scroll Bar

Move up in project	UpArrow	Scroll Bar

Open SpeedMenu	Alt+F10	Right Click

Page down	PgDn	Scroll Bar

Page up	PgUp	Scroll Bar

Promote a node	Alt+LeftArrow

Reference Copy Node	Alt+Left Click Drag

Scroll left	LeftArrow	Scroll Bar

Scroll right	RightArrow	Scroll Bar

Select a node*	Up/DownArrow	Left Click

Select Contiguous nodes	Shift UpArrow	Shift Left Click

Select Non-Contiguous nodes	Ctrl Left Click


See Also

Keyboard

Managing Projects

Project Hierarchy


Source Pools

See Also

What are Source Pools?

An X is displayed to the left of a Source Pool in the project tree. Source Pools are a collection of nodes in the project that are typically marked "exclude from parent" and not built. Use Source Pools to share common source or header files between targets (great when multi-targeting). Use Source Pools to share Style Sheets between nodes and update it in one place. You can also use Source Pools to invoke tools at strategic points in your build process.

You can reference copy Source Pools to use in your project. When a Source Pool is referenced by a target node, the nodes in the Source Pool take on the options and target attributes of the target. Think of a source pool as an alias for child node(s). Any action taken with the source pool node can be considered to have occured to each child node.

Note:	Open the sample project SRCPOOL.IDE in EXAMPLES\IDE\SRCPOOL directory. This project file includes a text file that describes how the Source Pool is used in that example.

Creating Source Pools

1.	Choose Project|New Target

2.	Enter the name for the Source Pool

3.	Select Source Pool from the Type list.

Source Pools Uses

Share Source - useful for maintaining files used by multiple targets. For example, two targets, one a 16-bit and one a 32-bit application can use a single set of source nodes.

When building two versions of a library, avoid having elements rebuilt (if files are out of sync) by keeping intermediate and output files in separate directories.

Share Headers - useful if you have several header files that you need to include throughout your project. Add a new header file to the Source Pool and the reference copies are automatically updated.

Share Option Settings - Useful with multiple targets. Also, try creating small Style Sheets that you can plug in and out of your projects. For example, multiple targets can reference copy a Source Pool that uses a desired Style Sheet. Then, make changes (like compiling with or without debug info) in one place. Or, break up option settings into small easy to handle Style Sheets (e.g., one for compiler options, one for librarian options, one for linker options, one for debug info, etc.). Use Source Pools with these smaller Style Sheets, and you can pop settings changes in an out of your project by commenting in or out the appropriate Source Pool.

Use Tools - Activate a tool at a specified point in the build process. For example, create a tool to open a DOS shell and use transfer macros (e.g., remove debug info, copy files to a delivery directory, link in libraries, point to where header files can be found, or create import libs). Associate tools with a Source Pool and they can be called automatically.


See Also

Managing Projects

Project Hierarchy


Local Options

See Also

Inherited options or Style Sheet options can be overridden at the node level. Set options for an individual node by selecting Edit Local Options on the Project Hierarchy SpeedMenu. or by selecting Edit Local Options from the Edit Local Options on the Edit Window SpeedMenu when no project is loaded. The local options dialog box displays where the node is located in the project hierarchy and allows you to set options for that node.

Once options have been set, they become local overrides associated with the node. Local Override are useful when you use a Style Sheet (perhaps inherited from a parent node).

To Set Local Options:

1.	Select (highlight) a node for which you want to override options.

2.	Choose Edit local options from the SpeedMenu. The Project Options dialog box is displayed.

3.	Select the option you want to override. Selecting an option automatically activates the Local Override box. The Local Override box is grayed if no option is selected. You can tab over to an option if you want to see if the Local Override box is checked,but not change the setting for that option. You must select each individual option to see if it is overridden. If you find yourself overriding more than one or two options, you might want to create a separate Style Sheet instead of using Local Override. Any settings you make take place immediately.

To Undo an Override

1.	Select (highlight) a node for which you want to override options.

2.	Choose Edit local options from the SpeedMenu. The Project Options dialog box is displayed.

3.	Select the option and uncheck the Local Override box.


Setting Options Locally

A Local Options dialog box contains the same options as the Options|Project dialog box, except that changes you make here affect only a selected node. This is also where Build Attributes for an individual node are set.

A Local Options dialog box displays when you:

1.	Choose Edit local options from the Project Hierarchy SpeedMenu,

2.	Choose View Options Hierarchy from the Edit Window SpeedMenu, when no project is loaded.

3.	Select a node, choose View Options Hierarchy from the Project Hierarchy SpeedMenu, then double-click in the Components list on the option you want to override.

To Override an Option:

Select the option you want to override. Selecting an option automatically activates the Local Override box. The Local Override box is grayed if no option is selected. You can tab over to an option if you want to see if the Local Override box is checked,but not change the setting for that option. You must select each individual option to see if it is overridden. If you find yourself overriding more than one or two options, you might want to create a separate Style Sheet instead of using Local Override. Any settings you make take place immediately.

Choose...	If You Want To...

OK	Accept changes to all options and close return to the Project Hierarchy.

Undo Page	Restore the current screen of options to the settings present when you selected the Options Settings dialog box.

Cancel	Restore all options to the settings present when you opened the Options Settings dialog box. (Same as close box.)

Help	See context-sensitive online Help. The Help button gives a summary for the current screen of options. For Help on an individual option, select (highlight) an option and press F1.

To Undo an Override

To undo an override, select the option and uncheck the Local Override box.

To Override Multiple Options

Options dialog boxes use a dual window format. A list of topics is displayed in the left window.

Topics in the left window expand to display sub-topics. Select a sub-topic and the options associated with that sub-topic are display in the right window.

When you first open an Options dialog box, the list of topics is collapsed. This is indicated with a + sign beside any topic which can be expanded. Highlight a topic to display a brief summary of the types of options available under that topic.

To expand or collapse a topic, double-click on it or highlight it and press Enter or use the commands on the Options dialog box SpeedMenu. When expanded, the + changes to a -, and a list of sub-topics is displayed under the topic.

To override multiple options, choose each sub-topic and options display on the right. You can change settings on one or several pages, without leaving the Options dialog box. Options are initially set to their default values.


See Also

Managing Projects

Project Hierarchy


Node Types

The Project Manger uses the following types of nodes to distinguish the different files in your project:

Node Type	Description

Project	At the top of the project tree, it represents the entire project. All the files used to build that project are under the project node (similar to a symbolic target in a makefile). By default, the project node is not displayed in the Project Tree. Since it can sometimes be helpful to see the "total" picture, display the project node with Options|Environment|Project View.

Target	A file created when its dependent nodes are built. A target can be one of a variety of target types, but is usually an .EXE or .DLL that you are creating from source code. A project can contain many target nodes. For example, in a single project, you might build an executable file and two separate .DLL files, making three targets.

Source	A file used to build a target. Files such as .C, .CPP, and .RC are files that can be associated with source nodes.

Run-time	A file used during the linking stage of your project, such as startup code and .LIB files.  By default, run-time nodes are not displayed in the Project Tree. To display them, choose Options|Environment|Project View.


Node Attributes

See Also

Edit Node Attributes on the Project Hierarchy SpeedMenu displays the Node Attributes dialog box. These are the Node Attributes options:

Name

Enter a name for the node.

Description

Enter a comment that explains the node.

Style Sheet

Select a Style Sheet for the node. Style Sheets are predefined sets of options that can be associated with a node. If <<None>> is specified, the project hierarchy uses the parent options, plus any local overrides on nodes up the hierarchy.

Note:	If you need to create or edit an existing Style Sheet, click the Styles button and access the Style Sheets dialog box..

Translator

Select a translator to associate with the node. A translator is any program that changes (translates) one file type to another. For example, TLINK is a translator that uses .OBJ files to produce an .EXE file.

Node Type

Some node-types are assigned by the system such as [AppExpert] and [SourcePool] but most node-types are a reflection of a file extension: [.cpp], [.exe], [.def], etc. Node types have default translators. Change the Node type by selecting from the drop down list of available types. EXE, .DLL, and source pool nodes can not be changed. You can change which viewers and translators are available through Options|Tools in the 'Advanced' dialog (see 'Applies to', 'Translate from' and 'to' fields).

Note:	You can also edit an individual node name and type through the Project Hierarchy's SpeedMenu 'Edit node attributes' command.

Exclude Debug Information

Select Exclude Debug Information to prevent debug information from being generated for this node.

Overlay This Module

Select Overlay This Module to have the appropriate code generated so that this module can be overlaid. This option is only available if you have chosen DOS Overlay as the Target Type in the TargetExpert.

Styles Button

Press the Styles button to access the Style Sheet dialog box, where you can create, view or customize Style Sheets.

Tools Button

Press the Tools button to access the Tool Options dialog box, where you can view and customize tools for use as node translators/viewers.


See Also

Managing Projects

Project Hierarchy


Style Sheets

See Also

A Style Sheet is a group of option settings. Option settings control how target nodes in your project are built. You can attach Style Sheets to entire projects or to individual nodes in a project. You can attach one or more Style Sheets to your entire project or assign one or more Style Sheets to individual nodes in your project.

When you initially create a project, it inherits the settings of the default project when you choose Project|New Project. The new project is given the settings of the Default Style Sheet. If some components in your project require different settings, you can attach different Style Sheets to those nodes or use Local Options to override the default project Style Sheet settings.

Note:	STYLESHT.IDE in the directory \EXAMPLES\IDE\STYLESHT illustrates the use of Style Sheets and contains a text file that explains the use of Style Sheets. This file uses Style Sheets for each of the targets (two versions of WHELLO).

The Available Style Sheets List

Choose Options|Style Sheets on the main menu (or click the Styles button on the Edit Node Attributes dialog box) to access the Style Sheets dialog box. where you create, compose, copy, edit, rename, or delete from the list of Style Sheets that are available for your project.

The list of available Style Sheets is associated just with the current project. If you create a Style Sheet for one project, then open a second project, the new Style Sheet will not be included in the second project's list of available Style Sheets. However, Sharing Style Sheets between projects is possible, allowing styles and tools from the current project to be inherited by new projects.

At Build Time

When a node is built:

The project hierarchy uses the node's Style Sheet and any Local Overrides

If a node does not have a Style Sheet, the project hierarchy uses the Style Sheet of the parent.

If the parent node does not use a Style Sheet, the project hierarchy looks at the next parent, continuing up the hierarchy until it reaches the project node.

Changing Default Project Options

To modify default project options, choose Options|Project. This displays the Project Options dialog box, where you set options for your entire project.

You can also change default settings by choosing Options|Style Sheets on the main menu (or click the Styles button on the Edit Node Attributes dialog box). Select the Default Project Options Style Sheet from the list of available Style Sheets.

Attaching Style Sheets to Nodes

Sometimes different nodes in a project need to be built with option settings that are different than those in the project Style Sheet. For example, you might want to compile .C files with one set of options but .CPP files with another. Or, you might want to build one target with 16-bit options and another with 32-bit options.

To attach an existing Style Sheet to a node:

1.	Select the node and right-click.

2.	Choose Edit node attributes.

3.	Select a Style Sheet from the combo box.

4.	Click OK.

Note:	To display the name of any attached Style Sheet next to nodes in the project tree, choose Options|Environment Project View and select Style Sheet.


See Also

Options|Project

Managing Projects

Project Hierarchy

Sharing Style Sheets

Style Sheet dialog box


Sharing Style Sheets

See Also

There are two ways to share Style Sheet between projects.

Inheriting Style Sheet Settings

When you create a custom Style Sheet, that Style Sheet remains with the project for which it was created; it doesn't get added to the list of predefined Style Sheets. However, if you want a new project to use one of your custom Style Sheets, you can do so by letting a new project inherit settings from another project.

To pass Style Sheets (and user defined tools) from an existing project to a new project, edit your BCW.INI file to make sure it includes the following line:

[project] inherit=1

This allows Style Sheets to be inherited from an open project.

Next, open a project that contains the settings you want to pass to a new project. Choose Project|New Project to create a new project. At creation, the new project inherits the option settings and user defined tools of the project that was open.

Editing the Project Description Language files

You can also share Style Sheets across projects by editing the Project Description Language files (.PDL) associated with your projects.

Note:	Be careful if you choose to edit .PDL files. If a .PDL file is corrupted, the project hierarchy will not be able to read it. You may want to make a backup copy of the .PDL file before you begin making changes.

A .PDL file is a text file that contains information about the Style Sheets and Tools used in your project. Style Sheet and Tools information can be copied from one .PDL file to another, allowing you to quickly modify Style Sheet and tools for your projects. .

Note:	.PDL files are only generated when SaveAsText=1 and ReadAsText=1 entries are present in the Project section of your BCW.INI file.

To edit the .PDL file:

1.	Open the .PDL file containing the Style Sheet you want to share. You can open the .PDL file using any text editor.

2.	Search for Subsystem = Style Sheet. Then, scan for the desired Style Sheet by name. For example, if you created a Style Sheet called MYSTYLE, you'll see a section in the .PDL file that starts { StyleSheet = "MYSTYLE".

3.	Copy all the text from the beginning to the ending brace. You can copy more than one Style Sheet.

To share a user-defined tool, copy the section that reads Subsystem=<tool>.

4.	Open the .PDL file that is going to use the copied Style Sheet.

5.	Find the section for Style Sheets, then paste the copied text to the end of the existing Style Sheet list.

6.	Save the .PDL file that received the copied Style Sheet. When you open a project file, the project hierarchy checks the date of the .PDL file with the same name as the .IDE file. If the .PDL file is newer than the .IDE file, the contents of the .PDL file is added to the .IDE file.


See Also

Managing Projects

Project Hierarchy

Style Sheets Dialog Box

Style Sheets


TargetExpert

See Also

The Borland C++ TargetExpert lets you specify a target type for a node in the active project or the program loaded in the active Edit Window. For example, a target can be a 16-bit Windows DLL that you want to change to be 32-bit Windows DLL. You can change attributes for Standard target types. A Source Pool or an AppExpert target type can not be changed.

To change Target attributes, select the node, then choose TargetExpert from the Project Hierarchy SpeedMenu or select TargetExpert from the Edit Window SpeedMenu when no project is loaded.

Note:	You cannot change target attributes for source pools.

New targets are created with a default project skeleton. To change the default project skeleton for a specific project type, use Advanced Options on the Project|New Project dialog box.

The options on the TargetExpert dialog box are:

Target Type - type of target (output) file

Standard Libraries - which standard libraries or defines to use in your application

Platform - the desired platform for your project

Target Model - the memory model for your program

Floating Point - (DOS applications)

Emulation - (DOS applications)

No Math Support - to link in the DOS math librarian

Alternate Startup - (DOS applications)


See Also

Advanced Options Button

Managing Projects

Project Hierarchy


View Options Hierarchy

See Also

The Project Hierarchy SpeedMenu. View Options Hierarchy command displays The Options Hierarchy dialog box where you browse through the option settings for your project, nodes by node.

Project Options:

A node tree on the left offers a graphical representation of your project. Browse through the tree and select a node to view or change the option settings.

Outliner Symbols

+	indicates a collapsed node or branch (sublevel catagories not displayed)

- 	indicates a fully expanded node or branch

Options List

The Options list shows each node in square brackets, followed by the name of that node's Style Sheet. It also lists any options that are overridden for that node. View Options Hierarchy lets you see what options are sent to dependent nodes.

To change an option for the project at a global level, highlight an option within the Default Project Options section and double-click. You can also change global options by double clicking the Project node.

Note:	By default, the Project node is not displayed in the project hierarchy. To display the project node, choose Show Project Node in the Options|Environment|Project View.

Edit button

Press the Edit button to edit option settings for the currently selected node. Local Options are displayed. You can also double-click on a specific option to display the Local Options page that contains that option, where you can make changes for the selected node.


See Also

Managing Projects

Project Hierarchy


Edit button (Options Hierarchy)

Press the Edit button to edit option settings for the currently selected node. Local Options are displayed. You can also double-click on a specific option to display the Local Options page that contains that option.

If the option belongs to a Style Sheet, you are editing the Style Sheet. If the option is overridden at the node level, you are editing the Local Options for that selected node.


Reference Copy Nodes

See Also

When you copy a node by reference, you are creating a pointer to a node in another location in the project. A reference node is not distinct from the original. For that reason, reference copies of nodes appear in a lighter font in the Project Hierarchy.

Node Attributes and Local Options

Node attributes and local options are initially the same for a reference copy as they are for the original. You can edit node attributes or local options in the reference copy without affecting the original. If you edit the original, all reference copies are updated.

Note:	If you delete an original node, all reference copies of that node are deleted. You cannot undo such a deletion.

Dependency Nodes

Whether a reference copy was made of a source pool or of a normal node, it initially contains the same dependency nodes as the original.

Action	Original	Referency Copy
Deleting	If a node is deleted from the original, it is also deleted from the reference copy.	Dependency nodes can be deleted from the reference copy. Deleting a node from a reference copy does not affect the original.
Adding	If a nodes is added to the original, it is added to the reference copy.	You can not add a node to a reference copy.
Moving	If a node is moved out of the original, it is deleted from the reference copy.	An entire reference copy can be moved by moving the top-most node. A dependency node in a reference copy can not be moved.


See Also

Managing Projects

Project Hierarchy


Creating a Multiple-Target Project

See Also

Creating multi-target projects is very similar to creating projects with one target:

1.	Create a project using Project|New Project

2.	Choose Project|New Target to add a second target to your application.

3.	Type a name for the second target and choose a target type (Standard is the default). Choose OK. The project hierarchy adds a new target to your project just as it does for the first target in a project.

To view a sample project with two targets, open the file MULTITRG.IDE in the EXAMPLES\IDE\MULTITRG directory. This project file builds two versions of the WHELLO program--one that is 16-bit and one that is 32-bit. The project file contains a text file that describes how to use two targets or more in one project file.

With more than one target in a project, you can choose to build a single target, multiple targets, or the whole project.


See Also

Managing Projects

Project Hierarchy


Converting Old Projects

See Also

The project hierarchy can load and use projects from previous versions of Borland C++. Choose Project|Open project, then type the name of the old project file. You can also change the search attributes from *.IDE to *.PRJ to list the old 3.0 and 3.1 projects.

The project hierarchy converts the old project to a new one. Be sure to save the new project if you want to keep using it with this version of Borland C++. To save the project, choose Options|Save. Make sure Project is checked, then click OK. The new project is saved with the old name and the new .IDE extension.


See Also

Managing Projects

Project Hierarchy


Building Part Of a Project

See Also

You can build part of a project three ways:

Select a node and use Build node from the SpeedMenu to build it and all of its dependents.

Use Make node from the SpeedMenu, to build only the out-of-date nodes.

Translate a single node.

Build a Node and Its Dependents

1.	Choose the node you want to build.

2.	Right-click the node and choose Build node from the SpeedMenu.

All the dependent nodes are built regardless of whether they're out-of-date.

Build a Project Using Make Node

1.	Choose the node you want to build.

2.	Right-click the node and choose Make node from the SpeedMenu.

Make node builds only the nodes that are not current.

Translate the Individual Node:

Suppose you're working on a file and you just want to see if it will compile (you don't want to compile the entire project).

1.	Select the node you want to translate.

2.	Either

a.	Choose Project|Compile from the main menu.

b.	Open the SpeedMenu and choose a translation command. Default translation commands are provided for many nodes. For example, if you've selected a .CPP file, the SpeedMenu for that node contains a C++ Compile command, which compiles only the selected .CPP node.

c.	Use your own translator. Add translators to the Tools Menu or to the SpeedMenu with the Options|Tools advanced editing feature.

Note:	Project|Compile translates the current node if the Project Hierarchy is selected. If an editor window is selected, Project|Compile translates the text in the editor.


See Also

Managing Projects

Project Hierarchy


Deleting Targets

See Also

To Delete a Target:

1.	Select the target and open the SpeedMenu..

2.	Choose Delete node.

3.	The project hierarchy asks if you're sure you want to delete the target. Click OK.

Note:	Use care when deleting target nodes - you cannot undo the deletion.


See Also

Managing Projects

Project Hierarchy


Delete Node

1.	Select the node and open the SpeedMenu..

2.	Choose Delete node.

Note:	Use care when deleting target nodes - you cannot undo the deletion.

Note:	If you delete an original node, all reference copies of that node are also deleted. You cannot undo this deletion.


Add Node

Select Add Node on the Project Hierarchy SpeedMenu to add a node below the selected node.

You can also add a node with the INSERT key.

Note:	New projects are created with a default project skeleton. To change the default project skeleton for a specific project type, use the Advanced Options button on the Project|New Project dialog box.


Make Node (Project Window SpeedMenu)
Make Node (Project Hierarchy SpeedMenu)

Choose Make Node on the Project Hierarchy SpeedMenu to MAKE all targets. Make Node checks file dates and times to see if they have been updated. If so, the project hierarchy rebuilds those files, then moves up the project tree and checks the next nodes' file dates and times. The project manger checks all the nodes in a project and builds all of the out-of-date files.

The .EXE file name is fully spelled out in the Project Hierarchy for target names. If no project is loaded, the .EXE name is derived from the Editor Window.

The Make Node command rebuilds only the files that are not current.


Build Node (Project Window SpeedMenu)
Build Node (Project Hierarchy SpeedMenu)

The Build Node command on the Project Hierarchy SpeedMenu rebuilds all the files in the current project, regardless of whether they are out of date.

This option is similar to Make Node on the SpeedMenu, except that Build Node rebuilds all the files in the project whether or not they are current.

Build Node builds the project using the Default Project Options Style Sheet unless you have attached a different Style Sheet to a node or overridden the options locally.

For example, if you have a project with an .EXE target that is dependent on a .CPP file, and the .CPP is dependent on two .H files, the project hierarchy checks the dependencies for the two .H files first, then it compiles the .CPP file to an .OBJ, and finally, the project uses the new .OBJ file to link the .EXE.

Build Node:

1.	Deletes the appropriate precompiled header (.CSM) file, if it exists.

2.	Deletes any cached autodependency information in the project.

3.	Builds the node / executes the translator.

If you abort a Build Node command by pressing Esc or choosing Cancel, or if you get errors that stop the build, you must explicitly select the nodes to be rebuilt.


Compile (Project Window SpeedMenu)
Compile (Project Hierarchy SpeedMenu)

When you select Compile on the Project Hierarchy SpeedMenu., the Project hierarchy translates the selected nodes (not the project itself).

Note:	Additional ways to compile in the Project Hierarchy are to double click on the node or select Compile from the Project Menu.

A Compile Status information box displays the compilation progress and results. Choose OK when compilation is complete.

If any errors occurred, the Message window becomes active and displays and highlights the first error or warning.


Adding Files Without Relative Path Information

Because the Project Hierarchy supports drag and drop, you can copy files right from a desktop file manager. Relative path information is included when files are copied. If sources might move or if you have moved the IDE, relative path information could cause errors. Here is how to add files to your project without the presence of relative path information.

1.	Make sure that Absolute (Options|Project|Make|New Node Path) is turned off (this is the default setting).

2.	Right click on the node under which the added files will become children once they are dropped.

3.	Choose Add Node from the Project Hierarchy Speed Menu.

4.	Browse and highlight the file(s) you wish to add. (Hold down the Ctrl Key to select non-contiguous files.)

5.	After highlighting the desired files, shift focus to the input box and capture to the Clipboard (Ctrl C).

6.	Browse back to the project file location.

7.	Shift focus to the input box, paste from the Clipboard (Ctrl V or Shift Insert) and choose OK.

Files added to the project by this method do not have relative path information.


Application (.exe)

Application (.exe) - generates an Application project and creates the current default project skeleton for that target type.


Dynamic Library (.dll)

Dynamic Library (.dll) - generates a Dynamic Library project and creates the current default project skeleton for that target type.


EasyWin (.exe)

EasyWin (.exe) - generates an .EasyWin project and creates the current default project skeleton for that target type. An EasyWin project is a character-mode (DOS) application that runs under Windows.


Static Library (.lib)

Static Library (for .exe) [.lib] - generates a Static Library file for use in an executable.

Static Library (for .dll) [.lib] - generates a Static Library file for use in a dynamic link library.


Import Library (.lib)

Import Library (.lib) - generates an Import Library project.


Windows Help (.hpj)

Windows Help (.hpj) - generates a Windows Help file that is usually accessed from a Windows application (.exe).


Select One Node

Left Click on node

Type node name and selection bar moves incrementally to nearest match

ESC key exits incremental search mode

Up/Down Arrow move selection bar up or down (does not wrap)


Find (Search for) a Node

Left Click on a node

Type node name and selection bar moves incrementally to nearest match

ESC key exits incremental search mode

Up/Down Arrow move selection bar up or down (does not wrap)


Select Contiguous Nodes

First, select a node (Left Click, type name, or use Up/Down Arrow). Then,

Shift Left Click to select nodes between first node and current mouse cursor

Shift + Up/Down Arrow to select additional nodes


Select Non-Contiguous Nodes

1.	Select a node (Left Click, type name, or use Up/Down Arrow)

2.	Ctrl + Left Click each additional node


Move Node(s) Up or Down

First, select a node(s). Then,

Left Click Drag to move node(s). Nodes moved with the mouse become a child of the drop target

Alt + Up/Down Arrow move node(s) one line up or down

Note:	Non-contiguous nodes become contiguous nodes when moved.


Promote a Node

1.	Select a node

2.	Alt + Left Arrow moves node up through levels of dependencies


Demote a Node

1.	Select a node

2.	Alt + Right Arrow moves node down through levels of dependencies

Note:	You can also demote a node by moving it with the mouse. Nodes moved with the mouse become a child of the drop target.


Expand a Node

Left Click on folder icon marked + to expand node

Plus expands a node marked +

Spacebar expands a node marked +


Collapse a Node

Left Click on folder icon marked - to collapse node

Minus collapses a node marked -

Spacebar collapses a node marked -


Add a Node

Insert adds a node below the selected node

Select Add Node on the SpeedMenu

Choose the files you want associated with nodes. If the files you type do not exist in the current directory, the IDE creates them.

Note:	Do NOT use Insert to add target nodes. To add a target node, use Project|New Target. This opens the New Target dialog box, where you can select target type, platform, model, and libraries.


Change the Project View

Use Options|Environment|Project View to set options that specify what types of nodes appear in the Project Hierarchy and what information appears beside each node.

The options to choose from are Build Translator, Code Size, Data Size, Description, Location, Name, Number of Lines, Node Type, Style Sheet, Output, Show Runtime Nodes, and Show Project Node.


Delete a Node

Delete deletes the selected node

Select Delete Node on the SpeedMenu

Note:	Use care when deleting target nodes. You cannot undo the deletion.

Note:	Use care when deleting a node that has been reference-copied. All reference copies of that node are also deleted. You cannot undo the deletion.


Expand the Hierarchy (Project Tree)

The * key expands project tree.


Collapse the Hierarchy (Project Tree)

The - key collapses project tree.


Scroll Hierarchy (Project Tree) Left or Right

Left/Right Arrow scrolls left or right in the Hierarchy (Project Tree).

Scroll Bar scrolls left or right in the Hierarchy.


Move Cursor to Top of Hierarchy (Project Tree)

Home moves the cursor to the top of the Hierarchy (Project Tree).

Scroll Bar moves you up or down through the Hierarchy.


Move Cursor to Bottom of Hierarchy (Project Tree)

End moves the cursor to the top of the Hierarchy (Project Tree).

Scroll Bar moves you up or down through the Hierarchy.


Page Through the Hierarchy (Project Tree)

Page Up/Page Down pages up or down through the Hierarchy (Project Tree).

Scroll Bar moves you up or down through the Hierarchy.


Copy a Node

Control + Left Click Drag to make a copy of the selected node and make it a child of the drop target.

This creates an identical, but separate copy of the node in the location you specify. Nodes that have been copied inherit all attributes from the original node and you can modify attributes for either the original or the copy.


Reference Copy a Node

Alt + Left Click Drag to make a reference copy of the selected node and make it a child of the drop target. Reference copies appear in a lighter font to identify them in the project tree.

A reference copy acts as a pointer to a node located elsewhere in the project. A reference copy is not a unique node. If you modify the original node (attributes or dependants), the reference copy is also modified. If you delete an original node, all reference copies of that node are also deleted. You cannot undo this deletion.


Open SpeedMenu

Right Click opens the SpeedMenu for the node at the mouse cursor

Alt + F10 opens the SpeedMenu for the selected node


Default Action For Node

Double Click performs the default action of a selected node.

Enter performs the default action of a selected node.

To determine a nodes default action, select the node. Right click to access the SpeedMenu. Choose the View command. The first "viewer" listed is the default action for the selected node.


Nodes

Nodes are the visual representation of project components. With the exception of source pools and the IDE node, each node in the project tree represents a stage of development, a set of options, and a file.


Translator

A translator can be any program that changes (translates) one file type to another. For example, the compiler is a translator that uses .C and .CPP files to create .OBJs, and TLINK is a translator that uses .OBJ files to produce an .EXE file.


Viewer

A viewer is a tool that lets you see the contents of a node. For example, an editor is a viewer that lets you examine the code in a .CPP file. On the local menu for a .CPP node, you'll see the Text Edit command. The default editor for the Text Edit view is the IDE editor.

Other node types have other viewers available. For example, Resource Workshop can view .RC files. You can't view an .EXE node in a text editor, but you can choose to view it using the integrated debugger, Turbo Debugger for Windows, the Browser, or even as an executing program.


Project Hierarchy Colors

Blue	nodes you add.

White	target nodes (these have an icon in the left margin).

Yellow	nodes added by the compiler, AppExpert, ClassExpert, or TargetExpert.


Style Sheets

A Style Sheet is a group of option settings. Option settings control how targets in your project are built. You can attach one or more Style Sheets to your entire project or assign one or more Style Sheets to individual nodes in your project.


Target Nodes

A file created when its dependent nodes are built. A target is usually an .EXE or .DLL that you are creating from source code. A project can contain many target nodes. For example, in a single project, you might build an executable file and two separate .DLL files, making three targets.


Source Pools

Source Pools are a collection of nodes in the project that are typically marked "exclude from parent" and not built. Use Source Pools to share common source or header files between targets (great when multi-targeting). Use Source Pools to share Style Sheets between nodes and update it in one place. You can also use Source Pools to invoke tools at strategic points in your build process.


Tools

Tools are programs and utilities that can be run without leaving the IDE. Tools can be installed on the Tool Menu, or associated with project nodes. They can be standalone programs (like GREP, Turbo Debugger, or an alternate editor). Tools can be used to build nodes in the project. They can be used to view node contents or carry out an action at a specific point in your program compilation process. You can specify program arguments when you create a tool, or opt to be prompted for them at run-time.


16-bit Compiler
Project | 16-bit Compiler (Options|Project|16-bit Compiler)

16-bit Compiler options affect the compilation of all 16-bit Windows 3.x applications. For most options in this section you will usually want to keep the default settings.

The subtopics are

Processor

Calling Convention

Memory Model

Segment Names Data

Segment Names Far Data

Segment Names Code

Entry/Exit Code


16-bit Compiler|Processor (Project Options)
16-bit Compiler | Processor (Options|Project|16-bit Compiler)

The Processor options let you specify the minimum type of CPU your program will run on. These options introduce instructions specific to the CPU type you select to increase performance.

The options are

Instruction Set

Data Alignment


16-bit Instruction Set (Project Options)
16-bit Instruction Set (Options|Project|16-bit Compiler|Processor)

The Instruction Set options specify for which CPU instruction set the compiler should generate code.

8086

(Command-line equivalent: -1-)

Choose the 8086 option if you want the compiler to generate code for the 8086-compatible instruction set.

80186

(Command-line equivalent: -1)

Choose the 80186 option if you want the compiler to generate code for the 80186/286 instruction set (16-bit only).

80286

(Command-line equivalent: -2)

Choose the 80286 option if you want the compiler to generate code for the 80286 protected-mode-compatible instruction set (16-bit only).

80386

(Command-line equivalent: -3)

Choose the 80386 option if you want the compiler to generate code for the 80386 protected-mode-compatible instruction set.

i486

(Command-line equivalent: -4)

Choose the i486 option if you want the compiler to generate 80386/i486 instructions running in enhanced-mode Windows.


Data Alignment (Project Options)
Data Alignment (Options|Project|16-bit Compiler or 32-bit Compiler|Processor)

Byte Alignment

(Command-line equivalent: -an)

Align to n: 1=byte, 2=word (2 bytes), 4=double word (32-bit only, 4 bytes). Forces integer-size and larger items to be aligned on a machine-word boundary. Extra bytes are inserted in a structure to ensure member alignment. Automatic and global variables are aligned properly. char and unsigned char variables and fields can be placed at any address; all others are placed at an even-numbered address. This option is off by default (-a-), allowing byte-wise alignment.

Word Alignment (2-byte)

(Command-line equivalent: -a2)

When the Word Alignment option is on, the compiler aligns non-character data (structs and unions only) at even addresses. Extra bytes are inserted in a structure to ensure member alignment. Automatic and global variables are aligned properly. char and unsigned char variables and fields can be placed at any address; all others are placed at an even-numbered address.

Word alignment increases the speed at which 80x86 processors fetch and store data.

When this option is off, the compiler uses byte-aligning, where data (structs and unions only) can be aligned at either odd or even addresses, depending on which is the next available address.

Default = Byte Alignment

Double Word (2-byte)

(32-bit only)

(Command-line equivalent: -a4)

Double Word Alignment tells Borland C++ to align non-character data (within structs and unions only) at 32-bit word (4-byte) boundaries. When this setting is off, Borland C++ uses byte-aligning, where data (again, within structs and unions only) can be aligned at either odd or even addresses, depending on the next available address.

Double Word Alignment increases the speed at which 80x86 processors fetch and store data.

Quad Word (8-byte)

(32-bit only)

(Command-line equivalent: -a8)

Quad Word Alignment tells Borland C++ to align non-character data (within structs and unions only) at 64-bit word (8-byte) boundaries. When this setting is off, Borland C++ uses byte-aligning, where data (again, within structs and unions only) can be aligned at either odd or even addresses, depending on the next available address.

Quad Word Alignment increases the speed at which 80x86 processors fetch and store data.


16-bit Compiler|Calling Convention (Project Options)
16-bit Compiler | Calling Convention (Options|Project|16-bit Compiler)

Calling Convention options produce function calls that are smaller and faster by identifying which calling sequences (C, Pascal, or Register) are used by your program. Unlike normal C, calling-convention functions must pass the correct number and type of arguments.

The options are

Calling Conventions:

C

Pascal

Register


16-bit Calling Conventions (Project Options)
16-bit Calling Conventions (Options|Project|16-bit Compiler)

Note: Do not change these options unless you are an expert.

The Calling Convention options tell the compiler which calling sequences to generate for function calls. The C, Pascal, and Register calling conventions differ in the way each handles stack cleanup, order of parameters, case, and prefix (underbar) of global identifiers.

C

(Command-line equivalent: -pc, -p-)

This option tells the compiler to generate a C calling sequence for function calls (generate underbars, case sensitive, push parameters right to left). This is the same as declaring all subroutines and functions with the _ _cdecl keyword. Functions declared using the C calling convention are not required to pass a fixed number of parameters.

You can use the _ _pascal or _ _fastcall keyword to specifically declare a function or subroutine using another calling convention.

Pascal

(Command-line equivalent: -p)

This option tells the compiler to generate a Pascal calling sequence for function calls (do not generate underbars, all uppercase, calling function cleans stack, pushes parameters left to right). This is the same as declaring all subroutines and functions with the _ _pascal keyword. The resulting function calls are usually smaller and faster than those made with the C calling convention. Functions must pass the correct number and type of arguments, unlike normal C use. You can use the _ _cdecl or _ _fastcall keyword to specifically declare a function or subroutine using another calling convention.

Register

(Command-line equivalent: -pr)

This option forces the compiler to generate all subroutines and all functions using the new fastcall parameter-passing convention. This is equivalent to declaring all subroutine and functions with the _ _fastcall keyword. With this option enabled, functions or routines expect parameters to be passed in registers.

You can use the_ _pascal or _ _cdecl keyword to specifically declare a function or subroutine using another calling convention.


16-bit Compiler|Memory Model (Project Options)
16-bit Compiler | Memory Model (Options|Project|16-bit Compiler)

The Memory Model section lets you specify the organization of segments for code and data in your program. Large is the most common memory model used for Windows programs. All .OBJ and .LIB files in your program should be compiled in the same memory model.

The options are

Model

Assume SS Equals DS

Options

Put Constant Strings in Code Segments

Far Virtual tables

Automatic Far Data

Fast Huge Pointers

Far Data Threshold


Model (Project Options)
Model (Options|Project|16-bit Compiler|Memory Model)

The Model options specify the memory model you want to use. The memory model you choose determines the default method of memory addressing.

Tiny

(Command-line equivalent: -mt)

This is the smallest of the memory models. Use this model when memory is at an absolute premium. All four segment registers (CS, DS, SS, ES) are set to the same address. You have a total of 64K for all of your code, data, and stack. Near pointers are always used. Tiny model programs can be converted to .COM format by linking with the /t option.

Small

(Command-line equivalent: -ms)

Use the small model for average size applications. The code and data segments are different and don't overlap, so you have 64K of code and 64K of data and stack. Near pointers are always used.

Medium

(Command-line equivalent: -mm)

Use the medium model for large programs that do not keep much data in memory. Far pointers are used for code but not for data. For DOS, data and stack together are limited to 64K, but code can occupy up to 1 MB.

Compact

(Command-line equivalent: -mc)

Use the compact model if your code is small but you need to address a lot of data. The Compact model is the opposite of the medium model: far pointers are used for data but not for code; code is imited to 64K, pointers can point almost anywhere. All functions are near by default and all data pointers are far by default.

Large

(Command-line equivalent: -ml)

Use the large model for very large applications only. Far pointers are used for both code and data. In DOS, data is limited to 1MB. Far pointers can point almost anywhere. All functions and data pointers are far by default.

Huge

(Command-line equivalent: -mh)

Use the huge model for very large applications only. Far pointers are used for both code and data. Borland C++ normally limits the size of all static data to 64K; the huge memory model sets aside that limit, allowing data to occupy more than 64K.

Default for 16-bit = Large.


Assume SS Equals DS (Project Options)
Assume SS Equals DS (Options|Project|16-bit Compiler|Memory Model)

The Assume SS Equals DS options specify how the compiler considers the stack segment (SS) and the data segment (DS).

Default for Memory Model

(No command-line equivalent.)

The memory model you use determines whether the stack segment (SS) is equal to the data segment (DS) Usually, the compiler assumes that SS is equal to DS in the small and medium memory models (except for DLLs).

Never

(Command-line equivalent: -Fs-)

The compiler does not assume SS is equal to DS. This is always the case in the compact and large memory models and when building a Windows DLL.

Always

(Command-line equivalent: -Fs)

The compiler always assumes that SS is equal to DS in all memory models. This option causes the IDE to substitute the C0Fx.OBJ startup module for C0x.OBJ and places the stack in the data segment. You can use it when porting code originally written for an implementation that makes the stack part of the data segment.


Put Constant Strings in Code Segments (Project Options)
Put Constant Strings in Code Segments (Options|Project|16-bit Compiler|Memory Model)

(Command-line equivalent: -dc)

This option takes literal strings defined in the program source and places them in the code segment, rather than in the data segment making the data type const (16-bit only).

Note:	This should be used only with compact or large memory models. This option does not work with overlays.

Using this option saves data segment space. In large programs, especially those with a large number of literal strings, this option shifts the burden from the data segment to the code segment.

Default = OFF


Automatic Far Data (Project Options)
Automatic Far Data (Options|Project|16-bit Compiler|Memory Model)

(Command-line equivalent: -Ff and -Ff=size)

When the Automatic Far Data option is on, the compiler automatically places data objects larger than or equal to the threshold size into far data segments. The threshold size defaults to 32,767.

When this option is off, the size value is ignored

This option and the Far Data Threshold input box work together. The Far Data Threshold specifies the minimum size above that which data objects will be automatically made far.

If you use this option in conjunction with the Generate COMDEFs option (-Fc), the COMDEFs become far in the compact and large models.

Default = OFF


Far Virtual Tables (Project Options)
Far Virtual Tables (Options|Project|16-bit Compiler|Memory Model)

(Command-line equivalent: -Vf)

When the Far Virtual Tables option is on, virtual tables are created in the code segment instead of the data segment. Virtual table pointers are made into full 32-bit pointers.

You use Far Virtual Tables to remove the virtual tables from the data segment, that could be getting full, and to share objects (of classes with virtual functions) between modules that use different data segments (for example, a DLL and an executable using that DLL).

You must compile all modules that might share objects either entirely with or without this option.

This option changes the mangled names of C++ objects.


Far Data Threshold (Project Options)
Far Data Threshold (Options|Project|16-bit Compiler|Memory Model)

(Command-line equivalent: -Ff=size, where "size" = threshold size)

Use Far Data Threshold to specify the size portion needed to complete the Automatic Far Data option.

This value is ignored if the Automatic Far Data option is off.


Fast Huge Pointers (Project Options)
Fast Huge Pointers (Options|Project|16-bit Compiler|Memory Model)

(Command-line equivalent: -h)

The Fast Huge Pointers option normalizes huge pointers only when a segment wrap-around occurs in the offset portion of the segment. This greatly speeds up the computation of huge pointer expressions, but must be used with caution, because it can cause problems for huge arrays when array elements cross a segment boundary.


16-bit Compiler|Segment Names Data (Project Options)
16-bit Compiler | Segment Names Data (Options|Project|16-bit Compiler)

Use Segment Names Data to change the default segment, group, and class names for initialized and uninitialized data.

Note:	Do not change the settings in this dialog box unless you are an expert.

The options are

Initialized Data

Uninitialized Data


Initialized Data (Project Options)
Initialized Data (Options|Project|16-bit Compiler|Segment Names Data)

Use Initialized Data to change the default segment, group, and class names for initialized data.

Use an asterisk (*) to select default names.

Note:	Do not change the settings in this dialog box unless you are an expert.

Initialized Data segment

(Command-line equivalent = -zRname)

Sets the name of the initialized data segment. By default, the initialized data segment is named _DATA.

Initialized Data group

(Command-line equivalent = -zSname)

Sets the name of the initialized data segment group. By default, the data group is named DGROUP.

Initialized Data class

(Command-line equivalent = -zTname)

Sets the name of the initialized data segment. By default, the initialized data segment class is named DATA.


Uninitialized Data (Project Options)
Uninitialized Data (Options|Project|16-bit Compiler|Segment Names Data)

Use Uninitialized Data to change the default segment, group, and class names for code uninitialized data.

Use an asterisk (*) to select default names.

Note:	Do not change the settings in this dialog box unless you are an expert.

Uninitialized Data (BSS segment)

(Command-line equivalent = -zDname)

Sets the name of the uninitialized data segment. By default, the uninitialized data segment is named _BSS.

Uninitialized Data (BSS group)

(Command-line equivalent = -zGname)

Sets the name of the uninitialized data segment group. By default, the data group is named DGROUP.

Uninitialized Data (BSS class)

(Command-line equivalent = -zBname)

Sets the name of the uninitialized data segment class. By default, the uninitialized data segments are assigned to class BSS.


16-bit Compiler|Segment Names Far Data (Project Options)
16-bit Compiler | Segment Names Far Data (Options|Project|16-bit Compiler)

16-bit Compiler|Segment Names Far Data options set the far data segment name, group, class name, and the far virtual tables segment name and class.

The options are:

Far Data

Far Data Segment

Far Data Group

Far Data Class

Far Virtual Tables

Virtual Table Segment

Virtual Table Class


Far Data (Project Options)
Far Data (Options|Project|16-bit Compiler|Segment Names Far Data)

Use Far Data to change the default segment, group, and class names for far data.

Use an asterisk (*) to select default names.

Note:	Do not change the settings in this dialog box unless you are an expert.

Far Data Segment

(Command-line equivalent = -zEname)

Sets the name of the segment where far objects are placed. By default, the segment name is the name of the far object followed by _DATA.

Far Data Group

(Command-line equivalent = -zHname)

Causes far objects to be placed into the named group. By default, far objects are not placed into a group.

Far Data Class

(Command-line equivalent = -zFname)

Sets the name of the class for far objects. By default, the name is FAR_DATA.


Far Virtual Tables (Project Options)
Far Virtual Tables (Options|Project|16-bit Compiler|Segment Names Far Data)

Use Far Virtual Tables to change the default segment and class names virtual tables.

Use an asterisk (*) to select default names.

Note:	Do not change the settings in this dialog box unless you are an expert.

Virtual Table Segment

(Command-line equivalent = -zWname)

Sets the name of the far virtual table segment. By default, far virtual tables are generated in the CODE segment.

Virtual Table Class

Sets the name of the far virtual table class segment. By default, far virtual table classes are generated in the CODE segment.


16-bit Compiler|Segment Names Code (Project Options)
16-bit Compiler | Segment Names Code (Options|Project|16-bit Compiler)

Segment Names Code options let you specify a new code segment name and reassign the group and class.

The options are

Code Segment

Code Group

Code Class


Code (Project Options)
Code (Options|Project|16-bit Compiler|Segment Names Code)

Use Code to change the name of the code segment, as well as the code group and class.

Use an asterisk (*) to select default names.

Note:	Do not change the settings in this dialog box unless you are an expert.

Code Segment

(Command-line equivalent = -zAname)

Sets the name of the code segment. By default, the code segment is named _CODE, except for the medium and large models where the name is filename_CODE (filename here is the source file name).

Code Group

(Command-line equivalent = -zPname)

Causes any output files to be generated with a code group for the code segment.

Code Class

(Command-line equivalent = -zCname)

Sets the name of the code segment class. By default, the code segment is assigned to clase CODE.


16-bit Compiler|Entry/Exit Code (Project Options)
16-bit Compiler | Entry/Exit Code (Options|Project|16-bit Compiler)

Entry/Exit Code options tell the compiler what type of application the compiler creates by specifying what prolog and epilog code to generate.

The options are

Windows All Functions Exportable

Windows Explicit Functions Exported

Windows Smart Callbacks

Windows Smart Callbacks, Explicit Functions Exportable

Windows DLL, All Functions Exportable

Windows DLL, Explicit Functions Exported


Entry/Exit Code (Project Options)
Entry/Exit Code (Options|Project|16-bit Compiler|Entry/Exit Code)

These options specify which type of prolog and epilog code the compiler generates for each module's functions.

Windows All Functions Exportable

(Command-line equivalent: -W)

This option generates the necessary overhead information for every function (whether the function needs it or not). It assumes that all functions can be called by the Windows kernel or by other modules.

This option creates a Windows EXE function prolog/epilog for all 'far' functions, then sets up those functions to be called from another module. To actually export the function address from the EXE to a DLL, the code includes a call to MakeProcInstance(), passing the resulting pointer to the DLL requesting the address of the function. The function must have -export or the function name must be included in the .DEF file of the executable.

This option creates a general Windows executable, but not necessarily the most efficient.

Windows Explicit Functions Exported

(Command-line equivalent: -WE)

Use this option if you have functions that will not be called by the Windows kernel. Windows Explicit Functions Exported operates the same as Windows All Functions Exportable except that only those functions marked with the _export keyword (and methods of classes marked as _export) are given the extra prolog/epilog.

This option is far more efficient than Windows All Functions Exportable, since only those functions called from outside the module get the prolog overhead. This option requires determining which functions/classes need to be exported in advance. MakeProcInstance() is still used, but no .DEF file manipulation is needed.

Windows Smart Callbacks

(Command-line equivalent: -WS)

Use this option only if the compiler can assume that DS = SS for all functions in the module (which is true for the vast majority of Windows programs and the default for Borland tools).

This option creates a Windows EXE function prolog/epilog for all 'far' functions, then sets up those functions to be called from another module. MakeProcInstance() does not need to be called and .DEF file editing is not needed.

Windows Smart Callbacks, Explicit Functions Exportable

(Command-line equivalent: -WSE, 16-bit only)

This option is the same as Windows Smart Callbacks except that only those functions marked with the _export keyword (and methods of classes marked as _export) are given the extra prolog/epilog. This is efficient since only those functions called from outside the module get the prolog overhead. This option requires determining in advance which functions/classes need to be exported in advance.

Windows DLL, All Functions Exportable

(Command-line equivalent: -WD)

This option creates a Windows DLL function prolog/epilog for all 'far' functions, then sets up those functions to be called from another module. In order to actually export the function address from the DLL, functions must be marked with the _export keyword or function names need to be included in the .DEF file of the executable.

Windows DLL, Explicit Functions Exported

(Command-line equivalent: -WDE)

This option is the same as Windows DLL, All Functions Exportable except that only those functions marked with the _export keyword (and methods of classes marked as _export) are given the extra prolog/epilog. This is far more efficient than Windows DLL, All Functions Exportable since only those functions called from outside the module get the prolog overhead. This option requires determining which functions/classes need to be exported in advance. No .DEF file manipulation is needed.


32-Bit Compiler Options
32-bit Compiler Options (Options|Project|32-bit Compiler)

32-bit Compiler Options affect the compilation of all 32-bit Windows applications for Windows NT and Win32s. Because 32-bit programs are not segmented, there are fewer options to configure than for 16-bit programs.

The subtopics are

Processor

Calling Conventions


32-bit Compiler|Processor (Project Options)
32-bit Compiler | Processor (Options|Project|32-bit Compiler|Processor)

32-bit Compiler Processor options specify which CPU instruction set to use and how to handle floating-point code for 32-bit programs.

The options are

Instruction Set

Data Alignment


32-bit Instruction Set (Project Options)
32-bit Instruction Set (Options|Project|32-bit Compiler|Processor)

The Instruction Set options specify for which CPU instruction set the compiler should generate code.

80386 32-bit

(Command-line equivalent: -3)

Choose the 80386 option if you want the compiler to generate 80386 protected-mode compatible instructions running in Windows enhanced-mode.

i486 32-bit

(Command-line equivalent: -4)

Choose the i486 option if you want the compiler to generate i486 protected-mode compatible instructions running in Windows enhanced-mode.

Pentium

(Command-line equivalent: -5)

Choose the Pentium option if you want the compiler to generate Pentium instructions running in Windows enhanced-mode.


32-Bit Compiler|Calling Convention (Project Options)
32-bit Compiler | Calling Convention (Options|Project|32-bit Compiler|Calling Convention)

Calling Convention options produce function calls that are smaller and faster by identifying which calling sequences (C, Pascal, or Register) your program uses. Unlike normal C, calling-convention functions must pass the correct number and type of arguments.

The options are

Calling Conventions:

C

Pascal

Register

Standard Call


32-bit Calling Conventions (Project Options)
32-bit Calling Conventions (Options|Project|32-bit Compiler|Calling Convention)

Note: Do not change this option unless you're an expert.

The Calling Convention options tell the compiler which calling sequences to generate for function calls. The C, Pascal, and Register calling conventions differ in the way each handles stack cleanup, order of parameters, case, and prefix (underscore) of global identifiers.

C

(Command-line equivalent: -pc)

This option tells the compiler to generate a C calling sequence for function calls. This is equivalent to declaring all subroutine and functions with the _ _cdecl keyword. The resulting function calls are smaller and faster.

You can use the _ _stdcall, _ _pascal, or _ _fastcall keyword to specifically declare a function or subroutine using another calling convention.

Pascal

(Command-line equivalent: -p)

This option tells the compiler to generate a Pascal calling sequence for function calls (do not generate underbars, all uppercase, calling function cleans stack, pushes parameters left to right). This is the same as declaring all subroutines and functions with the _ _pascal keyword. The resulting function calls are usually smaller and faster than those made with the C calling convention. Functions must pass the correct number and type of arguments, unlike normal C use. You can use the _ _cdecl or _ _fastcall keyword to specifically declare a function or subroutine using another calling convention.

Register

(Command-line equivalent: -pr)

This option specifies the fastcall parameter-passing convention. This option forces the compiler to generate all subroutine calls and all functions using the new fastcall parameter-passing convention. This is equivalent to declaring all subroutines and functions with the _ _fastcall keyword. With this option enabled, functions or routines expect parameters to be passed in registers.

You can use the _ _stdcall, _ _pascal, or _ _cdecl keyword to specifically declare a function or subroutine using another calling convention.

Standard Call (32-bit Compiler Only)

(Command-line equivalent: -ps)

This option tells the compiler to generate a Stdcall calling sequence for function calls (does not generate underscores, preserve case, called function cleans stack, pushes parameters right to left). This is the same as declaring all subroutines and functions with the _ _stdcall keyword. Functions must pass the correct number and type of arguments, unlike normal C use. You can use the _ _cdecl or _ _pascal keyword to specifically declare a function or subroutine using another calling convention.

For example:

myname(int,int) => myname

Default = C


Build Attributes (Project Options)
Build Attributes (Options|Project|Build Attributes)

See Also

Build attributes affect whether or not a node is built during compilation. The icons associated with each of these options are displayed next to the nodes in the Project hierarchy diagram. Build Attributes are set in the Options|Project dialog box.

The available options are:

Always Build

Check Always Build and the node is always built, even if it has not changed.

Build When Out of Date

Check Build When Out of Date and the node is built only if it has changed.

Never Build

Check Never Build and the node is not built.

Can't Build

Check Can't Build to be notified when a node cannot be built.

Exclude From Parent

Check Exclude from Parent and the system indicates when a node should be excluded from parent (such as with source pools).


See Also

Managing Projects

Project Hierarchy


Browser Options (Environment Options)
Browser Options (Options|Environment)

The Options|Environment|Browser options determine which symbols can be viewed using the Browser and whether one or more Browser windows can be open at the same time.

The options are:

Visible Symbols

Browser Window Behavior


Visible Symbols (Environment Options)
Visible Symbols (Options|Environment|Browser)

Use the Environment|Browser|Visible Symbols options to specify the types of symbols you want to have visible in the Browser. These options define the default settings for each new Browser view. You can change these options for each view by using the controls at the bottom of each of the open Browser views.

The types of symbols you can view are:

Constants	Display constants and defined values.

Types	Display data types.

Functions	Display functions.

Debuggable	Display 'debuggable' objects.

Variables	Display local and global variables.

Inherited	Display inherited classes, data members, and member functions.

Virtual	Display virtual classes, data members, and member functions.

Private	Display private classes, data members, and member functions.


Browser Window Behavior (Environment Options)
Browser Window Behavior (Options|Environment|Browser)

The Environment|Browser|Browser Window Behavior options control how many Browser views you can have open at one time. These options specify the default setting for the start of the first Brower session. You can also set these options within a Browser view by choosing Toggle Window Mode on the Browser SpeedMenu.

Mode	Description

Single Window	Lets you open only one Browser view at a time. (It also disables the Return to Previous View command on the Browser SpeedMenu.) The next time you select a Browser action, the Browser replaces the view you currently have open.

Multiple Window	Lets you open multiple Browser views at the same time. Each time you select a new Browser action, an additional Browser view window opens.


Compiler Options
Compiler Options (Options|Project|Compiler)

Compiler options are common to all C and C++ programs. They directly affect how the compiler generates code.

The subtopics are:

Defines

Code Generation

Floating Point

Compiler Output

Source

Debugging

Precompiled Headers


Compiler|Defines (Project Options)
Compiler | Defines (Options|Project|Compiler)

Preprocessor defines used in #if statements and macro definitions to the preprocessor can be entered on the Compiler Defines page. The following rules apply when using the Defines input box:

Separate multiple defines with semicolons (;), and assign values with an equal sign (=).

Leading and trailing spaces are stripped, but embedded spaces are left intact.

If you want to include a semicolon in a macro, place a backslash (\) in front of it.


Compiler|Code Generation (Project Options)
Compiler | Code Generation (Options|Project|Compiler)

Compiler Code Generation options affect how code is generated.

The options are:

Allocate Enums as Ints

Unsigned Characters

Duplicate Strings Merged

fastthis

Register Variables


Allocate Enums as Ints (Project Options)
Allocate Enums As Ints (Options|Project|Compiler|Code Generation)

(Command-line equivalent: -b)

When the Allocate Enums As Ints option is on, the compiler always allocates a whole word, that is, a two-byte int (16-bit) or four-byte int (32-bit), for enumeration types (variables of type enum).

When this option is off, the compiler allocates the smallest integer that can hold the enumeration values: the compiler allocates an unsigned or signed char if the values of the enumeration are within the range of 0 to 255 (minimum) or -128 to 127 (maximum), or an unsigned or signed short if the values of the enumeration are within the range of 0 to 65,535 (minimum) or -32,768 to 32,767 (maximum) for 16-bit programs only. The compiler allocates a four-byte int for 32-bit compiler or a two-byte int for 16-bit compiler to represent the enumeration values if any value is out of range.

Default = ON


Unsigned Characters (Project Options)
Unsigned Characters (Options|Project|Compiler|Code Generation)

(Command-line equivalent: -K)

When the Unsigned Characters option is on, the compiler treats all char declarations as if they were unsigned char type, which provides compatibility with other compilers.

Default = OFF


Duplicate Strings Merged (Project Options)
Duplicate Strings Merged (Options|Project|Compiler|Code Generation)

(Command-line equivalent: -d)

When the Duplicate Strings Merged option is on, the compiler merges two literal strings when one matches another. This produces smaller programs, but can introduce errors if you modify one string.


_fastthis (Project Options)
_fastthis (Options|Project|Compiler|Code Generation)

(Command-line equivalent: -po)

When the fastthis option is enabled (16-bit applications only), the compiler compiles member functions to expect their this pointer to be passed in a register (or a register pair in 16-bit large data models). Likewise, calls to member functions load the register (or register pair) with this.

When this is a 'near' (16-bit) pointer, it is supplied in the SI register; for 'far' this pointers, DS"SI is used. If necessary, the compiler saves and restores DS. All references in the member function to member data are done via the SI register.

The names of member functions compiled with fastthis are mangled differently from non-fastthis member functions, to prevent mixing the two. It is easiest to compile all classes with fastthis, but you can compile some classes with fastthis and some without, as in the following example:

// no -po on the command-line

class X;

#pragma option -po

class Y     //Y will use fastthis

{

.

.

.

};

class X     //X will not use fastthis,

{           //since its class declaration

.           //appeared before fastthis was turned on

.

.

};

#pragma option -po.


Register Variables (Project Options)
Register Variables (Options|Project|Compiler|Code Generation)

These options suppress or enable the use of register variables.

None

(Command-line equivalent: -r-)

Choose None to tell the compiler not to use register variables even if you have used the register keyword.

Register Keyword

(Command-line equivalent: -rd)

Choose Register Keyword to tell the compiler to use register variables only if you use the register keyword and a register is available. Use this option or the Automatic option to optimize the use of registers. You can use -rd in #pragma options.

Automatic

(Command-line equivalent: -r)

Choose Automatic to tell the compiler to automatically assign register variables if possible, even when you do not specify a register variable by using the register type specifier.

Generally, you can keep this option set to Automatic unless you are interfacing with preexisting assembly code that does not support register variables.

Default = Automatic


Compiler|Floating Point (Project Options)
Compiler | Floating Point (Options|Project|Compiler)

Floating-Point options tell the compiler how to handle 16-bit floating-point code and floating-point optimization.

The options are:

Floating Point

No Floating Point

Fast Floating Point

Correct Pentium FDIV Flaw


Floating Point (Project Options)
Floating Point (Options|Project|Compiler|Floating Point)

The Floating Point options specify how the compiler handles floating-point numbers in your code.

No Floating Point

(Command-line equivalent: -f-)

Choose No Floating Point if you are not using floating point. No floating-point libraries are linked. If you choose None and use floating-point calculations in your program, you get link errors.

Fast Floating Point

(Command-line equivalent: -ff)

When Fast Floating Point is on, floating-point operations are optimized without regard to explicit or implicit type conversions. Calculations can be faster than under ANSI operating mode.

When this option is off, the compiler follows strict ANSI rules regarding floating-point conversions.

Default = ON

Correct Pentium FDIV Flaw

(Command-line equivalent: -fp)

Choose Correct Pentium FDIV Flaw if you want to include code in your program that corrects the Pentium FDIV (floating point division) flaw. Choosing this option will decrease your program's performance when using the FDIV instruction.

Note:	Use of this option only corrects FDIV instructions in modules that you compile. The run-time library also contains FDIV instructions which are not modified by the use of this switch. Turn this option on when recompiling the run-time library source provided with the CD-ROM version of Borland C++ to produce a library which corrects all FDIV instructions generated by the compiler.

The following functions use FDIV instructions in assembly language which are not corrected if you use this option:

acos	cosh	pow10l

acosl	coshl	powl

asin	cosl	sin

asinl	exp	sinh

atan	expl	sinhl

atan2	fmod	sinl

atan2l	fmodl	tan

atanl	pow	tanh

cos	pow10	tanhl

tanl

Any function that converts a floating point number to or from a string (ie. printf, scanf) is also not corrected.

Default = OFF


Pentium FDIV (Floating Point Division) Flaw

Testing for the Pentium FDIV Flaw

Here is a very simple test you can use to verify the compiler workaround (IDE: Correct Pentium FDIV Flaw; command-line: -fp) to the Pentium FDIV flaw:

#include <stdio.h>

int main ()

{

    double x=8391670, y=3145727;

    printf("Answer (should be zero): %lf\n", x - ((x / y) * y));

}

You can also use a similar test in your applications to determine the presence of a Pentium processor which exhibits the FDIV flaw.

For More Information

For more information on the Pentium FDIV flaw and software solution, you can access the URL http://www.intel.com/IAL on the World Wide Web.

For information on replacing Pentium processors which exhibit the FDIV flaw, you can access the URL http://www.intel.com/IAL on the World Wide Web or call one of the following Intel phone numbers:

1-800-628-8686

1-916-356-3551


Compiler|Compiler Output (Project Options)
Compiler | Compiler Output (Options|Project|Compiler)

Set control of object file contents on the Compiler Output page.

The options are:

Autodependency Information

Generate Underscores

Generate COMDEFs


Auto-Dependencies (Project Options)
Autodependency Information (Options|Project|Compiler|Compiler Ourput)

(Command-line equivalent: -X-)

When the Autodependencies option is checked, the Project Manager automatically checks dependencies for every .OBJ file on disk that has a corresponding .C or .CPP source file in the project list.

The Project Manager opens the .OBJ file and looks for information about files included in the source code. This information is always placed in the .OBJ file when the source module is compiled.

Then every file that was used to build the .OBJ file is checked for time and date against the time and date information in the .OBJ file. The source file is recompiled if the dates are different. This is called an autodependency check.

When this option is unchecked (-X), the compiler does not use autodependency output.

If the project file contains valid dependency information, the Project Manager does the autodependency check using that information.

This is much faster than reading each .OBJ file.

Default = Checked (-X-)


Generate Underbars (Project Options)
Generate Underscores (Options|Project|Compiler|Compiler Ourput)

(Command-line equivalent: -u)

When the Generate Underscores option is on, the compiler automatically adds an underscore character (_) in front of every global identifier (functions and global variables). Pascal identifiers (those modified by the _ _pascal keyword) are made uppercase and are not prefixed with an underscore.

Turn this option on to avoid errors if you are linking with the standard Borland C++ libraries.

Default = ON


Generate COMDEFs (Project Options)
Generate COMDEFs (Options|Project|Compiler|Compiler Ourput)

(Command-line equivalent: -Fc)

Generate COMDEFs generates communal variables (COMDEFs) for global C variables that are not initialized and not declared as static or extern.

For example, a definition such as

int SomeArray[256];

could appear in a header file that is then included in many modules. When this option is on, the compiler generates SomeArray as a communal variable rather than a public definition (a COMDEF record rather than a PUBDEF record). You can use this option when porting code that uses a similar feature with another implementation.

The linker generates only one instance of the variable, so it will not be a duplicate definition linker error. As long as a given variable does not need to be initialized to a nonzero value, you do not need to include a definition for it in any of the source files.

Default = OFF


Compiler|Source (Project Options)
Compiler | Source (Options|Project|Compiler)

Compiler|Source options set source code interpretation.

The options are:

Source

Nested Comments

Identifier Length

Language Compliance

Borland Extensions

ANSI

UNIX V

Kernighan and Ritchie


Nested Comments (Project Options)
Nested Comments (Options|Project|Compiler|Source)

(Command-line equivalent: -C)

When the Nested Comments option is on, you can nest comments in your C and C++ source files.

Nested comments are not allowed in standard C implementations, and they are not portable.


Identifier Length (Project Options)
Identifier Length (Options|Project|Compiler|Source)

(Command-line equivalent: -in, where "n" = significant characters)

Use the Identifier Length input box to specify the number of significant characters (those which will be recognized by the compiler) in an identifier.

Except in C++, which recognizes identifiers of unlimited length, all identifiers are treated as distinct only if their significant characters are distinct. This includes variables, preprocessor macro names, and structure member names.

Valid numbers for N are 0, and 8 to 250, where 0 means use the maximum identifier length of 250.

Borland C++defaults to 32 characters per identifier for C programs. Other systems, including some UNIX compilers, ignore characters beyond the first eight. If you are porting to other environments, you might want to compile your code with a smaller number of significant characters, which helps you locate name conflicts in long identifiers that have been truncated.

Default = 55


Language Compliance (Project Options)
Language Compliance (Options|Project|Compiler|Source)

The Language Compliance options tell the compiler how to recognize keywords in your programs.

Borland Extensions

(Command-line equivalents: -A-, -AT)

The Borland Extensions option tells the compiler to recognize Borland's extensions to the C language keywords, including near, far, huge, asm, cdecl, pascal, interrupt, _es, _export, _ds, _cs, _ss, and the register pseudovariables (_AX, _BX, and so on). For a complete list of keywords, see the keyword index.

ANSI

(Command-line equivalent: -A)

The ANSI option compiles C and C++ ANSI-compatible code, allowing for maximum portability.

UNIX V

(Command-line equivalent: -AU)

The UNIX V option tells the compiler to recognize only UNIX V keywords and treat any of Borland's C++ extension keywords as normal identifiers.

Kernighan and Ritchie

(Command-line equivalent: -AK)

The Kernighan and Ritchie option tells the compiler to recognize only the K&R extension keywords and treat any of Borland's C++ extension keywords as normal identifiers.

Hint:	If you get declaration syntax errors from your source code, check this option (is it set to Borland?).

Default = Borland Extensions


Compiler|Debugging (Project Options)
Compiler | Debugging (Options|Project|Compiler)

Compiler Debugging options affect the generation of debug information during compilation.

The options are:

Standard Stack Frame

Test Stack Overflow

Out-of-Line Inline Functions

Line Numbers

Debug Information in OBJs

Browser Information in OBJs


Standard Stack Frame (Project Options)
Standard Stack Frame (Options|Project|Compiler|Debugging)

(Command-line equivalent: -k)

When the Standard Stack Frame option is on, the compiler generates a standard stack frame (standard function entry and exit code).

This is helpful when debugging, since it simplifies the process of tracing back through the stack of called subroutines.

Any function that does not use local variables and has no parameters is compiled with abbreviated entry and return code when this option is off. This makes the code shorter and faster.

The Standard Stack Frame option should always be on when you compile a source file for debugging.

Default = ON


Test Stack Overflow (Project Options)
Test Stack Overflow  (Options|Project|Compiler|Debugging)

(Command-line equivalent: -N)

When the Test Stack Overflow option is on, the compiler generates stack overflow logic at the entry of each function. It causes a stack overflow message to appear when a stack overflow is detected.

Even though this costs space and time in a program, it can be a real help, since a stack overflow bug can be difficult to track down. If an overflow is detected, the message "Stack overflow!" is printed, and the program exits with an exit code of 1.


Out-of-Line Inline Functions (Project Options)
Out-of-Line Inline Functions (Options|Project|Compiler|Debugging)

(Command-line equivalent: -vi)

When the Out-of-Line Inline Functions option is on, inline functions behave like actual functions. A separate function body is generated, and a call is made to that function.

When the Out-of-Line Inline Functions option is off, inline functions are substituted at the place of a call, and a separate function body is not generated.


Line Numbers Debug Info (Project Options)
Line Numbers (Options|Project|Compiler|Debugging)

(Command-line equivalent: -y)

When the Line Numbers option is on, the compiler automatically includes line numbers in the object and object map files (the latter for use by a symbolic debugger).

Including line numbers increases the size of the object and map files but does not affect the speed of the executable program.

When Line Numbers is on, make sure you turn off Jump Optimization in the Optimizations Specific options. Otherwise, the compiler might group together common code from multiple lines of source text during jump optimization, or might reorder lines (which makes line-number tracking difficult).

Default = OFF


Debug Info in OBJs (Project Options)
Debug Information In OBJs (Options|Project|Compiler|Debugging)

(Command-line equivalent: -v)

When the Debug Info In OBJs option is on, debugging information is included in object (.OBJ) files. The compiler passes this option to the linker so it can include the debugging information in the .EXE file. For debugging, this option treats C++ inline functions as normal functions.

You need debugging information in order to use either the integrated debugger or the stand alone Turbo Debugger.

When this option is off, you can link and create larger object files. While this option does not affect execution speed, it does affect compilation time.

Default = ON


Browser Info in OBJs (Project Options)
Browser Reference Information In OBJs (Options|Project|Compiler|Debugging)

(Command-line equivalent: -R)

When the Browser Info In OBJs option is on, browser information is included in object (.OBJ) files. You need debugging information in order to use the Browser.

When this option is off, you can link and create larger object files. While this option does not affect execution speed, it does affect compilation time.


Compiler | Precompiled headers (Options|Project|Compiler)

Precompiled header files can dramatically increase compilation speed by storing an image of the symbol table on disk in a file, then later reloading that file from disk instead of parsing all the header files again. Directly loading the symbol table from disk is much faster than parsing the text of header files, especially if several source files include the same header file.

The options are:

Generate and Use

Use But Do Not Generate

Do Not Generate or Use

Precompiled Header Name

Stop Precompiling After Header File


Precompiled Headers (Project Options)
Precompiled Headers (Options|Project|Compiler)

See Also

Precompiled Headers can dramatically increase compilation speeds, though they require a considerable amount of disk space. They are saved in the file <<filename>>.CSM.

Generate And Use

(Command-line equivalent: -H)

When the Generate And Use precompiled headers option is on, the IDE generates and uses precompiled headers.

Use But Do Not Generate

(Command-line equivalent: -Hu)

When the Use But Do Not Generate option is on, the IDE uses but does not generate precompiled headers.

Do Not Generate Or Use

(Command-line equivalent: -H-)

When the Do Not Generate Or Use option is on, the IDE does not generate or use precompiled headers.

Default = Do Not Generate Or Use


See Also

Precompiled Headers


Precompiled Header Name (Project Options)
Precompiled Header Name (Options|Project|Compiler|Precompiled Header)

(Command-line equivalent: -H=filename)

Enter the name of the file used for precompiled headers.


Stop Precompiling After Header File (Project Options)
Stop Precompiling After Header File (Options|Project|Compiler|Precompiled Header)

This option terminates the list of header files that are eligible for precompilation. You can use it to reduce the amount of disk space used by precompiled headers.

The header file you enter or select must be contained in a source file in order for a .CSM file to be generated.

A header file that is included from another header file, such as any header included in windows.h, does not cause the generation of a .CSM file. This is because windows.h must be completed for a .CSM file to be created, but processing would stop before windows.h was completely done.


C++ Compiler Options (Project Options)
C++ Compiler Options (Options|Project|C++ Options)

Compiler|C++ Options affect compilation of all C and C++ programs. For most options in this section, you usually want to keep the default settings.

The subtopics are:

Member Pointers

C++ Compatibility

Virtual Tables

Templates

Exception Handling/RTTI


C++ Options|Member Pointers (Project Options)
C++ Options | Member Pointers (Options|Project|C++ Options|Member Pointers)

Use C++ Member Pointers options to direct member pointers and affect how the compiler treats explicit casts.

The options are:

Honor Precision of Member Pointers

Member Pointer Representation

Support All Cases

Support Multiple Inheritance

Support Single Inheritance

Smallest for Class


Honor Precision of Member Pointers (Project Options)
Honor Precision of Member Pointers (Options|Project|C++ Options|Member Pointers)

(Command-line equivalent: -Vmp)

When the Honor Precision of Member Pointers option is on, the compiler honors an explicit cast (declared precision) to a pointer to a member of a simpler base class, even though it is actually pointing to a derived class member.


Member Pointer representation (Project Options)
Member Pointer Representation (Options|Project|C++ Options|Member Pointers)

The C++ Member Pointers options specify what member pointers can point to.

Support All Cases

(Command-line equivalent: -Vmv)

When the Support All Cases option is on, the compiler places no restrictions on what members can be pointed to.

Member pointers use the most general (but not always the most efficient) representation.

Support Multiple Inheritance

(Command-line equivalent: -Vmm)

When the Support Multiple Inheritance option is on, member pointers can point to members of multiple inheritance classes (with the exception of virtual base classes).

Support Single Inheritance

(Command-line equivalent: -Vms)

When the Support Single Inheritance option is on, member pointers can point to members of base classes that use single inheritance only.

Smallest for Class

(Command-line equivalent: -Vmd)

When the Smallest for Class option is on, member pointers use the smallest possible representation that allows member pointers to point to all members of their particular class. If the class is not fully defined at the point where the member pointer type is declared, the most general representation is chosen by the compiler (a warning is issued).

Default = Support All Cases


C++ Options|C++ Compatibility (Project Options)
C++ Options | C++ Compatibility (Options|Project|C++ Options|C++ Compatibility)

Use the C++ Compatibility options to handle C++ compatibility issues, such as handling 'char' types, specifying options about hidden pointers, passing class arguments, adding hidden members and code to a derived class, passing the 'this' pointer to 'Pascal' member functions, changing the layout of classes, or insuring compatibility when class instances are shared with non-C++ code or code compiled with previous versions of Borland C++.

Treat 'char' as Distinct Type

Virtual Base Pointers

Always Near

Same Size as 'this' Pointer

Options

Pass Class Values Via Reference to Temporary

Disable Constructor Displacements

Push 'this' First for Pascal Member Functions

'deep' Virtual Bases

Vtable Pointer Follows Data Members

Treat 'far' classes as 'huge'


Do Not Treat 'char' as Distinct Type (Project Options)
Do Not Treat 'char' as Distinct Type (Options|Project|C++ Options|C++ Compatibility)

(Command-line equivalent: -K2)

Allow only signed and unsigned char types. The Borland C++ compiler allows for signed char, unsigned char, and char data types. This option treats char as signed.

This option is provided for compatibility with previous versions of Borland C++.

Default = OFF


Virtual Base Pointers (Project Options)
Virtual Base Pointers (Options|Project|C++ Options|C++ Compatibility)

When a class inherits virtually from a base class, the compiler stores a hidden pointer in the class object to access the virtual base class subobject.

The Virtual Base Pointers options specify options about the hidden pointer.

Always Near

(Command-line equivalent: -Vb-)

When the Always Near option is on, the hidden pointer will always be a near pointer. This allows for the smallest and most efficient code.

Same Size as 'this' Pointer

(Command-line equivalent: -Vb)

When the Same Size as 'this' Pointer option is on, the compiler matches the size of the hidden pointer to the size of the 'this' pointer in the instance class.

This allows for compatibility with previous versions of the compiler.

Default = Always Near


Pass Class Values via Reference to Temporary (Project Options)
Pass Class Values via Reference to Temporary (Options|Project|C++ Options|C++ Compatibility)

(Command-line equivalent: -Va)

When the Pass Class Values via Reference to Temporary option is on, the compiler passes class arguments using the "reference to temporary" approach. When an argument of type class with constructors is passed by value to a function, this option instructs the compiler to create a temporary variable at the calling site, initialize this temporary variable with the argument value, and pass a reference to this temporary to the function.

This option insures compatibility with previous versions of the compiler.


Disable Constructor Displacements (Project Options)
Disable Constructor Displacements (Options|Project|C++ Options|C++ Compatibility)

(Command-line equivalent: -Vc)

When the Disable Constructor Displacements option is on, the compiler does not add hidden members and code to a derived class (the default).

This option insures compatibility with previous versions of the compiler.


Push 'this" First for Pascal Member Functions (Project Options)
Push 'this' First for Pascal Member Functions (Options|Project|C++ Options|C++ Compatibility)

(Command-line equivalent: -Vp)

When the Push 'this' First for Pascal Member Functions option is on, the compiler passes the 'this' pointer to 'Pascal' member functions as the first parameter on the stack.

By default, the compiler passes the 'this' parameter as the last parameter on the stack, which permits smaller and faster member function calls.

Default = OFF


'deep' Virtual Bases (Project Options)
'deep' Virtual Bases (Options|Project|C++ Options|C++ Compatibility)

(Command-line equivalent: -Vc)

When the 'deep' Virtual Bases option is on, the compiler does not change the layout of any classes in order to relax the restrictions on pointers.


Vtable Pointer Follows Data Members (Project Options)
Vtable Pointer Follows Data Members (Options|Project|C++ Options|C++ Compatibility)

(Command-line equivalent -Vt)

When the Virtual Table Pointer Follows Data Members option is on, the compiler places the virtual table pointer after any nonstatic data members of the specified class.

This option insures compatibility when class instances are shared with non-C++ code and when sharing classes with code compiled with previous versions of Borland C++.


Treat 'far' classes as 'huge' (Project Options)
Treat 'far' classes as 'huge' (Options|Project|C++ Options|C++ Compatibility)

(Command-line equivalent -Vh)

When the Treat 'far' classes as 'huge' option is on, the compiler treats all __far classes as __huge. For example, the following will normally fail to compile. Checking this option allows the fragment to compile.

struct __huge A

{

virtual	void	f();  // A vtable is required to see the error.

};

struct __far B  :  public A

{

};

// Error: Attempting to derive a far class from the huge base 'A'.

Default = OFF


C++ Options|Virtual Tables (Project Options)
C++ Options | Virtual Tables (Options|Project|C++ Options)

C++ Options|Virtual Tables options control C++ virtual tables and the expansion of inline functions when debugging.

The options are:

Linkage

Smart

Local

External

Public


Virtual Tables Linkage (Project Options)
Virtual Tables Linkage (Options|Project|C++ Options|Virtual Tables)

The C++ Virtual Tables options control C++ virtual tables and the expansion of inline functions when debugging.

Smart

(Command-line equivalent: -V)

You use the Smart option to generate C++ virtual tables (and out-of-line inline functions) so that only one instance of a given virtual table or inline function will be included in the program.

The Smart option produces the smallest and most efficient executables, but uses .OBJ and .ASM extensions only available with TLINK 3.0 and TASM 2.0 (or newer).

Local

(Command-line equivalent: -Vs)

You use the Local option to generate local virtual tables (and out-of-line inline functions) so that each module gets its own private copy of each virtual table or inline function it uses.

The Local option uses only standard .OBJ and .ASM constructs, but produces larger executables.

External

(Command-line equivalent: -V0)

You use the External option to generate external references to virtual tables. One or more of the modules comprising the program must be compiled with the Public option to supply the definitions for the virtual tables.

Public

(Command-line equivalent: -V1)

Public produces public definitions for virtual tables. When using External or Public options, at least one of the modules in the program must be compiled with the Public option to supply the definitions for the virtual tables. All other modules should be compiled with the External option to refer to that Public copy of the virtual tables.


C++ Options|Templates (Project Options)
C++ Options | Templates (Options|Project|C++ Options)

Use the options under C++ Options | Templates to tell the compiler how to generate template instances in C++.

The options are:

Instance Generation

Smart

Global

External


Templates Instance Generation (Project Options)
Templates Instance Generation (Options|Project|C++ Options|Templates)

See Also

The Template Instance Generation options specify how the compiler generates template instances in C++.

Smart

(Command-line equivalent: -Jg)

When the Smart option is on, the compiler generates public (global) definitions for all template instances. If more than one module generates the same template instance, the linker automatically merges duplicates to produce a single definition.

In order to generate the instances, however, the compiler must have available the function body (in the case of a template function) or the bodies of member functions and definitions for static data members (in the case of a template class), typically in a header file.

This is a convenient way of generating template instances.

Global

(Command-line equivalent: -Jgd)

When the Global option is on, the compiler generates public (global) definitions for all template instances.

The Global option does not merge duplicates. If the same template instance is generated more than once, the linker reports public symbol re-definition errors.

External

(Command-line equivalent: -Jgx)

When the External option is on, the compiler generates external references to all template instances.

When you use this option, all template instances in your code must be publicly defined so that external references are properly resolved.


See Also

Using Template Compiler Switches


C++ Options|Exception handling/RTTI (Project Options)
C++ Options | Exception Handling/RTTI (Options|Project|C++ Options)

Use the Exceptions Handling options to enable or disable exception handling and to tell the compiler how to handle the generation of run-time type information.

If you use exception handling constructs in your code and compile with exceptions disabled, you'll get an error.

The options are:

Enable Exceptions

Enable Exception Location Information

Enable Destructor Cleanup

Enable Fast Exception Prologs

Enable Compatible Exceptions

Enable Run-Time Type Information


Enable Exceptions (Project Options)
Enable Exceptions (Options|Project|C++ Options|Exception Handling/RTTI)

(Command-line equivalent: -x)

When Enable Exceptions is on, C++ exception handling is enabled. When this option is off, attempts to use exception handling routines will generate error messages during compilation.

Turning this option off makes it easier for you to remove exception handling information from programs that you intend to port to other platforms or compilers.

Default = ON


Exception Handling (Project Options)
Exception Handling (Options|Project|C++ Options|Exception Handling/RTTI)

Enable Exception Location Information

(Command-line equivalent: -xp)

When Enable Exception Location Information is on, run-time identification of exceptions is available, providing the file name and line number in the source code where the exception occurred. This enables the program to query file and line number from where a C++ exception was thrown.

Default = OFF

Enable Destructor Cleanup

(Command-line equivalent: -xd)

When the Enable Destructor Cleanup option is enabled and an exception is thrown, destructors are called for all automatically declared objects between the scope of the catch and throw statements.

Note:	Destructors are not automatically called for dynamic objects, and dynamic objects are not automatically freed.

Default = ON

Enable Fast Exception Prologs

(Command-line equivalent: -xf)

When Enable Fast Exception Prologs is enabled, inline code is expanded for every exception handling function. This option improves performance, but does increase the size of the .EXE.

Default = OFF

Note:	If you select both Fast Exception Prologs and Enable Compatible Exceptions, fast prologs will not be generated.

Enable Compatible Exceptions

(Command-line equivalent: -xc)

Enable Compatible Exceptions allows .EXE's and .DLL's built with Borland C++ to be compatible with .EXE's built with other products. When Enable Compatible Exceptions is not enabled, some exception handling information is included in the .EXE, even if Enable Exceptions is set to OFF, which could cause compatibility issues.

Note:	Libraries that can be linked into DLLs will need to be built with this option enabled.

Default = OFF


Enable Runtime Type Information (Project Options)
Enable Run-time Type Information (Options|Project|C++ Options|Exception Handling/RTTI)

(Command-line equivalent: -RT)

Enables the compiler to generate code that allows run-time type identification.

Default = ON


Debugger Options (Environment Options)
Debugger Options (Options|Environment|Debugger)

See Also

The Options|Environment|Debugger options affect the debugging of your program and how the integrated debugger is configured.

The options are:

Run Arguments

Event Capture

Windows Debugging Mode


See Also

Debugging in the IDE


Run Arguments (Environment Options)
Run Arguments (Options|Environment|Debugger)

See Also

Use the Run Arguments input box to enter any command-line options you want to pass to the application being debugged.


Event Capture (Environment Options)
Event Capture (Options|Environment|Debugger)

See Also

Use the Event Capture options to specify which types of messages or events are recorded in the Event Log.

Window Messages

When Window Messages is selected, all window-related messages are recorded in the Event Log.

Output Messages

When Output Messages is selected, all output debug strings are recorded in the Event Log.

Breakpoints

When Breakpoints is selected, breakpoint events are recorded in the Event Log.


Windows Debugging Mode (Environment Options)
Windows Debugging Mode (Options|Environment|Debugger)

See Also

The Windows Debugging Mode options determine the mode in which the debugger operates.

Hard Mode On All Stops

The Hard Mode On All Stops option disables multi-tasking and takes over the Windows messaging system. Only one application can run so the debugger must take control of Windows and only allow itself to be the only application running.

Smart

When the Smart option is selected, the debugger chooses hard or soft mode, depending on what events are occuring in the system. If it chooses soft mode, the debugger attempts to handle messages from other applications. This allows you to freely switch between applications while the debugger is running. This is the default setting.


Directories Options (Project Options)
Directories Options (Options|Project|Directories)

Options|Project

The Directories Options tell the Borland C++ compiler how to find or where to put header files, library files, source code, output files and other program elements.

The subtopics are:

Source Directories

Output Directories


Source Directories (Project Options)
Source Directories (Options|Project|Directories)

See Also

The Source Directories options specify the directory that contains your standard include files and where the integrated debugger looks for source files.

Multiple directory names are allowed in each of the list boxes; a semicolon (;) must separate the names.

Click the down-arrow icon or press Alt+Down arrow to display the history list of previously entered directory names.

Include

(Command-line equivalent: -Ipath, where "path" = directory path)

Use the Include list box to specify the directories that contain the standard include files. Standard include files are those given in angle brackets (<>) in a #include statement (for example, #include <myfile.>).

Library

(Command-line equivalent: -Lpath, where "path" = directory path)

Use the Library list box to specify the directories that contain the Borland C++ IDE startup object files (C0?.OBJ) and run-time library files (.LIB files). By default, the linker looks for them in the current directory.

Source

Use the Source list box to specify the directories where the integrated debugger looks for the source files used in your project.


Output Directory (Project Options)
Output Directories (Options|Project|Directories)

See Also

The Output Directories options specify the directories where your .OBJ, .EXE, and .MAP files are placed. The Borland C++ IDE looks for those directories when performing a make or run and to check dates and times of .OBJs and .EXEs. If the entry is blank, the files are stored in the current  directory.

Click the down-arrow icon or press Alt+Down arrow to display the history list of previously entered directory names.

Intermediate

Use the Intermediate list box to specify where Borland C++ places object (.OBJ) and map (.MAP) files when it builds your project.

Final

(Command-line equivalent: -npath, where "path" = directory path)

Use the Final list box to specify where Borland C++ places the end result of building your project (.OBJ, .ASM, or .I files).


See Also

Guidelines for Entering Directory Names


Guidelines for Entering Directory Names

See Also

Use the following guidelines when entering directories in the Directories Options pages.

You must separate multiple directory path names (if allowed) with a semicolon (;).

You can use up to a maximum of 127 characters (including whitespace).

Whitespace before and after the semicolon is allowed but not required.

Relative and absolute path names are allowed, including path names relative to the logged position in drives other than the current one.

For example,

C:\;C:..\BORLAND\TCW;A:\TCW;D:..\TCW\BIN


See Also

Directories Oettings

Entering Directories for Command-Line Options


Editor Options (Environment Options)
Editor Options (Options|Environment|Editor)

See Also

The Options|Environment|Editor options let you specify the appearance and behavior of the Borland C++ IDE editor.

The subtopics are:

Options

File

Display

The options are:

Editor SpeedSettings


See Also

Keyboard Shortcuts

Keystroke Mapping Option

Keymapper


Editor SpeedSettings (Environment Options)
Editor SpeedSettings (Options|Environment|Editor)

The Editor SpeedSettings in the Editor options allow you to set several editor-related options at one time. These options are set to emulate a specific type of editor. The display box in the lower right corner of the dialog shows which options are set by these SpeedSettings and what their values are for each setting.

The available Editor SpeedSettings are:

Default Keymapping

Press the Default Keymapping button to use the default key assignments for the editor, menus, and other IDE windows.

IDE Classic

Press the IDE Classic button to use the traditional Borland key assignments for the editor, menus, and other IDE windows.

BRIEF Emulation

Press the BRIEF emulation button to use Brief key assignments for the editor, menus, and other IDE windows.

Epsilon Emulation

Press the Epsilon emulation button to use Epsilon key assignments for the editor, menus, and other IDE windows.


Editor|Options (Environment Options)
Editor | Options (Options|Environment|Editor|Options)

The Editor|Options let you tailor the behavior of the IDE editor.

The Editor options are:

Auto Indent Mode

Insert Mode

Use Tab Character

Optimal Fill

Backspace Unindents

Cursor Through Tabs

Group Undo

Cursor Beyond EOF

Undo After Save

Keep Trailing Blanks

BRIEF Regular Expressions

Overwrite Blocks

Persistent Blocks

Double Click Line

Block Indent

Undo Limit

Tab Stops


Auto Indent Mode (Environment Options)
Auto Indent Mode (Options|Environment|Editor|Options)

When the Auto Indent Mode option is on, pressing Enter in an Edit window positions the cursor under the first nonblank character in the preceding nonblank line.

This feature can help you keep your program code more readable.

You can use Optimal Fill in conjunction with Auto Indent Mode to automatically insert the smallest number of tabs and spaces to indent your code.


Insert Mode (Environment Options)
Insert Mode (Options|Environment|Editor|Options)

When the Insert Mode option is on, the text you type is inserted, pushing the existing text to the right.

When this option is off, any text you type into Edit windows overwrites existing text.

To toggle Insert mode when you're working in an Edit window (without changing the default setting), press the INS key.


Use Tab Character (Environment Options)
Use Tab Character (Options|Environment|Editor|Options)

When the Use Tab Character option is on, the editor inserts a true tab character (ASCII 9) when you press Tab.

When this option is off, the Borland C++ IDE replaces tabs with spaces.

The Tab Stops option determines the number of spaces used to replace a tab.


Optimal Fill (Environment Options)
Optimal Fill (Options|Environment|Editor|Options)

When the Optimal Fill option is on, the Borland C++ IDE begins every autoindented line with the minimum number of characters possible, using tabs and spaces as necessary.

This option causes lines to be produced that have fewer characters than lines created with this option off.

This option works only when the Use Tab Character option is on.


Backspace Unindents (Environment Options)
Backspace Unindents (Options|Environment|Editor|Options)

If the cursor is on a blank line (or on the first nonblank character of a line),  when Backspace Unindents is

on	the Backspace key aligns (outdents) the line to the previous indention level

off	the Backspace key moves the cursor one character to the left, deleting each character

If the cursor is on a tab and the Backspace Unindents is off, and Cursor through Tabs is

on	the Backspace key moves the cursor one character to the left, deleting one blank space

off	the Backspace key moves the cursor one tab to the left, deleting the tab and any blank spaces to the right of the tab


Cursor through Tabs (Environment Options)
Cursor through Tabs (Options|Environment|Editor|Options)

When the Cursor through Tabs option is on, the cursor moves uniformly through the line as you press arrow keys for horizontal movement.

When this option is off, the cursor jumps several columns when you move the cursor over a tab.


Group Undo (Environment Options)
Group Undo (Options|Environment|Editor|Options)

See Also	Example

When Group Undo is on, and you use the Edit|Undo command, the effects of the last command are reversed, as are all immediately preceding commands of the same type.

Insertions, deletions, overstrikes, and cursor movements are editing commands that can be grouped.

The editor sees inserting a carriage return (pressing Enter) as an insertion followed by a cursor movement.

The grouping of inserted characters stops when you press Enter because the type of editing has changed (you inserted characters, then moved the cursor).

When Group Undo is off, Edit|Undo reverses the effect of a single editor command or keystroke.


See Also

Undo Limit


Group Undo Examples

If Group Undo is on and you type OOPS then choose Undo, the entire word is deleted. If you select Edit|Redo after undoing OOPS, the entire OOPS group appears in the window all at once.

If Group Undo is off and you type OOPS, only the last typed character is undone when you choose Undo. You would need to choose Undo four times to undo the word OOPS. Only one letter will appear each time you choose Redo.


Cursor Beyond EOF (Environment Options)
Cursor Beyond EOF (Options|Environment|Editor|Options)

When the Cursor Beyond EOF option is checked, the cursor can be moved beyond the EOF. When this option is not checked, the cursor stops at the EOF and cannot be moved beyond it.


Undo After Save (Environment Options)
Undo After Save (Options|Environment|Editor|Options)

When the Undo After Save option is on, you can perform an Edit|Undo command after the file has been saved.

When this option is off, an Edit|Undo command cannot be performed after the file has been saved. The undo buffer is deleted each time the file is saved.


Keep Trailing Blanks (Environment Options)
Keep Trailing Blanks (Options|Environment|Editor|Options)

When the Keep Trailing Blanks option is checked, trailing blanks in lines should be stored as a part of the file. This means you should be able to cursor through them, and END should take you beyond them, not beyond the last word on the line. When this option is not checked, trailing blanks are ignored and not saved as part of the file.


BRIEF Regular Expressions (Environment Options)
BRIEF Regular Expressions (Options|Environment|Editor|Options)

See Also

When the BRIEF Regular Expressions option is on, BRIEF-style regular expressions are supported in editing operations such as search-and-replace.

When the BRIEF Regular Expressions option is off, then GREP-like regular expressions are used (unless turned off in the Find Text dialog box.


See Also

Search|Find

Search|Replace


Overwrite Blocks (Environment Options)
Overwrite Blocks (Options|Environment|Editor|Options)

When the Overwrite Blocks option is on, the Persistent Blocks option is off, and a block of text is marked, typing a letter replaces the marked block with the letter typed.

If you do this . . .	The result is this . . .

Press DEL or Backspace	Clears entire selected text

Press a key or Edit|Paste	Replaces entire selected text

If the Overwrite Blocks option is off, typing a letter inserts that letter after the marked text, without affecting the block.

When both this option and the Persistent Blocks option is on, the text you enter is added to the currently selected block.


Persistent Blocks (Environment Options)
Persistent Blocks (Options|Environment|Editor|Options)

When Persistent Blocks option is on, marked blocks remain selected until they are deleted or unmarked, or another block is selected.

When this option is off, moving the cursor after a block that is selected de-selects the entire block of text.


Double Click Line (Environment Options)
Double Click Line (Options|Environment|Editor|Options)

When the Double Click Line option is checked, double clicking the mouse performs line selection, the entire line is selected (even if the line is blank). When this option is not checked, double-clicking the mouse performs word selection. If the cursor is past the end of the current line, then the last word on the line is selected. If the cursor is past the beginning of the line, then the first word on the line is selected. If the cursor is positioned between two words, the word it is closest to becomes selected. If the cursor is on a blank line, this has no affect.


Block Indent (Environment Options)
Block Indent (Options|Environment|Editor|Options)

Block Indent is an edit field which allows the user to specify the number of characters blocks are indented when the block indent and block outdent commands are used. The value you enter in the Block Indent input field must be in the range from 1 through 16.


Undo Limit (Environment Options)
Undo Limit (Options|Environment|Editor|Options)

See Also

Undo Limit is an edit field which allows you to specify the number of keystrokes that you can undo. Valid range is 0..32767.


See Also

Edit|Undo

Group Undo


Tab Stops (Environment Options)
Tab Stops (Options|Environment|Editor|Options)

See Also

Tab Stops is an edit field which allows the user to specify multiple tab stops. Valid entries correspond to a list of numbers in which each number must be greater than the number to its left. Tab Stops are set on each value. When the list of tab stops has been exhausted, tabs are set to the <last number entered> + (<last number entered> - <second to last number entered>).

Example

The values 3 6 9 12 25 would set tab stops at columns 3, 6, 9, 12, and 25. After column 25, each tab pressed will move the cursor 13 characters to the right.


See Also

Cursor Through Tabs

Use Tab Character


Editor|File (Environment Options)
Editor | File (Options|Environment|Editor|File)

The Editor|File options let you tailor the behavior of the IDE editor.

The options are:

Create Backup Files

Preserve Line Ends

Default Extension

Original Path

Mirror Path

Backup Path

Keystroke Mapping

Reserved Words


Create Backup Files (Environment Options)
Create Backup Files (Options|Environment|Editor|File)

When the Create Backup Files option is on and you choose File|Save, the Borland C++ IDE automatically creates a backup of the source file in the active Edit window.

The backup file has the extension .BAK.

The Mirror, Original, and Backup paths are all independent. The only relationship between each of these paths is the Create Backup files checkbox.

When the Create Backup option is off, these options are ignored. If the Create Backup option is turned back on, these options are restored to their current values.


Preserve Line Ends (Environment Options)
Preserve Line Ends (Options|Environment|Editor|File)

When the Preserve Line Ends option is checked, files are saved with their original line ends. When this option is not checked, files are saved with the Borland C++ default value for line ends.

This option allows the user to specify how the file writes line ends when a file is saved. You can always use the Borland C++ default value, or you can write the original line end of the file.

Line ends usually consist one of the following combination of characters:

LF

CR

LF CR

CR LF	(Borland C++ default)

where LF = Line Feed (ASCII value 10) and CR = Carriage Return (ASCII value 13).


Default Extension (Environment Options)
Default Extension (Options|Environment|Editor|File)

You use the Default Extension input box to tell the Borland C++ IDE which extension to use when loading source files that do not have an extension.

Ending a file name with a period indicates that the file should have a blank extension; the Borland C++ IDE will not add one.

Note:	Changing this extension does not affect the history lists in the current desktop.


Mirror Path (Environment Options)
Original Path (Options|Environment|Editor|File)

Use the Original Path edit field to specify a directory to store original versions, "snapshots," of changed files. The original version is considered a copy of the file that was initially opened during your current IDE session.

This file is created when the first modification is made to the original file, then it is never updated. The full path of the file is saved, and directories will be created if necessary.

Notes:

This option only takes affect when the Create Backup Files option is checked.

The Mirror, Original, and Backup paths are all independent. The only relationship between each of these paths is the Create Backup Files checkbox.

When the Create Backup Files option is off, these options are unavailable. If the Create Backup Files option is turned back on, these options are restored to their current values.


Original Path (Environment Options)
Mirror Path (Options|Environment|Editor|File)

Use the Mirror Path edit field to specify a directory to store the latest versions of a changed file. The full path of the file is saved, and directories will be created if necessary.

Notes:

This option only takes affect when the Create Backup Files option is checked.

The Mirror, Original, and Backup paths are all independent. The only relationship between each of these paths is the Create Backup Files checkbox.

When the Create Backup Files option is off, these options are unavailable. If the Create Backup Files option is turned back on, these options are restored to their current values.


Backup Path (Environment Options)
Backup Path (Options|Environment|Editor|File)

Use the Backup Path edit field to specify a directory where backup files should be stored.

Notes:

Backup files are only saved when the Create Backup Files option is checked. If the Backup Path edit field is blank, the backup files are stored in the current directory with a .BAK extension. Otherwise, they are saved with the complete file name.

The Mirror, Original, and Backup paths are all independent. The only relationship between each of them and the Create Backup Files checkbox.

When the Create Backup Files option is off, these options are unavailable. If the Create Backup Files option is turned back on, these options are restored to their current values.


Keystroke Mapping (Environment Options)
Keystroke Mapping (Options|Environment|Editor|File)

See Also

Use the Keystroke Mapping list box to select the keyboard binding (.CKB) file you want to use during an Borland C++ IDE session.

The default choices installed with the Borland C++ IDE are:

Internal (default)

Classic

Brief

Epsilon

TDW


See Also

Keyboard Shortcuts

Keymapper


Reserved Words (Environment Options)
Reserved Words (Options|Environment|Editor|File)

See Also

Use the Reserved Words list to select which set of keywords are to be supported by Syntax Highlighting options.


See Also

Setting Up Client Areas

Syntax Highlighting options


Editor|Display (Environment Options)
Editor | Display (Options|Environment|Editor|Display)

The Editor|Display options let you tailor the behavior of the IDE editor.

The options are:

BRIEF Cursor Shapes

Horizontal Scroll Bar

Vertical Scroll Bar

Font

Size

Visible Right Margin

Right Margin


BRIEF Cursor Shapes (Environment Options)
BRIEF Cursor Shapes (Options|Environment|Editor|Display)

Use the BRIEF Cursor Shapes option to toggle the cursor shapes in the Edit window.

The default Windows cursor is a vertical bar between characters. Turning the BRIEF Cursor Shapes option on causes the flashing text cursor to become an underline. This underline cursor will enlarge when it is located on virtual white space in the Edit window.


Show Scroll Bars (Environment Options)
Horizontal Scroll Bar (Options|Environment|Editor|Display)

When the Horizontal Scroll Bar option is on, horizontal scroll bars are displayed in active edit windows.

When this option is off, horizontal scroll bars will not be displayed in active edit windows.


Show Scroll Bars (Environment Options)
Vertical Scroll Bar (Options|Environment|Editor|Display)

When the Vertical Scroll Bar option is on, vertical scroll bars are displayed in active edit windows.

When this option is off, vertical scroll bars will not be displayed in active edit windows.


Font (Environment Options)
Font (Options|Environment|Editor|Display)

Use the Font list box to select the font you want to use in the IDE editor. The editor supports only monospaced fonts. Only monospaced fonts currently installed on your system will appear in the Font list box.


Size (Environment Options)
Size (Options|Environment|Editor|Display)

Use the Size list box to enter the point size for the editor font you selected in the Font list box by choosing one of the predefined sizes from the list.


Visible Right Margin (Environment Options)
Visible Right Margin (Options|Environment|Editor|Display)

See Also

When the Visible Right Margin option is on, you should see a light grey vertical line appear at the Right margin setting (default of 80). The margin will appear to the right of any character entered at the margin setting.

When the Visible Right Margin option is off, you should not see the light grey vertical line.

Note:	This is a visual setting only and has no affect on preventing the user from typing beyond the margin setting.


See Also

Right Margin


Right Margin (Environment Options)
Right Margin (Options|Environment|Editor|Display)

See Also

Right Margin is an edit field which allows the user to specify the Right Margin for edit windows. Valid entries here are 1..1024.


See Also

Visible Right Margin


Default Editor Options (Environment Options)
Default Editor Options

Option	Default	Classic	Brief	Epsilon

Auto Indent Mode	ON	ON	ON	ON

Backspace Unindents	ON	ON	ON	ON

Block Indent	3	3	3	3

BRIEF Cursor Shapes	OFF	OFF	ON	OFF

BRIEF Regular Expressions	OFF	OFF	ON	OFF

Cursor Beyond EOF	OFF	OFF	ON	OFF

Cursor Through Tabs	ON	ON	ON	ON

Double Click Line	OFF	OFF	OFF	OFF

Group Undo	OFF	OFF	ON	OFF

Insert Mode	ON	ON	ON	ON

Keep Trailing Blanks	OFF	OFF	ON	ON

Keymap	internal	classic	epsilon	brief

Optimal Fill	ON	ON	ON	ON

Overwrite Blocks	ON	OFF	OFF	OFF

Persistent Blocks	OFF	ON	OFF	OFF

Tab Stops	3	3	3	3

Undo After Save	OFF	OFF	OFF	OFF

Undo Limit	32767	32767	32767	32767

Use Tab Character	ON	ON	ON	ON


Librarian Settings (Project Options)
Librarian Options (Options|Project|Librarian)

Librarian options affect the behavior of the built-in Librarian. The built-in Librarian combines the .OBJ files in your project into .LIB files. Options in this section control that process. In addition, you can cause the librarian to generate a list (.LST) file containing the .OBJs in a generated .LIB and the functions those .OBJs contain.

The options are:

Generate List File

Case Sensitive Library

Purge Comment Records

Create Extended Dictionary

Library Page Size


Generate List File (Project Options)
Generate List File (Options|Project|Librarian)

When the Generate List File option is on, the Librarian automatically produces a list file (.LST) that lists the contents of your library when it is created.


Case-Sensitive Library (Project Options)
Case-Sensitive Library (Options|Project|Librarian)

(Command-line equivalent = /c)

When the Case-Sensitive Library option is on, the Librarian treats case as significant in all symbols in the library. For example, if Case-Sensitive Library is checked, "CASE", "Case", and "case" are all treated as different symbols.


Purge Comment Records (Project Options)
Purge Comment Records (Options|Project|Librarian)

(Command-line equivalent = /0)

When the Purge Comment Records option is on, the Librarian removes all comment records from modules added to the library.


Create Extended Dictionary (Project Options)
Create Extended Dictionary (Options|Project|Librarian)

(Command-line equivalent = /E)

When the Create Extended Dictionary option is on, the Librarian includes, in compact form, additional information that helps the linker process library files faster.


Library Page Size (Project Options)
Library Page Size (Options|Project|Librarian)

(Command-line equivalent = /Psize, where size is number of pages)

The Library Page Size input box is where you set the number of bytes in each library "page" (dictionary entry).

The page size determines the maximum size of the library. Page size must be a power of 2 between 16 and 32,768 inclusive. The default page size of 16 allows a library of about 1 MB in size.

To create a larger library, change the page size to the next higher value (32).


Linker Options (Project Options)
Linker Options (Options|Project|Linker)

Linker options affect how an application is linked.

Linker options let you control how intermediate files (.OBJ, .LIB and .RES) are combined into executables (.EXE) and dynamic-link libraries (.DLL). For most options in this section, you will usually want to keep the default settings.

The subtopics are:

General

Map File

16-bit Linker

32-bit Linker

Warnings


Linker | General (Project Options)
Linker | General (Options|Project|Linker|General)

Use the Linker|General options to include or exclude debugging information from your .EXE or .DLL. Debug information must be included in your program if you want to use the debugger (you can turn it off for production versions).

The options are:

Case Sensitive Link

Case Sensitive Exports and Imports (16-bit only)

Include Debug Information

Default Libraries

Pack Code Segments

Code Pack Size


Case-Sensitive Link (Project Options)
Case-Sensitive Link (Options|Project|Linker|General)

(Command-line equivalent = /c)

When the Case-Sensitive Link option is on, the linker is case sensitive. Normally, this option should be checked, since C and C++ are both case-sensitive languages.

Default = ON


Case-Sensitive Exports and Imports (Project Options)
Case Sensitive Exports and Imports (Options|Project|Linker|General)

(Command-line equivalent = /C or /C+)

(16-bit only)

When the Case-Sensitive Exports option is on, the linker is case sensitive when it processes the names in the IMPORTS and EXPORTS sections of the module definition file.

When this option is off, the linker ignores case.

Use this option when you are trying to export non-callback functions from DLLs, as in exported C++ member functions or dynamic versions of ObjectWindows Library and BIDS.

Do not use this option for normal Windows callback functions (declared FAR PASCAL).

Default = OFF


Include Debug Information (Project Options)
Include Debug Information (Options|Project|Linker|General)

(Command-line equivalent = /v)

When the Include Debug Information option is on, the linker includes information in the output file needed to debug your application with the Borland C++ Integrated Debugger (or the Turbo Debugger).


Default Libraries (Project Options)
Default Libraries (Options|Project|Linker|General)

(Command-line equivalent = /n)

When you are linking with modules created by a compiler other than the Borland C++ compiler, the other compiler might have placed a list of default libraries in the object file.

When the Default Libraries option is on, the linker tries to find any undefined routines in these libraries and in the default libraries supplied by the C++ IDE.

When this option is off, the linker searches only the default libraries supplied by the C++ IDE and ignores any defaults in .OBJ files. You might want to leave this option off when linking modules written in another language.

Default = ON


Pack Code Segments (Project Options)
Pack Code Segments (Options|Project|Linker|General)

(Command-line equivalent = /P)

When the Pack Code Segments option is on, the linker tries to minimize the number of code segments by packing multiple code segments together. This typically improves performance.

This option applies only to Windows applications and DLLs. This option will never create segments greater than 64K. A new segment is started if needed.

Because there is a certain amount of system overhead for every segment maintained, code segment packing, by reducing the number of segments to maintain, typically increases performance.

Default = ON


Code Pack Size input box (Project Options)
Code Pack Size (Options|Project|Linker|General)

(Command-line equivalent = /P=n, where n specifies the number of bytes between 1 and 65,536)

Use Code Pack Size to change the default code-packing size to any value between 1 and 65,536.

Default = 8192 bytes


Linker|Map File (Project Options)
Linker | Map File (Options|Project|Linker|Map File)

Linker|Map File options tell what type of map file to produce. You can configure your map file output using the Map File options which gives you information on segment ordering, segment sizes, and public symbols.

The options are:

Off

Segments

Publics

Detailed

Print Mangled Names In Map File

Include Source Line Numbers


Map File (Project Options)
Map File (Options|Project|Linker|Map File)

You use the Map File options to choose the type of map file to be produced at link time.

For settings other than Off, the map file is placed in the output directory defined in the Directories|Output page

Off

The Off option tells the linker not to create a map file. Off is the default.

Segments

(Command-line equivalent = /s)

The Segments option tells the linker to produce a map file that includes a list of segments, the program start addresses, and any warning or error messages generated during the link.

Publics

(Command-line equivalent = /M)

The Publics option tells the linker to produce the same map file that Segments produces with a list of public symbols added (sorted alphabetically as well as in increasing address order). This kind of map file is useful in debugging. Many debuggers can use the list of public symbols to allow you to refer to symbolic addresses when you are debugging.

Detailed

(Command-line equivalent = /x)

The Detailed option tells the linker to produce the same map file that Publics produces with a detailed segment map added.

The detailed segment map includes the address, length in bytes, class, segment name, group, module, and ACPB information.

See Also

Linker|Map File


Print Mangled Names In Map File (Project Options)
Print Mangled Names In Map File (Options|Project|Linker|Map File)

(Command-line equivalent for 32-bit = /Gx, where x=m; command-line equivalent for 16-bit = /M)

Prints the mangled C++ identifiers in the map file, not the full name.

Default = OFF


Include Source Line Numbers (Project Options)
Include Source Line Numbers (Options|Project|Linker|Map File)

(Command-line equivalent: -y)

When the Include Source Line Numbers option is on, the compiler automatically includes line numbers in the object and object map files (the latter for use by a symbolic debugger).

Including line numbers increases the size of the object and map files but does not affect the speed of the executable program.

When Include Source Line Numbers is on, make sure you turn Jump Optimizations off in the Optimization|Specific options page. Otherwise, the compiler might group together common code from multiple lines of source text during jump optimization, or it might reorder lines (which makes line-number tracking difficult.)

Default = OFF


Linker|16-Bit Options (Project Options)
Linker | 16-bit Linker (Options|Project|Linker|16-bit Linker)

16-bit Linker options tell the linker how to link 16-bit programs.

The options are:

Initialize Segments

Inhibit Optimizing Far Call To Near

Enable 32-bit Processing

Segment Alignment

Linker goodies

Discard Nonresident Name Table

Transfer Resident Names to Nonresident Names Table


Initialize Segments (Project Options)
Initialize Segments (Options|Project|Linker|16-bit Linker)

(Command-line equivalent = /i)

When the Initialize Segments option is on, the linker initializes uninitialized trailing segments to be output into the executable file even if the segments do not contain data records. This is normally not needed and will make your .EXE files larger.


Inhibit Optimizing Far Call To Near (Project Options)
Inhibit Optimizing Far Call To Near (Options|Project|Linker|16-bit Linker)

(Command-line equivalent = /f)

When the linker patches two code segments together, and far calls are made from one to the other, the linker will optimize the code by converting the far calls to near calls. When Inhibit Optimizing Far Call To Near is enabled, this optimization does not occur.

You might want to enable this option when you experience run-time crashes that appear to be related to corruption of the virtual tables. Because virtual tables reside in the code segment, their contents can sometimes be interpreted by the linker as one of these far calls.

Default = OFF


Process Extended Dictionary (Options|Project|Linker|16-bit Linker)

(Command-line equivalent to ignore extended dictionaries = /e; command-line equivalent to process extended dictionaries = /E)

The Enable Extended Dictionary option indicates whether the linker should use the extended dictionary of a library to search for symbols.

The library files that are shipped with Borland C++ all contain an extended dictionary with information that enables the linker to link faster with those libraries. Although linking with libraries that contain an extended dictionary is faster, you might want to leave this option off if you have a program that needs slightly more memory to link when an extended dictionary is used.

When Enable Extended Dictionary is set to off, the linker will ignore any debugging information contained in a library that has an extended dictionary.

Default = OFF


Enable 32-bit Processing (Project Options)
Enable 32-bit Processing (Options|Project|Linker|16-bit Linker)

(Command-line equivalent = /3)

The Enable 32-bit processing option lets you link 32-bit DOS object modules produced by TASM or a compatible assembler. This option increases the memory requirements for TLINK and slows down linking.


Segment input box (Project Options)
Segment Alignment (Options|Project|Linker|16-bit Linker)

(Command-line equivalent = /A:dd)

Use the Segment input box to change the current byte value on which to align segments. You can enter numbers in the range of 2 to 65,535.

Note:	The alignment factor is automatically rounded up to the nearest power of two. For example, if you enter 650, it is rounded up to 1,024.

For efficiency, you should use the smallest value that still allows for correct segment offsets in the segment table.


Discard Nonresident Name Table (Project Options)
Discard Nonresident Name Table (Options|Project|Linker|16-bit Linker)

(Command-line equivalent = /Gx, where x=n)

When the Discard Nonresident Name Table option is enabled, nonresident name tables are marked as discardable. This allows Windows to discard them if it needs to free up memory resources.

Default = OFF


Transfer Resident Names to Nonresident Names Table (Project Options)
Transfer Resident Names to Nonresident Names Table (Options|Project|Linker|16-bit Linker)

(Command-line equivalent = /Gx, where x=r)

When the transfer resident names to nonresident names table option is enabled, exported names are automatically assigned an ordinal value. This speeds the lookup process at runtime, and frees you from having to specify ordinal values in the .DEF file.

Default = OFF


Linker|32-Bit Options (Project Options)
Linker | 32-bit Linker (Options|Project|Linker|32-bit Linker)

32-bit Linker options tell the linker how to link 32-bit programs.

The options are:

Image is Based

Image is Based Address (in Hexadecimal)

File Alignment

Stack Size (in Hexadecimal)

Maximum Linker Errors


Image is Based (Project Options)
Image is Based (Options|Project|Linker|32-bit Linker)

The Image is Based option affects whether an application has an image base address. If this setting is turned on, internal fixups are removed from the image and the requested load address of the first object in the application is set to the number specified in the Address input box. This can greatly reduce the size of your final application module. It is not recommended for use when producing a DLL.


Image Is Based Address (in hexadecimal) (Project Options)
Image Is Based Address (in Hexadecimal) (Options|Project|Linker|32-bit Linker)

The Image Is Based Address options specifies whether an application has an image base address. If this setting is turned on, internal fixups are removed from the image and the requested load address of the first object in the application is set to 0x10000. This can greatly reduce the size of your final application module.

Note:	It is not recommended that you enable this option when producing a DLL.


File Alignment (Project Options)
File Alignment (Options|Project|Linker|32-bit Linker)

(Command-line equivalent = /A:dd, where dd must be a decimal power of 2)

The File Alignment option specifies page alignment for code and data within the executable file. The value you enter must be a decimal power of 2. For example, if you specify an alignment value of 12, the pages of code and data are stored on 4096-byte boundaries. Windows will seek pages for loading based on this alignment value. The default is 9, which means pages are aligned on 512-byte boundaries within the executable file.


Stack Size (in hexadecimal) (Project Options)
Stack Size (in Hexadecimal) (Options|Project|Linker|32-bit Linker)

(Command-line equivalent = /S:xxxx, where xxxx is a hexadecimal string)

Valid for 32-bit applications only. Specifies stack size (in hexadecimal) where the number entered is a hexadecimal string. Specifying the stack size here overrides any stack-size setting in a module-definition file.


Maximum Linker Errors (Project Options)
Maximum Linker Errors (Options|Project|Linker|32-bit Linker)

(Command-line equivalent = /Enn)

Specifies maximum errors the linker reports before terminating. /E0 (default) reports an infinite number of errors (that is, as many as possible).


Linker|Warnings (Project Options)
Linker | Warnings (Options|Project|Linker|Warnings)

Warnings options enable or disable the display of Linker warnings.

The options are:

Warn Duplicate Symbol in .LIB

"No Stack" Warning

32 bit warnings

No Entry Point

Duplicate Symbol

No Def File

Import Does Not Match Previous Definition

Extern not Qualified with Import

Using Based Linking in DLL

Self-relative Fixup Overflowed


Warn duplicate symbol in .LIB (Project Options)
Warn Duplicate Symbol in .LIB (Options|Project|Linker|Warnings)

See Also

(Command-line equivalent = /d)

When the Warn Duplicate Symbols option is on, the linker warns you of duplicate symbols in object and library files.

When this option is off, if a symbol must be included in the program, the linker will use the copy of that symbol in the first file on the command line in which it is found. Since this is a commonly used feature, the linker does not normally warn about the duplicate symbols.

Default = OFF


See Also

Generate COMDEFs


Make Options (Project Options)
Make Options (Options|Project|Make)

Make options control the conditions under which the building of a project stops and how the project manager uses autodependency information.

The options are:

Break Make On

Autodependencies

New Node Path


Break Make On (Project Options)
Make | Break Make On (Options|Project|Make)

The Make|Break Make On options specify the error condition that stops the making of a project.

Warnings

This option stops a make when the compiler encounters warnings.

Errors

This option stops a make when the compiler encounters errors.

Fatal Errors

This option tells the Project Manager to generate a list of errors and warnings for all files and all targets in the project. The Project Manager will go on to link if no errors occur.

Default = Errors


Auto-Dependencies (Project Options)
Make | Autodependencies (Options|Project|Make)

When the Make|Autodependencies option is selected, the Project Manager automatically checks dependencies for every target that has a corresponding source file in the project list.

None

When None is selected, no autodependency checking is performed.

Use

When Use is selected, autodependency checking is performed by reading the autodependency information out of the .OBJ files.

Cache

When Cache is selected, autodependency information is stored in memory to make dependency checking faster. This option speeds up compilation, but autodependency information will not display in the project tree.

Cache and Display

When Cache and Display is selected, the Project Manager stores the autodependency information in the project file and displays it in the project tree. This makes dependency checking faster, but makes project files larger.


Make|New Node Path (Project Options)
Make | New Node Path (Options|Project|Make)

Turn on the Absolute option if you want new nodes to have an absolute, instead of a relative, path.


Messages Settings (Project Options)
Messages Options (Options|Project|Messages)

Messages options let you control the messages output by the IDE compiler. Compiler messages are indicators of potential trouble spots in your program. These messages can warn you of many kinds of problems that may be waiting to happen, such as variables and parameters that are declared but never used, type mismatches, and many others.

The subtopics are:

Portability

ANSI Violations

Obsolete C++

Potential C++ Errors

Inefficient C++ Coding

Potential Errors

Inefficient Coding

General

Display Warnings

All

Selected

None

Stop after ... warnings

Stop after ... errors


Display Warnings (Project Options)
Display Warnings (Options|Project|Messages)

Use the Display Warnings options to choose which warnings are displayed.

All

(Command-line equivalent: -w)

Display all types of warnings.

Selected

(Command-line equivalent: -wxxx)

Choose which warnings are displayed. Using pragma warn in your source code overrides messages options set either at the command line or in the IDE.

None

Display no warnings. Errors are still displayed.

Default = Selected


Stop After ... warnings (Project Options)
Stop After ... Warnings (Options|Project|Messages)

(Command-line equivalent: -gn)

Warnings: Stop After causes compilation to stop after the specified number of warnings has been detected.

The default is 100, but you can enter any number from 0 to 255.

Entering 0 causes compilation to continue until either the end of the file or the error limit set in Errors: Stop After has been reached, whichever comes first.


Stop After ... errors (Project Options)
Stop After ... Errors (Options|Project|Messages)

(Command-line equivalent: -jn)

Errors: Stop After causes compilation to stop after the specified number of errors has been detected.

The default is 25, but you can enter any number from 0 to 255.

Entering 0 causes compilation to continue until the end of the file.


Messages|Portability (Project Options)
Messages | Portability (Options|Project|Messages|Portability)

Compiler Messages|Portability options enable or disable individual warning messages about statements that might not operate correctly in all computer environments.

The options are:

Non-portable pointer conversion

Non-portable pointer comparison

Constant out of range in comparison

Constant is long

Conversion may lose significant digits

Mixing pointers to signed and unsigned char


Messages|ANSI Violations (Project Options)
Messages | ANSI Violations (Options|Project|Messages|ANSI Violations)

Compiler Messages|ANSI Violations options enable or disable individual warning messages about statements that violate the ANSI standard for the C language.

The options are:

Void functions may not return a value

Both return and return of a value used

Suspicious pointer conversion

Undefined structure 'ident'

Redefinition of 'ident' is not identical

Hexadecimal value more than three digits

Bit fields must be signed or unsigned int

'ident' declared as both external and static

Declare 'ident' prior to use in prototype

Division by zero

Initializing 'ident' with 'ident'

Initialization is only partially bracketed


Messages|Obsolete C++ (Project Options)
Messages | Obsolete C++ (Options|Project|Messages|Obsolete C++)

Compiler Messages|Obsolete C++  options choose which specific obsolete items or incorrect syntax C++ warnings to display.

The options are:

Base initialization without class name is obsolete

This style of function definition is obsolete

Overloaded prefix operator used as a postfix operator


Messages|Potential C++ Errors (Project Options)
Messages | Potential C++ Errors (Options|Project|Messages|Potential C++ Errors)

Compiler Messages|Potential C++ Errors options enable or disable individual warning messages about statements that violate C++ language implementation.

The options are:

Constant member 'ident' is not initialized

Assigning 'type' to 'enumeration'

'function' hides virtual function 'function2'

Non-const function 'ident' called for const object

Base class 'ident' inaccessible because also in 'ident'

Array size for 'delete' ignored

Use qualified name to access nested type 'ident'

Handler for '<type1>' Hidden by Previous Handler for '<type2>'

Conversion to 'type' will fail for virtual base members

Maximum precision used for member pointer type type

Use '> >' for nested templates instead of '>>'

Non-volatile function function called for volatile object


Messages|Inefficient C++ Coding (Project Options)
Messages | Inefficient C++ Coding (Options|Project|Messages|Inefficient Coding)

Compiler Messages|Inefficient C++ Coding options enable or disable individual warning messages about inefficient C++ coding.

The options are:

Functions containing 'ident' not expanded inline

Temporary used to initialize 'ident'

Temporary used for parameter 'ident'


Messages|Potential Errors (Project Options)
Messages | Potential Errors (Options|Project|Messages|Potential Errors)

Compiler Messages|Potential Errors options enable or disable individual warning messages about potential coding errors.

The options are:

Possibly incorrect assignment

Possible use of 'ident' before definition

No declaration for function 'ident'

Call to function with no prototype

Function should return a value

Ambiguous operators need parentheses

Condition is always (true/false)


Messages|Inefficient Coding (Project Options)
Messages | Inefficient Coding (Options|Project|Messages|Inefficient Coding)

Compiler Messages|Inefficient Coding options are used to enable or disable individual warning messages about inefficient coding.

The options are:

'ident' assigned a value which is never used

Parameter 'ident' is never used

'ident' declared but never used

Structure passed by value

Unreachable code

Code has no effect


Messages|General (Project Options)
Messages | General (Options|Project|Messages|General)

Compiler Messages|General options enable or disable a few general warning messages.

The options are:

Unknown assembler instruction

Ill-formed pragma

Array variable 'ident' is near

Superfluous & with function

'ident' is obsolete

Cannot create precompiled header

User-defined warnings


User-Defined Warnings (Project Options)
User-Defined Warnings (Options|Project|Messages|General)

(Command-line equivalent: -wmsg)

The User-defined warnings option allows user-defined messages to appear in the IDE's Message Window. User-defined messages are introduced with the #pragma message compiler syntax.

Note:	In addition to messages that you introduce with the #pragma message compiler syntax, User-defined warnings allows warnings introduced by third party libraries to be displayed. Remember, if you need Help on a third party warning, please contact the vendor of the header file that issued the warning.

Default = ON


Calling Conventions

16-bit calling conventions

32-bit calling conventions


Optimizations Settings (Project Options)
Optimizations Options (Options|Project|Optimizations)

See Also

Optimization options are the software equivalent of performance tuning. There are three categories of optimizations provided for in this section:

those that make your code smaller

those that make your code faster

other general optimizations.

The subtopics are:

Specific

Size

Speed

Settings

Disable All Optimizations


See Also

Pentium instruction set option


Disable all optimizations (Project Options)
Disable All Optimizations (Options|Project|Optimizations)

(Command-line equivalent: -Od)

Disables all of the optimization options, including those which would normally be performed as part of the speed/size tradeoff.

Because this disables code compaction (Tail merging) and cross-jump optimizations, using this option can keep the debugger from jumping around or returning from a function without warning.

Note:	You can override this setting by using named options sets in the project manager.


Optimizations|Specific (Project Options)
Optimizations | Specific (Options|Project|Optimizations|Specific)

Compiler Optimization|Specific options set specific optimizations.

The options are:

Select Code in Favor of

Executable Speed

Executable Size

Common Subexpressions

No Optimization

Optimize Locally

Optimize Globally

Assume No Pointer Aliasing


Select code in favor of: (Project Options)
Select Code in Favor of (Options|Project|Optimizations|Specific)

Use the Select Code in Favor of options to change the compiler's code-generation strategy.

Executable Speed

(Command-line equivalents: -Ot, -G)

The Executable Speed option tells the C++ IDE to optimize your code for speed. When you optimize for speed, the compiler chooses the fastest sequence for a given task. It determines whether it can safely generate code to perform a rep movsw instruction instead of calling a helper function to do the copy. This produces faster structure copies for structures and unions over eight bytes long than does the helper function call.

If you are creating Windows applications, you'll probably want to optimize for speed.

Executable size

(Command-line equivalent: -Os)

The Executable Size option tells the C++ IDE to optimize your code for size by scanning the generated code for duplicate sequences. When such sequences warrant, the optimizer replaces one sequence of code with a jump to the other and eliminates the first piece of code. This occurs most often with switch statements. Normally the compiler optimizes for size, choosing the smallest code sequence possible.


Common Subexpression (Project Options)
Common Subexpression (Options|Project|Optimizations|Specific)

The Common Subexpressions options tell the compiler how to find and eliminate duplicate expressions in your code.

No Optimization

When the No Optimization option is on, the compiler does not eliminate common subexpressions.

Optimize Locally

(Command-line equivalent: -Oc)

When the Optimize Locally option is on, the compiler eliminates common subexpressions within groups of statements unbroken by jumps (basic blocks).

Optimize Globally

(Command-line equivalent: -Og)

When the Optimize Globally option is on, the compiler eliminates common subexpressions within an entire function. This option globally eliminates duplicate expressions within the target scope and stores the calculated value of those expressions once (instead of recalculating the expression).

Although in theory this optimization could reduce code size, it optimizes for speed and rarely results in size reductions. Use this option if you prefer to reuse expressions rather than create explicit stack locations for them.


Assume No Pointer Aliasing (Project Options)
Assume No Pointer Aliasing (Options|Project|Optimizations|Specific)

(Command-line equivalent: -Oa)

When the Assume No Pointer Aliasing option is on, the compiler assumes that pointer expressions are not aliased in common subexpression evaluation.

Assume No Pointer Aliasing affects the way the optimizer performs common subexpression elimination and copy propagation by allowing the optimizer to maintain copy propagation information across function calls and to maintain common subexpression information across some stores. Without this option the optimizer must discard information about copies and subexpressions. Pointer aliasing might create bugs that are hard to spot, so it is only applied when you use Assume No Pointer Aliasing.

Assume No Pointer Aliasing controls how the optimizer treats expressions with pointers in them. When compiling with global or local common subexpressions and Assume No Pointer Aliasing is enabled, the optimizer recognizes *p * x as a common subexpression in function func1.

  int g, y;

  int func1(int *p)

  {

    int x=5;

    y = *p * x;

    g = 3;

    return (*p * x);

  }

  void func2(void)

  {

    g=2;

    func1(&g);  // This is incorrect--the assignment g = 3

                // invalidates the expression *p * x

  }


Optimizations|Size (Project Options)
Optimizations | Size

Use the Optimizations|Size options to change the compiler's code-generation strategy, specify how to find and eliminate duplicate expressions in your code, and affect the way the optimizer performs common subexpression elimination and copy propagation.

The options are:

Jump Optimizations

Loop Optimization

Suppress Redundant Loads

Dead Code Elimination

Windows Prolog/Epilog

Global Register Allocation


Jump Optimization (Project Options)
Jump Optimization (Options|Project|Optimizations|Size)

(Command-line equivalent: -O)

When the Jump Optimization option is on, the compiler reduces the code size by eliminating redundant jumps and reorganizing loops and switch statements.

When this option is on, the sequences of tracing and stepping in the debugger can be confusing, because there might be multiple lines of source code associated with a particular generated code sequence.

When this option is off, you'll get the best stepping results while debugging.


Loop Optimization (Project Options)
Loop Optimization (Options|Project|Optimizations|Size)

(Command-line equivalent: -Ol)

When the Loop Optimization option is on, loops are compacted into REP/STOSx instructions.

Loop optimization takes advantage of the string move instructions on the 80x86 processors by replacing the code for a loop with a string move instruction, making the code faster.

Depending on the complexity of the operands, the compacted loop code can also be smaller than the corresponding non-compacted loop.


Suppress Redundant Loads (Project Options)
Suppress Redundant Loads (Options|Project|Optimizations|Size)

(Command-line equivalent: -Z)

When the Suppress Redundant Loads option is on, the compiler suppresses the reloading of registers by remembering the contents of registers and reusing them as often as possible.

Exercise caution when using this option. The compiler cannot detect if a value has been modified indirectly by a pointer.


Dead Code Elimination (Project Options)
Dead Code Elimination (Options|Project|Optimizations|Size)

(Command-line equivalent: -Ob)

When the Dead Code Elimination option is on, the compiler reveals variables that might not be needed.


Global Register Allocation (Project Options)
Global Register Allocation (Options|Project|Optimizations|Size)

(Command-line equivalent: -Oe)

When the Global Register Allocation option is on, global register allocation and variable live range analysis are enabled. This option should always be used when optimizing code, because it increases the speed and decreases the size of your application.


Windows Prolog/Epilog (Project Options)
Windows Prolog/Epilog (Options|Project|Optimizations|Size)

(Command-line equivalent: -OW)

Use the Windows Prolog/Epilog option to suppress the bp inc/dec on Windows far functions (16-bit only).


Optimizations|Speed (Project Options)
Optimizations | Speed (Options|Project|Optimizations|Speed)

Use the Optimizations|Speed options to specify how common memory functions are handled, to move invariant code out of loops, to handle copies of constants, variables, and expressions, and to create loop induction variables, and to enable strength reduction optimizations.

The options are:

Inline Intrinsic Functions

Invariant Code Motion

Copy Propagation

Induction Variables


Inline Intrinsic Functions (Project Options)
Inline Intrinsic Functions (Options|Project|Optimizations|Speed)

(Command-line equivalent: -Oi)

When the Inline Intrinsic Functions option is on, the compiler generates the code for common memory functions like strcpy() within your function's scope, eliminating the need for a function call. The resulting code executes faster, but it is larger.

Note:	You can control the inlining of these functions with the pragma intrinsic. For example, #pragma intrinsic strcpy causes the compiler to generate inline code for all subsequent calls to strcpy in your function, and #pragma intrinsic -strcpy prevents the compiler from inlining strcpy. Using these pragmas in a file overrides compiler options.

When inlining any intrinsic function, you must include a prototype for that function before you use it, because the compiler creates a macro that renames the inlined function to a function that the compiler recognizes internally. In the previous example, the compiler would create a macro #define strcpy _ _strcpy_ _.

The compiler recognizes calls to functions with two leading and two trailing underscores and tries to match the prototype of that function against its own internally stored prototype. If you don't supply a prototype or if the prototype you supplied doesn't match the compiler's prototype, the compiler rejects the attempt to inline that function and generates an error.


Invariant Code Motion (Project Options)
Invariant Code Motion (Options|Project|Optimizations|Speed)

(Command-line equivalent: -Om)

When the Invariant Code Motion option is on, invariant code is moved out of loops and your code is optimized for speed. The optimizer uses information about all the expressions in the function (gathered during common subexpression elimination) to find expressions whose values do not change inside a loop.

To prevent the calculation from being done many times inside the loop, the optimizer moves the code outside the loop so that it is calculated only once. The optimizer then reuses the calculated value inside the loop.

You should use loop-invariant code motion whenever you are compiling for speed and you have used global common subexpressions, because moving code out of loops can result in enormous speed gains. For example, in the following code,  x * y * z is evaluated in every iteration of the loop:

int v[10];

void f(void)

{

  int i,x,y,z;

  for (i = 0; i < 10; i++)

    v[i] = x * y * z;

}

The optimizer rewrites the code:

int v[10];

void f(void)

{

  int i,x,y,z,t1;

  t1 = x * y * z;

  for (i = 0; i < 10; i++)

    v[i] = t1;

}


Copy Propagation (Project Options)
Copy Propagation (Options|Project|Optimizations|Speed)

(Command-line equivalent: -Op)

When the Copy Propagation option is on, copies of constants, variables, and expressions are propagated whenever possible.

Copy propagation is primarily speed optimization, but it never increases the size of your code. Like loop-invariant code motion, copy propagation relies on the analysis performed during common subexpression elimination. Copy propagation means that the optimizer remembers the values assigned to expressions and uses those values instead of loading the value of the assigned expressions. Copies of constants, expressions, and variables can be propagated.


Induction Variables (Project Options)
Induction Variables (Options|Project|Optimizations|Speed)

(Command-line equivalent: -Ov)

When the Induction Variables option is on, loop induction variables are created and strength reduction optimization is enabled, which optimizes for speed.

Use this option when you're compiling for speed and your code contains loops. The optimizer uses induction to create new variables (induction variables) from expressions used in loops. The optimizer assures that the operations performed on these new variables are computationally less expensive (reduced in strength) than those used by the original variables.

Optimizations are common if you use array indexing inside loops, because a multiplication operation is required to calculate the position in the array that is indicated by the index. For example, the optimizer creates an induction variable out of the operation v[i] in the following code because the v[i] operation requires multiplication, which also eliminates the need to preserve the value of i:

int v[10];

void f(void)

{

  int i,x,y,z;

  for (i = 0; i < 10; i++)

     v[i] = x * y * z;

}

With Induction variables enabled, the code changes:

int v[10];

void f(void)

{

  int i,x,y,z, *p;

  for (p = v; p < &v[10]; p++)

    *p = x * y * z;

}


Preferences Options (Environment Options)
Preferences Options (Options|Environment|Preferences)

The Options|Environment|Preferences options let you set source tracking options and control what desktop information is saved when you exit the Borland C++ IDE, build or make a project, use a transfer tool, run the integrated debugger, close a project, save a project, or switch to another project.

The options are:

Save In Desktop

Message Window

Auto-Save

Source Tracking


Save In Desktop (Environment Options)
Save In Desktop (Options|Environment|Preferences)

See Also

The Preferences|Save In Desktop options let you specify what parts of the desktop you want saved when you exit the Borland C++ IDE, build or make a project, use a transfer tool, run the integrated debugger, close a project, save a project, or switch to another project.

The options are:

History Lists

When the History Lists option is on, history lists are saved across sessions.  Default = ON.

Watch Expressions

When the Watch Expressions option is on, watch expressions are saved across sessions. Default = ON.

Breakpoints

When the Breakpoints option is on, breakpoints are saved across sessions. Default = ON.

Open Windows

When the Open Windows option is on, the position and content of any open windows are saved across sessions. Default = ON.

Closed Windows

When the Closed Windows option is on, the list of closed windows that appears at the bottom of the File menu is saved across sessions. Default = ON.


See Also

Adding a Watch

Debugging in the IDE

Setting Breakpoints


Auto-Save (Environment Options)
Auto-Save (Options|Environment|Preferences)

The Preferences|Auto-Save options specify what is automatically saved when you exit the Borland C++ IDE, build or make a project, use a transfer tool, run the integrated debugger, close a project, save a project, or switch to another project.

The options are:

Editor Files

Environment

Desktop

Project


Editor Files (Environment Options)
Editor Files (Options|Environment|Preferences)

When the Editor Files option is on, the Borland C++ IDE automatically saves the modified file in the active Edit window when you exit the Borland C++ IDE, build or make a project, use a transfer tool, run the integrated debugger, close a project, save a project, or switch to another project.

Default = OFF


Environment (Environment Options)
Environment (Options|Environment|Preferences)

When the Environment option is on, the Borland C++ IDE also saves the settings to disk when you exit the Borland C++ IDE, build or make a project, use a transfer tool, run the integrated debugger, close a project, save a project, or switch to another project.

If you turn the Environment option off, you must use the Options|Save command to save the environment settings to disk.

Default = ON


Desktop (Environment Options)
Desktop (Options|Environment|Preferences)

When the Desktop option is on, the IDE saves your desktop files in the file PRJNAME.DSW.

Each project file has a corresponding desktop file that contains state information about the associated project.

Desktop information saved includes the following:

context information for each file in the project (position in the file, location of the window on the screen, etc.)

history lists for various input boxes

layout of the windows on the desktop

If you turn the Desktop option off, you must use the Options|Save command to save the desktop settings to disk.

Default = ON


Project (Environment Options)
Project (Options|Environment|Preferences)

When the Project option is on, the Borland C++ IDE saves your project, autodependency, and default style sheet settings on exit and restores them when you return to the IDE and load that project.

The project file contains the information required to build the executable targets of the project (FILENAME.EXE or FILENAME.DLL).

The build information consists of the following:

source files and libraries

compiler options

include, library, and output paths

linker options

build options and attributes

transfer tools

Default = ON


Message Window (Environment Options)
Message Window (Options|Environment|Preferences)

Preferences|Save Old Messages option, tells the Borland C++ IDE to save error messages currently in the Message window.

Note:	Only transfer items that prompt for a command line will have their messages saved. They will be saved only when the command line for the tool being run has been modified, (i.e. when you are prompted from transfer items for a command line, like GREP). In every other case, the messages will be removed. Simple compiles do not save messages.

To change the command line for internal tools, use the Options|Tools command.

Default = OFF


Source Tracking (Environment Options)
Source Tracking (Options|Environment|Preferences)

The Preferences|Source Tracking options specify whether the Borland C++ IDE opens a new Edit window or uses the current one as you step through your code to a file that's not already loaded in an Edit window. This setting is also used when you open edit windows by double-clicking on a message in the Message window.

New Window

When the New Window option is on, the Borland C++ IDE opens a new Edit window whenever it encounters a source file that is not already loaded. This is the default setting.

Current Window

When the Current Window option is on, the Borland C++ IDE replaces the contents of the active Edit window whenever it loads a new file.


Project View Options (Environment Options)
Project View Options (Options|Environment|Project View)

See Also

Use the Options|Environment|Project View options to specify what types of nodes appear in the Project Hierarchy and what information appears with each node.

The options are:

Build Translator

Choose the Build Translator option to display the translator associated with the node.

Code Size

Choose the Code Size option to display the total size in bytes of code segments. This information appears only after the node has been built.

Data Size

Choose the Data Size option to display the size (in bytes) of the data segment. This information appears only after the node has been built.

Description

Choose the Description option to display a description of the node. Type the description using the Edit node attributes dialog box from the Project Window SpeedMenu.

Location

Choose the Location option to display the path to the file associated with the node.

Name

Choose the Name option to display the name of the file associated with the node.

Number of Lines

Choose the Number of Lines option to display the number of lines in the file associated with the node. This information appears only after the node has been built.

Node Type

Choose the Node Type option to display the type associated with a node. Some node-types are assigned by the system such as [AppExpert] and[SourcePool] but most node-types are a reflection of a file extension: [.cpp], [.exe], [.def], etc.

Every node in a project is an instance of a node-type. It's the node type that determines which viewers and translators will be available for instances of that node-type.

Note:	You can manipulate which viewers and translators are available through Options|Tools in the 'Advanced' dialog under 'Applies to', 'Translate from' and 'to' edit fields.

The Project Manager and MAKE engine look to the node-type field to determine how to deal with each node. For example, the node name might be 'myfile.cxx' but if the node-type is [.cpp] the file will be treated as if it had a .cpp extension and all the C++ translator and viewers will be available to the 'myfile.cxx' node.

Note:	 You can manipulate an individual node's name and type through the Project Window's SpeedMenu 'Edit node attributes' command.

Style Sheet

Choose the Style Sheet option to display the name of the style sheet attached to a node.

Output

Choose the Output option to display the name of the file (and its path) that is created when the node is translated. For example, a .CPP node creates an .OBJ file.

Show Runtime Nodes

Choose the Show Runtime Nodes option to display the standard libraries and startup code used when a target is built.

Show Project Node

Choose the Show Project Node option to show the top-level node associated with the entire project. The project node is built when you choose Project|Build All.

Note:	All targets are dependents of the project node.


See Also

Edit Node Attributes

Styles Sheets (defined)

translators (defined)


Resources Settings (Project Options)
Resources Options (Options|Project|Resources)

Resource options let you set several options for how resources are compiled and bound to your application by the integrated resource compiler and resource linker.

The options are:

Target Windows Version

Language for Win32 (available for Target Windows Version Win32 only)

Pack Fastload Area


Target Windows Version (Project Options)
Target Windows Version (Options|Project|Resources)

The Target Windows Version group of options sets the earliest version of Windows under which your application can run. If you're using any features specific to Windows 3.1, you should check Windows 3.1 to ensure that your application won't run under Windows 3.0.

Windows 3.0

Sets the earliest version of Windows under which your application can run to Windows 3.0.

Windows 3.1

Sets the earliest version of Windows under which your application can run to Windows 3.1.

Win32

Sets the earliest version of Windows under which your application can run to Win32.


Language for Win32 (Project Options)
Language for Win32 (Options|Project|Resources)

Use the Language for Win32 list boxes to select the base and sublanguages to be used for the resources in the your project. For example, you might define your resource to have English as the base language and U.S. as the sublanguage.

Multiple resources with the same ID may be bound to a single .EXE or .DLL if they each have different major and/or minor languages specified. The language currently specified by Windows will determine which resource identified by the ID will actually be loaded.

Major

Use the Major list box to select the base language to be used for the resources.

Minor

Use the Minor list box to select the sublanguage to be used for the resources.


Pack Fastload Area (Project Options)
Pack Fastload Area (Options|Project|Resources)

The Pack Fastload Area option optimizes how resources and segments are arranged in the executable file.

When Pack Fastload Area is checked, the resource linker causes all data segments, nondiscardable code segments, and the entry-point code segment to be preloaded and written to a contiguous area in the executable file.

If you uncheck Pack Fastload Area, no such optimizations will be done.

Default = OFF


Syntax Highlighting Options (Environment Options)
Syntax Highlighting Options

See Also

The Options|Environment|Syntax Highlighting options let you customize the colors and styles used to denote syntax elements in your code. These options also tell the Borland C++ IDE editor how to display these elements.

The sub-topic is:

Customize

The options are:

Color SpeedSettings

Use Syntax Highlighting

Syntax Extensions


See Also

Using Syntax Highlighting


Color SpeedSettings (Environment Options)
Color SpeedSettings (Options|Environment|Syntax Highlighting)

See Also

The Color SpeedSettings allow you to use preset syntax highlighting color schemes. You can see the effect of each SpeedSetting by watching the sample window on the right.

Defaults

Press the Defaults button to use the default syntax highlighting color scheme.

Classic

Press the Classic button to use the Borland DOS IDE syntax highlighting color scheme.

Twilight

Press the Twilight button to use the Twilight syntax highlighting color scheme.

Ocean

Press the Ocean button to use the Ocean syntax highlighting color scheme.


Use Syntax Highlighting (Environment Options)
Use Syntax Highlighting (Options|Environment|Syntax Highlighting)

See Also

When the Use Syntax Highlighting option is on, the editor displays your program code in the specified colors and attributes.

When this option is off, all of your program code appears in the color defined for the Plain Text element in the Element list box.


Syntax Extensions (Environment Options)
Syntax Extensions (Options|Environment|Syntax Highlighting)

See Also

By default, only files with a .C, .CPP, or .H extension will display syntax highlighting. You might want to highlight other file types.

To change which files will be displayed with syntax highlighting, enter the desired file extensions in the Syntax Highlighting|Syntax Extensions input box. Any file extension, including one with wildcards (*), is valid. To enter multiple file extensions, place a semicolon (;) between each one.


Syntax Highlighting|Customize (Environment Options)
Syntax Highlighting | Customize (Options|Environment)

See Also

Use the Syntax Highlighting|Customize options to set colors for specific code elements. The options you can set are:

Element

Color

Attribute

Default FG (foreground)

Default BG (background)

Sample


Element list box

See Also

You use the Syntax Highlighting|CustomizeElement list box to choose a syntax element whose colors you want to change. You can also click on an element in Sample display box to select an element.

The syntax elements whose colors and display attributes you can alter include:

Whitespace	Execution Point

Comment	Enabled Break

Reserved Word	Disabled Break

Identifier	Invalid Break

Symbol	Error Line

String	Plain Text

Integer	Client 1

Float	Client 2

Octal	Client 3

Hex	Client 4

Character	Client 5

Preprocessor	Client 6

Illegal Character	Client 7

Marked Block	Client 8

Search Match

As you change the colors or underline attributes of a syntax element, the changes appear in the Sample code box.


Color Matrix
Color

See Also

The Syntax Highlighting|Customize|Color matrix displays the possible color choices for elements of code.

You can set the foreground or background colors for any element. As soon as you select a color for an element, the change appears in the Sample display box.

FG	The rectangle containing the letters FG displays the current element's foreground color.

BG	The rectangle containing BG displays the element's background color.

FB	A rectangle containing the letters FB displays the current element's foreground and background color (where the same color is assigned to both).

This option works differently than the Default FG and Default BG options that set the colors of an element to the defaults defined in your Windows Control Panel.


Attribute

See Also

Use the Syntax Highlighting|Customize|Attribute options to choose the attributes of a code element.

Select the code element you wish to change by clicking on the element in the the Element list box. Then, click the attribute you wish to use. As soon as you choose the attribute, you will see it reflected in the Sample display box.

Bold

Use the Bold option to make the specified code element display in boldface.

Italic

Use the Italic option to make the specified code element display in italics.

Underline

Use the Underline option to make the specified code element display underlined.


Default FG (foreground)
Default FG (foreground color)

See Also

You use the Syntax Highlighting|Customize|Default FG option to set the foreground color of the element currently selected in the Element list box to your Windows system text color.

To change the Windows system colors, use the Control Panel in the Program Manager.


Default BG (background)
Default BG (background color)

See Also

You use the Syntax Highlighting|Customize|Default BG option to set the background color of the element currently selected in the Element list box to your Windows system background color.

To change the Windows system colors, use the Control Panel in the Program Manager.


Sample display box

See Also

The Sample display box shows you the current syntax highlighting settings for your Borland C++ editor window.

When you change these settings using Syntax Highlighting|Customize options, the colors in the Sample display box change to reflect any changes you have made in the options.

Use the scroll bars to see other sections of the sample code to see the effect on types of elements not currently visible in the Sample display box.

You can select which code element you want to customize the colors for by clicking on it on the Sample display box, or by selecting it in the Element list box.


Using Syntax Highlighting

You use syntax highlighting to control how code is displayed. Setting the different syntax elements to different colors makes it easier for you to quickly identify parts of your code.

Some of the tasks you can perform with syntax highlighting include:

Activating Syntax Highlighting

Selecting a Syntax Element

Changing the Syntax Highlighting Colors

Setting the Background Color

Setting the Foreground Color

Setting Text Attributes

Setting Up Client Areas

Most of these tasks are performed using the Syntax Highlighting options section of the Environment options settings dialog.


Activating Syntax Highlighting

Using Syntax Highlighting

To turn syntax highlighting on, you choose Use Syntax Highlighting option on the Syntax Highlighting options section of the Environment options settings dialog.


Selecting a Syntax Element

Using Syntax Highlighting

To select a Syntax Element to customize the colors for, either:

Choose an element from the Element list box.

Click on an element In the Sample Code display box.


Changing the Syntax Highlighting Colors

Using Syntax Highlighting

To alter syntax highlighting colors for parts of your code, change the settings in the Syntax Highlighting options.

As you change the colors or attributes, the changes appear in the Sample Code display box.


Setting the Background Color

Using Syntax Highlighting

With the mouse:

Right-click on the background color you want in the Color matrix.

The letters BG in the color rectangle indicate that the background is now set to that color.

From the keyboard:

Press Tab (or Alt+C) to go to the Color matrix.

Press the arrow keys or Spacebar to select the background color you want.

Press B.

The letters BG in the color rectangle indicate that the background is now set to that color.

To use the Windows system background color for the current syntax element's background, choose the Default BG option.


Setting the Foreground Color

Using Syntax Highlighting

With the mouse:

Left-click the foreground color you want in the Color matrix.

The letters FG in the color rectangle indicate that the foreground is now set to that color.

From the keyboard:

In the Color matrix, press the arrow keys or Spacebar to select the foreground color you want.

Press F. The letters FG in the color rectangle indicate that the foreground is now set to that color.

To use the Windows system text color for the current syntax element's foreground, choose the Default FG option.


Setting Text Attributes

Using Syntax Highlighting

Set the normal, bold, italic, or underline attribute: choose the Bold, Italic, or Underline options.


Setting Up Client Areas

Using Syntax Highlighting

Among the elements for which you can specify syntax highlighting are eight user-defined lists in which you can specify your own keywords, functions, or other language elements that you want highlighted. These elements are stored in token (.TOK) files.

Two token files are shipped with Borland C++: C.TOK and C32.TOK. You select the one you want to use in Reserved Words option in the Editor|File settings.

You can modify these files to include your own keywords. To add keywords to a token file:

1.	Open the token file you want to modify.

2.	At the end of the file add the heading [Client 1].

3.	Start a new line and enter the new keyword.

4.	Enter each additional keyword, making certain that there is a carriage return after each keyword you add.

If you want to create a new user-defined area, place a new heading (as in step 2), incrementing the number by 1. You can have up to 8 of these areas.

You must exit the IDE and restart Borland C++ in order for your changes to be in effect.

Example

[Client 1]

LocateWinFunction

LocateDOSFunction

[Client 2]

Icon

Bitmap

ListBox


SpeedBar Options

The Options|Environment|SpeedBar options control what commands can be accessed from the IDE SpeedBar.

The sub-topics are:

Customize

The options are:

SpeedBar Options

Orientation


SpeedBar|SpeedBar Options (Environment Options)
SpeedBar | SpeedBar Options (Options|Environment)

The SpeedBar|SpeedBar Options control the operation of the SpeedBar.

Hide SpeedBar

Check Hide SpeedBar to prevent the SpeedBar from being displayed in the Borland C++ IDE desktop.

Use Flyby Help Hints

Check Use Flyby Help Hints to display status line help hints when you move the mouse pointer over a SpeedBar button.

When this option is off, you must press the left mouse button on the SpeedBar button to view a help hint. To get a help hint without having the SpeedBar action take place, press the left mouse button and move the pointer away from the SpeedBar button before releasing it.


SpeedBar|Orientation (Environment Options)
SpeedBar | Orientation (Options|Environment)

The SpeedBar|Orientation options control the placement of the SpeedBar on the Borland C++ IDE desktop.

Top

The Top option causes the SpeedBar to be displayed at the top of the Borland C++ IDE desktop.

Bottom

The Bottom option causes the SpeedBar to be displayed at the bottom of the Borland C++ IDE desktop.


SpeedBar|Customize (Environment Options)
SpeedBar | Customize (Options|Environment)

The SpeedBar|Customize options control which commands can be accessed from the IDE SpeedBar. Use the:

Window

Use the Window list to select the IDE desktop window you want to customize the SpeedBar for. The windows for which you can customize the SpeedBar include the Editor window, Project Hierarchy, and Message Window.

Available Buttons

The Available Buttons list displays the commands (and the icons associated with them) that you can use on your SpeedBar. This list excludes any buttons that are currently in the Active Buttons list.

Active Buttons

The Active Buttons list displays the commands (and the icons associated with them) that are currently on the SpeedBar for the IDE window currently selected in the Window list box. This list excludes any buttons that are currently in the Available Buttons list. The button that appears at the top of the list appears on the far left of the SpeedBar; the last button appears on the far right.

Customizing a SpeedBar

Use the Copy Layout button to copy the SpeedBar options from the window currently selected in the Window list box to another window.

Use the Restore Layout button to restore the default SpeedBar options of the one currently selected in the Window list box.

Use the Separator button to place a blank space above the selected button in the Active Buttons list for the SpeedBar you are customizing.

Use the Left Arrow button to move the button currently selected in the Active Buttons list and place it in the Available Buttons list.

Use the Right Arrow button to move the button currently selected in the Available Buttons list and place it in the Active Buttons list.

Use the Up Arrow button to move the selected button in the Active Buttons list up one position in the SpeedBar.

Use the Down Arrow button to move the selected button in the Active Buttons list down one position in the SpeedBar.


Copy Speedbar Layout dialog box
Copy Speedbar Layout dialog box (Options|Environment)

Use the Copy Speedbar Layout dialog box to specify which windows the current Speedbar layout should be copied to. The name of the window currently selected in the Window list of the Speedbar|Customize settings will be grayed out.


The Inline Assembler (BASM)

With the Borland C++ inline assembler, you can write 8086/8087 and 80286/80287 assembler code directly inside your C and C++ programs.

Index to Inline Assembler Help

asm

assembler directive

expression classes

expression operators

expression symbols

expression types

expressions

instruction opcodes

labels

numeric constants

operands

predefined type symbols

prefix opcodes

register symbols

relocatable expressions

reserved words

string constants

Using the Inline Assembler

You access the inline assembler through assembler statements (with the asm directive).

Expressions

The Borland C++ inline assembler operands are expressions. The basic elements of an expression are constants, registers, symbols, and operators.

The inline assembler divides expressions into three classes:

registers

memory references

immediate values

Symbols

The inline assembler provides access to almost all C++ symbols in assembler expressions, including labels, constants, types, variables, procedures, and functions.

In addition to any currently declared C++ types, the inline assembler provides several predefined type symbols.

Constants

The Borland C++ inline assembler supports two types of constants:

numeric constants

string constants

Opcodes, Operators, and Directives

The Borland C++ inline assembler supports:

All 8086/8087 and 80286/80287 instructions

Opcodes

Most Turbo Assembler expression operators

Turbo Assembler's define byte, define word, and define double word directives (DB, DW, and DD)

The inline assembler also implements a large subset of the syntax supported by Turbo Assembler and Microsoft's Macro Assembler.


Inline Assembler Operands

Inline assembler operands are expressions made up of a combination of constants, registers, symbols, and operators.

Although inline assembler expressions are built using the same basic principles as C++ expressions, there are some important differences.

The inline assembler:

Recognizes its own set of reserved words.

Evaluates all expressions as 32-bit integer values.

Interprets variable references as the address of the variable. (C++ interprets them as the variable's contents.)

Also, all inline assembler expressions must resolve to a constant value.


Inline Assembler Expressions

The Borland C++ inline assembler operands are expressions.

Inline assembler expressions are built from expression elements (constants, registers, and symbols) and operators. Each expression has an associated expression class and expression type.

Evaluation

The inline assembler evaluates all expressions as 32-bit integer values. It does not support floating-point and string values, except string constants.

Note: The most important difference between C++ expressions and inline assembler expressions is that all inline assembler expressions must resolve to a constant value (a value that can be computed at compile time).


Inline Assembler Expression Classes

The inline assembler divides expressions into three classes:

registers

memory references

immediate values


Inline Assembler Expression Operators

This table lists the inline assembler's expression operators in decreasing order of precedence.

The operators within each category have equal precedence.

Category	Operator	What it is (or does)

Highest	(...) 	Subexpression

[...] 	Memory reference

 . 	Structure member selector

Unary	HIGH	Returns high-order 8 bits

LOW	Returns low-order 8 bits

+ 	Unary plus

- 	Unary minus

: 	Segment override

OFFSET	Returns offset part

SEG	Returns segment part

TYPE	Returns type (byte size)

PTR	Typecast

* 	Multiplication

/ 	Integer division

MOD	Integer modulus (remainder)

SHL	Logical shift left

SHR	Logical shift right

Additive	+ 	Binary addition

- 	Binary subtraction

Bitwise	NOT	Bitwise negation

AND	Bitwise AND

OR 	Bitwise OR

XOR	Bitwise Exclusive OR


Inline Assembler Expression Types

Every inline assembler expression has an associated type.

This type is a size, because the inline assembler regards the type of an expression as the size of its memory location.

The inline assembler performs type checking whenever possible; an error results if the type check fails.

You can use a typecast to change the type of a memory reference. For example, all of these refer to the first (least significant) byte of the OutBufPtr variable:

asm {

  MOV     DL,BYTE PTR OutBufPtr

  MOV     DL,Byte(OutBufPtr)

  MOV     DL,OutBufPtr.Byte

}

In some cases, a memory reference is untyped (it has no associated type); for example, an immediate value enclosed in square brackets:

asm {

  MOV     AL,[100H]

  MOV     BX,[100H]

}

The inline assembler permits both of these instructions because

the expression [100H] has no associated type (it just means "the contents of address 100H in the data segment") and

the type can be determined from the first operand (byte for AL, word for BX).

In cases where the type can't be determined from another operand, the inline assembler requires an explicit typecast, like this:

asm {

  INC     BYTE PTR [100H]

  IMUL    WORD PTR [100H]

}


Inline Assembler Predefined Type Symbols

In addition to any currently declared C++ types, the inline assembler provides these predefined type symbols.

Symbol	Type

BYTE	1

WORD	2

DWORD	4

NEAR	0FFFEH

FAR	0FFFFH


Inline Assembler NEAR and FAR Pseudo-Types

The NEAR and FAR pseudo-types are used by procedure and function symbols to indicate their call model.

You can use NEAR and FAR in typecasts just like other symbols. For example, if FarFunction is a FAR function:

void far farFunction (void);

and you're writing inline assembler code in the same module as FarFunction, you can use the more efficient NEAR call instruction to call FarFunction:

asm {

  PUSH    CS

  CALL    NEAR PTR FarFunction

}


Inline Assembler Register Expressions

An inline assembler expression that consists solely of a register name is a register expression.

Examples of register expressions are AX, CL, DI, and ES.

Used as operands, register expressions direct the assembler to generate instructions that operate on the CPU registers.


Inline Assembler Memory Reference Expressions

Inline assembler expressions that denote memory locations are memory references.

C++'s labels, variables, typed constants, procedures, and functions belong to this category.

Memory references are further classified as either relocatable or absolute expressions.


Inline Assembler Immediate Value Expressions

Inline assembler expressions that aren't registers and aren't associated with memory locations are immediate values.

This group includes C++'s untyped constants.

Immediate values are further classified as either relocatable or absolute expressions.


Inline Assembler Relocatable vs. Absolute Expressions

Typically, an expression that refers to a label, variable, procedure, or function is relocatable, and an expression that operates solely on constants is absolute.

A relocatable expression denotes a value that requires relocation at link time.

An absolute expression denotes a value that requires no such relocation.

(Relocation is the process by which the linker assigns absolute addresses to symbols.)

At compile time, the compiler does not know the final address of a label, variable, procedure, or function.

The final address does not become known until link time, when the linker assigns a specific absolute address to the symbol.

The inline assembler allows you to carry out any operation on an absolute value, but it restricts operations on relocatable values to addition and subtraction of constants.


Inline Assembler Register Symbols

In the Borland C++ inline assembler, the following reserved symbols denote CPU registers:

Symbols	Registers

AX BX CX DX	16-bit general purpose

AL BL CL DL	8-bit low registers

AH BH CH DH	8-bit high registers

SP BP SI DI	16-bit pointer or index

CS DS SS ES	16-bit segment registers

ST	8087 register stack

When an operand consists solely of a register name, it is called a register operand. All registers can be used as register operands.

Register Indexing

The base registers (BX and BP) and the index registers (SI and DI) can be written within square brackets to indicate indexing.

These are valid index register combinations:

[BP]

[BP+DI]

[BP+SI]

[BX]

[BX+DI]

[BX+SI]

[DI]

[SI]

Segment Overriding

The segment registers (ES, CS, SS, and DS) can be used in conjunction with the colon (:) segment override operator to indicate a different segment than the one the processor selects by default.

For example:

asm mov AX, 0xb000

asm mov ES, AX

asm mov SI, WORDPTR es:[0]


Inline Assembler Expression Symbols

The inline assembler provides access to almost all C++ symbols in assembler expressions, including labels, constants, types, variables, procedures, and functions.

The inline assembler also provides several predefined type symbols.

Symbol	Value	Class	Type

Label	Address of label	Memory	Short

Constant	Value of constant	Immediate	0

Type	0	Memory	Size of type

Field	Offset of field	Memory	Size of type

Variable	Address of variable	Memory	Size of type

Function	Address of function	Memory	Near or Far

Symbols that can NOT be used

The following symbols can NOT be used in inline assembler expressions:

String, floating-point, and set constants

Functions declared with the inline modifier

Labels that aren't declared in the current block

Local Variables

Local variables (variables declared in procedures and functions) are always allocated on the stack and accessed relative to SS:BP.

The value of a local variable symbol is its signed offset from SS:BP.

The inline assembler automatically adds [BP] in references to local variables.

Scope

A scope is provided by type, field, and variable symbols of a structure or object type.

Operator

Some symbols, such as structure types and variables, have a scope that can be accessed using the structure member selector (.) operator.

Type Identifier

You can use a type identifier to construct variables "on the fly".


ST(x) Register Symbol

The symbol ST denotes the topmost register on the 8087 floating-point register stack.

Each of the eight floating-point registers can be referred to using ST(x), where X is a constant between 0 and 7, indicating the distance from the top of the register stack.


Inline Assembler String Constants

In inline assembler statements, string constants must be enclosed in single or double quotes.

Two consecutive quotes of the same type as the enclosing quotes count as only one character.

String constants of any length are allowed in DB directives, and cause allocation of a sequence of bytes containing the ASCII values of the characters in the string.

When not in a DB directive, a string constant can be no longer than four characters, and denotes a numeric value which can participate in an expression.

If the string is shorter than four characters, the leftmost (first) character(s) are assumed to be 0 (zero).

Here are some examples of string constants and their corresponding numeric values:

String	Numeric

Constant	Value

'a'	00000061H

'ba'	00006261H

'cba'	00636261H

'dcba'	64636261H

'a '	00006120H

'   a'	20202061H

'a'*2	000000E2H

'a'-'A'	00000020H

NOT 'a'	FFFFFF9EH


Inline Assembler Numeric Constants

Inline assembler numeric constants must be integers between -2,147,483,648 and 4,294,967,295, and they must start with one of the digits 0 through 9 or a $ character.

By default, numeric constants use decimal (base 10) notation, but the inline assembler supports binary (base 2), octal (base 8), and hexadecimal (base 16) notations as well.

To select

this notation	Write a...

Binary	letter B after the number

Octal	letter O after the number

Hexadecimal	letter H after the number, or a $ before the number

C++ expressions allow only decimal notation and hexadecimal notation (using a $ prefix); they don't support the B, O, and H suffixes.

When you write a hexadecimal constant using the H suffix, and the first significant digit is one of the hexadecimal digits A through F, an extra zero (0) in front of the number is required.

Examples:

0BAD4H	Hexadecimal constant

$BAD4	Hexadecimal constant

BAD4H	Identifier (it starts with a letter B, not a digit)


Inline Assembler Reserved Words

Within operands, the following reserved words have a predefined meaning to the inline assembler:

Reserved Words Table

AH

AL

AND

AX

BH

BL

BP

BX

BYTE

CH

CL

CS

CX

DH

DI

DL

DS

DWORD

DX

ES

FAR

HIGH

LOW

MOD

NEAR

NOT

OFFSET

OR

PTR

SEG

SHL

SHR

SI

SP

SS

ST

TYPE

WORD

XOR

These reserved words always take precedence over user-defined identifiers.


Inline Assembler Prefix Opcodes

The inline assembler supports the following prefix opcodes:

Opcode	What It Means

LOCK	Bus lock

REP	Repeat string operation

REPE	Repeat string operation while equal

REPZ	Repeat string operation while 0

REPNE	Repeat string operation while not equal

REPNZ	Repeat string operation while not 0

An assembler instruction can be prefixed by zero, one, two, or three of these opcodes. Any more than three prefix opcodes won't make sense.

If you specify a prefix opcode without an instruction opcodes in the same statement, the prefix opcode affects the instruction opcode in the next assembler statement.

Because some 80x86 processors do not handle all combinations correctly, ordering in multiple prefix opcodes is important.


Inline Assembler Instruction Opcodes

The inline assembler supports all 8086/8087 and 80286/80287 instruction opcodes.

For complete descriptions of the instruction opcodes, refer to your 80x86 and 80x87 manuals.

See Also

inline assembler RET instructions

automatic jump sizing


Inline Assembler RET Instructions

Depending on the call model of the current procedure or function, RET generates either a near return or a far return machine-code instruction.


Inline Assembler Jump Optimization

The inline assembler optimizes jump instructions by automatically selecting the shortest, most efficient form of a jump instruction.

When the target is a label (not a procedure or function), this automatic jump sizing applies to JMP and to all conditional jump instructions.

Opcode	Distance to Target Label	Inline Assembler Generates

JMP	Within -128 to 127 bytes	Short jump

NOT within -127 to 128 bytes	Near jump

Conditional	Within -128 to 127 bytes	Short jump

Jumps	NOT within -127 to 128 bytes	Short jump

Jumps to the entry points of procedures and functions are always either near or far, but never short.

Conditional jumps to procedures and functions are not allowed.


Inline Assembler DB, DW, and DD Directives

The inline assembler supports three assembler directives: DB (define byte), DW (define word), and DD (define double word).

Dir	Operand Type	Value Range	Inline Assembler Generates

DB	Constant expression	-128 to 255	1 byte

Character string	Any length	Sequence of bytes corresponding to ASCII code of each character

DW	Constant expression	-32,768 to 65,535	1 word

Address expression	Near pointer (offset word)

DD	Constant expression	-2,147,483,648	1 double word

to 4,294,967,295

Address expression	Far pointer (offset  word followed by segment word)

The data generated by the DB, DW, and DD directives is always stored in the code segment.

To generate uninitialized or initialized data in the data segment, use normal C++ declarations.

Here are some examples of DB, DW, and DD directives:

Dir	Operand	Result

DB	0FFH	One byte

DB	0,99	Two bytes

DB	'Hello...', 0DH,0AH	String + CR/LF

DB	12,"Borland C++"	C++-style string

DW	0FFFFH	One word

DW	0,9999	Two words

DW	'A'	Same as DB 'A',0

DW	'BA'	Same as DB 'A','B'

DW	MyVar	Offset of MyVar

DW	MyProc	Offset of MyProc

DD	0FFFFFFFFH	One double-word

DD	0,999999999	Two double-words

DD	'A'	Same as DB 'A',0,0,0

DD	'DCBA'	Same as DB 'A','B','C','D'

DD	MyVar	Pointer to MyVar

DD	MyProc	Pointer to MyProc

The only kind of symbol that can be defined in an inline assembler statement is a label. All variables must be declared using C or C++ syntax.


Inline Assembler Statement

The syntax of an assembler statement is

opcode operand <operand operand   >; or Newline

where

"opcode" is an assembler instruction opcode

"operand" is an assembler expression

";or Newline" is a semicolon or a new line, either of which signals the end of the asm statement.

Comments are allowed between assembler statements, but not within them.


Inline Assembler Labels

Labels consist of a label identifier and a colon before a statement.


Inline Assembler Subexpression (...)

The expression within the parentheses is a subexpression.

(Expression)

Subexpressions are evaluated completely before they are treated as a single expression element.

Another expression can precede the expression within the parentheses. In this case, the result becomes the sum of the values of the two expressions, with the type of the first expression.


Inline Assembler Memory Reference Operator [...]

The expression within brackets refers to a memory location.

[Expression]

This memory reference expression is evaluated completely prior to being treated as a single expression element.

To indicate CPU register indexing, you can use the plus (+) operator to combine the memory reference expression with the BX, BP, SI, or DI registers.

Another expression can precede the memory reference expression. In this case, the result becomes the sum of the values of the two expressions, with the type of the first expression.

Result

Always a memory reference.


Inline Assembler Structure Member Operator (xxx . yyy)

The second expression is a member of the structure identified by the first expression.

Expression1.Expression2

Result

Sum of the two expressions.

Result Type

Type of the second expression.

Symbols belonging to the scope identified by the first expression can be accessed in the second expression.


Inline Assembler HIGH Operator

HIGH returns the high-order 8 bits of the word-sized expression following the operator.

HIGH Expression

The expression must be an absolute immediate value.


Inline Assembler LOW Operator

LOW returns the low-order 8 bits of the word-sized expression following the operator.

LOW Expression

The expression must be an absolute immediate value.


Inline Assembler Unary Plus (+...)

Unary plus returns the expression following the plus with no changes.

+Expression

The expression must be an absolute immediate value.


Inline Assembler Unary Minus (-...)

Unary minus returns the negated value of the expression following the minus.

-Expression

The expression must be an absolute immediate value.


Inline Assembler Segment Override Operator (: ...)

This operator instructs the assembler that the expression after the colon belongs to the segment given by the segment register name before the colon (CS, DS, SS, or ES).

XX:Expression

where XX = CS, DS, SS, or ES.

Result

A memory reference with the value of the expression after the colon.

When a segment override is used in an instruction operand, the instruction will be prefixed by an appropriate segment override prefix instruction.

This ensures that the indicated segment is selected.


Inline Assembler OFFSET Operator

OFFSET returns the offset part (low-order word) of the expression following the operator.

OFFSET Expression

Result

An immediate value.


Inline Assembler SEG Operator

SEG returns the segment part (high-order word) of the expression following the operator.

SEG Expression

Result

An immediate value.


Inline Assembler TYPE Operator

TYPE returns the type (size in bytes) of the expression following the operator.

TYPE Expression

The type of an immediate value is 0.


Inline Assembler Typecast Operator (... PTR ...)

PTR casts the second expression to the type of the first expression.

Expression1 PTR Expression2

Result

A memory reference with the value of the second expression and the type of the first expression.


Inline Assembler Multiplication Operator (... * ...)

The * operator multiplies the first expression by the second expression.

Expression1 * Expression2

Both expressions must be absolute immediate values.

Result

Absolute immediate value.


Inline Assembler Integer Division (... / ...)

The / operator divides the first expression by the second expression and returns the integer part of the operation.

Expression1 / Expression2

Both expressions must be absolute immediate values.

Result

Absolute immediate value.


Inline Assembler Integer Modulus (... MOD ...)

MOD divides the first expression by the second expression and returns the remainder part of the operation.

Expression1 MOD Expression2

Both expressions must be absolute immediate values.

Result

Absolute immediate value.


Inline Assembler Shift Left Operator (... SHL ...)

SHL shifts the first expression to the left by nnn bits, where nnn is the second expression.

Expression1 SHL Expression2

Both expressions must be absolute immediate values.

Result

Absolute immediate value.


Inline Assembler Shift Right Operator (... SHR ...)

SHR shifts the first expression to the right by nnn bits, where nnn is the second expression.

Expression1 SHR Expression2

Both expressions must be absolute immediate values.

Result

Absolute immediate value.


Inline Assembler Addition Operator (... + ...)

The + operator adds the first expression to the second expression (or vice versa).

Expression1 + Expression2

The expressions can be immediate values or memory references, but only one of the expressions can be a relocatable value.

Result

Relocatable value if one of the expressions is a relocatable value.

Memory reference if either of the expressions is a memory reference.


Inline Assembler Subtraction Operator (... - ...)

The - operator subtracts the second it from the first expression.

Expression1 - Expression2

The first expression can have any class, but the second expression must be an absolute immediate value.

Result

Has the same class as the first expression.


Inline Assembler Bitwise NOT
Inline Assembler Bitwise Negation (NOT)

NOT returns the bitwise negative (1's complement) of the expression after it.

NOT Expression

The expression must be an absolute immediate value.

Result

Absolute immediate value.


Inline Assembler Bitwise AND

AND returns the bitwise AND of the two expressions.

Expression1 AND Expression2

Both expressions must be absolute immediate values.

Result

Absolute immediate value.


Inline Assembler Bitwise OR

OR returns the bitwise OR of the two expressions.

Expression1 OR Expression2

Both expressions must be absolute immediate values.

Result

Absolute immediate value.


Inline Assembler Bitwise XOR
Inline Assembler Bitwise Exclusive XOR

XOR returns the bitwise exclusive-OR of the two expressions.

Expression1 XOR Expression2

Both expressions must be absolute immediate values.

Result

Absolute immediate value.


Inline Assembler Function Returns

Functions using the inline assembler directive (asm) must return their results as follows:

Result	Returned In

Ordinal	AL (8-bit values)

AX (16-bit values)

DX:AX  (32-bit values)

Real	DX:BX:AX

8087	ST(0) on the 8087's

register stack

Pointer	DX:AX


short jump

1-byte opcode followed by 1-byte displacement.


near jump

1-byte opcode followed by 2-byte displacement.


short inverse jump

A short jump with the inverse condition jumps over a near jump to the target label (5 bytes in total).


Using TLINK and TLINK32

See Also

TLINK and TLINK32 are command-line tools that combine object modules (.OBJ files) and library modules (.LIB files) to produce executable files. Because the compiler automatically calls TLINK, you don't need to use TLINK unless you suppress the linking stage of compiling (see the -c compiler option).

TLINK uses configuration file called TLINK.CFG (or TLINK32.CFG), a response file, and command-line options to link object modules, libraries, and resources into an executable file (.EXE or .DLL).

TLINK links 16-bit (Windows) code and uses RLINK.EXE. TLINK32 links 32-bit (Windows NT) code and uses RLINK32.DLL.


See Also

Command-Line Options

TLINK.CFG

Response File

Error and Warning Messages


TLINK Command-line Options

TLINK options control how TLINK works. Unless specified, instructions and options for TLINK also apply to TLINK32.

TLINK and TLINK32 command-line options are case-sensitive.

TLINK can also use a configuration file called TLINK.CFG (or TLINK32.CFG) for options that you'd normally type at the command-line.

Syntax

TLINK [@respfile][options] startupfile myobjs, exename, [mapfile], [mylibs] runtimelib [import], [deffile], [resfiles]

[options]	TLINK options that control how TLINK works. For example, options specify whether to produce an .EXE or a DLL file. TLINK options must be preceded by either a slash (/) or a hyphen (-).

[startupfile]	a Borland initialization module for executables or DLLs that arranges the order of the various segments of the program. Failure to link in the correct initialization module usually results in a long list of error messages telling you that certain identifiers are unresolved, or that no stack has been created.

[myobjs]	the .OBJ files you want linked. Specify the path if the files arn't in the current directory. (TLINK appends an .OBJ extensions if no extension is present)

[exename]	the name you want given to the executable file (.COM, .EXE or .DLL). If you don't specify an executable file name, TLINK derives the name of the executable by appending .EXE or .DLL to the first object file name listed. (TLINK assumes or appends an .EXE extensions for executable files if no extension is present. It also assumes or appends a .DLL extention for dynamic link libraries if no extension is present.)

[mapfile]	(optional) is the name you want given to the map file. If you don't specify a name, the map file name is given the same as exefile (but with the .MAP extension). (TLINK appends a .MAP extensions if no extension is present)

[mylibs]	(optional) are the library files you want included at link time. If these files aren't in the current directory or the search path (see the /L option) then you must include their paths.  (TLINK appends a .LIB extensions if no extension is present)

[runtimelib]	the Borland run-time library. If no libraries are included, none are linked.

[importlib]	the Windows import library, which provides access to the Microsoft Windows API functions.

[deffile]	the module definition file for a Windows executable. If you don't specify a module definition (.DEF) file and you have used the /Twe or /Twd option, TLINK creates an application based on default settings.  (TLINK appends a .DEF extensions if no extension is present)

[resfiles]	a list of .RES files to bind to the executable. (TLINK appends an .RES extensions if no extension is present)


TLINK.CFG File

TLINK uses a configuration file called TLINK.CFG (or TLINK32.CFG) for options that you'd normally type at the command-line (note that TLINK.CFG can only be options, not file names). Configuration files let you save options you use continually without having to always type them.

TLINK looks for TLINK.CFG in the current directory, then in the directory from which it was loaded.

The following TLINK.CFG file tells TLINK to look for libraries first in the directory C:\BC4\LIB then in C:\WINAPPS\LIB, to include debug information in the executables it creates, to create a detailed segment map, and to produce a Windows executable (.EXE not .DLL).

/Lc:\bc4\lib;c:\winapps\lib

/v /s

/Twe


Response Files

The command-line compilers also use response files.

Response files are ASCII files of options and file names for TLINK.EXE (and TLINK32.EXE) that you would normally type at the command line. Response files let you have a longer command line than most operating systems allow, plus you don't have to continually type the same information. Response files can include the same information as configuration files, but they can also contain file names.

Unlike the command line, a response file can be several lines long by ending a line with a plus character (+) and continuing it on the next line. Note that if a line ends with an option that uses the plus to turn it on (such as /v+), the + is not treated as a line continuation character.

If you separate command-line components (such as .OBJ files from .LIB files) by lines in a response file, you must leave out the comma used to separate them on the command line. For example,

/c c0ws+

   myprog,myexe

   mymap

   mylib cws

leaves out the commas you'd have to type if you put the information on the command line:

   TLINK /c c0ws myprog,myexe,mymap,mylib cws

To use response files,

1.	Type the command-line options and file names into an ASCII text file and save the file. Response files shipped with Borland C++ have the .RSP extension.

2.	Type TLINK @[path]RESFILE.RSP where RESFILE.RSP is the name of your response file.

You can specify more than one response file as follows:

   tlink /c @listobjs,myexe,mymap,@listlibs


Using TLINK with BCC.EXE

BCC always starts TLINK with the /c (case-sensitive link) option.

You can pass options and files to TLINK through the command-line compilers (BCC.EXE and BCC32.EXE) by typing file names on the command line with explicit .OBJ and .LIB extensions. For example,

BCC mainfile.obj sub1.obj mylib.lib

links MAINFILE.OBJ, SUB1.OBJ, and MYLIB.LIB and produces the executable MAINFILE.EXE.


TLINK Options

DPMI (Add On)

Unless specified, options work for both TLINK and TLINK32. Options are case-sensitive and must be preceded by either a slash (/) or a hyphen (-). You can place options anywhere in the command line. Spaces aren't necessary among options (/m/c is the same as /m  /c), but you must separate options from files with a space.

The following table lists the TLINK options.

Option For	Description

/ax	(TLINK32) Specifies application type
/aa targets Windows applications
/ap targets Windows-compatible character mode applications.

/A:dd	Specifies page alignment for code and data within the executable file where dd must be a decimal power of 2.

For example, if you specify an alignment value of /A:12, the pages of code and data are stored on 4096-byte boundaries.

The operating system seeks pages for loading based on this alignment value. The default is /A:9, which means pages are aligned on 512-byte boundaries within the executable file.

/B:xxxxxx	(TLINK32) Specifies an image base address for an application.

If this option is used, internal fixups are removed from the image, and the requested load address of the first object is set to the hexadecimal number given with the option. All successive objects are aligned on 64K linear address boundaries. This option makes applications smaller on disk, and improves both load-time and run-time performance since the operating system no longer has to apply internal fixups.

/c	Treats case as significant in public and external symbols.

/C	(TLINK) Treats case as significant in EXPORTS and IMPORTS section of module definition file.

/d	(TLINK) Warns of duplicate symbols in library files.

If the symbol must be included in the program, TLINK uses the copy of that symbol from the first file specified on the command line (or the first file named in a response file).

This option also warns you if symbols appear in both an .OBJ file and a .LIB file (TLINK will use the first one linked in, usually the one in the .OBJ file).

/E	(TLINK) Enables processing of extended dictionaries in libraries.

The library files in Borland C++ contain an extended dictionary with information that lets TLINK use less memory and link faster with those libraries. You can add the extended dictionary to other library files using the TLIB's /E option. Avoid using /E with programs linked with libraries which have been built without an extended dictionary (third-party libraries which have been provided without source code, for example).

/Enn	(TLINK32) Specifies maximum errors the linker reports before terminating. /E0 (default) reports an infinite number of errors (that is, as many as possible).

/e	(TLINK) Ignores extended dictionaries in libraries. This is the opposite of the /E option and is the default.

/f	(TLINK) Inhibits optimization of far calls to near data.

/Gx	"Goodies" options where x can be:

n = discard Nonresident name table

r = export Resident names by ordinal number

m = put Mangles names in map file

You generate the smallest possible DLLs using this option by linking with /Gr, running IMPLIB, then relinking with /Gr /Gn.

/i	(TLINK) Initializes all segments. Outputs uninitialized trailing segments into the executable file even if the segments do not contain data records (uninitialized trailing segments).

/l (lowercase L)	(TLINK) Includes source line numbers. This option creates a section in the .MAP file for source code line numbers. Linked .OBJ files must be compiled with debug information.

Note: If you use /x to suppress map file creation, the /l (lowercase L) option has no effect.

/L	Specifies library search paths by letting you list directories for TLINK to search when you don't enter an explicit path for a library or the C or C++ initialization module. TLINK searches the current directory first (where you typed TLINK). For example,

TLINK /Lc:\BC4\lib;c:\mylibs splash logo,,,utils .\logolib

first searches the current directory for UTILS.LIB, then searches C:\BC4\LIB, then C:\MYLIBS. Because .\LOGOLIB explicitly names the current directory, TLINK does not search the libraries specified with the /L option to find LOGOLIB.LIB.

/m	Creates map file with publics. This option creates a more complete map than TLINK normally does by adding a list of sorted public symbols to the map file. This kind of map file is useful in debugging. Many debuggers can use the list of public symbols, letting you refer to symbolic addresses when you are debugging. See also /s.

/n	(TLINK) Doesn't use default libraries. This option ignores default libraries specified by some compilers. Use this /n when linking modules written in another language.

/Oc	(TLINK) Chain fixups. This optimization usually results in significantly smaller .EXE files, which load faster.

/Oc removes duplicate and/or unnecessary fixup data from the .EXE file. This is done by emitting only one fixup record for each unique internal fixup, and "remembering" the duplicate fixups by creating a linked list of the fixup locations within the .EXE data segment.

The loader applies the fixups specified in the fixup record to each of the locations specified in the linked list. Using this optimization also eliminates trailing zeros in data segments.

/Oi	(TLINK) Iterate data. This optimization results in smaller .EXE files which load faster.

/Oi scans data segments for patterns (e.g., blocks of 128 0 filled bytes). Instead of emitting the data, it emits a "description" of the chunk of data which matches the pattern (e.g., a 5-byte descriptor specifying 128 bytes of 0). Using this optimization also eliminates trailing zeros in data segments.

/Oa	(TLINK) Minimize segment alignment value.

The minimum segment alignment value is determined by the size of the .EXE file. An .EXE of 1 -> 64K will result in an alignment value of 1. An .EXE of 64K+1 -> 128K will result in a value of 2, etc.

This optimization results in a smaller .EXE file. However, the resultant .EXE file may actually load slower since the newly calculated alignment value may cause the segments to cross physical disk sector boundaries more often. Unless the /A switch has been specified to the linker as an input option, the linker initially generates an .EXE using the default alignment value of 256.

Note:	/Oa over-rides whatever alignment value has been used by the linker to initially generate the .EXE.

/Or	(TLINK) Minimize resource alignment value. This optimization is the same as /Oa, except that it applies to resource alignment values. Whenever one or more of the optimization switches are specified, the linker will reorder the segments in the EXE as follows:

PRELOAD segments

PRELOAD resources

LOAD ON CALL segments

LOAD ON CALL resources

/P	(TLINK) Packs code segments. This option combines as many code segments as possible in one physical segment up to (and never greater than) the code-segment packing limit. TLINK starts a new segment if it needs to. The default code-segment packing limit is 8,192 bytes (8K). To change it, use /P=n where n specifies the number of bytes between 1 and 65,536. You would probably want the limit to be a multiple of 4K under 386 enhanced mode. Although the optimum segment size in 386 enhanced mode is 4K, the default code-segment packing size is 8K because typical code segments are from 4K to 8K and 8K might pack more efficiently. Because each maintained segment has some system overhead, code segment packing typically increases performance. /P- turns off code segment packing (useful if you've turned it on in the configuration file and want to disable it for a particular link).

/R[lmpetkv]	(TLINK) Sends options to RLINK.EXE

/R[ve]	(TLINK32) verbose

/Rexxxx	(TLINK32) Renames the executable to xxxx .

/S:xxxxxx	(TLINK32) Specifies stack size (in hexadecimal) where xxxxxx is a hexadecimal string. Specifying the stack size with /S overrides any stack size setting in a module-definition file.

/s	(TLINK) Creates detailed map of segments. This option creates a map file with the same features as the /m option, but adds a detailed segment map. For each segment in each module, this map file includes the address, length in bytes, class, segment name, group, module, and ACBP information. If the same segment appears in more than one module, each module appears as a separate line. Except for the ACBP field, the information in the detailed segment map is self-explanatory.

With the /s option, public symbols with no references are flagged "idle." For example, this fragment from the public symbol section of a map file indicates that symbols Symbol1 and Symbol3 are not referenced by the image being linked:

0002:00000874      Idle Symbol1

0002:00000CE4      Symbol2

0002:000000E7      Idle Symbol3

/Tpx	(TLINK32) Specifies application target, where /Tpe builds a protected mode 32-bit .EXE file and /Tpd builds a protected mode 32-bit DLL.

/Twx	(TLINK) Specifies Windows 3.x target application, where /Twe means build a Windows .EXE file. /Twd means build a Windows DLL. This option is not necessary if you include a module-definition file with an EXETYPE Windows statement because TLINK creates an application (.EXE) if the module-definition file has a NAME statement or a DLL if the module-definition file has a LIBRARY statement.

/v	Includes full symbolic debug information in the executable file. If this option is found anywhere on the command line, debugging information is included in the executable file for all object modules that contain debugging information. You can use the /v+ and /v* options to selectively enable or disable debugging information on a module-by-module basis (but not on the same command line as /v). For example, the command

TLINK mod1 /v+ mod2 mod3 /v- mod4

includes debugging information for modules mod2 and mod3, but not for mod1 and mod4.

/wxxx	(TLINK32) Enable or disable warnings TLink warnings. where xxx can be one of the following:

-bdl	controls the "Using based linking for DLLs may cause the DLL to malfunction" warning

-def	controls the "No .DEF file; using defaults" warning

-dpl	controls the "Duplicate symbol" warning for libraries

-dup	controls the "Duplicate symbol" warning for .OBJs

-ent	controls the "No entry point" warning

-imt	controls the "Import does not match previous definition" warning

-inq	controls the "Extern not qualified with _ _import" warning

-msk	controls the "Multiple stack segments found" warning

-srf	controls the "Self-relative fixupp overflowed" warning

-stk	controls the "No stack" warning

/x	Doesn't create map file. TLINK usually creates map files that list segments in the program, the program start address, and any TLINK warning or error messages.

/ye	(TLINK) Uses expanded memory for swapping.  /ye or /ye+ enable expanded memory swapping (default). ye- disables expanded memory swapping.

This option controls TLINK's use of expanded memory for I/O buffering. If TLINK needs more memory for active data structures (while reading object files or writing the executable file), it either clears buffers or swaps them to expanded memory. When reading files, TLINK clears the input buffer so that its space can be used for other data structures. When creating an executable, it writes the buffer to its correct place in the executable file. In both cases, you can substantially increase the link speed by swapping to expanded memory. By default, swapping to extended memory is enabled, and swapping to expanded memory is disabled. If swapping is enabled and no appropriate memory exists in which to swap, then swapping does not occur.

/yx	(TLINK) Configures TLINK's use of extended memory. This option controls TLINK's use of extended memory for I/O buffering. By default, TLINK can use up to 8MB of extended memory. /yx+  uses all available extended memory up to 8MB. /yxn  uses only up to n KB extended memory.


ACBP Information (TLINK /s Option)

When the /s option is used, TLINK creates a detailed map of segments. For each segment in each module, this map file includes the address, length in bytes, class, segment name, group, module, and ACBP information. The ACBP field encodes the A (alignment), C (combination), and B (big) attributes into a set of four bit fields, as defined by Intel. TLINK uses only three of the fields, the A, C, and B fields. The ACBP value in the map is printed in hexadecimal. The following values of the fields must be OR'ed together to arrive at the ACBP value printed.

Field	Value	Description

The A field (alignment)	00	An absolute segment.

20	A byte-aligned segment.

40	A word-aligned segment.

60	A paragraph-aligned segment.

80	A page-aligned segment.

A0	An unnamed absolute portion of storage.

The C field (combination)	00	Cannot be combined.

08	A public combining segment.

The B field (big)	00	Segment less than 64K.

02	Segment exactly 64K.


Module Definition File

Example

A tool called IMPDEF creates module-definition files, and IMPLIB creates import libraries from module-definition files. The module-definition file provides information to TLINK about the contents and system requirements of a Windows application.

The module definition file names the .EXE or .DLL, identifies the application type, lists imported and exported functions, describes the code and data segment attributes, and lets you specify attributes for additional code and data segments, specifies the size of the stack, and provides for the inclusion of a stub program.

Specific elements of this file are the:

CODE statement

DATA statement

DESCRIPTION statement

EXETYPE statement

EXPORTS statement

IMPORTS statement

LIBRARY statement

NAME statement

SEGMENTS statement

STACKSIZE statement

STUB statement

When a module definition file is not specified

If no module-definition file is specified, the following defaults are assumed.

CODE	PRELOAD MOVEABLE DISCARDABLE

DATA	PRELOAD MOVEABLE MULTIPLE (for applications) or PRELOAD MOVEABLE SINGLE (for DLLs)

HEAPSIZE	4096

STACKSIZE	5120

If you want to change various attributes from the default, you'll need to have a module-definition file.

To replace the EXETYPE statement, the Borland C++ linker can discover what kind of executable you want to produce by checking settings in the IDE or options on the command line.

You can include an import library to substitute for the IMPORTS section of the module definition.

You can use the _export keyword in the definitions of export functions in your C and C++ source code to remove the need for an EXPORTS section. Note, however, that if _export is used to export a function, that function is exported by name rather than by ordinal (ordinal is usually more efficient).


CODE Statement (Module Definition File)

CODE defines the default attributes of code segments. Code segments can have any name, but must belong to segment classes whose name ends in CODE (such as CODE or MYCODE). The syntax is:

CODE [PRELOAD | LOADONCALL]

     [EXECUTEONLY | EXECUTEREAD]

     [IOPL | NOIOPL]

PRELOAD means code is loaded when the calling program is loaded.

LOADONCALL (the default) means the code is loaded when called by the program.

EXECUTEONLY means a code segment can only be executed.

EXECUTEREAD (the default) means the code segment can be read and executed.

IOPL means the code segment has I/O privileges.

NOIOPL (the default) means the code segment doesn't have I/O privileges.

CONFORMING (also known as 80286 conforming) means a code segment can be called from Ring 2 or Ring 3.

NONCONFORMING (the default) means the code segment is not 80286 conforming.


DATA Statement (Module Definition File)

DATA defines attributes of data segments. The syntax is:

DATA [NONE | SINGLE | MULTIPLE]

     [READONLY | READWRITE]

     [PRELOAD | LOADONCALL]

     [SHARED | NONSHARED]

NONE means that there is no data segment created. This option is available only for libraries.

SINGLE (the default for .DLLs) means a single data segment is created and shared by all processes.

MULTIPLE (the default for .EXEs) means that a data segment is created for each process.

READONLY means the data segment can be read only.

READWRITE means the data segment can be read and written to.

PRELOAD means the data segment is loaded when a module that uses it is first loaded.

LOADONCALL (the default) means the data segment is loaded when it is first accessed.

SHARED (the default for .DLLs) means one copy of the data segment is shared among all processes.

NONSHARED (the default for programs) means a copy of the data segment is loaded for each process needing to use the data segment.


DESCRIPTION Statement (Module Definition File)

DESCRIPTION (optional) inserts text into the application module and is typically used to embed author, date, or copyright information. The syntax is:

DESCRIPTION 'Text'

Text is an ASCII string delimited with single quotes.


EXETYPE Statement (Module Definition File)

EXETYPE defines the default executable file (.EXE) header type. The syntax is

EXETYPE  [WINDOWAPI] |

[WINDOWCOMPAT] | [NOTWINDOWCOMPAT]

WINDOWAPI is a Windows executable, and is equivalent to the TLINK option /aa.

WINDOWCOMPAT is a Windows-compatible character-mode executable, and is equivalent to the TLINK option /ap.

NOTWINDOWCOMPAT is a character-mode application which won't run under Windows. It is equivalent to the TLINK option /ai.


EXPORTS Statement (Module Definition File)

EXPORTS defines the names and attributes of functions to be exported. The EXPORTS keyword marks the beginning of the definitions. It can be followed by any number of export definitions, each on a separate line. The syntax is:

EXPORTS

   ExportName [Ordinal]

   [RESIDENTNAME] [Parameter]

ExportName specifies an ASCII string that defines the symbol to be exported as follows:

EntryName [=InternalName]

InternalName is the name used within the application to refer to this entry.

EntryName is the name listed in the executable file's entry table and is externally visible.

Ordinal defines the function's ordinal value as follows:

@ordinal

where ordinal is an integer value that specifies the function's ordinal value.

When an application or DLL module calls a function exported from a DLL, the calling module can refer to the function by name or by ordinal value. It's faster to refer to the function by ordinal because string comparisons aren't required to locate the function. To use less memory, export a function by ordinal (from the point of view of that function's DLL) and import/call a function by ordinal (from the point of view of the calling module).

When a function is exported by ordinal, the name resides in the nonresident name table. When a function is exported by name, the name resides in the resident name table. The resident name table for a module is in memory whenever the module is loaded; the nonresident name table isn't.

RESIDENTNAME specifies that the function's name must be resident at all times. This is useful only when exporting by ordinal (when the name wouldn't be resident by default).

Parameter is an optional integer value that specifies the number of words the function expects to be passed as parameters.


IMPORTS Statement (Module Definition File)

IMPORTS defines the names and attributes of functions to be imported from DLLs. Instead of listing imported DLL functions in the IMPORTS statement, you can either

specify an import library for the DLL in the TLINK command line, or

include the import library for the DLL in the project manager in the IDE.

The IMPORTS keyword marks the beginning of the definitions followed by any number of import definitions, each on a separate line. The syntax is

IMPORTS

   [InternalName=]ModuleName.Entry

InternalName is an ASCII string that specifies the unique name the application uses to call the function.

ModuleName specifies one or more uppercase ASCII characters that define the name of the executable module containing the function. The module name must match the name of the executable file. For example, the file SAMPLE.DLL has the module name SAMPLE.

Entry specifies the function to be imported--either an ASCII string that names the function or an integer that gives the function's ordinal value.


LIBRARY Statement (Module Definition File)

LIBRARY defines the name of a DLL module. A module-definition file can contain either a LIBRARY statement to indicate a DLL or a NAME statement to indicate a program.

A library's module name must match the name of the executable file. For example, the library MYLIB.DLL has the module name MYLIB. The syntax is:

LIBRARY LibraryName [INITGLOBAL | INITINSTANCE]

LibraryName (optional) is an ASCII string that defines the name of the library module. If you don't include a LibraryName, TLINK uses the file name with the extension removed. If the module-definition file includes neither a NAME nor a LIBRARY statement, TLINK assumes a NAME statement without a ModuleName parameter.

INITGLOBAL means the library-initialization routine is called only when the library module is first loaded into memory.

INITINSTANCE means the library-initialization routine is called each time a new process uses the library.


NAME Statement (Module Definition File)

NAME is the name of the application's executable module. The module name identifies the module when exporting functions. The syntax is:

NAME ModuleName

ModuleName (optional) specifies one or more uppercase ASCII characters that name the executable module. The name must match the name of the executable file. For example, an application with the executable file SAMPLE.EXE has the module name SAMPLE.

If ModuleName is missing, TLINK assumes that the module name matches the file name of the executable file. For example, if you do not specify a module name and the executable file is named MYAPP.EXE, TLINK assumes that the module name is MYAPP.

If the module-definition file includes neither a NAME nor a LIBRARY statement, TLINK assumes a NAME statement without a ModuleName parameter.


SEGMENTS Statement (Module Definition File)

SEGMENTS defines the segment attributes of additional code and data segments. The syntax is:

SEGMENTS

   SegmentName [CLASS 'ClassName']

   [MinAlloc]

   [SHARED | NONSHARED]

   [PRELOAD | LOADONCALL]

SegmentName is a character string that names the new segment. It can be any name, including the standard segment names _TEXT and _DATA, which represent the standard code and data segments.

ClassName (optional) is the class name of the specified segment. If no class name is specified, TLINK uses the class name CODE.

MinAlloc (optional) is an integer that specifies the minimum allocation size for the segment. Currently, TLINK ignores this value.

SHARED (the default for .DLLs) means one copy of the segment is shared among all processes.

NONSHARED (the default for programs) means a copy of the segment is loaded for each process needing to use the data segment.

PRELOAD means that the segment is loaded immediately; LOADONCALL means that the segment is loaded when it is accessed or called. The Resource Compiler may override the LOADONCALL option and preload segments instead.


STACKSIZE Statement (Module Definition File)

STACKSIZE defines the number of bytes needed by the application for its local stack. An application uses the local stack whenever it makes function calls. Do not use the STACKSIZE statement for dynamic-link libraries. The syntax is:

STACKSIZE bytes

bytes is an integer value that specifies the stack size in bytes.


STUB Statement (Module Definition File)

STUB appends a DOS executable file specified by FileName to the beginning of the module. The executable stub displays a warning message and terminate if the user attempts to run the executable stub in the wrong environment (running a Windows application under DOS, for example).

Borland C++ adds a built-in stub to the beginning of a Windows application unless a different stub is specified with the STUB statement. You should not use the STUB statement to include WINSTUB.EXE because the linker does this automatically.

The syntax is:

STUB "FileName"

FileName is the name of the DOS executable file to be appended to the module. The name must have the DOS file name format. If the file named by FileName is not in the current directory, TLINK searches for the file in the directories specified by the PATH environment variable.


Example Module Definition File

Here's a module definition file to serve as an example.

NAME           WHELLO

DESCRIPTION    'C++ Windows Hello World'

EXETYPE        WINDOWS

CODE           MOVEABLE

DATA           MOVEABLE MULTIPLE

HEAPSIZE       1024

STACKSIZE      5120

EXPORTS        MainWindowProc

Let's take this file apart, statement by statement:

NAME specifies a name for an application. If you want to build a DLL instead of an application, you would use the LIBRARY statement instead. Every module-definition file should have either a NAME statement or a LIBRARY statement, but never both. The name specified must be the same name as the executable file.

DESCRIPTION lets you specify a string that describes your application or library.

EXETYPE can be either WINDOWS or OS2. Only WINDOWS is supported in this version of Borland C++.

CODE defines the default attributes of code segments. The MOVEABLE option means that the code segment can be moved in memory at run-time.

DATA defines the default attributes of data segments. MOVEABLE means that it can be moved in memory at run-time. Windows lets you run more than one instance of an application at the same time. In support of that, the MULTIPLE options ensures that each instance of the application has its own data segment.

HEAPSIZE specifies the size of the application's local heap.

STACKSIZE specifies the size of the application's local stack. You can't use the STACKSIZE statement to create a stack for a DLL.

EXPORTS lists those functions in the WHELLO application that can be called by other applications or by Windows. Functions that are intended to be called by other modules are called callbacks, callback functions, or export functions.

To help you avoid the necessity of creating and maintaining long EXPORTS sections, Borland C++ provides the _export keyword. Functions flagged with _export are identified by the linker and entered into an export table for the module. If the Smart Callbacks option is used at compile time (/WS on the BCC command-line, or Options|Compiler|Entry/Exit Code|Windows Smart Callbacks), then callback functions do not need to be listed either in the EXPORTS statement or flagged with the _export keyword. Borland C++ compiles them in such a way so that they can be callback functions.

This application doesn't have an IMPORTS statement, because the only functions it calls from other modules are those from the Windows API; those functions are imported via the automatic inclusion of the IMPORT.LIB import library. When an application needs to call other external functions, these functions must be listed in the IMPORTS statement, or included via an import library.

This application doesn't include a STUB statement. Borland C++ uses a built-in stub for Windows applications. The built-in stub simply checks to see if the application was loaded under Windows, and, if not, terminates the application with a message that Windows is required. If you want to write and include a custom stub, specify the name of that stub with the STUB statement.


Transfer Macros

See Also

The Borland IDE recognizes certain macro names (or parameters that you want passed to the program) in the Command Line input box (parameter string) of the Tools dialog box. There are three kinds of transfer macros.

State Macros

Expand to a value that's based on the state of the IDE. The state macros are:

$ARG

$COL

$CONFIG

$DEF

$DEPLIST()

$ENV

$ERRCOL

$ERRLINE

$ERRNAME

$SELNODES

$TARGET

$INC

$LIB

$LINE

$PRJNAME

Storage Macros

Take data to be stored (such as file names) as arguments and return various parts of that data. For those that store file names, you can build up new file name specifications from existing file names.

The file name macros are:

$DIR()

$DRIVE()

$EDNAME

$EXT()

$NAME()

$OUTNAME

Instruction Macros

Tell the IDE to perform an action or make a setting. The instruction macros are:

$CAP EDIT

$CAP MSG

$IMPLIB

$NOSWAP

$OWLCVT

$PROMPT

$SAVE ALL

$SAVE CUR

$SAVE PROMPT

$RSP()

$TASM

$TD

$TLINKRSP

$UPTODATE

$WRITEMSG()


See Also

Alphabetical list of Transfer Macros


Transfer Arguments

When you choose a tool that contains a $PROMPT transfer macro in its command line, you will be prompted to enter arguments.

You can change or add to the parameter string before executing the tool.

The position of the $PROMPT macro in the command line determines what you see when prompted for arguments.

Anything preceding the $PROMPT macro is treated as a constant and won't be visible.


Alphabetical List of Transfer Macros

See Also

$ARG	the command-line parameters to be passed to a program.

$CAP	captures the output of a program

$CAP EDIT redirects program output into a standard file

$CAP MSG (filter) captures program output into message window

$COL	column number of current editor

$CONFIG	file name of config file

$DEF	pulls in contents of defines input but

$DEPLIST()	a list of dependencies for the currently selected node.

$DIR()	directory of file argument

$DRIVE()	drive of file argument

$EDNAME	name of file in active editor

$ENV	the contents of an environment variable.

$ERRCOL	column number of current error in file $ERRNAME

$ERRLINE	line number of current error in file $ERRNAME

$ERRNAME	line number of current error in file $ERRNAME

$EXT()	extension of file argument

$IMPLIB	executes IMPLIB

$INC	pulls in contents of include directories input box

$LIB	pulls in contents of library directories input box

$LINE	line number of current editor

$NAME()	name part of file argument

$NOSWAP	prevents user screen swap when program runs

$OUTNAME	expands to path and file name in the output path input box

$OWLCVT	builds command-line for transfering to owlcvt.exe, a utility used to aid in converting OWL1 source to OWL2 source.

$PRJNAME	current project file

$PROMPT	displays expanded parameter string before transfer program is called

$RSP()	places the expanded contents of the macro into a temporary file.

$SAVE	saves files in open edit windows

$SAVE ALL saves all modified files in edit window

$SAVE CUR saves modified file in current edit window

$SAVE PROMPT causes IDE to prompt when there are unsaved files in edit window

$SELNODES	the nodes currently selected in the project window.

$TARGET	the name of the current target.

$TASM	predefined for use with Turbo Assembler

$TD	selects the appropriate debugger for the current target.

$TLINKRSP	builds a response file for calling TLINK.

$UPTODATE	forces a make on the current target.

$WRITEMSG()	copies contents of message window to specified ASCII file


See Also

Functional List of Transfer Macros


$ARG

Transfer Macros

The $ARG transfer macro expands to the command-line parameters to be passed to a program run from the IDE using the Debug|Run menu command.

For example,

$TD $ARG

runs the stand-alone debugger on the current target, passing the command line parameters to the program.


$CAP EDIT

See Also	Transfer Macros

The $CAP EDIT transfer macro tells the IDE to redirect program output into a standard file.

After the transfer program is completed, a new edit window is created, and the captured output is displayed.

The captured output resides in a special edit window titled Transfer Output.

For $CAP EDIT to work correctly:

the transfer program must write to DOS standard output

you must also use the $NOSWAP macro.


See Also

$CAP MSG (filter)


$CAP MSG (filter)

See Also	Transfer Macros

The $CAP MSG transfer macro captures the program output and places it in the Message window, using a DLL filter for the converting program output into Message window format.

A special header ensures that the file is in the correct format.

Four filters are provided:

IMPL2MSG.DLL - Turbo Implib  (IMPLIB)

TASM2MSG.EXE - Turbo Assembler (TASM) and Microsoft assembler (MASM)

GREP2MSG.DLL - Grep

RC2MSG.DLL - Borland resource compiler (BRC) and MS resource compiler (RC)

BORL2MSG.DLL - Borland standard output filter. Can be used for any tool that has error and warning and fatals outputed as per the BCC command line compiler. This filter will work for Owl convert (OWLCVT),  Borland C++ (BCC and BCC32), Borland C/C++ preprocessor (CPP and CPP 32),  Borland Keymap Compiler (KEYMAPR), Borland Turbo Linker (TLINK and TLINK32) as well as other utilities.

HC312MSG.DLL  -  Microsoft help compiler (HC31)

You can write your own filters for other transfer programs you install. The source code to these filters is also provided in the EXAMPLES\IDE\FILTER subdirectory of your Borland C++ installation directory (usually BC4), a project file named FILTER.IDE will build the filters for you, and the tool API header file is named toolapi.h.

Any program that has line-oriented messages output (file and line number) can be used with this macro.


See Also

$CAP EDIT


$COL

Transfer Macros

The $COL transfer macro expands to the column number of the cursor in the current edit window.

If the active window is not an edit window, the string is set to 0.


$CONFIG

Transfer Macros

The $CONFIG transfer macro expands to the complete file name of the current configuration file.

This is a null string if no configuration file is defined. This macro is intended for use by programs that access or modify the configuration file. Besides providing the name of the file, this macro causes the current configuration to be saved (if modified) and reloaded when control returns to the IDE.

Use $CONFIG with Keymapper. With it, you can edit the keyboard script file in an editor and then invoke Keymapper to process the script.

When the configuration file is reloaded, your new or modified editor commands will be in effect.

When installing Keymapper as a transfer item, use the following command line:

$EDNAME

$CONFIG

This assumes the current edit window contains the keyboard script file to be processed.


$DEF

Transfer Macros

The $DEF transfer macro pulls in the contents of the Defines input box.

Use this macro to specify #define directives to an external translator.


$DEPLIST()

See Also	Transfer Macros

The $DEPLIST([node-type[,prefix[,post-fix]]]) transfer macro expands to a list of dependencies for the currently selected node in the project window.

The list is derived from the supplied extension by searching the dependencies of the selected node for a list of those extensions. Multiple dependecies will be separated by a space. Default project nodes are included in the list, as are nodes in associated source pools. For example,

$DEPLIST(.OBJ)

when applied to a .DLL or .EXE node, would list all the object nodes (.OBJ files) that would be linked into the target.

You can also specify prefix and postfix characters. For example, on a .LIB node, do $DEPLIST (.OBJ, -t) and the -t will be prefixed to each .obj.


See Also

$TARGET

$SELNODES


$DIR()

Transfer Macros

The $DIR transfer macro returns the directory portion of the path passed as an argument, without a trailing backslash.

Example

$DIR(D:\bc4\bin\bcc.exe)

expands to:

\bc4\bin


$DRIVE()

Transfer Macros

The $DRIVE transfer macro expands to the drive of the file argument.

Example

$DRIVE(D:\bc4\bin\bcc.exe)

expands to:

D:


$EDNAME

Transfer Macros

The $EDNAME transfer macro expands to the complete file name of file in the active Edit window.

If no Edit windows are active, then $EDNAME performs the same function as $SELNODES, expanding to the items currently selected in the Project window.


$ENV

Transfer Macros

The $ENV transfer macro expands to the contents of the environment variable supplied to the macro. If the specified variable cannot be found in the environment, the expansion does nothing.

Example

$ENV(PATH)

expands to the path setting in the environment.


$ERRCOL

See Also	Transfer Macros

The $ERRCOL transfer macro returns the column number of the current error displayed in the Message window. in the file $ERRNAME.

If there are no messages, the string is expanded to null string.


See Also

$ERRLINE


$ERRLINE

See Also	Transfer Macros

The $ERRLINE transfer macro returns the line number of the current error displayed in the Message window. in the file $ERRNAME.

If there are no messages, the string is expanded to null string.


See Also

$ERRCOL


$ERRNAME

See Also	Transfer Macros

The $ERRNAME transfer macro returns the complete file name of file referred to by the selected messages in the Message window.

$ERRNAME returns a null string if:

there are no messages, or

the current message does not refer to a file.


See Also

$ERRCOL

$ERRLINE


$EXT()

Transfer Macros

The $EXT transfer macro is the extension of the file argument; it does not include the period.

Example

$EXT(D:\bc4\bin\bcc.exe)

returns

exe


$IMPLIB

Transfer Macros

The $IMPLIB transfer macro executes IMPLIB.

$IMPLIB expands to:

$NOSWAP $CAP MSG(IMPL2MSG)$OUTNAME $EDNAME

The IMPL2MSG filter captures messages to a file that can be displayed in the Message window.


$INC

See Also	Transfer Macros

The $INC transfer macro expands to the list of include directories defined for the current node.

If a project is not loaded, the global include directory settings are returned.


See Also

$LIB


$LIB

See Also	Transfer Macros

The $LIB transfer macro expands to the list of library directories defined for the current node.

If a project is not loaded, the global library directory settings are returned.


See Also

$INC


$LINE

Transfer Macros

The $LINE transfer macro returns the line number where the cursor is located in the active edit window.

If the active window is not an edit window, the string is set to 0.


$NAME()

Transfer Macros

The $NAME transfer macro returns the file name part of the file argument. It does not include the period.

Example

$NAME(D:\bc4\bin\bcc.exe)

returns

bcc


$NOSWAP

Transfer Macros

The $NOSWAP transfer macro in a command line instructs the IDE not to show the transfer tool while it is running.  Windows applications and .PIF files run with NOSWAP are invoked with SW_HIDE.  A WINOLDAPP run from the IDE will cause a noticable screen swap when this macro is not present.

$NOSWAP has no effect on WINOLDAPPS under STANDARD mode windows.

Use this macro in conjunction with $CAP_MSG.


$OUTNAME

Transfer Macros

The $OUTNAME transfer macro expands to the path and file name that appears in the Intermediate or Final output box (depending on translator).

For example, if the project contains STARS.C, the default Output Path file name is STARS.OBJ.

This macro is useful when you are specifying modules for your user-defined translators.

If there is no project defined, $OUTNAME performs the same function as $EDNAME.


$OWLCVT

See Also	Transfer Macros

The $OWLCVT transfer macro builds a complete command-line for transfering to OWLCVT.EXE.

OWLCVT.EXE is a utility used to aid in converting OWL1 source to OWL2 source.


See Also

Transfer Arguments


$PRJNAME

See Also	Transfer Macros

The $PRJNAME transfer macro expands to the name of the current project file.

A null string is returned if no project is defined.


See Also

$DEPLIST

$SELNODES

$TARGET


$PROMPT

See Also	Transfer Macros

The $PROMPT transfer macro tells the IDE to display the transfer program's expanded parameter string in the Program Arguments input box for verification.

You can change or add to the string before it is passed to the transfer program.

The position of $PROMPT in the command line determines what is shown in the dialog box. You can place constant parameters in the command line by placing them before $PROMPT.

Example

The /c in

/c $PROMPT dir

is constant and does not show in the dialog box, but dir can be edited before the command is run.


See Also

Transfer Arguments


$RSP()

Transfer Macros

The $RSP() transfer macro places the expanded contents of the macro into a temporary file.  The IDE will attempt to place the temporary file as follows:

1.	in the project directory.

2.	Windows temporary directory.

3.	the current directory if it differs from the project directory

The temporary file will automatically be deleted when the transfer to the tool is completed.


$SAVE ALL

See Also	Transfer Macros

The $SAVE ALL transfer macro tells the IDE to save all files in all edit windows that have been modified, without prompting.


See Also

$SAVE CUR

$SAVE PROMPT


$SAVE CUR

See Also	Transfer Macros

The $SAVE CUR transfer macro tells the IDE to save the file in the current edit window if it has been modified. This ensures that the transfer program will use the latest version of the source file.


See Also

$SAVE ALL

$SAVE PROMPT


$SAVE PRJ

See Also	Transfer Macros

The $SAVE PRJ transfer macro tells the IDE to save the options of the current project.


See Also

$SAVE ALL

$SAVE CUR

$SAVE PROMPT


$SAVE PROMPT

See Also	Transfer Macros

The $SAVE PROMPT transfer macro tells the IDE to prompt when there are unsaved files in edit windows.


See Also

$SAVE ALL

$SAVE CUR


$SELNODES

See Also	Transfer Macros

The $SELNODES transfer macro expands to the nodes currently selected in the project window. Each node name will be separated by spaces.


See Also

$TARGET


$TARGET

See Also	Transfer Macros

The $TARGET transfer macro expands to the name of the current target of the project as determined by the node currently selected in the project window.


See Also

$SELNODES


$TASM

Transfer Macros

The $TASM transfer macro is predefined for use with Turbo Assembler (TASM). It uses the TASM2MSG filter to trap TASM messages. $TASM is essentially shorthand for this:

$NOSWAP $SAVE CUR $CAP MSG(TASM2MSG.DLL) /ml $EDNAME,$OUTNAME


$TD

Transfer Macros

The $TD transfer macro selects the appropriate debugger for the current target. That debugger is invoked with the result of $TARGET.


$TLINKRSP

See Also	Transfer Macros

The $TLINKRSP transfer macro builds a response file for calling TLINK. The following would designate the use of TLINK as the executable.

@$RSP($TLINKRSP)


See Also

$RSP


$UPTODATE

Transfer Macros

The $UPTODATE transfer macro forces a make on the current target before invoking the transfer tool.


$WRITEMSG
$WRITEMSG()

Transfer Macros

The $WRITEMSG() transfer macro copies the contents of the Message window to the specified ASCII file.

The translator can parse the file and act on the desired messages. For example:

WRITEMSG(C:\MESSAGES.TXT)

writes to the file MESSAGES.TXT in your root directory.


Using IMPLIB

See Also

The IMPLIB utility creates import library. IMPLIB takes as input DLLs, module definition files, or both, and produces an import library as output.

If you've created an Windows application, you've already used at least one import library, IMPORT.LIB, the import library for the standard Windows DLLs. (IMPORT.LIB is linked automatically when you build an Windows application in the IDE and when using BCC to link. You have to explicitly link with IMPORT.LIB only if you're using TLINK to link separately.)

An import library lists some or all of the exported functions for one or more DLLs. IMPLIB creates an import library directly from DLLs or from module definition files for DLLs (or a combination of the two).

Creating an Import Library for a DLL

Options must be lowercase and preceded by either a hyphen or a slash.

Type:

IMPLIB Options LibName [ DefFiles... | DLLs... ]

where Options is an optional list of one or more IMPLIB options, LibName is the name for the new import library, DefFiles is a list of one or more existing module definition files for one or more DLLs, and DLLs is a list of one or more existing DLLs. You must specify at least one DLL or module definition file.

Note:	A DLL can also have an extension of .EXE or .DRV, not just .DLL.

Option	Description

-i	Tells IMPLIB to ignore WEP, the Windows exit procedure required to end a DLL. Use this option if you are specifying more than one DLL on the IMPLIB command line.

-c	Warnings on case sensitive symbols

-o	Remove module extensions. (16-bit Windows only)

-w	No warnings.


See Also

Classes in a DLL

Functions in a DLL

IMPDEF

TLIB


Using The Module-Definition File Manager (IMPDEF)

See Also

Import libraries provide access to the functions in a Windows DLL.

IMPDEF takes as input a DLL name, and produces as output a module definition file with an export section containing the names of functions exported by the DLL.

The syntax is:

IMPDEF DestName.DEF SourceName.DLL

This creates a module definition file named DestName.DEF from the file SourceName.DLL. The resulting module definition file would look something like this:

LIBRARY     FileName

DESCRIPTION 'Description'

EXPORTS

            ExportFuncName              @Ordinal

        .

        .

        .

            ExportFuncName              @Ordinal

where:

FileName is the DLL's root file name

Description is the value of the DESCRIPTION statement if the DLL was previously linked with a module definition file that included a DESCRIPTION statement

ExportFuncName names an exported function

Ordinal is that function's ordinal value (an integer).


See Also

Classes in a DLL

Functions in a DLL

IMPLIB

TLIB


Classes in a DLL;
Classes in a DLL

See Also

IMPDEF is useful for a DLL that uses C++ classes. If you use the _export keyword when defining a class, all of the non-inline member functions and static data members for that class are exported. It's easier to let IMPDEF make a module definition file for you because it lists all the exported functions, and automatically includes the member functions and static data members.

Since the names of these functions are mangled, it would be tedious to list them all in the EXPORTS section of a module definition file simply to create an import library from the module definition file. If you use IMPDEF to create the module definition file, it will include the ordinal value for each exported function. If the exported name is mangled, IMPDEF will also include that function's unmangled, original name as a comment following the function entry. So, for instance, the module definition file created by IMPDEF for a DLL that used C++ classes would look something like this:

LIBRARY     FileName

DESCRIPTION 'Description'

EXPORTS

            MangledExportFuncName  @Ordinal ; ExportFuncName

        .

        .

        .

            MangledExportFuncName  @Ordinal ; ExportFuncName

where

FileName is the DLL's root file name

Description is the value of the DESCRIPTION statement if the DLL was previously linked with a module definition file that included a DESCRIPTION statement

MangledExportFuncName provides the mangled name

Ordinal is that function's ordinal value (an integer)

ExportFuncName gives the function's original name.


See Also

IMPDEF

IMPLIB

TLIB


Functions in a DLL

See Also

IMPDEF creates an editable source file that lists all the exported functions in the DLL. You can edit this .DEF file to contain only those functions that you want to make available to a particular application, then run IMPLIB on the edited .DEF file. This results in an import library that contains import information for a specific subset of a DLL's export functions.

Suppose you're distributing a DLL that provides functions to be used by several applications. Every export function in the DLL is defined with _export. Now, if all the applications used all the DLL's exports, then you could use IMPLIB to make one import library for the DLL. You could deliver that import library with the DLL, and it would provide import information for all of the DLL's exports. The import library could be linked to any application, thus eliminating the need for the particular application to list every DLL function it uses in the IMPORTS section of its module definition file.

But let's say you want to give only a few of the DLL's exports to a particular application. Ideally, you want a customized import library to be linked to that application--an import library that provides import information only for the subset of functions that the application will use. All of the other export functions in the DLL will be hidden to that client application.

To create an import library that satisfies these conditions, run IMPDEF on the compiled and linked DLL. IMPDEF produces a module definition file that contains an EXPORT section listing all of the DLL's export functions. You can edit that module definition file, remove the EXPORTS section entries for those functions you don't want in the customized import library, and then run IMPLIB on the module definition file. The result will be an import library that contains import information for only those export functions listed in the EXPORTS section of the module definition file.


See Also

IMPDEF

IMPLIB

TLIB


Using TLIB

See Also

When it modifies an existing library, TLIB always creates a copy of the original library with a .BAK extension.

Build or Modify Libraries

The libraries included with Borland C++ were built with TLIB. You can use TLIB to build your own libraries, or to modify the Borland C++ libraries, your libraries, libraries furnished by other programmers, or commercial libraries you've purchased.

You can use TLIB to:

Create a new library from a group of object modules.

Add object modules or other libraries to an existing library.

Remove object modules from an existing library.

Replace object modules from an existing library.

Extract object modules from an existing library.

List the contents of a new or existing library.

TLIB can also create (and include in the library file) an extended dictionary, which can be used to speed up linking.

Although TLIB is not essential for creating executable programs with Borland C++, it is a useful programming productivity tool that can be indispensable for large development projects.


See Also

IMPDEF

IMPLIB

Operation List

TLIB Command-Line Options

TLIB Examples

Using TLIB Response Files


TLIB Command-line Options

See Also

The TLIB command line takes the following general form, where items listed in square brackets are optional:

tlib [@respfile] [option] libname [operations] [, listfile]

TLIB options

For an online summary of TLIB options, type TLIB and press Enter.

Option	Description

@respfile	The path and name of the response file you want to include. You can specify more than one response file.

libname	The DOS path name of the library you want to create or manage. Every TLIB command must be given a libname. Wildcards are not allowed. TLIB assumes an extension of .LIB if none is given. Use only the .LIB extension because both BCC and the IDE require the .LIB extension in order to recognize library files. Note: If the named library does not exist and there are add operations, TLIB creates the library.

/C	The case-sensitive flag. This option is not normally used.

/E	Creates Extended Dictionary

/Psize	Sets the library page size to size.

/0	Purges comment records.

operations	The list of operations TLIB performs. Operations can appear in any order. If you only want to examine the contents of the library, don't give any operations.

listfile	The name of the file that lists library contents. The listfile name (if given) must be preceded by a comma. No listing is produced if you don't give a file name. The listing is an alphabetical list of each module. The entry for each module contains an alphabetical list of each public symbol defined in that module. The default extension for the listfile is .LST. You can direct the listing to the screen by using the listfile name CON, or to the printer by using the name PRN.


See Also

IMPDEF

IMPLIB

Operation List

TLIB Examples

TLIB


Using TLIB Response Files

See Also

When you use a large number of operations, or if you find yourself repeating certain sets of operations over and over, you will probably want to use response files. A response file is an ASCII text file (which can be created with the Borland C++ editor) that contains all or part of a TLIB command. Using TLIB Response Files, you can build TLIB commands larger than would fit on one command line. Response files can

Contain more than one line of text; use the ampersand character (&) at the end of a line to indicate that another line follows.

Include a partial list of commands. You can combine options from the the command line with options in a response file.

be used with other response files in a single TLIB command line.


See Also

TLIB Command-Line Options

TLIB Examples

TLIB


TLIB /C Option

See Also

Using Case-Sensitive Symbols in a Library

When you add a module to a library, TLIB maintains a dictionary of all public symbols defined in the modules of the library. All symbols in the library must be distinct. If you try to add a module to the library that duplicates a symbol, TLIB displays an error message and doesn't add the module.

Normally, when TLIB checks for duplicate symbols in the library, uppercase and lowercase letters are not treated differently (for example, the symbols lookup and LOOKUP are treated as duplicates). You can use the /C option to add a module to a library that includes symbols differing only in case.

Don't use /C if you plan to use the library with other linkers or let other people use the library.

TLIB normally rejects symbols that differ only in case because some linkers aren't case-sensitive. TLINK has no problem distinguishing uppercase and lowercase symbols. As long as you use your library only with TLINK, you can use the TLIB /C option without any problems.


See Also

TLIB Command-Line Options

TLIB Examples

TLIB


TLIB /E Option

See Also

Creating an Extended Dictionary

To increase the capacity of TLINK for large links, you can use TLIB to create an extended dictionary and append it to the library file. This dictionary contains, in a compact form, information that is not included in the standard library dictionary and that lets TLINK process library files so that those modules not needed in the link are not processed.

To create an extended dictionary for a library that is being modified, use the /E option when you start TLIB to add, remove, or replace modules in the library. To create an extended dictionary for an existing library that you don't want to modify, use the /E option. For example, if you type the following text, TLINK appends an extended dictionary to the specific library:

   tlib /E mylib

If you get the message "Table limit exceeded", use /E to see if it helps. If you use /E to add a library module containing a C++ class with a virtual function, you'll get the error message, Library contains COMDEF records--extended dictionary not created.


See Also

TLIB Command-Line Options

TLIB Examples

TLIB


TLIB /P Option

See Also

Setting the Page Size to Create a Large Library

Every DOS library file contains a dictionary that appears at the end of the .LIB file, following all of the object modules. For each module in the library, the dictionary contains a 16-bit address of that particular module within the .LIB file; this address is given in terms of the library page size (it defaults to 16 bytes).

The library page size determines the maximum combined size of all object modules in the library, which cannot exceed 65,536 pages. The default (and minimum) page size of 16 bytes allows a library of about 1 MB in size. To create a larger library, use the /P option to increase the page size. The page size must be a power of 2, and it cannot be smaller than 16 or larger than 32,768.

All modules in the library must start on a page boundary. For example, in a library with a page size of 32 (the lowest possible page size higher than the default 16), an average of 16 bytes will be lost per object module in padding. If you attempt to create a library that is too large for the given page size, TLIB will issue an error message and suggest that you use /P with the next available higher page size.


See Also

TLIB Command-Line Options

TLIB Examples

TLIB


Operation List

See Also

The operation list describes what actions you want TLIB to do and consists of a sequence of operations given one after the other. Each operation consists of a one- or two-character action symbol followed by a file or module name. You can put whitespace around either the action symbol or the file or module name, but not in the middle of a two-character action or in a name.

You can put as many operations as you like on the command line, up to DOS's COMMAND.COM-imposed line-length limit of 127 characters. The order of the operations is not important. TLIB always applies the operations in a specific order:

To replace a module, remove it, then add the replacement module.

1.	All extract operations are done first.

2.	All remove operations are done next.

3.	All add operations are done last.

TLIB finds the name of a module by stripping any drive, path, and extension information from the given file name.

Note that TLIB always assumes reasonable defaults. For example, to add a module that has an .OBJ extension from the current directory, you need to supply only the module name, not the path and .OBJ extension.

Wildcards are never allowed in file or module names.

TLIB recognizes three action symbols (*, +, *), which you can use singly or combined in pairs for a total of five distinct operations. The order of the characters is not important for operations that use a pair of characters. The action symbols and what they do are listed here:

To create a library, add modules to a library that does not yet exist.

TLIB action symbols

Symbol 	Name	Description

+	Add	TLIB adds the named file to the library. If the file has no extension, TLIB assumes an extension of .OBJ. If the file is itself a library (with a .LIB extension), then the operation adds all of the modules in the named library to the target library.

If a module being added already exists, TLIB displays a message and does not add the new module.

-	Remove	TLIB removes the named module from the library. If the module does not exist in the library, TLIB displays a message.

A remove operation needs only a module name. TLIB lets you enter a full path name with drive and extension included, but ignores everything except the module name.

*	Extract	TLIB creates the named file by copying the corresponding module from the library to the file. If the module does not exist, TLIB displays a message and does not create a file. If the named file already exists, it is overwritten.

You can't directly rename modules in a library. To rename a module, extract and remove it, rename the file just created, then add it back into the library.

-*	Extract &	TLIB copies the named module to the corresponding

*-	Remove	file name and then removes it from the library.

-+	Replace	TLIB replaces the named module with the corresponding file.


See Also

TLIB Command-Line Options

TLIB Examples

TLIB


TLIB Examples

These simple examples demonstrate some of the different things you can do with TLIB:

Example 1

To create a library named MYLIB.LIB with modules X.OBJ, Y.OBJ, and Z.OBJ, type:

tlib mylib +x +y +z.

Example 2

To create a library named MYLIB.LIB and get a listing in MYLIB.LST too, type:

tlib mylib +x +y +z, mylib.lst.

Example 3

To get a listing in CS.LST of an existing library CS.LIB, type:

tlib cs, cs.lst.

Example 4

To replace module X.OBJ with a new copy, add A.OBJ and delete Z.OBJ from MYLIB.LIB, type:

tlib mylib -+x +a -z.

Example 5

To extract module Y.OBJ from MYLIB.LIB and get a listing in MYLIB.LST, type:

tlib mylib *y, mylib.lst.

Example 6

To create a new library named ALPHA, with modules A.OBJ, B.OBJ, ..., G.OBJ using a response file:

1.	First create a text file, ALPHA.RSP, with

+a.obj +b.obj +c.obj &

      +d.obj +e.obj +f.obj &

      +g.obj

2.	Then use the TLIB command, which produces a listing file named ALPHA.LST:

tlib alpha @alpha.rsp, alpha.lst


IMPLIB

IMPLIB creates import libraries, and IMPDEF creates module definition files (.DEF files). Import libraries and module definition files provide information to the linker about functions imported from dynamic-link libraries (DLLs).


TLIB

TLIB is a utility that manages libraries of individual .OBJ (object module) files. A library is a convenient tool for dealing with a collection of object modules as a single unit.


Import Libraries

Import libraries contain records. Each record contains the name of a DLL, and specifies where in the DLL the imported functions reside. These records are bound to the application by TLINK or the IDE linker, and provide Windows with the information necessary to resolve DLL function calls. An import library can be substituted for part or all of the IMPORTS section of a module definition file.


IMPDEF

IMPDEF takes as input a DLL name, and produces as output a module definition file with an export section containing the names of functions exported by the DLL.


GREP: A Text-Search Utility

See Also

GREP (Global Regular Expression Print) is a powerful text-search program derived from the UNIX utility of the same name. GREP searches for a text pattern in one or more files or in its standard input stream.

Here is a quick example of a situation where you might want to use GREP. Suppose you wanted to find out which text files in your current directory contained the string "Bob". You would type:

grep Bob *.txt

GREP responds with a list of the lines in each file (if any) that contained the string "Bob". Because GREP does not ignore case by default, the strings "bob" and "boB" do not match.

GREP can do a lot more than match a single, fixed string. In the following section, you will see how to make GREP search for any string that matches a particular pattern.


See Also

Command-Line Options

Command-Line Syntax

Examples

File Specifications

The Search String


GREP: Command-Line Syntax

See Also

The general command-line syntax for GREP is

grep [-options] searchstring [file(s) ... ]

Option	Description

options	consist of one or more letters, preceded by a hyphen (-), that changes the behavior of GREP.

searchstring	gives the pattern to search for.

file(s)	tells GREP which files to search. (If you do not specify a file, GREP searches standard input; this lets you use pipes and redirection.)

Redirecting Output from GREP

If you find that the results of your GREP are longer than one screen, you can redirect the output to a file. For example, you could use this command:

GREP "Bob" *.txt > temp.txt

which searches all files with the TXT extension in the current directory, then puts the results in a file called TEMP.TXT. (You can name this file anything you like.) Use any word processor to read TEMP.TXT (the results of the search).

The command GREP ? prints a help screen showing the options, special characters, and defaults for GREP.


See Also

Command-Line Options

Examples

File Specifications

GREP: A Text-Search Utility

The Search String


GREP: Command-Line Options

See Also

In the command line, options are one or more single characters preceded by a hyphen (-). Each individual character is a switch that you can turn on or off: A plus symbol (+) after a character turns the option on; a hyphen (-) after the character turns the option off. The + sign is optional; for example, -r means the same thing as -r+. You can list multiple options individually (like this: -i -d -l), or you can combine them (like this: -ild or -il, -d, and so on).

Here are the GREP option characters and their meanings:

Option	Description

-c	Match Count only: Prints only a count of matching lines. For each file that contains at least one matching line, GREP prints the file name and a count of the number of matching lines. Matching lines are not printed. This option is off by default.

-d	Search subdirectories: For each file specified on the command line, GREP searches for all files that match the file specification, both in the directory specified and in all subdirectories below the specified directory. If you give a file without a path, GREP assumes the files are in the current directory. This option is off by default.

-i	Ignore case: GREP ignores upper/lowercase differences. When this option is on, GREP treats all letters a to z as identical to the corresponding letters A to Z in all situations. This option is off by default.

-l	List file names only: Prints only the name of each file containing a match. After GREP finds a match, it prints the file name and processing immediately moves on to the next file. This option is off by default.

-n	Line Numbers: Each matching line that GREP prints is preceded by its line number. This option is off by default.

-o	UNIX output format: Changes the output format of matching lines to support more easily the UNIX style of command-line piping. All lines of output are preceded by the name of the file that contained the  matching line. This option is off by default.

-r	Regular expression search: The text defined by searchstring is treated as a regular expression instead of as a literal string. This option is on by default. A regular expression is one or more occurrences of one or more characters optionally enclosed in quotes. The following symbols are treated specially:

^  start of line	$  end of line

.  any character	\  quote next character

*  match zero or more	+  match one or more

[aeiou0-9]	match a, e, i, o, u, and 0-9

[^aeiou0-9]	match all but a, e, i, o, u, and 0-9

-u	pdate options: GREP adds any options from the command line to its default options in GREP.COM. This option lets you to customize the default option settings. To see the defaults are set in GREP.COM, type GREP ?, then each option on the help screen is followed by a + or a - depending on its default setting.

-v	onmatch: Prints only nonmatching lines. Only lines that do not contain the search string are considered nonmatching lines. This option is off by default.

-w	Word search: Text found that matches the regular expression is considered a match only if the character immediately preceding and following cannot be part of a word. The default word character set includes A to Z, 0 to 9, and the underscore ( _ ). This option is off by default. An alternate form of this option lets you specify the set of legal word characters. Its form is -w[set], where set is any valid regular expression.

If you define the set with alphabetic characters, it is automatically defined to contain both the uppercase and lowercase values for each letter in the set (regardless of how it is typed), even if the search is case-sensitive. If you use the -w option in combination with the -u option, the new set of legal characters is saved as the default set.

-z	Verbose: GREP prints the file name of every file searched. Each matching line is preceded by its line number. A count of matching lines in each file is given, even if the count is zero. This option is off by default.

?	displays a help screen showing the options, special characters, and defaults for GREP.


See Also

Command-Line Syntax

Examples

File Specifications

GREP: A Text-Search Utility

The Search String


GREP: The Search String

See Also

The value of searchstring defines the pattern GREP searches for. A search string can be either a regular expression or a literal string.

In a regular expression, certain characters have special meanings: They are operators that govern the search.

In a literal string, there are no operators: Each character is treated literally.

You can enclose the search string in quotation marks to prevent spaces and tabs from being treated as delimiters. The text matched by the search string cannot cross line boundaries; that is, all the text necessary to match the pattern must be on a single line.

A regular expression is either a single character or a set of characters enclosed in brackets. A concatenation of regular expressions is a regular expression.

When you use the -r option (on by default), the search string is treated as a regular expression (not a literal expression. The following characters have special meanings:

Symbol	Description

 ^	A circumflex at the start of the expression matches the start of a line.

 $	A dollar sign at the end of the expression matches the end of a line.

 .	A period matches any character.

 *	An asterisk after a string matches any number of occurrences of that string followed by any characters, including zero characters. For example, bo* matches bot, boo, and as well as bo.

 +	A plus sign after a string matches any number of occurrences of that string followed by any characters, except zero characters. For example, bo+ matches bot and boo, but not b or bo.

{ }	Characters or expressions in braces are grouped so that the evaluation of a search pattern can be controlled and so grouped text can be referred to by number.

[ ]	Characters in brackets match any one character that appears in the brackets, but no others. For example [bot] matches b, o, or t.

[^]	A circumflex at the start of the string in brackets means NOT. Hence, [^bot] matches any characters except b, o, or t.

[-]	A hyphen within the brackets signifies a range of characters. For example, [b-o] matches any character from b through o.

  \  	A backslash before a wildcard character tells the C++ IDE to treat that character literally, not as a wildcard. For example, \^ matches ^ and does not look for the start of a line.

Four of the "special" characters ($, ., *, and +) do not have any special meaning when used within a bracketed set. In addition, the character ^ is only treated specially if it immediately follows the beginning of the set definition (immediately after the [ delimiter).


See Also

Command-Line Options

Command-Line Syntax

Examples

File Specifications

GREP: A Text-Search Utility


GREP: File Specifications

See Also

The files option tells GREP which files to search. Files can be an explicit file name or a generic file name  incorporating the DOS ? and * wildcards. In addition, you can type a path (drive and directory information). If you list files without a path, GREP searches the current directory. If you do not specify any files, input to GREP must come from redirection (<) or a vertical bar (|).


See Also

Command-Line Options

Command-Line Syntax

Examples

GREP: A Text-Search Utility

The Search String


GREP: Examples

See Also

These examples show how to combine the features of GREP to do different kinds of searches. They assume default settings for GREP are unchanged.

grep -r [^a-z]main\ *( *.c

grep -ri [a-c]:\\data\.fil *.c *.inc

grep "search string with spaces" *.doc *.c

grep -rd "[ ,.:?'\"]"$ \*.doc

grep -w[=] = *.c


See Also

GREP: Examples


GREP: Example 1

See Also

Command

grep -r [^a-z]main\ *( *.c

Matches

main(i,j:integer)

if (main  ()) halt;

if (MAIN  ()) halt;

Does Not Match

mymain()

Explanation

The search string tells GREP to search for the word main with no preceding lowercase letters ([^a-z]), followed by zero or more occurrences of blank spaces (\ *), then a  left parenthesis. Since spaces and tabs are normally  considered command-line delimiters, you must quote them if you want to include them as part of a regular expression. In this case, the space after main is quoted with the backslash escape character. You could also accomplish this by placing the space in double quotes.


GREP: Example 2

See Also

Command

grep -ri [a-c]:\\data\.fil *.c *.inc

Matches

A:\data.fil

B:\DATA.FIL

c:\Data.Fil

Does Not Match

d:\data.fil

a:data.fil

Explanation

Because the backslash (\) and period (.) characters usually have special meaning in path and file names, you must place the backslash escape character  immediately in front of them if you want to search for them. The -i option is used here, so the search is not case sensitive.


GREP: Example 3

See Also

Command

grep "search string with spaces" *.doc *.c

Matches

This is a search string with spaces in it.

Does Not Match

This search string has spaces in it.

Explanation

This is an example of how to search for a string with embedded spaces.


GREP: Example 4

See Also

Command

grep -rd "[ ,.:?'\"]"$ \*.doc

Matches

He said hi to me.

Where are you going?

In anticipation of a unique situation,

Examples include the following:

"Many men smoke, but fu man chu."

Does Not Match

He said "Hi" to me

Where are you going? I'm headed to the

Explanation

This example searches for any one of the characters " . : ? ' and , at the end of a line. The double quote within the range is preceded by an escape character so it is treated as a normal character instead of as the ending quote for the string. Also, the $ character appears outside of the quoted string. This demonstrates how regular expressions can be concatenated to form a longer expression.


GREP: Example 5

See Also

Command

grep -w[=] = *.c

Matches

i = 5;

j=5;

i += j;

Does Not Match

if (i == t) j++;

/* =================== */

Explanation

This example redefines the current set of legal characters for a word as the assignment operator (=) only, then does a word search. It matches C assignment statements, which use a single equal sign (=), but not equality tests, which use a double equal sign (==).


See Also

Command-Line Options

Command-Line Syntax

File Specifications

GREP: A Text-Search Utility

The Search String


BGIOBJ: Converting Graphics Drivers and Fonts

See Also

BGIOBJ.EXE converts graphics driver files and character sets (stroked font files) to object (.OBJ) files. Once files are converted, you can link them into your program, making them part of the executable file.

Linking drivers and fonts directly into your program is advantageous because the executable file contains all (or most) of the drivers and/or fonts it might need, and does not need to access the driver and font files on disk when running. However, linking the drivers and fonts into your executable file increases the EXE file size.

The BGIOBJ.EXE simplified syntax is:

BGIOBJ source_file

where source_file is the driver or font file to be converted to an object file. The new object file created has the same file name as the source file, with the extension .OBJ.


See Also

Adding the New .OBJ Files to GRAPHICS.LIB

Advanced Features

BGIOBJ Example

Registering the Drivers and Fonts

The /F option


BGIOBJ: Adding the New .OBJ Files to GRAPHICS.LIB

See Also

You should add the driver and font object modules to GRAPHICS.LIB, so the linker can locate them when it links in the graphics routines. If you do not add these new object modules to GRAPHICS.LIB, you will have to add them to the list of files in the project (.IDE) file, on the BCC command line, or on the TLINK command line. To add these object modules to GRAPHICS.LIB, invoke TLIB with the following command line:

tlib graphics + object_file_name [+ object_file_name]

where object_file_name is the name of the OBJ file created by BGIOBJ.EXE. The .OBJ extension is implied, so you do not need to include it. You can add several files with one command line to save time.


See Also

Advanced Features

BGIOBJ Example

Converting Graphics Drivers and Fonts

Registering the Drivers and Fonts

The /F option


BGIOBJ: Registering the Drivers and Fonts

See Also

After adding driver and font object modules to GRAPHICS.LIB, you have to register all the drivers and fonts that you want linked in; you do this by calling registerbgidriver and registerbgifont in your program (before calling initgraph). This informs the graphics system of the presence of those files, and ensures that they are linked when the linker creates the executable file.

The registering routines each take one parameter; a symbolic name defined in graphics.h. Each registering routine returns a nonnegative value if the driver or font is registered successfully.

The following table lists drivers and fonts in Borland C++ that you use with registerbgidriver and registerbgifont.

Driver File	registerbgidriver	Font file	registerbgifont

(*.BGI)	symbolic name	(*.CHR)	symbolic name

CGA	CGA_driver	TRIP	triplex_font

EGAVGA	EGAVGA_driver	LITT	small_font

HERC	Herc_driver	SANS	sansserif_font

ATT	ATT_driver	GOTH	gothic_font

PC3270	PC3270_driver

IBM8514	IBM8514_driver


See Also

Adding the New .OBJ Files to GRAPHICS.LIB

Converting Graphics Drivers and Fonts

BGIOBJ Example

The /F option

Advanced Features


BGIOBJ: Example

Suppose you want to convert the files for the CGA graphics driver, the gothic font, and the triplex font to object modules, then link them into your program. Here is what you do:

1. Convert the three binary files to object files using BGIOBJ.EXE (creates files CGA.OBJ, TRIP.OBJ, GOTH.OBJ).

2. You can add these object files to GRAPHICS.LIB with this TLIB command line:

tlib  graphics  +cga  +trip  +goth

3. If you do not add the object files to GRAPHICS.LIB, you must add the object file names CGA.OBJ, TRIP.OBJ, and GOTH.OBJ to your project list (if you are using the Borland C++ IDE), or to the BCC command line. For example, the BCC command line would look like this:

BCC  niftgraf graphics.lib cga.obj trip.obj goth.obj

4. Register these files in your graphics program:

/* Header file declares CGA_driver, triplex_font & gothic_font */

#include <graphics.h>

/* Register and check for errors */

if (registerbgidriver(CGA_driver) < 0) exit(1);

if (registerbgifont(triplex_font) < 0) exit(1);

if (registerbgifont(gothic_font)  < 0) exit(1);

/* ... */

initgraph(....);/* initgraph should be called after registering */

/* ... */


BGIOBJ: The /F option

See Also

This section explains what steps to take if you get the linker error Segment exceeds 64K (or a similar error) after linking in several driver and/or font files (especially with small- and compact-model programs).

By default, the files created by BGIOBJ.EXE all use the same segment (called _TEXT). This can cause problems if your program links in many drivers and/or fonts, or when you are using the small or compact memory model.

To solve this problem, you can convert one or more of the drivers or fonts with the BGIOBJ /F option. This option directs BGIOBJ to use a segment name of the form filename_TEXT, so that the default segment is not overburdened by all the linked-in drivers and fonts (and, in small and compact model programs, all the program code). For example, the following two BGIOBJ command lines direct BGIOBJ to use segment names of the form EGAVGA_TEXT and SANS_TEXT.

bgiobj  /F  egavga

bgiobj  /F  sans

When you select /F, BGIOBJ also appends F to the target object file name (EGAVGAF.OBJ, SANSF.OBJ, and so forth), and appends _far to the name that will be used with registerfarbgidriver and registerfarbgifont. (For example, EGAVGA_driver becomes EGAVGA_driver_far.)

For files created with /F, you must use these far registering routines instead of the regular registerbgidriver and registerbgifont. For example,

if (registerfarbgidriver(EGAVGA_driver_far) < 0)

exit(1);

if (registerfarbgifont(sansserif_font_far)  < 0)

exit(1);


See Also

Adding the New .OBJ Files to GRAPHICS.LIB

Advanced Features

BGIOBJ Example

Converting Graphics Drivers and Fonts

Registering the Drivers and Fonts


BGIOBJ: Advanced Features

See Also

This section explains some of the advanced features of BGIOBJ, and the routines registerfarbgidriver and registerfarbgifont.

This is the full syntax of the BGIOBJ.EXE command line:

BGIOBJ /F source destination public-name seg-name seg-class

This table describes components of the BGIOBJ command line.

Component	Description

/F or -F	Instructs BGIOBJ.EXE to use a segment name other than _TEXT (the default), and to change the public name and destination file name.

source	This is the driver or font file to be converted. If the file is not one of the driver/font files shipped with Borland C++, you should specify a  full file name (including extension).

destination 	Names the object file produced. The default destination file name is source.OBJ (sourceF.OBJ if you use the /F option).

public-name	This is the name used in the program in a call to registerbgidriver or registerbgifont (or their respective far versions) to link in the object module. The public name is the external name used by the linker, so it should be the name used in the program, prefixed with an underscore. If your program uses Pascal calling conventions, use uppercase letters and do not add an underscore.

seg-name	This is an optional segment name; the default is _TEXT (or filename_TEXT if /F is specified)

seg-class	An optional segment class; the default is CODE.

All parameters except source are optional. However, if you need to specify an optional parameter, all the parameters preceding it must also be specified.

If you choose to use your own public name(s), you have to add declaration(s) to your program, using one of the following forms:

void public_name(void);   /* if /F not used, */

 /* default segment name used */

extern int far public_name[];  /* if /F used, or */

 /* segment name not _TEXT */

In these declarations, public_name matches the public- name you used when converting with BGIOBJ. The graphics.h header file contains declarations of the default driver and font public names; if you use those default public names you do not have to declare them as just described.

After these declarations, you have to register all the drivers and fonts in your program. If you do not use the /F option and do not change the default segment name, you should register drivers and fonts through registerbgidriver and registerbgifont; otherwise, use registerfarbgidriver and registerfarbgifont.


See Also

Adding the New .OBJ Files to GRAPHICS.LIB

Advanced Features Example

BGIOBJ Example

Converting Graphics Drivers and Fonts

Registering the Drivers and Fonts

The /F option


BGIOBJ: Advanced Features Example

/* Example of loading a font file into memory */

#include <graphics.h>

#include <io.h>

#include <fcntl.h>

#include <stdio.h>

#include <conio.h>

#include <stdlib.h>

#include <process.h>

#include <alloc.h>

main()

{

 void  *gothic_fontp; /* points to font buffer in memory */

 int handle;          /* file handle used for I/O */

   unsigned fsize;    /* size of file (and buffer) */

   int errorcode;

   int graphdriver;

   int graphmode;

     /* open font file */

   handle = open("GOTH.CHR", O_RDONLY|O_BINARY);

   if (handle == -1)

   {

     printf("unable to open font file 'GOTH.CHR'\n");

     exit(1);

   }

     /* find out size of the file */

   fsize = filelength(handle);

     /* allocate buffer */

   gothic_fontp = malloc(fsize);

   if (gothic_fontp == NULL)

   {

     printf("unable to allocate memory for font file 'GOTH.CHR'\n");

     exit(1);

   }

     /* read font into memory */

   if (read(handle, gothic_fontp, fsize) != fsize)

   {

     printf("unable to read font file 'GOTH.CHR'\n");

     exit(1);

   }

     /* close font file */

   close(handle);

     /* register font */

   if (registerfarbgifont(gothic_fontp) != GOTHIC_FONT)

   {

     printf("unable to register font file 'GOTH.CHR'\n");

     exit(1);

   }

     /* detect and initialize graphix */

   graphdriver = DETECT;

   initgraph(&graphdriver, &graphmode, "..");

   errorcode = graphresult();

   if (errorcode != grOk)

   {

     printf("graphics error: %s\n",grapherrormsg(errorcode));

     exit(1);

   }

   settextjustify(CENTER_TEXT, CENTER_TEXT);

   settextstyle(GOTHIC_FONT, HORIZ_DIR, 4);

   outtextxy(getmaxx()/2,getmaxy()/2, "Borland Graphics Interface (BGI)");

    /* press a key to terminate */

   getch();

    /* shut down graphics system */

   closegraph();

   return(0);

}


OBJXREF: The Object Module Cross-Reference Utility

See Also

OBJXREF examines a list of object files and library files and produces reports on their contents. One type of report lists definitions of public names and references to them. The other type lists the segment sizes defined by object modules.

There are two categories of public names: global variables and function names. The TEST1.C and TEST2.C files in the section Sample OBJXREF Reports illustrate definitions of public names and external references to them.

Object modules are object (.OBJ) files produced by BC, BCC or TASM. A library (.LIB) file contains multiple object modules. An object module generated by BC is given the same name as the .C source file it was compiled from. This is also true for BCC, unless a different output file name is specifically indicated with the -o BCC command-line option.


See Also

Command Line

Control Options

Error Messages and Warnings

Examples

Report Options


OBJXREF: Command Line

See Also

The OBJXREF command line consists of the word OBJXREF followed by a series of command-line options and a list of object and library file names, separated by a space or tab character. The syntax is as follows:

OBJXREF @responsefile  options   filename  filename ...

The command-line options determine the kind of reports that OBJXREF generates and the amount of detail that OBJXREF provides. Each option begins with a forward slash (/) followed by a one- or two-character option name. Options are discussed in detail in the next section.

Object files and library files may be specified either on the command line or in a response file. On the command line, file names are separated by a space or a tab. All object modules specified as .OBJ files are included in reports. Like TLINK, however, OBJXREF includes only those modules from .LIB files which contain a public name referenced by an .OBJ file or by a previously included module from a .LIB file.

As a general rule, you should list all the .OBJ and .LIB files that are needed if the program is to link correctly, including the startup .OBJ file and one or more C libraries.

File names may include a drive and directory path. The DOS ? and * wildcard characters may be used to identify more than one file. File names may refer to .OBJ object files or to .LIB library files. (If you do not give a file extension, the .OBJ extension is assumed.)

Options and file names may occur in any order in the command line.

OBJXREF reports are written to the DOS standard output. The default is the screen. The reports can be sent to a printer (as with >LPT1:) or to a file (as with >lstfile) with the DOS redirection character (>).

Entering OBJXREF with no file names or options produces a summary of available options.

OBJXREF command-line options fall into two categories: control options and report options.


See Also

Control Options

Error Messages and Warnings

Examples

OBJXREF: The Object Module Cross-Reference Utility

Report Options


OBJXREF: Control Options

See Also

Control options modify the default behavior of OBJXREF (the default is that none of these options are enabled).

Option	Description

/I	Ignore case differences in public names. Use this option if you use TLINK without the /C option (which makes case differences significant).

/D	Look for .OBJ files in another directory. If you want OBJXREF to look for .OBJ files in a directory other than the current one, include the directory name on the command line, prefixed with /D:

OBJXREF /Ddir1 [; dir2 [; dir3]]

or

OBJXREF /Ddir1 [/Ddir2] [/Ddir3]

OBJXREF searches each of the directories in the specified order for all object and library files.

Important!	If you do not use a /D option, OBJXREF searches only the current directory. If you do use a /D option, however, the current directory is not searched unless it is included in the directory list.

/F	Include full library. All object modules in specified .LIB files are included even if they do not contain public names that are referenced by an object module being processed by OBJXREF. This provides information on the entire contents of a library file. (See example 4 in the section "OBJXREF examples.")

/O	Lets you to specify an output file where OBJXREF sends any generated reports. Its syntax is: OBJXREF file.obj /report option /Ooutputfilename.ext By default all output is sent to the screen.

/V	Verbose output. Lists names of files read and displays totals of public names, modules, segments, and classes.

/Z	Include zero-length segment definitions. Object modules may define a segment without allocating any space in it. Listing these zero length segment definitions normally makes the module size reports harder to use but it can be valuable if you are trying to remove all definitions of a segment.


See Also

Command Line

Error Messages and Warnings

Examples

OBJXREF: The Object Module Cross-Reference Utility

Report Options


OBJXREF: Report Options

See Also

Report options govern what sort of report is generated, and the amount of detail that OBJXREF provides.

Option	Report Generated

/RC	Report by class type: Module sizes ordered by class type of segment.

/RM	Report by module: Public names ordered by defining module.

/RP	Report by public names: Public names in order with defining module name.

/RR	Report by reference: Public name definitions and references ordered by name.

/RS	Report of module sizes: Module sizes ordered by segment name.

/RU	Report of unreferenced symbol names: Unreferenced public names ordered by defining module.

/RV	Verbose reporting: produces a report of every type.

/RX	Report by external reference: External references ordered by referencing module name.

Public names defined in .C files appear in reports with a leading underscore in the reports unless the -U- option was specified when the file was compiled (main appears as _main).

You can limit the modules, segments, classes, or public names that OBJXREF reports on by entering the appropriate name on the command line prefixed with the /N option. For example,

OBJXREF filelist /RM /NC0

tells OBJXREF to generate a report listing information only for the module named C0.


See Also

Command Line

Control Options

Error Messages and Warnings

OBJXREF: The Object Module Cross-Reference Utility

Sample Reports


OBJXREF: Sample Reports

See Also

Suppose you have two source files in your Borland C++ directory, and want to generate OBJXREF reports on the object files compiled from them. The source files are called TEST1.C and TEST2.C, and they look like this:

/* test1.c */

int i1;   /* defines i1 */

extern int i2; /* refers to i2 */

static int i3; /* not a public name */

extern void look(void);  /* refers to look */

void main(void)/* defines main */

{

 int i4;/* not a public name */

 look();/* refers to look */

}

/* test2.c */

#include <process.h>

extern int i1; /* refers to i1 */

int i2;   /* defines i2 */

void look(void)/* defines look */

{

 exit(i1);   /* refers to exit... */

}    /* and to i1 */

The object modules compiled from these source files are TEST1.OBJ and TEST2.OBJ. You can tell OBJXREF what kind of report to generate about these .OBJ files by entering the file names on the command line, followed by a /R and a second letter denoting report type.

Examples of Report Options

Report by Class Type (/RC)

Report by External References (/RX)

Report by Module (/RM)

Report by Public Names (/RP)

Report by Reference (/RR)

Report of Module Sizes (/RS)

Report of Unreferenced Symbol Names (/RU)

Verbose Reporting (/RV)

Note:	These examples show only useful parts of the output.


See Also

Report Options


Report by Public Names (/RP)

See Also

A report by public names lists each of the public names defined in the object modules being reported on, followed by the name of the module in which it is defined.

If you enter this on the command line:

OBJXREF  /RP  test1  test2

OBJXREF generates a report that looks like this:

SYMBOL DEFINED IN

_i1    TEST1

_i2    TEST2

_look  TEST2

_main  TEST1


See Also

Report Options

Sample Reports


Report by Module (/RM)

See Also

A report by module lists each object module being reported on, followed by a list of the public names defined in it.

If you enter this on the command line:

OBJXREF  /RM  test1  test2

OBJXREF generates a report that looks like this:

MODULE: TEST1 defines the following symbols:

      _i1

      _main

MODULE: TEST2 defines the following symbols:

      _i2

      _look


Report by Reference (/RR)

See Also

A report by reference lists each public name with  the defining module in parentheses on the same line. Modules that refer to this public name are listed on following lines indented from the left margin.

If you enter this on the command line:

OBJXREF  /RR  C0S  test1  test2  CS.LIB

OBJXREF generates a report that looks like this:

_exit (EXIT)

C0

TEST2

_i1 (TEST1)

TEST2

_look (TEST2)

TEST1

_main (TEST1)

C0


Report by External References (/RX)

See Also

A report by external references lists each module followed by a list of external references it contains.

If you enter this on the command line:

OBJXREF  /RX  C0S  test1  test2  CS.LIB

OBJXREF generates a report that looks like this:

MODULE: C0 references the following symbols:

   _main

MODULE: TEST1 references the following symbols:

   _i2

   _look

MODULE: TEST2 references the following symbols:

   _exit

   _i1


Report of Module Sizes (/RS)

See Also

A report by sizes lists segment names followed by a list of modules that define the segment. Sizes in bytes are given in decimal and hexadecimal notation. The word uninitialized appears where no initial values are assigned to any of the symbols defined in the segment. Segments defined at absolute addresses in a .ASM file are flagged Abs to the left of the segment size.

If you enter this on the command line:

OBJXREF  /RS  test1  test2

OBJXREF generates a report that looks like this:

TEST1_TEXT, PUBLIC

            10 (0000Ah)    TEST1

            10 (0000Ah)    total

TEST2_TEXT, PUBLIC

            15 (0000Fh)    TEST2

            15 (0000Fh)    total

_BSS, PUBLIC

             4 (00004h)    TEST1, uninitialized

             2 (00002h)    TEST2, uninitialized

             6 (00006h)    total


Report by Class Type (/RC)

See Also

A report by class type lists segment size definitions by segment class. The CODE class contains instructions, DATA class contains initialized data and BSS class contains uninitialized data. Segments which do not have a class type are listed under the notation No class type.

If you enter this on the command line:

OBJXREF  /RC  C0S  test1  test2  CS.LIB

OBJXREF generates a report that looks like this:

BSS

             4 (00004h)    _BSS, TEST1, uninitialized

             2 (00002h)    _BSS, TEST2, uninitialized

             6 (00006h)    total

CODE

             8 (00008h)    _TEXT, TEST1

            13 (0000Dh)    _TEXT, TEST2

            21 (00015h)    total


Report of Unreferenced Symbol Names (/RU)

See Also

A report of unreferenced symbol names lists modules that define public names not referenced in other modules. Such a symbol is either:

referenced only from within the defining module and does not need to be defined as a public symbol (in that case, if the module is in C, the keyword static should be added to the definition; if the module is in TASM, just remove the public definition).

never used (therefore, it can be deleted to save code or data space).

If you enter this on the command line:

OBJXREF  /RU  test1  test2

OBJXREF generates a report that looks like this:

MODULE: TEST2 defines the unreferenced symbol _i2.


Verbose Reporting (/RV)

See Also

If you enter /RV on the command line, OBJXREF generates one report of each type.


OBJXREF Examples

See Also

These examples assume that the application files are in the current directory of the default drive and that the Borland C++ startup files (C0x.OBJ) and the library files are in the \BC4\LIB directory.

Example 1

Command

C>OBJXREF \BC4\lib\c0l test1 test2 \BC4\lib\cl.lib

Explanation

In this example, the TEST1.OBJ and TEST2.OBJ files and the Borland C++ startup file \BC4\LIB\C0L.OBJ and the library file \BC4\LIB\CL.LIB are specified. Since no report type is specified, the resulting report is the default report by reference, listing public names and the modules that reference them.

Example 2

Command

C>OBJXREF /RV /Ltest1.arf

Explanation

The TLINK response file TEST1.ARF contains the same list of files as the command line in Example 1. The /RV option is specified, so a report of every type is generated. TEST1.ARF contains

\BC4\lib\c0l

test1 test2

test1.exe

test1.map

\BC4\lib\cl

Example 3

Command

C>OBJXREF /F /RV \BC4\lib\cs.lib

Explanation

This example reports on all the modules in the Borland C++ library file CS.LIB; OBJXREF can produce useful reports even when the files specified do not make a complete program. The /F causes all modules in CS.LIB file to be included in the report.


See Also

Command Line

Control Options

Examples

OBJXREF: The Object Module Cross-Reference Utility

Report Options


OBJXREF Error Messages and Warnings

See Also

OBJXREF generates two types of diagnostic messages: error messages and warnings.

Out of memory error

OBJXREF performs its cross referencing in RAM memory and might run out of memory even if TLINK is able to link the same list of files successfully. When this happens, OBJXREF stops. Remove memory resident programs to get more space, or add more RAM.

WARNING: Unable to open input file <filename>

The input file filename could not be located or opened. OBJXREF proceeds to the next file.

WARNING: Unknown option - <option>

The option name option is not recognized by OBJXREF. OBJXREF ignores the option.

WARNING: Unresolved symbol <symbol> in module <module>

The public name symbol referenced in module module is not defined in any of the .OBJ or .LIB files specified. OBJXREF flags the symbol in any reports it generates as being referenced but not defined.

WARNING: Invalid file specification <filename>

Some part of the file name filename is invalid. OBJXREF proceeds to the next file.

WARNING: No files matching <filename>

The file named filename listed on the command line or in a response file could not be located or opened. OBJXREF skips to the next file.

WARNING: Symbol <symbol> defined in <module1> duplicated in <module2>

Public name symbol is defined in modules module1 and module2. OBJXREF ignores the second definition.


See Also

Command Line

Control Options

Examples

OBJXREF: The Object Module Cross-Reference Utility

Report Options


TRIGRAPH: A Character-Conversion Utility

Trigraphs are three-character sequences that replace certain characters used in the C language that are not available on some keyboards. Translating trigraphs in the compiler would slow compilation down considerably, so Borland C++ provides a filter named TRIGRAPH.EXE to handle trigraph sequences when you need to. The syntax for invoking this program is as follows:

TRIGRAPH [-u] file(s) [file(s) ...]

The following table shows the trigraph sequences that TRIGRAPH.EXE recognizes:

Trigraph	Characters

??=	#

??(	[

??/	\

??)	]

??'	^

??<	{

??!	|

??>	}

??-	~


CPP and CPP32: The Preprocessors

See Also

CPP and CPP32 produce a list (in a file) of a C program in which include files and #define macros have been expanded. Unless otherwise noted, CPP refers to both CPP and CPP32. Neither is needed for normal compilation of C programs.

Often, when the compiler reports an error inside a macro or an include file, you can get more information about what the error is if you can see the include files or the results of the macro expansions. In many multi-pass compilers, a separate pass performs this work, and the results of the pass can be examined. Because Borland C++ uses an integrated single-pass compiler, use CPP to get the first-pass functionality found in other compilers.

CPP works similarly to BCC: it reads the same TURBOC.CFG file for default options and uses the same command-line options as BCC. CPP ignores any BCC options that do not pertain to CPP, and there is no special treatment for .OBJ, .LIB, or .ASM files. CPP32 uses the same command-line options that BCC32 uses.

For each file processed by CPP, the output is written to a file in the current directory (or the output directory named by the -n option) with the same name as the source name but with an extension of .I.

This output file is a text file containing each line of the source file and any include files. Any preprocessing  directive lines have been removed, along with any conditional text lines excluded from the compile. Unless you use a  command-line option to specify otherwise, text lines are prefixed with the file name and line number of the source or include file the line came from. Within a text line, any macros are replaced with their expansion text.

IMPORTANT!	The resulting output of CPP cannot be compiled because of the file name and line number prefix attached to each source line.


See Also

CPP and UUIDs

CPP as a Macro Preprocessor

Using MIDL with CPP.EXE and CPP32.EXE


CPP as a Macro Preprocessor

See Also

The -P option tells CPP to prefix each line with the source file name and line number. With the -P- option, CPP can be used as a macro preprocessor; the resulting .I file can then be compiled with BCC or BCC32. (Note that you can also use the BCC option -P to set default file extensions.)

The following simple program illustrates how CPP preprocesses a file, first with -P selected, then with -P-.

Source file: HELLOAJ.C

#define NAME "H.R. Floyd"

#define BEGIN {

#define END   }

main()

BEGIN

  printf("%s\n", NAME);

END

CPP command line:   CPP HELLOAJ.C

Output:

HELLOAJ.c 1:

HELLOAJ.c 2:

HELLOAJ.c 3:

HELLOAJ.c 4:

HELLOAJ.c 5: main()

HELLOAJ.c 6: {

HELLOAJ.c 7:    printf("%s\n","H.R. Floyd");

HELLOAJ.c 8: }

CPP command line:   CPP -P- HELLOAJ.C

Output:

main()

{

  printf("%s\n","H.R. Floyd");

}


See Also

CPP and CPP32: The Preprocessors

CPP and UUIDs

Using MIDL with CPP.EXE and CPP32.EXE


Using MIDL with CPP.EXE and CPP32.EXE

See Also

MIDL (Microsoft Interface Definition Language) is an RPC compiler. In order to use MIDL, with the Borland C++ preprocessors, you must use the following MIDL command:

MIDL -cpp_cmd {CPP|CPP32} -cpp_opt "-P- -oCON {CPP options}" {MIDL options} {.idl/.acf}

Option	Description

-cpp_cmd {CPP|CPP32}	Tells MIDL which preprocessor to use when processing an .IDL or .ACF file. MIDL calls the preprocessor to expand macros within source files.

-cpp_opt "{options}"	Specifies the command- line options for the preprocessor. The -P- removes line number and file name information from each line of the preprocessed output. The -oCON indicates that preprocessed output should go to standard output, instead of to file. The preprocessor banner and the current file that is being processed are not emitted. Including -oCON within a .CFG file processed by the preprocessor causes the banner to be emitted.

{CPP options}	pass options to CPP.

{MIDL options}	Any MIDL command-line options.

{.idl/.acf file}	The source file that MIDL processes.


See Also

CPP and CPP32: The Preprocessors

CPP and UUIDs

CPP as a Macro Preprocessor


CPP and UUIDs

See Also

In some cases, CPP does not accept valid UUIDs. For example, a valid UUID statement is:

uuid(5630EAA0-CA48-1067-B320-00DD010662DB)

When CPP or CPP32 encounter 5630EAA0, it is classified as a floating point number, and since it is an invalid floating point number, the preprocessor emits an error. To work around this problem, enclose the UUID within quotes and use the -ms_ext MIDL option. The UUID statement becomes:

uuid("5630EAA0-CA48-1067-B320-00DD010662DB")

and the MIDL command line becomes:

MIDL -ms_ext -cpp_cmd {CPP|CPP32} -cpp_opt "-P- -oCON {CPP options}" {MIDL options} {.idl/.acf file}


See Also

CPP and CPP32: The Preprocessors

CPP as a Macro Preprocessor

Using MIDL with CPP.EXE and CPP32.EXE


VBXGEN 1.0

See Also

VBXGEN is a utility program which generates a header file (.h) from a VBX control library (.vbx). The generated header file can be used by C, C++, or OWL programs and simplifies the use of VBX controls. The header file contains a section for each control model supported by a VBX library. Each model section contains a set of symbolic property and event names, default property data, and a custom C++ class for use with OWL programs.

Running VBXGEN

To generate a VBX header file using VBXGEN, perform the following steps:

1.	Start VBXGEN by clicking on its icon or running it from the Program or File Manager.

2.	Select the name of the VBX library.

3.	Select the name of the header file to be generated.

4.	VBXGEN will generate the header file and display a message box when finished.

For More Information

See the ObjectWindows Reference Guide for additional information about VBX classes or the ObjectWindows Programmer's Guide for instructions about writing applications that use VBX controls.

For an example using VBX controls in an ObjectWindows program, see the VBXCTLX example in the \EXAMPLES\OWL\OWLAPI\VBXCTL directory.

For an example using VBX controls in a C program, see the VBDIALOG example in the \EXAMPLES\WINDOWS\VBDIALOG directory.

See the online text file, BIVBX.WRI, for information about using the BIVBX library functions.


See Also

Symbolic Property and Event Names

Default Property Data

Custom OWL Classes


Symbolic Property and Event Names

VBXGEN

The use of symbolic property and event indices improves the performance and memory requirements of your program by eliminating the need to store and search for string names at run-time.

For example, the following code sets the bar color property of a Gauge control and requires a string search on the property name:

VBXSetPropByName( hCtlGauge, "BarColor", RGB(0,0,0) );

By using VBXGEN to generate a header file (switch.h), the above code can be replaced by a more efficient version which uses the index of the bar color property:

#include "switch.h"

VBXSetProp( hCtlGauge, Prop_BIGAUGE_BarColor, RGB(0,0,0) );

Similar replacements can be performed with event-related functions. Event indices are particularly useful when defining switch statements for event processing since strings cannot be used as case labels.


Default Property Data

VBXGEN

Some VBX controls do not operate correctly when created without a form file. This occurs when a program creates a control dynamically rather than as part of a dialog resource. If a control exhibits problems in this mode, try creating it with a form file created from the default property data generated in the header file.

For C/C++ Programs

HFORMFILE f = VBXCreateFormFile(sizeof(BIGAUGEData), BIGAUGEData);

HCTL g = VBXCreate(..., f);

VBXDeleteFormFile(f);

For OWL Programs

TVbxBIGAUGE* g = new TVbxBIGAUGE(..., sizeof(BIGAUGEData), BIGAUGEData);

Note:	VBXGEN_DATA or BIGAUGE_DATA symbol must be defined in order to use the default property data.


Custom OWL Classes

VBXGEN

VBXGEN generates a custom OWL class, derived from TVbxControl, for each control class in a VBX library. The OWL class defines simplified constructors, event handler stubs with parameter documentation, inline get and set functions for each property, and a sample response table which lists each event.

Constructors: defines constructors which automatically fill in the file and class name (i.e. GAUGE.VBX and BIGAUGE). For example:

new TVbxBIGAUGE( *window, IDC_GAUGE, "", 0, 0, 200, 30 );

Event stubs: documents event arguments and can be used for pasting into your own derived classes. For example:

void EvMouseMove(VBXEVENT FAR*)

{

  	// Button As Integer,Shift As Integer,X As Integer,Y As Integer

}

Get/Set functions: defines inline functions to get and set each control property. For example:

BOOL GetPropBarColor(COLORREF& v);

BOOL SetPropBarColor(COLORREF v);

Response Table: defines a sample response table for pasting into your own derived classes. For example:

DEFINE_RESPONSE_TABLE1(TVbxBIGAUGE, TVbxControl)

  	EV_VBXEVENTINDEX( IDC_BIGAUGE, Event_BIGAUGE_MouseMove, EvMouseMove ),

   ...

END_RESPONSE_TABLE;


Preprocessor Directives

Preprocessor directives are usually placed at the beginning of your source code, but they can legally appear at any point in a program. The Borland C++ preprocessor detects preprocessor directives (also known as control lines) and parses the tokens embedded in them. Borland C++ supports these preprocessor directives:

# (null directive)	#ifdef

#define	#ifndef

#elif	#include

#else	#line

#endif	#pragma

#error	#undef

#if

Any line with a leading # is taken as a preprocessing directive, unless the # is within a string literal, in a character constant, or embedded in a comment. The initial # can be preceded or followed by whitespace (excluding new lines).


# (null directive)

Directives

Syntax

#

Description

The null directive consists of a line containing the single character #. This directive is always ignored.


#define

See Also	Example	Directives

Syntax

#define macro_identifier <token_sequence>

Description

The#define directive defines a macro. Macros provide a mechanism for token replacement with or without a set of formal, function-like parameters.

Each occurrence of macro_identifier in your source code following this control line will be replaced in the original position with the possibly empty token_sequence (there are some exceptions, which are noted later). Such replacements are known as macro expansions. The token sequence is sometimes called the body of the macro.

An empty token sequence results in the removal of each affected macro identifier from the source code.

After each individual macro expansion, a further scan is made of the newly expanded text. This allows for the possibility of nested macros: The expanded text can contain macro identifiers that are subject to replacement. However, if the macro expands into what looks like a preprocessing directive, such a directive will not be recognized by the preprocessor. There are these restrictions to macro expansion:

Any occurrences of the macro identifier found within literal strings, character constants, or comments in the source code are not expanded.

A macro won't be expanded during its own expansion (so #define A A won't expand indefinitely).


Example

#define HI "Have a nice day!"

#define empty

#define NIL ""

#define GETSTD #include <stdio.h>


See Also

Keywords and Protected Words as Macros

Macros with Parameters

#undef

Using the -D and -U Command-line Options


#error

Example	Directives

Syntax

#error errmsg

Description

The #error directive generates the message:

Error: filename line# : Error directive: errmsg

This directive is usually embedded in a preprocessor conditional statement that catches some undesired compile-time condition. In the normal case, that condition will be false. If the condition is true, you want the compiler to print an error message and stop the compile. You do this by putting an #error directive within a conditional statement that is true for the undesired case.


Example

#if (MYVAL != 0 && MYVAL != 1)

#error MYVAL must be defined to either 0 or 1

#endif


#if, #elif, #else, and #endif

SeeAlso	Directives

Syntax

#if constant-expression-1

<section-1>

<#elif constant-expression-2 newline section-2>

  .

  .

  .

<#elif constant-expression-n newline section-n>

<#else <newline> final-section>

#endif

Description

Borland C++ supports conditional compilation by replacing the appropriate source-code lines with a blank line. The lines thus ignored are those beginning with # (except the #if, #ifdef, #ifndef, #else, #elif, and #endif directives), as well as any lines that are not to be compiled as a result of the directives. All conditional compilation directives must be completed in the source or include file in which they are begun.

The conditional directives #if, #elif, #else, and #endif work like the normal C conditional operators. If the constant-expression-1 (subject to macro expansion) evaluates to nonzero (true), the lines of code (possibly empty) represented by section-1, whether preprocessor command lines or normal source lines, are preprocessed and, as appropriate, passed to the Borland C++ compiler. Otherwise, if constant-expression-1 evaluates to zero (false), section-1 is ignored (no macro expansion and no compilation).

In the true case, after section-1 has been preprocessed, control passes to the matching #endif (which ends this conditional sequence) and continues with next-section. In the false case, control passes to the next #elif line (if any) where constant-expression-2 is evaluated. If true, section-2 is processed, after which control moves on to the matching #endif. Otherwise, if constant-expression-2 is false, control passes to the next #elif, and so on, until either #else or #endif is reached. The optional #else is used as an alternative condition for which all previous tests have proved false. The #endif ends the conditional sequence.

The processed section can contain further conditional clauses, nested to any depth; each #if must be carefully balanced with a closing #endif.

The net result of the preceding scenario is that only one section (possibly empty) is passed on for further processing. The bypassed sections are relevant only for keeping track of any nested conditionals, so that each #if can be matched with its correct #endif.

The constant expressions to be tested must evaluate to a constant integral value.


See Also

defined keyword

#ifdef

#ifndef


#ifdef and #ifndef

See Also	Directives

Syntax

#ifdef identifier

#ifndef identifier

Description

The #ifdef and #ifndef conditional directives let you test whether an identifier is currently defined or not; that is, whether a previous #define command has been processed for that identifier and is still in force. The line

#ifdef identifier

has exactly the same effect as

#if 1

if identifier is currently defined, and the same effect as

#if 0

if identifier is currently undefined.

#ifndef tests true for the "not-defined" condition, so the line

#ifndef identifier

has exactly the same effect as

#if 0

if identifier is currently defined, and the same effect as

#if 1

if identifier is currently undefined.

The syntax thereafter follows that of the #if, #elif, #else, and #endif.

An identifier defined as NULL is considered to be defined.


See Also

defined keyword


#include

Example	Directives

Syntax

#include <header_name>

#include "header_name"

#include macro_identifier

Description

The #include directive pulls in other named files, known as include files, header files, or headers, into the source code. The syntax has three versions:

The first and second versions imply that no macro expansion will be attempted; in other words, header_name is never scanned for macro identifiers. header_name must be a valid DOS file name with an extension (traditionally .h for header) and optional path name and path delimiters.

The third version assumes that neither < nor " appears as the first non-whitespace character following #include; further, it assumes a macro definition exists that will expand the macro identifier into a valid delimited header name with either of the <header_name> or "header_name" formats.

The preprocessor removes the #include line and conceptually replaces it with the entire text of the header file at that point in the source code. The source code itself is not changed, but the compiler "sees" the enlarged text. The placement of the #include can therefore influence the scope and duration of any identifiers in the included file.

If you place an explicit path in the header_name, only that directory will be searched.

The difference between the <header_name> and "header_name" formats lies in the searching algorithm employed in trying to locate the include file.


Example

This #include statement causes it to look for MYINCLUD.H in the standard include directory.

#include <stdio.h>

This #include statement causes it to look for MYINCLUD.H in the current directory, then in the default directories.

#include "myinclud.h"

After expansion, this #include statement causes the preprocessor to look in C:\BC4\INCLUDE\MYSTUFF.H and nowhere else.

#define myinclud "C:\BC4\INCLUDE\MYSTUFF.H"

/* Note: Single backslashes OK here; within a C statement you would

   need "C:\BC4\INCLUDE\\MYSTUFF.H" */

#include  myinclud

/* macro expansion */


#line

Directives

Syntax

#line integer_constant  <"filename">

Description

You can use the #line directive to supply line numbers to a program for cross-reference and error reporting. If your program consists of sections derived from some other program file, it is often useful to mark such sections with the line numbers of the original source rather than the normal sequential line numbers derived from the composite program.

The #line directive indicates that the following source line originally came from line number integer_constant of filename. Once the filename has been registered, subsequent #line commands relating to that file can omit the explicit filename argument.

Macros are expanded in #line arguments as they are in the #include directive.

The #line directive is primarily used by utilities that produce C code as output, and not in human-written code.


#pragma

Directives

Syntax

#pragma directive-name

Description

With #pragma, Borland C++ can define the directives it wants without interfering with other compilers that support #pragma. If the compiler doesn't recognize directive-name, it ignores the #pragma directive without any error or warning message.

Borland C++ supports the following #pragma directives:

#pragma argsused

#pragma codeseg

#pragma comment

#pragma exit

#pragma hdrfile

#pragma hdrstop

#pragma inline

#pragma intrinsic

#pragma message

#pragma option

#pragma saveregs

#pragma startup

#pragma warn


#pragma argsused

See Also	#pragma

Syntax

#pragma argused

Description

The argsused pragma is allowed only between function definitions, and it affects only the next function. It disables the warning message:

"Parameter name is never used in function func-name"


See Also

Preprocessor Directives


#pragma codeseg

See Also	#pragma

Syntax

#pragma codeseg <seg_name> <"seg_class"> <group>

Description

The codeseg directive lets you name the segment, class, or group where functions are allocated. If the pragma is used without any of its options arguments, the default code segment is used for function allocation.


#pragma comment

See Also	#pragma

Syntax

#pragma comment (comment type, "string")

Description

The comment directive lets you write a comment record into an output file. The comment type can be one of the following values:

Value	Explanation

exestr	The linker writes string into an .OBJ file. Your specified string is placed in the executable file. Such a string is never loaded into memory but can be found in the executable file by use of a suitable file search utility.

lib	Writes a comment record into an .OBJ file. The comment record is used by the linker as a library-search directory. A library module that is not specified in the linker's response-file can be specified by the comment LIB directive. The linker includes the library module name specified in string as the last library. Multiple modules can be named and linked in the order in which they are named.

user	The compiler writes string into the .OBJ file. The specified string is ignored by the linker.


#pragma exit and #pragma startup

See Also	#pragma

Syntax

#pragma startup function-name <priority>

#pragma exit function-name <priority>

Description

These two pragmas allow the program to specify function(s) that should be called either upon program startup (before the main function is called), or program exit (just before the program terminates through _exit).

The specified function-name must be a previously declared function taking no arguments and returning void; in other words, it should be declared as:

void func(void);

The optional priority parameter should be an integer in the range 64 to 255. The highest priority is 0. Functions with higher priorities are called first at startup and last at exit. If you don't specify a priority, it defaults to 100.

Note:	Priorities from 0 to 63 are used by the C libraries, and should not be used by the user.


#pragma hdrfile

See Also	#pragma

Syntax

#pragma hdrfile "filename.CSM"

Description

This directive sets the name of the file in which to store precompiled headers.

If you aren't using precompiled headers, this directive has no effect. You can use the command-line compiler option -H=filename or Use Precompiled Headers to change the name of the file used to store precompiled headers.


#pragma hdrstop

See Also	#pragma

Syntax

#pragma hdrstop

Description

This directive terminates the list of header files eligible for precompilation. You can use it to reduce the amount of disk space used by precompiled headers.


#pragma inline

See Also	#pragma

Syntax

#pragma inline

Description

This directive is equivalent to the -B command-line compiler option or the IDE inline option.

This is best placed at the top of the file, because the compiler restarts itself with the -B option when it encounters #pragma inline.


#pragma intrinsic

See Also	Example	#pragma

Syntax

#pragma intrinsic [-]function-name

Description

Use #pragma intrinsic to override command-line switches or IDE options to control the inlining of functions.

When inlining an intrinsic function, always include a prototype for that function before using it.


Example

This example causes the compiler to generate code for strcpy in your function:

#pragma intrinsic strcpy

 while this version prevents the compiler from inlining strcpy:

#pragma intrinsic -strcpy


#pragma message

See Also	Example	#pragma

Syntax

#pragma message ("text" ["text"["text" ...]])

#pragma message text

Description

Use #pragma message to specify a user-defined message within your program code.

The first form requires that the text consist of one or more string constants, and the message must be enclosed in parentheses. (This form is compatible with MSC.) The second form uses the text following the #pragma for the text of the warning message. With both forms of the #pragma, any macro references are expanded before the message is displayed.

Display of user-defined messages is on by default and can be turned on or off with the User-Defined Warnings (Options|Project|Messages|General) in the IDE. This option corresponds to the 16/32 bit compiler's -wmsg switch.


See Also

#pragma warn

Preprocessor Directives


Example

The following example displays either "You are compiling using version xxx of BC++" (where xxx is the version number) or "Sorry, you are not using the Borland C++ compiler".

#ifdef __BORLANDC__

#pragma message You are compiling using version __BORLANDC__ of BC++.

#else

#pragma message ("Sorry, you are not using the Borland C++ compiler")

#endif


#pragma option

See Also	#pragma

Syntax

#pragma option [options...]

Description

Use #pragma option to include command-line options within your program code.

options can be any command-line option (except those listed in the following paragraph). Any number of options can appear in one directive. Any of the toggle options (such as -a or -K) can be turned on and off as on the command line. For these toggle options, you can also put a period following the option to return the option to its command-line, configuration file, or option-menu setting. This allows you to temporarily change an option, then return it to its default, without having to remember (or even needing to know) what the exact default setting was.

Options that cannot appear in a pragma option include:

-B	-c	-dname

-Dname=string	-efilename	-E

-Fx	-h	-lfilename

-lexset	-M	-o

-P	-Q	-S

-T	-Uname	-V

-X	-Y

You can use #pragmas, #includes, #define, and some #ifs in the following cases:

Before the use of any macro name that begins with two underscores (and is therefore a possible built-in macro) in an #if, #ifdef, #ifndef or #elif directive.

Before the occurrence of the first real token (the first C or C++ declaration).

Certain command-line options can appear only in a #pragma option command before these events. These options are:

-Efilename	-f	-i#

-m*	-npath	-ofilename

-u	-W	-z

*

Other options can be changed anywhere. The following options will only affect the compiler if they get changed between functions or object declarations:

-1	-h	-r

-2	-k	-rd

-a	-N	-v

-ff	-O	-y

-G	-p	-Z

The following options can be changed at any time and take effect immediately:

-A	-gn	-zE

-b	-jn	-zF

-C	-K	-zH

-d	-wxxx

The options can appear followed by a dot (.) to reset the option to its command-line state.


#pragma saveregs

See Also	#pragma

Syntax

#pragma saveregs

Description

The saveregs pragma guarantees that a huge function will not change the value of any of the registers when it is entered. This directive is sometimes needed for interfacing with assembly language code. The directive should be placed immediately before the function definition. It applies to that function alone.


#pragma warn

See Also	Example	#pragma

Syntax

#pragma warn [+|-|.]www

Description

The warn pragma lets you override specific -wxxx command-line options or check Display Warningsl in the Messages options.


Example

If your source code contains the directives:

#pragma warn +xxx

#pragma warn -yyy

#pragma warn .zzz

the xxx warning will be turned on, the yyy warning will be turned off, and the zzz warning will be restored to the value it had when compilation of the file began. See the command-line options summary for a complete list of the three-letter abbreviations and the warnings to which they apply.


#undef

See Also	Example	Directives

Syntax

#undef macro_identifier

Description

You can undefine a macro using the #undef directive. #undef detaches any previous token sequence from the macro identifier; the macro definition has been forgotten, and the macro identifier is undefined. No macro expansion occurs within #undef lines.

The state of being defined or undefined turns out to be an important property of an identifier, regardless of the actual definition. The #ifdef and #ifndef conditional directives, used to test whether any identifier is currently defined or not, offer a flexible mechanism for controlling many aspects of a compilation.

After a macro identifier has been undefined, it can be redefined with #define, using the same or a different token sequence.

Attempting to redefine an already defined macro identifier will result in a warning unless the new definition is exactly the same token-by-token definition as the existing one. The preferred strategy where definitions might exist in other header files is as follows:

#ifndef BLOCK_SIZE

  #define BLOCK_SIZE 512

#endif

The middle line is bypassed if BLOCK_SIZE is currently defined; if BLOCK_SIZE is not currently defined, the middle line is invoked to define it.

No semicolon (;) is needed to terminate a preprocessor directive. Any character found in the token sequence, including semicolons, will appear in the macro expansion. The token sequence terminates at the first non-backslashed new line encountered. Any sequence of whitespace, including comments in the token sequence, is replaced with a single-space character.


Example

#define BLOCK_SIZE 512

  .

  .

  .

#undef BLOCK_SIZE

/* use of BLOCK_SIZE now would be illegal "unknown" identifier */

  .

  .

  .

#define BLOCK_SIZE 128   /* redefinition */


See Also

#define

Preprocessor directives

Using the -D and -U Command-line Options


Using the-D and -U Command-line Options

See Also

Identifiers can be defined and undefined using the command-line compiler options -D and -U.

The command line

BCC32 -Ddebug=1; paradox=0; X -Umysym myprog.c

is equivalent to placing

#define debug 1

#define paradox 0

#define X

#undef mysym

in the program.


See Also

#define

#undef


Keywords and Protected Words in Macros
Keywords and Protected Words as Macros

It is legal but ill-advised to use Borland C++ keywords as macro identifiers:

#define int long    /* legal but probably catastrophic */

#define INT long    /* legal and possibly useful */

The following predefined global identifiers cannot appear immediately following a #define or #undef directive:

_ _DATE_ _	_ _FILE_ _	_ _LINE_ _

_ _STDC_ _	_ _TIME_ _


Macros with Parameters

See Also

The following syntax is used to define a macro with parameters:

#define macro_identifier(<arg_list>) token_sequence

Any comma within parentheses in an argument list is treated as part of the argument, not as an argument delimiter.

Note there can be no whitespace between the macro identifier and the (. The optional arg_list is a sequence of identifiers separated by commas, not unlike the argument list of a C function. Each comma-delimited identifier plays the role of a formal argument or placeholder.

Such macros are called by writing

macro_identifier<whitespace>(<actual_arg_list>)

in the subsequent source code. The syntax is identical to that of a function call; indeed, many standard library C "functions" are implemented as macros. However, there are some important semantic differences, side effects, and potential pitfalls.

The optional actual_arg_list must contain the same number of comma-delimited token sequences, known as actual arguments, as found in the formal arg_list of the #define line: There must be an actual argument for each formal argument. An error will be reported if the number of arguments in the two lists is different.

A macro call results in two sets of replacements. First, the macro identifier and the parenthesis-enclosed arguments are replaced by the token sequence. Next, any formal arguments occurring in the token sequence are replaced by the corresponding real arguments appearing in the actual_arg_list.

As with simple macro definitions, rescanning occurs to detect any embedded macro identifiers eligible for expansion.


See Also

Converting to Strings with #

Nesting Parentheses and Commas

Side Effects and Other Dangers

Using the Backslash (\) for Line Continuation

Token Pasting with ##


Nesting Parentheses and Commas

The actual_arg_list can contain nested parentheses provided that they are balanced; also, commas appearing within quotes or parentheses are not treated like argument delimiters.


Token Pasting with ##

You can paste (or merge) two tokens together by separating them with ## (plus optional whitespace on either side). The preprocessor removes the whitespace and the ##, combining the separate tokens into one new token. You can use this to construct identifiers.


Converting to Strings with #

The # symbol can be placed in front of a formal macro argument in order to convert the actual argument to a string after replacement.


Using the Backslash (\) for Line Continuation

A long token sequence can straddle a line by using a backslash (\). The backslash and the following newline are both stripped to provide the actual token sequence used in expansions.


Side Effects and Other Dangers

The similarities between function and macro calls often obscure their differences. A macro call has no built-in type checking, so a mismatch between formal and actual argument data types can produce bizarre, hard-to-debug results with no immediate warning. Macro calls can also give rise to unwanted side effects, especially when an actual argument is evaluated more than once.pression.


Header File Search with <header_name>

The <header_name> version specifies a standard include file; the search is made successively in each of the include directories in the order they are defined. If the file is not located in any of the default directories, an error message is issued.


Header File Search with "header_name"

The "header_name" version specifies a user-supplied include file; the file is sought first in the current directory (usually the directory holding the source file being compiled). If the file is not found there, the search continues in the include directories as in the <header_name> situation.


Global Variables

Borland C++ provides you with predefined global variables for many common needs, such as dates, times, command-line arguments, and so on. For a list of obsolete global variables, see Obsolete Global Variables.

_8087	_osminor

_argc	_osversion

_argv	_psp

_ctype	_sys_errlist

_daylight	_sys_nerr

_directvideo	_threadid

_doserrno	_ _throwExceptionName

_environ	_ _throwFileName

_errno	_ _throwLineNumber

_floatconvert	_timezone

_fmode	_tzname

_new_handler	_version

_osmajor	_wscroll


_8087

Portability	Global Variables

Syntax

extern int _8087;

Header File

dos.h

Description

The _8087 variable is set to a nonzero value if the startup code autodetection logic detects a floating-point coprocessor.

_8087	Math

Value	Coprocessor

1    	8087

2    	80287

3    	80387

0    	(none detected)

The autodetection logic can be overridden by setting the 87 environment variable to YES or NO. (The commands are SET 87=YES and SET 87=NO; it is essential that there be no spaces before or after the equal sign.) In this case, the _8087 variable will reflect the override.


_argc

Portability	Example	Global Variables

Syntax

extern int _argc;

Header File

dos.h

Description

_argc has the value of argc passed to main when the program starts.


_argc and _argv example
/* _argc and _argv example */

#include <iostream.h>

#include <dos.h>     // TO GET THE GLOBAL _arg VALUES

void func() {

   cout << "argc= " << _argc << endl;

   for (int i = 0; i < _argc; ++i)

      cout << _argv[i] << endl;

   }

void main(int argc, char ** argv) {

   func(); // THIS FUNCTION KNOWS ALL THE main() ARGUMENTS

   }


_argv

Portability	Example	Global Variables

Syntax

extern char **_argv;

Header File

dos.h

Description

_argv points to an array containing the original command-line arguments (the elements of argv[]) passed to main when the program starts.


_ctype

Portability	Global Variables

Syntax

extern char _ctype[];

Header File

ctype.h

Description

_ctype is an array of character attribute information indexed by ASCII value + 1. Each entry is a set of bits describing the character. This array is used by isdigit, isprint, and so on.


_daylight

See Also	Portability	Global Variables

Syntax

extern int _daylight;

Header File

time.h

Description

_daylight is used by the time and date functions. It is set by the tzset, ftime, and localtime functions to 1 for daylight saving time, 0 for standard time.


See Also

_timezone

_tzname


_directvideo

Portability	Global Variables

Syntax

extern int _directvideo;

Header File

conio.h

Description

_directvideo controls whether your program's console output goes directly to the video RAM (_directvideo = 1) or goes via ROM BIOS calls (_directvideo = 0).

The default value is _directvideo = 1 (console output goes directly to video RAM). To use _directvideo = 1, the video hardware on your system must be identical to IBM display adapters. Setting _directvideo = 0 allows your console output to work on any system that is IBM BIOS-compatible.

_directvideo should be used only in character-based applications. It is not allowed in 16-bit Windows, Win32s, or Win32 GUI applications.


_environ

See Also	Portability	Global Variables

Syntax

extern char ** _environ;

Header File

dos.h

Description

_environ is an array of pointers to strings; it is used to access and alter the operating system environment variables. Each string is of the form:

envvar = varvalue

where envvar is the name of an environment variable (such as PATH), and varvalue is the string value to which envvar is set (such as C:\BIN;C:\DOS). The string varvalue can be empty.

When a program begins execution, the operating system environment settings are passed directly to the program. Note that env, the third argument to main, is equal to the initial setting of _environ.

The _environ array can be accessed by getenv; however, the putenv function is the only routine that should be used to add, change or delete the _environ array entries. This is because modification can resize and relocate the process environment array, but _environ is automatically adjusted so that it always points to the array.


See Also

getenv

putenv


errno

Portability	Example	Global Variables

Syntax

extern int errno;

Header File

errno.h

Description

errno is used by perror to print error messages when certain library routines fail to accomplish their appointed tasks.

When an error in a math or system call occurs, errno is set to indicate the type of error. Sometimes errno and _doserrno are equivalent. At other times, errno does not contain the actual operating system error code, which is contained in _doserrno. Still other errors might occur that set only errno, not _doserrno.


errno, _doserrno, _sys_errlist, and _sys_nerr example
/* errno, _doserrno, _sys_errlist, and _sys_nerr example */

/* DISPLAY THE SYSTEM ERRORS. */

#include <errno.h>

#include <stdio.h>

extern char *_sys_errlist[];

main()

{

   int i = 0;

   while(_sys_errlist[i++]) printf("%s\n", _sys_errlist[i]);

   return 0;

}


_doserrno

Portability	Example	Global Variables

Syntax

extern int _doserrno;

Header File

errno.h

Description

_doserrno is a variable that maps many operating system error codes to errno; however, perror does not use _doserrno directly.

When an operating system call results in an error, _doserrno is set to the actual operating system error code. errno is a parallel error variable inherited from UNIX.

The following list gives mnemonics for the actual DOS error codes to which _doserrno can be set. (This value of _doserrno may or may not be mapped (through errno) to an equivalent error message string in _sys_errlist.

Mnemonic	DOS error code

E2BIG	Bad environ

EACCES	Access denied

EACCES	Bad access

EACCES	Is current dir

EBADF	Bad handle

EFAULT	Reserved

EINVAL	Bad data

EINVAL	Bad function

EMFILE	Too many open

ENOENT	No such file or directory

ENOEXEC	Bad format

ENOMEM	Mcb destroyed

ENOMEM	Out of memory

ENOMEM	Bad block

EXDEV	Bad drive

EXDEV	Not same device

Refer to your DOS reference manual for more information about DOS error return codes.


_sys_errlist

Portability	Example	Global Variables

Syntax

extern char * _sys_errlist[ ];

Header File

errno.h

Description

_sys_errlist is used by perror to print error messages when certain library routines fail to accomplish their appointed tasks.

To provide more control over message formatting, the array of message strings is provided in _sys_errlist. You can use errno as an index into the array to find the string corresponding to the error number. The string does not include any newline character.

The following table gives mnemonics and their meanings for the values stored in _sys_errlist. The list is alphabetically ordered for ease your reading convenience. For the numerical ordering, see the header file errno.h.

Mnemonic	16-bit Description	32-bit Description

E2BIG	Arg list too long	Arg list too long

EACCES	Permission denied	Permission denied

EBADF	Bad file number	Bad file number

ECHILD	No child process

ECONTR	Memory blocks destroyed	Memory blocks destroyed

ECURDIR	Attempt to remove CurDir	Attempt to remove CurDir

EDEADLOCK	Locking violation

EDOM	Domain error	Math argument

EEXIST	File already exists	File already exists

EFAULT	Unknown error	Unknown error

EINTR	Interrupted function call

EINVACC	Invalid access code	Invalid access code

EINVAL	Invalid argument	Invalid argument

EINVDAT	Invalid data	Invalid data

EINVDRV	Invalid drive specified	Invalid drive specified

EINVENV	Invalid environment	Invalid environment

EINVFMT	Invalid format	Invalid format

EINVFNC	Invalid function number	Invalid function number

EINVMEM	Invalid memory block address	Invalid memory block address

EIO	input/output error

EMFILE	Too many open files	Too many open files

ENAMETOOLONG	File name too long

ENFILE	Too many open files

ENMFILE	No more files	No more files

ENODEV	No such device	No such device

ENOENT	No such file or directory	No such file or directory

ENOEXEC	Exec format error	Exec format error

ENOFILE	No such file or directory	File not found

ENOMEM	Not enough memory	Not enough core

ENOPATH	Path not found	Path not found

ENOSPC	No space left on device

ENOTSAM	Not same device	Not same device

ENXIO	No such device or address

EPERM	Operation not permitted

EPIPE	Broken pipe

ERANGE	Result out of range	Result too large

EROFS	Read-only file system

ESPIPE	Illegal seek

EXDEV	Cross-device link	Cross-device link

EZERO	Error 0	Error 0

Refer to your DOS reference manual for more information about DOS error return codes.


_sys_nerr

Portability	Example	Global Variables

Syntax

extern int _sys_nerr;

Header File

errno.h

Description

_sys_nerr is used by perror to print error messages when certain library routines fail to accomplish their appointed tasks.

This variable is defined as the number of error message strings in _sys_errlist.


_floatconvert

Portability	Example	Global Variables

Syntax

extern int _floatconvert;

Header File

stdio.h

Description

Floating-point output requires linking of conversion routines used by printf, scanf, and any variants of these functions. In order to reduce executable size, the floating-point formats are not automatically linked. However, this linkage is done automatically whenever your program uses a mathematical routine or the address is taken of some floating-point number. If neither of these actions occur, the missing floating-point formats can result in a run-time error.


_floatconvert example
/* _floatconvert example */

/* PREPARE TO OUTPUT FLOATING-POINT NUMBERS. */

#include <stdio.h>

#pragma extref _floatconvert

void main() {

  printf("d = %lf\n", 1);

}


_fmode

Portability	Global Variables

Syntax

extern int _fmode;

Header File

fcntl.h

Description

_fmode determines in which mode (text or binary) files will be opened and translated. The value of _fmode is O_TEXT by default, which specifies that files will be read in text mode. If _fmode is set to O_BINARY, the files are opened and read in binary mode. (O_TEXT and O_BINARY are defined in fcntl.h.)

In text mode, carriage-return/linefeed (CR/LF) combinations are translated to a single linefeed character (LF) on input. On output, the reverse is true: LF characters are translated to CR/LF combinations.

In binary mode, no such translation occurs.

You can override the default mode as set by _fmode by specifying a t (for text mode) or b (for binary mode) in the argument type in the library functions fopen, fdopen, and freopen. Also, in the function open, the argument access can include either O_BINARY or O_TEXT, which will explicitly define the file being opened (given by the open pathname argument) to be in either binary or text mode.


_new_handler

Portability	Global Variables

Syntax

typedef void (*pvf)();

pvf _new_handler;

Header File

new.h

Description

_new_handler contains a pointer to a function that takes no arguments and returns void. If operator new() is unable to allocate the space required, it will call the function pointed to by _new_handler; if that function returns it will try the allocation again. By default, the function pointed to by _new_handler simply terminates the application. The application can replace this handler, however, with a function that can try to free up some space. This is done by assigning directly to _new_handler or by calling the function set_new_handler,, which returns a pointer to the former handler.

As an alternative, you can set using the function set_new_handler, like this:

pvf set_new_handler(pvf p);

_new_handler is provided primarily for compatibility with C++ version 1.2. In most cases this functionality can be better provided by overloading operator new().


_osmajor

See Also	Portability	Global Variables

Syntax

extern unsigned char _osmajor;

Header File

dos.h

Description

The major version number of the operating system is available individually through _osmajor. For example, if you are running DOS version 3.2, _osmajor will be 3.

This variable can be useful when you want to write modules that will run on DOS versions 2.x and 3.x. Some library routines behave differently depending on the DOS version number, while others only work under DOS 3.x and higher. For example, refer to creatnew,  ioctl, and _rtl_open.


See Also

_osminor

_osversion

_version


_osminor

See Also	Portability	Global Variables

Syntax

extern unsigned char _osminor;

Header File

dos.h

Description

The minor version number of the operating system is available individually through _osminor. For example, if you are running DOS version 3.2, _osminor will be 20.

This variables can be useful when you want to write modules that will run on DOS versions 2.x and 3.x. Some library routines behave differently depending on the DOS version number, while others only work under DOS 3.x and higher. For example, refer to creatnew, ioctl, and _rtl_open.


See Also

_osmajor

_osversion

_version


_osversion

See Also	Portability	Global Variables

Syntax

extern unsigned _osversion;

Header File

dos.h

Description

_osversion contains the operating system version number, with the major version number in the low byte and the minor version number in the high byte. (For DOS version x.y, the x is the major version number, and y is the minor version number.)

_osversion is functionally identical to _version.


See Also

_osmajor

_osminor


_psp

Portability	Global Variables

Syntax

extern unsigned int _psp;

Header Files

dos.h

process.h

stdlib.h

Description

_psp specifies the address of the program segment prefix (PSP) of a program. The PSP is a DOS process descriptor; it contains initial DOS information about the program.

Note:	_psp cannot be used in DLLs.


_ _throwExceptionName

See Also	Portability	Global Variables

Syntax

extern char * _ _throwExceptionName;

Header File

except.h

Description

Use this global variable to get the name of a thrown exception. The output for this variable is a printable character string.


See Also

_ _throwFileName

_ _throwLineNumber


_ _throwFileName

See Also	Portability	Global Variables

Syntax

extern char * _ _throwFileName;

Header File

except.h

Description

Use this global variable to get the name of a thrown exception. The output for this variables is a printable character string.

To get the file name for a thrown exception with __throwFileName, you must compile the module with the -xp compiler option.


See Also

_ _throwExceptionName

_ _throwLineNumber


_ _throwLineNumber

See Also	Portability	Global Variables

Syntax

extern char * _ _throwLineNumber;

Header File

except.h

Description

Use this global variable to get the name of a thrown exception. The output for this variables is a printable character string.

To get the line number for a thrown exception with __throwLineNumber, you must compile the module with the -xp compiler option.


See Also

_ _throwExceptionName

_ _throwFileName


_threadid

Portability	Global Variables

Syntax

extern long _threadid;

Header File

stddef.h

Description

_threadid is a long integer that contains the ID of the currently executing thread. It is implemented as a macro, and should be declared only by including stddef.h.


_timezone

See Also	Portability	Global Variables

Syntax

extern long _timezone;

Header File

time.h

Description

_timezone is used by the time-and-date functions. It is calculated by then tzset function; it is assigned a long value that is the difference, in seconds, between the current local time and Greenwich mean time.


See Also

_daylight

_tzname


_tzname

See Also	Portability	Global Variables

Syntax

extern char * _tzname[2]

Header File

time.h

Description

The global variable _tzname is an array of pointers to strings containing abbreviations for time zone names. _tzname[0] points to a three-character string with the value of the time zone name from the TZ environment string. The global variable _tzname[1] points to a three-character string with the value of the daylight saving time zone name from the TZ environment string. If no daylight saving name is present, _tzname[1] points to a null string.


See Also

_daylight

_timezone


_version

See Also	Portability	Global Variables

Syntax

extern unsigned _version;

Header File

dos.h

Description

_version contains the operating system version number, with the major version number in the low byte and the minor version number in the high byte. (For DOS version x.y, the x is the major version number, and y is the minor.)


See Also

_osmajor

_osminor

_osversion


_wscroll

Portability	Global Variables

Syntax

extern int _wscroll

Header File

conio.h

Description

_wscroll is a console I/O flag. Its default value is 1. If you set _wscroll to 0, scrolling is disabled. This can be useful for drawing along the edges of a window without having your screen scroll.

_wscroll should be used only in character-based applications. It is available for EasyWin but is not allowed in 16-bit Windows, Win32s, or Win32 GUI applications.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

 	+	 	+	+	 	 	+


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

 	+	 	+	+


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

 	+	 	 	+	 	 	+


Obsolete Global Variables

See Also

The following global variables have been renamed to comply with ANSI naming requirements. You should always use the new names.

If you link with libraries that were compiled with Borland C++ 3.1 (or earlier) header files, the following message is generated:

Error: undefined external <varname> in module <LIBNAME>.LIB

You should recompile a library module that results in such an error. If you cannot recompile the code for such libraries, you can link with OBSOLETE.LIB to resolve the external variable names.

The following global variables have been renamed:

Old Name	New Name	Header File

daylight	_daylight	time.h

directvideo	_directvideo	conio.h

environ	_environ	stdlib.h

sys_errlist	_sys_errlist	errno.h

sys_nerr	_sys_nerr	errno.h

timezone	_timezone	time.h

tzname	_tzname	time.h


See Also

Obsolete Functions


_mexcep (typedef)

See Also

Defined In

math.h

Description

The typedef _mexcep enumerates these constants that represent possible mathematical errors.

_mexcep

Constant	Mathematical error

DOMAIN    	Argument was not in domain of function

Example:	log(-1)

SING      	Argument would result in a singularity

Example:	pow(0, -2)

OVERFLOW	Argument would produce a function result > MAXDOUBLE

Example:	exp(1000)

UNDERFLOW 	Argument would produce a function result < MINDOUBLE

Example:	exp(-1000)

TLOSS     	Argument would produce function result with total loss of significant digits

Example:	sin(10**70)

The symbolic constants MAXDOUBLE and MINDOUBLE are defined in VALUES.H.


See Also

_matherr


div_t and ldiv_t (typedef struct)

Defined In

stdlib.h

Syntax

typedef struct{

  int quot;    /* quotient */

  int rem;     /* remainder */

} div_t;

Description

The div_t type is a structure of integers used by div.

Syntax

typedef struct{

  long int quot;    /* quotient */

  long int rem;     /* remainder */

} ldiv_t;

Description

The ldiv_t type is a structure of longs used by ldiv.


jmp_buf (typedef struct)

Defined In

setjmp.h

Syntax

typedef struct{

  unsigned  j_sp,   j_ss;

  unsigned  j_flag, j_cs;

  unsigned  j_ip,   j_bp;

  unsigned  j_di,   j_es;

  unsigned  j_si,   j_ds;

} jmp_buf[1];

Description

A buffer of type jmp_buf is used to save and restore the program task state.


FILE (typedef struct)

Defined In

stdio.h

Syntax

typedef struct{

  short          level;

  unsigned       flags;

  char           fd;

  unsigned char  hold;

  short          bsize;

  unsigned char *buffer, *curp;

  unsigned       istemp;

  short          token;

} FILE;

Description

File control structure for streams.


dosSearchInfo (typedef struct)

Defined In

dos.h

Declaration

typedef struct{

  char   drive;

  char   pattern [13];

  char   reserved [7];

  char   attrib;

  short  time;

  short  date;

  long   size;

  char   nameZ [13];

} dosSearchInfo;


atexit_t (type)

Defined In

stdlib.h

Syntax

typedef void (* atexit_t)(void);

Description

Type of exit function passed to atexit.


size_t (type)

Defined in

alloc.h

mem.h

stddef.h

stdio.h

stdlib.h

string.h

Description

Type used for memory object sizes and repeat counts.


ptrdiff_t (type)

Defined In

alloc.h

mem.h

stddef.h

Description

Pointer difference data type.


fpos_t (type)

Defined In

stdio.h

Description

A file position type.


time_t (type)

Defined In

time.h

sys\types.h

Description

This variable type defines the value used for time functions.


clock_t (type)

Defined In

time.h

Description

The CLK_TCK constant defines the number of clock ticks per second. This data type is returned by the clock function stores an elapsed time measured in clock ticks.


sig_atomic_t (type)

Defined In

signal.h

Description

Atomic entity type.


wchar_t (type)

Defined In

stddef.h

stdlib.h>

Description

Wide-character constant (C only)

A character constant preceded by an L is a wide-character constant.


O_xxxx #defines
O_xxxx

Header File

fcntl.h

Description

These #defines are bit definitions for a file-access argument.

These RTL file-open functions use some (not all) of these definitions:

 	_dos_open

 	fdopen

 	fopen

 	freopen

 	_fsopen

 	open

 	_rtl_open

 	sopen

_dos_open and sopen also use file-sharing symbolic constants in the file-access argument.

Category

Constant	Description

Read/Write flag (Used by _dos_open, open, _rtl_open, and sopen)

O_RDONLY   	Open for reading only

O_WRONLY   	Open for writing only

O_RDWR     	Open for reading and writing

Other access flags (Used by open and sopen)

O_NDELAY	Not used; for UNIX compatibility.

O_APPEND	Append to end of file

If set, the file pointer is set to the end of the file prior to each write.

O_CREAT	Create and open file

If the file already exists, has no effect.

If the file does not exist, the file is created.

O_EXCL	Exclusive open: Used only with O_CREAT.

If the file already exists, an error is returned.

O_TRUNC	Open with truncation

If the file already exists, its length is truncated to 0. The file attributes remain unchanged.

Binary-mode/Text-mode flags(Used by fdopen, fopen, freopen, _fsopen, open and sopen)

O_BINARY	No translation: Explicitly opens the file in binary mode

O_TEXT 	CR-LF translation: Explicitly opens the file in text mode

Additional values available under DOS 3.x (Used by _rtl_open)

O_NOINHERIT	Child processes inherit file

O_DENYALL	Error if opened for read/write

O_DENYWRITE	Error if opened for write

O_DENYREAD	Error if opened for read

O_DENYNONE	Allow concurrent access

Note: Only one of the O_DENYxxx options can be included in a single open. These file-sharing attributes are in addition to any locking performed on the files.

DO NOT MODIFY these special read-only bits described in DOS documentation!

O_CHANGED  	Special DOS read-only bit

O_DEVICE   	Special DOS read-only bit


SEEK_xxx #defines
SEEK_xxx

See Also

Header File

io.h

stdio.h

Description

#defines that set seek starting points

Constant 	Value 	File Location

SEEK_SET	0	Seeks from beginning of file

SEEK_CUR	1	Seeks from current position

SEEK_END	2	Seeks from end of file


See Also

fseek

lseek


SH_xxxx #defines
SH_xxxx

Header File

share.h

Description

File-sharing mode for use with _dos_open and sopen (under DOS 3.0 or later).

Constant	Meaning

SH_COMPAT	Sets compatibility mode:

Allows other opens with SH_COMPAT. The call will fail if the file has already been opened in any other shared mode.

SH_DENYNONE	Permits read/write access

Allows other shared opens to the file, but not other SH_COMPAT opens

SH_DENYNO	Permits read/write access (provided for compatibility)

SH_DENYRD	Denies read access. Allows only writes from any other open to the file

SH_DENYRW	Denies read/write access. Only the current handle may have access to the file

SH_DENYWR	Denies write access. Allows only reads from any other open to the file

O_NOINHERIT	The file is not passed to child programs

These file-sharing attributes are in addition to any locking performed on the files.


P_xxxx #defines
P_xxxx

Header File

process.h

Description

Modes used by the spawn... functions.

Constant   	Meaning

P_WAIT  	Child runs separately, parent waits until exit

P_DETACH   	Child and parent run concurrently with child process in background mode

P_NOWAIT   	Child and parent run concurrently (Not implemented)

P_NOWAITO   	Child and parent run concurrently, but the child process is not saved

P_OVERLAY  	Child replaces parent so that parent no longer exists


SIG_xxx #defines
SIG_xxx

See Also

Header File

signal.h

Description

Predefined functions for handling signals generated by raise or by external events.

Name  	Meaning

SIG_DFL  	Terminate the program

SIG_IGN  	No action, ignore signal

SIG_ERR  	Return error code


See Also

signal

signal types


SIGxxxx #defines
SIGxxxx

Header File

signal.h

Description

Signal types used by raise and signal.

Signal 	Note 	Meaning	Default Action

SIGABRT  	(*) 	Abnormal termination	= to calling  _exit(3)

SIGFPE     	Bad floating-point operation     	= to calling  _exit(1)

Arithmetic error caused by

division by 0, invalid operation, etc.

SIGILL   	(#) 	Illegal operation 	= to calling _exit(1)

SIGINT 	Control-C interrupt 	Is to do an  INT 23h

SIGSEGV  	(#)	Invalid access to storage 	= to calling _exit(1)

SIGTERM  	(*) 	Request for program termination	= to calling _exit(1)

(*) Signal types marked with a (*) aren't generated by DOS or Borland C++  during normal operation. However, they can be generated with raise.

(#) Signals marked by (#) can't be generated asynchronously on 8088 or   8086 processors but can be generated on some other processors (see   signal for details).


stdaux, stderr, stdin, stdout, and stdprn

Header File

stdio.h

Description

Predefined streams automatically opened when the program is started.

Name  	Meaning

stdin   	Standard input device

stdout  	Standard output device

stderr  	Standard error output device

stdaux  	Standard auxiliary device

stdprn  	Standard printer


S_Ixxxx #defines
S_Ixxxx

Header File

sys\stat.h

Description

Definitions used for file status and directory functions.

Name    	Meaning

S_IFMT  	File type mask

S_IFDIR   	Directory

S_IFIFO   	FIFO special

S_IFCHR   	Character special

S_IFBLK   	Block special

S_IFREG   	Regular file

S_IREAD   	Owner can read

S_IWRITE  	Owner can write

S_IEXEC   	Owner can execute


NULL #define
NULL

Header File

alloc.h

mem.h

stddef.h

stdio.h

stdlib.h

Description

Null pointer value.


Bit Definitions for fnsplit

Header File

dir.h

Description

Bit definitions returned from fnsplit to identify which pieces of a file name were found during the split.

Flag     	Component

DIRECTORY   	Path includes a directory (and possibly subdirectories)

DRIVE     	Path includes a drive specification (see DIR.H)

EXTENSION  	Path includes an extension

FILENAME  	Path includes a file name

WILDCARDS   	Path contains wildcards (* or ?)


MAXxxxx #defines (fnsplit)
MAXxxxx

Header File

dir.h

Description

These symbols define the maximum number of characters in a file specification for fnsplit (including room for a terminating NULL).

Name	Meaning

MAXPATH   	Complete file name with path

MAXDRIVE  	Disk drive (e.g., "A:")

MAXDIR  	File subdirectory specification

MAXFILE   	File name without extension

MAXEXT  	File extension


_F_xxxx #defines
_F_xxxx

Header File

stdio.h

Description

File status flags of streams

Name   	Meaning

_F_RDWR  	Read and write

_F_READ  	Read-only file

_F_WRIT  	Write-only file

_F_BUF   	Malloc'ed buffer data

_F_LBUF  	Line-buffered file

_F_ERR   	Error indicator

_F_EOF   	EOF indicator

_F_BIN   	Binary file indicator

_F_IN  	Data is incoming

_F_OUT   	Data is outgoing

_F_TERM  	File is a terminal


FA_xxxx #defines
FA_xxxx

Header File

dos.h

Description

DOS file attributes

Constant   	Description

FA_RDONLY  	Read-only attribute

FA_HIDDEN  	Hidden file

FA_SYSTEM  	System file

FA_LABEL   	Volume label

FA_DIREC   	Directory

FA_ARCH  	Archive

For more detailed information about these attributes, refer to your DOS reference manuals.


EXIT_xxxx #defines
EXIT_xxxx

Header File

stdlib.h

Description

Constants defining exit conditions for calls to the exit function.

Name      	Meaning

EXIT_SUCCESS  	Normal program termination

EXIT_FAILURE  	Abnormal program termination


_IOxxx #defines
_IOxxx

See Also

Header File

stdio.h

Description

Constants for defining buffering style to be used with a file.

Name  	Meaning

_IOFBF  	The file is fully buffered. When a buffer is empty, the next input operation will attempt to fill the entire buffer.

       	On output, the buffer will be completely filled before any data is written to the file.

_IOLBF  	The file is line buffered.  When a buffer is empty, the next input operation will still attempt to fill the entire buffer.

      	On output, however, the buffer will be flushed whenever a newline character is written to the file.

_IONBF  	The file is unbuffered. The buf and size parameters are ignored. Each input operation will read directly from the file, and each output operation will immediately write the data to the file.


See Also

setvbuf


BUFSIZ #define
BUFSIZ

Header File

stdio.h

Description

Default buffer size used by setbuf function.


EOF #define
EOF

Header File

stdio.h

Description

A constant indicating that end-of-file has been reached on a file.


_IS_xxx #defines
_IS_xxx

Header File

ctype.h

Description

Bit settings in the _ctype[] used by the is... character macros.

Name   	Meaning

_IS_SP	Is space

_IS_DIG	Is digit

_IS_UPP	Is uppercase

_IS_LOW	Is lowercase

_IS_HEX	[A-F] or [a-f]

_IS_CTL	Control

_IS_PUN	Punctuation


CHAR_xxx #defines
CHAR_xxx

Header File

LIMITS.H

Description

Name    	Meaning

CHAR_BIT  	Type char, number of bits

CHAR_MAX  	Type char, minimum value

CHAR_MIN  	Type char, maximum value

These values are independent of whether type char is defined as signed or unsigned by default.


SCHAR_xxx #defines
SCHAR_xxx

Header File

limits.h

Description

Name     	Meaning

SCHAR_MAX  	Type char, maximum value

SCHAR_MIN  	Type char, minimum value


Uxxxx_MAX #defines
Uxxxx_MAX

Header File

limits.h

Description

Name     	Maximum value for type xxx

UCHAR_MAX  	unsigned char

USHRT_MAX  	unsigned short

UINT_MAX   	unsigned integer

ULONG_MAX  	unsigned long


SHRT_xxx #defines
SHRT_xxx

Header File

limits.h

Description

Name    	Meaning

SHRT_MAX  	Type short, maximum value

SHRT_MIN  	Type short, minimum value


INT_xxx #defines
INT_xxx

Header File

limits.h

Description

Maximum and minimum value for type int.

Name    	Meaning

INT_MAX   	Type int, maximum value

INT_MIN   	Type int, minimum value


LONG_xxx #defines
LONG_xxx

Header File

limits.h

Description

Maximum and minimum value for type long.

Name    	Meaning

LONG_MAX  	Type long, maximum value

LONG_MIN  	Type long, minimum value


CW_DEFAULT #define
CW_DEFAULT

Header File

float.h

Description

Default control word for 8087/80287 math coprocessor.


EDOM, ERANGE, HUGE_VAL #defines
EDOM, ERANGE, HUGE_VAL

Header File

errno.h

math.h

Description

Name    	Meaning

EDOM    	Error code for math domain error

ERANGE  	Error code for result out of range

HUGE_VAL  	Overflow value for math functions


NDEBUG #define
NDEBUG

Header File

assert.h

Description

NDEBUG means "Use #define to treat assert as a macro or a true function".

Can be defined in a user program. If defined, assert is a true function; otherwise assert is a macro.


NFDS #define
NFDS

Header File

dos.h

Description

Maximum number of file descriptors.


MAXxxxx #defines (integer data types)
MAXxxxx

Header File

values.h

Description

Maximum values for integer data types

Name    	Meaning

MAXSHORT  	Largest short

MAXINT  	Largest int

MAXLONG  	Largest long


M_E, M_LOGxxx, M_LNxx #defines
M_E, M_LOGxxx, M_LNxx

Header File

math.h

Description

The constant values for logarithm functions.

Name    	Meaning

M_E     	The value of e

M_LOG2E   	The value of log(e)

M_LOG10E  	The value of log10(e)

M_LN2   	The value of ln(2)

M_LN10  	The value of ln(10)


PI constants

Header File

math.h

Description

Common constants of pi

Name	Meaning

M_PI     	pi

M_PI_2    	One-half pi

M_PI_4    	One-fourth pi

M_1_PI    	One divided by pi

M_2_PI    	Two divided by pi

M_1_SQRTPI  	One divided by the square root of pi

M_2_SQRTPI  	Two divided by the square root of pi


M_SQRTxx #defines
M_SQRTxxx

Header File

math.h

Description

Constant values for square roots of 2.

Name	Meaning

M_SQRT2	Square root of 2

M_SQRT_2	1/2 the square root of 2


L_ctermid #define
L_ctermid

Header File

stdio.h

Description

The length of a device id string.


L_tmpnam #define
L_tmpnam

Header File

stdio.h

Description

Size of an array large enough to hold a temporary file name string.


TMP_MAX #define
TMP_MAX

Header File

stdio.h

Description

Maximum number of unique file names.


OPEN_MAX #define
OPEN

Header File

stdio.h

Description

Number of files that can be open simultaneously.

Name	Meaning

FOPEN_MAX	Maximum files per process

SYS_OPEN   	Maximum files for system


HANDLE_MAX #define
HANDLE_MAX

Header File

io.h

Description

Maximum number of handles.


RAND_MAX #define
RAND_MAX

Header File

stdlib.h

Syntax

Description

Maximum value returned by rand function.


BITSPERBYTE #define
BITSPERBYTE

Header File

values.h

Description

Number of bits in a byte.


Float and Double Limits

Header File

values.h

Description

UNIX System V compatible:

_LENBASE  	Base to which exponent applies

Limits for double float values

_DEXPLEN  	Number of bits in exponent

DMAXEXP   	Maximum exponent allowed

DMAXPOWTWO  	Largest power of two allowed

DMINEXP   	Minimum exponent allowed

DSIGNIF   	Number of significant bits

MAXDOUBLE   	Largest magnitude double value

MINDOUBLE   	Smallest magnitude double value

Limits for float values

_FEXPLEN  	Number of bits in exponent

FMAXEXP   	Maximum exponent allowed

FMAXPOWTWO  	Largest power of two allowed

FMINEXP   	Minimum exponent allowed

FSIGNIF   	Number of significant bits

MAXFLOAT  	Largest magnitude float value

MINFLOAT  	Smallest magnitude float value


HIBITx #defines
HIBITxxx

Header File

values.h

Description

Bit mask for the high (sign) bit of standard integer types.

Name  	Meaning

HIBITS   	For type short

HIBITI     	For type int

HIBITL   	For type long


Error Numbers in errno

Header File

errno.h

Description

These are the mnemonics and meanings for the error numbers found in errno.

Each value listed can be used to index into the sys_errlist array for displaying messages.

Also, perror will display messages.

Mnemonic 	Meaning

EZERO	Error 0

EINVFNC 	Invalid function number

ENOFILE  	File not found

ENOPATH  	Path not found

ECONTR 	Memory blocks destroyed

EINVMEM  	Invalid memory block address

EINVENV 	Invalid environment

EINVFMT	Invalid format

EINVACC	Invalid access code

EINVDAT	Invalid data

EINVDRV	Invalid drive specified

ECURDIR 	Attempt to remove CurDir

ENOTSAM	Not same device

ENMFILE	No more files

ENOENT 	No such file or directory

EMFILE	Too many open files

EACCES 	Permission denied

EBADF 	Bad file number

ENOMEM 	Not enough memory

ENODEV  	No such device

EINVAL 	Invalid argument

E2BIG  	Arg list too long

ENOEXEC	Exec format error

EXDEV  	Cross-device link

EDOM  	Math argument

ERANGE 	Result too large

EFAULT 	Unknown error

EEXIST  	File already exists


Bit fields

A bit field is an element of a structure that is defined in terms of bits. Using a special type of struct definition, you can declare a structure element that can range from 1 to 16 bits in length.

For example, this struct

struct  bit_field {

  int bit_1        : 1;

  int bits_2_to_5  : 4;

  int bit_6        : 1;

  int bits_7_to_16 : 10;

} bit_var;

corresponds to this collection of bit fields:

|----------------------------|---|---------|---|

| 16 15 14 13 12 11 10 9 8 7 | 6 | 5 4 3 2 | 1 |

|----------------------------|---|---------|---|

See Also

class

union


ftime structure
ftime

header: IO.H

A file's time and date. Used by the functions getftime and setftime.

struct ftime {

  unsigned ft_tsec  : 5;  /* Two seconds */

  unsigned ft_min   : 6;  /* Minutes */

  unsigned ft_hour  : 5;  /* Hours */

  unsigned ft_day   : 5;  /* Days */

  unsigned ft_month : 4;  /* Months */

  unsigned ft_year  : 7;  /* Year - 1980 */

};


exception and _exceptionl structure
_exception and _exceptionl

header: MATH.H

The format of error information for math routines.

Struct exception is used by _matherr:

struct _exception {

  int     type;

  char   *name;

  double  arg1, arg2, retval;

};

Struct _exceptionl is used by _matherrl:

struct _exceptionl {

  int     type;

  char   *name;

  long double arg1, arg2, retval;

};

Member  	What It Is (Or Represents)

type    	The type of mathematical error that occurred; an enum type defined in the typedef _mexcep.

name    	A pointer to a null-terminated string holding the name of the math library function that resulted in an error.

arg1,   	The arguments (passed to the function *name) that caused the error.

arg2	If only one argument was passed to the function, it is stored in arg1.

retval  	The default return value for matherr; you can modify this value.


complex and _complexl structure
complex and _complexl

header: MATH.H

Complex number representation.

Struct complex is used by the complex function cabs.

struct complex {

  double  x, y;

};

Struct _complexl is used by the long double complex function cabsl.

struct _complexl {

  long double x, y;

};

x is the real part, and y is the imaginary part.


tm structure
tm

header: TIME.H

A structure defining the broken-down time.

Used by the functions asctime, gmtime,localtime, mktime, and strftime.

struct tm {

  int tm_sec;   /* Seconds */

  int tm_min;   /* Minutes */

  int tm_hour;  /* Hour (0--23) */

  int tm_mday;  /* Day of month (1--31) */

  int tm_mon;   /* Month (0--11) */

  int tm_year;  /* Year (calendar year minus 1900) */

  int tm_wday;  /* Weekday (0--6; Sunday = 0) */

  int tm_yday;  /* Day of year (0--365) */

  int tm_isdst; /* 0 if daylight savings time is not in effect) */

};


timeb structure
timeb

header: SYS\TIMEB.H

Current time information filled out by the ftime function.

struct timeb {

  long time ;      /* seconds since 00:00:00, 1/1/70, GMT */

  short millitm ;  /* fraction of second  (in milliseconds) */

  short timezone ; /* difference between local time and GMT */

  short dstflag ;  /* 0 if daylight savings time is not in effect */

};

timezone is computed going west from GMT.

ftime gets this field from timezone, which is set by tzset.


stat structure
stat

header: SYS\STAT.H

A structure containing information about a file or directory. Used by the fstat and stat functions.

struct stat {

  short  st_dev,   st_ino;

  short  st_mode,  st_nlink;

  int    st_uid,   st_gid;

  short  st_rdev;

  long   st_size,  st_atime;

  long   st_mtime, st_ctime;

};

Element	What It Is

st_dev    	Drive number of disk containing the file, or file handle if the file is on a device

st_mode   	Bit mask giving information about the open file's mode

st_nlink  	Set to the integer constant 1

st_rdev   	Same as st_dev

st_size   	Size of the open file in bytes

st_atime  	Most recent time the open file was modified

st_mtime  	Same as st_atime

st_ctime  	Same as st_atime

st_ino    	These elements contain values

st_uid    	that are not meaningful under

st_gid    	DOS.


ffblk structure
ffblk

header: DIR.H

DOS file control block structure.

struct ffblk {

  char ff_reserved[21]; /* reserved by DOS */

  char ff_attrib;       /* attribute found */

  int  ff_ftime;        /* file time */

  int  ff_fdate;        /* file date */

  long ff_fsize;        /* file size */

  char ff_name[13];     /* found file name */

};

Remarks

ff_ftime and ff_fdate are 16-bit structures divided into bit fields for referring to the current date and time.

The structure of these fields was established by DOS.

See Also

findfirst

ftime structure

find_t structure


fcb structure
fcb

header: DOS.H

The structure of the MS-DOS file control blocks.

struct fcb {

  char   fcb_drive;

  char   fcb_name[8],  fcb_ext[3];

  short  fcb_curblk,   fcb_recsize;

  long   fcb_filsize;

  short  fcb_date;

  char   fcb_resv[10], fcb_currec;

  long   fcb_random;

};


xfcb structure
xfcb

header: DOS.H

The MS-DOS extended file control block structure.

struct xfcb {

  char         xfcb_flag;

  char         xfcb_resv[5];

  char         xfcb_attr;

  struct  fcb  xfcb_fcb;

};


dfree structure
dfree

header: DOS.H

The structure of the information returned by the getdfree function.

struct dfree {

  unsigned df_avail;  /* Available clusters */

  unsigned df_total;  /* Total clusters */

  unsigned df_bsec;   /* Bytes per sector */

  unsigned df_sclus;  /* Sectors per cluster */

};


fatinfo structure
fatinfo

header: DOS.H

The structure of the file allocation table information filled in by the getfat and getfatd functions.

struct fatinfo {

  char  fi_sclus;  /* sectors per cluster */

  char  fi_fatid;  /* the FAT id byte */

  int   fi_nclus;  /* number of clusters */

  int   fi_bysec;  /* bytes per sector */

};


time structure
time

header: DOS.H

Structure of the time as used by these functions:

dostounix

gettime

settime

unixtodos

struct time {

  unsigned char  ti_min;   /* minutes */

  unsigned char  ti_hour;  /* hours */

  unsigned char  ti_hund;  /* hundredths of seconds */

  unsigned char  ti_sec;   /* seconds */

};


date structure
date

header: DOS.H

Structure of the date as used by these functions:

dostounix

getdate

setdate

unixtodos

struct date {

  int da_year;     /* current year */

  char da_day;     /* day of the month */

  char da_mon;     /* month (1 = Jan) */

};


REGS (union)

header: DOS.H

The union REGS is used to pass information to and from these functions:

int86

int86x

intdos

intdosx

union REGS {

  struct  WORDREGS  x;

  struct  BYTEREGS  h;

};

See Also

struct REGPACK


BYTEREGS and WORDREGS structures
BYTEREGS and WORDREGS

header: DOS.H

Structures for storing byte and word registers

struct BYTEREGS  {

  unsigned char  al, ah, bl, bh;

  unsigned char  cl, ch, dl, dh;

};

struct WORDREGS  {

  unsigned int  ax, bx, cx, dx;

  unsigned int  si, di, cflag, flags;

};


SREGS structure
SREGS

header: DOS.H

The structure of the segment registers passed to and filled in by these functions:

int86x

intdosx

segread

struct SREGS {

  unsigned int  es;

  unsigned int  cs;

  unsigned int  ss;

  unsigned int  ds;

};


REGPACK structure
REGPACK

header: DOS.H

The structure of the values passsed to and returned by the intr function call.

struct REGPACK {

  unsigned  r_ax, r_bx, r_cx, r_dx;

  unsigned  r_bp, r_si, r_di;

  unsigned  r_ds, r_es, r_flags;

};

See Also

REGS


COUNTRY structure
COUNTRY

header: DOS.H

The structure COUNTRY specifies how certain country-dependent data is to be formatted.

struct COUNTRY {

  int co_date;         /* date format */

  char co_curr[5];     /* currency symbol */

  char co_thsep[2];    /* thousands separator */

  char co_desep[2];    /* decimal separator */

  char co_dtsep[2];    /* date separator */

  char co_tmsep[2];    /* time separator */

  char co_currstyle;   /* currency style */

  char co_digits;      /* significant digits in currency */

  char co_time;        /* time format */

  long co_case;        /* case map */

  char co_dasep[2];    /* data separator */

  char co_fill[10];    /* filler */

};

This is the date format in co_date:

Value 	Style	Format

0	U.S.	(Month, Day, Year)

1	European	(Day, Month, Year)

2	Japanese	(Year, Month, Day )

This is the currency display style in co_currstyle:

Style 	Example	Meaning

0	$10.52	Currency symbol precedes value with no spaces between the symbol and the number

1	10.52$	Currency symbol follows value with no spaces between the number and the symbol

2	$ 10.52	Currency symbol precedes value with a space after the symbol.

3	10.52 $	Currency symbol follows the number with a space before the symbol.


devhdr structure
devhdr

header: DOS.H

Header structure for MS-DOS device drivers.

struct devhdr {

  long            dh_next;

  short           dh_attr;

  unsigned short  dh_strat;

  unsigned short  dh_inter;

  char            dh_name[8];

};


lconv structure
lconv

Used by localeconv.

struct lconv {

  char *decimal_point;

  char *thousands_sep;

  char *grouping;

  char *int_curr_symbol;

  char *currency_symbol;

  char *mon_decimal_point;

  char *mon_thousands_sep;

  char *mon_grouping;

  char *positive_sign;

  char *negative_sign;

  char int_frac_digits;

  char frac_digits;

  char p_cs_precedes;

  char p_sep_by_space;

  char n_cs_precedes;

  char n_sep_by_space;

  char p_sign_posn;

  char n_sign_posn;

};


DOSERROR structure
DOSERROR

header: DOS.H

Used by dosexterr to return extended DOS errors.

struct DOSERROR {

  int  de_exterror;     /* extended error */

  char de_class;        /* error class */

  char de_action;       /* action */

  char de_locus;        /* error locus */

};

See Also

_doserrno

errno

Example

DOSERROR


/* DOSERROR example */

#include <stdio.h>

#include <dos.h>

  int main(void)  {

  FILE *fp;

  struct DOSERROR info;

  fp = fopen("perror.dat","r");

  if (!fp) perror("Unable to open file for reading");

    dosexterr(&info);

  printf("Extended DOS error information:\n");

  printf("   Extended error:     %d\n",info.de_exterror);

  printf("            Class:     %x\n",info.de_class);

  printf("           Action:     %x\n",info.de_action);

  printf("      Error Locus:     %x\n",info.de_locus);

  return 0;

}


find_t structure
find_t

header: DOS.H

DOS file control block structure used by _dos_findfirst and _dos_findnext.

The find_t structure corresponds exactly to the ffblk structure.

struct find_t {

  char     reserved[21];   /* Microsoft reserved - do not change*/

  char     attrib;         /* attribute byte for matched file */

  unsigned wr_time;        /* time of last write to file */

  unsigned wr_date;        /* date of last write to file */

  long     size;           /* size of file */

  char     name[13];       /* asciiz name of matched file */

};


dirent structure
dirent

header: DIRENT.H

Structure that corresponds to a single directory entry. Used by readdir.

In addition to non-accessible members, dirent contains the member

char  d_name[];

where d_name is an array of characters containing the null-terminated file name for the current directory entry.

The size of the array is indeterminate; use strlen to determine the length of the file name.


dosdate_t structure
dosdate_t

header: DOS.H

Structure used by _dos_getdate and _dos_setdate.

struct dosdate_t {

  unsigned char day;        /* 1--31 */

  unsigned char month;      /* 1--12 */

  unsigned int  year;       /* 1980--2099 */

  unsigned char dayofweek;  /* 0--6; 0 = Sunday */

};


dostime_t structure
dostime_t

header: DOS.H

Structure used by _dos_gettime and _dos_settime.

struct dostime_t {

  unsigned char hour;         /* Hours */

  unsigned char minute;       /* Minutes */

  unsigned char second;       /* Seconds */

  unsigned char hsecond;      /* Hundredths of seconds */

};


diskfree_t structure
diskfree_t

header: DOS.H

Structure used by _dos_getdiskfree.

struct diskfree_t {

  unsigned total_clusters;

  unsigned avail_clusters;

  unsigned sectors_per_cluster;

  unsigned bytes_per_sector;

};


utimbuf structure
utimbuf

header: UTIME.H

Structure used by utime.

struct utimbuf {

  time_t   actime;    /* access time */

  time_t   modtime;   /* modification time */

};

Because the DOS file system supports only a modification time, utime ignores actime and uses only modtime to set the file's modification time.


Keywords (Alphabetical)
Keywords

Keywords are words reserved for special purposes and must not be used as normal identifier names. You can set options in the IDE or for the command-line compiler to select ANSI keywords only, UNIX keywords only, or to support all keywords--including the Borland C++ extensions.

This is an alphabetical listing of the keywords supported in this release of Borland C++. For a functional listing of the keywords, see Keywords (by Category).

A

__asm

_asm

asm

auto

B

break

C

case

catch

__cdecl

_cdecl

cdecl

char

class

const

const_cast

continue

__cs

_cs

D

default

delete

do

double

_ds

__ds

dynamic_cast

E

else

enum

_es

__es

__except

_export

__export

extern

F

__far

_far

far

__fastcall

_fastcall

__finally

float

for

friend

G

goto

H

__huge

_huge

huge

I

if

__import

_import

inline

interrupt

int

__interrupt

_interrupt

L

__loadds

_loadds

long

N

__near

_near

near

new

O

operator

P

__pascal

_pascal

pascal

private

protected

public

R

register

reinterpret_cast

return

__rtti

S

__saveregs

_saveregs

__seg

_seg

short

signed

sizeof

__ss

_ss

static

static_cast

__stdcall

_stdcall

struct

switch

T

template

this

__thread

throw

__try

try

typedef

typeid

U

union

unsigned

V

virtual

void

volatile

W

wchar_t

while


Keywords (by Category)

This is a categorical listing of the keywords Borland C++ supports. For an alphabetical listing of the keywords, see Keywords (Alphabetical).

Borland C++ Extensions	keywords unique to Borland C++

C++ Specific	keywords recognized only in C++ programs

Modifiers	keywords that change one or more attributes of an identifier associated with an object

Operators	keywords that invoke functions against objects or identifiers

Statements	keywords that specify program control during execution

Storage Class Specifiers	keywords that define the location and duration of an identifier

Type Specifiers	keywords that determine how memory is allocated and bit patterns are interpreted


Borland C++ Keyword Extensions

Borland C++ provides additional keywords that are not part of the ANSI or UNIX conventions. You cannot use these keywords in your programs if you set the IDE or command-line options to recognize only ANSI or UNIX keywords.

The Borland C++ keyword extensions are:

_asm

__asm

_cdecl

cdecl

_cs

__ds

_ds

__es

_es

__except

__export

_export

far

_far

__far

__fastcall

_fastcall

__finally

__huge

_huge

huge

_import

__import

__interrupt

_interrupt

interrupt

_loadds

__loadds

near

__near

_near

_pascal

__pascal

pascal

__rtti

__saveregs

_saveregs

__seg

_seg

_ss

__thread

__try


C++ Specific Keywords

There are several keywords specific to C++. They are not available if you are writing a C-only program. These keywords primarily deal with classes, templates, and exception handling.

The keywords specific to C++ are:

asm	new	template

catch	operator	this

class	private	throw

const_cast	protected	try

delete	public	typeid

dynamic_cast	reinterpret_cast	typesafe_downcast

friend	__rtti	virtual

inline	static_cast	wchar_t


Modifiers

A declaration uses modifiers to alter aspects of the identifier/object mapping.

The Borland C++ modifiers are:

__cdecl

const

__cs

__ds

__es

__export

__far

__fastcall

__huge

__import

__interrupt

__loadds

__near

__pascal

__rtti

__ss

__stdcall

volatile


Operator Keywords

See Also

Several Borland C++ keywords denote operators that invoke functions against objects and identifiers.

The keyword operators supported by Borland C++ are:

delete	operator	typeid

new	sizeof


See Also

Operators


Statement Keywords

Statements specify the flow of control in a program. In the absence of specific jumps and selection statements, statements execute sequentially as they appear in the source code.

The statement keywords in Borland C++ are:

break	else	switch

case	__finally	throw

catch	for	try

continue	goto	while

default	if

do	return


Storage Class Specifiers

Storage classes dictate the location (data segment, register, heap, or stack) of an object and its duration or lifetime (the entire running time of the program, or during execution of some blocks of code). Storage class can be established by the declaration syntax, by its placement in the source code, or by both of these factors.

The storage class specifiers in Borland C++ are:

auto	register	typedef

extern	static


Type Specifiers

The type determines how much memory is allocated to an object and how the program interprets the bit patterns found in the object's storage allocation. A data type is the set of values (often implementation-dependent) identifiers can assume, together with the set of operations allowed on those values.

The type specifier keywords in Borland C++ are:

char	float	signed

class	int	struct

double	long	union

enum	short	unsigned

The compile-time operator, sizeof, lets you determine the size in bytes of any standard or user-defined type.


asm, _asm, and _ _asm

See Also	Example	Keywords

Syntax

asm <opcode> <operands> <; or newline>

_asm <opcode> <operands> <; or newline>

__asm <opcode> <operands> <; or newline>

Description

Use the asm, _asm, or _ _asm keyword to place assembly language statements in the middle of your C or C++ source code. Any C++ symbols are replaced by the appropriate assembly language equivalents.

You can group assembly language statements by beginning the block of statements with the asm keyword, then surrounding the statements with braces ({}). The initial brace must be on the same line as the asm keyword; placing it on the following line generates a syntax error.


Examples

// This example places a single assembler statement in your code:

asm pop dx

// If you want to include several of asm statements,

// surround them with braces:

asm {

  mov ax, 0x0e07

  xor bx, bx

  int 0x10         // makes the system beep

}


See Also

BASM


auto

Example	Keywords

Syntax

[auto] <data-definition> ;

Description

Use the auto modifer to define a local variable as having a local lifetime.

This is the default for local variables and is rarely used.


Example

int main()

{

  auto int i;

  i = 5;

  return i;

}


break

See Also	Example	Keywords

Syntax

break ;

Description

Use the break statement within loops to pass control to the first statement following the innermost enclosing brace.


See Also

continue

do

for

switch

while


Example

switch (time)

{

case 12:

cout << "Time for lunch!\n";

break;

case 1:

cout << "Meet with manager.\n";

break;

}


case

See Also	Example	Keywords

Syntax

switch ( <switch variable> ){

  case <constant expression> : <statement>; [break;]

    .

    .

    .

  default : <statement>;

}

Description

Use the case statement in conjunction with switches to determine which statements evalute.

The list of possible branch points within <statement> is determined by preceding substatements with

case <constant expression> : <statement>;

where <constant expression> must be an int and must be unique.

The <constant expression> values are searched for a match for the <switch variable>.

If a match is found, execution continues after the matching case statement until a break statement is encountered or the end of the switch statement is reached.

If no match is found, control is passed to the default case.

Note:	It is illegal to have duplicate case constants in the same switch statement.


See Also

break

default

switch


catch

See Also	Keywords

Syntax

catch (exception-declaration) compound-statement

Description

The exception handler is indicated by the catch keyword. The handler must be used immediately after the statements marked by the try keyword. The keyword catch can also occur immediately after another catch. Each handler will only evaluate an exception that matches, or can be converted to, the type specified in its argument list.


See Also

C++ Exception Handling

throw (keyword)


cdecl, _cdecl, and _ _cdecl

Example	Keywords

Syntax

cdecl <data/function definition> ;

_cdecl <data/function definition> ;

__cdecl <data/function definition> ;

Description

Use a cdecl, _cdecl, or __cdecl modifier to declare a variable or a function using the C-style naming conventions (case-sensitive, with a leading underscore appended). When  you use cdecl, _cdecl, or __cdecl in front of a function, it effects how the parameters are passed (last parameter is pushed first, and the caller cleans up the stack).

The cdecl, _cdecl, and __cdecl keywords are specific to Borland C++.


Example

int cdecl FileCount;

long far cdecl HisFunc(int x);


char

See Also	Keywords

Syntax

[signed|unsigned] char <variable_name>

Description

Use the type specifier char to define a character data type. Variables of type char are 1 byte in length.

A char can be signed, unsigned, or unspecified.

Objects declared as characters (char) are large enough to store any member of the basic ASCII character set.


See Also

data types (16-bit)

data types (32-bit)


class

See Also	Example	Keywords

Syntax

<classkey> <classname> [<:baselist>] { <member list> }

<classkey> is either a class, struct, or union.

<classname> can be any name unique within its scope.

<baselist> lists the base class(es) that this class derives from. <baselist> is optional

<member list> declares the class's data members and member functions.

Description

Use the class keyword to define a C++ class.

Within a class:

the data are called data members

the functions are called member functions


Example

class stars {

   int magnitude;

   int starfunc(void);

};


See Also

Class Templates

Function Templates

private

protected

public

this


const

See Also	Example	Keywords

Syntax

const <variable name> [ = <value> ] ;

<function name> ( const <type>*<variable name> ;)

<function name> const;

Description

Use the const modifier to make a variable value unmodifiable.

Use the const modifier to assign an initial value to a variable that cannot be changed by the program. Any future assignments to a const result in a compiler error.

Using the const Keyword in C++ Programs

C++ extends const to include classes and member functions. In a C++ class definition, use the const modifier following a member function declaration. The member function is prevented from modifying any data in the class.

A class object defined with the const keyword can only member functions that are also defined with const. If you attempt to call a member function that is not defined as constant, the call results in non-constant function class-name::member-function-name(). Using the const keyword in this manner is a safety feature of C++; it is not automatically supported by the compiler.

Warning:	A pointer can indirectly modify a const variable, as in the following:

*(int *)&my_age = 35;

If you use the const modifier with a pointer parameter in a function's parameter list, the function cannot modify the variable that the pointer points to. For example,

int printf (const char *format, ...);

printf is prevented from modifying the format string.


See Also

const_cast

volatile


Example

int lowerBound() const;


continue

See Also	Example	Keywords

Syntax

continue ;

Description

Use the continue statement within loops to pass control to the end of the innermost enclosing brace; at which point the loop continuation condition is re-evaluated.


See Also

while

do

for


Example

void main ()

{

  for (i = 0; i < 20; i++) {

     if (array[i] == 0)

       continue;

     array[i] = 1/array[i];

  }

}


default

See Also	Example	Keywords

Syntax

switch ( <switch variable> ){

  case <constant expression> : <statement>; [break;]

    .

    .

    .

  default : <statement>;

}

Description

Use the default statement in switch statement blocks.

If a case match is not found and the default statement is found within the switch statement, the execution continues at this point.

If no default is defined in the switch statement, control passes to the next statement that follows the switch statement block.


See Also

break


delete

See Also	Example	Operators

Syntax

<::> delete <cast-expression>

<::> delete [ ] <cast-expression>

delete <array-name> [ ];

Description

The delete operator offer dynamic storage deallocation, deallocating a memory block allocated by a previous call to new. It is similar but superior to the standard library function free.

You can also use the delete operator to remove arrays that you no longer need.


See Also

The delete Operator with Arrays

Overloading the operator delete


The delete Operator with Arrays

Arrays are deleted by operator delete[](). You must use the syntax delete [] expr when deleting an array. After C++ 2.1, the array dimension should not be specified within the brackets:

char * p;

void func()

{

   p = new char[10];    //  allocate 10 chars

   delete[] p;          // delete 10 chars

}

C++ 2.0 code required the array size. In order to allow 2.0 code to compile, Borland C++ issues a warning and simply ignores any size that is specified. For example, if the preceding example reads delete[10] p and is compiled, the warning is as follows:

Warning: Array size for 'delete' ignored in function func()

With Borland C++, the [] is actually required only when the array element is in a class with a destructor. But it is good programming practice to always tell the compiler that an array is being deleted.


Overloading the Operator delete

Example

The global operators, ::operator delete(), and ::operator delete[]() cannot be overloaded. However, you can override the default version of each of these operators with your own implementation. Only one instance of the each global delete function can exist in the program.

The user-defined operator delete must have a void return type and void* as its first argument; a second argument of type size_t is optional. A class T can define at most one version of each of T::operator delete[]() and T::operator delete(). To overload the delete operators, use the following prototypes.

void operator delete(void *Type_ptr, [size_t Type_size]);     // For Non-array

void operator delete[](size_t Type_ptr, [size_t Type_size]);  // For arrays


do

See Also	Example	Keywords

Syntax

do <statement> while ( <condition> );

Description

The do statement implements a do ... while loop.

<statement> is executed repeatedly as long as the value of <condition> remains non-zero.

Since the conditon is tests after each the loop executes the <statement>, the loop will execute at least once.


do Example

/* This example prompts users for a password  */

/* and continued to prompt them until they    */

/* enter one that matches the value stored in */

/* checkword.                                 */

#include <stdio.h>

#include <string.h>

int main ()

{

  char checkword[80] = "password";

  char password[80]  = "";

  do {

    printf ("Enter password: ");

    scanf("%s", password);

  } while (strcmp(password, checkword));

  return 0;

}


See Also

while


double

See Also	Keywords

Syntax

[long] double <identifier>

Description

Use the double type specifier to define an identifier to be a floating point data type. The optional modifier long extends the accuracy of the floating point value.

If you use the double keyword, the Borland C++ IDE will automatically link the floating-point math package into your program.


See Also

data types (16-bit)

data types (32-bit)

float

long

Standard Arithmetic Conversions


enum

Example	Keywords

Syntax

enum [<type_tag>] {<constant_name> [= <value>], ...} [var_list];

<type_tag> is an optional type tag that names the set.

<constant_name> is the name of a constant that can optionally be assigned the value of <value>. These are also called enumeration constants.

<value> must be an integer. If <value> is missing, it is assumed to be:

<prev> + 1

where <prev> is the value of the previous integer constant in the list. For the first integer constant in the list, the default value is 0.

<var_list> is an optional variable list that assigns variables to the enum type.

Description

Use the enum keyword to define a set of constants of type int, called an enumeration data type.

An enumeration data type provides mnemonic identifiers for a set of integer values. Borland C++ stores enumerators in a single byte if you uncheck Treat Enums As Ints (O|C|Code Generation) or use the -b flag.

Enums are interpreted always ints if the range of values permits, but if they are not ints the value gets promoted to an int in expressions. Depending on the values of the enumerators, identifiers in an enumerator list are implicitly of type signed char, unsigned char, or int.

In C, an enumerated variable can be assigned any value of type int--no type checking beyond that is enforced. In C++, an enumerated variable can be assigned only one of its enumerators.

In C++, lets you omit the enum keyword if <tag_type> is not the name of anything else in the same scope.  You can also omit <tag_type> if no further variables of this enum type are required.

In the absense of a <value> the first enumerator is assigned the value of zero. Any subsequent names without initializers will then increase by one. <value> can be any expression yielding a positive or negative integer value (after possible integer promotions). These values are usually unique, but duplicates are legal.

Enumeration tags share the same name space as structure and union tags. Enumerators share the same name space as ordinary variable identifiers.

In C++, enumerators declared within a class are in the scope of that class.


Examples

enum days { sun, mon, tues, wed, thur, fri, sat } anyday;

establishes a unique integral type, enum days, a variable anyday of this type, and a set of enumerators (sun, mon,...) with constant integer values.

enum modes { LASTMODE = -1, BW40=0, C40, BW80, C80, MONO = 7 };

/*

   "modes" is the type tag.

   "LASTMODE", "BW40", "C40", etc. are the constant names.

   The value of C40 is 1 (BW40 + 1); BW80 = 2 (C40 + 1), etc.

*/


_ _except

See Also	Keywords

Syntax

_ _except (expression) compound-statement

Description

The _ _except keyword specifies the action that should be taken when the exception specified by expression has been raised.


See Also

C-Based Structured Exceptions

_ _finally

_ _try (keyword)

try (keyword)


_export and _ _export

See Also	Keywords

Form 1

class _export <class name>

Form 2

return_type _export <function name>

Form 3

data_type _export <data name>

Description

These modifiers are used to export classes, functions, and data.

The linker enters functions flagged with _export or __export  into an export table for the module.

Using _export or __export eliminates the need for an EXPORTS section in your module definition file.

Note:	Exported functions must be declared as far. You can use the FAR type, defined in WINDOWS.H.

Functions that are not flagged with _export or __export receive abbreviated prolog and epilog code, resulting in a smaller object file and slightly faster execution.

Note:	If you use _export or __export to export a function, that function will be exported by name rather than by ordinal (ordinal is usually more efficient).

If you want to change various attributes from the default, you'll need a module definition file.


See Also

Prologs, Epilogs, and Exports: A Summary

Compiler Options and the _export Keyword

Smart Callbacks and the _export Keyword

Exportable Functions in DLLs

Using _export with C++ Classes


Prologs, Epilogs, and Exports: A Summary

See Also	Keywords

Use prologs and epilogs when exporting functions. They ensure that the correct data segment is active during callback functions and mark near and far stack frames for Windows stack-crawling.

To export a function:

1.	The compiler must create the correct prolog and epilog for the function: the function is then known as "exportable".

2.	The linker must create an entry for every export function in the header section of the executable.

This allows the correct data segment to be bound to the function at run time.

If a function is flagged with the _export keyword and you use any of the Windows compiler options, the function compiles as exportable and links it as an export.

If a function is not flagged with the _export keyword, the compiler will take one of the following actions:

If you compile with either of the All Functions Exportable IDE options, the function compile as exportable.

If the function is listed in the EXPORTS section of the module definition file, the function links as an export.

If you compile with either of the Explicit Functions Exported IDE options, the function is exportable.

Note:	Including a function that has not been compiled as an export, in the EXPORTS section of the module definition file exports the function but since the prolog is wrong the program will run incorrectly.


See Also

Compiler Options and the _export Keyword


Compiler Options and the _export Keyword
Compiler Options and the _ _export Keyword

See Also	Keywords	DPMI (Add On)

This table summarizes the effect of the combination of various Windows options and the _ _export keyword:

The·compiler option is: *	-W·or -WD	-WE·or -WDE	-WE·or -WDE	-W·or -WD	-W·or -WD	-WE·or -WDE	-W·or -WD	-WE·or -WDE
Function·flagged with·_export?	Yes	Yes	Yes	Yes	No	No	No	No
Function·listed in·EXPORTS?	Yes	Yes	No	No	Yes	Yes	No	No
Is·function exportable?	Yes	Yes	Yes	Yes	Yes	No	Yes	No
Will·function·be exported?	Yes	Yes	Yes	Yes	Yes	Yes **	No ***	No
*	Or the 32-bit console mode application equivalents.

**	The function will be exported in some sense, but because the prolog and epilog will not be corret, the function will not work as expected.

***	This combination also makes little sense. It is inefficient to compile all functions as exportable if you do not actuall export some of them.


See Also

_export

smart callbacks


Smart Callbacks and the _export Keyword

See Also	Keywords

If you use the Smart Callbacks IDE option at compile time, callback functions do not need to be listed in the EXPORTS statement or flagged with the _export keyword.

Functions compile them so that they are callback functions.


Exportable Functions in DLLs

There are two ways to compile a function f1( ) in a DLL as exportable and then export it.

Compile the DLL with all functions exportable (with the Windows DLL All Functions Exportable option in the IDE) and list f1( ) in the EXPORTS section of the module definition file, or

Flag the function f1( ) with the _export keyword.


Using _export with C++ Classes

See Also	Keywords

Whenever you declare a class as _export, the compiler treats it as huge (with 32-bit pointers), and exports all of its non-inline member functions and static data members.

You cannot declare a class as _export and as faror huge (_export implies huge, which implies far).

If you declare the class in an include file that is included in both the DLL source files and the source files of the application that use the DLL, declare the class

as _export when compiling the DLL

as huge when compiling the application

To do this, use the __DLL__ macro, which the compiler defines when it's building a DLL.

Note:	In the mangled name, the compiler encodes the information that a given class member is a member of a huge class. This ensures that the linker will catch any mismatches when a program is using huge and non-huge classes.


extern

See Also	Example	Keywords

Syntax

extern <data definition> ;

[extern] <function prototype> ;

Description

Use the extern modifier to indicate that the actual storage and initial value of a variable, or body of a function, is defined in a separate source code module. Functions declared with extern are visible throughout all source files in a program, unless you redefine the function as static.

The keyword extern is optional for a function prototype.

Use extern "c" to prevent function names from being mangled in C++ programs.


Examples

extern int _fmode;

extern void Factorial(int n);

extern "c" void cfunc(int);


See Also

Error message:  Unknown language, must be C or C++

Error message:  extern variable cannot be initialized

Error message:  Only one of a set of overloaded functions can be "C"

Error message:  Function defined inline after use as extern

Error message:  Linkage specification not allowed

Error message:  Undefined symbol 'symbol' in module 'module'


far, _far, and _ _far

Example	Keywords

Syntax

<type> far <pointer definition> ;

<type> far <function definition>

<type> _far <pointer definition> ;

<type> _far <function definition>

<type> __far <pointer definition> ;

<type> __far <function definition>

Description

Use the far, _far and __far modifiers to generate function code for calls and returns using variables that are outside of the data segment.

The first version of far, _far, or __far declares a pointer to be two words with a range of 1 megabyte. Use far when compiling small or compact models to force pointers to be far.


Examples

char far *s;

void * far * p;

int far my_func() {}


__far16 and _far16

See Also	Examples	Keywords

Syntax

_far16 function-declaration;

_far16 variable-name;

__far16 function-declaration;

__far16 variable-name;

Description

Use the _far16 and _ _far16 modifiers to call functions or reference data in a 16-bit DLL. When a 32-bit program references a function or data type for a 16-bit architecture, any use of the segmented architecture must be resolved in terms of the 32-bit flat model.

Indicate references to the 16-bit segmented architecture with the modifier far preceding a function or variable name in code generated by a 16-bit compiler. By substituting the keywords _far16 and  _ _far16 in place of far, the pointer adjusts to the flat memory model by the 32-bit compiler.

The _far and _ _far16 modifiers can also be a function modifier; that is, it can modify functions and function pointers as well as data pointers. You can combine the _far16 and _ _far16 function modifiers only with _ _cdecl or _ _pascal.

A call to a function that uses 16-bit data types requires some adjustment if the data is an integer type. Such an adjustment is made by changing the function prototype specification of parameters.


See Also

32-bit data types


Examples

16-bit Example

32-bit Example


16-bit far Example

/* A 16-bit declaration. */

char far* func(char far* param);

/* Data declared in a 16-bit declaration. */

int func(int, unsigned);

/* Data declared in a 16-bit declaration. */

extern struct s {

  char far* ptr;

  int i;

  }

struct s* sptr;  /* sptr is a pointer to struct. */


32-bit far Example

short __far16 func(short, unsigned short);

// Data declared in a 32-bit declaration.

char __far16 * __far16 func(char __far16* param);

// Data declared in a 32-bit declaration.

extern struct s {

  char __far16* ptr;

  short i;

  }

struct s __far16* sptr;  /* sptr is a pointer to struct. */


_fastcall and _ _fastcall

See Also	Keywords

Syntax

_fastcall function-name

__fastcall function-name

Description

Use the _fastcall or __fastcall modifiers to declare functions that expect parameters to be passed in registers.

The compiler treats this calling convention as a new language specifier, along the lines of _cdecl and _pascal

Functions declared using _cdecl or _pascal cannot also have the _fastcall or __fastcall modifiers because they use the stack to pass parameters. Likewise, the _fastcall or __fastcall modifiers cannot be used together with _export or _loadds.

The compiler generates a warning if you mix functions of these types or if you use the _fastcall or __fastcall modifiers in a dangerous situation. You can, however, use functions that use the _fastcall or __fastcall conventions in overlaid modules (for example, with modules that will use VROOMM).

The compiler prefixes the _fastcall function name with an at-sign ("@"). This prefix applies to both unmangled C function names and to mangled C++ function names.


See Also

Parameter Types and Possible Registers Used


Parameter Types and Possible Registers Used

The compiler uses the following rules when deciding which parameters are to be passed in registers.

Parameter Type	Registers

char (signed and unsigned)	AL, DL, BL

integer (signed and unsigned)	AX, DX, BX

long (signed and unsigned)	DX:AX

near pointer	AX, DX, BX

Only three parameters can be passed in registers to any one function.

Do not assume the assignment of registers will reflect the ordering of the parameters to a function. Far pointer, union, structure, and floating point (float, double, and long) parameters are pushed on the stack.


_ _finally

See Also	Keywords

Syntax

_ _finally compound-statement

Description

The _ _finally keyword specifies actions that should be taken regardless of how the flow within the preceding _ _try exits.

The _ _finally keyword is supported only in C programs.


See Also

C-Based Structured Exceptions


float

See Also	Keywords

Syntax

float <identifier>

Description

Use the float type specifier to define an identifier to be a floating point data type.

Type	Length	Range

float	32 bits 	3.4 * (10**-38) to 3.4 * (10**+38)

The C++ IDE automatically links the floating-point math package into you program if you use floating point values or operators.


See Also

double

Standard Arithmetic Conversions


for

Example	Keywords

Syntax

for ( [<initialization>] ; [<condition>] ; [<increment>] )  <statement>

Description

The for statement implements a for loop.

<statement> is executed repeatedly UNTIL the value of <condition> is FALSE.

Before the first iteration of the loop, <initialization> initializes variables for the loop.

After each iteration of the loop, <increments> increments a loop counter. (Consequently, j++ is functionally the same as ++j.)

In C++, <initialization> can be an expression or a declaration.

The scope of any identifier declared within the for loop extends to the end of the control statement only.

All the expressions are optional. If <condition> is left out, it is assumed to be always true.


Examples

for (i=0; i<100; i++)

   sum += x[i];

for (i=0, t=string; i < 40 && *t; i++, t++)

   putch(*t);

putch('\n');


friend

Example	Keywords

Syntax

friend <identifier>;

Description

Use friend to declare a function or class with full access rights to the private and protected members of an outside class, without being a member of that class.

In all other respects, the friend is a normal function in terms of scope, declarations, and definitions.


Example

class stars {

   friend galaxy;

   int magnitude;

   int starfunc(void);

};

class galaxy {

   long int number_of_stars;

   void stars_magnitude(stars&);

   void stars_func(stars*);

}


goto

Example	Keywords

Syntax

goto <identifier> ;

Description

Use the goto statement to transfer control to the location of a local label specified by <identifier>.

Labels are always terminated by a colon.


Example

Again:       /* this is the label */

;

.

.

.

goto Again;


huge
huge, _huge, _ _huge

See Also	Keywords

Syntax

<type> huge <pointer-definition> ;

<type> _huge <pointer-definition> ;

<type> __huge <pointer-definition> ;

Description

The huge modifiers are similar to the far modifier except for two additional features.

Its segment is normalized during pointer arithmetic so that pointer comparisons are accurate.

Huge pointers can be incremented without suffering from segment wraparound.


See Also

far


if

Example	Keywords

Syntax

if ( <condition> )  <statement1>;

if ( <condition> )  <statement1>;

   else  <statement2>;

Description

Use if to implement a conditional statement.

When <condition> evaluates to be nonzero, <statement1> executes.

If <condition> is false (0), <statement2> executes.

Else is optional, but no statements can come between an if statement and an else.

The #if and #else preprocessor statements (directives) look similar to the if and else statements, but have very different effects. They control which source file lines are compiled and which are ignored.


Examples

if (count < 50) count++;

if (x < y)

  z = x;

else

  z = y;


_import, _ _import

Keywords

Form 1

class _import <class name>

class __import <class name>

Form 2

return_type _import <function name> //32-bit only

return_type __import <function name> //32-bit only

Form 3

data_type _import <data name> //32-bit only

data_type __import <data name> //32-bit only

Description

This keyword can be used as a class modifier for 16-bit programs; and as a class, function, or data modifier in 32-bit programs. If you're importing classes that are declared with the modifier _ _huge, you must change the modifier to the keyword _ _import. The _ _huge modifier merely causes far addressing of the virtual tables (the same effect as the -Vf compiler option). The _ _import modifier makes all function and static addresses default to far.


inline

Example	Keywords

Syntax

inline <datatype> <class>_<function> (<parameters>) { <statements>; }

Description

Use the inline keyword to declare or define C++ inline functions.

Inline functions are best reserved for small, frequently used functions.


Example

inline char* cat_func(void) { return char*; }


int

See Also	Keywords

Syntax

[signed|unsigned] int <identifier> ;

Description

Use the int type specifier to define an integer data type.

Variables of type int are one word in length.

They can be signed (default) or unsigned.


See Also

data types (16-bit)

data types (32-bit)

double

Standard Arithmetic Conversions


interrupt, _interrupt, _ _interrupt

Example	Keywords

Syntax

interrupt <function-definition> ;

_interrupt <function-definition> ;

__interrupt <function-definition> ;

Description

Use the interrupt function modifier to define a function as an interrupt handler.

Interrupt functions compile with extra function entry and exit code so that all CPU registers are saved. The function uses an IRET instruction to return, so that the function can be used as harware and software interrupts.

Declare interrupt functions to be of type void and can be declared in any memory model.


Example

void interrupt myhandler()

{

...

}


_loadds and _ _loadds

Keywords

Syntax

_loadds <function-name>

__loadds <function-name>

Description

Use _loadds and __loads to indicate that a function should set the DS register, just as a huge function does, but does not imply _far16 calls.

These keywords are useful for writing low-level interface routines, such as mouse support routines.


long

See Also	Keywords

Syntax

long [int] <identifier> ;

[long] double <identifier> ;

Description

When used to modify an int, it doubles the number of bytes available to store the integer value.

When used to modify a double, it defines a floating point data type with 80 bits of precision instead of 64.

The Borland C++ IDE will link in the floating-point math package if you use floating point values or operators anywhere in your program.


See Also

data types (16-bit)

data types (32-bit)

float

Standard Arithmetic Conversions


near, _near, _ _near

Example	Keywords

Syntax

<type> near <pointer definition> ;

<type> near <function definition>

<type> _near <pointer definition> ;

<type> _near <function definition>

<type> __near <pointer definition> ;

<type> __near <function definition>

Description

Use near and _near type modifiers to force pointers to be near and to generate function code for a near call and a near return.

The first version of near and _near declares a pointer to be one word with a range of 64K.

Use this type modifier when compiling in the medium, large, or huge memory models to force pointers to be near.

When either near or _near is used with a function declaration, the compiler generates function code for a near call and a near return.


Example

char near *s;

int (near *ip)[10];

int near my_func() {}


new

See Also	Example	Operators

Syntax

<::> new <new-args> type-name <(initializer)>

<::> new <new-args> (type-name) <(initializer)>

Description

The new operator offer dynamic storage allocation, similar but superior to the standard library function malloc. The new operator must always be supplied with a data type in place of type-name. Items surrounded by angle brackets are optional. The optional arguments can be as follows:

:: operator, invokes the global version of new.

new-args can be used to supply additional arguments to new. You can use this syntax only if you have have an overloaded version of new that matches the optional arguments.

initializer, if present is used to initialize the allocation.

A request for non-array allocation uses the appropriate operator new() function. Any request for array allocation will call the appropriate operator new[]() function. Selection of operator is done as follows:

By default, operator new[]() calls operator new()

If a class Type has an overloaded version of operator new[](), arrays of Type will be allocated using Type::operator new[]()

If a class Type has an overloaded version of new, and no overloaded version of the array allocator operator new[](), arrays of Type will be allocated using Type::operator new()

Memory for a non-array object of Type is allocated using Type::operator new()

If none of the above cases apply, the global ::operator new() is used

Note:	Arrays of classes require the default constructor.

new tries to create an object of type Type by allocating (if possible) sizeof(Type) bytes in free store (also called the heap). new calculates the size of Type without the need for an explicit sizeof operator. Further, the pointer returned is of the correct type, "pointer to Type," without the need for explicit casting. The storage duration of the new object is from the point of creation until the operator delete destroys it by deallocating its memory, or until the end of the program.

If successful, new returns a pointer to the new object. By default, an allocation failure (such as insufficient or fragmented heap memory) results in the predefined exception xalloc being thrown. Your program should always be prepared to catch the xalloc exception before trying to access the new object (unless you use a new-handler).

A request for allocation of 0 bytes returns a non-null pointer. Repeated requests for zero-size allocations return distinct, non-null pointers.

Handling Errors for the new Operator

You can define a function to be called if the new operator fails. To tell the new operator about the new-handler function, use set_new_handler and supply a pointer to the new-handler. If you want new to return null on failure, you must use set_new_handler(0).


See Also

delete

The new Operator with Arrays

The ::operator new

Overloading the operator new


The Operator new With Arrays

Example

If Type is an array, the pointer returned by operator new[]() points to the first element of the array. When creating multidimensional arrays with new, all array sizes must be supplied (although the leftmost dimension doesn't have to be a compile-time constant):

mat_ptr = new int[3][10][12];    // OK

mat_ptr = new int[n][10][12];    // OK

mat_ptr = new int[3][][12];      // illegal

mat_ptr = new int[][10][12];     // illegal

Although the first array dimension can be a variable, all following dimensions must be constants.


// Example of the new and delete Operators

// ALLOCATE A TWO-DIMENSIONAL SPACE, INITIALIZE, AND DELETE IT.

#include <except.h>

#include <iostream.h>

void display(long double **);

void de_allocate(long double **);

int m = 3;                               // THE NUMBER OF ROWS.

int n = 5;                               // THE NUMBER OF COLUMNS.

int main(void) {

   long double **data;

   try {                                 // TEST FOR EXCEPTIONS.

      data = new long double*[m];        // STEP 1: SET UP THE ROWS.

      for (int j = 0; j < m; j++)

          data[j] = new long double[n];  // STEP 2: SET UP THE COLUMNS

      }

   catch (xalloc) {  // ENTER THIS BLOCK ONLY IF xalloc IS THROWN.

      // YOU COULD REQUEST OTHER ACTIONS BEFORE TERMINATING

      cout << "Could not allocate. Bye ...";

      exit(-1);

      }

   for (int i = 0; i < m; i++)

      for (int j = 0; j < n; j++)

          data[i][j] = i + j;            // ARBITRARY INITIALIZATION

   display(data);

   de_allocate(data);

   return 0;

   }

void display(long double **data) {

   for (int i = 0; i < m; i++) {

        for (int j = 0; j < n; j++)

             cout << data[i][j] << " ";

       cout << "\n" << endl;

       }

   }

void de_allocate(long double **data) {

   for (int i = 0; i < m;  i++)

       delete[] data[i];                 // STEP 1: DELETE THE COLUMNS

   delete[] data;                        // STEP 2: DELETE THE ROWS

   }


::operator new

See Also

By default, if there is no overloaded version of new, a request for dynamic memory allocation always uses the global version of new, ::operator new(). A request for array allocation calls ::operator new[](). With class objects of type name, a specific operator called name::operator new() or name::operator new[]() can be defined. new applied to class name objects invokes the appropriate name::operator new if it is present; otherwise, the global ::operator new is used.

Only the operator new() function will accept an optional initializer. The array allocator version, operator new[](), will not accept initializers. In the absence of explicit initializers, the object created by new contains unpredictable data (garbage). The objects allocated by new, other than arrays, can be initialized with a suitable expression between parentheses:

int_ptr = new int(3);

Arrays of classes with constructors are initialized with the default constructor. The user-defined new operator with customized initialization plays a key role in C++ constructors for class-type objects.


See Also

Overloading operator new


Overloading the Operator new

Example

The global ::operator new() and ::operator new[]() can be overloaded. Each overloaded instance must have a unique signature. Therefore, multiple instances of a global allocation operator can coexist in a single program.

Class-specific new operators can also be overloaded. The operator new can be implemented to provide alternative free storage (heap) memory-management routines, or implemented to accept additional arguments. A user-defined operator new must return a void* and must have a size_t as its first argument. To overload the new operators, use the following prototypes.

void * operator new(size_t Type_size);    // For Non-array

void * operator new[](size_t Type_size);  // For arrays

The Borland C++ compiler provides Type_size to the new operator. Any data type may be substitued for Type except function names (although a pointer to function is permitted), class declarations, enumeration declarations, const, volatile.


Example of Overloading the new and delete Operators

#include <stdlib.h>

class X {

   .

   .

   .

public:

   void* operator new(size_t size) { return newalloc(size);}

   void operator delete(void* p) { newfree(p); }

   X() { /* initialize here */ }

   X(char ch) { /* and here */ }

   ~X() { /* clean up here */ }

   .

   .

   .

};

The size argument gives the size of the object being created, and newalloc and newfree are user-supplied memory allocation and deallocation functions. Constructor and destructor calls for objects of class X (or objects of classes derived from X that do not have their own overloaded operators new and delete) will invoke the matching user-defined X::operator new() and X::operator delete(), respectively. (Destructors will be called only if you use the -xd compiler option and an exception is thrown.)

The X::operator new(), X::operator new[](), X::operator delete() and X::operator delete[]() operator functions are static members of X whether explicitly declared as static or not, so they cannot be virtual functions.

The standard, predefined (global) new(), new[](), delete(), and delete[]() operators can still be used within the scope of X, either explicitly with the global scope operator (::operator new(), ::operator new[](), ::operator delete(), and ::operator delete[]()), or implicitly when creating and destroying non-X or non-X-derived class objects. For example, you could use the standard new and delete when defining the overloaded versions:

void* X::operator new(size_t s)

{

   void* ptr = new char[s]; // standard new called

     .

     .

     .

   return ptr;

}

void X::operator delete(void* ptr)

{

     .

     .

     .

   delete (void*) ptr;     // standard delete called

}

The reason for the size argument is that classes derived from X inherit the X::operator new() and X::operator new[](). The size of a derived class object may well differ from that of the base class.


operator

See Also	Example	Keywords

Syntax

operator <operator symbol>( <parameters> )

{

   <statements>;

}

Description

Use the operator keyword to define a new (overloaded) action of the given operator. When the operator is overloaded as a member function, only one argument is allowed, as *this is implicitly the first argument.

When you overload an operator as a friend, you can specify two arguments.


Example

new_complex operator +(complex c1, complex c2)

{

   return complex(c1.real + c2.real, c1.imag + c2.imag);

}


See Also

class

overloading operators


pascal, _pascal, and _ _pascal

Example	Keywords

Syntax

pascal <data-definition/function-definition> ;

_pascal <data-definition/function-definition> ;

__pascal <data-definition/function-definition> ;

Description

Use the pascal, _pascal, and __pascal keywords to declare a variable or a function using a Pascal-style naming convention (the name is in uppercase).

In addition, "pascal" declares Pascal-style parameter-passing conventions when applied to a function header (first parameter pushed first; the called function cleans up the stack).

In C++ programs, functions declared with the pascal modifer will still be mangled.


Examples

int pascal FileCount;

far pascal long ThisFunc(int x, char *s);


private

See Also	Keywords

Syntax

private: <declarations>

Description

A private member can be accessed only by member functions and friends of the class in which it is declared.

Class members are private by default.

You can override the default struct access with private or protected but you cannot override the default union access.

Friend declarations are not affected by these access specifiers.


See Also

class

friend

protected

public


protected

See Also	Keywords

Syntax

protected: <declarations>

Description

A protected members can be accessed by member functions and friends of the class in which it was declared, and by classes derived from the declared class.

You can override the default struct access with private or protected but you cannot override the default union access.

Friend declarations are not affected by these access specifiers.


See Also

class

friend

private

public


public

See Also	Keywords

Syntax

public: <declarations>

Description

A public member can be accessed by any function.

Members of a struct or union are public by default.

You can override the default struct access with private or protected but you cannot override the default union access.

Friend declarations are not affected by these access specifiers.


See Also

class

friend

private

protected

struct

union


register

Example	Keywords

Syntax

register <data definition> ;

Description

Use the register storage class specifier to store the variable being declared in a CPU register (if possible), to optimize access and reduce code.

Items declared with the register have a global lifetime.


Example

register int i;


return

Example	Keywords

Syntax

return [ <expression> ] ;

Description

Use the return statement to exit from the current function back to the calling routine, optionally returning a value.


Example

double sqr(double x)

{

  return (x*x);

}


_saveregs, _ _saveregs

See Also	Keywords

Syntax

_saveregs <function-name>;

__saveregs <function-name>;

Description

The _saveregs modifier causes the function to preserve all register values and restore them before returning (except for explicit return values passed in registers such as AX or DX). _saveregs is not available in flat mode.

Use this keyword with functions; it is useful for writing low-level interface routines, such as mouse support routines.


See Also

_loadds


_seg, _ _seg

Example	Keywords

Syntax

<datatype> _seg *<identifier> ;

<datatype> __seg *<identifier> ;

Description

Use _seg in 16-bit segment pointer type declarators. _seg is not available in flat mode.

Any indirection through <identifier> has an assumed offset of 0. In arithmetic involving segment pointers they are treated like pointers except for the following restictions.

1.	You cannot use the ++, --, +=, or -= operators with segment pointers.

2.	You cannot subtract one segment pointer from another.

3.	If you add a near pointer to a segment pointer, the operation creates a far pointer result by using the segment from the segment pointer and the offset from the near pointer.

Therefore, the two pointers must point to the same type, or one must be a pointer to void.

There is no multiplication of the offset, regardless of the type pointed to.

4.	When a segment pointer is used in an indirection expression, it also implicitly converts to a far pointer.

5.	If you add or subtract an integer operand to or from a segment pointer, the result is a far pointer. The segment is taken from the segment pointer; the offset is calculated by multiplying the size of the object pointed to by the integer operand.

6.	Segment pointers can be assigned, initialized, passed into and out of functions, and compared.


Example

int _seg *name;


signed

See Also	Example	Keywords

Syntax

signed <type> <variable> ;

Description

Use the signed type modifier when the variable value can be either positive or negative. The signed modifier can be applied to base types int, char, long and short.

When the base type is omitted from a declaration, int is assumed.


Example

signed   int       i;    /* signed is default        */

signed             i;    /* same as "signed int i;"  */

unsigned long int  l;    /* int OK, not needed       */

signed   char      ch;   /* unsigned is default      */


See Also

char

int

long

short

unsigned

Standard Arithmetic Conversions


short

See Also	Example	Keywords

Syntax

short int <variable> ;

Description

Use the short type modifier when you want a variable smaller than an int. This modifier can be applied to the base type int.

When the base type is omitted from a declaration, int is assumed.


Examples

short int i;

short     i;    /* same as "short int i;" */


See Also

long

signed

Standard Arithmetic Conversions

unsigned


sizeof

See Also	Example	Operators

Syntax

sizeof <expression>

sizeof ( <type> )

Description

Use the sizeof operator to return the size, in bytes, of the given expression or type (as type size_t ).


Example

memset(buff, 0, sizeof(buff));

nitems = sizeof(table) / sizeof(table[0]);


See Also

Operator Precedence


static

Example	Keywords

Syntax

static <data definition> ;

static <function definition> ;

Description

Use the static storage class specifier with a local variable to preserve the last value between successive calls to that function. A static variable acts like a local variable but has the lifetime of an external variable.


Examples

static int i;

static void printnewline(void) {}


_stdcall and __stdcall

Keywords

Syntax

__stdcall <function-name>

_stdcall <function-name>

Description

The _stdcall and __stdcall keywords force the compiler to generate function calls using the Standard calling convention. The resulting function calls are smaller and faster. Functions must pass the correct number and type of arguments; this is unlike normal C use, which permits a variable number of function arguments.


struct

See Also	Example	Keywords

Syntax

struct [<struct type name>] {

  [<type> <variable-name[, variable-name, ...]>] ;

    .

    .

    .

} [<structure variables>] ;

Description

Use structs to group variables into a single record.

<struct type name>	An optional tag name that refers to the structure type

<structure variables>	The data definitions, also optional.

Though both <struct type name> and <structure variables> are optional, one of the two must appear.

You define elements in the record by naming a <type>, followed by one or more <variable-name> (separated by commas).

Separate different variable types by a semicolon.

To access elements in a structure, use a record selector (.).

To declare additional variables of the same type, use the keyword struct followed by the <struct type name>, followed by the variable names.


Example

struct my_struct {

  char name[80], phone_number[80];

  int  age, height;

} my_friend;

strcpy(my_friend.name,"Mr. Wizard");   /* accessing an element */

struct my_struct my_friends[100];   /* declaring additional variables */


See Also

bit fields

class

direct member selector

public

Precedence of Operators

union


switch

See Also	Example	Keywords

Syntax

switch ( <switch variable> ) {

  case <constant expression> : <statement>; [break;]

    .

    .

    .

  default : <statement>;

}

Description

Use the switch statement to pass control to a case which matches the <switch variable>. At which point the statements following the matching case evaluate.

If no case satisfies the condition the default case evaluates.

To avoid evaluating any other cases and reliquish control from the switch, terminate each case with break;.


See Also

break

case

default


Example

switch (operand) {

  case MULTIPLY:   x *= y; break;

  case DIVIDE:     x /= y; break;

  case ADD:        x += y; break;

  case SUBTRACT:   x -= y; break;

  case INCREMENT2: x++;            /* execution continues to next case */

  case INCREMENT1: x++;    break;

  case EXPONENT:

  case ROOT:

  case MOD:       printf("Not done\n"); break;

  default:        printf("Bug!\n");

  exit(1);

}


template

See Also	Keywords

Syntax

template < template-argument-list > declaration

Description

Use templates, (also called generics or parameterized types) to construct a family of related functions or classes.


See Also

Class Templates

Function Templates


this

See Also	Keywords

Syntax

class X {

int a;

public:

X (int b) {this -> a = b;}

Description

In nonstatic member functions, the keyword "this" is a pointer to the object for which the function is called. All calls to nonstatic member functions pass "this" as a hidden argument.

The keyword "this" is a local variable available in the body of any nonstatic member function. Use it implicitly within the function for member references. It does not need to be declared and it is rarely referred to explicitly in a function definition.

For example, in the call x.func(y), where y is a member of X, the keyword "this" is set to &x and y is set to this->y, which is equivalent to x.y.

Static member functions do not have a "this" pointer because they are called with no particular object in mind.  Thus, a static member function cannot access nonstatic members without explicitly specifying an object with . or ->.


See Also

.

->

class

new


_ _thread

Keywords

Syntax

Type _ _thread var_name;

For example,

   int _ _thread x;

declares an integer type that will be global but private to each thread in the program in which the statement appears.

Description

The keyword _ _thread is used in multithread programs to preserve a unique copy of global and static class variables. Each program thread maintains a private copy of a _ _thread variable for each threaded process.

The _ _thread modifier can be used with global (file-scope) and static variables. The modifier cannot be used with pointers or functions. (However, you can have pointers to _ _thread objects.) A program element that requires run-time initialization or run-time finalization cannot be declared to be a __thread type. The following declarations require run-time initialization and are therefore illegal:

   int f();

   int _ _thread x = f();  // Illegal

Instantiation of a class with a user-defined constructor or destructor requires run-time initialization and is therefore illegal:

   class X {

      X();

      ~X();

   }

   X _ _thread myclass;   // Illegal


throw

See Also	Keywords

Syntax

throw assignment-expression

Description

When an exception occurs, the throw expression initializes a temporary object of the type T (to match the type of argument arg) used in throw(T arg). Other copies can be generated as required by the compiler. Consequently, it can be useful to define a copy constructor for the exception object.


See Also

catch (keyword)

C++ Exception Handling

try (keyword)


_ _try

See Also	Keywords

Syntax

_ _try compound-statement handler-list

_ _try compound-statement termination-statement

Description

The _ _try keyword is supported only in C programs. Use try in C++ programs.

A block of code in which an exception can occur must be prefixed by the keyword __try. Following the try keyword is a block of code enclosed by braces. This indicates that the program is prepared to test for the existence of exceptions. If an exception occurs, the normal program flow is interrupted. The program begins a search for a handler that matches the exception. If the exception is generated in a C module, it is possible to handle the structured exception in either a C module or a C++ module.

If a  handler can be found for the generated structured exception, the following actions can be taken:

Execute the actions specified by the handler

Ignore the generated exception and resume program execution

Continue the search for some other handler (regenerate the exception)

If no handler is found, the program will call the terminate function. If no exceptions are thrown, the program executes in the normal fashion.


See Also

C-Based Structured Exceptions

__except

catch (keyword)

__finally

throw (keyword)


_ _try example
// try example

// In PROG.C

void func(void) {

   // generate an exception

   RaiseException( // specify your arguments );

}

// In CALLER.CPP

// How to test for C++ or C-based exceptions.

#include <excpt.h>

#include <iostream.h>

int main(void) {

   try

   {            // test for C++ exceptions

      try

      {         // test for C-based structured exceptions

         func();

      }

      __except( /* filter-expression */ )

      {

      cout << "A structured exception was generated.";

      /* specify actions to take for this structured exception */

      return -1;

      }

      return 0;

   }

   catch ( ... )

   {

   // handler for any C++ exception

   cout << "A C++ exception was thrown.";

   return 1;

   }

}


try

See Also	Example	Keywords

Syntax

try compound-statement handler-list

Description

The try keyword is supported only in C++ programs. Use _ _try in C programs.

A block of code in which an exception can occur must be prefixed by the keyword try. Following the try keyword is a block of code enclosed by braces. This indicates that the program is prepared to test for the existence of exceptions. If an exception occurs, the program flow is interrupted. The sequence of steps taken is as follows:

The program searches for a matching handler

If a handler is found, the stack is unwound to that point

Program control is tranferred to the handler

If no handler is found, the program will call the terminate function. If no exceptions are thrown, the program executes in the normal fashion.


See Also

catch (keyword)

C++ Exception Handling

throw (keyword)


typedef

Example	Keywords

Syntax

typedef <type definition> <identifier> ;

Description

Use the typedef keyword to assign the symbol name <identifier> to the data type definition <type definition>.


Examples

typedef unsigned char byte;

typedef char str40[41];

typedef struct {

     double re, im;

   } complex;


typeid

See Also	Example	Keywords

Syntax

typeid( expression )

typeid( type-name )

Description

You can use typeid to get run-time identification of types and expressions. A call to typeid returns a reference to an object of type const typeinfo. The returned object represents the type of the typeid operand.

If the typeid operand is a dereferenced pointer or a reference to a polymorphic type, typeid returns the dynamic type of the actual object pointed or referred to. If the operand is non-polymorphic, typeid returns an object that represents the static type.

You can use the typeid operator with fundamental data types as well as user-defined types.

If the typeid operand is a dereferenced NULL pointer, the Bad_typeid exception is thrown.


See Also

Bad_typeid class

_ _rtti


typeid example
// typeid example

typeinfo::before(), and

typeinfo::name().

#include <iostream.h>

#include <string.h>

#include <typeinfo.h>

class A { };

class B : A { };

char *true  = "true";

char *false = "false";

void main() {

   char C;

   float X;

   if (typeid( C ) == typeid( X ))

      cout << "C and X are the same type." << endl;

   else cout << "C and X are NOT the same type." << endl;

   cout << typeid(int).name();

   cout << " before " << typeid(double).name() << ": " <<

        (typeid(int).before(typeid(double)) ? true : false) << endl;

   cout << typeid(double).name();

   cout << " before " << typeid(int).name() << ": " <<

        (typeid(double).before(typeid(int)) ? true : false) << endl;

   cout << typeid(A).name();

   cout << " before " << typeid(B).name() << ": " <<

        (typeid(A).before(typeid(B)) ? true : false) << endl;

   }

Program Output

C and X are NOT the same type.

int before double: false

double before int: true

A before B: true


union

See Also	Example	Keywords

Syntax

union [<union type name>] {

  <type> <variable names> ;

  ...

} [<union variables>] ;

Description

Use unions to define variables that share storage space.

The compiler allocates enough storage in a_number to accommodate the largest element in the union.

Unlike a struct, the variables a_number.i and a_number.l occupy the same location in memory. Thus, writing into one overwrites the other.

Use the record selector (.) to access elements of a union .


Example

union int_or_long {

  int     i;

  long    l;

} a_number;


See Also

bit fields

class

public

record selector

struct


unsigned

See Also	Example	Keywords

Syntax

unsigned <type> <variable> ;

Description

Use the unsigned type modifier when variable values will always be positive. The unsigned modifer can be applied to base types int, char, long and short.

When the base type is omitted from a declaration, int is assumed.


Examples

unsigned int       i;

unsigned           i;    /* same as "unsigned int i;"    */

unsigned long int  l;    /* int OK, not needed           */

unsigned char      ch;   /* unsigned is default for char */


See Also

char

int

long

short

signed

Standard Arithmetic Conversions


virtual

See Also	Keywords

Syntax

virtual class-name

virtual function-name

Description

Use the virtual keyword to allow derived classes to provide different versions of a base class function. Once you declare a function as virtual, you can redefine it in any derived class, even if the number and type of arguments are the same.

The redefined function overrided the base class function.


See Also

virtual functions

virtual classes


void

Example	Keywords

Syntax

void identifier

Description

Use the void keyword as a function return type if the function does not return a value.

void hello(char *name)

{

  printf("Hello, %s.",name);

}

Use void as a function heading if the function does not take any parameters.

int init(void)

{

  return 1;

}

Void Pointers

Pointers can also be declared as void.

Void pointers cannot be dereferenced without explicit casting because the compiler cannot determine the size of the pointer object.


Example

int x;

float r;

void *p = &x;          /* p points to x */

int main (void)

  *(int *) p = 2;

  p = &r;              /* p points to r */

  *(float *)p = 1.1;

}


volatile

See Also	Keywords

Syntax

volatile <data definition> ;

Description

Use the volatile modifier to indicate that a variable can be changed by a background routine. The compiler might choose to ignore this modifier on particular data.

Every reference to the variable will reload the contents from memory rather than take advantage of situations where a copy can be in a register.

Note:	C++ extends volatile to include classes and member functions.


See Also

const


while

See Also	Example	Keywords

Syntax

while ( <condition> ) <statement>

Description

Use the while keyword to implement a while loop.

<statement> executes repeatedly until the value of <condition> is zero.

The test takes place before <statement> executes. Thus, if <condition> evaluates to zero on the first pass, the loop does not execute.


Example

while (*p == ' ') p++;


See Also

do


Data Types (16-bit)

See Also	Keywords

Type	Length	Range

unsigned char 	8 bits	0	to	 255

char	8 bits	-128 	to	 127

enum	16 bits	-32,768 	to	 32,767

unsigned int	16 bits	0 	to	 65,535

short int	16 bits	-32,768 	to	 32,767

int	16 bits	-32,768 	to	 32,767

unsigned long 	32 bits	0 	to	 4,294,967,295

long	32 bits	-2,147,483,648 	to	 2,147,483,647

float	32 bits	3.4 x 10-38 	to	 3.4 x 10+38

double	64 bits	1.7 x 10-308 	to	 1.7 x 10+308

long double	80 bits	3.4 x 10-4932 	to	 1.1 x 10+4932

near (pointer)	16 bits	not applicable

far (pointer)	32 bits	not applicable


See Also

data types (32-bit)

char

double

enum

far

float

int

long

near


Data Types (32-bit)

See Also	Keywords

Type	Length	Range

unsigned char 	8 bits	0	to	 255

char	8 bits	-128 	to	 127

short int	16 bits	-32,768 	to	 32,767

unsigned int	32 bits	0 	to	 4,294,967,295

int	32 bits	-2,147,483,648 	to	 2,147,483,647

unsigned long 	32 bits	0 	to	 4,294,967,295

enum	16 bits	-2,147,483,648 	to	 2,147,483,647

long	32 bits	-2,147,483,648 	to	 2,147,483,647

float	32 bits	3.4 x 10-38 	to	 3.4 x 10+38

double	64 bits	1.7 x 10-308 	to	 1.7 x 10+308

long double	80 bits	3.4 x 10-4932 	to	 1.1 x 10+4932

near (pointer)	32 bits	not applicable

far (pointer)	32 bits	not applicable


See Also

data types (16-bit)

char

double

enum

far

float

int

long

near


Standard Arithmetic Conversions

Keywords

When you use an arithmetic expression, such as a + b, where a and b are different arithmetic types, Borland C++ converts the operands before the expression evaluates. These standard conversions include promotions of "lower" types to "higher" types in the interests of accuracy and consistency.

Type Specifier	Converts To	Method

char	int	Zero or sign-extended (depends on default char type)

unsigned char	int	Zero-filled high byte (always)

signed char	int	Sign-extended (always)

short	int	Same value; sign extended

unsigned short	unsigned int	Same value; zero filled

enum	int	Same value

Borland C++ uses the following steps to convert the operands in an arithmetic expression:

1.	Any small integral types convert as shown in the table. After this, any two values associated with an operator are either int (including the long and unsigned modifiers), or they are of type double, float, or long double.

2.	If one operand is of type long double, the other operand converts to long double.

3.	If one operand is of type double, the other operand converts to double.

4.	If one operand is of type float, the other operand converts to float.

5.	If one operand is of type unsigned long, the other operand converts to unsigned long.

6.	If one operand is of type long, then the other operand converts to long.

7.	If one operand is of type unsigned, then the other operand converts to unsigned.

8.	Otherwise, both operands are of type int.

The result of the expression is the same type as that of the two operands.

Assigning a signed character object (such as a variable) to an integral object results in automatic sign extension. Objects of type signed char always use sign extension; objects of type unsigned char always set the high byte to zero when converted to int.

Converting a longer integral type to a shorter type truncates the higher order bits and leaves low-order bits unchanged. Converting a shorter integral type to a longer type either sign-extends or zero-fills the extra bits of the new value, depending on whether the shorter type is signed or unsigned, respectively.


_cs, __cs, _ds, __ds, _ss, __ss, _es, and __es

Example	Keywords

Syntax

<type> _cs <pointer definition> ;

<type> __cs <pointer definition> ;

<type> _ds <pointer definition> ;

<type> __ds <pointer definition> ;

<type> _ss <pointer definition> ;

<type> __ss <pointer definition> ;

<type> _es <pointer definition> ;

<type> __es <pointer definition> ;

Description

Use the _cs, __cs, _ds, __ds, _ss, __ss, _es, and __es keywords to define special versions of near data pointers.

These pointers are 16-bit offsets associated with the specified segment register: CS, DS, SS or ES.


Example

char _cs  *s;     /* in cs code segment  */

int  _ss  ix ;    /* in ss stack segment */

long _ds  l[4] ;  /* in ds data segment  */

char _es  m[8] ;  /* in es segment       */


Register Pseudovariables

Example	Keywords

_AX       _AL       _AH       _SI       _es

_BX       _BL       _BH       _DI       _ss

_CX       _CL       _CH       _BP       _cs

_DX       _DL       _DH       _SP       _ds

_FLAGS

All but the _FLAGS register pseudovariable are associated with the general purpose, segment, address, and special purpose registers.

Use register pseudovariables anywhere that you can use an integer variable to directly access the corresponding 80x86 register.

The 16-bit flags register contains information about the state of the 80x86 and the results of recent instructions.


Example

_AX = 0x4c00;


_ _rtti

See Also	Example	Keywords

Description

The RTTI mechanism lets you check whether an object is of some particular type and whether two objects are of the same type. You can do this with typeid operator, which determines the actual type of its argument and returns a reference to an object of type const typeinfo, which describes that type.

You can also use a type name as the argument to typeid, and typeid will return a reference to a const typeinfo object for that type. The class typeinfo class provides an operator== and an operator!= that you can use to determine whether two objects are of the same type. Class typeinfo also provides a member function name that returns a pointer to a char array that holds the name of the type..

RTTI is enabled by default in Borland C++. You can use the -RT command-line option to disable it ( -RT- ) or to enable it ( -RT ). If RTTI is disabled, or if the argument to typeid is a pointer or a reference to a non-polymorphic class, typeid returns a reference to a const typeinfo object that describes the declared type of the pointer or reference, and not the actual object that the pointer or reference is bound to.

In addition, even when RTTI is disabled, you can force all instances of a particular class and all classes derived from that class to provide polymorphic run-time type identification (where appropriate) by using the Borland C++ keyword _ _rtti in the class definition.

When you use the -RT- compiler option, if any base class is declared _ _rtti, then all polymorphic base classes must also be declared _ _rtti.

struct __rtti S1 { virtual s1func(); };  /* Polymorphic */

struct __rtti S2 { virtual s2func(); };  /* Polymorphic */

struct X : S1, S2 { };

If you turn off the RTTI mechanism (by using the -RT-compiler option), RTTI might not be available for derived classes. When a class is derived from multiple classes, the order and type of base classes determines whether or not the class inherits the RTTI capability.

When you have polymorphic and non-polymorphic classes, the order of inheritance is important. If you compile the following declarations with -RT-, you should declare X with the _ _rtti modifier. Otherwise, switching the order of the base classes for the class X results in the compile-time error Can't inherit non-RTTI class from RTTI base 'S1'.

struct _ _rtti S1 { virtual func(); };   /* Polymorphic class */

struct S2 { };                           /*  Non-polymorphic class */

struct _ _rtti X : S1, S2 { };

Note:	The class X is explicitly declared with _ _rtti. This makes it safe to mix the order and type of classes.

In the following example, class X inherits only non-polymorphic classes. Class X does not need to be declared _ _rtti.

struct _ _rtti S1 {  };   // Non-polymorphic class

struct S2 { };

struct X : S2, S1 { };   // The order is not essential

Applying either _ _rtti or using the -RT compiler option will not make a static class into a polymorphic class. For more more details, see the discussion of polymorphic classes in the Borland C++ Programmers Guide.


See Also

Bad_typeid class

typeinfo class


_ _rtti Example

/* HOW TO GET RUN-TIME TYPE INFORMATION FOR POLYMORPHIC CLASSES.*/

#include <iostream.h>

#include <typeinfo.h>

class __rtti Alpha {        /* Provide RTTI for this class and */

                             /* all classes derived from it */

    virtual void func() {};  /* A virtual function makes */

                             /* Alpha a polymorphic class. */

};

class B : public Alpha {};

int main(void) {

   B Binst;           // Instantiate class B

   B *Bptr;           // Declare a B-type pointer

   Bptr = &Binst;     // Initialize the pointer

   // THESE TESTS ARE DONE AT RUN TIME

   try {

      if (typeid( *Bptr ) == typeid( B ) )

          // Ask "WHAT IS THE TYPE FOR *Bptr?"

          cout << "Name is " << typeid( *Bptr).name();

      if (typeid( *Bptr ) != typeid( Alpha ) )

          cout << "\nPointer is not an Alpha-type.";

      return 0;

      }

   catch (Bad_typeid) {

      cout << "typeid() has failed.";

      return 1;

      }

   }

Program Output

Name is B

Pointer is not an Alpha-type.


wchar_t (keyword)

Syntax

wchar_t <identifier>;

Description

In C++ programs, wchar_t is a fundamental data type that can represent distinct codes for any element of the largest extended character set in any of the supported locales. A wchar_t type is the same size, signedness, and alignment requirement as an int type.


defined

See Also	Keywords

Syntax

#if defined[(] <identifier> [)]

#elif defined[(] <identifier> [)]

Description

Use the defined operator to test if an identifier was previously defined using #define. The defined operator is only valid in #if and #elif expressions.

Defined evaluates to 1 (true) if a previously defined symbol has not been undefined (using #undef); otherwise, it evaluates to 0 (false).

Defined performs the same function as #ifdef.

#if defined(mysym)

is the same as

#ifdef mysym

The advantage is that you can use defined repeatedly in a complex expression following the #if directive; for example,

#if defined(mysym) && !defined(yoursym)


See Also

#ifdef directive

Preprocessor Directives


Operators Summary

See Also

Operators are tokens that trigger some computation when applied to variables and other objects in an expression. The Borland C++ operators described here are the standard ANSI C operators:

Arithmetic

Assignment

Bitwise

C++ specific

Comma

Conditional

Logical

Postfix

Preprocessor

Reference/Dereference

Relational

sizeof

All operators can be overloaded except the following:

.	C++ direct component selector

.* 	C++ dereference

::	C++ scope access/resolution

?:	Conditional

Depending on context, the same operator can have more than one meaning. For example, the ampersand (&) can be interpreted as:

a bitwise AND (A & B)

an address operator (&A)

in C++, a reference modifier

Note:	No spaces are allowed in compound operators. Spaces change the meaning of the operator and will generate an error.


See Also

Overloading Operators

Precedence of Operators

Punctuators


Precedence of Operators

Operators

Operators on the same line have equal precedence.

Operators	Associativity
()	[]	->	::	.							left to right
!	~	+	-	++	--	&	*	sizeof	new	delete	right to left
.*	->*										left to right
*	/	%									left to right
+	-										left to right
<<	>>										left to right
<	<=	>	>=								left to right
==	!=										left to right
&											left to right
^											left to right
|											left to right
&&											left to right
||											right to left
?:											left to right
=	*=	/=	%=	+=	-=	&=	^=	|=	<<=	>>=	right to left
,											left to right


Arithmetic Operators

See Also	Operators

Syntax

+ cast-expression

- cast-expression

add-expression + multiplicative-expression

add-expression - multiplicative-expression

multiplicative-expr * cast-expr

multiplicative-expr / cast-expr

multiplicative-expr % cast-expr

postfix-expression ++       (postincrement)

++ unary-expression         (preincrement)

postfix-expression --       (postdecrement)

-- unary-expression         (predecrement)

Remarks

Use the arithmetic operators to perform mathimatical computations.

The unary expressions of + and - assign a positive or negative value to the cast-expression.

+ (addition), - (subtraction), * (multiplication), and / (division) perform their basic algebraic artimetic on all data types, interger and floating point.

% (modulus operator) returns the remainder of integer division and cannot be used with floating points.

++ (increment) adds one to the value of the expression. Postincrement adds one to the value of the expression after it evaluates; while preincrement adds one before it evaluates.

-- (decrement) subtracts one to the value of the expression. Postdecrement subtracts one to the value of the expression after it evaluates; while predecrement subtracts one before it evaluates.


Assignment Operators

See Also	Operators

Syntax

unary-expr  assignment-op  assignment-expr

Remarks

The assignment operators are:

=    *=     /=     %=    +=    -=

<<=  >>=    &=     ^=    |=

The = operator is the only simple assignment operator, the others are compound assignment operators.

In the expression E1 = E2, E1 must be a modifiable lvalue. The assignment expression itself is not an lvalue.

The expression

E1 op= E2

has the same effect as

E1 = E1 op E2

except the lvalue E1 is evaluated only once. For example, E1 += E2 is the same as E1 = E1 + E2.

The expression's value is E1 after the expression evaluates.

For both simple and compound assignment, the operands E1 and E2 must obey one of the following rules:

1.	E1 is a qualified or unqualified arithmetic type and E2 is an arithmetic type.

2.	E1 has a qualified or unqualified version of a structure or union type compatible with the type of E2.

3.	E1 and E2 are pointers to qualified or unqualified versions of compatible types, and the type pointed to by the left has all the qualifiers of the type pointed to by the right.

4.	Either E1 or E2 is a pointer to an object or incomplete type and the other is a pointer to a qualified or unqualified version of void. The type pointed to by the left has all the qualifiers of the type pointed to by the right.

5.	E1 is a pointer and E2 is a null pointer constant.

Note:	Spaces separating compound operators (+<space>=) will generate errors.


See Also

punctuators


Bitwise Operators

See Also	Operators

Syntax

AND-expression &  equality-expression

exclusive-OR-expr ^ AND-expression

inclusive-OR-expr exclusive-OR-expression

~cast-expression

shift-expression << additive-expression

shift-expression >> additive-expression

Remarks

Use the bitwise operators to modify the individual bits rather than the number.

Operator	What it does

&	bitwise AND; compares two bits and generates a 1 result if both bits are 1, otherwise it returns 0.

|	bitwise inclusive OR; compares two bits and generates a 1 result if either or both bits are 1, otherwise it returns 0.

^	bitwise exclusive OR; compares two bits and generates a 1 result if the bits are complementary, otherwise it returns 0.

~	bitwise complement; inverts each bit.  ~ is used to create destructors.

>>	bitwise shift right; moves the bits to the right, discards the far right bit and assigns the left most bit to 0.

<<	bitwise shift left; moves the bits to the left, it discards the far left bit and assigns the right most bit to 0.

Both operands in a bitwise expression must be of an integral type.

Bit value	Results of

E1	E2	E1 & E2	E1 ^ E2	E1 | E2

0	0	0	0	0

1	0	0	1	1

0	1	0	1	1

1	1	1	0	1

Note:	&, >>, << are context sensitive. & can also be the pointer reference operator.

>> can also be the input operator in I/O expressions.

<< can also be the output operator in I/O expressions.


See Also

overloading operators


C++ Specific Operators

See Also	Operators

The operators specific to C++ are:

::	Scope access (or resolution) operator

.*	Dereference pointers to class members

->*	Dereference pointers to pointers to class members

const_cast	adds or removes the const or volatile modifier from a type

delete	dynamically deallocates memory

dynamic_cast	converts a pointer to a desired type

new	dynamically allocates memory

reinterpret_cast	replaces casts for conversions that are unsafe or implementation dependent.

static_cast	converts a pointer to a desired type

typeid	gets run-time identification of types and expressions

typesafe_downcast	converts an object pointer into a pointer to a class

Use the scope access (or resolution) operator ::(two semicolons) to access a global (or file duration) name even if it is hidden by a local redeclaration of that name.

Use the .* and ->* operators to dereference pointers to class members and pointers to pointers to class members.


See Also

[ ]  Brackets


comma operator
Comma Punctuator and Operator

See Also	Operators

Syntax

expression , assignment-expression

Remarks

The comma separates elements in a function argument list.

The comma is also used as an operator in comma expressions. Mixing the two uses of comma is legal, but you must use parentheses to distinguish them.

The left operand E1 is evaluated as a void expression, then E2 is evaluated to give the result and type of the comma expression. By recursion, the expression

E1, E2, ..., En

results in the left-to-right evaluation of each Ei, with the value and type of En giving the result of the whole expression.

To avoid ambiguity with the commas in function argument and initializer lists, use parentheses. For example,

func(i, (j = 1, j + 4), k);

calls func with three arguments (i, 5, k), not four.


conditional operators
Conditional Operator

Operators

Syntax

logical-OR-expr ? expr : conditional-expr

Remarks

The conditional operator ?: is a ternary operator.

In the expression E1 ? E2 : E3, E1 evaluates first. If its value is nonzero (true), then E2 evaluates and E3 is ignored. If E1 evaluates to zero(false), then E3 evaluates and E2 is ignored.

The result of E1 ? E2 : E3 will be the value of either E2 or E3 depending upon which evaluates.

E1 must be a scalar expression. E2 and E3 must obey one of the following rules:

1.	Both of arithmetic type. E2 and E3 are subject to the usual arithmetic conversions, which determines the resulting type.

2.	Both of compatible structure or union types. The resulting type is the structure or union type of E2 and E3.

3.	Both of void type. The resulting type is void.

4.	Both of type pointer to qualified or unqualified versions of compatible types. The resulting type is a pointer to a type qualified with all the type qualifiers of the types pointed to by both operands.

5.	One operand is a pointer, and the other is a null pointer constant. The resulting type is a pointer to a type qualified with all the type qualifiers of the types pointed to by both operands.

6.	One operand is a pointer to an object or incomplete type, and the other is a pointer to a qualified or unqualified version of void. The resulting type is that of the non-pointer-to-void operand.


Logical Operators

Operators

Syntax

logical-AND-expr  && inclusive-OR-expression

logical-OR-expr   || logical-AND-expression

! cast-expression

Remarks

Operands in a logical expression must be of scalar type.

&&	logical AND; returns TRUE (1) only if both expressions evaluate to be nonzero, otherwise returns FALSE (0). If the first expression evaluates to FALSE, the second expression is not evaluated.

||	logical OR; returns TRUE (1) if either of the expressions evaluate to be nonzero, otherwise returns FALSE (0). If the first expression evaluates to TRUE, the second expression is not evaluated.

!	logical negation; returns TRUE (1) if the entire expression evaluates to be nonzero, otherwise returns FALSE (0). The expression !E is equivalent to (0 == E).


Postfix Operators

See Also	Operators

Syntax

postfix-expression(<arg-expression-list>)

array declaration [constant-expression]

compound statement { statement list }

postfix-expression . identifier

postfix-expression -> identifier

Remarks

( )	use to group expressions, isolate conditional expressions, indicate function calls and function parameters

{ }	use as the start and end of compound statements

[ ]	use to indicate single and multidimensional array subscripts

.	use to access structure and union members

->	use to access structure and union members


Preprocessor Operators

Operators

Remarks

The # (pound sign) is a preprocessor directive when it occurs as the first non-whitespace character on a line.

It signifies a compiler action, not necessarily associated with code generation.

# and ## (double pound signs) also perform operator replacement and merging during the preprocessor scanning phase.


reference/deference operators
Reference/Dereference Operators

See Also	Operators

Syntax

& cast-expression

* cast-expression

Remarks

The & and * operators work together to reference and dereference pointers that are passed to functions.

Referencing operator ( & )

Use the reference operator to pass the address of a pointer to a function outside of main().

The cast-expression operand must be one of the following:

a function designator

an lvalue designating an object that is not a bit field and is not declared with a register storage class specifier

If the operand is of type <type>, the result is of <type> pointer to type.

Dereferencing operator ( * )

Use the asterisk (*) in a variable expression to create pointers. And use the dereference operator in external functions to get a pointer's value that was passed by reference.

If the operand is of type "pointer to function," the result is a function designator.

If the operand is a pointer to an object, the result is an lvalue designating that object.

The result of indirection is undefined if either of the following occur:

1.	The cast-expression is a null pointer.

2.	The cast-expression is the address of an automatic variable and execution of its block has terminated.

Note:	& can also be the bitwise AND operator.

* can also be the multiplication operator.


See Also

overloading operators

punctuators


Relational Operators

See Also	Operators

Syntax

equality expression  ==  relational expression

equality expression  !=  relational expression

relational-expression  <   shift-expression

relational-expression  >   shift-expression

relational-expression  <=  shift-expression

relational-expression  >=  shift-expression

Remarks

Use relational operators to test equality or inequality of expressions. If the statement evaluates to be TRUE it returns a nonzero character; otherwise it returns FALSE (0).

==	equal

!=	not equal

>	greater than

<	less than

>=	greater than or equal

<=	less than or equal

In the expression

E1 <operator> E2

the operands must follow one of these conditions:

1.	Both E1 and E2 are of arithmetic type.

2.	Both E1 and E2 are pointers to qualified or unqualified versions of compatible types.

3.	One of E1 and E2 is a pointer to an object or incomplete type, and the other is a pointer to a qualified or unqualified version of void.

4.	One of E1 or E2 is a pointer and the other is a null pointer constant.


Array subscript operator

See Also	Operators

Brackets ([ ]) indicate single and multidimensional array subscripts. The expression

<exp1>[exp2]

is defined as

*((exp1) + (exp2))

where either:

exp1 is a pointer and exp2 is an integer or

exp1 is an integer and exp2 is a pointer


parentheses operators
Parentheses operator

See Also	Operators

Syntax

postfix-expression(<arg-expression-list>)

Remarks

Parentheses ()

group expressions

isolate conditional expressions

indicate function calls and function parameters

The value of the function call expression, if it has a value, is determined by the return statement in the function definition.

This is a call to the function given by the postfix expression.

arg-expression-list is a comma-delimited list of expressions of any type representing the actual (or real) function arguments.


.  (direct member selector)
Direct member selector

See Also	Example	Operators

Syntax

postfix-expression . identifier

postfix-expression must be of type union or structure.

identifier must be the name of a member of that structure or union type.

Remarks

Use the selection operator (.) to access structure and union members.

Suppose that the object s is of struct type S and sptr is a pointer to S. Then, if m is a member identifier of type M declared in S, this expression:

s.m

are of type M, and represent the member object m in s.


Example

struct mystruct {

   int i

   char str[21]

   double d

} s, *sptr=&s

 ...

s.i = 3          // assign to the i member of mystruct s

The expression s.m is an lvalue, provided that s is not an lvalue and m is not an array type.

If structure B contains a field whose type is structure A, the members of A can be accessed by two applications of the member selectors.


->  (indirect, or pointer, member selector)
Indirect member selector

See Also	Example	Operators

Syntax

postfix-expression -> identifier

postfix-expression must be of type  pointer to structure or pointer to union.

identifier must be the name of a  member of that structure or union type.

The expression designates a member of a structure or union object. The value of the expression is the value of the selected member it will be an lvalue if and only if the postfix expression is an lvalue.

Remarks

You use the selection operator -> to access structure and union members.

Suppose that the object s is of struct type S and sptr is a pointer to S. Then, if m is a member identifier of type M declared in S, this expression:

sptr->m

is of type M, and represents the member object m in s.

The expression

s->sptr

is a convenient synonym for (*sptr).m.


-> Example

struct mystruct {

   int i

   char str[21]

   double d

} s, *sptr=&s

  .

  .

  .

sptr->d = 1.23   // assign to the d member of mystruct s

The expression sptr->m is an lvalue unless m is an array type.

If structure B contains a field whose type is structure A, the members of A can be accessed by two applications of the member selectors.


Lvalues

Operators

An lvalue is an object locator: an expression that designates an object. An example of an lvalue expression is *P, where P is any expression evaluating to a non-null pointer.

A modifiable lvalue is an identifier or expression that relates to an object that can be accessed and legally changed in memory.

A const pointer to a constant, for example,is not a modifiable lvalue.

A pointer to a constant can be changed (but its dereferenced value cannot).

Historically, the l stood for "left," meaning that an lvalue could legally stand on the left (the receiving end) of an assignment statement. Now, only modifiable lvalues can legally stand on the left of an assignment statement.

For example, if a and b are nonconstant integer identifiers with properly allocated memory storage, they are both modifiable values, and assignments such as

a = 1

b = a + b

are legal.page R_Values

Rvalues

The expression

a + b

is not an lvalue: a + b = a is illegal because the expression on the left is not related to an object.

Such expressions are often called rvalues(short for "right values").


Increment/Decrement operators

Operators

Increment operator  ( ++ )

Syntax

postfix-expression ++       (postincrement)

++ unary-expression         (preincrement)

The expression is called the operand it must be of scalar type (arithmetic or pointer types) and must be a modifiable lvalue..

Postincrement operator

The value of the whole expression is the value of the postfix expression before the increment is applied.

After the postfix expression is evaluated,the operand is incremented by 1.

Preincrement operator

The operand is incremented by 1 before the expression is evaluated the value of the whole expression is the incremented value of the operand.

The increment value is appropriate to the type of the operand.

Pointer types follow the rules for pointer arithmetic.

Decrement operator  ( -- )

Syntax

postfix-expression --       (postdecrement)

-- unary-expression         (predecrement)

The decrement operator follows the same rules as the increment operator, except that the operand is decremented by 1 after or before the whole expression is evaluated.


Passing arguments by reference

See Also	Operators

C passes arguments only by value in C++, you can pass arguments by value or by reference.

C++ reference types, created with the &, are closely related to pointer types. They create aliases for objects and let you pass arguments to functions by reference.

The reference declarator (&) can be used to dcelare references outside functions:

int  i  = 0

int &Ir = i   // Ir is an alias for i

Ir = 2        // same effect as i = 2

This creates the lvalue Ir as an alias for i, provided that the initializer is the same type as the reference.

Any operations on Ir have precisely the same effect as operations on i. For example,

Ir = 2

assigns 2 to i, and

&Ir

returns the address of i.

The reference declarator can also be used to dcelare reference type parameters within a function:

void func1 (int i)

void func2 (int &Ir)

// Ir is type "reference to int"

    ...

int sum=3

func1(sum)     // sum passed by value

func2(sum)     // sum passed by reference

The sum argument passed by reference can be changed directly by func2.

func1, on the other hand, gets a copy of the sum argument (passed by value), so sum itself cannot be altered by func1.

When an actual argument x is passed by value,the matching formal argument in the function receives a copy of x.

Any changes to this copy within the function body are not reflected in the value of x itself.

Of course, the function can return a value that could be used later to change x, but the function cannot directly alter a parameter passed by value.

The traditional C method for changing x uses the actual argument &x, the address of x,rather than x itself.

Although &x is passed by value, the function can access x through the copy of &x it receives. Even if the function does not need to change x, it is still useful (though subject to possibly dangerous side effects)to pass &x, especially if x is a large data structure.

Passing x directly by value involves the wasteful copying of the data structure.


See Also

& operator

punctuators


Plus and Minus Operators

See Also	Operators

Unary

In these unary + - expressions

+ cast-expression

- cast-expression

the cast-expression operand must be of arithmetic type.

Results

+ cast-expression	Value of the operand after any required integral promotions.

- cast-expression	Negative of the value of the operand after any required integral promotions.

Binary

Syntax

add-expression + multiplicative-expression

add-expression - multiplicative-expression

Legal operand types for op1 + op2:

1.	Both op1 and op2 are of arithmetic type.

2.	op1 is of integral type, and op2 is of pointer to object type.

3.	op2 is of integral type, and op1 is of pointer to object type.

In case 1, the operands are subjected to the standard arithmetical conversions, and the result is the arithmetical sum of the operands.

In cases 2 and 3, the rules of pointer arithmetic apply.

Legal operand types for op1 - op2:

1.	Both op1 and op2 are of arithmetic type.

2.	Both op1 and op2 are pointers to compatible object types.

3.	op1 is of pointer to object type, and op2 is integral type.

In case 1, the operands are subjected to the standard arithmetic conversions, and the result is the arithmetic difference of the operands.

In cases 2 and 3, the rules of pointer arithmetic apply.

Note:	The unqualified type <type> is considered to be compatible with the qualified types const type, volatile type,and const volatile type.


Multiplicative Operators

See Also	Operators

Syntax

multiplicative-expr * cast-expr

multiplicative-expr / cast-expr

multiplicative-expr % cast-expr

Remarks

There are three multiplicative operators:

*	(multiplication)

/	(division)

%	(modulus or remainder)

The usual arithmetic conversions are made on the operands.

(op1 * op2)  Product of the two operands

(op1 / op2)  Quotient of (op1 divided by op2)

(op1 % op2)  Remainder of (op1 divided by op2)

For / and %, op2 must be nonzero op2 = 0 results in an error. (You can't divide by zero.)

When op1 and op2 are integers and the quotient is not an integer:

1.	If op1 and op2 have the same sign, op1 / op2 is the largest integer less than the true quotient, and op1 % op2 has the sign of op1.

2.	If op1 and op2 have opposite signs, op1 / op2 is the smallest integer greater than the true quotient, and op1 % op2 has the sign of op1.

Note: Rounding is always toward zero.

* is context sensitive and can be used as the pointer reference operator.


See Also

overloading operators

punctuators


Punctuators

See Also	Operators

The Borland C++ punctuators (also known as separators) are:

( )  Parentheses

{ }  Braces

,   Comma

;  Semicolon

:   Colon

...  Ellipsis

*   Asterisk

=   Equal Sign

#   Pound Sign

Most of these punctuators also function as operators.

See Also

token


braces punctuators
Braces

Operators

The braces ({ }) indicate the start and end of a compound statement.


semicolon punctuator
Semicolon

Operators

The semicolon (;) is a statement terminator.

Any legal C expression (including the empty expression) followed by  is interpreted as a statement, known as an expression statement.

The expression is evaluated and its value is discarded. If the expression statement has no side effects, Borland C++ can ignore it.

Semicolons are often used to create an empty statement.


colon punctuator
Colon

Example	Operators

Use the colon (:) to indicate a labeled statement:


Example

start:    x=0

...

goto start

...

switch (a) {

    case 1: puts("One")

            break

    case 2: puts("Two")

            break

 ...

 default:   puts("None of the above!")

            break

}


ellipsis punctuator
Ellipsis

Operators

An ellipsis (...) is three successive periods with no intervening whitespace.

Use an ellipsis in formal argument lists of function prototypes to indicate a variable number of arguments, or arguments with varying types. For example,

void func(int n, char ch,...)

This declaration indicates that calls to func must have at least two arguments, an int and a char, but can also have any number of additional arguments.

The comma preceding the ellipsis is not necessary.


equal sign punctuator
Equal sign

Operators

The equal sign (=) separates variable declarations from initialization lists.

char array[5] = { 1, 2, 3, 4, 5 } ;

int  x = 5;

In a C function, no code can precede any variable declarations.

In C++, declarations of any type can appear (with some restrictions) at any point within the code. In a C++ function argument list, the equal sign indicates the default value for a parameter:

int f(int i = 0) { ... }  //  parameter i has default value of zero

The equal sign is also used as the assignment operator.


Binary operators

Operators

These are the binary operators in Borland C++:

Arithmetic	+ 	Binary plus (add)

- 	Binary minus (subtract)

*	Multiply

/	Divide

% 	Remainder (modulus)

Bitwise	<<	Shift left

>>	Shift right

&	Bitwise AND

^   	Bitwise XOR (exclusive OR)

|   	Bitwise inclusive OR

Logical	&&  	Logical AND

||  	Logical OR

Assignment	=   	Assignment

*= 	Assign product

/=  	Assign quotient

%=  	Assign remainder (modulus)

+=  	Assign sum

-=  	Assign difference

<<= 	Assign left shift

 >>= 	Assign right shift

&=  	Assign bitwise AND

 ^=  	Assign bitwise XOR

|=  	Assign bitwise OR

Relational	<   	Less than

>   	Greater than

<=  	Less than or equal to

>=  	Greater than or equal to

==  	Equal to

!=  	Not equal to

Component selection	. 	Direct component selector

->  	Indirect component selector

Class-member	:: 	Scope access/resolution

.*  	Dereference pointer to class member

->* 	Dereference pointer to class member

Conditional	? : 	Actually a ternary operator for example,

a ? x : y 	"if a then x else y"

Comma	,	Evaluate

See Also

punctuators

&   Address


Unary operators

See Also	Operators

Syntax

<unary-operator> <unary expression>

OR

<unary-operator> <type><unary expression>

Remarks

Borland C++ provides the following unary operators:

!   Logical negation

*   Indirection

++  Increment

~   Bitwise complement

--  Decrement

-   Unary minus

+   Unary plus


See Also

virtual


Overloading Operators

See Also	Operators

C++ lets you redefine the actions of most operators, so that they perform specified functions when used with objects of a particular class. As with overloaded C++ functions in general, the compiler distinguishes the different functions by noting the context of the call: the number and types of the arguments or operands.

All the operators can be overloaded except for:

.   .*   ::   ?:   #   ##

The keyword operator followed by the operator symbol is called the operator function name; it is used like a normal function name when defining the new (overloaded) action for the operator.

A function operator called with arguments behaves like an operator working on its operands in an expression. The operator function cannot alter the number of arguments or the precedence and associativity rules applying to normal operator use.


See Also

Overloaded Operators and Inheritance

Overloading Binary Operators

Overloading Operator Functions

Overloading the Assignment Operator  =

Overloading the Class Member Access Operators ->

Overloading the Function Call Operator  ( )

Overloading the new and delete Operators

Overloading the Subscript Operator  []

Overloading Unary Operators


Overloading Operator Functions

See Also	Operators

Operator functions can be called directly, although they are usually invoked indirectly by the use of the overload operator:

c3 = c1.operator + (c2);   // same as c3 = c1 + c2

Apart from new and delete, which have their own rules, an operator function must either be a nonstatic member function or have at least one argument of class type. The operator functions =, ( ), [ ] and -> must be nonstatic member functions.


Overloaded Operators and Inheritance

See Also	Operators

With the exception of the assignment function operator =( ), all overloaded operator functions for class X are inherited by classes derived from X, with the standard resolution rules for overloaded functions. If X is a base class for Y, an overloaded operator function for X could possibly be further overloaded for Y.


Overloading the new and delete Operators

See Also	Operators

The operators new and delete can be overloaded to provide alternative free storage (heap) memory-management routines:

A user-defined operator new must return a void* and must have a size_t as its first argument.

A user-defined operator delete must have a void return type and void* as its first argument; a second argument of type size_t is optional.


Overloading Unary Operators

See Also	Operators

You can overload a prefix or postfix unary operator by declaring a nonstatic member function taking no arguments, or by declaring a nonmember function taking one argument. If @ represents a unary operator, @x and x@ can both be interpreted as either x.operator@() or operator@(x), depending on the declarations made. If both forms have been declared, standard argument matching is applied to resolve any ambiguity.

Under C++ 2.0, an overloaded operator ++ or -- is used for both prefix and postfix uses of the operator.

With C++ 2.1, when an operator++ or operator- - is declared as a member function with no parameters, or as a nonmember function with one parameter, it only overloads the prefix operator++ or operator- -. You can only overload a postfix operator++ or operator- - by defining it as a member function taking an int parameter or as a nonmember function taking one class and one int parameter.

When only the prefix version of an operator++ or operator- - is overloaded and the operator is applied to a class object as a postfix operator, the compiler issues a warning. Then it calls the prefix operator, allowing 2.0 code to compile. The preceding example results in the following warnings:

Warning: Overloaded prefix 'operator ++' used as a postfix operator in function func()

Warning: Overloaded prefix 'operator --' used as a postfix operator in function func()


Overloading Binary Operators

See Also	Operators

You can overload a binary operator by declaring a nonstatic member function taking one argument, or by declaring a non-member function (usually friend) taking two arguments. If @ represents a binary operator, x@y can be interpreted as either x.operator@(y) or operator@(x,y) depending on the declarations made. If both forms have been declared, standard argument matching is applied to resolve any ambiguity.


Overloading the Assignment Operator  =

See Also	Operators

The assignment operator=( ) can be overloaded by declaring a nonstatic member function. For example,

class String {

     .

     .

     .

   String& operator = (String& str);

     .

     .

     .

   String (String&);

   ~String();

}

This code, with suitable definitions of String::operator =(), allows string assignments str1 = str2 just like other languages. Unlike the other operator functions, the assignment operator function cannot be inherited by derived classes. If, for any class X, there is no user-defined operator =, the operator = is defined by default as a member-by-member assignment of the members of class X:

X& X::operator = (const X& source)

{

   // memberwise assignment

}


Overloading the Function Call Operator  ( )

See Also	Operators

Syntax

postfix-expression ( <expression-list> )

Description

In its ordinary use as a function call, the postfix-expression must be a function name, or a pointer or reference to a function. When the postfix-expression is used to make a member function call, postfix-expression must be a class member function name or a pointer-to-member expression used to select a class member function. In either case, the postfix-expression is followed by the optional expression-list (possibly empty).

A call X(arg1, arg2), where X is an object class X, is interpreted as X.operator()(arg1, arg2).

The function call operator, operator()(), can only be overloaded as a nonstatic member function.


Overloading the Subscript Operator  [ ]

Syntax

postfix-expression [ expression ]

Description

The corresponding operator function is operator[](); this can be user-defined for a class X (and any derived classes). The expression X[y], where X is an object of class X, is interpreted as x.operator[](y).

The operator[]() can only be overloaded as a nonstatic member function.


Overloading the Class Member Access Operators ->
Overloading the Class Member Access Operator  ->

See Also	Operators

Syntax

postfix-expression -> primary-expression

Description

The expression x->m, where x is a class X object, is interpreted as (x.operator->())->m, so that the function operator->() must either return a pointer to a class object or return an object of a class for which operator-> is defined.

The operator->() can only be overloaded as a nonstatic member function.


const_cast (typecast operator)
const_cast

See Also

Syntax

CONST_CAST(targetType,object)

Description

Use the const_cast operator to add or remove the const or volatile modifier from a type.

In the statement, const_cast< T > (arg), T and arg must be of the same type except for const and volatile modifiers. The cast is resolved at compile time. The result is of type T. Any number of const or volatile modifiers can be added or removed with a single const_cast expression.

A pointer to const can be converted to a pointer to non-const that is in all other respects an identical type. If successful, the resulting pointer refers to the original object.

A const object or a reference to const cast results in a non-const object or reference that is otherwise an identical type.

The const_cast operator performs similar typecasts on the volatile modifier. A pointer to volatile object can be cast to a pointer to non-volatile object without otherwise changing the type of the object. The result is a pointer to the original object. A volatile-type object or a reference to volatile-type can be converted into an identical non-volatile type.


See Also

dynamic_cast

reinterpret_cast

static_cast

typesafe_downcast


dynamic_cast (typecast operator)
dynamic_cast

See Also	Example

In the expression, dynamic_cast< T > (ptr), T must be a pointer or a reference to a defined class type or void*. The argument ptr must be an expression that resolves to a pointer or reference.

If T is void* then ptr must also be a pointer. In this case, the resulting pointer can access any element of the class that is the most derived element in the hierarchy. Such a class cannot be a base for any other class.

Conversions from a derived class to a base class, or from one derived class to another, are as follows: if T is a pointer and ptr is a pointer to a non-base class that is an element of a class hierarchy, the result is a pointer to the unique subclass. References are treated similarly. If T is a reference and ptr is a reference to a non-base class, the result is a reference to the unique subclass.

A conversion from a base class to a derived class can be performed only if the base is a polymorphic type.

The conversion to a base class is resolved at compile time. A conversion from a base class to a derived class, or a conversion across a hierarchy is resolved at runtime.

If successful, dynamic_cast< T > (ptr) converts ptr to the desired type. If a pointer cast fails, the returned pointer is valued 0. If a cast to a reference type fails, the Bad_cast exception is thrown.

Note:	Runtime type information (RTTI) is required for dynamic_cast.


// dynamic_cast Example

// HOW TO MAKE DYNAMIC CASTS

// This program must be compiled with the -RT (Generate RTTI) option.

#include <iostream.h>

#include <typeinfo.h>

class Base1

{

   // In order for the RTTI mechanism to function correctly,

   // a base class must be polymorphic.

   virtual void f(void) { /* A virtual function makes the class polymorphic */ }

};

class Base2 { };

class Derived : public Base1, public Base2 { };

int main(void) {

   try {

      Derived d, *pd;

      Base1 *b1 = &d;

      // Perform a downcast from a Base1 to a Derived.

      if ((pd = dynamic_cast<Derived *>(b1)) != 0) {

           cout << "The resulting pointer is of type "

                << typeid(pd).name() << endl;

         }

      else throw Bad_cast();

      // Attempt cast across the hierarchy.  That is, cast from

      // the first base to the most derived class and then back

      // to another accessible base.

      Base2 *b2;

      if ((b2 = dynamic_cast<Base2 *>(b1)) != 0) {

          cout << "The resulting pointer is of type "

               << typeid(b2).name() << endl;

         }

      else throw Bad_cast();

      }

   catch (Bad_cast) {

      cout << "dynamic_cast failed" << endl;

      return 1;

      }

   catch (...) {

      cout << "Exception handling error." << endl;

      return 1;

      }

   return 0;

}


See Also

const_cast

reinterpret_cast

__rtti (keyword)

static_cast

typeinfo

typesafe_downcast


reinterpret_cast (typecast operator)
reinterpret_cast

See Also	Example

Syntax

REINTERPRET_CAST(targetType,object)

Description

In the statement, reinterpret_cast< T > (arg), T must be a pointer, reference, arithmetic type, pointer to function, or pointer to member.

A pointer can be explicitly converted to an integral type.

An integral arg can be converted to a pointer. Converting a pointer to an integral type and back to the same pointer type results in the original value.

A yet undefined class can be used in a pointer or reference conversion.

A pointer to a function can be explicitly converted to a pointer to an object type provided the object pointer type has enough bits to hold the function pointer. A pointer to an object type can be explicitly converted to a pointer to a function only if the function pointer type is large enough to hold the object pointer.


// reinterpret_cast Example

// Use reinterpret_cast<Type>(expr) to replace (Type)expr casts

// for conversions that are unsafe or implementation dependent.

void func(void *v) {

        // Cast from pointer type to integral type.

        int i = reinterpret_cast<int>(v);

  .

  .

  .

}

void main() {

   // Cast from an integral type to pointer type.

   func(reinterpret_cast<void *>(5));

   // Cast from a pointer to function of one type to

   // pointer to function of another type.

   typedef void (* PFV)();

   PFV pfunc = reinterpret_cast<PFV>(func);

   pfunc();

   }


See Also

const_cast

dynamic_cast

static_cast

typesafe_downcast


static_cast (typecast operator)
static_cast

See Also

Syntax

STATIC_CAST(targetType,object)

Description

In the statement, static_cast< T > (arg), T must be a pointer, reference, arithmetic type, or enum type. The arg-type must match the T-type. Both T and arg must be fully known at compile time.

If a complete type can be converted to another type by some conversion method already provided by the language, then making such a conversion by using static_cast achieves exactly the same thing.

Integral types can be converted to enum types. A request to convert arg to a value that is not an element of enum is undefined.

The null pointer is converted to itself.

A pointer to one object type can be converted to a pointer to another object type. Note that merely pointing to similar types can cause access problems if the similar types are not similarly aligned.

You can explicitly convert a pointer to a class X to a pointer to some class Y if X is a base class for Y. A static conversion can be made only under the following conditions:

if an unambiguous conversion exists from Y to X

if X is not a virtual base class

An object can be explicitly converted to a reference type X& if a pointer to that object can be explicitly converted to an X*. The result of the conversion is an lvalue. No constructors or conversion functions are called as the result of a cast to a reference.

An object or a value can be converted to a class object only if an appropriate constructor or conversion operator has been declared.

A pointer to a member can be explicitly converted into a different pointer-to-member type only if both types are pointers to members of the same class or pointers to members of two classes, one of which is unambiguously derived from the other.

When T is a reference the result of static_cast< T > (arg) is an lvalue. The result of a pointer or reference cast refers to the original expression.


See Also

const_cast

dynamic_cast

reinterpret_cast

typesafe_downcast


typesafe_downcast (typecast operator)
typesafe_downcast

See Also

Syntax

TYPESAFE_DOWNCAST(object,toClass)

Description

Converts the pointer referred to by 'object' into a pointer to an object of type 'toClass'. The macro parameters to TYPESAFE_DOWNCAST are in the opposite order from the rest of the macros here. When using a compiler that supports new style casts and runtime type information this is done with dynamic_cast<> and will return 0 if the cast cannot be done. When using a compiler that does not support new-style casts and runtime type information this is done with fake runtime type information generated by the IMPLEMENT_CASTABLE macro.


See Also

const_cast

dynamic_cast

reinterpret_cast

static_cast


Predefined Macros

See Also

Macro	Value 	What Macro Is/Does

_ _BCOPT_ _	1	Defined in any compiler that has an optimizer

_ _BCPLUSPLUS_ _	0x340	Defined if you've selected C++ compilation; will increase in later releases

_ _BORLANDC_ _	0x460	Version number

_ _CDECL_ _ 	1	Defined if Calling Convention is set to C; otherwise undefined

_ _CONSOLE_ _	 	Available only for the 32-bit compiler. When defined, the macro indicates that the program is a console application.

_ _cplusplus	1	Defined if in C++ mode; otherwise, undefined

_ _DATE_ _	String literal	Date when processing began on the current file

_ _DLL_ _	1	Defined if Prolog/Epilog Code Generation is set to Windows DLL; otherwise undefined

_ _FILE_ _	String literal	Name of the current file being processed

_ _LINE_ _	Decimal constant	Number of the current source file line being processed

_ _MSDOS_ _	1	Integer constant

_ _MT_ _	1	Defined only for the 32-bit compiler if the -WM option is used. It specifies that the multithread library is to be linked.

_ _OVERLAY_ _	1	Specific to the Borland C and C++ family of compilers. It is predefined as 1 if you compile a module with the -Y option (enable overlay support). If you do not enable overlay support, this macro is undefined.

_ _PASCAL_ _ 	1	Defined if Calling Convention is set to Pascal; otherwise undefined

_ _STDC_ _	Constant	= 1 if you compile with the Keywords option set to ANSI; otherwise, undefined

_ _TCPLUSPLUS_ _ 	0x340	Version number

_ _TEMPLATES_ _	1	Specific to the Borland C and C++ family of compilers. It is defined as 1 for C++ files (meaning that Borland C++ supports templates); otherwise, it is undefined.

_ _TIME_ _	String literal	Time when processing began on the current file

_ _TLS_ _	1	Always true when the 32-bit compiler is used.

_ _TURBOC_ _ 	0x460	Will increase in later releases

_ _WIN32_ _	1	Always defined for the 32-bit compiler. It is defined for console and GUI applications.

_Windows	 	Defined for Windows 16- and 32-bit compilations

Note:	_ _DATE_ _, _ _FILE_ _, _ _LINE_ _, _ _STDC_ _, and _ _TIME_ _cannot appear immediately following a #define or #undef directive.


See Also

Memory model macros


Memory Model Macros

See Also

For any given compilation, only one memory-model macro is defined; all the others are undefined.

Macro 	Defined if...

_ _COMPACT_ _	You choose compact memory model at compile time

_ _LARGE_ _	You choose large memory model at compile time

_ _MEDIUM_ _	You choose medium memory model at compile time

_ _SMALL_ _	You choose small memory model at compile time

_ _TINY_ _	You choose tiny memory model at compile time

_ _HUGE_ _	You choose huge memory model at compile time


See Also

Predefined macros


Header Files Summary

See Also

Header files, also called include files, provide function prototype declarations for library functions. Data types and symbolic constants used with the library functions are also defined in them, along with global variables defined by Borland C++ and by the library functions. The Borland C++ library follows the ANSI C standard on names of header files and their contents.

Note:	The middle column indicates C++ header files and header files defined by ANSI C.

alloc.h	Declares memory-management functions (allocation, deallocation, and so on).

assert.h	ANSI C	Defines the assert debugging macro.

bcd.h	C++	Declares the C++ class bcd and the overloaded operators for bcd and bcd math functions.

bios.h	Declares various functions used in calling IBM-PC ROM BIOS routines.

bwcc.h	Defines the Borland Windows Custom Control interface.

checks.h	C++	Defines the class diagnostic macros.

complex.h	C++	Declares the C++ complex math functions.

conio.h	Declares various functions used in calling the operating system console I/O routines.

constrea.h	C++	Defines the conbuf and constream classes.

cstring.h	C++	Defines the string classes.

ctype.h	ANSI C	Contains information used by the character classification and character conversion macros (such as isalpha and toascii).

date.h	C++	Defines the date class.

_defs.h	Defines the calling conventions for different application types and memory models.

dir.h	Contains structures, macros, and functions for working with directories and path names.

direct.h	Defines structures, macros, and functions for dealing with directories and path names.

dirent.h	Declares functions and structures for POSIX directory operations.

dos.h	Defines various constants and gives declarations needed for DOS and 8086-specific calls.

errno.h	ANSI C	Defines constant mnemonics for the error codes.

except.h	C++	Declares the exception-handling classes and functions.

excpt.h	Declares C structured exception support.

fcntl.h	Defines symbolic constants used in connection with the library routine open.

file.h	C++	Defines the file class.

float.h	ANSI C	Contains parameters for floating-point routines.

fstream.h	C++	Declares the C++ stream classes that support file input and output.

generic.h	C++	Contains macros for generic class declarations.

io.h	Contains structures and declarations for low-level input/output routines.

iomanip.h	C++	Declares the C++ streams I/O manipulators and contains templates for creating parameterized manipulators.

iostream.h	C++	Declares the basic C++ streams (I/O) routines.

limits.h	ANSI C	Contains environmental parameters, information about compile-time limitations, and ranges of integral quantities.

locale.h	ANSI C	Declares functions that provide country- and language-specific information.

malloc.h	Declares memory-management functions and variables.

math.h	ANSI C	Declares prototypes for the math functions and math error handlers.

mem.h	Declares the memory-manipulation functions. (Many of these are also defined in string.h.)

memory.h	Contains memory-manipulation functions.

new.h	C++	Access to _new_handler, and set_new_handler.

_nfile.h	Defines the maximum number of open files.

_null.h	Defines the value of NULL.

process.h	Contains structures and declarations for the spawn... and exec... functions.

search.h	Declares functions for searching and sorting.

setjmp.h	ANSI C	Declares the functions longjmp and setjmp and defines a type jmp_buf that these functions use.

share.h	Defines parameters used in functions that make use of file-sharing.

signal.h	ANSI C	Defines constants and declarations for use by the signal and raise functions.

stdarg.h	ANSI C	Defines macros used for reading the argument list in functions declared to accept a variable number of arguments (such as vprintf, vscanf, and so on).

stddef.h	ANSI C	Defines several common data types and macros.

stdio.h	ANSI C	Defines types and macros needed for the standard I/O package defined in Kernighan and Ritchie and extended under UNIX System V. Defines the standard I/O predefined streams stdin, stdout, stdprn, and stderr and declares stream-level I/O routines.

stdiostr.h	C++	Declares the C++ (version 2.0) stream classes for use with stdio FILE structures. You should use iostream.h for new code.

stdlib.h	ANSI C	Declares several commonly used routines such as conversion routines and search/sort routines.

string.h	ANSI C	Declares several string-manipulation and memory-manipulation routines.

strstrea.h	C++	Declares the C++ stream classes for use with byte arrays in memory.

sys\locking.h	Contains definitions for mode parameter of locking function.

sys\stat.h	Defines symbolic constants used for opening and creating files.

sys\timeb.h	Declares the function ftime and the structure timeb that ftime returns.

sys\types.h	Declares the type time_t used with time functions.

thread.h	C++	Defines the thread classes.

time.h	ANSI C	Defines a structure filled in by the time-conversion routines asctime, localtime, and gmtime, and a type used by the routines ctime, difftime, gmtime, localtime, and stime. It also provides prototypes for these routines.

typeinfo.h	C++	Declares the run-time type information classes.

utime.h	Declares the utime function and the utimbuf struct that it returns.

values.h	Defines important constants, including machine dependencies; provided for UNIX System V compatibility.

varargs.h	Definitions for accessing parameters in functions that accept a variable number of arguments. Provided for UNIX compatibility; you should use stdarg.h for new code.


See Also

Precompiled Headers


Precompiled Headers (Using)
Precompiled Headers

See Also	Header Files

Borland C++ can generate (and subsequently use) precompiled headers for your projects.

Precompiled headers are header files that are compiled once, then used over and over again in their compiled state.

Using Precompiled Headers

To control the use of precompiled headers, do one of the following:

1.	Turn on the Precompiled Headers option in the Compiler settings page. The IDE bases the name of the precompiled header file on the project name, creating<project>.CSM

2.	Use the hdrfile and hdrstop pragmas inside your code.

A header that contains code can't be precompiled.

For example, although C++ class definitions can appear in header files, make sure that only inline member functions are defined in the header.

Heed warnings such as "Functions containing 'for' are not expanded inline".

Rules for Use

In order to load a previously generated precompiled header for a subsequent compilation, the second or later source file must:

have the same set of include files as the first, in the same order

have the same macros as the first, defined to identical values

use the same language as the first (C or C++)

use header files with identical time stamps as the first

In addition, the subsequent source file must be compiled with the same settings as the first for the following options:

Memory model, including SS != DS

Underscores on externs

 	Maximum identifier length

Target DOS (default) or Windows

Generate word alignment

Pascal calls

Treat enums as integers

 	Default char is unsigned

 Virtual table control

Setting File Names

The compiler stores all precompiled headers in one file (default name = TCDEF.CSM).

Use -H=<filename> or #pragma hdrfile to explicitly set the file name.

Note:	If your .CSM file is smaller than it should be, the compiler might have run out of disk space when writing to the .CSM file.

If the compiler runs out of disk space, it deletes the .CSM to make room for the .OBJ file, then creates a new (therefore shorter) .CSM file. If this happens, free up some disk space before compiling.


See Also

Precompiled Headers (Project Options)


alloc.h

See Also	Header Files

Declares memory-management functions (allocation, deallocation, and so on).

Functions

calloc

farcalloc

farfree

farmalloc

farrealloc

free

heapcheck

heapcheckfree

heapchecknode

heapfillfree

heapwalk

malloc

realloc

Constants, Data Types and Global Variables

NULL

ptrdiff_t

size_t


assert.h

See Also	Header Files

Defines the assert debugging macro.

Functions

assert


bios.h

See Also	Header Files

Declares various functions used in calling IBM-PC ROM BIOS routines.

Functions

_bios_equip

_bios_disk (in Borland C++ DOS Support Help)

_bios_equiplist

_bios_keybrd (in Borland C++ DOS Support Help)

_bios_memsize

_bios_serialcom (in Borland C++ DOS Support Help)

_bios_timeofday

bioscom (in Borland C++ DOS Support Help)

biosequip

bioskey (in Borland C++ DOS Support Help)

biosmemory

biosprint (in Borland C++ DOS Support Help)

biostime


conio.h

See Also	Header Files

Declares various functions used in calling the operating system console I/O routines.

Functions

cgets

clreol

clrscr

cprintf

cputs

cscanf

delline

getch

getche

getpass

gettext

gettextinfo

gotoxy

highvideo

inp

inport

inportb

inpw

insline

kbhit

lowvideo

movetext

normvideo

outp

outport

outportb

outpw

putch

puttext

_setcursortype

textattr

textbackground

textcolor

textmode

ungetch

wherex

wherey

window


See Also

EasyWin

Precompiled Headers


ctype.h

See Also	Header Files

Contains information used by the character classification and character conversion macros.

Functions and Macros

isalnum

isalpha

isascii

iscntrl

isdigit

isgraph

islower

isprint

ispunct

isspace

isupper

isxdigit

toascii

_tolower

tolower

_toupper

toupper

Constants, Data Types and Global Variables

_IS_CTL

_IS_DIG

_IS_HEX

_IS_LOW

_IS_PUN

_IS_SP

_IS_UPP


dir.h

See Also	Header Files

Contains structures, macros, and functions for working with directories and path names.

Functions

chdir

findfirst

findnext

fnmerge

fnsplit

getcurdir

getcwd

getdisk

mkdir

mktemp

rmdir

searchpath

setdisk

Constants, Data Types and Global Variables

DIRECTORY

DRIVE

EXTENSION

ffblk

FILENAME

MAXDIR

MAXDRIVE

MAXEXT

MAXFILE

MAXPATH


direct.h

See Also	Header Files

Defines structures, macros, and functions for dealing with directories and path names.

Includes

DIR.H

Functions

_chdrive

_getdcwd


dirent.h

See Also	Header Files

Declares functions and structures for POSIX directory operations.

Functions

closedir

opendir

readdir

rewinddir


dos.h

See Also	Header Files

Defines various constants and gives declarations needed for DOS and 8086-specific calls.

Functions

allocmem (in Borland C++ DOS Support Help)

bdos

bdosptr

_chain_intr

_chmod

country

ctrlbrk

delay (in Borland C++ DOS Support Help)

disable

_dos_allocmem (in Borland C++ DOS Support Help)

_dos_close

_dos_commit

_dos_creat

_dos_creatnew

dosexterr

_dos_findfirst

_dos_findnext

_dos_freemem (in Borland C++ DOS Support Help)

_dos_getdate

_dos_getdiskfree

_dos_getdrive

_dos_getfileattr

_dos_getftime

_dos_gettime

_dos_getvect

_dos_keep (in Borland C++ DOS Support Help)

_dos_open

_dos_read

_dos_setblock (in Borland C++ DOS Support Help)

_dos_setdate

_dos_setdrive

_dos_setfileattr

_dos_settime

_dos_setvect

dostounix

_dos_write

_emit_

enable

FP_OFF

FP_SEG

geninterrupt

getcbrk

getdate

getdfree

getdta

getfat

getfatd

getftime

getpsp

gettime

getvect

getverify

_harderr (in Borland C++ DOS Support Help)

_hardresume (in Borland C++ DOS Support Help)

_hardretn (in Borland C++ DOS Support Help)

inport

inportb

int86

int86x

intdos

intdosx

intr

keep (in Borland C++ DOS Support Help)

MK_FP

nosound (in Borland C++ DOS Support Help)

outport

outportb

parsfnm

peek

peekb

poke

pokeb

randbrd (in Borland C++ DOS Support Help)

randbwr (in Borland C++ DOS Support Help)

segread

setcbrk

setdate

setdta

settime

setvect

setverify

sleep

sound (in Borland C++ DOS Support Help)

unixtodos

unlink

Constants, Data Types and Global Variables

_8087

_argc

_argv

COUNTRY

date

devhdr

dfree

diskfree_t

dosdate_t

DOSERROR

dostime_t

_doserrno

dosSearchInfo

errno

_environ

fatinfo

fcb

FA_*

ffblk

_heaplen (in Borland C++ DOS Support Help)

NFDS

_osmajor

_osminor

_osversion

_ovrbuffer (in Borland C++ DOS Support Help)

_psp

REGPACK

REGS

SEEK_CUR

SEEK_END

SEEK_SET

SREGS

_stklen (in Borland C++ DOS Support Help)

time

_version

xfcb


errno.h

See Also	Header Files

Defines constant mnemonics for the error codes.

Constants, Data Types and Global Variables

_doserrno

errno

_sys_errlist

_sys_nerr

error number definitions


fcntl.h

See Also	Header Files

Defines open flags for open and similar library functions.

Functions

_fmode

_pipe

Constants

O_APPEND

O_BINARY

O_CHANGED

O_CREAT

O_DENYALL

O_DENYNONE

O_DENYREAD

O_DENYWRITE

O_DEVICE

O_EXCL

O_NOINHERIT

O_RDONLY

O_RDWR

O_TEXT

O_TRUNC

O_WRONLY


float.h

See Also	Header Files

Contains parameters for floating-point routines.

Functions

_clear87

_fpreset

_status87

Constants, Data Types and Global Variables

CW_DEFAULT

FPE_EXPLICITGEN

FPE_INEXACT

FPE_INTDIV0

FPE_INTOVFLOW

FPE_INVALID

FPE_OVERFLOW

FPE_UNDERFLOW

FPE_ZERODIVIDE

ILL_EXECUTION

ILL_EXPLICITGEN

SEGV_BOUND

SEGV_EXPLICITGEN


generic.h

See Also	Header Files

Contains macros for generic class declarations.


io.h

See Also	Header Files

Contains structures and declarations for low-level input/output routines

Functions

access

chmod

chsize

close

creat

creatnew

creattemp

dup

dup2

eof

filelength

_get_osfhandle

getftime

_InitEasyWin

ioctl

isatty

lock

locking

lseek

mktemp

open

_open_osfhandle

_pipe

read

remove

rename

_rtl_chmod

_rtl_close

_rtl_creat

_rtl_open

_rtl_read

_rtl_write

setftime

setmode

sopen

tell

umask

unlink

unlock

write

Constants, Data Types and Global Variables

ftime structure

HANDLE_MAX

fseek/lseek modes


iomanip.h

See Also	Header Files

Declares the C++ streams I/O manipulators and contains macros for creating parameterized manipulators.

Includes

IOSTREAM.H

Classes

iapply

imanip

ioapp

iomanip

oapp

omanip

sapp

smanip

Overloaded Operators

<<        >>


See Also

Precompiled headers

I/O Stream Classes


limits.h

See Also	Header Files

Contains environmental parameters, information about compile-time limitations, and ranges of integral quantities.

Constants, Data Types and Global Variables

CHAR_BIT

CHAR_MAX

CHAR_MIN

INT_MAX

INT_MIN

LONG_MAX

LONG_MIN

SCHAR_MAX

SCHAR_MIN

SHRT_MAX

SHRT_MIN

UCHAR_MAX

UINT_MAX

ULONG_MAX

USHRT_MAX


locale.h

See Also	Header Files

Declares functions that provide information specific to languages and countries.

Functions

localeconv

setlocale

Constants, Data Types and Global Variables

LC_ALL

LC_COLLATE

LC_CTYPE

LC_MONETARY

LC_NUMERIC

LC_TIME

lconv (struct)

NULL


malloc.h

See Also	Header Files

Declares memory-management functions and variables.

Includes

ALLOC.H

Functions

_heapadd

_heapchk

_heapmin

_heapset

_msize

_rtl_heapwalk

stackavail


math.h

See Also	Header Files

Declares prototypes for the math functions and math error handlers.

Functions

abs

acos, acosl

asin, asinl

atan, atanl

atan2, atan2l

atof, _atold

cabs, cabsl

ceil, ceill

cos, cosl

cosh, coshl

exp, expl

fabs, fabs

floor, floorl

fmod, fmodl

frexp, frexpl

hypot, hypotl

labs

ldexp, ldexpl

log, logl

log10, log101

_matherr,_matherrl

modf, modfl

poly, polyl

pow, powl

pow10, pow10l

sin, sinl

sinh, sinhl

sqrt, sqrtl

tan, tanl

tanh, tanhl

Constants, Data Types and Global Variables

complex (struct)

_complexl (struct)

EDOM

ERANGE

exception (struct)

_exceptionl (struct)

HUGE_VAL

M_E

M_LOG2E

M_LOG10E

M_LN2

M_LN10

M_PI

M_PI_2

M_PI_4

M_1_PI

M_2_PI

M_1_SQRTPI

M_2_SQRTPI

M_SQRT2

M_SQRT_2

_mexcep


mem.h

See Also	Header Files

Declares the memory-manipulation functions. (Many of these are also defined in string.h.)

Functions

_fmemccpy

_fmemchr

_fmemcmp

_fmemcpy

_fmemicmp

_fmemmove

_fmemset

_fmovmem

memccpy

memchr

memcmp

memcpy

memicmp

memmove

memset

movedata

movmem

setmem

Constants, Data Types and Global Variables

NULL

ptrdiff_t

size_t


memory.h

See Also	Header Files

Contains memory-manipulation functions.

Includes

MEM.H


new.h

See Also	Header Files

Provides access to the the following functions:

set_new_handler

_new_handler (global variable)


process.h

See Also	Header Files

Contains structures and declarations for the spawn... and exec... functions.

Functions

abort

_beginthread

_beginthreadNT

_c_exit

_cexit

cwait

_endthread

execl

execle

execlp

execlpe

execv

execve

execvp

execvpe

exit

_exit

getpid

spawnl

spawnle

spawnlp

spawnlpe

spawnv

spawnve

spawnvp

spawnvpe

wait

Constants, Data Types and Global Variables

P_DETACH

P_NOWAIT

P_NOWAITO

P_OVERLAY

P_WAIT


search.h

See Also	Header Files

Declares functions for searching and sorting.

Functions

bsearch

lfind

lsearch

qsort


setjmp.h

Declares the functions longjmp and setjmp and defines a type jmp_bufj that these functions use.

Functions

longjmp

setjmp

Constants, Data Types and Global Variables

jmp_buf


share.h

See Also	Header Files

Defines parameters used in functions that make use of file-sharing.

Constants, Data Types and Global Variables

SH_COMPAT

SH_DENYNO

SH_DENYNONE

SH_DENYRD

SH_DENYRW

SH_DENYWR


signal.h

See Also	Header Files

Defines constants and declarations for use by the signal and raise functions.

Functions

raise

signal

Constants, Data Types and Global Variables

predefined signal handlers

sig_atomic_t type

SIG_DFL

SIG_ERR

SIG_IGN

SIGABRT

SIGFPE

SIGILL

SIGINT

SIGSEGV

SIGTERM


stdarg.h

See Also	Header Files

Defines macros used for reading the argument list in functions declared to accept a variable number of arguments (such as vprintf, vscanf, and so on).

Macros

va_arg

va_end

va_start

Constants, Data Types and Global Variables

va_list


stddef.h

See Also	Header Files

Defines several common data types and macros.

Functions

offsetof

Constants, Data Types and Global Variables

NULL

ptrdiff_t

size_t

_threadid

wchar_t


stdio.h

See Also	Header Files

Defines types and macros needed for the standard I/O package defined in Kernighan and Ritchie and extended under UNIX System V. It defines the standard I/O predefined streams stdin, stdout, stdprn, and stderr, and declares stream-level I/O routines.

Functions

clearerr	_fstrncpy	spawnlp

fclose	ftell	spawnlpe

fcloseall	fwrite	spawnv

fdopen	getc	spawnve

feof	getchar	spawnvp

ferror	gets	spawnvpe

fflush	getw	sprintf

fgetc	_pclose	sscanf

fgetchar	perror	strerror

fgetpos	_popen	_strerror

fgets	printf	strncpy

fileno	putc	tempnam

flushall	putchar	tmpfile

fopen	puts	tmpnam

fprintf	putw	ungetc

fputc	remove	unlink

fputchar	rename	vfprintf

fputs	rewind	vfscanf

fread	rmtmp	vprintf

freopen	scanf	vscanf

fscanf	setbuf	vsprintf

fseek	setvbuf	vsscanf

fsetpos	spawnl

_fsopen	spawnle

Constants, Data Types and Global Variables

buffering modes	_F_TERM	SEEK_CUR

BUFSIZ	_F_WRIT	SEEK_END

EOF	FILE	SEEK_SET

_F_BIN	fpos_t	size_t

_F_BUF	fseek/lseek modes	stdaux

_F_EOF	_IOFBF	stderr

_F_ERR	_IOLBF	stdin

_F_IN	_IONBF	stdout

_F_LBUF	L_ctermid	stdprn

_F_OUT	L_tmpnam	SYS_OPEN

_F_RDWR	NULL	TMP_MAX

_F_READ	FOPEN_MAX


stdiostr.h

See Also	Header Files

Declares the C++ (version 2.0) stream classes for use with stdio FILE structures. You should use iostream.h for new code.

Includes

IOSTREAM.H

STDIO.H


stdlib.h

See Also	Header Files

Declares several commonly used routines such as conversion routines and search/sort routines.

Functions

abort	labs	realloc

abs	ldiv	_rotl

atexit	lfind	_rotr

atof	_lrotl	_searchenv

atoi	_lrotr	_searchstr

atol	lsearch	_splitpath

bsearch	ltoa	srand

calloc	_makepath	strtod

_crotr	malloc	strtol

div	max	_strtold

ecvt	mblen	strtoul

exit	mbstowcs	swab

_exit	mbtowc	system

fcvt	min	time

free	putenv	ultoa

_fullpath	qsort	wcstombs

gcvt	rand	wctomb

getenv	random

itoa	randomize

Constants, Data Types and Global Variables

div_t

_doserrno

environ

errno

EXIT_FAILURE

EXIT_SUCCESS

_fmode

ldiv_t

NULL

_osmajor

_osminor

RAND_MAX

size_t

sys_errlist

sys_nerr

_version

wchar_t


string.h

See Also	Header Files

Declares several string-manipulation and memory-manipulation routines.

Includes

LOCALE.H

Functions

_fmemccpy	_fstrset	strdup

_fmemchr	_fstrspn	strdup

_fmemcmp	_fstrstr	strerror

_fmemcpy	_fstrtok	_strerror

_fmemicmp	_fstrupr	stricmp

_fmemset	memccpy	strlen

_fstr*	memchr	strlwr

_fstrcat	memcmp	strncat

_fstrchr	memcpy	strncmp

_fstrcmp	memicmp	strncmpi

_fstrcpy	memmove	strncpy

_fstrcspn	memset	strnicmp

_fstrdup	movedata	strnset

_fstricmp	movmem	strpbrk

_fstrlen	setmem	strrchr

_fstrlwr	stpcpy	strrev

_fstrncat	strcat	strset

_fstrncmp	strchr	strspn

_fstrncpy	strcmp	strstr

_fstrnicmp	strcmp	strtok

_fstrnset	strcmpi	strupr

_fstrpbrk	strcoll	strxfrm

_fstrrchr	strcpy

_fstrrev	strcspn

Constants, Data Types and Global Variables

size_t


sys\locking.h

See Also	Header Files

Contains definitions for mode parameter of locking function.

Constants

LK_LOCK

LK_NBLCK

LK_NBRLCK

LK_RLCK

LK_UNLCK


sys\stat.h

See Also	Header Files

Defines symbolic constants used for opening and creating files.

Includes

SYS\TYPES.H

Functions

chmod

fstat

stat

Constants, Data Types and Global Variables

file status bits

stat structure


sys\timeb.h

See Also	Header Files

Functions

ftime

Constants, Data Types and Global Variables

timeb structure

_timezone


sys\types.h

See Also	Header Files

Constants, Data Types and Global Variables

time_t


time.h

See Also	Header Files

Defines a structure filled in by time-conversion routines asctime, localtime, and gmtime, and a type used by the routines ctime, difftime, gmtime, localtime and stime. It also provides prototypes for these routines.

Functions

asctime

clock

ctime

difftime

gmtime

localtime

mktime

randomize

stime

_strdate

strftime

_strtime

time

tzset

Constants, Data Types and Global Variables

CLK_TCK

clock_t

daylight

size_t

time_t

timezone

tm

tzname

Classes

Time classes


utime.h

See Also	Header Files

Declares the utime function and the utimbuf struct that it returns.

Function

utime

Constants, Data Types and Global Variables

time_t

utimbuf


values.h

See Also	Header Files

Defines UNIX compatible constants for limits to float and double values.

BITSPERBYTE

DMAXEXP

DMAXPOWTWO

DMINEXP

DSIGNIF

FMAXEXP

FMAXPOWTWO

FMINEXP

FSIGNIF

_FEXPLEN

HIBITI

HIBITL

HIBITS

_LENBASE

MAXDOUBLE

MAXFLOAT

MAXINT

MAXLONG

MAXSHORT

MINDOUBLE

MINFLOAT


varargs.h

See Also	Header Files

Definitions for accessing parameters in functions that accept a variable number of arguments.

These macros are compatible with UNIX System V.

Use STDARG.H for ANSI C compatibility.

Note: You can't include both STDARG.H and VARARGS.H

Macros

va_start

va_arg

va_end

Type

va_list


excpt.h

See Also	Header Files

The excpt.h header file contains the declarations and prototypes for structured exception-handling values, types, and routines. Consult the Windows API documentation for more details.


bwcc.h

See Also	Header Files

The bwcc.h header file defines the interface for Borland Windows Custom Control library (BWCC).

For details on using the Borland Windows Custom Control library, see the Borland Windows Custom Controls Reference.


_defs.h

See Also	Header Files

The _defs.h header file contains common definitions for pointer size and calling conventions.

Calling Conventions

_RTLENTRY	Specifies the calling convention used by the Standard Run-time Library.

_USERENTRY	Specifies the calling convention the Standard Run-time Library expects user-compiled functions to use for callbacks.

Export (and Size for DOS) Information

_EXPCLASS	Exports the class if you are building a DLL version of a library.

_EXPDATA	Exports the data if you are building a DLL version of a library.

_EXPFUNC	Exports the function if you are building a DLL version of a library.

Note:	These export macros are provided as examples only and should not be used to create user-defined functions.


_nfile.h

See Also	Header Files

The _nfile.h header file defines _NFILE_, which specifies the maximum number of open files you can have.

For 32-bit applications, _NFILE_ is defined as 40. For all other types of applications, _NFILE_ is defined as 20.


_null.h

See Also	Header Files

The _null.h defines the value of NULL for different memory models and applications types:

Model	Value

Flat	((void *)0)	if not C++ or Windows application

Flat	0

Tiny	0

Small	0

Medium	0

Large	0L


Using Templates

Templates, also called generics or parameterized types, let you construct a family of related functions or classes. These topics introduces the basic concept of templates:

Template Syntax

Function Templates

Class Templates

Using Template Compiler Switches

Note:	For some complete examples of templates and template-driven classes, see the source files for the ObjectWindows classes in the SOURCE\OWL directories.


Template Syntax

Using Templates

Template-declaration:

   template < template-argument-list > declaration

template-argument-list:

   template-argument

   template-argument-list, template argument

template-argument:

   type-argument

   argument-declaration

type-argument:

   class identifier

template-class-name:

   template-name < template-arg-list >

template-arg-list:

   template-arg

   template-arg-list , template-arg

template-arg:

   expression

   type-name


Function Templates

See Also	Using Templates

Consider a function max(x, y) that returns the larger of its two arguments. x and y can be of any type that has the ability to be ordered. But, since C++ is a strongly typed language, it expects the types of the parameters x and y to be declared at compile time. Without using templates, many overloaded versions of max are required, one for each data type to be supported even though the code for each version is essentially identical. Each version compares the arguments and returns the larger.

One way around this problem is to use a macro:

#define max(x,y) ((x > y) ? x : y)

However, using the #define circumvents the type-checking mechanism that makes C++ such an improvement over C. In fact, this use of macros is almost obsolete in C++. Clearly, the intent of max(x, y) is to compare compatible types. Unfortunately, using the macro allows a comparison between an int and a struct, which are incompatible.

Another problem with the macro approach is that substitution will be performed where you don't want it to be. By using a template instead, you can define a pattern for a family of related overloaded functions by letting the data type itself be a parameter:

template <class T> T max(T x, T y)

{

   return (x > y) ? x : y;

};

The data type is represented by the template argument <class T>. When used in an application, the compiler generates the appropriate function according to the data type actually used in the call:

int i;

Myclass a, b;

int j = max(i,0);       // arguments are integers

Myclass m = max(a,b);   // arguments are type Myclass

Any data type (not just a class) can be used for <class T>. The compiler takes care of calling the appropriate operator>(), so you can use max with arguments of any type for which operator>() is defined.


See Also

Implicit and Explicit Template Functions

Overriding a Template Function


Overriding a Template Function

Using Templates

The previous example is called a function template (or generic function, if you like). A specific instantiation of a function template is called a template function. Template function instantiation occurs when you take the function address, or when you call the function with defined (non-generic) data types. You can override the generation of a template function for a specific type with a non-template function:

#include <string.h>

char *max(char *x, char *y)

{

   return(strcmp(x,y)>0) ?x:y;

}

If you call the function with string arguments, it's executed in place of the automatic template function. In this case, calling the function avoided a meaningless comparison between two pointers.

Only trivial argument conversions are performed with compiler-generated template functions.

The argument type(s) of a template function must use all of the template formal arguments. If it doesn't, there is no way of deducing the actual values for the unused template arguments when the function is called.


Implicit and Explicit Template Functions

Using Templates

When doing overload resolution (following the steps of looking for an exact match), the compiler ignores template functions that have been generated implicitly by the compiler.

template<class T> T max(T a, T b)

{

        return  (a > b) ? a : b;

}

void    f(int i, char c)

{

        max(i, i);              // calls max(int ,int )

        max(c, c);              // calls max(char,char)

        max(i, c);              // no match for max(int,char)

        max(c, i);              // no match for max(char,int)

}

This code results in the following error messages:

Could not find a match for 'max(int,char)' in function f(int,char)

Could not find a match for 'max(char,int)' in function f(int,char)

If the user explicitly declares a template function, this function, on the other hand, will participate fully in overload resolution. For example,

template<class T> T max(T a, T b)

{

        return  (a > b) ? a : b;

}

   Explicit template function

int     max(int,int);           // declare max(int,int) explicitly

void    f(int i, char c)

{

        max(i, i);              // calls max(int ,int )

        max(c, c);              // calls max(char,char)

        max(i, c);              // calls max(int,int)

        max(c, i);              // calls max(int,int)

}


Class Templates

See Also	Using Templates

A class template (also called a generic class or class generator) lets you define a pattern for class definitions. Generic container classes are good examples. Consider the following example of a vector class (a one-dimensional array). Whether you have a vector of integers or any other type, the basic operations performed on the type are the same (insert, delete, index, and so on). With the element type treated as a type parameter to the class, the system will generate type-safe class definitions on the fly.

As with function templates, an explicit template class definition can be provided to override the automatic definition for a given type:

class Vector<char *> { ... };

The symbol Vector must always be accompanied by a data type in angle brackets. It cannot appear alone, except in some cases in the original template definition.

For a more complete implementation of a vector class, see the file vectimp.h in the container class library source code, found in the INCLUDE\CLASSLIB subdirectory.


See Also

Container Class Library

Eliminating Pointers in Templates

Template Arguments

Type-safe Generic Lists in Templates

Using Angle Brackets with Templates


Template Arguments

Using Templates

Although these examples use only one template argument, multiple arguments are allowed. Template arguments can also represent values in addition to data types:

template<class T, int size = 64> class Buffer { ... };

Non-type template arguments such as size can have default values. The value supplied for a non-type template argument must be a constant expression:

const int N = 128;

int i = 256;

Buffer<int, 2*N> b1;// OK

Buffer<float, i> b2;// Error: i is not constant

Since each instantiation of a template class is indeed a class, it receives its own copy of static members. Similarly, template functions get their own copy of static local variables.


Using Angle Brackets in Templates

Using Templates

Be careful when using the right angle bracket character upon instantiation:

Buffer<char, (x > 100 ? 1024 : 64)> buf;

In the preceding example, without the parentheses around the second argument, the > between x and 100 would prematurely close the template argument list.


Using Type-safe Generic Lists in Templates

Using Templates

In general, when you need to write lots of nearly identical things, consider using templates. The problems with the following class definition, a generic list class,

class GList

{

 public:

   void insert( void * );

   void *peek();

    .

    .

    .

};

are that it isn't type-safe and common solutions need repeated class definitions. Since there's no type checking on what gets inserted, you have no way of knowing what results you'll get. You can solve the type-safe problem by writing a wrapper class:

class FooList : public GList

{

 public:

   void insert( Foo *f ) { GList::insert( f ); }

   Foo *peek() { return (Foo *)GList::peek(); }

      .

      .

      .

};

This is type-safe. insert will only take arguments of type pointer-to-Foo or object-derived-from-Foo, so the underlying container will only hold pointers that in fact point to something of type Foo. This means that the cast in FooList::peek() is always safe, and you've created a true FooList. Now, to do the same thing for a BarList, a BazList, and so on, you need repeated separate class definitions. To solve the problem of repeated class definitions and be type-safe, you can once again use templates:

template <class T> class List : public GList

{

public:

   void insert( T *t ) { GList::insert( t ); }

   T *peek() { return (T *)GList::peek(); }

    .

    .

    .

};

  List<Foo> fList; // create a FooList class and an instance

                      named fList.

  List<Bar> bList; // create a BarList class and an instance

                      named bList.

  List<Baz> zList; // create a BazList class and an instance

                      named zList.

By using templates, you can create whatever type-safe lists you want, as needed, with a simple declaration. And there's no code generated by the type conversions from each wrapper class so there's no run-time overhead imposed by this type safety.


Eliminating Pointers in Templates

Using Templates

Another design technique is to include actual objects, making pointers unnecessary. This can also reduce the number of virtual function calls required, since the compiler knows the actual types of the objects. This is beneficial if the virtual functions are small enough to be effectively inlined. It's difficult to inline virtual functions when called through pointers, because the compiler doesn't know the actual types of the objects being pointed to.

template <class T> aBase

{

    .

    .

    .

 private:

  T buffer;

};

class anObject : public aSubject, public aBase<aFilebuf>

{

    .

    .

    .

};

All the functions in aBase can call functions defined in aFilebuf directly, without having to go through a pointer. And if any of the functions in aFilebuf can be inlined, you'll get a speed improvement, because templates allow them to be inlined.


Using Template Compiler Switches

Using Templates

The -Jg family of switches control how instances of templates are generated by the compiler. Every template instance encountered by the compiler will be affected by the value of the switch at the point where the first occurrence of that particular instance is seen by the compiler.

For template functions the switch applies to the function instances; for template classes, it applies to all member functions and static data members of the template class. In all cases, this switch applies only to compiler-generated template instances and never to user-defined instances. It can be used, however, to tell the compiler which instances will be user-defined so that they aren't generated from the template.

When using the -Jg family of switches, there are two basic approaches for generating template instances:

Include the function body (for a function template) or member function and static data member definitions (for a template class) in the header file that defines the particular template, and use the default setting of the template switch (-Jg). If some instances of the template are user-defined, the declarations (prototypes, for example) for them should be included in the same header but preceded by #pragma option -Jgx.

Compile all of the source files comprising the program with the -Jgx switch (causing external references to templates to be generated). In order to provide the definitions for all of the template instances, add a file (or files) to the program that includes the template bodies (including any user-defined instance definitions), and list all the template instances needed in the rest of the program to provide the necessary public symbol definitions. Compile the file (or files) with the -Jgd switch.


Main Function
The main() Function

See Also

Every C and C++ program must have a program-startup function.

Console-based programs call the main function at startup.

Windows GUI programs call the WinMain function at startup.

Where you place the startup function is a matter of preference. Some programmers place main at the beginning of the file, others at the end. Regardless of its location, the following points about main always apply.

Arguments to main

Wildcard Arguments

Using -p (Pascal Calling Conventions)

Value main( ) Returns


See Also

LibMain and DllEntryPoint

Multithread Programs

Passing File Information to Child Processes

Using Dynamic-link Libraries

WEP (Windows Exit Procedure)


Arguments to Main
Arguments to main ()

The main() Function	Example

Three parameters (arguments) are passed to main by the Borland C++ startup routine: argc, argv, and env.

argc, an integer, is the number of command-line arguments passed to main, including the name of the executable itself.

argv is an array of pointers to strings (char *[]).

-	argv[0] is the full path name of the program being run.

-	argv[1] points to the first string typed on the operating system command line after the program name.

-	argv[2] points to the second string typed after the program name.

-	argv[argc-1] points to the last argument passed to main.

-	argv[argc] contains NULL.

env is also an array of pointers to strings. Each element of env[] holds a string of the form ENVVAR=value.

-	ENVVAR is the name of an environment variable, such as PATH or COMSPEC.

-	value is the value to which ENVVAR is set, such as C:\APPS;C:\TOOLS; (for PATH) or C:\DOS\COMMAND.COM (for COMSPEC).

If you declare any of these parameters, you must declare them exactly in the order given: argc, argv, env. For example, the following are all valid declarations of arguments to main:

int main()

int main(int argc)                 /* legal but very unlikely */

int main(int argc, char * argv[])

int main(int argc, char * argv[], char * env[])]

The declaration int main(int argc) is legal, but it is very unlikely that you would use argc in your program without also using the elements of argv.

The argument env is also available through the global variable _environ..

For all platforms, argc and argv are also available via the global variables _argc and _argv.


Example of how Arguments are Passed to main( )

Here is an example that demonstrates a simple way of using these arguments passed to main:

/* Program ARGS.C */

#include <stdio.h>

#include <stdlib.h>

int main(int argc, char *argv[], char *env[]) {

   int i;

   printf("The value of argc is %d \n\n", argc);

   printf("These are the %d command-line arguments passed to"

          " main:\n\n", argc);

   for (i = 0; i < argc; i++)

      printf("   argv[%d]: %s\n", i, argv[i]);

   printf("\nThe environment string(s) on this system are:\n\n");

   for (i = 0; env[i] != NULL; i++)

      printf("   env[%d]: %s\n", i, env[i]);

   return 0;

   }

Suppose you run ARGS.EXE at the command prompt with the following command line:

   C:> args first_arg "arg with blanks" 3  4 "last but one" stop!

Notice that you can pass arguments with embedded blanks by surrounding them with quotes, as shown by "argument with blanks" and "last but one" in this example command line.

The output of ARGS.EXE (assuming that the environment variables are set as shown here) would then be like this:

The value of argc is 7

These are the 7 command-line arguments passed to main:

   argv[0]: C:\BC4\ARGS.EXE

   argv[1]: first_arg

   argv[2]: arg with blanks

   argv[3]: 3

   argv[4]: 4

   argv[5]: last but one

   argv[6]: stop!

The environment string(s) on this system are

   env[0]: COMSPEC=C:\COMMAND.COM

   env[1]: PROMPT=$p $g

   env[2]: PATH=C:\SPRINT;C:\DOS;C:\BC4

The maximum combined length of the command-line arguments passed to main (including the space between adjacent arguments and the program name itself) is

128 for DOS

260 for Win16

255 for Win32


Wildcard Arguments

The main() Function	Example

Command-line arguments containing wildcard characters can be expanded to all the matching file names, much the same way DOS expands wildcards when used with commands like COPY. All you have to do to get wildcard expansion is to link your program with the WILDARGS.OBJ object file, which is included with Borland C++.

Note:	Wildcard arguments are used only in console-mode applications.

Once WILDARGS.OBJ is linked into your program code, you can send wildcard arguments (such as *.* ) to your main function. The argument will be expanded (in the argv array) to all files matching the wildcard mask. The maximum size of the argv array varies, depending on the amount of memory available in your heap.

If no matching files are found, the argument is passed unchanged. (That is, a string consisting of the wildcard mask is passed to main.)

Arguments enclosed in quotes ("...") are not expanded.


Example of Using Wildcards Arguments with main()
Example of using Wildcard Arguments with main( )

The following commands compile the file ARGS.C and link it with the wildcard expansion module WILDARGS.OBJ, then run the resulting executable file ARGS.EXE:

BCC  ARGS.C  WILDARGS.OBJ

ARGS  C:\BC4\INCLUDE\*.H  "*.C"

When you run ARGS.EXE, the first argument is expanded to the names of all the *.H files in your Borland C++ INCLUDE directory. Note that the expanded argument strings include the entire path. The argument *.C is not expanded because it is enclosed in quotes.

In the IDE, simply specify a project file from the Project menu) that contains the following lines:

ARGS

WILDARGS.OBJ

If you prefer the wildcard expansion to be the default, modify your standard CW32?.LIB library files to have WILDARGS.OBJ linked automatically. To do so, remove SETARGV and INITARGS from the libraries and add WILDARGS. The following commands invoke the Turbo librarian (TLIB) to modify all the standard library files (assuming the current directory contains the standard C and C++ libraries and WILDARGS.OBJ):

Window Users

tlib  CW32          -setargv  +wildargs

tlib  CW32MT        -setargv  +wildargs

tlib  -setargv      +wildargs

DOS Users

tlib  cs  -setargv  +wildargs

tlib  cc  -setargv  +wildargs

tlib  cm  -setargv  +wildargs

tlib  cl  -setargv  +wildargs

tlib  ch  -setargv  +wildargs


Using --p (Pascal Calling Conventions)

The main() Function

If you compile your program using Pascal calling conventions, you must remember to explicitly declare main as a C type. Do this with the _ _cdeclkeyword, like this:

   int  _ _cdecl main(int argc, char* argv[], char* envp[])


Value Main Returns
The Value main() Returns

The main() Function

The value returned by main is the status code of the program: an int. If, however, your program uses the routine exit (or _exit) to terminate, the value returned by main is the argument passed to the call to exit (or to _exit).

For example, if your program contains the call

exit(1)

the status is 1.


Passing File Information to Child Processes

The main() Function

If your program uses the exec or spawn functions to create a new process, the new process will normally inherit all of the open file handles created by the original process. Some information, however, about these handles will be lost, including the access mode used to open the file. For example, if your program opens a file for read-only access in binary mode, and then spawns a child process, the child process might corrupt the file by writing to it, or by reading from it in text mode.

To allow child processes to inherit such information about open files, you must link your program with the object file FILEINFO.OBJ.

For example:

   BCC32 TEST.C \BC4\LIB\FILEINFO.OBJ

The file information is passed in the environment variable _C_FILE_INFO. This variable contains encoded binary information. Your program should not attempt to read or modify its value. The child program must have been built with the C++ run-time library to inherit this information correctly.

Other programs can ignore _C_FILE_INFO, and will not inherit file information.


Multithread Programs

See Also

32-bit programs can create more than one thread of execution. If your program creates multiple threads, and these threads also use the C++ run-time library, you must use the CW32MT.LIB or CW32MTI  library instead.

The multithread libraries provide the following functions which you use to create threads:

_beginthread

_beginthreadNT

The multithread libraries also provide

_endthread 	a function that terminates threads

_threadid	a global variable that contains the current identification number of the thread also known as the thread ID).

The header file stddef.h contains the declaration of _threadid.

When you compile or link a program that uses multiple threads, you must use the -WM compiler switch. For example:

   BCC32 -WM THREAD.C

Note:	Take special care when using the signal function in a multithread program. The SIGINT, SIGTERM, and SIGBREAK signals can be used only by the main thread (thread one) in a non-Win32 application. When one of these signals occurs, the currently executing thread is suspended, and control transfers to the signal handler (if any) set up by thread one. Other signals can be handled by any thread.

A signal handler should not use C++ run-time library functions, because a semaphore deadlock might occur. Instead, the handler should simply set a flag or post a semaphore, and return immediately.


See Also

Using Dynamic-link Libraries

LibMain and DllEntryPoint

The main() Function


WinMain

See Also

Syntax

int PASCAL WinMain(HINSTANCE hCurInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, int nCmdShow)

Description

This function is the main entry point for a Windows application. It must be supplied by the user.

Type	Parameter 	Description

HINSTANCE	hCurInstance 	The instance handle of the application. Each instance of an application has a unique instance handle. It is used as an argument to several Windows functions and can be used to distinguish between multiple instances of a given application.

HINSTANCE	hPrevInstance 	The handle of the previous instance of this application. This value is NULL if this is the first instance.

LPSTR 	lpCmdLine 	A far pointer to a null-terminated command-line. Specify this value when invoking the application from the program manager or from a call to WinExec.

int	nCmdShow	An integer that specifies the application's window display. Pass this value to ShowWindow.

Under Win32, there are two differences in the values passed through these parameters:

hPrevInstance always returns NULL.

lpCmdLine points to a string containing the entire command line, not just the parameters.

Return Value

The return value from WinMain is not currently used by Windows. It is useful during debugging because you can display this value upon termination of your program.


See Also

LibMain and DllEntryPoint

The main() Function

Using Dynamic-link Libraries

WEP (Windows Exit Procedure)


Using Dynamic-Link Libraries

See Also

Using DLLs in your applications reduces .EXE file size, conserves system memory, and provides more flexibility in changing, extending, or upgrading your applications. Windows supports both dynamic linking and static linking.

Creating a DLL

You create a DLL in much the same way you create an EXE:

Source files containing your code are compiled into .OBJ files

.OBJ files are linked together

The DLL, however, has no main function, and is therefore linked differently.

The following topics describe how to write a DLL:

Borland DLLs

DLLs and 16-bit Memory Models

Exporting and Importing Classes

Exporting and Importing Functions

LibMain and DllEntryPoint

WEP (Windows Exit Procedure)


See Also

TLINK

The main() Function

Multithread Programs


Static Linking

When an application uses a function from a static-link library (for example, the C run-time library), a copy of that function is bound to your application by TLINK at link time. Two applications running simultaneously that use the same function would each have their own copy of that function. It is more efficient, however, if both applications shared a single copy of the function. Dynamic linking provides this capability by resolving your application's references to external functions at run time.


Dynamic linking

When a program uses a function from a DLL, the function code is not linked into the .EXE. Instead, dynamic linking uses a two-step method:

1.	At link time, TLINK binds import records (which contain DLL and procedure-location information) to your .EXE. This temporarily satisfies any external references to DLL functions in your code. These import records are supplied by module-definition files or import libraries.

2.	At run time, the import-record information is used to locate and bind the DLL functions to your program.

With dynamic linking, your applications are smaller because

Only one copy of the function code is linked into your application.

System memory is conserved because DLL code and resources are shared among applications.


DLL

An executable library module containing functions or resources for use by applications or other DLLs. A DLL has no main function, which is the usual entry point for an application. Instead, a DLLs has multiple entry points, one for each exported function.

When a DLL is loaded by the operating system, the DLL can be shared among multiple applications; one loaded copy of the DLL is all that's necessary.


LibMain and DllEntryPoint

Using Dynamic-link Libraries (DLLs)

Syntax

int FAR PASCAL LibMain (HINSTANCE hInstance, WORD wDataSeg, WORD cbHeapSize, LPSTR lpCmdLine)

Description

You must supply the LibMain function for 16-bit programs, or the DllEntryPoint (32 bit Windows API) function for 32-bit programs as the main entry point for a DLL.

For 16-bit programs, Windows calls LibMain once, when the library is first loaded. LibMain performs initialization for the DLL.

For 32-bit programs, Windows calls DllEntryPoint each time the DLL is loaded and unloaded (it replaces WEP for 32-bit applications), each time a process attaches to or detaches from the DLL, or each time a thread within the process is created or destroyed.

DLL initialization depends almost entirely on the function of the particular DLL, but might include the following typical tasks:

Unlocking the data segment with UnlockData, if it has been declared as MOVEABLE.

Setting up global variables for the DLL, if it uses any.

The initialization code is executed only for the first application using the DLL.

The DLL startup code initializes the local heap automatically; you don't need to include code in LibMain to do this.

The following parameters (defined in windows.h) are passed to LibMain:

Parameter 	Type	Description

HANDLE	hInstance 	Instance handle of the DLL

WORD	wDataSeg 	Value of the data segment (DS) register

WORD	cbHeapSize	Size of the local heap specified in the module definition file for the DLL.

LPSTR	lpCmdLine 	A far pointer to the command line specified when the DLL was loaded.

 	 	This value is almost always null because DLLs are typically loaded automatically with no parameters. It is possible, however, to supply a command line to a DLL when it is loaded explicitly.

Return Value

On success, LibMain returns 1 (successful initialization).

On error, it returns 0 (failure in initialization).

Note:	If LibMain returns 0, Windows unloads the DLL from memory.


WEP (Windows Exit Procedure)

Using Dynamic-link Libraries (DLLs)

Syntax

   int FAR PASCAL WEP (int nParameter)

where nParameter is either

WEP_SYSTEM_EXIT	(indicates that all of Windows is shutting down)

WEP_FREE_DLL	(indicates that only this DLL is being unloaded)

Description

The exit point for a 16-bit DLL is the function WEP (Windows Exit Procedure). This function is not required in a DLL (because the Borland C++ run-time libraries provide a default), but you can supply your own WEP to perform any DLL cleanup before the DLL is unloaded from memory. Windows calls WEP just prior to unloading the DLL.

Under Borland C++, WEP does not need to be exported. Borland C++ defines its own WEP that calls your WEP (if you have defined one), and then performs system cleanup.

Return Value

WEP returns 1 to indicate success. Windows currently does not do anything with this return value.


Exporting and Importing Functions

Using Dynamic-link Libraries (DLLs)

To make your DLL functions accessible to other applications (.EXEs or other DLLs) the function names must be exported. To use exported functions, the function names must be imported.

Exporting Functions

There are two ways to export functions:

Create a module-definition file with an EXPORTS section listing all functions that will be used by other applications. The IMPDEF tool can help you do this.

Precede every function name to be exported in the DLL with the keyword _export in the function definition.

A function must be exported from a DLL before it can be imported to another DLL or application.

Importing Functions

If a Windows application module or another DLL uses functions from a DLL, you must tell the linker that you want to import the functions. There are three ways to do this:

Add an IMPORTS section to the module-definition file and list every DLL function that the module will use.

Include the import library for the DLLs when you link the module. The IMPLIB tool creates an import library for one or more DLLs.

Define your function using the _import keyword (32-bit applications only).


DLLs and 16-bit memory models

Using Dynamic-link Libraries (DLLs)

Functions in a DLL are not linked directly into a Windows application. They are called at run time instead. Calls to DLL functions, therefore, will be far calls because the DLL will have a different code segment than the application. The data used by called DLL functions also need to be far.

Suppose you have a Windows application called APP1, a DLL defined by LSOURCE1.C, and a header file for that DLL called lsource1.h. Function f1, which operates on a string, is called by the application.

If you want the function to work correctly regardless of the memory model used to compile the DLL, you need to explicitly make the function and its data far. In the header file lsource1.h, the function prototype would take this form:

   extern int _export FAR f(char FAR *dstring);

In the DLL source LSOURCE1.C, the implementation of the function would take this form:

int FAR f1(char far *dstring)

{

.

.

.

}

For the application to use the function, the function must be compiled as exportable and then exported. To accomplish this, you can either compile the DLL with all functions exportable (-WD) and list f1 in the EXPORTS section of the module-definition file, or you can flag the function with the _export keyword, as follows:

int FAR _export f1(char far *dstring)

{

.

.

.

}

If you compile the DLL under the large model (far data, far code), then you don't need to explicitly define the function or its data as far in the DLL. In the header file, the prototype would still take the form shown here because the prototype would need to be correct for a module compiled with a smaller memory model:

   extern int FAR f1(char FAR *dstring);

In the DLL, however, the function could be defined like this:

int _export f1(char *dstring)

{

.

.

.

}

Remember that before an application can use f1, it has to be imported into the application, either by listing f1 in the IMPORTS section of a module-definition file or by linking with an import library for the DLL.


Exporting and Importing Classes

Using Dynamic-link Libraries (DLLs)

To use classes in a DLL, the class must be exported from the .DLL file and imported by the .EXE file. Conditionalized macro expansion can be used to support both of these circumstances. For example, include something similar to the following code in a header file:

#if defined (BUILDING_YOUR_DLL)

   #define _YOURCLASS _export

#elif defined(USING_YOUR_DLL)

   #define _YOURCLASS _import

#else

   #define _YOURCLASS

#endif

In your definitions, define your classes like this:

class _YOURCLASS class1 {

// ...

};

Define BUILD_YOUR_DLL (with the -D option, for example) when you are building your DLL. The _YOURCLASS macro will expand to _import. Define USE_YOUR_DLL when you are building the .EXE which will use the DLL. The _YOURCLASS macro will expand to _import.


Static Data in 16-bit DLLs

See Also	Using Dynamic-link Libraries (DLLs)

Through the functions in a DLL, all applications using the DLL have access to the global data in the DLL. In 16-bit DLLs, a particular function will use the same data, regardless of the application that called it (unlike 32-bit DLLs where all data is private to the process). If you want a 16-bit DLL's global data to be protected for use by a single application, you need to write that protection yourself. The DLL itself does not have a mechanism for making global data available to a single application. If you need data to be private for a given caller of a DLL, you need to dynamically allocate the data and manage the access to that data manually. Static data in a 16-bit DLL is global to all callers of a DLL.


See Also

TLINK


Borland DLLs

General forms of compiler and linker command lines that use the DLL versions of the Borland run-time libraries and class libraries are described below.

Here is a 16-bit compile and link using the DLL version of the run-time library:

bcc -c -D_RTLDLL -ml source.cpp

tlink -C -Twe c0wl source, , , import crtldll

Note that the macro _RTLDLL and the -ml switch are used.

Here is the 32-bit version:

bcc32 -c -D_RTLDLL source.cpp

tlink32 -Tpe -ap c0x32 source, , , import32 cw32i

Here is a 16-bit compile and link using the DLL version of the class library:

bcc -c -D_BIDSDLL -ml source.cpp

tlink -C -Twe c0wl source, , , import bidsi crtldll

Here is a 32-bit compile and link using the DLL version of the class library:

bcc32 -c -D_BIDSDLL source.cpp

tlink32 -Tpe -ap c0x32 source, , , import32 bidsfi cw32i


C++ Exception Handling

See Also

These topics describe the C++ error-handling mechanism generally referred to as exception handling. The Borland C++ implementation is consistent with the proposed ANSI specification.

Throwing an Exception

Handling an Exception

Exception Specifications

Constructors and Destructors in Exception Handling

Unhandled Exceptions

Setting Exception Handling Options

The C++ language defines a standard for exception handling. The standard insures that the power of object-oriented design is supported throughout your program. An especially strong feature of the standard is the availability of virtual functions and the use of objects to define exceptions. Virtual functions guarantee a minimum of runtime overhead--zero additional program overhead if no exceptions are thrown.

In accordance with ANSI specifications, Borland C++ supports the termination exception-handling model. When an abnormal situation arises at runtime, the program should terminate. However, throwing an exception allows you to gather information at the throw point that could be useful in diagnosing the causes which led to failure. You can also specify in the exception handler the actions to be taken before the program terminates. Only synchronous exceptions are handled, meaning that the cause of failure is generated from within the program. An event such as Control-C (which is generated from outside the program) is not considered to be an exception.

When the program encounters an abnormal situation for which it is not designed, you may transfer control to some other part of the program that is designed to deal with the problem. This is done by throwing an exception.

The exception-handling mechanism requires the use of three keywords: try, catch, and throw. The try-block specified by try must be followed immediately by the handler specified by catch. If an exception is thrown in the try-block, program control is transferred to the appropriate exception handler. The program should attempt to catch any exception that is thrown by any function. Failure to do so could result in abnormal termination of program.

Although C++ allows an exception to be of any type, it is useful to make exceptions objects. The exception object is treated exactly the way any object would. An exception carries information from the point where the exception is thrown to the point where the exception is caught. This is information that the program user will want to know when the program encounters some anomaly at runtime.


See Also

new (keyword)

xalloc


See Also

C-Based Structured Exceptions

Constructors and Destructors in Exception Handling

Exception Specifications

Handling an Exception

Setting Exception Handling Options

Throwing an Exception

Unhandled Exceptions

Using C-Based Exceptions in C++ Programs


Throwing an Exception

See Also	Example	C++ Exception Handling

A block of code in which an exception can occur must be prefixed by the keyword try. Following the try keyword is a block of code enclosed by braces. This indicates that the program is prepared to test for the existence of exceptions. If an exception occurs, the program flow is interrupted. The sequence of steps taken is as follows:

The program searches for a matching handler

If a handler is found, the stack is unwound to that point

Program control is tranferred to the handler

If no handler is found, the program will call the terminate function. If no exceptions are thrown, the program executes in the normal fashion.

A throw expression is also referred to as a throw-point. You can specify whether an exception may be thrown by using one of the following syntax specifications:

When an exception occurs, the throw expression initializes a temporary object of the type T (to match the type of argument arg) used in throw(T arg). Other copies can be generated as required by the compiler. Consequently, it can be useful to define a copy constructor for the exception object.


Example 1

throw throw_object;

This example specifies that throw_object is to be passed to a handler.

Example 2

throw;

This example simply specifies that the last exception thrown is to be thrown again. An exception must currently exist. Otherwise, terminate is called.

Example 3

void my_func1() throw (A, B)

{

    // Body of function.

}

This example specifies a list of exceptions that my_func1 can throw. No other exceptions will propagate out of my_func1. If an exception other than A or B is generated within my_func1, it is considered to be an unexpected exception and program control will be transferred to the unexpected function.

Example 4

void my_func2() throw ()

{

     // Body of this function.

}

The final case specifies that my_func2 will throw no exceptions. If any function in the body of my_func2 throws an exception, such an exception will not exist beyond the body of my_func2.


Handling an Exception

See Also	Examples	C++ Exception Handling

The exception handler is indicated by the catch keyword. The handler must be used immediately after the try-block. The keyword catch can also occur immediately after another catch. Each handler will only evaluate an exception that matches, or can be converted to, the type specified in its argument list.

Every exception thrown by the program must be caught and processed by the exception handler. If the program fails to provide an exception handler for a thrown exception, the program will call terminate.

Exception handlers are evaluated in the order that they are encountered. An exception is caught when its type matches the type in the catch statement. Once a type match is made, program control is transferred to the handler. The stack will have been unwound upon entering the handler. The handler specifies what actions should be taken to deal with the program anomaly.

A goto statement can be used to transfer program control out of a handler but such a statement can never be used to enter a handler.

After the handler has executed, the program can continue at the point after the last handler for the current try-block. No other handlers are evaluated for the current exception.


Examples

Example 1

Example 2


Example 1

try {

   // Include any code that might throw an exception

}

catch (T X)

{

  // Take some actions

}

This example is specifically defined to handle an object of type T. If the argument is T, T&, const T, or const T&, the handler will accept an object of type X if any of the following are true:

T and X are of the same type

T is an accessible base class for X in the throw expression

T is a pointer type and X is a pointer type that can be converted to T by a standard pointer conversion in the throw expression


Example 2

try {

   // Include any code that might throw an exception

}

catch ( ... )

{

  // Take some actions

}

The statement catch ( ... ) will handle any exception, regardless of type. This statement, if used, must be the last handler for its try-block.


Exception Specifications

See Also	Examples	C++ Exception Handling

The C++ language makes it possible for you to specify any exceptions that a function can throw. This exception specification can be used as a suffix to the function declaration. The syntax for exception specification is as follows:

exception-specification:

   throw (type-id-listopt)

   type-id-list:

   type-id

   type-id-list, type-id

The function suffix is not considered to be part of the function's type. Consequently, a pointer to a function is not affected by the function's exception specification. Such a pointer checks only the function's return and argument types. Therefore, the following is legal:

void f2(void) throw();      // Should not throw exceptions

void f3(void) throw (BETA); // Should only throw BETA objects

void (* fptr)();            // Pointer to a function returning void

fptr = f2;

fptr = f3;

Extreme care should be taken when overriding virtual functions. Again, because the exception specification is not considered part of the function type, it is possible to violate the program design.

If an exception is thrown which is not listed in the exception specification, the unexpected function will be called.


See Also

C++ Exception Handling

set_terminate

set_unexpected

terminate_function (type)

unexpected_function (type)

unexpected


Examples

Example 1

Example 2

Example 3


Example 1

In the following example, the derived class BETA::vfunc is defined so that it should not throw any exceptions--a departure from the original function declaration.

class ALPHA {

public:

   struct ALPHA_ERR {};

   virtual void vfunc(void) throw (ALPHA_ERR) {}; // Exception specification

};

class BETA : public ALPHA {

   void vfunc(void) throw() {};  // Exception specification is changed

};

The following are examples of functions with exception specifications.

void f1();                // The function can throw any exception

void f2() throw();        // Should not throw any exceptions

void f3() throw( A, B* ); // Can throw exceptions publicly derived from A,

                          // or a pointer to publicly derived B

The definition and all declarations of such a function must have an exception specification containing the same set of type-id's. If a function throws an exception not listed in its specification, the program will call unexpected. This is a runtime issue--it will not be flagged at compile time. Therefore, care must be taken to handle any exceptions which can be thrown by elements called within a function.


Example 2

// HOW TO MAKE EXCEPTION-SPECIFICATIONS AND HANDLE ALL EXCEPTIONS

#include <iostream.h>

class ALPHA{};                // EXCEPTION DECLARATION

ALPHA _a;

void f3(void) throw (ALPHA) { // WILL THROW ONLY TYPE-ALPHA OBJECTS

   cout << "f3() was called" << endl;

   throw(_a);

   }

void f2(void) throw() {       // SHOULD NOT THROW EXCEPTIONS

   try {                      // WRAP ALL CODE IN A TRY-BLOCK

      cout << "f2() was called" << endl;

      f3();

      }

   catch ( ... ) {            // TRAP ALL EXCEPTIONS

      cout << "f2() has elements with exceptions!" << endl;

      }

   }

int main(void) {

   try {

      f2();

      return 0;

      }

   catch ( ... ) {

      cout << "Need more handlers!";

      return 1;

      }

   }

Output

f2() was called

f3() was called

f2() has elements with exceptions!


Example 3

The following examples illustrate the sequence of events which can occur when unexpected is called.

Program behavior when a function is registered with set_unexpected():

unexpected()  // CALLED AUTOMATICALLY

  |

  |

  |                // DEFINE YOUR UNEXPECTED HANDLER

  |               unexpected_function my_unexpected( void )

  |               {

  |                  // DEFINE ACTIONS TO TAKE

  |                  // POSSIBLY MAKE ADJUSTMENTS

  |               }

  |

  |               // REGISTER YOUR HANDLER

  |               set_unexpected( my_unexpected );

  |

my_unexpected();

Program behavior when no function is registered with set_unexpected() but there is a function registered with set_terminate():

unexpected()  // CALLED AUTOMATICALLY

  |

  |

  |          // DEFINE YOUR TERMINATION SCHEME

  |          terminate_function my_terminate( void )

  |             {

  |             // TAKE ACTIONS BEFORE TERMINATING

  |             // SHOULD NOT THROW EXCEPTIONS

  |             exit(1); // MUST END SOMEHOW.

  |             }

  |

  |          // REGISTER YOUR TERMINATION FUNCTION

  |          set_terminate( my_terminate )

  |

terminate()

  |

my_terminate()

// PROGRAM ENDS.


Constructors and Destructors in Exception Handling

See Also	C++ Exception Handling

When an exception is thrown, the copy constructor is called for the exception. The copy constructor is used to initialize a temporary object at the throw point. Other copies may be generated by the program.

When program flow is interrupted by an exception, destructors are called for all automatic objects which were constructed since the beginning of the the try-block was entered. If the exception was thrown during construction of some object, destructors will be called only for those objects which were fully constructed. For example, if an array of objects was under contruction when an exception was thrown, destructors will be called only for the array elements which were already fully constructed.

The effect of calling destructors for automatic objects is referred to as stack unwinding. Stack unwinding always occurs. Destructors are called by default but the default can be switched off.


Unhandled Exceptions

See Also	C++ Exception Handling

If an exception is thrown and no handler is found it, the program will call the terminate function. This example illustrates the series of events that can occur when the program encounters an exception for which no handler can be found.

terminate();

  .

  .

  .

abort();  // PROGRAM ENDS.


Setting Exception Handling Options

See Also	C++ Exception Handling

Command-Line
IDE Setting	Switch

Enable exception handling	-x

Enable destructor cleanup	-xd

Enable throwing exceptions from a DLL	-xds

Enable exception location information	-xp


C-Based Structured Exceptions

See Also

Borland C++ provides support for program development that makes use of structured exceptions. You can compile and link a C source file that contains an implementation of structured exceptions. In a C program, the ANSI-compatible keywords used to implement structured exceptions are _ _except, _ _finally, and _ _try.

Note:	The _ _finally and _ _try keywords can appear only in C programs.

try-except Exception-Handling Syntax

For try-except exception-handling implementations the syntax is as follows:

try-block:

  _ _try compound-statement (in a C module)

  try compound-statement (in a C++ module)

handler:

  _ _except (expression) compound-statement

try-finally Termination Syntax

For try-finally termination implementations the syntax is as follows:

try-block:

  _ _try compound-statement

termination:

  _ _finally compound-statement

See your Win32 documentation for additional details on the implementation of structured exceptions for 16- and 32-bit platforms.


See Also

C++ Exception Handling

__except

__finally

_ _try (keyword)

Using C-Based Exceptions in C++ Programs


Using C-Based Exceptions in C++ Programs

See Also	Example

Borland C++ allows substantial interaction between C and C++ error handling mechanisms. The following interactions are supported:

C structured exceptions can be used in C++ programs.

C++ exceptions cannot be used in a C program because C++ exceptions require that their handler be specified by the catch keyword and catch is not allowed in a C program.

An exception generated by a call to the RaiseException function is handled by a try/_ _except or _ _try/_ _except block. All handlers of try/catch blocks are ignored when RaiseException is called.

The following C exception helper functions can be used in a C and C++ programs:

GetExceptionCode

GetExceptionInformation

SetUnhandledExceptionFilter

UnhandledExceptionFilter

Borland C++ does not enforce the use of UnhandledExceptionFilter function only in the except filter of _ _try/_ _except or try/_ _except blocks. However, program behavior is undefined when this function is called outside of the _ _try/_except or try/_ _except block.

The full functionality of an _ _except block is allowed in C++. If an exception is generated in a C module, it is possible to provide a handler-block in a separate calling C++ module. If no handler is found in the calling module, the default action is to terminate the program.

If a handler can be found for the generated structured exception, the following actions can be taken:

execute the actions specified by the handler

ignore the generated exception and resume program execution

continue the search for some other handler (regenerate the exception)

These actions are consistent with the design of structured exceptions.

The _ _try/_ _finally ensures that the code in the _ _finally block is executed no matter how the flow within the _ _try exits. The _ _finally keyword is not allowed in a C++ program and the _ _try/_ _finally block is not supported in a C++ program.

Even though the _ _try/_ _finally block is not supported in a C++ program, a C-based exception generated by the operating system or the program can still result in proper stack unwinding by using local objects within destructors. Any module compiled with the -xd compiler option will have destructors invoked for all objects with auto storage. Stack unwinding occurs from the point where the exception is thrown to the point where the exception is caught.


See Also

C-Based Structured Exceptions

C++ Exception Handling


C-Based Exceptions in C++ Programs Example

/* In PROG.C */

void func(void) {

   .

   .

   .

   /* generate an exception */

   RaiseException( /* specifiy your arguments */ );

   .

   .

   .

}

// In CALLER.CPP

// How to test for C++ or C-based exceptions.

#include <excpt.h>

#include <iostream.h>

int main(void) {

   try

   {            // test for C++ exceptions

      try

      {         // test for structured exceptions

         func();

      }

      __except( /* filter-expression */ )

      {

      cout << "A structured exception was generated.";

   .

   .

   .

      /* specify actions to take for this structured exception */

      return -1;

      }

      return 0;

   }

   catch ( ... )

   {

   // handler for any C++ exception

   cout << "A C++ exception was thrown.";

   return 1;

   }

}


International API

See Also

Borland C++ provides support for international program development. Currently, support is provided for the Great Britain and United States English, French, and German locales. Future releases of Borland C++ will increase the number of locales supported.

To illustrate the effects of selecting different locales, Borland C++ provides a sample ObjectWindows application named INTLDEMO.EXE.

The LOCALE.BLL file is installed in BC4\BIN directory.

Support for these locales is contained in the LOCALE.BLL library. By default, the C locale is in effect. A call to setlocale will

dynamically link the LOCALE.BLL library to your program.

enable a locale-specific module.

specify which character set (also called code page or code set) to use with the locale

You can query the locale settings by using localeconv and setlocale functions.

If the call to setlocale can be resolved, several character-handling functions change their behavior.

Note:	Because the Borland C++ international API currently supports only 8-bit characters (thereby enabling recognition of as many as 256 characters), only single-byte character-handling functions are affected.  For a list of affected functions, see International API Routines.

In your code, you must #define _ _USELOCALES_ _ to have the locale-sensitive functions available. Otherwise, only the C type locale macros will be used.


See Also

International API Routines.

International API Sample Program


International API Sample Program (ANSI character set)

See Also

To illustrate the effects of selecting different locales, Borland C++ provides a sample ObjectWindows application named INTLDEMO.EXE

INTLDEMO is located in BC4\EXAMPLES\OWLAPPS\INTLDEMO which includes all source code and a project file.

Note:	You must install ObjectWindows before you can build INTLDEMO.EXE.

It demonstrates how the setlocale function can produce an internationally aware Windows application.

The program lets you choose to display the user interface in English, French, or German.

ANSI Character Set

INTLDEMO displays the Windows ANSI character set (also referred to as the WIN 1252 character set) in a 16-by-16 character grid.

Characters are highlighted according to the selections under the Locale and Classification menus. When you run INTLDEMO, the screen shows the default C locale, and the default classification is isalpha. The highlighted characters are A to Z and a to z. If you select another locale such as French, the accented versions of the characters are also highlighted. Various combinations of locale and classification can be illustrated by selecting the appropriate menu items.

File Menu

Choose File|List to open a dialog box that demonstrates the effects of the locale on

collation sequences

date and time functions

The files in the current directory are sorted according to the current locale. File dates and times display according to the conventions in the language of the selected locale.

File names can be switched between upper and lower case to demonstrate the effects of the toupper and tolower functions in the current locale. The dialog also illustrates the effects of the BWCCIntlInit function on the OK, Cancel, and Help buttons of the dialog.

You can select any file in the directory to view and sort its contents according to the locale collation sequence currently selected.

Conventions Menu

Choose Conventions|Show to display the results of calling the localeconv function for the current locale. For example, if you select the French locale, the international currency symbol becomes FRF and the currency symbol becomes F.

Note:	If you keep the Conversions window open as you select a new language or locale, its values are updated immediately.

Language Menu

Use the Language menu to change the language of the user interface. This feature uses ObjectWindows to associate windows interface elements to a module, in this case a .DLL that contains the resources in a particular language.

When you change the language, the program loads a new language DLL and then reloads the interface elements from the new DLL.

Note:	Date and times in the File List dialog are not affected by the change in language, but by the choice of locale.

Classification Menu

Use the Classification menu to see a list of the locale-sensitive is....() functions. Selecting one of these items will highlight characters in the main window that return true for the selected function in the current locale.


See Also

Classification Routines

International API Routines.


Library Routines, by Category
Borland C++ Library Routines, by Category

See Also	Overview

If you know the name of the function you want Help on, see:

Borland C++ Library Routines, by Name

Otherwise, if you do not know the name of a particular function, but you know what type of action it performs, choose one of the following categories:

Classification Routines

Console I/O Routines

Conversion Routines

Diagnostic Routines

Directory Control Routines

EasyWin Routines

Inline Routines

Input/output Routines

Interface Routines

International API Routines

Manipulation Routines

Math Routines

Memory Routines

Miscellaneous Routines

Obsolete Functions

Process Control Routines

Time and Date Routines

Variable Argument List Routines


See Also

Default Run-time Libraries

Dynamic-link Libraries

Library Routines, by Name

Reasons to Access the Run-time Library Source Code

Static Run-time Libraries


Borland C++ has several hundred classes, functions, and macros that you call from within your C and C++ programs to perform a wide variety of tasks, including low- and high-level I/O, string and file manipulation, memory allocation, process control, data conversion, mathematical calculations, and much more. These classes, functions, and macros are collectively referred to as library routines.


Reasons To Access the Run-time Library Source Code

See Also

Here are some reasons why you might want to obtain the source code for run-time library routines:

To write a function similar to, but not the same as, a Borland C++ function.  With access to the run-time library source code, you can tailor the library function to suit your needs, and avoid having to write a separate function of your own.

To know more about the internals of a library function when you debug your code.

To delete the leading underscores on C symbols.

To learn programming techniques by studying tight, professionally written library source code.

Because Borland believes strongly in the concept of open architecture, the Borland C++ run-time library source code is available for licensing. Just fill out the order form distributed with your Borland C++ package, include your payment, and Borland will ship you the Borland C++ run-time library source code.


See Also

Dynamic-link Libraries

Static Run-time Libraries


Guidelines for Selecting Run-Time Libraries

See Also	Overview

Use the following guidelines when selecting which run-time libraries to use:

16-bit DLLs are supported only in the large memory model.

For 32-bit programs, only the flat memory model is supported.

32-bit console and GUI programs require different startup code.

Multithread applications are supported only in 32-bit programs.


Run-time Libraries Overview

Borland C++ has several hundred classes, functions, and macros that you call from within your C and C++ programs to perform a wide variety of tasks, including low- and high-level I/O, string and file manipulation, memory allocation, process control, data conversion, mathematical calculations, and much more. These classes, functions, and macros are collectively referred to as library routines.

The Borland C++  run-time libraries are divided into static (OBJ and LIB) and dynamic-link (DLL) versions.

Static libraries are located in the LIB subdirectory of your installation.

Dynamic-link libraries are located in the BIN subdirectory of your installation.

Several versions of the run-time libraries are available. For example, there are specific versions for each memory-model, debugging, and 16- and 32-bit versions. There are also optional libraries to provide mathematics, containers, ObjectWindows development, and international applications.


See Also

Default Run-time Libraries

Dynamic-link Libraries

Obsolete Functions

Reasons to Access the Run-time Library Source Code

Static Run-time Libraries


Static Run-time Libraries

See Also	Legend	Overview

Listed below are each of the Borland C++ static library names, the operating environment in which it is available, and its use.

File name	Environment	Use

Directory of BC45\LIB

BIDSI.LIB	Win 16	16-bit dynamic BIDS import library for BIDS45.DLL

BIDSF.LIB	Win32s, Win32	32-bit BIDS library

BIDSFI.LIB	Win32s, Win32	32-bit dynamic BIDS import library for BIDS45F.DLL

BIDS?.LIB	Win 16	16-bit BIDS library

BWCC.LIB	Win 16	16-bit import library for BWCC.DLL

BWCC32.LIB	Win32s, Win32	32-bit import library for BWCC32.DLL

C0D32.OBJ	Win32s, Win32	32-bit DLL startup module

C0D?.OBJ	Win 16	16-bit DLL startup module

C0W32.OBJ	Win32s, Win32	32-bit GUI EXE startup module

C0W?.OBJ	Win 16	16-bit EXE startup module

C0X32.OBJ	Win32	32-bit console-mode EXE startup module

CRTLDLL.LIB	Win 16	16-bit dynamic import library for BC45RTL.DLL

CT.LIB	DOS	tiny library (DOS only)

CW32.LIB 	Win32s, Win32	32-bit GUI single-thread library

CW?.LIB	Win 16	16-bit library

CW32I.LIB	Win32s, Win32	32-bit single-thread, GUI, dynamic RTL import library for CW3215.DLL

CW32MT.LIB	Win32 	32-bit GUI multithread library

CW32MTI.LIB	Win32 	32-bit multithread, GUI, dynamic RTL import library for CW3215MT.DLL

IMPORT.LIB	Win 16	16-bit import library

IMPORT32.LIB	Win32s, Win32	32-bit import library

MATHW?.LIB	Win 16	16-bit math libraries

NOEH?.LIB	16-bit DOS, DPMI16	Eliminate exception handling code in run-time libraries

NOEHW?.LIB	Win 16, DPMI16	Eliminate exception handling code in run-time libraries

W32SUT16.LIB	Win 16	16-bit universal thunking library

W32SUT32.LIB	Win32s	32-bit universal thunking library

OBSOLETE.LIB	Win 16, Win32, Win32s	Provides obsolete global variables.

Directory of BC45\LIB\16-BIT

FILES.C	Win 16	Increases the number of file handles

FILES2.C	Win 16	Increases the number of file handles

MATHERR.C	Win 16	Sample of a user-defined floating-point math exception handler for float and double types

MATHERRL.C	Win 16	Sample of a user-defined floating-point math exception handler for long double type

WILDARG.OBJ	Win 16 	Transforms wild-card arguments into an array of arguments to main() in console-mode applications

Directory of BC45\LIB\32-BIT

FILES.C	Win32s, Win32	Increases the number of file handles

FILES2.C 	Win32s, Win32	Increases the number of file handles

FILEINFO.OBJ	Win32s, Win32	Passes open file-handle information to child processes

GP.OBJ	Win32s, Win32	Prints register-dump information when an exception occurs

MATHERR.C	Win32s, Win32	Sample of a user-defined floating-point math exception handler for float and double types

MATHERRL.C	Win32s, Win32	Sample of a user-defined floating-point math exception handler for long double type

WILDARGS.OBJ	Win32 	Transforms wild-card arguments into an array of arguments to main() in console-mode applications

Directory of BC45\LIB\STARTUP

BUILD-C0.BAT	Win 16	Batch file to build C0D?.OBJ, C0F?.OBJ, and C0W?.OBJ

C0.ASM	DOS	Source for C0?.OBJ

C0D.ASM	Win 16	Source for C0D?.OBJ

C0W.ASM	Win 16	Source for C0W?.OBJ

RULES.ASI	Win 16	Assembly rules for C0D.ASM and C0W.ASM


Legend

Each memory model has its own library file and math file that contain versions of the routines written for that particular model.

The ? placeholder in each of the library file names represents one of the supported memory models (S = small, M = Medium, C = compact, and L = large).

For example, the available versions of the 16-bit DLL startup module (C0D?.OBJ ) are:

C0DS.OBJ	(small)

C0DM.OBJ	(medium)

C0DC.OBJ	(compact)

C0DL.OBJ	(large)


See Also

Default Run-time Libraries

Dynamic-link Libraries

Guidelines for Selecting Run-Time Libraries

Library Routines, by Category

Library Routines, by Name

Obsolete Functions

Reasons to Access the Run-time Library Source Code


Dynamic-link Libraries

See Also	Overview

The dynamic-link library (DLL) version of the run-time library is contained in the BIN subdirectory of your installation. Several versions of the dynamic-link libraries are available. For example, there are 16- and 32-bit specific versions, and versions that support multithread applications.

In the 16-bit specific version, only the large-memory model DLL is provided. No other memory-model is supported in a 16-bit DLL.

Listed below are each of the Borland C++  DLL names, the operating environment in which it is available, and its use.

Directory: BC45\BIN

File Name	Environment	Use

BC450RTL.DLL 	Win 16	16-bit, large-memory model

BIDS45.DLL	Win 16	16-bit BIDS

BIDS45F.DLL	Win32s, Win32	32-bit BIDS

CW3215.DLL	Win32s, Win32	32-bit, single thread, GUI mode

CW3215MT.DLL	Win32 	32-bit, multithread, GUI mode

LOCALE.BLL	Win 16, Win32s, Win32	Locale library


See Also

Default Run-time Libraries

Guidelines for Selecting Run-Time Libraries

Library Routines, by Category

Library Routines, by Name

Obsolete Functions

Reasons to Access the Run-time Library Source Code

Static Run-time Libraries


Default Run-Time Libraries

See Also	Overview

The following table identifies the default run-time libraries used with each compiler.

Compiler	Environment	Default Libraries
BCC.EXE	16 bit Windows	C0WS.OBJ, CWS.LIB, MATHWS.LIB, IMPORT.LIB
BCC32.EXE	Win32 and Win32s	C0W32.OBJ, CW32.LIB, IMPRTW32.LIB
BCW.EXE	16 bit Windows	Same as BCC.EXE
BCW32.EXE	Win32 and Win32s	Same as BCC32.EXE


See Also

Dynamic-link Libraries

Library Routines, by Category

Library Routines, by Name

Obsolete Functions

Reasons to Access the Run-time Library Source Code

Static Run-time Libraries


C++ Prototyped Routines

See Also

Certain routines described in this book have multiple declarations. You must choose the prototype appropriate for your program. In general, the multiple prototypes are required to support the original C implementation and the stricter and sometimes different C++ function declaration syntax. For example, some string-handling routines have multiple prototypes because in addition to the ANSI-C specified prototype, Borland C++ provides prototypes consistent with the ANSI C++ draft.

Function	Header

getvect	dos.h

max	stdlib.h

memchr	string.h

min	stdlib.h

setvect	dos.h

strchr	string.h

strpbrk	string.h

strrchr	string.h

strstr	string.h


See Also

string.h

Header Files Summary

Library Routines, by Category

Library Routines, by Name


Classification Routines

See Also

The following routines classify ASCII characters as letters, control characters, punctuation, uppercase, and so.

These routines are all declared in ctype.h.

isalnum	islower

isalpha	isprint

isascii	ispunct

iscntrl	isspace

isdigit	isupper

isgraph	isxdigit


See Also

Header Files Summary

Library Routines, by Category

Library Routines, by Name


Console I/O Routines

See Also

The following routines output text to the screen or read from the keyboard. They cannot be used in a GUI application.

Function	Header	Function	Header

cgets	conio.h	movetext	conio.h

clreol	conio.h	normvideo	conio.h

clrscr	conio.h	putch	conio.h

cprintf	conio.h	puttext	conio.h

cputs	conio.h	_setcursortype	conio.h

delline	conio.h	textattr	conio.h

getpass	conio.h	textbackground	conio.h

gettext	conio.h	textcolor	conio.h

gettextinfo	conio.h	textmode	conio.h

gotoxy	conio.h	ungetc	stdio.h

highvideo	conio.h	wherex	conio.h

insline	conio.h	wherey	conio.h

lowvideo	conio.h	window	conio.h


See Also

conio.h

Header Files Summary

Library Routines, by Category

Library Routines, by Name


Conversion Routines

See Also

The following routines convert characters and strings from

alpha to different numeric representations (floating-point, integers, longs)

numeric to alpha representations

uppercase to lowercase (and vice versa).

Function	Header	Function	Header

atof	stdlib.h	strtol	stdlib.h

atoi	stdlib.h	_strtold	stdlib.h

atol	stdlib.h	strtoul	stdlib.h

ecvt	stdlib.h	toascii	ctype.h

fcvt	stdlib.h	_tolower	ctype.h

gcvt	stdlib.h	tolower	ctype.h

itoa	stdlib.h	_toupper	ctype.h

ltoa	stdlib.h	toupper	ctype.h

strtod	stdlib.h	ultoa	stdlib.h


See Also

ctype.h

stdlib.h

time.h

Header Files Summary

Library Routines, by Category

Library Routines, by Name


Diagnostic Routines

See Also

The following routines provide built-in troubleshooting capability.

Function	Header

assert	assert.h

_matherr	math.h

_matherrl	math.h

perror	errno.h


See Also

assert.h

errno.h

math.h

Header Files Summary

Library Routines, by Category

Library Routines, by Name


Directory Control Routines

See Also

The following routines manipulate directories and path names.

Function	Header	Function	Header

chdir	dir.h	_getdcwd	direct.h

_chdrive	direct.h	getdisk	dir.h

closedir	dirent.h	_makepath	stdlib.h

_dos_findfirst	dos.h	mkdir	dir.h

_dos_findnext	dos.h	mktemp	dir.h

_dos_getdiskfree	dos.h	opendir	direct.h

_dos_getdrive	dos.h	readdir	dirent.h

_dos_setdrive	dos.h	rewinddir	dirent.h

findfirst	dir.h	rmdir	dir.h

findnext	dir.h	_searchenv	stdlib.h

fnmerge	dir.h	searchpath	dir.h

fnsplit	dir.h	_searchstr	stdlib.h

_fullpath	stdlib.h	setdisk	dir.h

getcurdir	dir.h	_splitpath	stdlib.h

getcwd	dir.h


See Also

dir.h

direct.h

dirent.h

dos.h

stdlib.h

stdio.h

Header Files Summary

Library Routines, by Category

Library Routines, by Name


EasyWin Routines

See Also

The following routines are portable to EasyWin programs, but are not available in Windows 16-bit programs. They are provided to help you port DOS programs into a Windows 16-bit applications.

Function	Header	Function	Header

clreol	conio.h	printf	stdio.h

clrscr	conio.h	putch	conio.h

fgetchar	stdio.h	putchar	stdio.h

getch	stdio.h	puts	stdio.h

getchar	stdio.h	scanf	stdio.h

getche	stdio.h	vprintf	stdio.h

gets	stdio.h	vscanf	stdio.h

gotoxy	conio.h	wherex	conio.h

kbhit	conio.h	wherey	conio.h

perror	errno.h


See Also

EasyWin

Converting DOS Applications to Windows

Using EasyWin from within a Windows Program

_InitEasyWin

Header Files Summary

Library Routines, by Category

Library Routines, by Name


Inline Routines

See Also

The following routines have inline versions. The compiler will generate code for the inline versions when you use #pragma intrinsic or if you specify program optimization..

Function	Header	Function	Header

abs	math.h	stpcpy	string.h

alloca	malloc.h	strcat	string.h

_crotl	stdlib.h	strchr	string.h

_crotr	stdlib.h	strcmp	string.h

_lrotl	stdlib.h	strcpy	string.h

_lrotr	stdlib.h	strlen	string.h

memchr	mem.h	strncat	string.h

memcmp	mem.h	strncmp	string.h

memcpy	mem.h	strncpy	string.h

memset	mem.h	strnset	string.h

_rotl	stdlib.h	strrchr	string.h

_rotr	stdlib.h	strset	string.h


See Also

math.h

mem.h

stdlib.h

string.h

Header Files Summary

Library Routines, by Category

Library Routines, by Name


Input/output Routines

See Also

The following routines provide stream- and operating-system level I/O capability.

Function	Header	Function	Header

access	io.h	getftime	io.h

chmod	io.h	gets	stdio.h

chsize	io.h	getw	stdio.h

clearerr	stdio.h	ioctl	io.h

close	io.h	isatty	io.h

creat	io.h	kbhit	conio.h

creatnew	io.h	lock	io.h

creattemp	io.h	locking	io.h

cscanf	conio.h	lseek	io.h

_dos_close	dos.h	open	io.h

_pclose	stdio.h	_open_osfhandle	io.h

_dos_creat 	dos.h	perror	stdio.h

_dos_creatnew	dos.h	_pipe	io.h

_dos_getfileattr	dos.h	_popen	stdio.h

_dos_getftime	dos.h	printf	stdio.h

_dos_open	dos.h	putc	stdio.h

_dos_read	dos.h	putchar	stdio.h

_dos_setfileattr	dos.h	puts	stdio.h

_dos_setftime	dos.h	putw	stdio.h

_dos_write	dos.h	read	io.h

dup	io.h	remove	stdio.h

dup2	io.h	rename	stdio.h

eof	io.h	rewind	stdio.h

fclose	stdio.h	rmtmp	stdio.h

fcloseall	stdio.h	_rtl_chmod	io.h

fdopen	stdio.h	_rtl_close	io.h

feof	stdio.h	_rtl_creat	io.h

ferror	stdio.h	_rtl_open	io.h

fflush	stdio.h	_rtl_read	io.h

fgetc	stdio.h	_rtl_write	io.h

fgetchar	stdio.h	scanf	stdio.h

fgetpos	stdio.h	setbuf	stdio.h

fgets	stdio.h	setftime	io.h

filelength	io.h	setmode	io.h

fileno	stdio.h	setvbuf	stdio.h

flushall	stdio.h	sopen	io.h

fopen	stdio.h	sprintf	stdio.h

fprintf	stdio.h	sscanf	stdio.h

fputc	stdio.h	strerror	stdio.h

fputchar	stdio.h	_strerror	string.h, stdio.h

fputs	stdio.h	tell	io.h

fread	stdio.h	tempnam	stdio.h

freopen	stdio.h	TFile (class)	file.h

fscanf	stdio.h	tmpfile	stdio.h

fseek	stdio.h	tmpnam	stdio.h

fsetpos	stdio.h	umask	io.h

_fsopen	stdio.h	unlink	dos.h

fstat	sys\stat.h	unlock	io.h

ftell	stdio.h	utime	utime.h

fwrite	stdio.h	vfprintf	stdio.h

get_osfhandle	io.h	vfscanf	stdio.h

getc	stdio.h	vprintf	stdio.h

getch	conio.h	vscanf	stdio.h

getchar	stdio.h	vsprintf	stdio.h

getche	conio.h	vsscanf	io.h


See Also

conio.h

io.h

stdio.h

string.h

sys\stat.h

utime.h

Header Files Summary

Library Routines, by Category

Library Routines, by Name


Interface Routines
Interface Routines (DOS, 8086, BIOS)

See Also

The following routines provide operating system, BIOS and machine-specific capabilities.

Function	Header	Function	Header

bdos	dos.h	inp	conio.h

bdosptr	dos.h	inpw	conio.h

_bios_equiplist	bios.h	inport	dos.h

biosequip	bios.h	inportb	dos.h

biosmemory	bios.h	int86	dos.h

biostime	bios.h	int86x	dos.h

_chain_intr	dos.h	intdos	dos.h

country	dos.h	intdosx	dos.h

ctrlbrk	dos.h	intr	dos.h

_disable	dos.h	MK_FP	dos.h

disable	dos.h	outp	conio.h

dosexterr	dos.h	outpw	conio.h

_dos_getvect	dos.h	outport	dos.h

_dos_setvect	dos.h	outportb	dos.h

_enable	dos.h	parsfnm	dos.h

enable	dos.h	peek	dos.h

FP_OFF	dos.h	peekb	dos.h

FP_SEG	dos.h	poke	dos.h

geninterrupt	dos.h	pokeb	dos.h

getcbrk	dos.h	segread	dos.h

getdfree	dos.h	setcbrk	dos.h

getdta	dos.h	_setcursortype	conio.h

getfat	dos.h	setdta	dos.h

getfatd	dos.h	setvect	dos.h

getpsp	dos.h	setverify	dos.h

getvect	dos.h	sleep	dos.h

getverify	dos.h


See Also

bios.h

conio.h

dos.h

Header Files Summary

Library Routines, by Category

Library Routines, by Name


International API Routines

See Also

The following routines are affected by the current locale. The current locale is specified by the setlocale function and is enabled by defining _ _USELOCALES_ _ with -D command line option. When you define _ _USELOCALES_ _, only function versions of the following routines are used in the run-time library rather than macros.

Function	Header	Function	Header

cprintf	stdio.h	scanf	stdio.h

cscanf	stdio.h	setlocale	locale.h

fprintf	stdio.h	sprintf	stdio.h

fscanf	stdio.h	sscanf	stdio.h

isalnum	ctype.h	strcoll	string.h

isalpha	ctype.h	strftime	time.h

iscntrl	ctype.h	strlwr	string.h

isdigit	ctype.h	strupr	string.h

isgraph	ctype.h	strxfrm	string.h

islower	ctype.h	tolower	ctype.h

isprint	ctype.h	toupper	ctype.h

ispunct	ctype.h	vfprintf	stdio.h

isspace	ctype.h	vfscanf	stdio.h

isupper	ctype.h	vprintf	stdio.h

isxdigit	ctype.h	vscanf	stdio.h

localeconv	locale.h	vsprintf	stdio.h

printf	stdio.h	vsscanf	stdio.h


See Also

ctype.h

locale.h

stdio.h

stdlib.h

string.h

Header Files Summary

Library Routines, by Category

Library Routines, by Name


Manipulation Routines

See Also

The following routines handle strings and blocks of memory: copying, comparing, converting, and searching.

Function	Header	Function	Header

mblen	stdlib.h	strerror	string.h

mbstowcs	stdlib.h	stricmp	string.h

mbtowc	stdlib.h	strlen	string.h

memccpy	mem.h, string.h	strlwr	string.h

memchr	mem.h, string.h	strncat	string.h

memcmp	mem.h, string.h	strncmpi	string.h

memcpy	mem.h, string.h	strncmp	string.h

memicmp	mem.h, string.h	strncpy	string.h

memmove	mem.h, string.h	strnicmp	string.h

memset	mem.h, string.h	strnset	string.h

movedata	mem.h, string.h	strpbrk	string.h

movmem	mem.h, string.h	strrchr	string.h

setmem	mem.h	strrev	string.h

stpcpy	string.h	strset	string.h

strcat	string.h	strspn	string.h

strchr	string.h	strstr	string.h

strcmpi	string.h	strtok	string.h

strcmp	string.h	strupr	string.h

strcoll	string.h	strxfrm	string.h

strcpy	string.h	wcstombs	stdlib.h

strcspn	string.h	wctomb	stdlib.h

strdup	string.h


See Also

mem.h

stdlib.h

string.h

Header Files Summary

Library Routines, by Category

Library Routines, by Name


Math Routines

See Also

The folowing routines perform mathematical calculations and conversions.

Function	Header	Function	Header

abs	complex.h, stdlib.h	labs	stdlib.h

acos	complex.h, math.h	ldexp	math.h

acosl	math.h	ldexpl	math.h

arg	complex.h	ldiv	math.h

asin	complex.h, math.h	log	complex.h, math.h

asinl	math.h	logl	math.h

atan	complex.h, math.h	log10	complex.h, math.h

atan2	complex.h, math.h	log10l	math.h

atan2l	math.h	_lrotl	stdlib.h

atanl	math.h	_lrotr	stdlib.h

atof	stdlib.h, math.h	ltoa	stdlib.h

atoi	stdlib.h	_matherr	math.h

atol	stdlib.h	_matherrl	math.h

_atold	math.h	modf	math.h

bcd (class)	bcd.h	modfl	math.h

cabs	math.h	norm	complex.h

cabsl	math.h	polar	complex.h

ceil	math.h	poly	math.h

ceill	math.h	polyl	math.h

_clear87	float.h	pow	complex.h, math.h

complex (class)	complex.h	pow10	math.h

conj	complex.h	pow10l	math.h

_control87	float.h	powl	math.h

cos	complex.h, math.h	rand	stdlib.h

cosh	complex.h, math.h	random	stdlib.h

coshl	math.h	randomize	stdlib.h

cosl	math.h	real	complex.h

div	math.h	_rotl	stdlib.h

ecvt	stdlib.h	_rotr	stdlib.h

exp	complex.h, math.h	sin	complex.h, math.h

expl	math.h	sinh	complex.h, math.h

fabs	math.h	sinhl	math.h

fabsl	math.h	sinl	complex.h, math.h

fcvt	stdlib.h	sqrt	complex.h, math.h

floor	math.h	sqrtl	math.h

floorl	math.h	srand	stdlib.h

fmod	math.h	_status87	float.h

fmodl	math.h	strtod	stdlib.h

_fpreset	float.h	strtol	stdlib.h

frexp	math.h	_strtold	stdlib.h

frexpl	math.h	strtoul	stdlib.h

gcvt	stdlib.h	tan	complex.h, math.h

hypot	math.h	tanh	complex.h, math.h

hypotl	math.h	tanhl	complex.h, math.h

imag	complex.h	tanl	math.h

itoa	stdlib.h	ultoa	stdlib.h


See Also

bcd.h

complex.h

float.h

math.h

stdlib

Header Files Summary

Library Routines, by Category

Library Routines, by Name

Mathematical Classes


Memory Routines

SeeAlso

The following routines provide dynamic memory allocation in the small-data and large-data models.

Function	Header	Function	Header

alloca	malloc.h	heapcheckfree	alloc.h

_bios_memsize	bios.h	heapchecknode	alloc.h

calloc	alloc.h, stdlib.h 	heapwalk	alloc.h

farcalloc	alloc.h	malloc	alloc.h, stdlib.h

farfree	alloc.h	realloc	alloc.h, stdlib.h

farmalloc	alloc.h	set_new_handler	new.h

free	alloc.h, stdlib.h	stackavail	malloc.h

heapcheck	alloc.h


See Also

alloc.h

bios.h

dos.h

malloc.h

new.h

stdlib.h

Header Files Summary

Library Routines, by Category

Library Routines, by Name


Miscellaneous Routines

See Also

The following routines provide non-local goto capabilities and locale.

Function	Header

localeconv	locale.h

longjmp	setjmp.h

setjmp	setjmp.h

setlocale	locale.h


See Also

locale.h

setjmp.h

Header Files Summary

Library Routines, by Category

Library Routines, by Name


Obsolete Functions

See Also

The old names of the following functions are available, but the compiler will generate a warning that you are using an obsolete name. Future versions of Borland C++ might not provide support for the old function names.

The following function names have been changed:

Old name	New name	Header file

_chmod	_rtl_chmod	io.h

_close	_rtl_close	io.h

_creat	_rtl_creat	io.h

_heapwalk	_rtl_heapwalk	malloc.h

_open	_rtl_open	io.h

_read	_rtl_read	io.h

_write	_rtl_write	io.h


See Also

Library Routines, by Category

Library Routines, by Name

Obsolete Global Variables


Process Control Routines

See Also

The following routines invoke and terminate new processes from within another routine.

Function	Header	Function	Header

abort	(process.h)	exit	(process.h)

_beginthread	_expand	(process.h)

_beginthreadNT	(process.h)	getpid	(process.h)

_c_exit	(process.h)	_pclose	(stdio.h)

_cexit	(process.h)	_popen	(stdio.h)

cwait	(process.h)	raise	(signal.h)

_endthread	(process.h)	signal	(signal.h)

execle	(process.h)	spawnle	(process.h)

execl	(process.h)	spawnlpe	(process.h)

execlpe	(process.h)	spawnlp	(process.h)

execlp	(process.h)	spawnl	(process.h)

execve	(process.h)	spawnve	(process.h)

execv	(process.h)	spawnvpe	(process.h)

execvpe	(process.h)	spawnvp	(process.h)

execvp	(process.h)	spawnv	(process.h)

_exit	(process.h)	wait	(process.h)


See Also

process.h

signal.h

Header Files Summary

Library Routines, by Category

Library Routines, by Name


Time and Date Routines

See Also

The following following functions are time conversion and time manipulation routines.

Function	Header	Function	Header

asctime	time.h	gmtime	time.h

_bios_timeofday	bios.h	localtime	time.h

ctime	time.h	mktime	time.h

difftime	time.h	stime	time.h

_dos_getdate	dos.h	_strdate	time.h

_dos_gettime	dos.h	strftime	time.h

_dos_setdate	dos.h	_strtime	time.h

_dos_settime	dos.h	TDate (class)	date.h

dostounix	dos.h	time	time.h

ftime	sys\timeb.h	TTime (class)	date.h

getdate	dos.h	tzset	time.h

gettime	dos.h	unixtodos	dos.h


See Also

bios.h

time.h

dos.h

sys\timeb.h

Header Files Summary

Library Routines, by Category

Library Routines, by Name

TTime class

TDate class


Variable Argument List
Variable Argument List Routines

See Also

The following routines are for use when accessing variable argument lists (such as with printf, vscanf, and so on).

Function	Header

va_start	stdarg.h

va_arg	stdarg.h

va_end	stdarg.h


See Also

stdarg.h

Header Files Summary

Library Routines, by Category

Library Routines, by Name


Library Routines, by Name
Borland C++ Library Routines, by Name

See Also	Overview

If you do not know the name of a particular function, but you know what type of action it performs, see:

Borland C++ Library Routines, by Category

Otherwise, if you know which function you want Help on, choose one of the following topics:

A

abort

abs

access

acos

acosl

alloca

arg

asctime

asin

asinl

assert

atan

atan2

atan2l

atanl

atexit

atof

atoi

atol

_atold

B

bcd (class)

bdos

bdosptr

_beginthread

_beginthreadNT

_bios_equiplist

_bios_memsize

_bios_timeofday

biosequip

biosmemory

biostime

bsearch

C

_c_exit

cabs

cabsl

calloc

ceil

ceill

_cexit

cgets

_chain_intr

chdir

_chdrive

chmod

chsize

_clear87

clearerr

clock

close

closedir

clreol

clrscr

complex (class)

conj

_control87

cos

cosh

coshl

cosl

country

creat

creatnew

creattemp

_crotl

_crotr

cscanf

ctime

ctrlbrk

cwait

D

delline

difftime

disable

_disable

div

_dos_close

_dos_commit

_dos_creat

_dos_creatnew

_dos_findfirst

_dos_findnext

_dos_getdate

_dos_getdiskfree

_dos_getdrive

_dos_getfileattr

_dos_getftime

_dos_gettime

_dos_getvect

_dos_open

_dos_read

_dos_setdate

_dos_setdrive

_dos_setfileattr

_dos_setftime

_dos_settime

_dos_setvect

_dos_write

dosexterr

dostounix

dup

E

ecvt

_ _emit_ _

enable

_enable

_endthread

eof

execl

execle

execlp

execlpe

execv

execve

execvp

execvpe

exit

_exit

exp

_expand

expl

F

fabs

fabsl

farcalloc

farfree

farmalloc

farrealloc

fclose

fcloseall

fcvt

fdopen

feof

ferror

fflush

fgetc

fgetchar

fgetpos

fgets

filelength

fileno

findfirst

findnext

floor

floorl

flushall

_fmemccpy

_fmemchr

_fmemcmp

_fmemcpy

_fmemicmp

_fmemset

fmod

fmodl

fnmerge

fnsplit

fopen

FP_OFF

FP_SEG

_fpreset

fprintf

fputc

fputchar

fputs

fread

free

freopen

frexp

frexpl

fscanf

fseek

fsetpos

_fsopen

fstat

_fstrcat

_fstrchr

_fstrcspn

_fstrdup

_fstricmp

_fstrlen

_fstrlwr

_fstrncat

_fstrncmp

_fstrncpy

_fstrnicmp

_fstrnset

_fstrpbrk

_fstrrchr

_fstrrev

_fstrset

_fstrspn

_fstrstr

_fstrtok

_fstrupr

ftell

ftime

_fullpath

fwrite

G

gcvt

geninterrupt

_get_osfhandle

getc

getcbrk

getch

getchar

getche

getcurdir

getcwd

getdate

_getdcwd

getdfree

getdisk

getdta

getenv

getfat

getfatd

getftime

getpass

getpid

getpsp

gets

gettext

gettextinfo

gettime

getvect

getverify

getw

gmtime

gotoxy

H

_heapadd

heapcheck

heapcheckfree

heapchecknode

_heapchk

heapfillfree

_heapmin

_heapset

heapwalk

highvideo

hypot

hypotl

I

imag

_InitEasyWin

inp

inport

inportb

inpw

insline

int86x

intdos

intdosx

intr

ioctl

isalnum

isalpha

isascii

isatty

iscntrl

isdigit

isgraph

islower

isprint

ispunct

isspace

isupper

isxdigit

itoa

K

kbhit

L

labs

ldexp

ldexpl

ldiv

lfind

localeconv

localtime

lock

locking

log

log10

log10l

logl

longjmp

lowvideo

_lrotl

_lrotr

lsearch

lseek

ltoa

M

_makepath

malloc

_matherr

_matherrl

max

mblen

mbstowcs

mbtowc

memccpy

memchr

memcmp

memcpy

memicmp

memmove

memset

min

MK_FP

mkdir

mktemp

mktime

modf

modfl

movedata

movetext

movmem

_msize

N

norm

normvideo

O

offsetof

open

_open_osfhandle

opendir

outp

outport

outportb

outpw

P

parsfnm

_pclose

peek

peekb

perror

_pipe

poke

pokeb

polar

poly

polyl

_popen

pow

pow10

pow10l

powl

printf

putc

putch

putchar

putenv

puts

puttext

putw

Q

qsort

R

raise

rand

random

randomize

read

readdir

real

realloc

remove

rename

rewind

rewinddir

rmdir

rmtmp

_rotl

_rotr

_rtl_chmod

_rtl_close

_rtl_creat

_rtl_heapwalk

_rtl_open

_rtl_read

_rtl_write

S

scanf

_searchenv

searchpath

_searchstr

segread

set_new_handler

setbuf

setcbrk

_setcursortype

setdate

setdisk

setdta

setftime

setjmp

setlocale

setmem

setmode

settime

setvbuf

setvect

setverify

signal

sin

sinh

sinhl

sinl

sleep

sopen

spawnl

spawnle

spawnlp

spawnlpe

spawnv

spawnve

spawnvp

spawnvpe

_splitpath

sprintf

sqrt

sqrtl

srand

sscanf

stackavail

stat

_status87

stime

stpcpy

strcat

strchr

strcmp

strcmpi

strcoll

strcpy

strcspn

_strdate

strdup

strerror

_strerror

strftime

stricmp

strlen

strlwr

strncat

strncmp

strncmpi

strncpy

strnicmp

strnset

strpbrk

strrchr

strrev

strset

strspn

strstr

_strtime

strtod

strtok

strtol

_strtold

strtoul

strupr

strxfrm

swab

system

T

tan

tanh

tanhl

tanl

tell

tempnam

textattr

textbackground

textcolor

textmode

time

tmpfile

tmpnam

toascii

tolower

_tolower

toupper

_toupper

tzset

U

ultoa

umask

ungetc

ungetch

unixtodos

unlink

unlock

utime

V

va_arg

va_end

va_start

vfprintf

vfscanf

vprintf

vscanf

vsprintf

vsscanf

W

wait

wcstombs

wctomb

wherex

wherey

window

write


See Also

Default Run-time Libraries

Dynamic-link Libraries

Header Files Summary

Library Routines, by Category

Reasons to Access the Run-time Library Source Code

Static Run-time Libraries


abort

See Also	Example	Portability

Syntax

#include <stdlib.h>

void abort(void);

Description

Abnormally terminates a program.

abort causes an abnormal program termination by calling raise(SIGABRT). If there is no signal handler for SIGABRT, then abort writes a termination message (Abnormal program termination) on stderr, then aborts the program by a call to _exit with exit code 3.

Return Value

abort returns the exit code 3 to the parent process or to the operating system command processor.


See Also

assert

atexit

_c_exit

_cexit

_exit

exit

raise

signal

spawnl


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


abs

See Also	Example	Portability

Syntax

#include <stdlib.h>

int abs(int x);

Description

Returns the absolute value of an integer.

abs returns the absolute value of the integer argument x. If abs is called when stdlib.h has been included, it's treated as a macro that expands to inline code.

If you want to use the abs function instead of the macro, include

#undef abs

in your program, after the #include <stdlib.h>.

This function can be used with bcd and complex types.

Return Value

The abs function returns an integer in the range of 0 to INT_MAX, with the exception that an argument with the value INT_MIN is returned as INT_MIN. The values for INT_MAX and INT_MIN are defined in header file limit.h.


See Also

bcd

cabs

complex

fabs

labs


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


access

See Also	Example	Portability

Syntax

#include <io.h>

int access(const char *filename, int amode);

Description

Determines accessibility of a file.

access checks the file named by filename to determine if it exists, and whether it can be read, written to, or executed.

The list of amode values is as follows:

06	Check for read and write permission

04	Check for read permission

02	Check for write permission

01	Execute (ignored)

00	Check for existence of file

Under DOS, OS/2, and Windows (16- and 32-bit) all existing files have read access (amode equals 04), so 00 and 04 give the same result. Similarly, amode values of 06 and 02 are equivalent because under DOS write access implies read access.

If filename refers to a directory, access simply determines whether the directory exists.

Return Value

If the requested access is allowed, access returns 0; otherwise, it returns a value of -1, and the global variable errno is set to one of the following values:

ENOENT	Path or file name not found

EACCES	Permission denied


See Also

chmod

fstat

stat


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


acos, acosl

See Also	Example	Portability

Syntax

#include <math.h>

double acos(double x);

long double acosl(long double x);

Description

Calculates the arc cosine.

acos returns the arc cosine of the input value.

acosl is the long double version; it takes a long double argument and returns a long double result.

Arguments to acos and acosl must be in the range -1 to 1, or else acos and acosl return NAN and set the global variable errno to

EDOM  Domain error

This function can be used with bcd and complex types.

Return Value

acos and acosl of an argument between -1 and +1 return a value in the range 0 to pi. Error handling for these routines can be modified through the functions _matherr_matherr and _matherrl.


See Also

asin

atan

atan2

bcd

complex

cos

_matherr

sin

tan


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
acos	+	+	+	+	+	+	+
acosl	+		+	+			+


alloca

See Also	Example	Portability

Syntax

#include <malloc.h>

void *alloca(size_t size);

Description

Allocates temporary stack space.

alloca allocates size bytes on the stack; the allocated space is automatically freed up when the calling function exits.

Because alloca modifies the stack pointer, do not place calls to alloca in an expression that is an argument to a function.

The alloca function should not be used in the try-block of a C++ program. If an exception is thrown, any values placed on the stack by alloca will be corrupted.

If the calling function does not contain any references to local variables in the stack, the stack will not be restored correctly when the function exits, resulting in a program crash. To ensure that the stack is restored correctly, use the following code in the calling function:

char *p;

char dummy[5];

dummy[0] = 0;

  .

  .

  .

p = alloca(nbytes);

Return Value

If enough stack space is available, alloca returns a pointer to the allocated stack area. Otherwise, it returns NULL.


See Also

malloc


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


asctime

See Also	Example	Portability

Syntax

#include <time.h>

char *asctime(const struct tm *tblock);

Description

Converts date and time to ASCII.

asctime converts a time stored as a structure in *tblock to a 26-character string of the same form as the ctime string:

   Sun Sep 16 01:03:52 1973\n\0

Return Value

asctime returns a pointer to the character string containing the date and time. This string is a static variable that is overwritten with each call to asctime.


See Also

ctime

difftime

ftime

gmtime

localtime

mktime

strftime

stime

time

tzset


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


asin, asinl

See Also	Example	Portability

Syntax

#include <math.h>

double asin(double x);

long double asinl(long double x);

Description

Calculates the arc sine.

asin of a real argument returns the arc sine of the input value.

asinl is the long double version; it takes a long double argument and returns a long double result.

Real arguments to asin and asinl must be in the range -1 to 1, or else asin and asinl return NAN and set the global variable errno to

  EDOM  Domain error

This function can be used with bcd and complex types.

Return Value

asin and asinl of a real argument return a value in the range -pi/2 to pi/2. Error handling for these functions may be modified through the functions _matherr and _matherrl.


See Also

acos

atan

atan2

bcd

complex

cos

_matherr

sin

tan


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
asin	+	+	+	+	+	+	+
asinl	+		+	+			+


assert

See Also	Example	Portability

Syntax

#include <assert.h>

void assert(int test);

Description

Tests a condition and possibly aborts.

assert is a macro that expands to an if statement; if test evaluates to zero, assert aborts the program (by calling abort) and asserts the following a message on stderr:

Assertion failed: test, file filename, line linenum

The filename and linenum listed in the message are the source file name and line number where the assert macro appears.

If you place the #define NDEBUG directive ("no debugging") in the source code before the #include <assert.h> directive, the effect is to comment out the assert statement.

Return Value

None.


See Also

abort


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


atan, atanl

See Also	Example	Portability

Syntax

#include <math.h>

double atan(double x);

long double atanl(long double x);

Description

Calculates the arc tangent.

atan calculates the arc tangent of the input value.

atanl is the long double version; it takes a long double argument and returns a long double result. This function can be used with bcd and complex types.

Return Value

atan and atanl of a real argument return a value in the range -pi/2 to pi/2. Error handling for these functions can be modified through the functions _matherr and _matherrl.


See Also

acos

asin

atan2

bcd

complex

cos

_matherr

sin

tan


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
atan	+	+	+	+	+	+	+
atanl	+		+	+			+


atan2, atan2l

See Also	Example	Portability

Syntax

#include <math.h>

double atan2(double y, double x);

long double atan2l(long double y, long double x);

Description

Calculates the arc tangent of y/x.

atan2 returns the arc tangent of y/x; it produces correct results even when the resulting angle is near pi/2 or -pi/2 (x near 0). If both x and y are set to 0, the function sets the global variable errno to EDOM, indicating a domain error.

atan2l is the long double version; it takes long double arguments and returns a long double result.

Return Value

atan2 and atan2l return a value in the range -pi to pi. Error handling for these functions can be modified through the functions _matherr and _matherrl.


See Also

acos

asin

atan

cos

_matherr

sin

tan


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
atan2	+	+	+	+	+	+	+
atan2l	+		+	+			+


atexit

See Also	Example	Portability

Syntax

#include <stdlib.h>

int atexit(void (_USERENTRY * func)(void));

Description

Registers termination function.

atexit registers the function pointed to by func as an exit function. Upon normal termination of the program, exit calls func just before returning to the operating system. fcmp must be used with the _USERENTRY calling convention.

Each call to atexit registers another exit function. Up to 32 functions can be registered. They are executed on a last-in, first-out basis (that is, the last function registered is the first to be executed).

Return Value

atexit returns 0 on success and nonzero on failure (no space left to register the function).


See Also

abort

_c_exit

_cexit

_exit

exit

spawn...


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	+  	+	+


atof, _atold

See Also	Example	Portability

Syntax

#include <math.h>

double atof(const char *s);

long double _atold(const char *s);

Description

Converts a string to a floating-point number.

atof  converts a string pointed to by s to double; this function recognizes the character representation of a floating-point number, made up of the following:

An optional string of tabs and spaces

An optional sign

A string of digits and an optional decimal point (the digits can be on both sides of the decimal point)

An optional e or E followed by an optional signed integer

The characters must match this generic format:

  [whitespace] [sign] [ddd] [.] [ddd] [e|E[sign]ddd]

atof also recognizes +INF and -INF for plus and minus infinity, and +NAN and -NAN for Not-a-Number.

In this function, the first unrecognized character ends the conversion.

_atold is the long double version; it converts the string pointed to by s to a long double.

The functions strtod and _strtold are similar to atof and _atold; they provide better error detection, and hence are preferred in some applications.

Return Value

atof and _atold return the converted value of the input string.

If there is an overflow, atof (or _atold) returns plus or minus HUGE_VAL (or _LHUGE_VAL), errno is set to ERANGE (Result out of range), and _matherr (or _matherrl) is not called.


See Also

atoi

atol

ecvt

fcvt

gcvt

scanf

strtod


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
atof	+	+	+	+	+	+	+
_atold	+		+	+			+


atoi

See Also	Example	Portability

Syntax

#include <stdlib.h>

int atoi(const char *s);

Description

Converts a string to an integer.

atoi converts a string pointed to by s to int; atoi recognizes (in the following order)

An optional string of tabs and spaces

An optional sign

A string of digits

The characters must match this generic format:

  [ws] [sn] [ddd]

In this function, the first unrecognized character ends the conversion. There are no provisions for overflow in atoi (results are undefined).

Return Value

atoi returns the converted value of the input string. If the string cannot be converted to a number of the corresponding type (int), atoi returns 0.


See Also

atof

atol

ecvt

fcvt

gcvt

scanf

strtod


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


atol

See Also	Example	Portability

Syntax

#include <stdlib.h>

long atol(const char *s);

Description

Converts a string to a long.

atol converts the string pointed to by s to long. atol recognizes (in the following order)

An optional string of tabs and spaces

An optional sign

A string of digits

The characters must match this generic format:

[ws] [sn] [ddd]

In this function, the first unrecognized character ends the conversion. There are no provisions for overflow in atol (results are undefined).

Return Value

atol returns the converted value of the input string. If the string cannot be converted to a number of the corresponding type (b), atol returns 0.


See Also

atof

atoi

ecvt

fcvt

gcvt

scanf

strtod

strtol

strtoul


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


bdos

See Also	Example	Portability

Syntax

#include <dos.h>

int bdos(int dosfun, unsigned dosdx, unsigned dosal);

Description

Accesses DOS system calls.

bdos provides direct access to many of the DOS system calls. See your DOS reference manuals for details on each system call.

For system calls that require an integer argument, use bdos; if they require a pointer argument, use bdosptr. In the large data models (compact, large, and huge), it is important to use bdosptr instead of bdos for system calls that require a pointer as the call argument.

dosfun is defined in your DOS reference manuals.

dosdx is the value of register DX.

dosal is the value of register AL.

Return Value

The return value of bdos is the value of AX set by the system call.


See Also

bdosptr

geninterrupt

int86

int86x

intdos

intdosx


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


bdosptr

See Also	Example	Portability

Syntax

#include <dos.h>

int bdosptr(int dosfun, void *argument, unsigned dosal);

Description

Accesses DOS system calls.

bdosptr provides direct access to many of the DOS system calls. See your DOS reference manuals for details of each system call.

For system calls that require an integer argument, use bdos; if calls require a pointer argument, use bdosptr. In the large data models (compact, large, and huge), it is important to use bdosptr for system calls that require a pointer as the call argument. In the small data models, the argument parameter to bdosptr specifies DX; in the large data models, it gives the DS:DX values to be used by the system call.

dosfun is defined in your DOS reference manuals. dosal is the value of register AL.

Return Value

The return value of bdosptr is the value of AX on success or -1 on failure. On failure, the global variables errno and _doserrno are set.


See Also

bdos

geninterrupt

int86

int86x

intdos

intdosx


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


_beginthread

See Also	Example	Portability

Syntax

#include <process.h>

unsigned long _beginthread(_USERENTRY (*start_address)(void *), unsigned stack_size, void *arglist)

Description

Starts execution of a new thread.

Note:	The start_address must be declared to be _USERENTRY.

The _beginthread function creates and starts a new thread. The thread starts execution at start_address.

The size of its stack in bytes is stack_size; the stack is allocated by the operating system after the stack size is rounded up to the next multiple of 4096. The thread is passed arglist as its only parameter; it can be NULL, but must be present. The thread terminates by simply returning, or by calling _endthread.

Either this function or _beginthreadNT must be used instead of the operating system thread-creation API function because _beginthread and _beginthreadNT perform initialization required for correct operation of the run-time library functions.

This function is available only in the multithread libraries.

Return Value

_beginthread returns the handle of the new thread.

On error, the function returns -1, and the global variable errno is set to one of the following values:

EAGAIN	Too many threads

EINVAL	Invalid request

Also see the Win32 description of GetLastError.


See Also

_beginthreadNT

_endthread


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

 	 	 	 	+	 	 	+


_beginthreadNT

See Also	Example	Portability

Syntax

#include <process.h>

unsigned long _beginthreadNT(void (_USERENTRY *start_address)(void *), unsigned stack_size, void *arglist, void *security_attrib, unsigned long create_flags, unsigned long *thread_id);

Description

Starts execution of a new thread under Windows NT.

Note:	 The start_address must be declared to be _USERENTRY.

All multithread Windows NT programs must use _beginthreadNT or the _beginthreadfunction instead of the operating system thread-creation API function because these functions perform initialization required for correct operation of the run-time library functions. The _beginthreadNT function provides support for the operating system security. These functions are available only in the multithread libraries.

The _beginthreadNT function creates and starts a new thread. The thread starts execution at start_address.

The size of its stack in bytes is stack_size; the stack is allocated by the operating system after the stack size is rounded up to the next multiple of 4096. The thread arglist can be NULL, but must be present. The thread terminates by simply returning, or by calling _endthread.

The _beginthreadNT function uses the security_attr pointer to access the SECURITY_ATTRIBUTES structure. The structure contains the security attributes for the thread. If security_attr is NULL, the thread is created with default security attributes. The thread handle is not inherited if security_attr is NULL.

_beginthreadNT reads the create_flags variable for flags that provide additional information about the thread creation. This variable can be zero, specifying that the thread will run immediately upon creation. The variable can also be CREATE_SUSPENDED; in which case, the thread will not run until the ResumeThread function is called. ResumeThread is provided by the Win32 API.

_beginthreadNT initializes the thread_id variable with the thread identifier.

Return Value

On success, _beginthreadNT returns the handle of the new thread.

On error, it returns -1, and the global variable errno is set to one of the following values:

EAGAIN	Too many threads

EINVAL	Invalid request


See Also

_beginthread

_endthread


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

 	 	 	 	+


biosequip

Example	Portability

Syntax

#include <bios.h>

int biosequip(void);

Description

Checks equipment.

biosequip uses BIOS interrupt 0x11 to return an integer describing the equipment connected to the system.

Return Value

The return value is interpreted as a collection of bit-sized fields. The IBM PC values follow:

Bits 14-15	Number of parallel printers installed

 	00 = 0 printers

 	01 = 1 printer

 	10 = 2 printers

 	11 = 3 printers

Bit 13	Serial printer attached

Bit 12	Game I/O attached

Bits 9-11	Number of COM ports  (DOS only sees two ports but can be pushed to see four; the IBM PS/2 can see up to eight.)

 	000 = 0 ports

 	001 = 1 port

 	010 = 2 ports

 	011 = 3 ports

 	100 = 4 ports

 	101 = 5 ports

 	110 = 6 ports

 	111 = 7 ports

Bit 8	Direct memory access (DMA)

 	0 = Machine has DMA

 	1 = Machine does not have DMA; for example, PC Jr.

Bits 6-7	Number of disk drives

 	00 = 1 drive

 	01 = 2 drives

 	10 = 3 drives

 	11 = 4 drives, only if bit 0 is 1

Bits 4-5	Initial video mode

 	00 = Unused

 	01 = 40x25 BW with color card

 	10 = 80x25 BW with color card

 	11 = 80x25 BW with mono card

Bits 2-3	Motherboard RAM size

 	00 = 16K

 	01 = 32K

 	10 = 48K

 	11 = 64K

Bit 1	Floating-point coprocessor

Bit 0	Boot from disk


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


_bios_equiplist

Example	Portability

Syntax

#include <bios.h>

unsigned _bios_equiplist(void);

Description

Checks equipment.

_bios_equiplist uses BIOS interrupt 0x11 to return an integer describing the equipment connected to the system.

Return Value

The return value is interpreted as a collection of bit-sized fields. The IBM PC values follow:

Bits 14-15	Number of parallel printers installed

 	00 = 0 printers

 	01 = 1 printer

 	10 = 2 printers

 	11 = 3 printers

Bit 13	Serial printer attached

Bit 12	Game I/O attached

Bits 9-11	Number of COM ports  (DOS only sees two ports but can be pushed to see four; the IBM PS/2 can see up to eight.)

 	000 = 0 ports

 	001 = 1 port

 	010 = 2 ports

 	011 = 3 ports

 	100 = 4 ports

 	101 = 5 ports

 	110 = 6 ports

 	111 = 7 ports

Bit 8	Direct memory access (DMA)

 	0 = Machine has DMA

 	1 = Machine does not have DMA; for example, PC Jr.

Bits 6-7	Number of disk drives

 	00 = 1 drive

 	01 = 2 drives

 	10 = 3 drives

 	11 = 4 drives, only if bit 0 is 1

Bits 4-5	Initial video mode

 	00 = Unused

 	01 = 40x25 BW with color card

 	10 = 80x25 BW with color card

 	11 = 80x25 BW with mono card

Bits 2-3	Motherboard RAM size

 	00 = 16K

 	01 = 32K

 	10 = 48K

 	11 = 64K

Bit 1	Floating-point coprocessor

Bit 0	Boot from disk


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


biosmemory

Example	Portability

Syntax

#include <bios.h>

int biosmemory(void);

Description

Returns memory size.

biosmemory returns the size of RAM memory using BIOS interrupt 0x12. This does not include display adapter memory, extended memory, or expanded memory.

Return Value

biosmemory returns the size of RAM memory in 1K blocks.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


_bios_memsize

Example	Portability

Syntax

#include <bios.h>

unsigned _bios_memsize(void);

Description

Returns memory size.

_bios_memsize returns the size of RAM memory using BIOS interrupt 0x12. This does not include display adapter memory, extended memory, or expanded memory.

Return Value

_bios_memsize returns the size of RAM memory in 1K blocks.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


biostime

Example	Portability

Syntax

#include <bios.h>

long biostime(int cmd, long newtime);

Description

Reads or sets the BIOS timer.

biostime either reads or sets the BIOS timer. This is a timer counting ticks since midnight at a rate of ticks per second as defined by _BIOS_CLOCKS_PER_SEC. biostime uses BIOS interrupt 0x1A.

If cmd equals 0, biostime returns the current value of the timer. If cmd equals 1, the timer is set to the long value in newtime. For example:

totalsecs = biostime(int cmd, long newtime) / _BIOS_CLK_TCK;

The _BIOS_CLOCKS_PER_SEC and _BIOS_CLK_TCK constants are defined in bios.h.

Return Value

When biostime reads the BIOS timer (cmd = 0), it returns the timer's current value.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


_bios_timeofday

Example	Portability

Syntax

#include <bios.h>

unsigned _bios_timeofday(int cmd, long *timep);

Description

Reads or sets the BIOS timer.

_bios_timeofday either reads or sets the BIOS timer. This is a timer counting ticks since midnight at a rate of roughly 18.2 ticks per second. _bios_timeofday uses BIOS interrupt 0x1A.

The cmd parameter can be either of the following values:

_TIME_GETCLOCK	The function stores the current BIOS timer value into the location pointed to by timep. If the timer has not been read or written since midnight, the function returns 1. Otherwise, the function returns 0.

_TIME_SETCLOCK	The function sets the BIOS timer to the long value pointed to by timep. The function does not return a value.

Return Value

The _bios_timeofday returns the value in AX that was set by the BIOS timer call.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


bsearch

See Also	Example	Portability

Syntax

#include <stdlib.h>

void *bsearch(const void *key, const void *base, size_t nelem, size_t width, int (_USERENTRY *fcmp)(const void *, const void *));

Description

Binary search of an array.

bsearch searches a table (array) of nelem elements in memory, and returns the address of the first entry in the table that matches the search key. The array must be in order. If no match is found, bsearch returns 0.

Note:	Because this is a binary search, the first matching entry is not necessarily the first entry in the table.

The type size_t is defined in stddef.h header file.

nelem gives the number of elements in the table.

width specifies the number of bytes in each table entry.

The comparison routine fcmp must be used with the _USERENTRY calling convention.

fcmp is called with two arguments: elem1 and elem2. Each argument points to an item to be compared. The comparison function compares each of the pointed-to items (*elem1 and *elem2), and returns an integer based on the results of the comparison.

For bsearch, the fcmp return value is

< 0  if *elem1 < *elem2

== 0 if *elem1 == *elem2

> 0  if *elem1 > *elem2

Return Value

bsearch returns the address of the first entry in the table that matches the search key. If no match is found, bsearch returns 0.


See Also

lfind

lsearch

qsort


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


cabs, cabsl

See Also	Example	Portability

Syntax

#include <math.h>

double cabs(struct complex z);

long double cabsl(struct _complexl z);

Description

cabs calculates the absolute value of a complex number. cabs is a macro that calculates the absolute value of z, a complex number. z is a structure with type complex; the structure is defined in math.h as

struct complex {

   double x, y;

   };

where x is the real part, and y is the imaginary part.

Calling cabs is equivalent to calling sqrt with the real and imaginary components of z, as shown here:

sqrt(z.x * z.x + z.y * z.y)

cabsl is the long double version; it takes a structure with type _complexl as an argument, and returns a long double result. The structure is defined in math.h as

struct _complexl {

   long double x, y;

};

Note:	If you are using C++, you may also use the complex class defined in complex.h, and use the function abs to get the absolute value of a complex number.

Return Value

cabs (or cabsl) returns the absolute value of z, a double. On overflow, cabs (or cabsl) returns HUGE_VAL (or _LHUGE_VAL) and sets the global variable errno to

ERANGE	Result out of range

Error handling for these functions can be modified through the functions _matherr and _matherrl.


See Also

abs

complex

errno (global variable)

fabs

labs

_matherr


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
cabs	+	+	+	+			+
cabsl	+		+	+			+


calloc

See Also	Example	Portability

Syntax

#include <stdlib.h>

void *calloc(size_t nitems, size_t size);

Description

Allocates main memory.

calloc provides access to the C memory heap. The heap is available for dynamic allocation of variable-sized blocks of memory. Many data structures, such as trees and lists, naturally employ heap memory allocation.

All the space between the end of the data segment and the top of the program stack is available for use in the tiny (DOS only), small and medium data models,except for a small margin immediately before the top of the stack. This margin allows room for the application to grow on the stack, and provides a small amount of room needed by the operating system.

In the large data models (compact, large, and huge), all space beyond the program stack to the end of physical memory is available for the heap.

Note:	Memory models are available only for 16-bit applications.

calloc allocates a block of size nitems * size. The block is cleared to 0. If you want to allocate a block larger than 64K, you must use farcalloc.

Return Value

calloc returns a pointer to the newly allocated block. If not enough space exists for the new block or if nitems or size is 0, calloc returns NULL.


See Also

farcalloc

free

malloc

realloc


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


ceil, ceill

See Also	Example	Portability

Syntax

#include <math.h>

double ceil(double x);

long double ceill(long double x);

Description

Rounds up.

ceil finds the smallest integer not less than x.

ceill is the long double version; it takes a long double argument and returns a long double result.

Return Value

These functions return the integer found as a double (ceil) or a long double (ceill).


See Also

floor

fmod


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
ceil	+	+	+	+	+	+	+
ceill	+		+	+			+


_c_exit

See Also	Example	Portability

Syntax

#include <process.h>

void _c_exit(void);

Description

Performs _exit cleanup without terminating the program.

_c_exit performs the same cleanup as _exit, except that it does not terminate the calling process.

Return Value

None.


See Also

abort

atexit

_cexit

exec...

_exit

exit

signal

spawn...


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


_cexit

See Also	Example	Portability

Syntax

#include <process.h>

void _cexit(void);

Description

Performs exit cleanup without terminating the program.

_cexit performs the same cleanup as exit, except that it does not close files or terminate the calling process. Buffered output (waiting to be output) is written, and any registered "exit functions" (posted with atexit) are called.

Return Value

None.


See Also

abort

atexit

_c_exit

exec...

_exit

exit

signal

spawn...


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+ 	 	 	+


cgets

See Also	Example	Portability

Syntax

#include <conio.h>

char *cgets(char *str);

Description

Reads a string from the console.

cgets reads a string of characters from the console, storing the string (and the string length) in the location pointed to by str.

cgets reads characters until it encounters a carriage-return/linefeed (CR/LF) combination, or until the maximum allowable number of characters have been read. If cgets reads a CR/LF combination, it replaces the combination with a \0 (null terminator) before storing the string.

Before cgets is called, set str[0] to the maximum length of the string to be read. On return, str[1] is set to the number of characters actually read. The characters read start at str[2] and end with a null terminator. Thus, str must be at least str[0] plus 2 bytes long.

Note:	Do not use this function for Win32s or Win32 GUI applications.

Return Value

On success, cgets returns a pointer to str[2].


See Also

cputs

fgets

getch

getche

gets


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+	 	 	+


_chain_intr

See Also	Example	Portability

Syntax

#include <dos.h>

void _chain_intr(void (interrupt far *newhandler)());

Description

Chains to another interrupt handler.

_chain_intr passes control from the currently executing interrupt handler to the new interrupt handler whose address is newhandler. The current register set is not passed to the new handler. Instead, the new handler receives the registers that were stacked (and possibly modified in the stack) by the old handler. The new handler can simply return, as if it were the original handler. The old handler is not entered again.

_chain_intr can be called only by C interrupt functions. It is useful when writing a TSR that needs to insert itself in a chain of interrupt handlers (such as the keyboard interrupt).

Return Value

None.


See Also

_dos_getvect

_dos_setvect


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


chdir

See Also	Example	Portability

Syntax

#include <dir.h>

int chdir(const char *path);

Description

Changes current directory.

chdir causes the directory specified by path to become the current working directory; path must specify an existing directory.

A drive can also be specified in the path argument, such as

   chdir("a:\\BC")

but this method changes only the current directory on that drive; it does not change the active drive.

Under Windows, only the current process is affected.

Under DOS, the function changes the current directory of the parent process.

Return Value

Upon successful completion, chdir returns a value of 0. Otherwise, it returns a value of -1, and the global variable errno is set to

ENOENT	Path or file name not found


See Also

getcurdir

getcwd

getdisk

mkdir

rmdir

setdisk

system


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


_chdrive

See Also	Example	Portability

Syntax

#include <direct.h>

int _chdrive(int drive);

Description

Sets current disk drive.

_chdrive sets the current drive to the one associated with drive: 1 for A, 2 for B, 3 for C, and so on.

This function changes the current drive of the parent process.

Return Value

_chdrive returns 0 if the current drive was changed successfully; otherwise, it returns -1.


See Also

_dos_setdrive


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


chmod

See Also	Example	Portability

Syntax

#include <sys\stat.h>

int chmod(const char *path, int amode);

Description

Changes file access mode.

chmod sets the file-access permissions of the file given by path according to the mask given by amode. path points to a string.

amode can contain one or both of the symbolic constants S_IWRITE and S_IREAD (defined in sys\stat.h).

Value of amode	Access permission

S_IWRITE	Permission to write

S_IREAD	Permission to read

S_IREAD | S_IWRITE	Permission to read and write (write permission implies read permission)

Return Value

Upon successfully changing the file access mode, chmod returns 0. Otherwise, chmod returns a value of -1.

In the event of an error, the global variable errno is set to one of the following values:

EACCES	Permission denied

ENOENT	Path or file name not found


See Also

access

fstat

open

_rtl_chmod

sopen

stat


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


chsize

See Also	Example	Portability

Syntax

#include <io.h>

int chsize(int handle, long size);

Description

Changes the file size.

chsize changes the size of the file associated with handle. It can truncate or extend the file, depending on the value of size compared to the file's original size.

The mode in which you open the file must allow writing.

If chsize extends the file, it will append null characters (\0). If it truncates the file, all data beyond the new end-of-file indicator is lost.

Return Value

On success, chsize returns 0. On failure, it returns -1 and the global variable errno is set to one of the following values:

EACCESS	Permission denied

EBADF	Bad file number

ENOSPC	No space left on device


See Also

close

creat

open

_rtl_creat


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


_clear87

See Also	Example	Portability

Syntax

#include <float.h>

unsigned int _clear87 (void);

Description

Clears floating-point status word.

_clear87 clears the floating-point status word, which is a combination of the 80x87 status word and other conditions detected by the 80x87 exception handler.

Return Value

The bits in the value returned indicate the floating-point status before it was cleared. For information on the status word, refer to the constants defined in float.h.


See Also

_control87

_fpreset

_status87


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+ 	 	 	+


clearerr

See Also	Example	Portability

Syntax

#include <stdio.h>

void clearerr(FILE *stream);

Description

Resets error indication.

clearerr resets the named stream's error and end-of-file indicators to 0. Once the error indicator is set, stream operations continue to return error status until a call is made to clearerr or rewind. The end-of-file indicator is reset with each input operation.

Return Value

None.


See Also

eof

feof

ferror

perror

rewind


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


clock

See Also	Example	Portability

Syntax

#include <time.h>

clock_t clock(void);

Description

Determines processor time.

clock can be used to determine the time interval between two events. To determine the time in seconds, the value returned by clock should be divided by the value of the macro CLK_TCK.

Return Value

On success, clock returns the processor time elapsed since the beginning of the program invocation.

On error (if the processor time is not available or its value cannot be represented), clock returns -1.


See Also

time


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	+	+	+


close

See Also	Example	Portability

Syntax

#include <io.h>

int close(int handle);

Description

Closes a file.

The close function closes the file associated with handle, a file handle obtained from a call to creat, creatnew, creattemp, dup, dup2, open, _rtl_creat, or _rtl_open.

It does not write a Ctrl-Z character at the end of the file. If you want to terminate the file with a Ctrl-Z, you must explicitly output one.

Return Value

Upon successful completion, close returns 0.

On error (if it fails because handle is not the handle of a valid, open file), close returns a value of -1 and the global variable errno is set to

EBADF	Bad file number


See Also

chsize

creat

creatnew

dup

fclose

open

_rtl_close

sopen


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


closedir

See Also	Example	Portability

Syntax

#include <dirent.h>

void closedir(DIR *dirp);

Description

Closes a directory stream.

On UNIX platforms, closedir is available on POSIX-compliant systems.

The closedir function closes the directory stream dirp, which must have been opened by a previous call to opendir. After the stream is closed, dirp no longer points to a valid directory stream.

Return Value

If closedir is successful, it returns 0. Otherwise, closedir returns -1 and sets the global variable errno to

EBADF	The dirp argument does not point to a valid open directory stream


See Also

errno (global variable)

opendir

readdir

rewinddir


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


clreol

See Also	Example	Portability

Syntax

#include <conio.h.>

void clreol(void);

Description

Clears to end of line in text window.

clreol clears all characters from the cursor position to the end of the line within the current text window, without moving the cursor.

Note:	This function should not be used in Win32s or Win32 GUI applications.

Return Value

None.


See Also

clrscr

delline

window


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


clrscr

See Also	Example	Portability

Syntax

#include <conio.h>

void clrscr(void);

Description

Clears the text-mode window.

clrscr clears the current text window and places the cursor in the upper left corner (at position 1,1).

Note:	Do not use this function for Win32s or Win32 GUI applications.

Return Value

None.


See Also

clreol

delline

window


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


_control87

See Also	Portability

Syntax

#include <float.h>

unsigned int _control87(unsigned int newcw, unsigned int mask);

Description

Manipulates the floating-point control word.

_control87 retrieves or changes the floating-point control word.

The floating-point control word is an unsigned int that, bit by bit, specifies certain modes in the floating-point package; namely, the precision, infinity, and rounding modes. Changing these modes lets you mask or unmask floating-point exceptions.

_control87 matches the bits in mask to the bits in newcw. If a mask bit equals 1, the corresponding bit in newcw contains the new value for the same bit in the floating-point control word, and _control87 sets that bit in the control word to the new value.

Here is a simple illustration:

Original control word:	0100	0011	0110	0011

mask:	1000	0001	0100	1111

newcw:	1110	1001	0000	0101

Changing bits:	1xxx	xxx1	x0xx	0101

If mask equals 0, _control87 returns the floating-point control word without altering it.

Return Value

The bits in the value returned reflect the new floating-point control word. For a complete definition of the bits returned by _control87, see the header file float.h.


See Also

_clear87

_fpreset

signal

_status87


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


cos, cosl

See Also	Example	Portability

Syntax

#include <math.h>

double cos(double x);

long double cosl(long double x);

Description

Calculates the cosine of a value.

cos computes the cosine of the input value. The angle is specified in radians.

cosl is the long double version; it takes a long double argument and returns a long double result.

This function can be used with bcd and complex types.

Return Value

cos of a real argument returns a value in the range -1 to 1. Error handling for these functions can be modified through _matherr (or _matherrl).


See Also

acos

asin

atan

atan2

bcd

complex

_matherr

sin

tan


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
cos	+	+	+	+	+	+	+
cosl	+		+	+			+


cosh, coshl

See Also	Example	Portability

Syntax

#include <math.h>

double cosh(double x);

long double coshl(long double x);

Description

Calculates the hyperbolic cosine of a value.

cosh computes the hyperbolic cosine, [image]. coshl is the long double version; it takes a long double argument and returns a long double result.

This function can be used with bcd and complex types.

Return Value

cosh returns the hyperbolic cosine of the argument.

When the correct value would create an overflow, these functions return the value HUGE_VAL (cosh) or _LHUGE_VAL (coshl) with the appropriate sign, and the global variable errno is set to ERANGE. Error handling for these functions can be modified through the functions _matherr and _matherrl.


See Also

acos

asin

atan

atan2

bcd

complex

cos

_matherr

sin

sinh

tan

tanh


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
cosh	+	+	+	+	+	+	+
coshl	+		+	+			+


country

Example	Portability

Syntax

#include <dos.h>

struct COUNTRY *country(int xcode, struct country *cp);

Description

Returns country-dependent information.

country specifies how certain country-dependent data (such as dates, times, and currency) will be formatted. The values set by this function depend on the operating system version being used.

If cp has a value of -1, the current country is set to the value of xcode, which must be nonzero. The COUNTRY structure pointed to by cp is filled with the country-dependent information of the current country (if xcode is set to zero), or the country given by xcode.

The structure COUNTRY is defined as follows:

struct COUNTRY{

   short co_date;             /* date format */

   char co_curr[5];           /* currency symbol */

   char co_thsep[2];          /* thousands separator */

   char co_desep[2];          /* decimal separator */

   char co_dtsep[2];          /* date separator */

   char co_tmsep[2];          /* time separator */

   char co_currstyle;         /* currency style */

   char co_digits;            /* significant digits in currency */

   char co_time;              /* time format */

   long co_case;              /* case map */

   char co_dasep[2];          /* data separator */

   char co_fill[10];          /* filler */

};

The date format in co_date is

0	for the U.S. style of month, day, year.

1	for the European style of day, month, year.

2	for the Japanese style of year, month, day.

Currency display style is given by co_currstyle as follows:

0	for the currency symbol to precede the value with no spaces between the symbol and the number.

1 	for the currency symbol to follow the value with no spaces between the number and the symbol.

2	for the currency symbol to precede the value with a space after the symbol.

3	for the currency symbol to follow the number with a space before the symbol.

Return Value

On success, country returns the pointer argument cp. On error, it returns NULL.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	 	 	 	+


cprintf

See Also	Example	Portability

Syntax

#include <conio.h>

int cprintf(const char *format[, argument, ...]);

Description

Writes formatted output to the screen.

cprintf accepts a series of arguments, applies to each a format specifier contained in the format string pointed to by format, and outputs the formatted data directly to the current text window on the screen. There must be the same number of format specifiers as arguments.

For details details on format specifiers, see printf Format Specifiers.

The string is written either directly to screen memory or by way of a BIOS call, depending on the value of the global variable _directvideo.

Unlike fprintf and printf, cprintf does not translate linefeed characters (\n) into carriage-return/linefeed character pairs (\r\n). Tab characters (specified by \t) are not expanded into spaces.

Note:	Do not use this function for Win32s or Win32 GUI applications.

Return Value

cprintf returns the number of characters output.


See Also

_directvideo (global variable)

fprintf

printf

putch

sprintf

vprintf


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+	 	 	+


cputs

See Also	Example	Portability

Syntax

#include <conio.h>

int cputs(const char *str);

Description

Writes a string to the screen.

cputs writes the null-terminated string str to the current text window. It does not append a newline character.

The string is written either directly to screen memory or by way of a BIOS call, depending on the value of the global variable _directvideo. Unlike puts, cputs does not translate linefeed characters (\n) into carriage-return/linefeed character pairs (\r\n).

Note:	Do not use this function for Win32s or Win32 GUI applications.

Return Value

cputs returns the last character printed.


See Also

cgets

fputs

putch

puts


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+	 	 	+


creat

See Also	Example	Portability

Syntax

#include <io.h>

int creat(const char *path, int amode);

Description

Creates a new file or overwrites an existing one.

Note:	Remember that a backslash in a path requires '\\'.

creat creates a new file or prepares to rewrite an existing file given by path. amode applies only to newly created files.

A file created with creat is always created in the translation mode specified by the global variable _fmode (O_TEXT or O_BINARY).

If the file exists and the write attribute is set, creat truncates the file to a length of 0 bytes, leaving the file attributes unchanged. If the existing file has the read-only attribute set, the creat call fails and the file remains unchanged.

The creat call examines only the S_IWRITE bit of the access-mode word amode. If that bit is 1, the file can be written to. If the bit is 0, the file is marked as read-only. All other operating system attributes are set to 0.

amode can be one of the following (defined in sys\stat.h):

Value of amode 	Access permission

S_IWRITE	Permission to write

S_IREAD	Permission to read

S_IREAD / S_IWRITE	Permission to read and write (write permission implies read permission)

Return Value

Upon successful completion, creat returns the new file handle, a nonnegative integer; otherwise, it returns -1.

In the event of error, the global variable errno is set to one of the following:

EACCES	Permission denied

ENOENT	Path or file name not found

EMFILE	Too many open files


See Also

chmod

chsize

close

creatnew

creattemp

dup

dup2

_fmode (global variable)

fopen

open

_rtl_creat

sopen

write


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


creatnew

See Also	Example	Portability

Syntax

#include <io.h>

int creatnew(const char *path, int mode);

Description

Creates a new file.

creatnew is identical to _rtl_creat with one exception: If the file exists, creatnew returns an error and leaves the file untouched.

The mode argument to creatnew can be zero or an OR-combination of any one of the following constants (defined in dos.h):

FA_HIDDEN	Hidden file

FA_RDONLY	Read-only attribute

FA_SYSTEM	System file

Return Value

Upon successful completion, creat returns the new file handle, a nonnegative integer; otherwise, it returns -1.

In the event of error, the global variable errno is set to one of the following values:

EACCES	Permission denied

EEXIST	File already exists

EMFILE	Too many open files

ENOENT	Path or file name not found


See Also

close

creat

creattemp

_dos_creatnew

dup

_fmode (global variable)

open

_rtl_creat


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


creattemp

See Also	Example	Portability

Syntax

#include <io.h>

int creattemp(char *path, int attrib);

Description

Creates a unique file in the directory associated with the path name.

A file created with creattemp is always created in the translation mode specified by the global variable _fmode (O_TEXT or O_BINARY).

path is a path name ending with a backslash (\). A unique file name is selected in the directory given by path. The newly created file name is stored in the path string supplied. path should be long enough to hold the resulting file name. The file is not automatically deleted when the program terminates.

creattemp accepts attrib, a DOS attribute word. Upon successful file creation, the file pointer is set to the beginning of the file. The file is opened for both reading and writing.

The attrib argument to creattemp can be zero or an OR-combination of any one of the following constants (defined in dos.h):

FA_HIDDEN 	Hidden file

FA_RDONLY	Read-only attribute

FA_SYSTEM	System file

Return Value

Upon successful completion, the new file handle, a nonnegative integer, is returned; otherwise, -1 is returned.

In the event of error, the global variable errno is set to one of the following values:

EACCES	Permission denied

EMFILE	Too many open files

ENOENT	Path or file name not found


See Also

close

creat

creatnew

dup

_fmode (global variable)

open

_rtl_creat


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


_crotl, _crotr

See Also	Example	Portability

Syntax

#include <stdlib.h>

unsigned char _crotl(unsigned char val, int count);

unsigned char _crotr(unsigned char val, int count);

Description

Rotates an unsigned char left or right.

_crotl rotates the given val to the left count bits. _crotr rotates the given val to the right count bits.

The argument val is an unsigned char, or its equivalent in decimal or hexadecimal form.

Return Value

The functions return the rotated word:

_crotl returns the value of val left-rotated count bits.

_crotr returns the value of val right-rotated count bits.


See Also

_lrotl

_lrotr

_rotl

_rotr


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


cscanf

See Also	Example	Portability

Syntax

#include <conio.h>

int cscanf(char *format[, address, ...]);

Description

Scans and formats input from the console.

cscanf scans a series of input fields one character at a time, reading directly from the console. Then each field is formatted according to a format specifier passed to cscanf in the format string pointed to by format. Finally, cscanf stores the formatted input at an address passed to it as an argument following format, and echoes the input directly to the screen. There must be the same number of format specifiers and addresses as there are input fields.

Note:	For details on format specifiers, see scanf Format Specifiers.

cscanf might stop scanning a particular field before it reaches the normal end-of-field (whitespace) character, or it might terminate entirely for a number of reasons. See scanf for a discussion of possible causes.

Note:	Do not use this function for Win32s or Win32 GUI applications.

Return Value

cscanf returns the number of input fields successfully scanned, converted, and stored; the return value does not include scanned fields that were not stored. If no fields were stored, the return value is 0.

If cscanf attempts to read at end-of-file , the return value is EOF.


See Also

fscanf

getche

scanf

sscanf


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+	 	 	+


ctime

See Also	Example	Portability

Syntax

#include <time.h>

char *ctime(const time_t *time);

Description

Converts date and time to a string.

ctime converts a time value pointed to by time (the value returned by the function time) into a 26-character string in the following form, terminating with a newline character and a null character:

   Mon Nov 21 11:31:54 1983\n\0

All the fields have constant width.

The global long variable _timezone contains the difference in seconds between GMT and local standard time (in PST, _timezone is 8*60*60). The global variable _daylight is nonzero if and only if the standard U.S. _daylight saving time conversion should be applied. These variables are set by the tzset function, not by the user program directly.

Return Value

ctime returns a pointer to the character string containing the date and time. The return value points to static data that is overwritten with each call to ctime.


See Also

asctime

_daylight (global variable)

difftime

ftime

getdate

gmtime

localtime

settime

time

_timezone (global variable)

tzset


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


ctrlbrk

See Also	Example	Portability

Syntax

#include <dos.h>

void ctrlbrk(int (*handler)(void));

Description

Sets control-break handler.

ctrlbrk sets a new control-break handler function pointed to by handler. The interrupt vector 0x23 is modified to call the named function.

ctrlbrk establishes a DOS interrupt handler that calls the named function; the named function is not called directly.

The handler function can perform any number of operations and system calls. The handler does not have to return; it can use longjmp to return to an arbitrary point in the program. The handler function returns 0 to abort the current program; any other value causes the program to resume execution.

Return Value

ctrlbrk returns nothing.


See Also

getcbrk

signal


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


cwait

See Also	Example	Portability

Syntax

#include <process.h>

int cwait(int *statloc, int pid, int action);

Description

Waits for child process to terminate.

The cwait function waits for a child process to terminate. The process ID of the child to wait for is pid. If statloc is not NULL, it points to the location where cwait will store the termination status. The action specifies whether to wait for the process alone, or for the process and all of its children.

If the child process terminated normally (by calling exit, or returning from main), the termination status word is defined as follows:

Bits 0-7	Zero

Bits 8-15	The least significant byte of the return code from the child process. This is the value that is passed to exit, or is returned from main. If the child process simply exited from main without returning a value, this value will be unpredictable.

If the child process terminated abnormally, the termination status word is defined as follows:

Bits 0-7	Termination information about the child:

 	1	Critical error abort.

 	2	Execution fault, protection exception.

 	3	External termination signal.

Bits 8-15	Zero

If pid is 0, cwait waits for any child process to terminate. Otherwise, pid specifies the process ID of the process to wait for; this value must have been obtained by an earlier call to an asynchronous spawn function.

The acceptable values for action are WAIT_CHILD, which waits for the specified child only, and WAIT_GRANDCHILD, which waits for the specified child and all of its children. These two values are defined in process.h.

Return Value

When cwait returns after a normal child process termination, it returns the process ID of the child.

When cwait returns after an abnormal child termination, it returns -1 to the parent and sets errno to EINTR (the child process terminated abnormally).

If cwait returns without a child process completion, it returns a -1 value and sets errno to one of the following values:

ECHILD	No child exists or the pid value is bad

EINVAL	A bad action value was specified


See Also

spawnl

wait


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

 	 	 	+	 	 	+


delline

See Also	Example	Portability

Syntax

#include <conio.h>

void delline(void);

Description

Deletes line in text window.

delline deletes the line containing the cursor and moves all lines below it one line up. delline operates within the currently active text window.

Note:	Do not use this function for Win32s or Win32 GUI applications.

Return Value

None.


See Also

clreol

clrscr

insline

window


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


difftime

See Also	Example	Portability

Syntax

#include <time.h>

double difftime(time_t time2, time_t time1);

Description

Computes the difference between two times.

difftime calculates the elapsed time in seconds, from time1 to time2.

Return Value

difftime returns the result of its calculation as a double.


See Also

asctime

ctime

_daylight (global variable)

gmtime

localtime

time

_timezone (global variable)


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


disable, _disable, enable, _enable

See Also	Examples	Portability

Syntax

#include <dos.h>

void disable(void);

void _disable(void);

void enable(void);

void _enable(void);

Description

Disables and enables interrupts.

These macros are designed to provide a programmer with flexible hardware interrupt control.

disable and _disable macros disable interrupts. Only the NMI (non-maskable interrupt) is allowed from any external device.

enable and _enable macros enable interrupts, allowing any device interrupts to occur.

Return Value

None.


See Also

getvect


Examples

disable

_disable

enable

_enable


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+


div

See Also	Example	Portability

Syntax

#include <stdlib.h>

div_t  div(int numer, int denom);

Description

Divides two integers, returning quotient and remainder.

div divides two integers and returns both the quotient and the remainder as a div_t type. numer and denom are the numerator and denominator, respectively. The div_t type is a structure of integers defined (with typedef) in stdlib.h as follows:

typedef struct {

   int  quot;      /* quotient */

   int  rem;       /* remainder */

} div_t;

Return Value

div returns a structure whose elements are quot (the quotient) and rem (the remainder).


See Also

ldiv


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	+	+	+


_dos_close

See Also	Example	Portability

Syntax

#include <dos.h>

unsigned _dos_close(int handle);

Description

Closes a file.

The _dos_close function closes the file associated with handle; handle is a file handle obtained from a _dos_creat, _dos_creatnew, or _dos_open call.

Return Value

Upon successful completion, _dos_close returns 0. Otherwise, it returns the operating system error code and the global variable errno is set to

  EBADF    Bad file number


See Also

_dos_creat

_dos_open

_dos_read

_dos_write


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	 	 	 	+


_dos_commit

See Also	Example	Portability

Syntax

#include <dos.h>

unsigned _dos_commit(int handle);

Description

Outputs a file to the disk.

This function makes DOS flush any output that it has buffered for a specific handle to the disk.

Return Value

The function returns zero on success. On failure the function returns the DOS error code and sets errno to EBADF on failure.


See Also

_dos_creat

_dos_write

_rtl_close

_rtl_creat


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


_dos_creat

See Also	Example	Portability

Syntax

#include <dos.h>

unsigned _dos_creat(const char *path,int attrib,int *handlep);

Description

Creates a new file or overwrites an existing one.

_dos_creat opens the file specified by path. The file is always opened in binary mode. Upon successful file creation, the file pointer is set to the beginning of the file. _dos_creat stores the file handle in the location pointed to by handlep. The file is opened for both reading and writing.

If the file already exists, its size is reset to 0. (This is essentially the same as deleting the file and creating a new file with the same name.)

The attrib argument is an ORed combination of one or more of the following constants (defined in dos.h):

_A_NORMAL	Normal file

_A_RDONLY	Read-only file

_A_HIDDEN	Hidden file

_A_SYSTEM	System file

Return Value

On success, _dos_creat returns 0.

On error, it returns the operating system error code and the global variable errno is set to one of the following values:

EACCES	Permission denied

ENOENT	Path or file name not found

EMFILE	Too many open files


See Also

chsize

close

creat

creatnew

creattemp

_rtl_chmod

_rtl_close


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	 	 	 	+


_dos_creatnew

See Also	Example	Portability

Syntax

#include <dos.h>

unsigned _dos_creatnew(const char *path, int attrib, int *handlep);

Description

Creates a new file.

_dos_creatnew creates and opens the new file path. The file is given the access permission attrib, an operating-system attribute word. The file is always opened in binary mode. Upon successful file creation, the file handle is stored in the location pointed to by handlep, and the file pointer is set to the beginning of the file. The file is opened for both reading and writing.

If the file already exists, _dos_creatnew returns an error and leaves the file untouched.

The attrib argument to _dos_creatnew is an OR combination of one or more of the following constants (defined in dos.h):

_A_NORMAL	Normal file

_A_RDONLY	Read-only file

_A_HIDDEN	Hidden file

_A_SYSTEM	System file

Return Value

Upon successful completion, _dos_creatnew returns 0. Otherwise, it returns the operating system error code, and the global variable errno is set to one of the following:

EACCES	Permission denied

EEXIST	File already exists

EMFILE	Too many open files

ENOENT	Path or file name not found


See Also

creatnew

_dos_close

_dos_creat

_dos_getfileattr

_dos_setfileattr


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	 	 	 	+


dosexterr

Example	Portability

Syntax

#include <dos.h>

int dosexterr(struct DOSERROR *eblkp);

Description

Gets extended DOS error information.

This function fills in the DOSERROR structure pointed to by eblkp with extended error information after a DOS call has failed. The structure is defined as follows:

struct  DOSERROR {

   int de_exterror;     /* extended error */

   char de_class;       /* error class */

   char de_action;      /* action */

   char de_locus;       /* error locus */

};

The values in this structure are obtained by way of DOS call 0x59. A de_exterror value of 0 indicates that the prior DOS call did not result in an error.

Return Value

dosexterr returns the value de_exterror.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


_dos_findfirst

See Also	Example	Portability

Syntax

#include <dos.h>

unsigned _dos_findfirst(const char *pathname, int attrib,

                        struct find_t *ffblk);

Description

Searches a disk directory.

_dos_findfirst begins a search of a disk directory.

pathname is a string with an optional drive specifier, path, and file name of the file to be found. The file name portion can contain wildcard match characters (such as ? or *). If a matching file is found, the find_t structure pointed to by ffblk is filled with the file-directory information.

The format of the find_t structure is as follows:

struct find_t {

   char reserved[21];     /* reserved by the operating system */

   char attrib;           /* attribute found */

   int wr_time;           /* file time */

   int wr_date;           /* file date */

   long size;             /* file size */

   char name[13];         /* found file name */

};

attrib is an operating system file-attribute word used in selecting eligible files for the search. attrib is an OR combination of one or more of the following constants (defined in dos.h):

_A_NORMAL	Normal file

_A_RDONLY	Read-only attribute

_A_HIDDEN	Hidden file

_A_SYSTEM	System file

_A_VOLID	Volume label

_A_SUBDIR	Directory

_A_ARCH	Archive

For more detailed information about these attributes, refer to your operating system reference manuals.

Note:	wr_time and wr_date contain bit fields for referring to the file's date and time. The structure of these fields was established by the operating system.

wr_time:

Bits 0-4	The result of seconds divided by 2 (for example, 10 here means 20 seconds)

Bits 5-10	Minutes

Bits 11-15 	Hours

wr_date:

Bits 0-4	Day

Bits 5-8	Month

Bits 9-15	Years since 1980 (for example, 9 here means 1989)

Return Value

_dos_findfirst returns 0 on successfully finding a file matching the search pathname. When no more files can be found, or if there is some error in the file name, the operating system error code is returned, and the global variable errno is set to

ENOENT	Path or file name not found


See Also

_dos_findnext


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	 	 	 	+


_dos_findnext

See Also	Example	Portability

Syntax

#include <dos.h>

unsigned _dos_findnext(struct find_t *ffblk);

Description

Continues _dos_findfirst search.

_dos_findnext is used to fetch subsequent files that match the pathname given in _dos_findfirst. ffblk is the same block filled in by the _dos_findfirst call. This block contains necessary information for continuing the search. One file name for each call to _dos_findnext is returned until no more files are found in the directory matching the pathname.

Return Value

_dos_findnext returns 0 on successfully finding a file matching the search pathname. When no more files can be found, or if there is some error in the file name, the operating system error code is returned, and the global variable errno is set to

ENOENT	Path or file name not found


See Also

_dos_findfirst


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	 	 	 	+


_dos_getdate, _dos_setdate, getdate, setdate

See Also	Examples	Portability

Syntax

#include <dos.h>

void _dos_getdate(struct dosdate_t *datep);

unsigned _dos_setdate(struct dosdate_t *datep);

void getdate(struct date *datep);

void setdate(struct date *datep);

Description

Gets and sets system date.

getdate fills in the date structure (pointed to by datep) with the system's current date.

setdate sets the system date (month, day, and year) to that in the date structure pointed to by datep.

The date structure is defined as follows:

struct date{

   int da_year;     /* current year */

   char da_day;     /* day of the month */

   char da_mon;     /* month (1 = Jan) */

};

_dos_getdate fills in the dosdate_t structure (pointed to by datep) with the system's current date.

The dosdate_t structure is defined as follows:

struct dosdate_t {

   unsigned char day;       /* 1-31 */

   unsigned char month;     /* 1-12 */

   unsigned int  year;      /* 1980 - 2099 */

   unsigned char dayofweek; /* 0 - 6 (0=Sunday) */

};

Return Value

_dos_getdate, getdate, and setdate do not return a value.

If the date is set successfully, _dos_setdate returns 0.

Otherwise, it returns a non-zero value and the global variable errno is set to

EINVAL	Invalid date


See Also

ctime

gettime

settime


Examples

getdate

_dos_getdate

_dos_setdate

setdate


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	 	 	 	+


_dos_getdiskfree

See Also	Example	Portability

Syntax

#include <dos.h>

unsigned _dos_getdiskfree(unsigned char drive, struct diskfree_t *dtable);

Description

Gets disk free space.

_dos_getdiskfree accepts a drive specifier in drive (0 for default, 1 for A, 2 for B, and so on) and fills in the diskfree_t structure pointed to by dtable with disk characteristics.

The diskfree_t structure is defined as follows:

struct diskfree_t {

   unsigned avail_clusters;       /* available clusters */

   unsigned total_clusters;       /* total clusters */

   unsigned bytes_per_sector;     /* bytes per sector */

   unsigned sectors_per_cluster;  /* sectors per cluster */

};

Return Value

_dos_getdiskfree returns 0 if successful. Otherwise, it returns a non-zero value and the global variable errno is set to

EINVAL	Invalid drive specified


See Also

getfat

getfatd


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	 	 	 	+


_dos_getdrive, _dos_setdrive

See Also	Examples	Portability

Syntax

#include <dos.h>

void _dos_getdrive(unsigned *drivep);

void _dos_setdrive(unsigned drivep, unsigned *ndrives);

Description

Gets and sets the current drive number.

_dos_getdrive gets the current drive number.

_dos_setdrive sets the current drive and stores the total number of drives at the location pointed to by ndrives.

The drive numbers at the location pointed to by drivep are as follows: 1 for A, 2 for B, 3 for C, and so on.

This function changes the current drive of the parent process.

Return Value

None. Use _dos_getdrive to verify that the current drive was changed successfully.


See Also

getcwd


Examples

_dos_getdrive

_dos_setdrive


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	 	 	 	+


_dos_getfileattr, _dos_setfileattr

See Also	Examples	Portability

Syntax

#include <dos.h>

int _dos_getfileattr(const char *path, unsigned *attribp);

int _dos_setfileattr(const char *path, unsigned attrib);

Description

Changes file access mode.

_dos_getfileattr fetches the file attributes for the file path. The attributes are stored at the location pointed to by attribp.

_dos_setfileattr sets the file attributes for the file path to the value attrib.  The file attributes can be an OR combination of the following symbolic constants (defined in dos.h):

_A_RDONLY	Read-only attribute

_A_HIDDEN	Hidden file

_A_SYSTEM	System file

_A_VOLID	Volume label

_A_SUBDIR	Directory

_A_ARCH	Archive

_A_NORMAL	Normal file (no attribute bits set)

Return Value

Upon successful completion, _dos_getfileattr and _dos_setfileattr return 0. Otherwise, these functions return the operating system error code, and the global variable errno is set to

ENOENT	Path or file name not found


See Also

chmod

stat


Examples

_dos_getfileattr

_dos_setfileattr


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	 	 	 	+


_dos_getftime, _dos_setftime

See Also	Examples	Portability

Syntax

#include <dos.h>

unsigned _dos_getftime(int handle, unsigned *datep, unsigned *timep);

unsigned _dos_setftime(int handle, unsigned date, unsigned time);

Description

Gets and sets file date and time.

_dos_getftime retrieves the file time and date for the disk file associated with the open handle. The file must have been previously opened using _dos_open, _dos_creat, or _dos_creatnew. _dos_getftime stores the date and time at the locations pointed to by datep and timep.

_dos_setftime sets the file's new date and time values as specified by date and time.

Note that the date and time values contain bit fields for referring to the file's date and time. The structure of these fields was established by the operating system.

Date:

Bits 0-4	Day

Bits 5-8	Month

Bits 9-15	Years since 1980 (for example, 9 here means 1989)

Time:

Bits 0-4	The result of seconds divided by 2 (for example, 10 here means 20 seconds)

Bits 5-10	Minutes

Bits 11-15	Hours

Return Value

_dos_getftime and _dos_setftime return 0 on success.

In the event of an error return, the operating system error code is returned and the global variable errno is set to one of the following values:

EACCES	Permission denied

EBADF	Bad file number


See Also

fstat

stat


Examples

_dos_getftime

_dos_setftime


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	 	 	 	+


_dos_gettime, _dos_settime

See Also	Examples	Portability

Syntax

#include <dos.h>

void _dos_gettime(struct dostime_t *timep);

unsigned _dos_settime(struct dostime_t *timep);

Description

Gets and sets system time.

_dos_gettime fills in the dostime_t structure pointed to by timep with the system's current time.

_dos_settime sets the system time to the values in the dostime_t structure pointed to by timep.

The dostime_t structure is defined as follows:

struct dostime_t {

   unsigned char hour;     /* hours 0-23 */

   unsigned char minute;   /* minutes 0-59 */

   unsigned char second;   /* seconds 0-59 */

   unsigned char hsecond;  /* hundredths of seconds 0-99 */

};

Return Value

_dos_gettime does not return a value.

If _dos_settime is successful, it returns 0. Otherwise, it returns the operating system error code, and the global variable errno is set to:

EINVAL	Invalid time


See Also

_dos_getdate

_dos_setdate

_dos_settime

stime

time


Examples

_dos_gettime

_dos_settime


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	 	 	 	+


_dos_getvect

See Also	Example	Portability

Syntax

#include <dos.h>

void interrupt(*_dos_getvect(unsigned interruptno)) ();

Description

Gets interrupt vector.

Every processor of the 8086 family includes a set of interrupt vectors, numbered 0 to 255. The 4-byte value in each vector is actually an address, which is the location of an interrupt function.

_dos_getvect reads the value of the interrupt vector given by interruptno and returns that value as a (far) pointer to an interrupt function. The value of interruptno can be from 0 to 255.

Return Value

_dos_getvect returns the current 4-byte value stored in the interrupt vector named by interruptno.


See Also

_disable

_enable

_dos_setvect


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


_dos_open

See Also	Example	Portability

Syntax

#include <fcntl.h>

#include <share.h>

#include <dos.h>

unsigned _dos_open(const char *filename, unsigned oflags, int *handlep);

Description

Opens a file for reading or writing.

_dos_open open the file specified by filename, then prepares it for reading or writing, as determined by the value of oflags. The file is always opened in binary mode. _dos_open stores the file handle at the location pointed to by handlep.

oflags uses the flags from the following two lists. Only one flag from List 1 can be used (and one must be used) and the flags in List 2 can be used in any logical combination.

List 1: Read/write flags

O_RDONLY	Open for reading.

O_WRONLY	Open for writing.

O_RDWR	Open for reading and writing.

The following additional values can be included in oflags (using an OR operation):

List 2: Other access flags

O_NOINHERIT	The file is not passed to child programs.

SH_COMPAT	Allow other opens with SH_COMPAT. The call will fail if the file has already been opened in any other shared mode.

SH_DENYRW	Only the current handle can have access to the file.

SH_DENWR	Allow only reads from any other open to the file.

SH_DENYRD	Allow only writes from any other open to the file.

SH_DENYNO	Allow other shared opens to the file, but not other SH_COMPAT opens.

Note:	These symbolic constants are defined in fcntl.h and share.h.

Only one of the SH_DENYxx values can be included in a single _dos_open routine. These file-sharing attributes are in addition to any locking performed on the files.

The maximum number of simultaneously open files is defined by HANDLE_MAX.

Return Value

On success:_dos_open returns 0 and stores the file handle at the location pointed to by handlep. The file pointer, which marks the current position in the file, is set to the beginning of the file.

On error, it returns the operating system error code and sets the global variable errno to one of the following values:

EACCES	Permission denied

EINVACC	Invalid access code

EMFILE	Too many open files

ENOENT	Path or file not found


See Also

open

_rtl_read

sopen


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	 	 	 	+


_dos_read

See Also	Example	Portability

Syntax

#include <dos.h>

unsigned _dos_read(int handle, void *buf, unsigned len, unsigned *nread);

Description

Reads from file.

The _dos_read function reads len bytes from the file associated with handle into the buffer pointed to by the pointer buf. The actual number of bytes read is stored at the location pointed to by nread; when an error occurs, or the end-of-file is encountered, this number might be less than len.

_dos_read does not remove carriage returns because it treats all files as binary files.

handle is a file handle obtained from a _dos_creat, _dos_creatnew, or _dos_open call.

For _read, handle is a file handle obtained from a creat, open, dup, or dup2 call.

On disk files, _dos_read begins reading at the current file pointer. When the reading is complete, they increment the file pointer by the number of bytes read. On devices, the bytes are read directly from the device.

The maximum number of bytes that _dos_read can read is UINT_MAX -1 (because UINT_MAX is the same as -1, the error return indicator). UINT_MAX is defined in limits.h.

Return Value

On success, _dos_read returns 0.

On error, it returns the DOS error code and sets the global variable errno.

On success, _read returns a positive integer indicating the number of bytes placed in the buffer. On end-of-file, _read returns zero. On error, read returns -1, and the global variable errno is set to one of the following values:

EACCES	Permission denied

EBADF	Bad file number


See Also

_open

read

_rtl_write


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	 	 	 	+


_dos_setvect

See Also	Example	Portability

Syntax

#include <dos.h>

void _dos_setvect(unsigned interruptno, void interrupt (*isr) ());

Description

Sets interrupt vector entry.

Every processor of the 8086 family includes a set of interrupt vectors, numbered 0 to 255. The 4-byte value in each vector is actually an address, which is the location of an interrupt function.

_dos_setvect sets the value of the interrupt vector named by interruptno to a new value, isr, which is a far pointer containing the address of a new interrupt function. The address of a C routine can be passed to isr only if that routine is declared to be an interrupt routine.

If you use the prototypes declared in dos.h, simply pass the address of an interrupt function to _dos_setvect in any memory model.

Return Value

None.


See Also

_dos_getvect


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


dostounix

See Also	Example	Portability

Syntax

#include <dos.h>

long dostounix(struct date *d, struct time *t);

Description

Converts date and time to UNIX time format.

dostounix converts a date and time as returned from getdate and gettime into UNIX time format. d points to a date structure, and t points to a time structure containing valid date and time information.

The date and time must not be earlier than or equal to Jan 1 1980 00:00:00.

Return Value

UNIX version of current date and time parameters: number of seconds since 00:00:00 on January 1, 1970 (GMT).


See Also

getdate

gettime

unixtodos


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	 	 	 	+


_dos_write

See Also	Example	Portability

Syntax

#include <dos.h>

unsigned _dos_write(int handle, const void far *buf, unsigned len, unsigned *nwritten);

unsigned _dos_write(int handle, const void *buf, unsigned len, unsigned *nwritten);

Description

Writes to a file.

_dos_write writes len bytes from the buffer pointed to by pointer buf to the file associated with handle.

_dos_write does not translate a linefeed character (LF) to a CR/LF pair because it treats all files as binary data.

The actual number of bytes written is stored at the location pointed to by nwritten. If the number of bytes actually written is less than that requested, the condition should be considered an error and probably indicates a full disk. For disk files, writing always proceeds from the current file pointer. On devices, bytes are directly sent to the device.

Return Value

On success, _dos_write returns 0.

On error, it returns the operating system error code and sets the global variable errno is set to one of the following values:

EACCES	Permission denied

EBADF	Bad file number


See Also

_dos_open

_dos_creat

_dos_read


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	 	 	 	+


dup

See Also	Example	Portability

Syntax

#include <io.h>

int dup(int handle);

Description

Duplicates a file handle.

dup creates a new file handle that has the following in common with the original file handle:

Same open file or device

Same file pointer (that is, changing the file pointer of one changes the other)

Same access mode (read, write, read/write)

handle is a file handle obtained from a call to creat, open, dup, dup2, _rtl_creat, or _rtl_open.

Return Value

Upon successful completion, dup returns the new file handle, a nonnegative integer; otherwise, dup returns -1.

In the event of error, the global variable errno is set to one of the following values:

EBADF	Bad file number

EMFILE	Too many open files


See Also

close

creat

creatnew

creattemp

dup2

fopen

open

_rtl_close

_rtl_creat

_rtl_open


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


dup2

See Also	Example	Portability

Syntax

#include <io.h>

int dup2(int oldhandle, int newhandle);

Description

Duplicates a file handle (oldhandle) onto an existing file handle (newhandle).

dup2 creates a new file handle that has the following in common with the original file handle:

Same open file or device

Same file pointer (that is, changing the file pointer of one changes the other)

Same access mode (read, write, read/write)

dup2 creates a new handle with the value of newhandle. If the file associated with newhandle is open when dup2 is called, the file is closed.

newhandle and oldhandle are file handles obtained from a creat, open, dup, or dup2 call.

Return Value

dup2 returns 0 on successful completion, -1 otherwise.

In the event of error, the global variable errno is set to one of the following values:

  EBADF  Bad file number

  EMFILE Too many open files


See Also

close

creat

creatnew

creattemp

dup

fopen

open

_rtl_close

_rtl_creat

_rtl_open


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


ecvt

See Also	Example	Portability

Syntax

#include <stdlib.h>

char *ecvt(double value, int ndig, int *dec, int *sign);

Description

Converts a floating-point number to a string.

ecvt converts value to a null-terminated string of ndig digits, starting with the leftmost significant digit, and returns a pointer to the string. The position of the decimal point relative to the beginning of the string is stored indirectly through dec (a negative value for dec means that the decimal lies to the left of the returned digits). There is no decimal point in the string itself. If the sign of value is negative, the word pointed to by sign is nonzero; otherwise, it's 0. The low-order digit is rounded.

Return Value

The return value of ecvt points to static data for the string of digits whose content is overwritten by each call to ecvt and fcvt.


See Also

fcvt

gcvt

sprintf


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


_ _emit_ _

Example	Portability

Syntax

#include <dos.h>

void _ _emit_ _(argument, ...);

Description

Inserts literal values directly into code.

_ _emit_ _ is an inline function that lets you insert literal values directly into object code as it is compiling. It is used to generate machine language instructions without using inline assembly language or an assembler.

Generally the arguments of an _ _emit_ _ call are single-byte machine instructions. However, because of the capabilities of this function, more complex instructions, complete with references to C variables, can be constructed.

You should use this function only if you are familiar with the machine language of the 80x86 processor family. You can use this function to place arbitrary bytes in the instruction code of a function; if any of these bytes is incorrect, the program misbehaves and can easily crash your machine. Borland C++ does not attempt to analyze your calls for correctness in any way. If you encode instructions that change machine registers or memory, Borland C++ will not be aware of it and might not properly preserve registers, as it would in many cases with inline assembly language (for example, it recognizes the usage of SI and DI registers in inline instructions). You are completely on your own with this function.

You must pass at least one argument to _ _emit_ _; any number can be given. The arguments to this function are not treated like any other function call arguments in the language. An argument passed to _ _emit_ _ will not be converted in any way.

There are special restrictions on the form of the arguments to _ _emit_ _. Arguments must be in the form of expressions that can be used to initialize a static object. This means that integer and floating-point constants and the addresses of static objects can be used. The values of such expressions are written to the object code at the point of the call, exactly as if they were being used to initialize data. The address of a parameter or auto variable, plus or minus a constant offset, can also be used. For these arguments, the offset of the variable from BP is stored.

The number of bytes placed in the object code is determined from the type of the argument, except in the following cases:

If a signed integer constant (that is 0x90) appears that fits within the range of 0 to 255, it is treated as if it were a character.

If the address of an auto or parameter variable is used, a byte is written if the offset of the variable from BP is between -128 and 127; otherwise, a word is written.

Simple bytes are written as follows:

   _ _emit_ _(0x90);

If you want a word written, but the value you are passing is under 255, simply cast it to unsigned using one of these methods:

   _ _emit_ _(0xB8, (unsigned)17);

   _ _emit_ _(0xB8, 17u);

Two- or four-byte address values can be forced by casting an address to void near * or void far *, respectively.

Return Value

None.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


_endthread

See Also	Examples	Portability

Syntax

#include <process.h>

void _endthread(void);

Description

Terminates execution of a thread.

The _endthread function terminates the currently executing thread. The thread must have been started by an earlier call to _beginthread or _beginthreadNT.

This function is available in the multithread libraries; it is not in the single-thread libraries.

Return Value

The function does not return a value.


See Also

_beginthread

_beginthreadNT


Examples

_beginthread (Win32s version)

_beginthreadNT (Windows NT version)


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

 	 	 	+	 	 	+


eof

See Also	Example	Portability

Syntax

#include <io.h>

int eof(int handle);

Description

Checks for end-of-file.

eof determines whether the file associated with handle has reached end-of-file.

Return Value

If the current position is end-of-file, eof returns the value 1; otherwise, it returns 0. A return value of -1 indicates an error; the global variable errno is set to

EBADF	Bad file number


See Also

clearerr

feof

ferror

perror


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


execl, execle, execlp, execlpe, execv, execve, execvp, execvpe

See Also	Examples	Portability

Syntax

#include <process.h>

int execl(char *path, char *arg0 *arg1, ..., *argn, NULL);

int execle(char *path, char *arg0, *arg1, ..., *argn, NULL, char **env);

int execlp(char *path, char *arg0,*arg1, ..., *argn, NULL);

int execlpe(char *path, char *arg0, *arg1, ..., *argn, NULL, char **env);

int execv(char *path, char *argv[]);

int execve(char *path, char *argv[], char **env);

int execvp(char *path, char *argv[]);

int execvpe(char *path, char *argv[], char **env);

Description

Loads and runs other programs.

The functions in the exec... family load and run (execute) other programs, known as child processes. When an exec... call succeeds, the child process overlays the parent process. There must be sufficient memory available for loading and executing the child process.

path is the file name of the called child process. The exec... functions search for path using the standard search algorithm:

If no explicit extension is given, the functions search for the file as given. If the file is not found, they add .EXE and search again. If not found, they add .COM and search again. If found, the command processor, COMSPEC (Windows) or COMMAND.COM (DOS), is used to run the batch file.

If an explicit extension or a period is given, the functions search for the file exactly as given.

The suffixes l, v, p, and e added to the exec... "family name" specify that the named function operates with certain capabilities.

l	specifies that the argument pointers (arg0, arg1, ..., argn) are passed as separate arguments. Typically, the l suffix is used when you know in advance the number of arguments to be passed.

v	specifies that the argument pointers (argv[0] ..., arg[n]) are passed as an array of pointers. Typically, the v suffix is used when a variable number of arguments is to be passed.

p	specifies that the function searches for the file in those directories specified by the PATH environment variable (without the p suffix, the function searches only the current working directory). If the path parameter does not contain an explicit directory, the function searches first the current directory, then the directories set with the PATH environment variable.

e	specifies that the argument env can be passed to the child process, letting you alter the environment for the child process. Without the e suffix, child processes inherit the environment of the parent process.

Each function in the exec... family must have one of the two argument-specifying suffixes (either l or v). The path search and environment inheritance suffixes (p and e) are optional; for example:

execl is an exec... function that takes separate arguments, searches only the root or current directory for the child, and passes on the parent's environment to the child.

execvpe is an exec... function that takes an array of argument pointers, incorporates PATH in its search for the child process, and accepts the env argument for altering the child's environment.

The exec... functions must pass at least one argument to the child process (arg0 or argv[0]); this argument is, by convention, a copy of path. (Using a different value for this 0th argument won't produce an error.)

path is available for the child process.

When the l suffix is used, arg0 usually points to path, and arg1, ..., argn point to character strings that form the new list of arguments. A mandatory null following argn marks the end of the list.

When the e suffix is used, you pass a list of new environment settings through the argument env. This environment argument is an array of character pointers. Each element points to a null-terminated character string of the form

   envvar = value

where envvar is the name of an environment variable, and value is the string value to which envvar is set. The last element in env is null. When env is null, the child inherits the parents' environment settings.

The combined length of arg0 + arg1 + ... + argn (or of argv[0] + argv[1] + ... + argn[n]), including space characters that separate the arguments, must be less than 128 bytes for a 16-bit application, or 260 bytes for Win32 application. Null terminators are not counted.

When an exec... function call is made, any open files remain open in the child process.

Return Value

If successful, the exec... functions do not return. On error, the exec... functions return -1, and the global variable errno is set to one of the following values:

EACCES	Permission denied

EMFILE	Too many open files

ENOENT	Path or file name not found

ENOEXEC	Exec format error

ENOMEM	Not enough memory


See Also

abort

atexit

_c_exit

_cexit

_exit

exit

_fpreset

searchpath

spawn...

system


Examples

execl

execle

execlp

execlpe

execv

execve

execvp

execvpe


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+	 	 	+


_exit

See Also	Example	Portability

Syntax

#include <stdlib.h>

void _exit(int status);

Description

Terminates program.

_exit terminates execution without closing any files, flushing any output, or calling any exit functions.

The calling process uses status as the exit status of the process. Typically a value of 0 is used to indicate a normal exit, and a nonzero value indicates some error.

Return Value

None.


See Also

abort

atexit

_c_exit

_cexit

exec...

exit

spawn...


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


exit

See Also	Example	Portability

Syntax

#include <stdlib.h>

void exit(int status);

Description

Terminates program.

exit terminates the calling process. Before termination, all files are closed, buffered output (waiting to be output) is written, and any registered "exit functions" (posted with atexit) are called.

status is provided for the calling process as the exit status of the process. Typically a value of 0 is used to indicate a normal exit, and a nonzero value indicates some error. It can be, but is not required, to be set with one of the following:

EXIT_FAILURE	Abnormal program termination; signal to operating system that program has terminated with an error

EXIT_SUCCESS	Normal program termination

Return Value

None.


See Also

abort

atexit

_c_exit

_cexit

exec...

_exit

signal

spawn...


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


exp, expl

See Also	Example	Portability

Syntax

#include <math.h>

double exp(double x);

long double expl(long double x);

Description

Calculates the exponential e to the x.

expl is the long double version; it takes a long double argument and returns a long double result.

This function can be used with bcd and complex types.

Return Value

exp returns e to the x.

Sometimes the arguments passed to these functions produce results that overflow or are incalculable. When the correct value overflows, exp returns the value HUGE_VAL and expl returns _LHUGE_VAL. Results of excessively large magnitude cause the global variable errno to be set to

ERANGE	Result out of range

On underflow, these functions return 0.0, and the global variable errno is not changed. Error handling for these functions can be modified through the functions _matherr and _matherrl.


See Also

frexp

ldexp

log

log10

_matherr

pow

pow10

sqrt


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
exp	+	+	+	+	+	+	+
expl	+		+	+			+


_expand

See Also	Example	Portability

Syntax

#include <malloc.h>

void *_expand(void *block, size_t size);

Description

Grows or shrinks a heap block in place.

This function attempts to change the size of an allocated memory block without moving the block's location in the heap. The data in the block are not changed, up to the smaller of the old and new sizes of the block. The block must have been allocated earlier with malloc, calloc, or realloc, and must not have been freed.

Return Value

If _expand is able to resize the block without moving it, _expand returns a pointer to the block, whose address is unchanged. If _expand is unsuccessful, it returns a NULL pointer and does not modify or resize the block.


See Also

calloc

malloc

realloc


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

 	 	 	+	 	 	+


fabs, fabsl

See Also	Example	Portability

Syntax

#include <math.h>

double fabs(double x);

long double fabsl(long double x);

Description

Returns the absolute value of a floating-point number.

fabs calculates the absolute value of x, a double. fabsl is the long double version; it takes a long double argument and returns a long double result.

Return Value

fabs and fabsl return the absolute value of x.


See Also

abs

cabs

labs


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
fabs	+	+	+	+	+	+	+
fabsl	+		+	+			+


farcalloc

See Also	Example	Portability

Syntax

#include <alloc.h>

void far *farcalloc(unsigned long nunits, unsigned long unitsz);

Description

Allocates memory from the far heap.

farcalloc allocates memory from the far heap for an array containing nunits elements, each unitsz bytes long.

For allocating from the far heap, note that:

All available RAM can be allocated.

Blocks larger than 64K can be allocated.

Far pointers (or huge pointers if blocks are larger than 64K) are used to access the allocated blocks.

In the compact, large, and huge memory models, farcalloc is similar, though not identical, to calloc. It takes unsigned long parameters, while calloc takes unsigned parameters. For DOS users, a tiny model program cannot use faralloc.

Return Value

farcalloc returns a pointer to the newly allocated block, or NULL if not enough space exists for the new block.


See Also

calloc

farfree

farmalloc

malloc


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


farfree

See Also	Example	Portability

Syntax

#include <alloc.h>

void farfree(void far * block);

Description

Frees a block from far heap.

farfree releases a block of memory previously allocated from the far heap.

In the small and medium memory models, blocks allocated by farmalloc cannot be freed with normal free, and blocks allocated with malloc cannot be freed with farfree. In these models, the two heaps are completely distinct. For DOS users, a tiny model program cannot use farfree.

Return Value

None.


See Also

farcalloc

farmalloc


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


farmalloc

See Also	Example	Portability

Syntax

#include <alloc.h>

void far *farmalloc(unsigned long nbytes);

Description

Allocates from far heap.

farmalloc allocates a block of memory nbytes bytes long from the far heap.

For allocating from the far heap, note that

All available RAM can be allocated.

Blocks larger than 64K can be allocated.

Far pointers are used to access the allocated blocks.

In the compact, large, and huge memory models, farmalloc is similar though not identical to malloc. It takes unsigned long parameters, while malloc takes unsigned parameters. For DOS users, a tiny model program cannot use farmalloc.

Return Value

farmalloc returns a pointer to the newly allocated block, or NULL if not enough space exists for the new block.


See Also

farcalloc

farfree

farrealloc

malloc


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


farrealloc

See Also	Example	Portability

Syntax

#include <alloc.h>

void far *farrealloc(void far *oldblock, unsigned long nbytes);

Description

Adjusts allocated block in far heap.

farrealloc adjusts the size of the allocated block to nbytes copying the contents to a new location if necessary.

For allocating from the far heap:

All available RAM can be allocated.

Blocks larger than 64K can be allocated.

Far pointers are used to access the allocated blocks.

For DOS users, a tiny model program cannot use farrealloc.

Return Value

farrealloc returns the address of the reallocated block which might be different than the address of the original block. If the block cannot be reallocated farrealloc returns NULL.


See Also

realloc


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


fclose

See Also	Example	Portability

Syntax

#include <stdio.h>

int fclose(FILE *stream);

Description

Closes a stream.

fclose closes the named stream. All buffers associated with the stream are flushed before closing. System-allocated buffers are freed upon closing. Buffers assigned with setbuf or setvbuf are not automatically freed. (But if setvbuf is passed null for the buffer pointer it will free it upon close.)

Return Value

fclose returns 0 on success. It returns EOF if any errors were detected.


See Also

close

fcloseall

fdopen

fflush

flushall

fopen

freopen


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


fcloseall

See Also	Example	Portability

Syntax

#include <stdio.h>

int fcloseall(void);

Description

Closes open streams.

fcloseall closes all open streams except

stdin

stdout

stdprn

stderr

stdauxstdstreams

Note:	stdprn and stdaux streams are not available in OS/2 and Win32.

Return Value

fcloseall returns the total number of streams it closed. It returns EOF if any errors were detected.


See Also

fclose

fdopen

flushall

fopen

freopen


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


fcvt

See Also	Example	Portability

Syntax

#include <stdlib.h>

char *fcvt(double value, int ndig, int *dec, int *sign);

Description

Converts a floating-point number to a string.

fcvt converts value to a null-terminated string digit starting with the leftmost significant digit with ndig digits to the right of the decimal point. fcvt then returns a pointer to the string. The position of the decimal point relative to the beginning of the string is stored indirectly through dec (a negative value for dec means to the left of the returned digits). There is no decimal point in the string itself. If the sign of value is negative the word pointed to by sign is nonzero; otherwise it is 0.

The correct digit has been rounded for the number of digits to the right of the decimal point specified by ndig.

Return Value

The return value of fcvt points to static data whose content is overwritten by each call to fcvt and ecvt.


See Also

ecvt

gcvt

sprintf


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


fdopen

See Also	Example	Portability

Syntax

#include <stdio.h>

FILE *fdopen(int handle, char *type);

Description

Associates a stream with a file handle.

fdopen associates a stream with a file handle obtained from creat, dup, dup2, or open.

The type of stream must match the mode of the open handle.

The type string used in a call to fdopen is one of the following values:

Value	Description

r	Open for reading only.

w	Create for writing.

a	Append; open for writing at end-of-file or create for writing if the file does not exist.

r+	Open an existing file for update (reading and writing).

w+	Create a new file for update.

a+	Open for append; open (or create if the file does not exist) for update at the end of the file.

To specify that a given file is being opened or created in text mode, append t to the value of the type string (for example, rt or  w+t).

Similarly to specify binary mode append b to the type string (for example, rb or  w+b).

If t or b is not given in the type string, the mode is governed by the global variable _fmode.

If _fmode is set to O_BINARY, files will be opened in binary mode.

If _fmode is set to O_TEXT, files will be opened in text mode.

Note:	The O_... constants are defined in fcntl.h.

When a file is opened for update, both input and output can be done on the resulting stream; however,

output cannot be directly followed by input without an intervening fseekor rewind

input cannot be directly followed by output without an intervening fseek, rewind, or an input that encounters end-offile

Return Value

On successful completion fdopen returns a pointer to the newly opened stream. In the event of error it returns NULL.


See Also

fclose

fopen

freopen

_get_osfhandle

open


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


feof

See Also	Example	Portability

Syntax

#include <stdio.h>

int feof(FILE *stream);

Description

Detects end-of-file on a stream.

feof is a macro that tests the given stream for an end-of-file indicator. Once the indicator is set read operations on the file return the indicator until rewind is called or the file is closed. The end-of-file indicator is reset with each input operation.

Return Value

feof returns nonzero if an end-of-file indicator was detected on the last input operation on the named stream and 0 if end-of-file has not been reached.


See Also

clearerr

eof

ferror

perror


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


ferror

See Also	Example	Portability

Syntax

#include <stdio.h>

int ferror(FILE *stream);

Description

Detects errors on stream.

ferror is a macro that tests the given stream for a read or write error. If the stream's error indicator has been set it remains set until clearerr or rewind is called or until the stream is closed.

Return Value

ferror returns nonzero if an error was detected on the named stream.


See Also

clearerr

eof

feof

fopen

gets

perror


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


fflush

See Also	Example	Portability

Syntax

#include <stdio.h>

int fflush(FILE *stream);

Description

Flushes a stream.

If the given stream has buffered output fflush writes the output for stream to the associated file.

The stream remains open after fflush has executed. fflush has no effect on an unbuffered stream.

Return Value

fflush returns 0 on success. It returns EOF if any errors were detected.


See Also

fclose

flushall

setbuf

setvbuf


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


fgetc

See Also	Example	Portability

Syntax

#include <stdio.h>

int fgetc(FILE *stream);

Description

Gets character from stream.

fgetc returns the next character on the named input stream.

Return Value

On success fgetc returns the character read after converting it to an int without sign extension. On end-of-file or error it returns EOF.


See Also

fgetchar

fputc

getc

getch

getchar

getche

ungetc

ungetch


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


fgetchar

See Also	Example	Portability

Syntax

#include <stdio.h>

int fgetchar(void);

Description

Gets character from stdin.

fgetchar returns the next character from stdin. It is defined as fgetc(stdin).

Note:	For Win32s or Win32 GUI applications, stdin must be redirected.

Return Value

On success fgetchar returns the character read after converting it to an int without sign extension. On end-of-file or error it returns EOF.


See Also

fgetc

fputchar

freopen

getchar


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


fgetpos

See Also	Example	Portability

Syntax

#include <stdio.h>

int fgetpos(FILE *stream, fpos_t *pos);

Description

Gets the current file pointer.

fgetpos stores the position of the file pointer associated with the given stream in the location pointed to by pos. The exact value is unimportant; its value is opaque except as a parameter to subsequent fsetpos calls.

Return Value

On success fgetpos returns 0. On failure it returns a nonzero value and sets the global variable errno to

EBADF	Bad file number

EINVAL	Invalid number


See Also

fseek

fsetpos

ftell

tell


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	+	+	+


fgets

See Also	Example	Portability

Syntax

#include <stdio.h>

char *fgets(char *s, int n, FILE *stream);

Description

Gets a string from a stream.

fgets reads characters from stream into the string s. The function stops reading when it reads either n - 1 characters or a newline character whichever comes first. fgets retains the newline character at the end of s. A null byte is appended to s to mark the end of the string.

Return Value

On success fgets returns the string pointed to by s; it returns NULL on end-of-file or error.


See Also

cgets

fputs

gets


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


filelength

See Also	Example	Portability

Syntax

#include <io.h>

long filelength(int handle);

Description

Gets file size in bytes.

filelength returns the length (in bytes) of the file associated with handle.

Return Value

On success filelength returns a long value the file length in bytes. On error it returns -1 and the global variable errno is set to

EBADF	Bad file number


See Also

fopen

lseek

open


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


fileno

See Also	Example	Portability

Syntax

#include <stdio.h>

int fileno(FILE *stream);

Description

Gets file handle.

fileno is a macro that returns the file handle for the given stream. If stream has more than one handle fileno returns the handle assigned to the stream when it was first opened.

Return Value

fileno returns the integer file handle associated with stream.


See Also

fdopen

fopen

freopen

_get_osfhandle


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


findfirst

See Also	Example	Portability

Syntax

#include <dir.h>

int findfirst(const char *pathname, struct ffblk *ffblk, int attrib);

Description

Searches a disk directory.

findfirst begins a search of a disk directory for files specifed by attributes or wildcards.

pathname is a string with an optional drive specifier path and file name of the file to be found. Only the file name portion can contain wildcard match characters (such as ? or *). If a matching file is found the ffblk structure is filled with the file-directory information.

Win16

For Win16, the format of the structure ffblk is as follows:

struct ffblk {

   char ff_reserved[21];     /* reserved by DOS */

   char ff_attrib;           /* attribute found */

   int ff_ftime;             /* file time */

   int ff_fdate;             /* file date */

   long ff_fsize;            /* file size */

   char ff_name[13];         /* found file name */

   };

Win32

For Win32, the format of the structure ffblk is as follows:

struct ffblk {

   long           ff_reserved;

   long           ff_fsize;       /* file size */

   unsigned long  ff_attrib;      /* attribute found */

   unsigned short ff_ftime;       /* file time */

   unsigned short ff_fdate;       /* file date */

   char           ff_name[256];   /* found file name */

   };

attrib is a file-attribute byte used in selecting eligible files for the search. attrib should be selected from the following constants defined in dos.h:

FA_RDONLY	Read-only attribute

FA_HIDDEN	Hidden file

FA_SYSTEM	System file

FA_LABEL	Volume label

FA_DIREC	Directory

FA_ARCH 	Archive

A combination of constants can be ORed together.

For more detailed information about these attributes refer to your operating system documentation.

ff_ftime and ff_fdate contain bit fields for referring to the current date and time. The structure of these fields was established by the operating system. Both are 16-bit structures divided into three fields.

ff_ftime:

Bits 0 to 4	The result of seconds divided by 2 (for example 10 here means 20 seconds)

Bits 5 to 10	Minutes

Bits 11 to 15	Hours

ff_fdate:

Bits 0-4	Day

Bits 5-8	Month

Bits 9-15	Years since 1980 (for example 9 here means 1989)

The structure ftime declared in io.h uses time and date bit fields similar in structure to ff_ftime and ff_fdate.

Return Value

findfirst returns 0 on successfully finding a file matching the search pathname.

When no more files can be found, or if there is an error in the file name:

-1 is returned

errno is set to

ENOENT	Path or file name not found

_doserrno is set to one of the following values:

ENMFILE	No more files

ENOENT	Path or file name not found


See Also

findnext

getftime

setftime


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


findnext

See Also	Example	Portability

Syntax

#include <dir.h>

int findnext(struct ffblk *ffblk);

Description

Continues findfirst search.

findnext is used to fetch subsequent files that match the pathname given in findfirst. ffblk is the same block filled in by the findfirst call. This block contains necessary information for continuing the search. One file name for each call to findnext will be returned until no more files are found in the directory matching the pathname.

Return Value

findnext returns 0 on successfully finding a file matching the search pathname. When no more files can be found or if there is an error in the file name

-1 is returned

errno is set to

ENOENT	Path or file name not found

_doserrno is set to one of the following values:

ENMFILE	No more files

ENOENT	Path or file name not found


See Also

findfirst


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


floor, floorl

See Also	Example	Portability

Syntax

#include <math.h>

double floor(double x);

long double floorl(long double x);

Description

Rounds down.

floor finds the largest integer not greater than x.

floorl is the long double version; it takes a long double argument and returns a long double result.

Return Value

floor returns the integer found as a double. floorl returns the integer found as a long double.


See Also

ceil

fmod


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
floor	+	+	+	+	+	+	+
floorl	+		+	+			+


flushall

See Also	Example	Portability

Syntax

#include <stdio.h>

int flushall(void);

Description

Flushes all streams.

flushall clears all buffers associated with open input streams and writes all buffers associated with open output streams to their respective files. Any read operation following flushall reads new data into the buffers from the input files. Streams stay open after flushall executes.

Return Value

flushall returns an integer the number of open input and output streams.


See Also

fclose

fcloseall

fflush


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


fmod, fmodl

See Also	Example	Portability

Syntax

#include <math.h>

double fmod(double x, double y);

long double fmodl(long double x, long double y);

Description

Calculates x modulo y, the remainder of x/y.

fmod calculates x modulo y (the remainder f, where x = ay + f for some integer a, and 0 < f < y).

fmodl is the long double version; it takes long double arguments and returns a long double result.

Return Value

fmod and fmodl return the remainder f where x = ay + f (as described above). When y = 0, fmod and fmodl return 0.


See Also

ceil

floor

modf


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
fmod	+	+	+	+	+	+	+
fmodl	+		+	+			+


fnmerge

See Also	Example	Portability

Syntax

#include <dir.h>

void fnmerge(char *path, const char *drive, const char *dir, const char *name, const char *ext);

Description

Builds a path from component parts.

fnmerge makes a path name from its components. The new path name is

X:\DIR\SUBDIR\NAME.EXT

where:

drive	=	X

dir	=	\DIR\SUBDIR\

name	=	NAME

ext	=	.EXT

fnmerge assumes there is enough space in path for the constructed path name. The maximum constructed length is MAXPATH. MAXPATH is defined in dir.h.

fnmerge and fnsplit are invertible; if you split a given path with fnsplit then merge the resultant components with fnmerge you end up with path.

Return Value

None.


See Also

fnsplit


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


fnsplit

See Also	Example	Portability

Syntax

#include <dir.h>

int fnsplit(const char *path, char *drive, char *dir, char *name, char *ext);

Description

Splits a full path name into its components.

fnsplit takes a file's full path name (path) as a string in the form   X:\DIR\SUBDIR\NAME.EXT and splits path into its four components. It then stores those components in the strings pointed to by drive, dir, name,  and ext. All five components must be passed but any of them can be a null which means the corresponding component will be parsed but not stored. If any path component is null, that component corresponds to a non-NULL, empty string.

The maximum sizes for these strings are given by the constants MAXDRIVE, MAXDIR, MAXPATH, MAXFILE, and MAXEXT (defined in dir.h) and each size includes space for the null-terminator.

Constant	Max 16-bit	Max 32-bit	String

MAXPATH 	80	260	path

MAXDRIVE	3	3	drive; includes colon (:)

MAXDIR	66	260	dir; includes leading and trailing backslashes (\)

MAXFILE	9	260	name

MAXEXT	5	260	ext; includes leading dot (.)

fnsplit assumes that there is enough space to store each non-null component.

When fnsplit splits path it treats the punctuation as follows:

drive includes the colon (C:, A:, and so on)

dir includes the leading and trailing backslashes (\BC\include\, \source\ ,and so on)

name includes the file name

ext includes the dot preceding the extension (.C, .EXE, and so on).

fnmerge and fnsplit are invertible; if you split a given path with fnsplit then merge the resultant components with fnmerge you end up with path.

Return Value

fnsplit returns an integer (composed of five flags defined in dir.h) indicating which of the full path name components were present in path. These flags and the components they represent are

EXTENSION	An extension

FILENAME	A file name

DIRECTORY	A directory (and possibly subdirectories)

DRIVE	A drive specification (see dir.h)

WILDCARDS	Wildcards (* or ?)


See Also

fnmerge


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


fopen

See Also	Example	Portability

Syntax

#include <stdio.h>

FILE *fopen(const char *filename, const char *mode);

Description

Opens a stream.

fopen opens the file named by filename and associates a stream with it. fopen returns a pointer to be used to identify the stream in subsequent operations.

The mode string used in calls to fopen is one of the following values:

Value	Description

r	Open for reading only.

w	Create for writing. If a file by that name already exists, it will be overwritten.

a	Append; open for writing at end-of-file or create for writing if the file does not exist.

r+	Open an existing file for update (reading and writing).

w+	Create a new file for update (reading and writing). If a file by that name already exists, it will be overwritten.

a+	Open for append; open (or create if the file does not exist) for update at the end of the file.

To specify that a given file is being opened or created in text mode append a t to the mode string (rt w+t and so on). Similarly to specify binary mode append a b to the mode string (wb a+b and so on). fopen also allows the t or b to be inserted between the letter and the + character in the mode string; for example rt+ is equivalent to r+t.

If a t or b is not given in the mode string the mode is governed by the global variable _fmode. If _fmode is set to O_BINARY files are opened in binary mode. If _fmode is set to O_TEXT they are opened in text mode. These O_... constants are defined in fcntl.h.

When a file is opened for update, both input and output can be done on the resulting stream; however,

output cannot be directly followed by input without an intervening fseek or rewind

input cannot be directly followed by output without an intervening fseek, rewind, or an input that encounters end-offile

Return Value

On successful completion fopen returns a pointer to the newly opened stream. In the event of error it returns NULL.


See Also

creat

dup

fclose

fdopen

ferror

_fmode (global variable)

fread

freopen

fseek

fwrite

open

rewind

setbuf

setmode


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


FP_OFF, FP_SEG

See Also	Example	Portability

Syntax

#include <dos.h>

unsigned FP_OFF(void far *p);

unsigned FP_SEG(void far *p);

Description

Gets a far address offset or segment.

FP_OFF is a macro that gets or sets the offset of the far pointer p.

FP_SEG is a macro that gets or sets the segment value of the far pointer p.

Return Value

FP_OFF returns an unsigned integer value representing an offset value.

FP_SEG returns an unsigned integer representing a segment value.


See Also

MK_FP

movedata

segread


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


_fpreset

See Also	Portability

Syntax

#include <float.h>

void _fpreset(void);

Description

Reinitializes floating-point math package.

_fpreset reinitializes the floating-point math package. This function is usually used in conjunction with system or the exec... or spawn... functions. It is also used to recover from floating-point errors before calling longjmp.

Note:	If an 80x87 coprocessor is used in a program a child process (executed by the system, or by an exec... or spawn... function) might alter the parent process' floating-point state.

If you use an 80x87 take the following precautions:

Do not call system or an exec... or spawn... function while a floating-point expression is being evaluated.

Call _fpreset to reset the floating-point state after using system exec... or spawn... if there is any chance that the child process performed a floating-point operation with the 80x87.

Return Value

None.


See Also

_clear87

_control87

_status87


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


fprintf

See Also	Example	Portability

Syntax

#include <stdio.h>

int fprintf(FILE *stream, const char *format[, argument, ...]);

Description

Writes formatted output to a stream.

fprintf accepts a series of arguments applies to each a format specifier contained in the format string pointed to by format and outputs the formatted data to a stream. There must be the same number of format specifiers as arguments.

Note:	For details on format specifiers, see printf Format Specifiers.

Return Value

fprintf returns the number of bytes output. In the event of error it returns EOF.


See Also

cprintf

fscanf

printf

putc

sprintf


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


fputc

See Also	Example	Portability

Syntax

#include <stdio.h>

int fputc(int c, FILE *stream);

Description

Puts a character on a stream.

fputc outputs character c to the named stream.

Note:	For Win32s or Win32 GUI applications, stdin must be redirected.

Return Value

On success, fputc returns the character c. On error, it returns EOF.


See Also

fgetc

putc


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


fputchar

See Also	Example	Portability

Syntax

#include <stdio.h>

int fputchar(int c);

Description

Outputs a character on stdout.

fputchar outputs character c to stdout. fputchar(c) is the same as fputc(cstdout).

For Win32s or Win32 GUI applications, stdout must be redirected.

Return Value

On success fputchar returns the character c.

On error it returns EOF.


See Also

fgetchar

freopen

putchar


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	 	+	+	 	+


fputs

See Also	Example	Portability

Syntax

#include <stdio.h>

int fputs(const char *s, FILE *stream);

Description

Outputs a string on a stream.

fputs copies the null-terminated string s to the given output stream; it does not append a newline character and the terminating null character is not copied.

Return Value

On success fputs returns a non-negative value.

On error it returns a value of EOF.


See Also

fgets

gets

puts


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


fread

See Also	Example	Portability

Syntax

#include <stdio.h>

size_t fread(void *ptr, size_t size, size_t n, FILE *stream);

Description

Reads data from a stream.

fread reads n items of data each of length size bytes from the given input stream into a block pointed to by ptr.

The total number of bytes read is (n * size).

Return Value

On success fread returns the number of items (not bytes) actually read.

On end-of-file or error it returns a short count (possibly 0).


See Also

fopen

fwrite

printf

read


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


free

See Also	Example	Portability

Syntax

#include <stdlib.h>

void free(void *block);

Description

Frees allocated block.

free deallocates a memory block allocated by a previous call to calloc, malloc, or realloc.

Return Value

None.


See Also

calloc

malloc

realloc

strdup


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


freopen

See Also	Example	Portability

Syntax

#include <stdio.h>

FILE *freopen(const char *filename, const char *mode, FILE *stream);

Description

Associates a new file with an open stream.

freopen substitutes the named file in place of the open stream. It closes stream regardless of whether the open succeeds. freopen is useful for changing the file attached to stdin, stdout, or stderr.

The mode string used in calls to fopen is one of the following values:

Value	Description

r	Open for reading only.

w	Create for writing. .

a	Append; open for writing at end-of-file or create for writing if the file does not exist.

r+	Open an existing file for update (reading and writing).

w+	Create a new file for update (reading and writing).

a+	Open for append; open (or create if the file does not exist) for update at the end of the file.

To specify that a given file is being opened or created in text mode append a t to the mode string (rt w+t and so on); similarly to specify binary mode append a b to the mode string (wb a+b and so on).

If a t or b is not given in the mode string the mode is governed by the global variable _fmode. If _fmode is set to O_BINARY files are opened in binary mode. If _fmode is set to O_TEXT they are opened in text mode. These O_... constants are defined in fcntl.h.

When a file is opened for update, both input and output can be done on the resulting stream; however,

output cannot be directly followed by input without an intervening fseekor rewind

input cannot be directly followed by output without an intervening fseek, rewind, or an input that encounters end-offile

Return Value

On successful completion freopen returns the argument stream.

On error it returns NULL.


See Also

fclose

fdopen

fopen

open

setmode


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


frexp, frexpl

See Also	Example	Portability

Syntax

#include <math.h>

double frexp(double x, int *exponent);

long double frexpl(long double x, int *exponent);

Description

Splits a number into mantissa and exponent.

frexp calculates the mantissa m (a double greater than or equal to 0.5 and less than 1) and the integer value n such that x (the original double value) equals m * 2n. frexp stores n in the integer that exponent points to.

frexpl is the long double version; it takes a long double argument for x and returns a long double result.

Return Value

frexp and frexpl return the mantissa m. Error handling for these routines can be modified through the functions _matherr and _matherrl.


See Also

exp

ldexp

_matherr


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
frexp	+	+	+	+	+	+	+
frexpl	+		+	+			+


fscanf

See Also	Example	Portability

Syntax

#include <stdio.h>

int fscanf(FILE *stream, const char *format[, address, ...]);

Description

Scans and formats input from a stream.

fscanf scans a series of input fields one character at a time reading from a stream. Then each field is formatted according to a format specifier passed to fscanf in the format string pointed to by format. Finally fscanf stores the formatted input at an address passed to it as an argument following format. The number of format specifiers and addresses must be the same as the number of input fields.

Note:	For details on format specifiers, see scanf Format Specifiers.

fscanf can stop scanning a particular field before it reaches the normal end-of-field character (whitespace) or it can terminate entirely for a number of reasons. See scanf for a discussion of possible causes.

Return Value

fscanf returns the number of input fields successfully scanned, converted and stored. The return value does not include scanned fields that were not stored.

If fscanf attempts to read at end-of-file, the return value is EOF. If no fields were stored, the return value is 0.


See Also

atof

cscanf

fprintf

printf

scanf

sscanf

vfscanf

vscanf

vsscanf


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


fseek

See Also	Example	Portability

Syntax

#include <stdio.h>

int fseek(FILE *stream, long offset, int whence);

Description

Repositions a file pointer on a stream.

fseek sets the file pointer associated with stream to a new position that is offset bytes from the file location given by whence. For text mode streams offset should be 0 or a value returned by ftell.

whence must be one of the values 0. 1, or 2 which represent three symbolic constants (defined in stdio.h) as follows:

Constant	whence	File location

SEEK_SET	0	File beginning

SEEK_CUR	1	Current file pointer position

SEEK_END	2	End-of-file

fseek discards any character pushed back using ungetc. fseek is used with stream I/O; for file handle I/O use lseek.

After fseek the next operation on an update file can be either input or output.

Return Value

fseek returns 0 if the pointer is successfully moved and nonzero on failure.

fseek might return a 0 indicating that the pointer has been moved successfully when in fact it has not been. This is because DOS, which actually resets the pointer, does not verify the setting. fseek returns an error code only on an unopened file or device.

In the event of an error return the global variable errno is set to one of the following values:

EBADF	Bad file pointer

EINVAL	Invalid argument

ESPIPE	Illegal seek on device


See Also

fgetpos

fopen

fsetpos

ftell

lseek

rewind

setbuf

tell


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


fsetpos

See Also	Example	Portability

Syntax

#include <stdio.h>

int fsetpos(FILE *stream, const fpos_t *pos);

Description

Positions the file pointer of a stream.

fsetpos sets the file pointer associated with stream to a new position. The new position is the value obtained by a previous call to fgetpos on that stream. It also clears the end-of-file indicator on the file that stream points to and undoes any effects of ungetc on that file. After a call to fsetpos the next operation on the file can be input or output.

Return Value

On success fsetpos returns 0.

On failure it returns a nonzero value and also sets the global variable errno to a nonzero value.


See Also

fgetpos

fseek

ftell


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	+	+	+


_fsopen

See Also	Example	Portability

Syntax

#include <stdio.h>

#include <share.h>

FILE *_fsopen(const char *filename, const char *mode, int shflag);

Description

Opens a stream with file sharing.

_fsopen opens the file named by filename and associates a stream with it. _fsopen returns a pointer that is used to identify the stream in subsequent operations.

The mode string used in calls to _fsopen is one of the following values:

Mode	Description

r	Open for reading only.

w	Create for writing. If a file by that name already exists, it will be overwritten.

a	Append; open for writing at end of file. or create for writing if the file does not exist.

r+	Open an existing file for update (reading and writing).

w+	Create a new file for update (reading and writing). If a file by that name already exists, it will be overwritten.

a+	Open for append; open (or create if the file does not exist) for update at the end of the file.

To specify that a given file is being opened or created in text mode append a t to the mode string (rt w+t and so on). Similarly to specify binary mode append a b to the mode string (wb a+b and so on). _fsopen also allows the t or b to be inserted between the letter and the + character in the mode string; for example rt+ is equivalent to r+t. If a t or b is not given in the mode string the mode is governed by the global variable _fmode. If _fmode is set to O_BINARY files are opened in binary mode. If _fmode is set to O_TEXT they are opened in text mode. These O_... constants are defined in fcntl.h.

When a file is opened for update, both input and output can be done on the resulting stream, however:

output cannot be directly followed by input without an intervening fseekor rewind

input cannot be directly followed by output without an intervening fseek, rewind, or an input that encounters end-offile

shflag specifies the type of file-sharing allowed on the file filename. Symbolic constants for shflag are defined in share.h.

Note:	For DOS users, the file-sharing flags are ignored if SHARE is not loaded.

Value of shflag	Description

SH_COMPAT	Sets compatibility mode

SH_DENYRW	Denies read/write access

SH_DENYWR	Denies write access

SH_DENYRD	Denies read access

SH_DENYNONE	Permits read/write access

SH_DENYNO	Permits read/write access

Return Value

On successful completion _fsopen returns a pointer to the newly opened stream.

On error it returns NULL.


See Also

creat

_dos_open

dup

fclose

fdopen

ferror

_fmode (global variable)

fopen

fread

freopen

fseek

fwrite

open

rewind

setbuf

setmode

sopen


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


fstat, stat

See Also	Examples	Portability

Syntax

#include <sys\stat.h>

int fstat(int handle, struct stat *statbuf);

int stat(const char *path, struct stat *statbuf);

Description

Gets open file information.

fstat stores information in the stat structure about the file or directory associated with handle.

stat stores information about a given file or directory in the stat structure. The name of the file is path.

statbuf points to the stat structure (defined in sys\stat.h). That structure contains the following fields:

st_mode	Bit mask giving information about the file's mode

st_dev	Drive number of disk containing the file or file handle if the file is on a device

st_rdev	Same as st_dev

st_nlink	Set to the integer constant 1

st_size	Size of the file in bytes

st_atime	Most recent access (Windows) or last time modified (DOS)

st_mtime	Same as st_atime

st_ctime	Same as st_atime

The stat structure contains three more fields not mentioned here. They contain values that are meaningful only in UNIX.

The st_mode bit mask that gives information about the mode of the open file includes the following bits:

One of the following bits will be set:

S_IFCHR	If handle refers to a device.

S_IFREG 	If an ordinary file is referred to by handle.

One or both of the following bits will be set:

S_IWRITE	If user has permission to write to file.

S_IREAD	If user has permission to read to file.

The HPFS and NTFS file-management systems make the following distinctions:

st_atime	Most recent access

st_mtime	Most recent modify

st_ctime	Creation time

Return Value

fstat and stat return 0 if they successfully retrieved the information about the open file.

On error (failure to get the information) these functions return -1 and set the global variable errno to

EBADF	Bad file handle


See Also

access

chmod


Examples

fstat

stat


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


_fstr*

See Also	Portability

Syntax

#include <string.h>

__far string functions

Description

Provides string operations in a large-code model.

Choose See Also to see a list of string functions that have a __far version. The __far version of a string function is prefixed with _fstr. The behavior of a __far string function is identical to the behavior of the standard function to which it corresponds. The only difference is that arguments and return value (if any) to a __far string function are modified by the __far keyword. The entry for each of the functions provides a description for the __far version.

Return Value

The return value for a _fstr-type function is a __far type.

Note:	When a far string function returns an int or size_t, the return value is never modified by the far keyword.


See Also

strcat

strchr

strcmp

strcpy

strcspn

strdup

stricmp

strlen

strlwr

strncat

strncmp

strncpy

strnicmp

strnset

strpbrk

strrchr

strrev

strset

strspn

strstr

strtok

strupr


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


ftell

See Also	Example	Portability

Syntax

#include <stdio.h>

long int ftell(FILE *stream);

Description

Returns the current file pointer.

ftell returns the current file pointer for stream. The offset is measured in bytes from the beginning of the file (if the file is binary). The value returned by ftell can be used in a subsequent call to fseek.

Return Value

ftell returns the current file pointer position on success. It returns -1L on error and sets the global variable errno to a positive value.

In the event of an error return the global variable errno is set to one of the following values:

EBADF	Bad file pointer

ESPIPE	Illegal seek on device


See Also

fgetpos

fseek

fsetpos

lseek

rewind

tell


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+  	+	+


ftime

See Also	Example	Portability

Syntax

#include <sys\timeb.h>

void ftime(struct timeb *buf)

Description

Stores current time in timeb structure.

On UNIX platforms ftime is available only on System V systems.

ftime determines the current time and fills in the fields in the timeb structure pointed to by buf. The timeb structure contains four fields: time, millitm, _timezone, and dstflag:

struct timeb {

   long time ;

   short millitm ;

   short _timezone ;

   short dstflag ;

};

time	provides the time in seconds since 00:00:00 Greenwich mean time (GMT) January 1 1970.

millitm	is the fractional part of a second in milliseconds.

_timezone	is the difference in minutes between GMT and the local time. This value is computed going west from GMT. ftime gets this field from the global variable _timezone which is set by tzset.

dstflag	is used to indicate whether daylight saving time will be taken into account during time calculations.

Note:	ftime calls tzset. Therefore it isn't necessary to call tzset explicitly when you use ftime.

Return Value

None.


See Also

asctime

ctime

gmtime

localtime

stime

time

tzset


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


_fullpath

See Also	Example	Portability

Syntax

#include <stdlib.h>

char * _fullpath(char *buffer, const char *path, int buflen);

Description

Converts a path name from relative to absolute.

_fullpath converts the relative path name in path to an absolute path name that is stored in the array of characters pointed to by buffer. The maximum number of characters that can be stored at buffer is buflen. The function returns NULL if the buffer isn't big enough to store the absolute path name or if the path contains an invalid drive letter.

If buffer is NULL, _fullpath allocates a buffer of up to _MAX_PATH characters. This buffer should be freed using free when it is no longer needed. _MAX_PATH is defined in stdlib.h.

Return Value

If successful the _fullpath function returns a pointer to the buffer containing the absolute path name.

On error, it returns NULL.


See Also

_makepath

_splitpath


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


fwrite

See Also	Example	Portability

Syntax

#include <stdio.h>

size_t fwrite(const void *ptr, size_t size, size_t n, FILE *stream);

Description

Writes to a stream.

fwrite appends n items of data each of length size bytes to the given output file. The data written begins at ptr. The total number of bytes written is (n x size). ptr in the declarations is a pointer to any object.

Return Value

On successful completion fwrite returns the number of items (not bytes) actually written.

On error it returns a short count.


See Also

fopen

fread


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+  	+	+


gcvt

See Also	Example	Portability

Syntax

#include <stdlib.h>

char *gcvt(double value, int ndec, char *buf);

Description

Converts floating-point number to a string.

gcvt converts value to a null-terminated ASCII string and stores the string in buf. It produces ndec significant digits in FORTRAN F format, if possible; otherwise, it returns the value in the printf E format (ready for printing). It might suppress trailing zeros.

Return Value

gcvt returns the address of the string pointed to by buf.


See Also

ecvt

fcvt

sprintf


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


geninterrupt

See Also	Example	Portability

Syntax

#include <dos.h>

void geninterrupt(int intr_num);

Description

Generates a software interrupt.

The geninterrupt macro triggers a software trap for the interrupt given by intr_num. The state of all registers after the call depends on the interrupt called.

Interrupts can leave registers in unpredictable states.

Return Value

None.


See Also

bdos

bdosptr

disable

enable

getvect

int86

int86x

intdos

intdosx

intr


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+


getc

See Also	Example	Portability

Syntax

#include <stdio.h>

int getc(FILE *stream);

Description

Gets character from stream.

getc returns the next character on the given input stream and increments the stream's file pointer to point to the next character.

Note:	For Win32s or Win32 GUI applications, stdin must be redirected.

Return Value

On success, getc returns the character read, after converting it to an int without sign extension.

On end-of-file or error, it returns EOF.


See Also

fgetc

getch

getchar

getche

gets

putc

putchar

ungetc


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


getcbrk

See Also	Example	Portability

Syntax

#include <dos.h>

int getcbrk(void);

Description

Gets control-break setting.

getcbrk uses the DOS system call 0x33 to return the current setting of control-break checking.

Return Value

getcbrk returns 0 if control-break checking is off, or 1 if checking is on.


See Also

ctrlbrk

setcbrk


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


getch

See Also	Example	Portability

Syntax

#include <conio.h>

int getch(void);

Description

Gets character from keyboard, does not echo to screen.

getch reads a single character directly from the keyboard, without echoing to the screen.

Note:	Do not use this function for Win32s or Win32 GUI applications.

Return Value

getch returns the character read from the keyboard.


See Also

cgets

cscanf

fgetc

getc

getchar

getche

getpass

kbhit

putch

ungetch


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+ 	 	 	+


getchar

See Also	Example	Portability

Syntax

#include <stdio.h>

int getchar(void);

Description

Gets character from stdin.

getchar is a macro that returns the next character on the named input stream stdin. It is defined to be getc(stdin).

Note:	Do not use this function for Win32s or Win32 GUI applications.

Return Value

On success, getchar returns the character read, after converting it to an int without sign extension.

On end-of-file or error, it returns EOF.


See Also

fgetc

fgetchar

freopen

getc

getch

getche

gets

putc

putchar

scanf

ungetc


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+ 	 	+	+	+	+


getche

See Also	Example	Portability

Syntax

#include <conio.h>

int getche(void);

Description

Gets character from the keyboard, echoes to screen.

getche reads a single character from the keyboard and echoes it to the current text window using direct video or BIOS.

Note:	Do not use this function for Win32s or Win32 GUI applications.

Return Value

getche returns the character read from the keyboard.


See Also

cgets

cscanf

fgetc

getc

getch

getchar

kbhit

putch

ungetch


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+	 	 	+


getcurdir

See Also	Example	Portability

Syntax

#include <dir.h>

int getcurdir(int drive, char *directory);

Description

Gets current directory for specified drive.

getcurdir gets the name of the current working directory for the drive indicated by drive. drive specifies a drive number (0 for default, 1 for A, and so on). directory points to an area of memory of length MAXDIR where the null-terminated directory name will be placed. The name does not contain the drive specification and does not begin with a backslash.

Return Value

getcurdir returns 0 on success or -1 in the event of error.


See Also

chdir

getcwd

getdisk

mkdir

rmdir


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


getcwd

See Also	Example	Portability

Syntax

#include <dir.h>

char *getcwd(char *buf, int buflen);

Description

Gets current working directory.

getcwd gets the full path name (including the drive) of the current working directory, up to buflen bytes long and stores it in buf. If the full path name length (including the null terminator) is longer than buflen bytes, an error occurs.

If buf is NULL, a buffer buflen bytes long is allocated for you with malloc. You can later free the allocated buffer by passing the return value of getcwd to the function free.

Return Value

getcwd returns the following values:

If buf is not NULL on input, getcwd returns buf on success, NULL on error.

If buf is NULL on input, getcwd returns a pointer to the allocated buffer.

In the event of an error return, the global variable errno is set to one of the following values:

ENODEV	No such device

ENOMEM	Not enough memory to allocate a buffer (buf is NULL)

ERANGE 	Directory name longer than buflen (buf is not NULL)


See Also

chdir

getcurdir

_getdcwd

getdisk

mkdir

rmdir


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


_getdcwd

See Also	Example	Portability

Syntax

#include <direct.h>

char * _getdcwd(int drive, char *buffer, int buflen);

Description

Gets current directory for specified drive.

_getdcwd gets the full path name of the working directory of the specified drive (including the drive name), up to buflen bytes long, and stores it in buffer. If the full path name length (including the null-terminator) is longer than buflen, an error occurs. The drive is 0 for the default drive, 1=A, 2=B, and so on.

If buffer is NULL, _getdcwd allocates a buffer at least buflen bytes long. You can later free the allocated buffer by passing the _getdcwd return value to the free function.

Return Value

If successful, _getdcwd returns a pointer to the buffer containing the current directory for the specified drive.

Otherwise it returns NULL, and sets the global variable errno to one of the following values:

ENOMEM	Not enough memory to allocate a buffer (buffer is NULL)

ERANGE	Directory name longer than buflen (buffer is not NULL)


See Also

chdir

getcwd

mkdir

rmdir


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


getdfree

See Also	Example	Portability

Syntax

#include <dos.h>

void getdfree(unsigned char drive, struct dfree *dtable);

Description

Gets disk free space.

getdfree accepts a drive specifier in drive (0 for default, 1 for A, and so on) and fills the dfree structure pointed to by dtable with disk attributes.

The dfree structure is defined as follows:

struct dfree {

   unsigned df_avail;     /* available clusters */

   unsigned df_total;     /* total clusters */

   unsigned df_bsec;      /* bytes per sector */

   unsigned df_sclus;     /* sectors per cluster */

};

Return Value

getdfree returns no value. In the event of an error, df_sclus in the dfree structure is set to (unsigned) -1.


See Also

getfat

getfatd


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


getdisk, setdisk

See Also	Examples	Portability

Syntax

#include <dir.h>

int getdisk(void);

int setdisk(int drive);

Description

Gets or sets the current drive number.

getdisk gets the current drive number. It returns an integer: 0 for A, 1 for B, 2 for C, and so on.

setdisk sets the current drive to the one associated with drive: 0 for A, 1 for B, 2 for C, and so on.

The setdisk function changes the current drive of the parent process.

Return Value

getdisk returns the current drive number. setdisk returns the total number of drives available.


See Also

getcurdir

getcwd


Examples

getdisk

setdisk


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


getdta

See Also	Example	Portability

Syntax

#include <dos.h>

char far *getdta(void);

Description

Gets disk transfer address.

getdta returns the current setting of the disk transfer address (DTA).

In the small and medium memory models, the current data segment is the assumed segment. If you use C or C++ exclusively, this will be the case, but assembly routines can set the DTA to any hardware address.

In the compact or large models, the address returned by getdta is the correct hardware address and can be located outside the program.

Return Value

getdta returns a far pointer to the current DTA.


See Also

fcb (structure)

setdta


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


getenv

See Also	Example	Portability

Syntax

#include <stdlib.h>

char *getenv(const char *name);

Description

Gets a string from environment.

getenv returns the value of a specified variable. On DOS and OS/2, name must be uppercase. On other systems, name can be either uppercase or lowercase. name must not include the equal sign (=). If the specified environment variable does not exist, getenv returns a NULL pointer.

To delete the variable from the environment, use getenv("name=").

Note:	Environment entries must not be changed directly. If you want to change an environment value, you must use putenv.

Return Value

On success, getenv returns the value associated with name.

If the specified name is not defined in the environment, getenv returns a NULL pointer.


See Also

_environ (global variable)

getpsp

putenv


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


getfat

See Also	Example	Portability

Syntax

#include <dos.h>

void getfat(unsigned char drive, struct fatinfo *dtable);

Description

Gets file allocation table information for given drive.

getfat gets information from the file allocation table (FAT) for the drive specified by drive (0 for default, 1 for A, 2 for B, and so on). dtable points to the fatinfo structure to be filled in. The fatinfo structure filled in by getfat is defined as follows:

struct fatinfo {

   char fi_sclus;          /* sectors per cluster */

   char fi_fatid;          /* the FAT id byte */

   unsigned fi_nclus;      /* number of clusters */

   int fi_bysec;           /* bytes per sector */

};

Return Value

None.


See Also

getdfree

getfatd


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


getfatd

See Also	Example	Portability

Syntax

#include <dos.h>

void getfatd(struct fatinfo *dtable);

Description

Gets file allocation table information.

getfatd gets information from the file allocation table (FAT) of the default drive. dtable points to the fatinfo structure to be filled in.

The fatinfo structure filled in by getfatd is defined as follows:

struct fatinfo {

   char fi_sclus;     /* sectors per cluster */

   char fi_fatid;     /* the FAT id byte */

   int fi_nclus;      /* number of clusters */

   int fi_bysec;      /* bytes per sector */

};

Return Value

None.


See Also

getdfree

getfat


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


getftime, setftime

See Also	Examples	Portability

Syntax

#include <io.h>

int getftime(int handle, struct ftime *ftimep);

int setftime(int handle, struct ftime *ftimep);

Description

Gets and sets the file date and time.

getftime retrieves the file time and date for the disk file associated with the open handle. The ftime structure pointed to by ftimep is filled in with the file's time and date.

setftime sets the file date and time of the disk file associated with the open handle to the date and time in the ftime structure pointed to by ftimep. The file must not be written to after the setftime call or the changed information will be lost. The file must be open for writing; an EACCES error will occur if the file is open for read-only access.

setftime requires the file to be open for writing; an EACCES error will occur if the file is open for read-only access.

The ftime structure is defined as follows:

struct ftime {

   unsigned ft_tsec: 5;      /* two seconds */

   unsigned ft_min: 6;       /* minutes */

   unsigned ft_hour: 5;      /* hours */

   unsigned ft_day: 5;       /* days */

   unsigned ft_month: 4;     /* months */

   unsigned ft_year: 7;      /* year - 1980*/

   };

Return Value

getftime and setftime return 0 on success.

In the event of an error return -1 is returned and the global variable errno is set to one of the following values:

EACCES	Permission denied

EBADF	Bad file number

EINVFNC 	Invalid function number


See Also

fflush

open

setftime


Examples

getftime

setftime


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


_get_osfhandle

See Also	Example	Portability

Syntax

#include <io.h>

long _get_osfhandle(int filehandle);

Description

Associates file handles.

The _get_osfhandle function associates an operating system file handle with an existing run-time file handle. The variable filehandle is the file handle of your program.

Return value

On success, _get_osfhandle returns an operating system file handle corresponding to the variable  filehandle.

On error, it returns -1 and sets the global variable errno to

EBADF	an invalid file handle


See Also

fdopen

fileno

_open_osfhandle


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

 	 	 	+


getpass

See Also	Example	Portability

Syntax

#include <conio.h>

char *getpass(const char *prompt);

Description

Reads a password.

getpass reads a password from the system console after prompting with the null-terminated string prompt and disabling the echo. A pointer is returned to a null-terminated string of up to eight characters (not counting the null-terminator).

Note:	Do not use this function for Win32s or Win32 GUI applications.

Return Value

The return value is a pointer to a static string which is overwritten with each call.


See Also

getch


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 +	 	+	 	 	+


getpid

See Also	Example	Portability

Syntax

#include <process.h>

unsigned getpid(void)

Description

Gets the process ID of a program.

This function returns the current process ID--an integer that uniquely identifies the process.

Return Value

getpid returns the current process' ID.


See Also

getpsp


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


getpsp

See Also	Example	Portability

Syntax

#include <dos.h>

unsigned getpsp(void);

Description

Gets the program segment prefix.

getpsp gets the segment address of the program segment prefix (PSP) using DOS call 0x62.

Return Value

getpsp returns the address of the Program Segment Prefix (PSP).


See Also

getenv

_psp (global variable)


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


gets

See Also	Example	Portability

Syntax

#include <stdio.h>

char *gets(char *s);

Description

Gets a string from stdin.

gets collects a string of characters terminated by a new line from the standard input stream stdin and puts it into s. The new line is replaced by a null character (\0) in s.

gets allows input strings to contain certain whitespace characters (spaces, tabs). gets returns when it encounters a new line; everything up to the new line is copied into s.

Note:	For Win32s or Win32 GUI applications, stdin must be redirected.

Return Value

On success, gets returns the string argument s.

On end-of-file or error, it returns NULL


See Also

cgets

ferror

fgets

fopen

fputs

fread

freopen

getc

puts

scanf


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	 	+	+	+	+


gettext

See Also	Example	Portability

Syntax

#include <conio.h>

int gettext(int left, int top, int right, int bottom, void *destin);

Description

Copies text from text mode screen to memory.

gettext stores the contents of an onscreen text rectangle defined by left, top, right, and bottom into the area of memory pointed to by destin.

All coordinates are absolute screen coordinates not window-relative. The upper left corner is (1,1). gettext reads the contents of the rectangle into memory sequentially from left to right and top to bottom.

Each position onscreen takes 2 bytes of memory: The first byte is the character in the cell and the second is the cell's video attribute. The space required for a rectangle w columns wide by h rows high is defined as

bytes = (h rows) x (w columns) x 2

Note:	Do not use this function for Win32s or Win32 GUI applications.

Return Value

gettext returns 1 if the operation succeeds.

On error, it returns 0 (for example, if it fails because you gave coordinates outside the range of the current screen mode).


See Also

movetext

puttext


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+	 	 	+


gettextinfo

See Also	Example	Portability

Syntax

#include <conio.h>

void gettextinfo(struct text_info *r);

Description

Gets text mode video information.

gettextinfo fills in the text_info structure pointed to by r with the current text video information.

The text_info structure is defined in conio.h as follows:

struct text_info {

   unsigned char winleft;        /* left window coordinate */

   unsigned char wintop;         /* top window coordinate */

   unsigned char winright;       /* right window coordinate */

   unsigned char winbottom;      /* bottom window coordinate */

   unsigned char attribute;      /* text attribute */

   unsigned char normattr;       /* normal attribute */

   unsigned char currmode;       /* BW40, BW80, C40, C80, or C4350 */

   unsigned char screenheight;   /* text screen's height */

   unsigned char screenwidth;    /* text screen's width */

   unsigned char curx;           /* x-coordinate in current window */

   unsigned char cury;           /* y-coordinate in current window */

};

Note:	Do not use this function for Win32s or Win32 GUI applications.

Return Value

None. Results are returned in the structure pointed to by r.


See Also

textattr

textbackground

textcolor

textmode

wherex

wherey

window


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+	 	 	+


gettime, settime

See Also	Examples	Portability

Syntax

#include <dos.h>

void gettime(struct time *timep);

void settime(struct time *timep);

Description

Gets and sets the system time.

gettime fills in the time structure pointed to by timep with the system's current time.

settime sets the system time to the values in the time structure pointed to by timep.

The time structure is defined as follows:

struct time {

   unsigned char ti_min;      /* minutes */

   unsigned char ti_hour;     /* hours */

   unsigned char ti_hund;     /* hundredths of seconds */

   unsigned char ti_sec;      /* seconds */

};

Return Value

None.


See Also

_dos_gettime

_dos_settime

getdate

setdate

stime

time


Examples

gettime

settime


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
gettime	+		+	+			+
settime	+		+				+


getvect, setvect

See Also	Example	Portability

Syntax

#include <dos.h>

void interrupt(*getvect(int interruptno)) ();                  /* C version */

void interrupt(*getvect(int interruptno)) ( ... );             // C++ version

void setvect(int interruptno, void interrupt (*isr) ());       /* C version */

void setvect(int interruptno, void interrupt (*isr) ( ... ));  // C++ version

Description

Gets and sets interrupt vector.

Every processor of the 8086 family includes a set of interrupt vectors numbered 0 to 255. The 4-byte value in each vector is actually an address which is the location of an interrupt function.

getvect reads the value of the interrupt vector given by interruptno and returns that value as a (far) pointer to an interrupt function. The value of interruptno can be from 0 to 255.

setvect sets the value of the interrupt vector named by interruptno to a new value, isr, which is a far pointer containing the address of a new interrupt function. The address of a C routine can be passed to isr only if that routine is declared to be an interrupt routine.

Note:	In C++, only static member functions or non-member functions can be declared to be an interrupt routine. If you use the prototypes declared in  dos.h, simply pass the address of an interrupt function to setvect in any memory model

Return Value

getvect returns the current 4-byte value stored in the interrupt vector named by interruptno.

setvect does not return a value.


See Also

disable

_dos_getvect

_dos_setvect

enable

geninterrupt


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


getverify

See Also	Example	Portability

Syntax

#include <dos.h>

int getverify(void);

Description

Returns the state of the operating system verify flag.

getverify gets the current state of the verify flag.

The verify flag controls output to the disk. When verify is off writes are not verified; when verify is on all disk writes are verified to ensure proper writing of the data.

Return Value

getverify returns the current state of the verify flag either 0 (off) or 1 (on).


See Also

setverify


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	 	 	 	+


getw

See Also	Example	Portability

Syntax

#include <stdio.h>

int getw(FILE *stream);

Description

Gets integer from stream.

getw returns the next integer in the named input stream. It assumes no special alignment in the file.

getw should not be used when the stream is opened in text mode.

Return Value

getw returns the next integer on the input stream.

On end-of-file or error, getw returns EOF.

Note:	Because EOF is a legitimate value for getw to return, feof or ferror should be used to detect end-of-file or error.


See Also

putw


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


gmtime

See Also	Example	Portability

Syntax

#include <time.h>

struct tm *gmtime(const time_t *timer);

Description

Converts date and time to Greenwich mean time (GMT).

gmtime accepts the address of a value returned by time and returns a pointer to the structure of type tm containing the time elements. gmtime converts directly to GMT.

The global long variable _timezone should be set to the difference in seconds between GMT and local standard time (in PST _timezone is 8 x 60 x 60). The global variable _daylight should be set to nonzero only if the standard U.S. daylight saving time conversion should be applied.

This is the tm structure declaration from the time.h header file:

struct tm {

   int tm_sec;             /* Seconds */

   int tm_min;             /* Minutes */

   int tm_hour;            /* Hour (0 - 23) */

   int tm_mday;            /* Day of month (1 - 31) */

   int tm_mon;             /* Month (0 - 11) */

   int tm_year;            /* Year (calendar year minus 1900) */

   int tm_wday;            /* Weekday (0 - 6; Sunday is 0) */

   int tm_yday;            /* Day of year (0 -365) */

   int tm_isdst;           /* Nonzero if daylight saving time is in effect. */

};

These quantities give the time on a 24-hour clock, day of month (1 to 31), month (0 to 11), weekday (Sunday equals 0), year - 1900, day of year (0 to 365), and a flag that is nonzero if daylight saving time is in effect.

Return Value

gmtime returns a pointer to the structure containing the time elements. This structure is a static that is overwritten with each call.


See Also

asctime

ctime

ftime

localtime

stime

time

tzset


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+  	+	+


gotoxy

See Also	Example	Portability

Syntax

#include <conio.h>

void gotoxy(int x

int y);

Description

Positions cursor in text window.

gotoxy moves the cursor to the given position in the current text window. If the coordinates are in any way invalid the call to gotoxy is ignored. An example of this is a call to gotoxy(40,30) when (35,25) is the bottom right position in the window. Neither argument to gotoxy can be zero.

Note:	Do not use this function for Win32s or Win32 GUI applications.

Return Value

None.


See Also

wherex

wherey

window


Examples

gotoxygotoxy_Ex


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


_heapadd

See Also	Portability

Syntax

#include <malloc.h>

int _heapadd(void *block, size_t size);

Description

Adds a block to the heap.

This function adds a new block of memory to the heap. The block must not have been previously allocated from the heap. _heapadd is typically used to add large static data areas to the heap.

Return Value

On success, _heapadd returns 0.

On error, it returns -1.


See Also

free

malloc


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

 	 	 	+	 	 	+


heapcheck

Example	Portability

Syntax

#include <alloc.h>

int heapcheck(void);

Description

Checks and verifies the heap.

heapcheck walks through the heap and examines each block, checking its pointers, size, and other critical attributes. For DOS users, heapcheck maps to farheapcheck in the large and huge memory models.

Return Value

The return value is less than 0 for an error and greater than 0 for success. The return values and their meaning are as follows:

_HEAPCORRUPT	Heap has been corrupted

_HEAPEMPTY	No heap

_HEAPOK	Heap is verified


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+	 	 	+


heapcheckfree

Example	Portability

Syntax

#include <alloc.h>

int heapcheckfree(unsigned int fillvalue);

Description

Checks the free blocks on the heap for a constant value.

Return Value

The return value is less then 0 for an error and greater than 0 for success. The return values and their meaning are as follows:

_BADVALUE	A value other than the fill value was found

_HEAPCORRUPT	Heap has been corrupted

_HEAPEMPTY	No heap

_HEAPOK	Heap is accurate


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+	 	 	+


heapchecknode

Example	Portability

Syntax

#include <alloc.h>

int heapchecknode(void *node);

Description

Checks and verifies a single node on the heap.

If a node has been freed and heapchecknode is called with a pointer to the freed block, heapchecknode can return _BADNODE rather than the expected _FREEENTRY. This is because adjacent free blocks on the heap are merged, and the block in question no longer exists.

Return Value

One of the following values:

_BADNODE	Node could not be found

_FREEENTRY	Node is a free block

_HEAPCORRUPT	Heap has been corrupted

_HEAPEMPTY	No heap

_USEDENTRY	Node is a used block


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+	 	 	+


_heapchk

See Also	Example	Portability

Syntax

#include <malloc.h>

int _heapchk(void);

Description

Checks and verifies the heap.

_heapchk walks through the heap and examines each block, checking its pointers, size, and other critical attributes.

Return Value

One of the following values:

_HEAPBADNODE	A corrupted heap block has been found

_HEAPEMPTY	No heap exists

_HEAPOK	The heap appears to be uncorrupted


See Also

_heapset

_rtl_heapwalk


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

 	 	 	+	 	 	+


heapfillfree

Example	Portability

Syntax

#include <alloc.h>

int heapfillfree(unsigned int fillvalue);

Description

Fills the free blocks on the heap with a constant value.

Return Value

One of the following values:

_HEAPCORRUPT	Heap has been corrupted

_HEAPEMPTY	No heap

_HEAPOK	Heap is accurate


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+	 	 	+


_heapmin

See Also	Portability

Syntax

#include <malloc.h>

int _heapmin(void);

Description

Release unused heap areas.

The _heapmin function returns unused areas of the heap to the operating system. This allows blocks that have been allocated and then freed to be used by other processes. Due to fragmentation of the heap, _heapmin might not always be able to return unused memory to the operating system; this is not an error.

Return Value

_heapmin returns 0 if it is successful, or -1 if an error occurs.


See Also

free

malloc


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


_heapset

See Also	Example	Portability

Syntax

#include <malloc.h>

int _heapset(unsigned int fillvalue);

Description

Fills the free blocks on the heap with a constant value.

_heapset checks the heap for consistency using the same methods as _heapchk. It then fills each free block in the heap with the value contained in the least significant byte of fillvalue. This function can be used to find heap-related problems. It does not guarantee that subsequently allocated blocks will be filled with the specified value.

Return Value

One of the following values:

_HEAPOK	The heap appears to be uncorrupted

_HEAPEMPTY	No heap exists

_HEAPBADNODE	A corrupted heap block has been found


See Also

_heapchk

_rtl_heapwalk


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

 	 	 	+	 	 	+


heapwalk

Example	Portability

Syntax

#include <alloc.h>

int heapwalk(struct heapinfo *hi);

Description

heapwalk is used to "walk" through the heap, node by node.

heapwalk assumes the heap is correct. Use heapcheck to verify the heap before using heapwalk. _HEAPOK is returned with the last block on the heap. _HEAPEND will be returned on the next call to heapwalk.

heapwalk receives a pointer to a structure of type heapinfo (declared in alloc.h). For the first call to heapwalk, set the hi.ptr field to null. heapwalk returns with hi.ptr containing the address of the first block. hi.size holds the size of the block in bytes. hi.in_use is a flag that's set if the block is currently in use.

Return Value

One of the following values:

_HEAPEMPTY	No heap exists

_HEAPEND	The end of the heap has been reached

_HEAPOK	The heapinfo block contains valid information about the next heap block


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+	 	 	+


highvideo

See Also	Example	Portability

Syntax

#include <conio.h>

void highvideo(void);

Description

Selects high-intensity characters.

highvideo selects high-intensity characters by setting the high-intensity bit of the currently selected foreground color.

This function does not affect any characters currently onscreen, but does affect those displayed by functions (such as cprintf) that perform direct video, text mode output after highvideo is called.

Note:	Do not use this function for Win32s or Win32 GUI applications.

Return Value

None.


See Also

cprintf

cputs

gettextinfo

lowvideo

normvideo

textattr

textcolor


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+	 	 	+


hypot, hypotl

Example	Portability

Syntax

#include <math.h>

double hypot(double x, double y);

long double hypotl(long double x, long double y);

Description

Calculates hypotenuse of a right triangle.

hypot calculates the value z where

z2 = x2 + y2 and z >= 0

This is equivalent to the length of the hypotenuse of a right triangle, if the lengths of the two sides are x and y.

hypotl is the long double version; it takes long double arguments and returns a long double result.

Return Value

On success, these functions return z, a double (hypot) or a long double) (hypotl). On error (such as an overflow), they set the global variable errno to

ERANGE	Result out of range

and return the value HUGE_VAL (hypot) or _LHUGE_VAL) (hypotl). Error handling for these routines can be modified through the functions _matherr and _matherrl.


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
hypot	+	+	+	+			+
hypotl	+		+	+			+


_InitEasyWin

See Also	Example	Portability

Syntax

#include <io.h>

void _InitEasyWin(void);

Description

The purpose of EasyWin is to convert DOS applications to Windows programs, quickly and easily. You might, however, occasionally want to use EasyWin from within a true 16-bit Windows program. For example, you might want to add printf functions to your program code to help you debug your 16-bit Windows program.

To use EasyWin from within a Windows program, make a call to the _InitEasyWin function before doing any standard input or output.

For example:

#include <windows.h>

#include <stdio.h>

#pragma argsused

int PASCAL WinMain(HANDLE hInstance, HANDLE hPrevInstance,
                   LPSTR lpszCmdLine, int cmdShow)

{

   _InitEasyWin();

   /* Normal windows setup */

   printf("Hello, world\n");

   return 0;

}

The prototype for _InitEasyWin can be found in stdio.h and iostream.h.

Return Value

None.


See Also

Using EasyWin

Using EasyWin from within a Windows Program


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

 	 	 	+


inp

See Also	Example	Portability

Syntax

#include <conio.h>

int inp(unsigned portid);

Description

Reads a byte from a hardware port.

inp is a macro that reads a byte from the input port specified by portid. If inp is called when conio.h has been included, it will be treated as a macro that expands to inline code. If you don't include conio.h, or if you do include conio.h and undefine the macro inp, you get the inp function.

Return Value

inp returns the value read.


See Also

inpw

outp

outpw


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


inport

See Also	Example	Portability

Syntax

#include <dos.h>

int inport(int portid);

Description

Reads a word from a hardware port.

inport works just like the 80x86 instruction IN. It reads the low byte of a word from the input port specified by portid; it reads the high byte from portid + 1.

Return Value

inport returns the value read.


See Also

inportb

outport

outportb


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


inportb

See Also	Example	Portability

Syntax

#include <dos.h>

unsigned char inportb(int portid);

Description

Reads a byte from a hardware port.

inportb is a macro that reads a byte from the input port specified by portid.

If inportb is called when dos.h has been included, it will be treated as a macro that expands to inline code. If you don't include dos.h, or if you do include dos.h and #undef the macro inportb, you get the inportb function.

Return Value

inportb returns the value read.


See Also

inport

outport

outportb


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


inpw

See Also	Example	Portability

Syntax

#include <conio.h>

unsigned inpw(unsigned portid);

Description

Reads a word from a hardware port.

inpw is a macro that reads a 16-bit word from the inport port specified by portid. It reads the low byte of the word from portid, and the high byte from portid + 1.

If inpw is called when conio.h has been included, it will be treated as a macro that expands to inline code. If you don't include conio.h, or if you do include conio.h and #undef the macro inpw, you get the inpw function.

Return Value

inpw returns the value read.


See Also

inp

outp

outpw


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


insline

See Also	Example	Portability

Syntax

#include <conio.h>

void insline(void);

Description

Inserts a blank line in the text window.

insline inserts an empty line in the text window at the cursor position using the current text background color. All lines below the empty one move down one line, and the bottom line scrolls off the bottom of the window.

Note:	Do not use this function for Win32s or Win32 GUI applications.

Return Value

None.


See Also

clreol

delline

window


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+	 	 	+


int86

See Also	Example	Portability

Syntax

#include <dos.h>

int int86(int intno, union REGS *inregs, union REGS *outregs);

Description

 General 8086 software interrupt.

int86 executes an 8086 software interrupt specified by the argument intno. Before executing the software interrupt, it copies register values from inregs into the registers.

After the software interrupt returns, int86 copies the current register values to outregs, copies the status of the carry flag to the x.cflag field in outregs, and copies the value of the 8086 flags register to the x.flags field in outregs. If the carry flag is set, it usually indicates that an error has occurred.

Note:	inregs can point to the same structure that outregs points to.

Return Value

int86 returns the value of AX after completion of the software interrupt. If the carry flag is set (outregs -> x.cflag  != 0), indicating an error, this function sets the global variable _doserrno to the error code. Note that when the carry flag is not set (outregs -> x.cflag = 0), you may or may not have an error. To be certain, always check _doserrno.


See Also

bdos

bdosptr

geninterrupt

int86x

intdos

intdosx

intr


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


int86x

See Also	Example	Portability

Syntax

#include <dos.h>

int int86x(int intno, union REGS *inregs, union REGS *outregs, struct SREGS *segregs);

Description

General 8086 software interrupt interface.

int86x executes an 8086 software interrupt specified by the argument intno. Before executing the software interrupt, it copies register values from inregs into the registers.

In addition, int86x copies the segregs ->ds and segregs ->es values into the corresponding registers before executing the software interrupt. This feature allows programs that use far pointers or a large data memory model to specify which segment is to be used for the software interrupt.

After the software interrupt returns, int86x copies the current register values to outregs, the status of the carry flag to the x.cflag field in outregs, and the value of the 8086 flags register to the x.flags field in outregs. In addition, int86x restores DS and sets the segregs ->es and segregs ->ds fields to the values of the corresponding segment registers. If the carry flag is set, it usually indicates that an error has occurred.

int86x lets you invoke an 8086 software interrupt that takes a value of DS different from the default data segment, and/or takes an argument in ES.

Note:	inregs can point to the same structure that outregs points to.

Return Value

int86x returns the value of AX after completion of the software interrupt. If the carry flag is set (outregs -> x.cflag  != 0), indicating an error, this function sets the global variable _doserrno to the error code. Note that when the carry flag is not set (outregs -> x.cflag = 0), you may or may not have an error. To be certain, always check _doserrno.


See Also

bdos

bdosptr

geninterrupt

intdos

intdosx

int86

intr

segread


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


intdos

See Also	Example	Portability

Syntax

#include <dos.h>

int intdos(union REGS *inregs, union REGS *outregs);

Description

General DOS interrupt interface.

intdos executes DOS interrupt 0x21 to invoke a specified DOS function. The value of inregs -> h.ah specifies the DOS function to be invoked.

After the interrupt 0x21 returns, intdos copies the current register values to outregs, copies the status of the carry flag to the x.cflag field in outregs, and copies the value of the 8086 flags register to the x.flags field in outregs. If the carry flag is set, it indicates that an error has occurred.

Note:	inregs can point to the same structure that outregs points to.

Return Value

intdos returns the value of AX after completion of the DOS function call. If the carry flag is set (outregs -> x.cflag != 0), indicating an error, it sets the global variable _doserrno to the error code. Note that when the carry flag is not set (outregs -> x.cflag = 0), you may or may not have an error. To be certain, always check _doserrno.


See Also

bdos

bdosptr

geninterrupt

int86

int86x

intdosx

intr


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


intdosx

See Also	Example	Portability

Syntax

#include <dos.h>

int intdosx(union REGS *inregs, union REGS *outregs, struct SREGS *segregs);

Description

General DOS interrupt interface.

intdosx executes DOS interrupt 0x21 to invoke a specified DOS function. The value of inregs -> h.ah specifies the DOS function to be invoked.

In addition, intdosx copies the segregs ->ds and segregs ->es values into the corresponding registers before invoking the DOS function. This feature allows programs that use far pointers or a large data memory model to specify which segment is to be used for the function execution.

After the interrupt 0x21 returns, intdosx copies the current register values to outregs, copies the status of the carry flag to the x.cflag field in outregs, and copies the value of the 8086 flags register to the x.flags field in outregs. In addition, intdosx sets the segregs ->es and segregs ->ds fields to the values of the corresponding segment registers and then restores DS. If the carry flag is set, it indicates that an error occurred.

intdosx lets you invoke a DOS function that takes a value of DS different from the default data segment and/or takes an argument in ES.

Note:	inregs can point to the same structure that outregs points to.

Return Value

intdosx returns the value of AX after completion of the DOS function call. If the carry flag is set (outregs -> x.cflag != 0), indicating an error, it sets the global variable _doserrno to the error code. Note that when the carry flag is not set (outregs -> x.cflag = 0), you may or may not have an error. To be certain, always check _doserrno.


See Also

bdos

bdosptr

geninterrupt

int86

int86x

intdos

intr

segread


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


intr

See Also	Example	Portability

Syntax

#include <dos.h>

void intr(int intno, struct REGPACK *preg);

Description

 Alternate 8086 software interrupt interface.

The intr function is an alternate interface for executing software interrupts. It generates an 8086 software interrupt specified by the argument intno.

intr copies register values from the REGPACK structure *preg into the registers before executing the software interrupt. After the software interrupt completes, intr copies the current register values into *preg, including the flags.

The arguments passed to intr are as follows:

intno	Interrupt number to be executed

preg 	Address of a structure containing

(a)	the input registers before the interrupt call

(b)	the value of the registers after the interrupt call

The REGPACK structure (defined in dos.h) has the following format:

struct  REGPACK {

   unsigned  r_ax, r_bx, r_cx, r_dx;

   unsigned  r_bp, r_si, r_di, r_ds, r_es, r_flags;

};

Return Value

No value is returned. The REGPACK structure *preg contains the value of the registers after the interrupt call.


See Also

geninterrupt

int86

int86x

intdos

intdosx


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


ioctl

Example	Portability

Syntax

#include <io.h>

int ioctl(int handle, int func [, void *argdx, int argcx]);

Description

Controls I/0 device.

ioctl is available on UNIX systems, but not with these parameters or functionality. UNIX version 7 and System III differ from each other in their use of ioctl. ioctl calls are not portable to UNIX and are rarely portable across DOS machines.

DOS 3.0 extends ioctl with func values of 8 and 11.

This is a direct interface to the DOS call 0x44 (IOCTL).

The exact function depends on the value of func as follows:

0	Get device information.

1	Set device information (in argdx).

2	Read argcx bytes into the address pointed to by argdx.

3	Write argcx bytes from the address pointed to by argdx.

4	Same as 2 except handle is treated as a drive number (0 equals default, 1 equals A, and so on).

5	Same as 3 except handle is a drive number (0 equals default, 1 equals A, and so on).

6	Get input status.

7	Get output status.

8	Test removability; DOS 3.0 only.

11	Set sharing conflict retry count; DOS 3.0 only.

ioctl can be used to get information about device channels. Regular files can also be used, but only func values 0, 6, and 7 are defined for them. All other calls return an EINVAL error for files.

See the documentation for system call 0x44 in your DOS reference manuals for detailed information on argument or return values.

The arguments argdx and argcx are optional.

ioctl provides a direct interface to DOS device drivers for special functions. As a result, the exact behavior of this function varies across different vendors' hardware and in different devices. Also, several vendors do not follow the interfaces described here. Refer to the vendor BIOS documentation for exact use of ioctl.

Return Value

For func 0 or 1, the return value is the device information (DX of the ioctl call). For func values of 2 through 5, the return value is the number of bytes actually transferred. For func values of 6 or 7, the return value is the device status.

In any event, if an error is detected, a value of -1 is returned, and the global variable errno is set to one of the following:

EBADF	Bad file number

EINVAL	Invalid argument

EINVDAT	Invalid data


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+


isalnum

Example	Portability

Syntax

#include <ctype.h>

int isalnum(int c);

Description

Tests for an alphanumeric character.

isalnum is a macro that classifies ASCII-coded integer values by table lookup. The macro is affected by the current locale's LC_CTYPE category. For the default C locale, c is a letter (A to Z or a to z) or a digit (0 to 9).

You can make this macro available as a function by undefining (#undef) it.

Return Value

It is a predicate returning nonzero for true and 0 for false. isalnum returns nonzero if c is a letter or a digit.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


isalpha

Example	Portability

Syntax

#include <ctype.h>

int isalpha(int c);

Description

Classifies an alphabetical character.

isalpha is a macro that classifies ASCII-coded integer values by table lookup. The macro is affected by the current locale's LC_CTYPE category. For the default C locale, c is a letter (A to Z or a to z).

You can make this macro available as a function by undefining (#undef) it.

Return Value

isalpha returns nonzero if c is a letter.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


isascii

Example	Portability

Syntax

#include <ctype.h>

int isascii(int c);

Description

Character classification macro.

isascii is a macro that classifies ASCII-coded integer values by table lookup. It is a predicate returning nonzero for true and 0 for false.

isascii is defined on all integer values.

Return Value

isascii returns nonzero if the low order byte of c is in the range 0 to 127 (0x00-0x7F).


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


isatty

Example	Portability

Syntax

#include <io.h>

int isatty(int handle);

Description

Checks for device type.

isatty determines whether handle is associated with any one of the following character devices:

a terminal

a console

a printer

a serial port

Return Value

If the device is one of the four character devices listed above, isatty returns a nonzero integer. If it is not such a device, isatty returns 0.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


iscntrl

Example	Portability

Syntax

#include <ctype.h>

int iscntrl(int c);

Description

Tests for a control character.

iscntrl is a macro that classifies ASCII-coded integer values by table lookup. The macro is affected by the current locale's LC_CTYPE category. For the default C locale, c is a delete character or control character (0x7F or 0x00 to 0x1F).

You can make this macro available as a function by undefining (#undef) it.

Return Value

iscntrl returns nonzero if c is a delete character or ordinary control character.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


isdigit

Example	Portability

Syntax

#include <ctype.h>

int isdigit(int c);

Description

Tests for decimal-digit character.

isdigit is a macro that classifies ASCII-coded integer values by table lookup. The macro is affected by the current locale's LC_CTYPE category. For the default C locale, c is a digit (0 to 9).

You can make this macro available as a function by undefining (#undef) it.

Return Value

isdigit returns nonzero if c is a digit.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


isgraph

Example	Portability

Syntax

#include <ctype.h>

int isgraph(int c);

Description

Tests for printing character.

isgraph is a macro that classifies ASCII-coded integer values by table lookup. The macro is affected by the current locale's LC_CTYPE category. For the default C locale, c is a printing character except blank space (' ').

You can make this macro available as a function by undefining (#undef) it.

Return Value

isgraph returns nonzero if c is a printing character.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


islower

Example	Portability

Syntax

#include <ctype.h>

int islower(int c);

Description

Tests for lowercase character.

islower is a macro that classifies ASCII-coded integer values by table lookup. The macro is affected by the current locale's LC_CTYPE category. For the default C locale, c is a lowercase letter (ato z).

You can make this macro available as a function by undefining (#undef) it.

Return Value

islower returns nonzero if c is a lowercase letter.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


isprint

Example	Portability

Syntax

#include <ctype.h>

int isprint(int c);

Description

Tests for printing character.

isprint is a macro that classifies ASCII-coded integer values by table lookup. The macro is affected by the current locale's LC_CTYPE category. For the default C locale, c is a printing character including the blank space (' ').

You can make this macro available as a function by undefining (#undef) it.

Return Value

isprint returns nonzero if c is a printing character.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


ispunct

Example	Portability

Syntax

#include <ctype.h>

int ispunct(int c);

Description

Tests for punctuation character.

ispunct is a macro that classifies ASCII-coded integer values by table lookup. The macro is affected by the current locale's LC_CTYPE category. For the default C locale, c is any printing character that is neither an alphanumeric nor a blank space (' ').

You can make this macro available as a function by undefining (#undef) it.

Return Value

ispunct returns nonzero if c is a punctuation character.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


isspace

Example	Portability

Syntax

#include <ctype.h>

int isspace(int c);

Description

Tests for space character.

isspace is a macro that classifies ASCII-coded integer values by table lookup. The macro is affected by the current locale's LC_CTYPE category.

You can make this macro available as a function by undefining (#undef) it.

Return Value

isspace returns nonzero if c is a space, tab, carriage return, new line, vertical tab, formfeed (0x09 to 0x0D, 0x20), or any other locale-defined space character.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


isupper

Example	Portability

Syntax

#include <ctype.h>

int isupper(int c);

Description

 Tests for uppercase character.

isupper is a macro that classifies ASCII-coded integer values by table lookup. The macro is affected by the current locale's LC_CTYPE category. For the default C locale, c is an uppercase letter (A to Z).

You can make this macro available as a function by undefining (#undef) it.

Return Value

isupper returns nonzero if c is an uppercase letter.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


isxdigit

Example	Portability

Syntax

#include <ctype.h>

int isxdigit(int c);

Description

Tests for hexadecimal character.

isxdigit is a macro that classifies ASCII-coded integer values by table lookup. The macro is affected by the current locale's LC_CTYPE category.

You can make this macro available as a function by undefining (#undef) it.

Return Value

isxdigit returns nonzero if c is a hexadecimal digit (0 to 9, A to F, a to f) or any other hexadecimal digit defined by the locale.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


itoa

See Also	Example	Portability

Syntax

#include <stdlib.h>

char *itoa(int value, char *string, int radix);

Description

Converts an integer to a string.

itoa converts value to a null-terminated string and stores the result in string. With itoa, value is an integer.

radix specifies the base to be used in converting value; it must be between 2 and 36, inclusive. If value is negative and radix is 10, the first character of string is the minus sign (-).

Note:	The space allocated for string must be large enough to hold the returned string, including the terminating null character (\0). itoa can return up to 17 bytes.

Return Value

itoa returns a pointer to string.


See Also

ltoa

ultoa


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


kbhit

See Also	Example	Portability

Syntax

#include <conio.h>

int kbhit(void);

Description

Checks for currently available keystrokes.

kbhit checks to see if a keystroke is currently available. Any available keystrokes can be retrieved with getch or getche.

Note:	Do not use this function for Win32s or Win32 GUI applications.

Return Value

If a keystroke is available, kbhit returns a nonzero value. Otherwise, it returns 0.


See Also

getch

getche


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


labs

See Also	Example	Portability

Syntax

#include <math.h>

long labs(long int x);

Description

Gives long absolute value.

labs computes the absolute value of the parameter x.

Return Value

labs returns the absolute value of x.


See Also

abs

cabs

fabs


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+  	+	+


ldexp, ldexpl

See Also	Example	Portability

Syntax

#include <math.h>

double ldexp(double x, int exp);

long double ldexpl(long double x, int exp);

Description

Calculates

lexpl is the long double version; it takes a long double argument for x and returns a long double result.

Return Value

On success, ldexp (or ldexpl) returns the value it calculated, [image]. Error handling for these routines can be modified through the functions _matherr and _matherrl.


See Also

exp

frexp

modf


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
ldexp	+	+	+	+	+	+	+
ldexpl	+		+	+			+


ldiv

See Also	Example	Portability

Syntax

#include <stdlib.h>

ldiv_t ldiv(long int numer, long int denom);

Description

Divides two longs, returning quotient and remainder.

ldiv divides two longs and returns both the quotient and the remainder as an ldiv_t type. numer and denom are the numerator and denominator, respectively.

The ldiv_t type is a structure of longs defined in stdlib.h as follows:

typedef struct {

   long int quot;      /* quotient */

   long int rem;       /* remainder */

   } ldiv_t;

Return Value

ldiv returns a structure whose elements are quot (the quotient) and rem (the remainder).


See Also

div


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	+	+	+


lfind

See Also	Example	Portability

Syntax

#include <stdlib.h>

void  *lfind(const void *key, const void *base, size_t *num, size_t width, int (_USERENTRY *fcmp)(const void *, const void *));

Description

Performs a linear search.

lfind makes a linear search for the value of key in an array of sequential records. It uses a user-defined comparison routine fcmp. The fcmp function must be used with the _USERENTRY calling convention.

The array is described as having *num records that are width bytes wide, and begins at the memory location pointed to by base.

Return Value

lfind returns the address of the first entry in the table that matches the search key. If no match is found, lfind returns NULL. The comparison routine must return 0 if *elem1 == *elem2, and nonzero otherwise (elem1 and elem2 are its two parameters).


See Also

bsearch

lsearch

qsort


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


localeconv

See Also	Example	Portability

Syntax

#include <locale.h>

struct lconv *localeconv(void);

Description

Queries the locale for numeric format.

This function provides information about the monetary and other numeric formats for the current locale. The information is stored in a struct lconv type. The structure can only be modified by the setlocale. Subsequent calls to localeconv will update the lconv structure.

The lconv structure is defined in locale.h. It contains the following fields:

Field	Application

char *decimal_point;	Decimal point used in nonmonetary formats. This can never be an empty string.

char *thousands_sep;	Separator used to group digits to the left of the decimal point. Not used with monetary quantities.

char *grouping;	Size of each group of digits. Not used with monetary quantities. See the value listing table below.

char *int_curr_symbol;	International monetary symbol in the current locale. The symbol format is specified in the ISO 4217 Codes for the Representation of Currency and Funds.

char *currency_symbol;	Local monetary symbol for the current locale.

char *mon_decimal_point;	Decimal point used to format monetary quantities.

char *mon_thousands_sep;	Separator used to group digits to the left of the decimal point for monetary quantities.

char *mon_grouping;	Size of each group of digits used in monetary quantities. See the value listing table below.

char *positive_sign;	String indicating nonnegative monetary quantities.

char *negative_sign;	String indicating negative monetary quantities.

char int_frac_digits;	Number of digits after the decimal point that are to be displayed in an internationally formatted monetary quantity.

char frac_digits;	Number of digits after the decimal point that are to be displayed in a formatted monetary quantity.

char p_cs_precedes;	Set to 1 if currency_symbol precedes a nonnegative formatted monetary quantity. If currency_symbol is after the quantity, it is set to 0.

char p_sep_by_space;	Set to 1 if currency_symbol is to be separated from the nonnegative formatted monetary quantity by a space. Set to 0 if there is no space separation.

char n_cs_precedes;	Set to 1 if currency_symbol precedes a negative formatted monetary quantity. If currency_symbol is after the quantity, set to 0.

char n_sep_by_space;	Set to 1 if currency_symbol is to be separated from the negative formatted monetary quantity by a space. Set to 0 if there is no space separation.

char p_sign_posn;	Indicate where to position the positive sign in a nonnegative formatted monetary quantity.

char n_sign_posn;	Indicate where to position the positive sign in a negative formatted monetary quantity.

Any of the above strings (except decimal_point) that is empty " " is not supported in the current locale. The nonstring char elements are nonnegative numbers. Any nonstring char element that is set to CHAR_MAX indicates that the element is not supported in the current locale.

The grouping and mon_grouping elements are set and interpreted as follows:

Value	Meaning

CHAR_MAX	No further grouping is to be performed.

0	The previous element is to be used repeatedly for the remainder of the digits.

any other integer	Indicates how many digits make up the current group. The next element is read to determine the size of the next group of digits before the current group.

The p_sign_posn and n_sign_posn elements are set and interpreted as follows:

Value	Meaning

0	Use parantheses to surround the quantity and currency_symbol.

1	Sign string precedes the quantity and currency_symbol.

2	Sign string succeeds the quatity and currency_symbol.

3	Sign string immediately precedes the quantity and currency_symbol.

4	Sign string immediately succeeds the quantity and currency_symbol.

Return Value

Returns a pointer to the the filled-in structure of type struct lconv. The values in the structure will change whenever setlocale modifies the LC_MONETARY or LC_NUMERIC categories.


See Also

setlocale


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	+	+	+


localtime

See Also	Example	Portability

Syntax

#include <time.h>

struct tm *localtime(const time_t *timer);

Description

Converts date and time to a structure.

localtime accepts the address of a value returned by time and returns a pointer to the structure of type tm containing the time elements. It corrects for the time zone and possible daylight saving time.

The global long variable _timezone contains the difference in seconds between GMT and local standard time (in PST, _timezone is 8 x 60 x 60). The global variable daylight contains nonzero only if the standard U.S. daylight saving time conversion should be applied. These values are set by tzset, not by the user program directly.

This is the tm structure declaration from the time.h header file:

struct tm {

   int tm_sec;

   int tm_min;

   int tm_hour;

   int tm_mday;

   int tm_mon;

   int tm_year;

   int tm_wday;

   int tm_yday;

   int tm_isdst;

};

These quantities give the time on a 24-hour clock, day of month (1 to 31), month (0 to 11), weekday (Sunday equals 0), year - 1900, day of year (0 to 365), and a flag that is nonzero if _daylight saving time is in effect.

Return Value

localtime returns a pointer to the structure containing the time elements. This structure is a static that is overwritten with each call.


See Also

asctime

ctime

ftime

gmtime

stime

time

tzset


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


lock

See Also	Example	Portability

Syntax

#include <io.h>

int lock(int handle, long offset, long length);

Description

Sets file-sharing locks. DOS users must be sure to load SHARE.EXE before using lock.

lock provides an interface to the operating system file-sharing mechanism.

A lock can be placed on arbitrary, nonoverlapping regions of any file. A program attempting to read or write into a locked region will retry the operation three times. If all three retries fail, the call fails with an error.

Return Value

lock returns 0 on success. On error, lock returns -1 and sets the global variable errno to

EACCES	Locking violation


See Also

locking

open

sopen

unlock


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


locking

See Also	Example	Portability

Syntax

#include <io.h>

#include <sys\locking.h>

int locking(int handle, int cmd, long length);

Description

Sets or resets file-sharing locks. DOS users must be sure to load SHARE.EXE before using locking.

locking provides an interface to the operating system file-sharing mechanism. The file to be locked or unlocked is the open file specified by handle. The region to be locked or unlocked starts at the current file position, and is length bytes long.

Locks can be placed on arbitrary, nonoverlapping regions of any file. A program attempting to read or write into a locked region will retry the operation three times. If all three retries fail, the call fails with an error.

The cmd specifies the action to be taken (the values are defined in sys\locking.h):

LK_LOCK	Lock the region. If the lock is unsuccessful, try once a second for 10 seconds before giving up.

LK_RLCK	Same as LK_LOCK.

LK_NBLCK	Lock the region. If the lock if unsuccessful, give up immediately.

LK_NBRLCK	 Same as LK_NBLCK.

LK_UNLCK	Unlock the region, which must have been previously locked.

Return Value

On successful operations, locking returns 0. Otherwise, it returns -1, and the global variable errno is set to one of the following values:

EACCES	File already locked or unlocked

EBADF	Bad file number

EDEADLOCK	File cannot be locked after 10 retries (cmd is LK_LOCK or LK_RLCK)

EINVAL	Invalid cmd, or SHARE.EXE not loaded


See Also

_fsopen

lock

open

sopen

unlock


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


log, logl

See Also	Example	Portability

Syntax

#include <math.h>

double log(double x);

long double logl(long double x);

Description

Calculates the natural logarithm of x.

log calculates the natural logarithm of x.

logl is the long double version; it takes a long double argument and returns a long double result.

This function can be used with bcd and complex types.

Return Value

On success, log and logl return the value calculated, ln(x).

If the argument x passed to these functions is real and less than 0, the global variable errno is set to

EDOM	Domain error

If x is 0, the functions return the value negative HUGE_VAL (log) or negative _LHUGE_VAL (logl), and set errno to ERANGE. Error handling for these routines can be modified through the functions _matherr and _matherrl.


See Also

bcd

complex

exp

log10

sqrt


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
log	+	+	+	+	+	+	+
logl	+		+	+			+


log10, log10l

See Also	Example	Portability

Syntax

#include <math.h>

double log10(double x);

long double log10l(long double x);

Description

log10 calculates the base 10 logarithm of x.

log10l is the long double version; it takes a long double argument and returns a long double result.

This function can be used with bcd and complex types.

Return Value

On success, log10 (or log10l) returns the value calculated, [image].

If the argument x passed to these functions is real and less than 0, the global variable errno is set to

EDOM	Domain error

If x is 0, these functions return the value negative HUGE_VAL (log10) or _LHUGE_VAL (log10l). Error handling for these routines can be modified through the functions _matherr and _matherrl.


See Also

bcd

complex

exp

log


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
log10	+	+	+	+	+	+	+
log10l	+		+	+			+


longjmp

See Also	Example	Portability

Syntax

#include <setjmp.h>

void longjmp(jmp_buf jmpb, int retval);

Description

Performs nonlocal goto.

A call to longjmp restores the task state captured by the last call to setjmp with the argument jmpb. It then returns in such a way that setjmp appears to have returned with the value retval.

A task state includes

Win 16	Win 32
All segment registers CS, DS, ES, SS	No segment registers are saved
Register variables	Register variables
DI and SI	EBX, EDI, ESI
Stack pointer SP	Stack pointer ESP
Frame pointer BP	Frame pointer EBP
Flags	Flags are not saved
A task state is complete enough that setjmp and longjmp can be used to implement co-routines.

setjmp must be called before longjmp. The routine that called setjmp and set up jmpb must still be active and cannot have returned before the longjmp is called. If this happens, the results are unpredictable.

longjmp cannot pass the value 0; if 0 is passed in retval, longjmp will substitute 1.

DOS Users

You cannot use setjmp and longjmp for implementing co-routines if your program is overlaid. Normally, setjmp and longjmp save and restore all the registers needed for co-routines, but the overlay manager needs to keep track of stack contents and assumes there is only one stack. When you implement co-routines, there are usually either two stacks or two partitions of one stack, and the overlay manager will not track them properly.

You can have background tasks that run with their own stacks or sections of stack, but you must ensure that the background tasks do not invoke any overlaid code, and you must not use the overlay versions of setjmp or longjmp to switch to and from background.

Return Value

None.


See Also

ctrlbrk

setjmp

signal


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+ 	+	+


lowvideo

See Also	Example	Portability

Syntax

#include <conio.h>

void lowvideo(void);

Description

Selects low-intensity characters.

lowvideo selects low-intensity characters by clearing the high-intensity bit of the currently selected foreground color.

This function does not affect any characters currently onscreen. It affects only those characters displayed by functions that perform text mode, direct console output after this function is called.

Note:	Do not use this function for Win32s or Win32 GUI applications.

Return Value

None.


See Also

highvideo

normvideo

textattr

textcolor


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+	 	 	+


_lrotl, _lrotr

See Also	Example	Portability

Syntax

#include <stdlib.h>

unsigned long _lrotl(unsigned long val, int count);

unsigned long _lrotr(unsigned long val, int count);

Description

Rotates an unsigned long integer value to the left or right.

_Irotlrotates the given val to the left count bits. _lrotr rotates the given val to the right count bits.

Return Value

The functions return the rotated integer:

_lrotl returns the value of val left-rotated count bits.

_lrotr returns the value of val right-rotated count bits.


See Also

_crotr

_crotl

_rotl

_rotr


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


lsearch

See Also	Example	Portability

Syntax

#include <stdlib.h>

void *lsearch(const void *key, void *base, size_t *num, size_t width, int (_USERENTRY *fcmp)(const void *, const void *));

Description

 Performs a linear search.

lsearch searches a table for information. Because this is a linear search, the table entries do not need to be sorted before a call to lsearch. If the item that key points to is not in the table, lsearch appends that item to the table.

base points to the base (0th element) of the search table.

num points to an integer containing the number of entries in the table.

width contains the number of bytes in each entry.

key points to the item to be searched for (the search key).

The function fcmp must be used with the _USERENTRY calling convention.

The argument fcmp points to a user-written comparison routine, that compares two items and returns a value based on the comparison.

To search the table, lsearch makes repeated calls to the routine whose address is passed in fcmp.

On each call to the comparison routine, lsearch passes two arguments:

key	a pointer to the item being searched for

elem	pointer to the element of base being compared.

fcmp is free to interpret the search key and the table entries in any way.

Return Value

lsearch returns the address of the first entry in the table that matches the search key.

If the search key is not identical to *elem, fcmp returns a nonzero integer. If the search key is identical to *elem, fcmp returns 0.


See Also

bsearch

lfind

qsort


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


lseek

See Also	Example	Portability

Syntax

#include <io.h>

long lseek(int handle, long offset, int fromwhere);

Description

Moves file pointer.

lseek sets the file pointer associated with handle to a new position offset bytes beyond the file location given by fromwhere. fromwhere must be one of the following symbolic constants (defined in io.h):

fromwhere	File location

SEEK_CUR	Current file pointer position

SEEK_END	End-of-file

SEEK_SET	File beginning

Return Value

lseek returns the offset of the pointer's new position measured in bytes from the file beginning. lseek returns -1L on error, and the global variable errno is set to one of the following values:

EBADF	Bad file handle

EINVAL	Invalid argument

ESPIPE	Illegal seek on device

On devices incapable of seeking (such as terminals and printers), the return value is undefined.


See Also

filelength

fseek

ftell

getc

open

sopen

ungetc

_rtl_write

write


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


ltoa

See Also	Example	Portability

Syntax

#include <stdlib.h>

char *ltoa(long value, char *string, int radix);

Description

Converts a long to a string.

ltoa converts value to a null-terminated string and stores the result in string. value is a long integer.

radix specifies the base to be used in converting value; it must be between 2 and 36, inclusive. If value is negative and radix is 10, the first character of string is the minus sign (-).

Note:	The space allocated for string must be large enough to hold the returned string, including the terminating null character (\0). ltoa can return up to 33 bytes.

Return Value

ltoa returns a pointer to string.


See Also

itoa

ultoa


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


_makepath

See Also	Example	Portability

Syntax

#include <stdlib.h>

void _makepath(char *path, const char *drive, const char *dir,

               const char *name, const char *ext);

Description

Builds a path from component parts.

_makepath makes a path name from its components. The new path name is

   X:\DIR\SUBDIR\NAME.EXT

where

drive	=	X:

dir 	=	\DIR\SUBDIR\

name	=	NAME

ext	=	.EXT

If drive is empty or NULL, no drive is inserted in the path name. If it is missing a trailing colon (:), a colon is inserted in the path name.

If dir is empty or NULL, no directory is inserted in the path name. If it is missing a trailing slash (\ or /), a backslash is inserted in the path name.

If name is empty or NULL, no file name is inserted in the path name.

If ext is empty or NULL, no extension is inserted in the path name. If it is missing a leading period (.), a period is inserted in the path name.

_makepath assumes there is enough space in path for the constructed path name. The maximum constructed length is _MAX_PATH. _MAX_PATH is defined in stdlib.h.

_makepath and _splitpath are invertible; if you split a given path with _splitpath, then merge the resultant components with _makepath, you end up with path.

Return Value

None


See Also

_fullpath

_splitpath


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


malloc

See Also	Example	Portability

Syntax

#include <stdlib.h> or #include<alloc.h>

void *malloc(size_t size);

Description

malloc allocates a block of size bytes from the memory heap. It allows a program to allocate memory explicitly as it's needed, and in the exact amounts needed.

Allocates main memory.The heap is used for dynamic allocation of variable-sized blocks of memory. Many data structures, for example, trees and lists, naturally employ heap memory allocation.

For 16-bit programs, all the space between the end of the data segment and the top of the program stack is available for use in the small data models, except for a small margin immediately before the top of the stack. This margin is intended to allow the application some room to make the stack larger, in addition to a small amount needed by DOS.

In the large data models, all the space beyond the program stack to the end of available memory is available for the heap.

Return Value

On success, malloc returns a pointer to the newly allocated block of memory. If not enough space exists for the new block, it returns NULL. The contents of the block are left unchanged. If the argument size == 0, malloc returns NULL.


See Also

calloc

farcalloc

farmalloc

free

realloc


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+ 	+	+


_matherr, _matherrl

Example	Portability

Syntax

#include <math.h>

int _matherr(struct _exception *e);

int _matherrl(struct _exceptionl *e);

Description

User-modifiable math error handler.

_matherr is called when an error is generated by the math library.

_matherrl is the long double version; it is called when an error is generated by the long double math functions.

_matherr and _matherrl each serve as a user hook (a function that can be customized by the user) that you can replace by writing your own math error-handling routine.

_matherr and _matherrl are useful for information on trapping domain and range errors caused by the math functions. They do not trap floating-point exceptions, such as division by zero. See signal for information on trapping such errors.

You can define your own _matherr or _matherrl routine to be a custom error handler (such as one that catches and resolves certain types of errors); this customized function overrides the default version in the C library. The customized _matherr or _matherrl should return 0 if it fails to resolve the error, or nonzero if the error is resolved. When _matherr or _matherrl return nonzero, no error message is printed and the global variable errno is not changed.

Here are the _exception and _exceptionl structures (defined in math.h):

struct _exception {

   int   type;

   char  *name;

   double arg1, arg2, retval;

};

struct _exceptionl {

   int   type;

   char  *name;

   long double arg1, arg2, retval;

};

The members of the _exception and _exceptionl structures are shown in the following table:

Member 	What It Is (Or Represents)

type	The type of mathematical error that occurred; an enum type defined in the typedef _mexcep (see definition after this list).

name	A pointer to a null-terminated string holding the name of the math library function that resulted in an error.

arg1, arg2	The arguments (passed to the function that name points to) caused the error; if only one argument was passed to the function, it is stored in arg1.

retval	The default return value for _matherr (or _matherrl); you can modify this value.

The typedef _mexcep, also defined in math.h, enumerates the following symbolic constants representing possible mathematical errors:

Symbolic Constant	Mathematical Error

DOMAIN	Argument was not in domain of function, such as log(-1).

SING	Argument would result in a singularity, such as pow(0, -2).

OVERFLOW	Argument would produce a function result greater than DBL_MAX (or LDBL_MAX), such as exp(1000).

UNDERFLOW 	Argument would produce a function result less than DBL_MIN (or LDBL_MIN), such as exp(-1000).

TLOSS	Argument would produce function result with total loss of significant digits, such as sin(10e70).

The macros DBL_MAX, DBL_MIN, LDBL_MAX, and LDBL_MIN are defined in float.h

The source code to the default _matherr and _matherrl is on the Borland C++ distribution disks.

The UNIX-style _matherr and _matherrl default behavior (printing a message and terminating) is not ANSI compatible. If you want a UNIX-style version of these routines, use MATHERR.C and MATHERRL.C provided on the Borland C++ distribution disks.

Return Value

The default return value for _matherr and _matherrl is 1 if the error is UNDERFLOW or TLOSS, 0 otherwise. _matherr and _matherrl can also modify e -> retval, which propagates back to the original caller.

When _matherr and _matherrl return 0 (indicating that they were not able to resolve the error), the global variable errno is set to 0 and an error message is printed.

When _matherr and _matherrl return nonzero (indicating that they were able to resolve the error), the global variable errno is not set and no messages are printed.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


max

See Also	Example	Portability

Syntax

#include <stdlib.h> /* macro version */

(type) max(a, b);

template <class T> T max( T t1, T t2 ); // C++ only

Description

Returns the larger of two values.

The C macro and the C++ template function compare two values and return the larger of the two. Both arguments and the routine declaration must be of the same type.

Return Value

max returns the larger of two values.


See Also

min


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


mblen

See Also	Example	Portability

Syntax

#include <stdlib.h>

int mblen(const char *s, size_t n);

Description

Determines the length of a multibyte character.

If s is not null, mblen determines the number of bytes in the multibyte character pointed to by s. The maximum number of bytes examined is specified by n.

The behavior of mblen is affected by the setting of LC_CTYPE category of the current locale.

Return Value

If s is null, mblen returns a nonzero value if multibyte characters have state-dependent encodings. Otherwise, mblen returns 0.

If s is not null, mblen returns 0 if s points to the null character, and -1 if the next n bytes do not comprise a valid multibyte character; the number of bytes that comprise a valid multibyte character.


See Also

mbstowcs

mbtowc

setlocale


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	+	+	+


mbstowcs

See Also	Example	Portability

Syntax

#include <stdlib.h>

size_t mbstowcs(wchar_t *pwcs, const char *s, size_t n);

Description

Converts a multibyte string to a wchar_t array.

The function converts the multibyte string s into the array pointed to by pwcs. No more than n values are stored in the array. If an invalid multibyte sequence is encountered, mbstowcs returns (size_t) -1.

The pwcs array will not be terminated with a zero value if mbstowcs returns n.

Return Value

If an invalid multibyte sequence is encountered, mbstowcs returns (size_t) -1. Otherwise, the function returns the number of array elements modified, not including the terminating code, if any.


See Also

mblen

mbtowc

setlocale


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	+	+	+


mbtowc

See Also	Example	Portability

Syntax

#include <stdlib.h>

int mbtowc(wchar_t *pwc, const char *s, size_t n);

Description

Converts a multibyte character to wchar_t code.

If s is not null, mbtowc determines the number of bytes that comprise the multibyte character pointed to by s. Next, mbtowc determines the value of the type wchar_t that corresponds to that multibyte character. If there is a successful match between wchar_t and the multibyte character, and pwc is not null, the wchar_t value is stored in the array pointed to by pwc. At most n characters are examined.

Return Value

When s points to an invalid multibyte character, -1 is returned. When s points to the null character, 0 is returned. Otherwise, mbtowc returns the number of bytes that comprise the converted multibyte character.

The return value never exceeds MB_CUR_MAX or the value of n.


See Also

mblen

mbstowcs

setlocale


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	+	+	+


memccpy, _fmemccpy

See Also	Example	Portability

Syntax

#include <mem.h>

void *memccpy(void *dest, const void *src, int c, size_t n);

void far * far _fmemccpy(void far *dest, const void far *src, int c, size_t n)

Description

Copies a block of n bytes.

memccpy is available on UNIX System V systems.

memccpy copies a block of n bytes from src to dest. The copying stops as soon as either of the following occurs:

The character c is first copied into dest.

n bytes have been copied into dest.

Return Value

memccpy returns a pointer to the byte in dest immediately following c, if c was copied; otherwise, memccpy returns NULL.


See Also

memcpy

memmove

memset


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
memccpy	+	+	+	+			+
_fmemccpy	+		+


memchr, _fmemchr

Example	Portability

Syntax

#include <mem.h>

void *memchr(const void *s, int c, size_t n);                       /* C only */

void far * far _fmemchr(const void far *s, int c, size_t n);   /* C only

*/

const void *memchr(const void *s, int c, size_t n);                  // C++ only

void *memchr(void *s, int c, size_t n);                              // C++ only

const void far * far _fmemchr(const void far *s, int c, size_t n);    //

C++ only

void far * far _fmemchr(void far *s, int c, size_t n);       // C++ only

void *memchr(const void *s, int c, size_t n);

void far * far _fmemchr(const void far *s, int c, size_t n);

Description

Searches n bytes for character c.

memchr is available on UNIX System V systems.

memchr searches the first n bytes of the block pointed to by s for character c.

Return Value

On success, memchr returns a pointer to the first occurrence of c in s; otherwise, it returns NULL.

Note:	If you are using the intrinsic version of these functions, the case of n = 0 will return NULL.


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
memchr	+	+	+	+	+	+	+
_fmemchr	+		+


memcmp, _fmemcmp

See Also	Example	Portability

Syntax

#include <mem.h>

int memcmp(const void *s1, const void *s2, size_t n);

int far _fmemcmp(const void far *s1, const void far *s2, size_t n)

Description

Compares two blocks for a length of exactly n bytes.

memcmp is available on UNIX System V systems.

memcmp compares the first n bytes of the blocks s1 and s2 as unsigned chars.

Return Value

Because it compares bytes as unsigned chars, memcmp returns a value that is

< 0 if s1 is less than s2

= 0 if s1 is the same as s2

> 0 if s1 is greater than s2

For example,

   memcmp("\xFF", "\x7F", 1)

returns a value greater than 0.

Note:	If you are using the intrinsic version of these functions, the case of n = 0 will return NULL.


See Also

memicmp


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
memcmp	+	+	+	+	+	+	+
_fmemcmp	+		+


memcpy, _fmemcpy

See Also	Example	Portability

Syntax

#include <mem.h>

void *memcpy(void *dest, const void *src, size_t n);

void far *far _fmemcpy(void far *dest, const void far *src, size_t n);

Description

Copies a block of n bytes.

memcpy is available on UNIX System V systems.

memcpy copies a block of n bytes from src to dest. If src and dest overlap, the behavior of memcpy is undefined.

Return Value

memcpy returns dest.


See Also

memccpy

memmove

memset

movedata

movmem


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
memcpy	+	+	+	+	+	+	+
_fmemcpy	+		+


memicmp, _fmemicmp

See Also	Example	Portability

Syntax

#include <mem.h>

int memicmp(const void *s1, const void *s2, size_t n);

int far _fmemicmp(const void far *s1, const void far *s2, size_t n)

Description

Compares n bytes of two character arrays, ignoring case.

memicmp is available on UNIX System V systems.

memicmp compares the first n bytes of the blocks s1 and s2, ignoring character case (upper or lower).

Return Value

memicmp returns a value that is

< 0 if s1 is less than s2

= 0 if s1 is the same as s2

> 0 if s1 is greater than s2


See Also

memcmp


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
memicmp	+	+	+	+			+
_fmemicmp	+		+


memmove, _fmemmove

See Also	Example	Portability

Syntax

#include <mem.h>

void *memmove(void *dest, const void *src, size_t n);

void far * far _fmemmove (void far *dest, const void far *src, size_t n)

Description

Copies a block of n bytes.

memmove copies a block of n bytes from src to dest. Even when the source and destination blocks overlap, bytes in the overlapping locations are copied correctly.

_fmemmove is the far version.

Return Value

memmove and _fmemmove return dest.


See Also

memccpy

memcpy

movmem


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
memmove	+	+	+	+	+	+	+
_fmemmove	+		+


memset, _fmemset

See Also	Example	Portability

Syntax

#include <mem.h>

void *memset(void *s, int c, size_t n);

void far * far _fmemset (void far *s, int c, size_t n)

Description

Sets n bytes of a block of memory to byte c.

memset sets the first n bytes of the array s to the character c.

Return Value

memset returns s.


See Also

memccpy

memcpy

setmem


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
memset	+	+	+	+	+	+	+
_fmemset	+		+


min

See Also	Example	Portability

Syntax

#include <stdlib.h> /* macro version */

(type) min(a, b);

template <class T> T min( T t1, T t2 ); // C++ only

Description

Returns the smaller of two values.

The C macro and the C++ template function compare two values and return the smaller of the two. Both arguments and the routine declaration must be of the same type.

Return Value

min returns the smaller of two values.


See Also

max


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


mkdir

See Also	Example	Portability

Syntax

#include <dir.h>

int mkdir(const char *path);

Description

Creates a directory.

mkdir is available on UNIX, though it then takes an additional parameter.

mkdir creates a new directory from the given path name path.

Return Value

mkdir returns the value 0 if the new directory was created.

A return value of -1 indicates an error, and the global variable errno is set to one of the following values:

EACCES	Permission denied

ENOENT	No such file or directory


See Also

chdir

getcurdir

getcwd

rmdir


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


MK_FP

See Also	Example	Portability

Syntax

#include <dos.h>

void far * MK_FP(unsigned seg, unsigned ofs);

Description

Makes a far pointer.

MK_FP is a macro that makes a far pointer from its component segment (seg) and offset (ofs) parts.

Return Value

MK_FP returns a far pointer.


See Also

FP_OFF

FP_SEG

movedata

segread


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


mktemp

Example	Portability

Syntax

#include <dir.h>

char *mktemp(char *template);

Description

Makes a unique file name.

mktemp replaces the string pointed to by template with a unique file name and returns template.

template should be a null-terminated string with six trailing Xs. These Xs are replaced with a unique collection of letters plus a period, so that there are two letters, a period, and three suffix letters in the new file name.

Starting with AA.AAA, the new file name is assigned by looking up the name on the disk and avoiding pre-existing names of the same format.

Return Value

If template is well-formed, mktemp returns the address of the template string. Otherwise, it returns null.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


mktime

See Also	Example	Portability

Syntax

#include <time.h>

time_t mktime(struct tm *t);

Description

Converts time to calendar format.

Converts the time in the structure pointed to by t into a calendar time with the same format used by the time function. The original values of the fields tm_sec, tm_min, tm_hour, tm_mday, and tm_mon are not restricted to the ranges described in the tm structure. If the fields are not in their proper ranges, they are adjusted. Values for fields tm_wday and tm_yday are computed after the other fields have been adjusted.

The allowable range of calendar times is Jan 1 1970 00:00:00 to Jan 19 2038 03:14:07.

Return Value

On success, mktime returns calendar time as described above.

On error (if the calendar time cannot be represented), mktime returns -1.


See Also

localtime

strftime

time


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	+	+	+


modf, modfl

See Also	Example	Portability

Syntax

#include <math.h>

double modf(double x, double *ipart);

long double modfl(long double x, long double *ipart);

Description

Splits a double or long double into integer and fractional parts.

modf breaks the double x into two parts: the integer and the fraction. modf stores the integer in ipart and returns the fraction.

modfl is the long double version; it takes long double arguments and returns a long double result.

Return Value

modf and modfl return the fractional part of x.


See Also

fmod

ldexp


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
modf	+	+	+	+	+	+	+
modfl	+		+	+			+


movedata

See Also	Example	Portability

Syntax

#include <mem.h>

void movedata(unsigned srcseg, unsigned srcoff, unsigned dstseg, unsigned dstoff, size_t n);

Description

Copies n bytes.

movedata copies n bytes from the source address (srcseg:srcoff) to the destination address (dstseg:dstoff). movedata provides a memory-model independent means for moving blocks of data.

Return Value

None.


See Also

FP_OFF

memcpy

MK_FP

movmem

segread


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


movmem
movmem, _fmovmem

See Also	Examples	Portability

Syntax

#include <mem.h>

void movmem(const void *src, void *dest, unsigned length);

void _fmovmem(const void far *src, void far *dest, unsigned length);

Description

Moves a block of length bytes.

movmem moves a block of length bytes from src to dest. Even if the source and destination blocks overlap, the move direction is chosen so that the data is always moved correctly.

_fmovmem is the far version.

Return Value

None.


See Also

memcpy

memmove

movedata


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


movetext

See Also	Example	Portability

Syntax

#include <conio.h>

int movetext(int left, int top, int right, int bottom, int destleft, int desttop);

Description

Copies text onscreen from one rectangle to another.

movetext copies the contents of the onscreen rectangle defined by left, top, right, and bottom to a new rectangle of the same dimensions. The new rectangle's upper left corner is position (destleft, desttop).

All coordinates are absolute screen coordinates. Rectangles that overlap are moved correctly.

movetext is a text mode function performing direct video output.

Note:	Do not use this function for Win32s or Win32 GUI applications.

Return Value

On success, movetext returns nonzero.

On error (for example, if it failed because you gave coordinates outside the range of the current screen mode), movetext returns 0.


See Also

gettext

puttext


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+	 	 	+


_msize

See Also	Example	Portability

Syntax

#include <malloc.h>

size_t _msize(void *block);

Description

Returns the size of a heap block.

_msize returns the size of the allocated heap block whose address is block. The block must have been allocated with malloc, calloc, or realloc. The returned size can be larger than the number of bytes originally requested when the block was allocated.

Return Value

_msize returns the size of the block in bytes.


See Also

malloc

free

realloc


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

 	 	 	+	 	 	+


normvideo

See Also	Example	Portability

Syntax

#include <conio.h>

void normvideo(void);

Description

Selects normal-intensity characters.

normvideo selects normal characters by returning the text attribute (foreground and background) to the value it had when the program started.

This function does not affect any characters currently on the screen, only those displayed by functions (such as cprintf) performing direct console output functions after normvideo is called.

Note:	Do not use this function for Win32s or Win32 GUI applications.

Return Value

None.


See Also

highvideo

lowvideo

textattr

textcolor


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+	 	 	+


offsetof

Example	Portability

Syntax

#include <stddef.h>

size_t offsetof(struct_type, struct_member);

Description

Gets the byte offset to a structure member.

offsetof is available only as a macro. The argument struct_type is a struct type. struct_member is any element of the struct that can be accessed through the member selection operators or pointers.

If struct_member is a bit field, the result is undefined.

See also Chapter 2 in the Programmer's Guide for a discussion of the sizeof operator, memory allocation, and alignment of structures.

Return Value

offsetof returns the number of bytes from the start of the structure to the start of the named structure member.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


open

See Also	Example	Portability

Syntax

#include <fcntl.h>

#include<io.h>

int open(const char *path, int access [, unsigned mode]);

Description

Opens a file for reading or writing.

open opens the file specified by path, then prepares it for reading and/or writing as determined by the value of access.

To create a file in a particular mode, you can either assign to the global variable _fmode or call open with the O_CREAT and O_TRUNC options ORed with the translation mode desired.

For example, the call

   open("XMP",O_CREAT|O_TRUNC|O_BINARY,S_IREAD)

creates a binary-mode, read-only file named XMP, truncating its length to 0 bytes if it already existed.

For open, access is constructed by bitwise ORing flags from the following lists. Only one flag from the first list can be used (and one must be used); the remaining flags can be used in any logical combination.

These symbolic constants are defined in fcntl.h.

Read/Write Flags

O_RDONLY	Open for reading only.

O_WRONLY	Open for writing only.

O_RDWR	Open for reading and writing.

Other Access Flags

O_NDELAY	Not used; for UNIX compatibility.

O_APPEND	If set, the file pointer will be set to the end of the file prior to each write.

O_CREAT	If the file exists, this flag has no effect. If the file does not exist, the file is created, and the bits of mode are used to set the file attribute bits as in chmod.

O_TRUNC	If the file exists, its length is truncated to 0. The file attributes remain unchanged.

O_EXCL	Used only with O_CREAT. If the file already exists, an error is returned.

O_BINARY	Can be given to explicitly open the file in binary mode.

O_TEXT	Can be given to explicitly open the file in text mode.

If neither O_BINARY nor O_TEXT is given, the file is opened in the translation mode set by the global variable _fmode.

If the O_CREAT flag is used in constructing access, you need to supply the mode argument to open from the following symbolic constants defined in sys\stat.h.

Value Of Mode	Access Permission

S_IWRITE	Permission to write

S_IREAD	Permission to read

S_IREAD|S_IWRITE	Permission to read and write

Return Value

On success, open returns a nonnegative integer (the file handle). The file pointer, which marks the current position in the file, is set to the beginning of the file.

On error, open returns -1 and the global variable errno is set to one of the following values:

EACCES	Permission denied

EINVACC	Invalid access code

EMFILE	Too many open files

ENOENT	No such file or directory


See Also

chmod

chsize

close

creat

creatnew

creattemp

dup2

dup

fdopen

filelength

fopen

freopen

getftime

lock

lseek

_open_osfhandle

read

_rtl_creat

_rtl_open

_rtl_write

sopen

write


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


opendir

See Also	Example	Portability

Syntax

#include <dirent.h>

DIR *opendir(char *dirname);

Description

Opens a directory stream for reading.

opendir is available on POSIX-compliant UNIX systems.

The opendir function opens a directory stream for reading. The name of the directory to read is dirname. The stream is set to read the first entry in the directory.

A directory stream is represented by the DIR structure, defined in dirent.h. This structure contains no user-accessible fields. Multiple directory streams can be opened and read simultaneously. Directory entries can be created or deleted while a directory stream is being read.

Use the readdir function to read successive entries from a directory stream. Use the closedir function to remove a directory stream when it is no longer needed.

Return Value

On success, opendir returns a pointer to a directory stream that can be used in calls to readdir, rewinddir, and closedir.

On errror (If the directory cannot be opened), it returns NULL and sets the global variable errno to

ENOENT	The directory does not exist

ENOMEM	Not enough memory to allocate a DIR object


See Also

closedir

readdir

rewinddir


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


_open_osfhandle

See Also	Example	Portability

Syntax

#include <io.h>

int _open_osfhandle(long osfhandle, int flags);

Description

Associates file handles.

The _open_osfhandle function allocates a run-time file handle and sets it to point to the operating system file handle specified by osfhandle.

The value flags is a bitwise OR combination of one or more of the following manifest constants (defined in fcntl.h):

O_APPEND	Repositions the file pointer to the end of the file before every write operation.

O_RDONLY	Opens the file for reading only.

O_TEXT	Opens the file in text (translated) mode.

Return Value

On success, _open_osfhandle returns a C run-time file handle. Otherwise, it returns -1.


See Also

_get_osfhandle

open


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

 	 	 	+


outp

See Also	Example	Portability

Syntax

#include <conio.h>

int outp(unsigned portid, int value);

Description

Outputs a byte to a hardware port.

outp is a macro that writes the low byte of value to the output port specified by portid.

If outp is called when conio.h has been included, it will be treated as a macro that expands to inline code. If you don't include conio.h, or if you do include conio.h and #undef the macro outp, you'll get the outp function.

Return Value

outp returns value.


See Also

inp

inpw

outpw


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


outport, outportb

See Also	Examples	Portability

Syntax

#include <dos.h>

void outport(int portid, int value);

void outportb(int portid, unsigned char value);

Description

Outputs a word or byte to a hardware port.

outport works just like the 80x86 instruction OUT. It writes the low byte of the word given by value to the output port specified by portid and writes the high byte of the word to portid +1.

outportb is a macro that writes the byte given by value to the output port specified by portid.

If you include dos.h,, outportb will be treated as a macro that expands to inline code. If you do not include dos.h, or if you include dos.h and #undef the macro outportb, you will get the outportb function.

Return Value

None.


See Also

inport

inportb


Examples

outport

outportb


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


outpw

See Also	Example	Portability

Syntax

#include <conio.h>

unsigned outpw(unsigned portid, unsigned value);

Description

Outputs a word to a hardware port.

outpw is a macro that writes the 16-bit word given by value to the output port specified by portid. It writes the low byte of value to portid, and the high byte of the word to portid +1, using a single 16-bit OUT instruction.

If outpw is called when conio.h has been included, it will be treated as a macro that expands to inline code. If you don't include conio.h, or if you do include conio.h and #undef the macro outpw, you'll get the outpw function.

Return Value

outpw returns value.


See Also

inp

inpw

outp


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


parsfnm

Example	Portability

Syntax

#include <dos.h>

char *parsfnm(const char *cmdline, struct fcb *fcb, int opt);

Description

Parses file name.

parsfnm parses a string pointed to by cmdline for a file name. The string is normally a command line. The file name is placed in a file control block (FCB) as a drive, file name, and extension. The FCB is pointed to by fcb.

The opt parameter is the value documented for AL in the DOS parse system call. See your DOS reference manuals under system call 0x29 for a description of the parsing operations performed on the file name.

Return Value

On success, parsfnm returns a pointer to the next byte after the end of the file name.

On error (in parsing the file name), parsfnm returns null.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


_pclose

See Also	Example	Portability

Syntax

#include <stdio.h>

int _pclose(FILE * stream);

Description

Waits for piped command to complete.

_pclose closes a pipe stream created by a previous call to _popen, and then waits for the associated child command to complete.

Return Value

On success, _pclose returns the termination status of the child command. This is the same value as the termination status returned by cwait, except that the high and low order bytes of the low word are swapped.

On error, it returns -1.


See Also

_pipe

_popen


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

 	 	 	+	 	 	+


peek

See Also	Example	Portability

Syntax

#include <dos.h>

int peek(unsigned segment, unsigned offset);

Description

Returns the word at memory location specified by segment:offset.

peek returns the word at the memory location segment:offset.

If peek is called when dos.h has been included, it is treated as a macro that expands to inline code. If you don't include dos.h, or if you do include it and #undef peek, you'll get the function rather than the macro.

Return Value

peek returns the word of data stored at the memory location segment:offset.


See Also

peekb

poke


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


peekb

See Also	Example	Portability

Syntax

#include <dos.h>

char peekb(unsigned segment, unsigned offset);

Description

Returns the byte of memory specified by segment:offset.

peekb returns the byte at the memory location addressed by segment:offset.

If peekb is called when dos.h has been included, it is treated as a macro that expands to inline code. If you don't include dos.h, or if you do include it and #undef peekb, you'll get the function rather than the macro.

Return Value

peekb returns the byte of information stored at the memory location segment:offset.


See Also

peek

pokeb


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


perror

See Also	Example	Portability

Syntax

#include <stdio.h>

void perror(const char *s);

Description

Prints a system error message.

perror prints to the stderr stream (normally the console) the system error message for the last library routine that set the global variable errno.

It prints the argument s followed by a colon (:) and the message corresponding to the current value of the global variable errno and finally a new line. The convention is to pass the file name of the program as the argument string.

The array of error message strings is accessed through the global variable _sys_errlist. The global variable errno can be used as an index into the array to find the string corresponding to the error number. None of the strings include a newline character.

The global variable _sys_nerr contains the number of entries in the array.

The following messages are generated by perror:

Win 16 and Win 32 messages

Arg list too big

Attempted to remove current directory

Bad address

Bad file number

Block device required

Broken pipe

Cross-device link

Error 0

Exec format error

Executable file in use

File already exists

File too large

Illegal seek

Inappropriate I/O control operation

Input/output error

Interrupted function call

Invalid access code

Invalid argument Resource busy

Invalid dataResource temporarily unavailable

Invalid environment

Invalid format

Invalid function number

Invalid memory block address

Is a directory

Math argument

Memory arena trashed

Name too long

No child processes

No more files

No space left on device

No such device

No such device or address

No such file or directory

No such process

Not a directory

Not enough memory

Not same device

Operation not permitted

Path not found

Permission denied

Possible deadlock

Read-only file system

Resource busy

Resource temporarily unavailable

Result too large

Too many links

Too many open files

Win 32 only messages

Note:	For Win32s or Win32 GUI applications, stderr must be redirected.

Bad address

Block device required

Broken pipe

Executable file in use

File too large

Illegal seek

Inappropriate I/O control

Input/output error

Interrupted function call

Is a directory

Name too long

No child processes

No space left on device

No such device or address

No such process

Not a directory

Operation not permitted

Possible deadlock

Read-only file system

Resource busy

Resource temporarily unavailable

Too many links


See Also

clearerr

eof

freopen

_strerror

strerror


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	 	+	+	+	+


_pipe

See Also	Example	Portability

Syntax

#include <fcntl.h>

#include<io.h>

int _pipe(int *handles, unsigned int size, int mode);

Description

Creates a read/write pipe.

The _pipe function creates an anonymous pipe that can be used to pass information between processes. The pipe is opened for both reading and writing. Like a disk file, a pipe can be read from and written to, but it does not have a name or permanent storage associated with it; data written to and from the pipe exist only in a memory buffer managed by the operating system.

The read handle is returned to handles[0], and the write handle is returned to handles[1]. The program can use these handles in subsequent calls to read, write, dup, dup2, or close. When all pipe handles are closed, the pipe is destroyed.

The size of the internal pipe buffer is size. A recommended minimum value is 512 bytes.

The translation mode is specified by mode, as follows:

O_BINARY	The pipe is opened in binary mode

O_TEXT	The pipe is opened in text mode

If mode is zero, the translation mode is determined by the external variable _fmode.

Return Value

On success, _pipe returns 0 and returns the pipe handles to handles[0] and handles[1].

On error, it returns -1 and sets errno to one of the following values:

EMFILE	Too many open files

ENOMEM	Out of memory


See Also

_pclose

_popen


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

 	 	 	+	 	 	+


poke

See Also	Example	Portability

Syntax

#include <dos.h>

void poke(unsigned segment, unsigned offset, int value);

Description

Stores an integer value at a memory location given by segment:offset.

poke stores the integer value at the memory location segment:offset.

If this routine is called when dos.h has been included, it will be treated as a macro that expands to inline code. If you don't include dos.h, or if you do include it and #undef poke, you'll get the function rather than the macro.

Return Value

None.


See Also

peek

pokeb


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


pokeb

See Also	Example	Portability

Syntax

#include <dos.h>

void pokeb(unsigned segment, unsigned offset, char value);

Description

Stores a byte value at memory location segment:offset.

pokeb stores the byte value at the memory location segment:offset.

If this routine is called when dos.h has been included, it will be treated as a macro that expands to inline code. If you don't include dos.h, or if you do include it and #undef pokeb, you'll get the function rather than the macro.

Return Value

None.


See Also

peekb

poke


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


poly, polyl

Example	Portability

Syntax

#include <math.h>

double poly(double x, int degree, double coeffs[]);

long double polyl(long double x, int degree, long double coeffs[]);

Description

Generates a polynomial from arguments.

poly generates a polynomial in x, of degree degree, with coefficients coeffs[0], coeffs[1], ..., coeffs[degree]. For example, if n = 4, the generated polynomial is:

polyl is the long double version; it takes long double arguments and returns a long double result.

Return Value

poly and polyl return the value of the polynomial as evaluated for the given x.


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
poly	+	+	+	+			+
polyl	+		+	+			+


_popen

See Also	Example	Portability

Syntax

#include <stdio.h>

FILE *_popen (const char *command, const char *mode);

Description

Creates a command processor pipe.

The _popen function creates a pipe to the command processor. The command processor is executed asynchronously, and is passed the command line in command. The mode string specifies whether the pipe is connected to the command processor's standard input or output, and whether the pipe is to be opened in binary or text mode.

The mode string can take one of the following values:

Value	Description

rt	Read child command's standard output (text).

rb	Read child command's standard output (binary).

wt	Write to child command's standard input (text).

wb	Write to child command's standard input (binary).

The terminating t or b is optional; if missing, the translation mode is determined by the external variable _fmode.

Use the _pclose function to close the pipe and obtain the return code of the command.

Return Value

On success, _popen returns a FILE pointer that can be used to read the standard output of the command, or to write to the standard input of the command, depending on the mode string.

On error, it returns NULL.


See Also

_pclose

_pipe


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

 	 	 	+	 	 	+


pow, powl

See Also	Example	Portability

Syntax

#include <math.h>

double pow(double x, double y);

long double powl(long double x, long double y);

Description

Calculates x to the power of y.

powl is the long double version; it takes long double arguments and returns a long double result.

This function can be used with bcd and complex types.

Return Value

On success, pow and powl return the value calculated of x to the power of y.

Sometimes the arguments passed to these functions produce results that overflow or are incalculable. When the correct value would overflow, the functions return the value HUGE_VAL (pow) or _LHUGE_VAL (powl). Results of excessively large magnitude can cause the global variable errno to be set to

ERANGE	Result out of range

If the argument x passed to pow or powl is real and less than 0, and y is not a whole number, or you call pow(0,0), the global variable errno is set to

EDOM	Domain error

Error handling for these functions can be modified through the functions _matherr and _matherrl.


See Also

bcd

complex

exp

pow10

sqrt


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
pow	+	+	+	+	+	+	+
powl	+		+	+			+


pow10, pow10l

See Also	Example	Portability

Syntax

#include <math.h>

double pow10(int p);

long double pow10l(int p);

Description

Calculates 10 to the power of p.

pow10l is the long double version; it takes long double arguments and returns a long double result.

Return Value

On success, pow10 returns the value calculated, 10 to the power of p and pow10l returns a long double result.

The result is actually calculated to long double accuracy. All arguments are valid, although some can cause an underflow or overflow.


See Also

exp

pow


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
pow10	+	+	+	+			+
pow10l	+		+	+			+


printf

See Also	Example	Portability

Syntax

#include <stdio.h>

int printf(const char *format[, argument, ...]);

Description

Writes formatted output to stdout.

printf function:

Accepts a series of arguments

Appllies to each argument a format specifier contained in the format string *format

Outputs the formatted data (to the screen, a stream, stdout, or a string)

There must be enough arguments for the format. If there are not, the results will be unpredictable and likely disastrous.  Excess arguments (more than required  by the format) are merely ignored.

Note:	For Win32s or Win32 GUI applications, stdout must be redirected.

Return Value

On success, printf returns the number of bytes output.

On error, printf returns EOF.

More About printf

Format String

Format Specifiers

Format Specifier Conventions

Flag Characters

Input-size Modifiers

Precision Specifiers

Type Characters

Width Specifiers


See Also

cprintf

ecvt

fprintf

fread

freopen

fscanf

putc

puts

putw

scanf

sprintf

vprintf

vsprintf


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	 	+	+	+	+


printf Format String

See Also

The format string, present in each of the printf function calls, controls how each function will convert, format, and print its arguments.

Note:	There must be enough arguments for the format; if not, the results will be unpredictable and possibly disastrous. Excess arguments (more than required by the format) are ignored.

The format string is a character string that contains two types of objects:

Plain characters are copied verbatim to the output stream.

Conversion specifications fetch arguments from the argument list and apply formatting to them.

Plain characters are simply copied verbatim to the output stream.

Conversion specifications fetch arguments from the argument list and apply formatting to them.


See Also

Format Specifiers

Format Specifier Conventions

Flag Characters

Input-size Modifiers

Precision Specifiers

Type Characters

Width Specifiers

...printf functions


printf Format Specifiers

See Also

print format specifiers have the following form

% [flags] [width] [.prec] [F|N|h|l|L] type_char

Each format specifier begins with the percent character (%).

After the % come the following optional specifiers, in this order:

Optional Format String Components

These are the general aspects of output formatting controlled by the optional characters, specifiers, and modifiers in the format string:

Component	Optional/Required	What it Controls or Specifies

[flags]	(Optional)	Flag character(s)  Output justification, numeric signs, decimal points, trailing zeros, octal and hex prefixes

[width]	(Optional)	Width specifier  Minimum number of characters to print, padding with blanks or zeros

[prec]	(Optional)	Precision specifier  Maximum number of characters to print; for integers, minimum number of digits to print

[F|N|h|l|L]	(Optional)	Input size modifier  Override default size of next input argument:

N	=	near pointer

F	=	far pointer

h	=	short int

l	=	long

L	=	long double

type_char	(Required)	Conversion-type character


See Also

Format String

Format Specifier Conventions

Flag Characters

Input-size Modifiers

Precision Specifiers

Type Characters

Width Specifiers

...printf functions


printf Flag characters

See Also

They can appear in any order and combination.

Flag 	What it means

-	Left-justifies the result, pads on the right with blanks. If not given, it right-justifies the result, pads on the left with zeros or blanks.

+	Signed conversion results always begin with a plus (+) or minus (-) sign.

blank	If value is nonnegative, the output begins with a blank instead of a plus; negative values still begin with a minus.

#	Specifies that arg is to be converted using an alternate form.

Note:	Plus (+) takes precedence over blank () if both are given.


See Also

Format String

Format Specifiers

Format Specifier Conventions

Precision Specifiers

Type Characters

Width Specifiers

...printf functions


Alternate Forms for printf Conversion

See Also

If you use the # flag conversion character, it has the following effect on the argument (arg) being converted:

Conversion character	How # affects the argument

c s d iu	No effect.

0	0 is prepended to a nonzero arg.

x X	0x (or 0X) is prepended to arg.

e E f	The result always contains a decimal point even if no digits follow the point. Normally, a decimal point appears in these results only if a digit follows it.

g G	Same as e and E, except that trailing zeros are not removed.


See Also

Format String

Format Specifiers

Format Specifier Conventions

Flag Characters

Input-size Modifiers

Precision Specifiers

Type Characters

Width Specifiers

...printf functions


printf Width Specifiers

See Also

The width specifier sets the minimum field width for an output value.

Width is specified in one of two ways:

directly, through a decimal digit string

indirectly, through an asterisk (*)

If you use an asterisk for the width specifier, the next argument in the call (which must be an int) specifies the minimum output field width.

Nonexistent or small field widths do not cause truncation of a field. If the result of a conversion is wider than the field width, the field is expanded to contain the conversion result.

Width specifier	How output width is affected

n	At least n characters are printed. If the output value has less than n characters, the output is padded with blanks (right-padded if - flag given, left-padded otherwise).

0n	At least n characters are printed. If the output value has less than n characters, it is filled on the left with zeros.

*	The argument list supplies the width specifier, which must precede the actual argument being formatted.


See Also

Format String

Format Specifiers

Format Specifier Conventions

Flag Characters

Input-size Modifiers

Precision Specifiers

Type Characters

...printf functions


printf Precision Specifiers

See Also

The printf  precision specifiers set the maximum number of characters (or minimum number of integer digits) to print.

A printf precision specification always begins with a period (.) to separate it from any preceding width specifier.

Then, like [width], precision is specified in one of two ways:

directly, through a decimal digit string

indirectly, through an asterisk (*)

If you use an * for the precision specifier, the next argument in the call (treated as an int) specifies the precision.

If you use asterisks for the width or the precision, or for both, the width argument must immediately follow the specifiers, followed by the precision argument, then the argument for the data to be converted.

[.prec]	How Output Precision Is Affected

(none)	Precision set to default:

=	1 for d,i,o,u,x,X types

=	6 for e,E,f types

=	All significant digits for g,G types

=	Print to first null character for s types

=	No effect on c types

.0	For d,i,o,u,x types, precision set to defaul

for e,E,f types, no decimal point is printed.

.n	n characters or n decimal places are printed.

If the output value has more than n characters, the output might be truncated or rounded. (Whether this happens depends on the type character.)

.	The argument list supplies the precision specifier, which must precede the actual argument being formatted.

No numeric characters will be output for a field (i.e., the field will be blank) if the following conditions are all met:

you specify an explicit precision of 0

the format specifier for the field is one of the integer formats (d, i, o, u, or x)

the value to be printed is 0

How [.prec] Affects Conversion

Char Type 	Effect of [.prec] (.n) on Conversion

d	Specifies that at least n digits are printed.

i	If input argument has less than n digits,

o	output value is left-padded x with zeros.

u	If input argument has more than n digits,

x	the output value is not truncated.

X

e	Specifies that n characters are

E	printed after the decimal point, and

f	the last digit printed is rounded.

g	Specifies that at most n significant

G	digits are printed.

c	Has no effect on the output.

s	Specifies that no more than n characters are printed.


See Also

Format String

Format Specifiers

Format Specifier Conventions

Flag Characters

Input-size Modifiers

Type Characters

Width Specifiers

...printf functions


printf Conversion Type Characters
printf Conversion-Type Characters

See Also

The information in this table is based on the assumption that no flag characters, width specifiers, precision specifiers, or input-size modifiers were included in the format specifier.

Note: Certain conventions accompany some of these format specifiers.

Type Char	Expected Input	Format of output

Numerics

d	Integer	signed decimal integer

i	Integer	signed decimal integer

o	Integer	unsigned octal integer

u	Integer	unsigned decimal integer

x	Integer	unsigned hexadecimal int (with a, b, c, d, e, f)

X	Integer	unsigned hexadecimal int (with A, B, C, D, E, F)

f	Floating point	signed value of the form [-]dddd.dddd.

e	Floating point	signed value of the form [-]d.dddd or e[+/-]ddd

g	Floating point	signed value in either e or f form, based on given value and precision. Trailing zeros and the decimal point are printed if necessary.

E	Floating point	Same as e; with E for exponent.

G	Floating point	Same as g; with E for exponent if e format used

Characters

c	Character	Single character

s	String pointer	Prints characters until a null-terminator is pressed or precision is reached

%	None	Prints the % character

Pointers

n	Pointer to int	Stores (in the location pointed to by the input argument) a count of the chars written so far.

p	Pointer	Prints the input argument as a pointer; format depends on which memory model was used. It will be either XXXX:YYYY or YYYY (offset only).

Infinite floating-point numbers are printed as +INF and -INF.

An IEEE Not-A-Number is printed as +NAN or -NAN.


See Also

Format String

Format Specifiers

Format Specifier Conventions

Flag Characters

Input-size Modifiers

Precision Specifiers

Width Specifiers

...printf functions


printf Input-size Modifiers

See Also

These modifiers determine how printf functions interpret the next input argument, arg[f].

Modifier 	Type of arg  	arg is interpreted as ...

F	Pointer (p, s,	A far pointer

N	and n)  	A near pointer (Note: N can't be used with any conversion in huge model.)

h	d i o u x X	A short int

l	d i o u x X	A long int

e E f g G	A double

L	e E f g G	A long double

These modifiers affect how all the printf functions interpret the data type of the corresponding input argument arg.

Both F and N reinterpret the input variable arg. Normally, the arg for a %p, %s, or %n conversion is a pointer of the default size for the memory model.

h, l, and L override the default size of the numeric data input arguments. Neither h nor l affects character (c,s) or pointer (p,n) types.


See Also

Format String

Format Specifiers

Format Specifier Conventions

Flag Characters

Precision Specifiers

Type Characters

Width Specifiers

...printf functions


printf Format Specifier Conventions

See Also

Certain conventions accompany some of the printf format specifiers for the following conversions:

- %e or %E

- %f

- %g or %G

- %x or %X

Note:	Infinite floating point numbers are printed as +INF and -INF. An IEEE Not-a-Number is printed as +NAN or -NAN.


See Also

Format String

Format Specifiers

Flag Characters

Input-size Modifiers

Precision Specifiers

Type Characters

Width Specifiers


%e or %E Conversions

See Also

The argument is converted to match the style

[-] d.ddd...e[+/-]ddd

where:

one digit precedes the decimal point

the number of digits after the decimal point is equal to the precision.

the exponent always contains at least two digits


See Also

...printf functions


%f Conversions

See Also

The argument is converted to decimal notation in the style

[-] ddd.ddd...

where the number of digits after the decimal point is equal to the precision (if a non-zero precision was given).


See Also

...printf functions


%g or %G Conversions

See Also

The argument is printed in style e, E or f, with the precision specifying the number of significant digits.

Trailing zeros are removed from the result, and a decimal point appears only if necessary.

The argument is printed in style e or f (with some restraints) if g is the conversion character. Style e is used only if the exponent that results from the conversion is either greater than the precision or less than -4.

The argument is printed in style E if G is the conversion character.


See Also

...printf functions


%x or %X Conversions

See Also

For x conversions, the letters a, b, c, d, e, and f appear in the output.

For X conversions, the letters A, B, C, D, E, and F appear in the output.


See Also

...printf functions


...printf functions

The ...printf functions include

fprintf	sends formatted output to a stream

printf	sends formatted output to stdout

sprintf	sends formatted output to a string

vfprintf	sends formatted output to a stream, using an argument list

vprintf	sends formatted output to stdout, using an argument list

vsprintf	sends formatted output to a string, using an argument list


putc

See Also	Portability

Syntax

#include <stdio.h>

int putc(int c, FILE *stream);

Description

Outputs a character to a stream.

putc is a macro that outputs the character c to the stream given by stream.

Return Value

On success, putc returns the character printed, c.

On error, putc returns EOF.

See Also

fprintf

fputc

fputchar

fputs

fwrite

getc

getchar

printf

putch

putchar

putw

vprintf


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


putch

See Also	Example	Portability

Syntax

#include <conio.h>

int putch(int c);

Description

Outputs character to screen.

putch outputs the character c to the current text window. It is a text mode function performing direct video output to the console. putch does not translate linefeed characters (\n) into carriage-return/linefeed pairs.

The string is written either directly to screen memory or by way of a BIOS call, depending on the value of the global variable _directvideo.

Note:	This function should not be used in Win32s or Win32 GUI applications.

Return Value

On success, putch returns the character printed, c. On error, it returns EOF.


See Also

cprintf

cputs

getch

getche

putc

putchar


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


putchar

See Also	Example	Portability

Syntax

#include <stdio.h>

int putchar(int c);

Description

putchar(c) is a macro defined to be putc(c, stdout).

Note:	For Win32s or Win32 GUI applications, stdout must be redirected.

Return Value

On success, putchar returns the character c. On error, putchar returns EOF.


See Also

fputchar

getc

getchar

printf

putc

putch

puts

putw

freopen

vprintf


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+ 	+	+	+	+	+


putenv

See Also	Example	Portability

Syntax

#include <stdlib.h>

int putenv(const char *name);

Description

Adds string to current environment.

putenv accepts the string name and adds it to the environment of the current process. For example,

   putenv("PATH=C:\\BC");

putenv can also be used to modify an existing name. On DOS and OS/2, name must be uppercase. On other systems, name can be either uppercase or lowercase. name must not include the equal sign (=). You can set a variable to an empty value by specifying an empty string on the right side of the '=' sign.

putenv can be used only to modify the current program's _environment. Once the program ends, the old _environment is restored. The _environment of the current process is passed to child processes, including any changes made by putenv.

Note that the string given to putenv must be static or global. Unpredictable results will occur if a local or dynamic string given to putenv is used after the string memory is released.

Return Value

On success, putenv returns 0; on failure, -1.


See Also

getenv


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


puts

See Also	Example	Portability

Syntax

#include <stdio.h>

int puts(const char *s);

Description

Outputs a string to stdout.

puts copies the null-terminated string s to the standard output stream stdout and appends a newline character.

Note:	For Win32s or Win32 GUI applications, stdout must be redirected.

Return Value

On successful completion, puts returns a nonnegative value. Otherwise, it returns a value of EOF.


See Also

cputs

fputs

gets

printf

putchar

freopen


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	 	+


puttext

See Also	Example	Portability

Syntax

#include <conio.h>

int puttext(int left, int top, int right, int bottom, void *source);

Description

Copies text from memory to the text mode screen.

puttext writes the contents of the memory area pointed to by source out to the onscreen rectangle defined by left, top, right, and bottom.

All coordinates are absolute screen coordinates, not window-relative. The upper left corner is (1,1).

puttext places the contents of a memory area into the defined rectangle sequentially from left to right and top to bottom.

Each position onscreen takes 2 bytes of memory: The first byte is the character in the cell, and the second is the cell's video attribute. The space required for a rectangle w columns wide by h rows high is defined as

bytes = (h rows) x (w columns) x 2

puttext is a text mode function performing direct video output.

Note:	This function should not be used in Win32s or Win32 GUI applications.

Return Value

puttext returns a nonzero value if the operation succeeds; it returns 0 if it fails (for example, if you gave coordinates outside the range of the current screen mode).


See Also

gettext

movetext

window


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+	 	 	+


putw

See Also	Example	Portability

Syntax

#include <stdio.h>

int putw(int w, FILE *stream);

Description

Puts an integer on a stream.

putw outputs the integer w to the given stream. putw neither expects nor causes special alignment in the file.

Return Value

On success, putw returns the integer w. On error, putw returns EOF. Because EOF is a legitimate integer, use ferror to detect errors with putw.


See Also

getw

printf


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


qsort

See Also	Example	Portability

Syntax

#include <stdlib.h>

void qsort(void *base, size_t nelem, size_t width, int (_USERENTRY *fcmp)(const void *, const void *));

Description

Sorts using the quicksort algorithm.

qsort is an implementation of the "median of three" variant of the quicksort algorithm. qsort sorts the entries in a table by repeatedly calling the user-defined comparison function pointed to by fcmp.

base points to the base (0th element) of the table to be sorted.

nelem is the number of entries in the table.

width is the size of each entry in the table, in bytes.

fcmp, the comparison function, must be used with the _USERENTRY calling convention.

fcmp accepts two arguments, elem1 and elem2, each a pointer to an entry in the table. The comparison function compares each of the pointed-to items (*elem1 and *elem2), and returns an integer based on the result of the comparison.

*elem1  < *elem2        fcmp returns an integer < 0

*elem1 == *elem2       fcmp returns 0

*elem1  > *elem2        fcmp returns an integer > 0

In the comparison, the less-than symbol (<) means the left element should appear before the right element in the final, sorted sequence. Similarly, the greater-than (>) symbol means the left element should appear after the right element in the final, sorted sequence.

Return Value

None.


See Also

bsearch

lsearch


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


raise

See Also	Example	Portability

Syntax

#include <signal.h>

int raise(int sig);

Description

Sends a software signal to the executing program.

raise sends a signal of type sig to the program. If the program has installed a signal handler for the signal type specified by sig, that handler will be executed. If no handler has been installed, the default action for that signal type will be taken.

The signal types currently defined in signal.h are noted here:

Signal	Description

SIGABRT	Abnormal termination

SIGFPE	Bad floating-point operation

SIGILL	Illegal instruction

SIGINT	Ctrl-C interrupt

SIGSEGV	Invalid access to storage

SIGTERM	Request for program termination

SIGUSR1	User-defined signal

SIGUSR2	User-defined signal

SIGUSR3	User-defined signal

SIGBREAK	Ctrl-Break interrupt

Note:	SIGABRT isn't generated by Borland C++ during normal operation. It can, however, be generated by abort, raise, or unhandled exceptions.

Return Value

On succes, raise returns 0.

On error it returns nonzero.


See Also

abort

signal


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


rand

See Also	Example	Portability

Syntax

#include <stdlib.h>

int rand(void);

Description

Random number generator.

rand uses a multiplicative congruential random number generator with period 2 to the 32nd power to return successive pseudorandom numbers in the range from 0 to RAND_MAX. The symbolic constant RAND_MAX is defined in stdlib.h.

Return Value

rand returns the generated pseudorandom number.


See Also

random

randomize

srand


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


random

See Also	Example	Portability

Syntax

#include <stdlib.h>

int random(int num);

Description

Random number generator.

random returns a random number between 0 and (num-1). random(num) is a macro defined in stdlib.h. Both num and the random number returned are integers.

Return Value

random returns a number between 0 and (num-1).


See Also

rand

randomize

srand


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


randomize

See Also	Example	Portability

Syntax

#include <stdlib.h>

#include <time.h>

void randomize(void);

Description

Initializes random number generator.

randomize initializes the random number generator with a random value.

Return Value

None.


See Also

rand

random

srand


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


read

See Also	Example	Portability

Syntax

#include <io.h>

int read(int handle, void *buf, unsigned len);

Description

Reads from file.

read attempts to read len bytes from the file associated with handle into the buffer pointed to by buf.

For a file opened in text mode, read removes carriage returns and reports end-of-file when it reaches a Ctrl-Z.

The file handle handle is obtained from a creat, open, dup, or dup2 call.

On disk files, read begins reading at the current file pointer. When the reading is complete, it increments the file pointer by the number of bytes read. On devices, the bytes are read directly from the device.

The maximum number of bytes that read can read is UINT_MAX -1, because UINT_MAX is the same as -1, the error return indicator. UINT_MAX is defined in limits.h.

Return Value

On successful completion, read returns an integer indicating the number of bytes placed in the buffer. If the file was opened in text mode, read does not count carriage returns or Ctrl-Z characters in the number of bytes read.

On end-of-file, read returns 0. On error, read returns -1 and sets the global variable errno to one of the following values:

EACCES	Permission denied

EBADF	Bad file number


See Also

open

_rtl_read

write


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


readdir

See Also	Example	Portability

Syntax

#include <dirent.h>

struct dirent *readdir(DIR *dirp);

Description

Reads the current entry from a directory stream.

readdir is available on POSIX-compliant UNIX systems.

The readdir function reads the current directory entry in the directory stream pointed to by dirp. The directory stream is advanced to the next entry.

The readdir function returns a pointer to a dirent structure that is overwritten by each call to the function on the same directory stream. The structure is not overwritten by a readdir call on a different directory stream.

The dirent structure corresponds to a single directory entry. It is defined in dirent.h, and contains (in addition to other non-accessible members) the following member:

   char  d_name[];

where d_name is an array of characters containing the null-terminated file name for the current directory entry. The size of the array is indeterminate; use strlen to determine the length of the file name.

All valid directory entries are returned, including subdirectories, "." and ".." entries, system files, hidden files, and volume labels. Unused or deleted directory entries are skipped.

A directory entry can be created or deleted while a directory stream is being read, but readdir might or might not return the affected directory entry. Rewinding the directory with rewinddir or reopening it with opendir ensures that readdir will reflect the current state of the directory.

Return Value

On success, readdir returns a pointer to the current directory entry for the directory stream.

If the end of the directory has been reached, or dirp does not refer to an open directory stream, readdir returns NULL.


See Also

closedir

opendir

rewinddir


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


realloc

See Also	Example	Portability

Syntax

#include <stdlib.h>

void *realloc(void *block, size_t size);

Description

Reallocates main memory.

realloc attempts to shrink or expand the previously allocated block to size bytes. If size is zero, the memory block is freed and NULL is returned. The block argument points to a memory block previously obtained by calling malloc, calloc, or realloc. If block is a NULL pointer, realloc works just like malloc.

realloc adjusts the size of the allocated block to size, copying the contents to a new location if necessary.

Return Value

realloc returns the address of the reallocated block, which can be different than the address of the original block.

If the block cannot be reallocated, realloc returns NULL.

If the value of size is 0, the memory block is freed and realloc returns NULL.


See Also

calloc

farrealloc

free

malloc


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


remove

See Also	Example	Portability

Syntax

#include <stdio.h>

int remove(const char *filename);

Description

Removes a file.

remove deletes the file specified by filename. It is a macro that simply translates its call to a call to unlink. If your file is open, be sure to close it before removing it.

The filename string can include a full path.

Return Value

On successful completion, remove returns 0. On error, it returns -1, and the global variable errno is set to one of the following values:

EACCES	Permission denied

ENOENT	No such file or directory


See Also

unlink


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


rename

Example	Portability

Syntax

#include <stdio.h>

int rename(const char *oldname, const char *newname);

Description

Renames a file.

rename changes the name of a file from oldname to newname. If a drive specifier is given in newname, the specifier must be the same as that given in oldname.

Directories in oldname and newname need not be the same, so rename can be used to move a file from one directory to another. Wildcards are not allowed.

This function will fail (EACCES) if either file is currently open in any process.

Return Value

On success, rename returns 0.

On error (if the file cannot be renamed), it returns  -1 and the global variable errno is set to one of the following values:

EACCES	Permission denied: filename already exists or has an invalid path

ENOENT	No such file or directory

ENOTSAM	Not same device


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	+	+	+


rewind

See Also	Example	Portability

Syntax

#include <stdio.h>

void rewind(FILE *stream);

Description

Repositions a file pointer to the beginning of a stream.

rewind(stream) is equivalent to fseek(stream, 0L, SEEK_SET), except that rewind clears the end-of-file and error indicators, while fseek clears the end-of-file indicator only.

After rewind, the next operation on an update file can be either input or output.

Return Value

None.


See Also

fopen

fseek

ftell


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


rewinddir

See Also	Example	Portability

Syntax

#include <dirent.h>

void rewinddir(DIR *dirp);

Description

Resets a directory stream to the first entry.

rewinddir is available on POSIX-compliant UNIX systems.

The rewinddir function repositions the directory stream dirp at the first entry in the directory. It also ensures that the directory stream accurately reflects any directory entries that might have been created or deleted since the last opendir or rewinddir on that directory stream.

Return Value

None.


See Also

closedir

opendir

readdir


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


rmdir

See Also	Example	Portability

Syntax

#include <dir.h>

int rmdir(const char *path);

Description

Removes a directory.

rmdir deletes the directory whose path is given by path. The directory named by path

must be empty

must not be the current working directory

must not be the root directory

Return Value

rmdir returns 0 if the directory is successfully deleted. A return value of -1 indicates an error, and the global variable errno is set to one of the following values:

EACCES	Permission denied

ENOENT	Path or file function not found


See Also

chdir

getcurdir

getcwd

mkdir


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


rmtmp

See Also	Example	Portability

Syntax

#include <stdio.h>

int rmtmp(void);

Description

Removes temporary files.

The rmtmp function closes and deletes all open temporary file streams, which were previously created with tmpfile. The current directory must the same as when the files were created, or the files will not be deleted.

Return Value

rmtmp returns the total number of temporary files it closed and deleted.


See Also

tmpfile


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


_rotl, _rotr

See Also	Example	Portability

Syntax

#include <stdlib.h>

unsigned short _rotl(unsigned short value, int count);

unsigned short _rotr(unsigned short value, int count);

Description

 Bit-rotates an unsigned short integer value to the left or right.

_rotl rotates the given value to the left count bits.

_rotr rotates the given value to the right count bits.

Return Value

_rotl, and _rotr return the rotated integer:

_rotl returns the value of value left-rotated count bits.

_rotr returns the value of value right-rotated count bits.


See Also

_crotl

_crotr

_lrotl

_lrotr


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


_rtl_chmod

See Also	Example	Portability

Syntax

#include <dos.h>

#include <io.h>

int _rtl_chmod(const char *path, int func [, int attrib]);

Description

Gets or sets file attributes.

Note:	This function replaces _chmod which is obsolete

_rtl_chmod can either fetch or set file attributes. If func is 0, _rtl_chmod returns the current attributes for the file. If func is 1, the attribute is set to attrib.

attrib can be one of the following symbolic constants (defined in dos.h):

FA_RDONLY	Read-only attribute

FA_HIDDEN	Hidden file

FA_SYSTEM	System file

FA_LABEL	Volume label

FA_DIREC	Directory

FA_ARCH	Archive

Return Value

On success, _rtl_chmod returns the file attribute word.

On error, it returns a value of -1 and sets the global variable errno to one of the following values:

ENOENT	Path or filename not found

EACCES	Permission denied


See Also

chmod

_rtl_creat


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+


_rtl_close

See Also	Example	Portability

Syntax

#include <io.h>

int _rtl_close(int handle);

Description

Closes a file.

Note:	This function replaces _close which is obsolete

The _rtl_close function closes the file associated with handle, a file handle obtained from a call to creat, creatnew, creattemp, dup, dup2, open, _rtl_creat, or _rtl_open.

It does not write a Ctrl-Z character at the end of the file. If you want to terminate the file with a Ctrl-Z, you must explicitly output one.

Return Value

On success, _rtl_close returns 0.

On error (if it fails because handle is not the handle of a valid, open file), _rtl_close returns a value of -1 and the global variable errno is set to

EBADF	Bad file number


See Also

chsize

close

creat

creatnew

dup

fclose

_rtl_creat

_rtl_open

sopen


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+


_rtl_creat

Syntax

#include <dos.h>

#include <io.h>

int _rtl_creat(const char *pathc int attrib);

Description

Creates a new file or overwrites an existing one.

Note:	This function replaces _creat which is obsolete

_rtl_creat opens the file specified by path. The file is always opened in binary mode. Upon successful file creation, the file pointer is set to the beginning of the file. The file is opened for both reading and writing.

If the file already exists its size is reset to 0. (This is essentially the same as deleting the file and creating a new file with the same name.)

The attrib argument is an ORed combination of one or more of the following constants (defined in dos.h):

FA_RDONLY	Read-only attribute

FA_HIDDEN	Hidden file

FA_SYSTEM	System file

Return Value

On success, _rtl_creat returns the new file handle (a non-negative integer).

On error, it returns -1 and sets the global variable errno to one of the following values:

EACCES	Permission denied

EMFILE	Too many open files

ENOENT	Path or file name not found


See Also

chsize

close

creat

creatnew

creattemp

_rtl_chmod

_rtl_close


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+


_rtl_heapwalk

See Also	Example	Portability

Syntax

#include <malloc.h>

int _rtl_heapwalk(_HEAPINFO *hi);

Description

Inspects the heap node by node.

Note:	This function replaces _heapwalk which is obsolete.

_rtl_heapwalk assumes the heap is correct. Use _heapchk to verify the heap before using _rtl_heapwalk. _HEAPOK is returned with the last block on the heap. _HEAPEND will be returned on the next call to _rtl_heapwalk.

_rtl_heapwalk receives a pointer to a structure of type _HEAPINFO (declared in malloc.h).

For the first call to _rtl_heapwalk, set the hi._pentry field to NULL. _rtl_heapwalk returns with hi._pentry containing the address of the first block.

hi._size	holds the size of the block in bytes.

hi._useflag	is a flag that is set to _USEDENTRY if the block is currently in use. If the block is free, hi._useflag is set to _FREEENTRY.

Return Value

This function returns one of the following values:

_HEAPBADNODE	A corrupted heap block has been found

_HEAPBADPTR	The _pentry field does not point to a valid heap block

_HEAPEMPTY	No heap exists

_HEAPEND	The end of the heap has been reached

_HEAPOK	The _heapinfo block contains valid information about the next heap block


See Also

_heapchk

_heapset


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

 	 	 	+	 	 	+


_rtl_open

See Also	Example	Portability

Syntax

#include <fcntl.h>

int _rtl_open(const char *filename, int oflags);

Description

Opens a file for reading or writing.

Note:	This function replaces _open which is obsolete.

_rtl_open opens the file specified by filename, then prepares it for reading or writing, as determined by the value of oflags. The file is always opened in binary mode.

oflags uses the flags from the following two lists. Only one flag from List 1 can be used (and one must be used) and the flags in List 2 can be used in any logical combination.

List 1: Read/write flags

O_RDONLY	Open for reading.

O_WRONLY	Open for writing.

O_RDWR	Open for reading and writing.

The following additional values can be included in oflags (using an OR operation):

List 2: Other access flags

O_NOINHERIT	The file is not passed to child programs.

SH_COMPAT	Allow other opens with SH_COMPAT. The call will fail if the file has already been opened in any other shared mode.

SH_DENYRW	Only the current handle can have access to the file.

SH_DENWR	Allow only reads from any other open to the file.

SH_DENYRD	Allow only writes from any other open to the file.

SH_DENYNO	Allow other shared opens to the file, but not other SH_COMPAT opens.

Note:	These symbolic constants are defined in fcntl.h and share.h.

Only one of the SH_DENYxx values can be included in a single _rtl_open routine. These file-sharing attributes are in addition to any locking performed on the files.

The maximum number of simultaneously open files is defined by HANDLE_MAX.

Return Value

On success:_rtl_open returns a non-negative integer (the file handle). The file pointer, which marks the current position in the file, is set to the beginning of the file.

On error, it returns -1 and sets the global variable errno to one of the following values:

EACCES	Permission denied

EINVACC	Invalid access code

EMFILE	Too many open files

ENOENT	Path or file not found


See Also

open

_rtl_read

sopen


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+


_rtl_read

See Also	Example	Portability

Syntax

#include <dos.h>

int _rtl_read(int handle, void *buf, unsigned *len);

Description

Reads from file.

Note:	This function replaces _read which is obsolete.

This function reads len bytes from the file associated with handle into the buffer pointed to by buf. When a file is opened in text mode, _rtl_read does not remove carriage returns.

The argument handle is a file handle obtained from a creat, open, dup, or dup2 call.

On disk files, _rtl_read begins reading at the current file pointer. When the reading is complete, it increments the file pointer by the number of bytes read. On devices, the bytes are read directly from the device.

The maximum number of bytes it can read is UINT_MAX -1 (because UINT_MAX is the same as -1, the error return indicator). UINT_MAX is defined in limits.h.

Return Value

On success, _rtl_read returns either

a positive integer, indicating the number of bytes placed in the buffer

zero,  indicating end-of-file

On error, it returns -1 and sets the global variable errno to one of the following values:

EACCES	Permission denied

EBADF	Bad file number


See Also

read

_rtl_open

_rtl_write


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+


_rtl_write

See Also	Example	Portability

Syntax

#include <io.h>

int _rtl_write(int handle void *buf unsigned len);

Description

Writes to a file.

Note:	This function replaces _write which is obsolete.

_rtl_write attempts to write len bytes from the buffer pointed to by buf to the file associated with handle.

The maximum number of bytes that _rtl_write can write is UINT_MAX -1 (because UINT_MAX is the same as -1), which is the error return indicator for _rtl_write. UINT_MAX is defined in limits.h. _rtl_write does not translate a linefeed character (LF) to a CR/LF pair because all its files are binary files.

If the number of bytes actually written is less than that requested the condition should be considered an error and probably indicates a full disk.

For disk files, writing always proceeds from the current file pointer. On devices, bytes are directly sent to the device.

For files opened with the O_APPEND option, the file pointer is not positioned to EOF before writing the data.

Return Value

On success, _rtl_write returns number of bytes written.

On error, it returns -1 and sets the global variable errno to one of the following values:

EACCES	Permission denied

EBADF	Bad file number


See Also

lseek

_rtl_read

write


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+


scanf

See Also	Example	Portability

Syntax

#include <stdio.h>

int scanf(const char *format[, address, ...]);

Description

Scans and formats input from the stdin stream.

To use this I/O function in a Windows application, see EasyWin.

Note:	For Win32s or Win32 GUI applications, stdin must be redirected.

The scanf function:

scans a series of input fields one character at a time

formats each field according to a corresponding format specifier passed  in the format string *format.

vsscanf	scans and formats input from a string, using an argument list

There must be one format specifier and address for each input field.

scanf might stop scanning a particular field before it reaches the normal end-of-field (whitespace) character, or it might terminate entirely. For details about why this might happen, see When ...scanf Stops Scanning.

Warning:	scanf often leads to unexpected results if you diverge from an expected pattern. You must provide information that tells scanf how to synchronize at the end of a line.

The combination of gets or fgets followed by sscanf is safe and easy, and therefore recommended over scanf.

Return Value

On success, scanf returns the number of input fields successfully scanned, converted, and stored. The return value does not include scanned fields that were not stored.

On error:

if no fields were stored, scanf returns 0.

if scanf attempts to read at end-of-file or at end-of-string, it returns EOF.

More About scanf

Argument-type Modifiers

Assignment Suppression

Format Specifiers

Format Specifier Conventions

Format String

Input Fields

Pointer-size Modifiers

Type Characters

Width Specifiers

When ...scanf Functions Stop Scanning


See Also

atof

cscanf

fscanf

freopen

getc

printf

sscanf

vfscanf

vscanf

vsscanf


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	 	+	+	+	+


The ...scanf Format String
The scanf Format String

See Also

The format string controls how each ...scanf function scans, converts, and stores its input fields.

The format string is a character string that contains three types of objects:

whitespace characters

non-whitespace characters

format specifiers

Whitespace Characters

The whitespace characters are blank, tab (\t) or newline (\n).

If a ...scanf function encounters a whitespace character in the format string, it reads, but does not store, all consecutive whitespace characters up to the next non-whitespace character in the input.

Trailing whitespace is left unread (including a newline), unless explicitly matched in the format string.

Non-whitespace Characters

The non-whitespace characters are all other ASCII characters except the percent sign (%).

If a ...scanf function encounters a non-whitespace character in the format string, it will read, but not store, a matching non-whitespace character.

Format Specifiers

The format specifiers direct the ...scanf functions to read and convert characters from the input field into specific types of values, then store them in the locations given by the address arguments.

Warning:	Each format specifier must have an address argument. If there are more format specs than addresses, the results are unpredictable and likely disastrous.

Excess address arguments (more than required by the format) are ignored.


See Also

Argument-type Modifiers

Assignment Suppression

Format Specifier Conventions

Format Specifiers

Input Fields

Pointer-size Modifiers

Type Characters

Width Specifiers

When ...scanf Functions Stop Scanning

...scanf functions


...scanf Format Specifiers
scanf Format Specifiers

See Also

In ...scanf format strings, format specifiers have the following form:

% [*] [width] [F|N] [h|l|L] type_char

Each format specifier begins with the percent character (%).

After the % come the following, in this order:

Component 	Optional/Required	What It Is/Does

[*]	(Optional) 	Assignment-suppression character. Suppresses assignment of the next input field.

[width]	(Optional) 	Width specifier.  pecifies maximum number of characters to read; fewer characters might be read if the ...scanf function encounters  a whitespace or unconvertible character.

[F|N]	(Optional) 	Pointer size modifier. Overrides default size of address argument:

N	= 	near pointer

F	= 	far pointer

[h|l|L]	(Optional) 	Argument-type modifier. Overrides default type of address argument:

h	=	short int

l	=	long int, if type_char specifies integer conversion

l	=	double, if type_char specifies floating-point conversion

L	=	long double, (valid only with floating-point conversion)

type_char	(Required)	Type character


See Also

Format Specifier Conventions

Format String

Input Fields

When ...scanf Functions Stop Scanning

...scanf functions


...scanf Type Characters
Type Characters

See Also

The information in this table is based on the assumption that no optional characters, specifiers, or modifiers (*, width, or size) were included in the format specifier.

Note: Certain conventions accompany some of these format specifiers.

Type 	Expected input  	Type of argument

Numerics

d	Decimal integer  	Pointer to int (int *arg)

D	Decimal integer  	Pointer to long (long *arg)

e,E	Floating point  	Pointer to float (float *arg)

f	Floating point  	Pointer to float (float *arg)

g,G	Floating point  	Pointer to float (float *arg)

o	Octal integer  	Pointer to int (int *arg)

O	Octal integer  	Pointer to long (long *arg)

i	Decimal, octal, or 	Pointer to int (int *arg)

hexadecimal integer

I	Decimal, octal, or	Pointer to long (long *arg)

hexadecimal integer

u	Unsigned decimal integer	Pointer to unsigned int (unsigned int *arg)

U	Unsigned decimal integer	Pointer to unsigned long (unsigned long *arg)

x	Hexadecimal integer 	Pointer to int (int *arg)

X	Hexadecimal integer 	Pointer to int (int *arg)

Characters

s	Character string  	Pointer to array of chars (char arg[])

c	Character	Pointer to char (char *arg) if a field width is given along with the c-type character  (such as %5c)

 	 	Pointer to array of W chars (char arg[W])

%	% character	No conversion done; the % is stored

Pointers

n	Pointer to int (int *arg). The number  of characters read successfully up to %n is stored in this int.

p	Hexadecimal form  	Pointer to an object (far* or near*)

YYYY:ZZZZ or ZZZZ  	%p conversions default to the pointer size native to the memory model


See Also

Argument-type Modifiers

Assignment Suppression

Format Specifier Conventions

Format Specifiers

Format String

Input Fields

Pointer-size Modifiers

Width Specifiers

When ...scanf Functions Stop Scanning

...scanf functions


Input Fields for ...scanf Functions
Input Fields for Scanf Functions

See Also

In a ...scanf function, any one of the following is an input field:

all characters up to (but not including) the next whitespace character

all characters up to the first one that can't be converted under the current  format specifier (such as an 8 or 9 under  octal format)

up to n characters, where n is the  specified field width


See Also

Argument-type Modifiers

Assignment Suppression

Format Specifier Conventions

Format Specifiers

Format String

Pointer-size Modifiers

Type Characters

Width Specifiers

When ...scanf Functions Stop Scanning

...scanf functions


...scanf Assignment-suppression Character
Assignment-suppression Character

See Also

The assignment-suppression character is an asterisk (*), not to be confused with the C indirection (pointer) operator.

If the asterisk follows the percent sign (%) in a format specifier, the next input field will be scanned but it won't be assigned to the next address argument.

The suppressed input data is assumed to be of the type specified by the type character that follows the asterisk character.


See Also

Argument-type Modifiers

Format Specifier Conventions

Format Specifiers

Format String

Input Fields

Pointer-size Modifiers

Type Characters

Width Specifiers

When ...scanf Functions Stop Scanning

...scanf functions


...scanf Width Specifiers
Width Specifiers

See Also

The width specifier (n), a decimal integer, controls the maximum number of characters to be read from the current input field.

Up to n characters are read, converted, and stored in the current address argument.

If the input field contains fewer than n characters, the ...scanf function reads all the characters in the field, then proceeds with the next field and format specifier.

The success of literal matches and suppressed assignments is not directly determinable.

If the ...scanf function encounters a whitespace or non-convertible character before it reads "width" characters, it:

reads, converts, and stores the characters read so far, then

attends to the next format specifier.

A non-convertible character is one that can't be converted according to the given format (8 or 9 when the format is octal, J or K when the format is hexadecimal or decimal, etc.).


See Also

Argument-type Modifiers

Assignment Suppression

Format Specifier Conventions

Format Specifiers

Format String

Input Fields

Pointer-size Modifiers

Type Characters

When ...scanf Functions Stop Scanning

...scanf functions


...scanf Pointer-size and Argument-type Modifiers
Pointer-size and Argument-type Modifiers

See Also

These modifiers affect how ...scanf functions interpret the corresponding address argument arg[f].

Pointer-size Modifiers

Pointer-size modifiers override the default or declared size of arg.

Modifier	arg Interpreted As...

F	Far pointer

N	Near pointer (Can't be used with any conversion in huge model)

Argument-type Modifiers

Argument-type modifiers indicate which type of the following input data is to be used (h = short, l = long, L = long double).

The input data is converted to the specified version, and the arg for that input data should point to an object of corresponding size.

Modifier	For This Type 	Convert Input to...

h	d i o u x	short int; store in short object

D I O U X 	(No effect)

e f c s n p 	(No effect)

l	d i o u x	long int; store in long object

e f g	double; store in double object

D I O U X	(No effect)

c s n p	(No effect)

L	e f g	long double; store in long double object

(all others)  	(No effect)


See Also

Assignment Suppression

Format Specifier Conventions

Format Specifiers

Format String

Input Fields

Type Characters

Width Specifiers

When ...scanf Functions Stop Scanning

...scanf functions


...scanf Format Specifier Conventions
Format Specifier Conventions

See Also

Certain conventions accompany some of the ...scanf format specifiers for the following conversions:

single character (%c)

character array (%[W]c)

string (%s)

floating-point (%e, %E, %f, %g, and %G)

unsigned (%d, %i, %o, %x, %D, %I, %O, %X, %c, %n)

search sets(%[...], %[^...])


See Also

Argument-type Modifiers

Assignment Suppression

Format Specifiers

Format String

Input Fields

Pointer-size Modifiers

Type Characters

Width Specifiers

When ...scanf Functions Stop Scanning

...scanf functions


Single Character Conversion (%c)

See Also

This specification reads the next character, including a whitespace character.

To skip one whitespace character and read the next non-whitespace character, use %1s.


See Also

...scanf functions


Character Array Conversion (%[W]c)

[W] = width specification

The address argument is a pointer to an array of characters (char arg[W]).

The array consists of W elements.


String Conversion (%s)

See Also

The address argument is a pointer to an array of characters (char arg[]).

The array size must be at least (n+1) bytes, where n = the length of string s (in characters).

A space or newline character terminates the input field.

A null terminator is automatically appended to the string and stored as the last element in the array.


See Also

...scanf functions


Floating-point Conversions (%e, %E, %f, %g, and %G)

See Also

Floating-point numbers in the input field must conform to the following generic format:

[+/-] ddddddddd [.] dddd [E|e] [+/-] ddd

where [item] indicates that item is optional, and ddd represents digits (decimal, octal, or hexadecimal).

In addition, +INF, -INF, +NAN, and -NAN are recognized as floating-point numbers. The sign (+ or -) and capitalization are required.


See Also

...scanf functions


Unsigned Conversions (%d, %i, %o, %x, %D, %I, %O, %X, %c, and %n)

See Also

A pointer to unsigned character, unsigned integer, or unsigned long can be used in any conversion where a pointer to a character, integer, or long is allowed.


See Also

...scanf functions


Search Set Conversion (%[search_set])

See Also	Examples

The set of characters surrounded by brackets can be substituted for the s-type character.

The address argument is a pointer to an array of characters (char arg[]).

These brackets surround a set of characters that define a search set of possible characters making up the string (the input field).

If the first character in the brackets is a caret (^), the search set is inverted to include all ASCII characters except those between the brackets.

(Normally, a caret will be included in the inverted search set unless explicitly listed somewhere after the first caret.)

The input field is a string not delimited by whitespace. ...scanf reads the corresponding input field up to the first character it reaches that does not appear in the search set (or in the inverted search set).

Rules covering search set ranges

1.	The character prior to the hyphen (-) must be lexically less than the one after it.

2.	The hyphen must not be the first or last character in the set. (If it is first or last, it is considered to just be the hyphen character, not a range definer.)

3.	The characters on either side of the hyphen must be the ends of the range and not part of some other range.


See Also

...scanf functions


Examples

%[abcd]	Searches the input field for any  of the characters a, b, c, and d

%[^abcd]	Searches the input field for any  characters except a, b, c, and d

You can also use a range facility shortcut [<first>-<last>] to define a range of letters or numerals in the search set.

Examples

To catch all decimal digits, you could define the search set with the explicit search set:  %[0123456789] or with the range shortcut:  %[0-9]

To catch alphanumeric characters, you could use the following shortcuts:

%[A-Z]  	Catches all uppercase letters

%[0-9A-Za-z]	Catches all decimal digits and all letters

%[A-FT-Z] 	Catches all uppercase letters from A through F and from T through Z.


When ...scanf Functions Stop Scanning

See Also

A ...scanf function might stop scanning a particular input field before reaching the normal field-end character (whitespace), or it might terminate entirely.

Stop and Skip to Next Input Field

...scanf functions stop scanning and storing the current input field and proceed to the next one if any of the following occurs:

An assignment-suppression character (*) appears after the % in the format specifier. The current input field is scanned but not stored.

width characters have been read.

The next character read can't be converted under the current format (for example, an A when the format is decimal).

The next character in the input field does not appear in the search set (or does appear in an inverted search set).

When scanf stops scanning the current input field for one of these reasons, it assumes that the next character is unread and is either

the first character of the following input field, or

the first character in a subsequent read operation on the input.

Terminate

...scanf functions will terminate under the following circumstances:

1.	The next character in the input field conflicts with a corresponding non-whitespace character in the format string.

2.	The next character in the input field is EOF.

3.	The format string has been exhausted.

If a character sequence that is not part of a format specifier occurs in the format string, it must match the current sequence of characters in the input field.

...scanf functions will scan but not store the matched characters.

When a conflicting character occurs, it remains in the input field as if the ...scanf function never read it.


See Also

Argument-type Modifiers

Assignment Suppression

Format Specifier Conventions

Format Specifiers

Format String

Input Fields

Pointer-size Modifiers

Type Characters

Width Specifiers

...scanf functions


...scanf functions

The ..scanf functions include

fscanf	scans and formats input from a stream

scanf	scans and formats input from stdin

sscanf	scans and formats input from a string

vfscanf	scans and formats input from a stream, using an argument list

vscanf	scans and formats input from stdin using an argument list

vsscanf	scans and formats input from a string, using an argument list


_searchenv

See Also	Example	Portability

Syntax

#include <stdlib.h>

char *_searchenv(const char *file, const char *varname, char *buf);

Description

Searches an environment path for a file.

_searchenv attempts to locate file, searching along the path specified by the operating system _environment variable varname. Typical environment variables that contain paths are PATH, LIB, and INCLUDE.

_searchenv searches for the file in the current directory of the current drive first. If the file is not found there, the environment variable varname is fetched, and each directory in the path it specifies is searched in turn until the file is found, or the path is exhausted.

When the file is located, the full path name is stored in the buffer pointed to by buf. This string can be used in a call to access the file (for example, with fopen or exec...). The buffer is assumed to be large enough to store any possible file name. If the file cannot be successfully located, an empty string (consisting of only a null character) will be stored at buf.

Return Value

None.


See Also

_dos_findfirst

_dos_findnext

exec...

spawn...

system


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


searchpath

See Also	Example	Portability

Syntax

#include <dir.h>

char *searchpath(const char *file);

Description

Searches the operating system path for a file.

searchpath attempts to locate file, searching along the operating system path, which is the PATH=... string in the environment. A pointer to the complete path-name string is returned as the function value.

searchpath searches for the file in the current directory of the current drive first. If the file is not found there, the PATH environment variable is fetched, and each directory in the path is searched in turn until the file is found, or the path is exhausted.

When the file is located, a string is returned containing the full path name. This string can be used in a call to access the file (for example, with fopen or exec...).

The string returned is located in a static buffer and is overwritten on each subsequent call to searchpath.

Return Value

searchpath returns a pointer to a file name string if the file is successfully located; otherwise, searchpath returns null.


See Also

exec...

findfirst

findnext

spawn...

system


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


_searchstr

See Also	Example	Portability

Syntax

#include <stdlib.h>

void _searchstr(const char *file, const char *ipath, char *buf);

Description

Searches a list of directories for a file.

_searchstr attempts to locate file, searching along the path specified by the string ipath.

_searchstr searches for the file in the current directory of the current drive first. If the file is not found there, each directory in ipath is searched in turn until the file is found, or the path is exhausted. The directories in ipath must be separated by semicolons.

When the file is located, the full path name is stored in the buffer pointed by by buf. This string can be used in a call to access the file (for example, with fopen or exec...). The buffer is assumed to be large enough to store any possible file name. The constant _MAX_PATH defined in stdlib.h, is the size of the largest file name. If the file cannot be successfully located, an empty string (consisting of only a null character) will be stored at buf.

Return Value

None.


See Also

_searchenv


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


segread

See Also	Example	Portability

Syntax

#include <dos.h>

void segread(struct SREGS *segp);

Description

Reads segment registers.

segread places the current values of the segment registers into the structure pointed to by segp.

This call is intended for use with intdosx and int86x.

Return Value

None.


See Also

FP_OFF

int86

int86x

intdos

intdosx

MK_FP

movedata


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


setbuf

See Also	Example	Portability

Syntax

#include <stdio.h>

void setbuf(FILE *stream, char *buf);

Description

Assigns buffering to a stream.

setbuf causes the buffer buf to be used for I/O buffering instead of an automatically allocated buffer. It is used after stream has been opened.

If buf is null, I/O will be unbuffered; otherwise, it will be fully buffered. The buffer must be BUFSIZ bytes long (specified in stdio.h).

stdin and stdout are unbuffered if they are not redirected; otherwise, they are fully buffered. setbuf can be used to change the buffering style used.

Unbuffered means that characters written to a stream are immediately output to the file or device, while buffered means that the characters are accumulated and written as a block.

setbuf produces unpredictable results unless it is called immediately after opening stream or after a call to fseek. Calling setbuf after stream has been unbuffered is legal and will not cause problems.

A common cause for error is to allocate the buffer as an automatic (local) variable and then fail to close the file before returning from the function where the buffer was declared.

Return Value

None.


See Also

fflush

fopen

fseek

setvbuf


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


setcbrk

See Also	Example	Portability

Syntax

#include <dos.h>

int setcbrk(int cbrkvalue);

Description

Sets control-break setting.

setcbrk uses the DOS system call 0x33 to turn control-break checking on or off.

value = 0	Turns checking off (check only during I/O to console, printer, or communications devices).

value = 1	Turns checking on (check at every system call).

Return Value

setcbrk returns cbrkvalue, the value passed.


See Also

getcbrk


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+


_setcursortype

Example	Portability

Syntax

#include <conio.h>

void _setcursortype(int cur_t);

Description

Selects cursor appearance.

Sets the cursor type to

_NOCURSOR	Turns off the cursor

_NORMALCURSOR	Normal underscore cursor

_SOLIDCURSOR	Solid block cursor

Note:	Do not use this function for Win32s or Win32 GUI applications.

Return Value

None.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+	 	 	+


setdta

See Also	Example	Portability

Syntax

#include <dos.h>

void setdta(char far *dta);

Description

Sets disk-transfer address.

setdta changes the current setting of the DOS disk-transfer address (DTA) to the value given by dta.

Return Value

None.


See Also

getdta


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+ 	 	+


setjmp

See Also	Example	Portability

Syntax

#include <setjmp.h>

int setjmp(jmp_buf jmpb);

Description

Sets up for nonlocal goto.

setjmp captures the complete task state in jmpb and returns 0.

A later call to longjmp with jmpb restores the captured task state and returns in such a way that setjmp appears to have returned with the value val.

A task state includes

Win 16 	Win 32

All segment registers	No segment registers are saved

CS, DS, ES, SS

Register variables	Register variables

DI and SI	EBX, EDI, ESI

Stack pointer SP	Stack pointer ESP

Frame pointer BP	Frame pointer EBP

Flags	Flags are not saved

A task state is complete enough that setjmp can be used to implement co-routines.

setjmp must be called before longjmp. The routine that calls setjmp and sets up jmpb must still be active and cannot have returned before the longjmp is called. If it has returned, the results are unpredictable.

setjmp is useful for dealing with errors and exceptions encountered in a low-level subroutine of a program.

DOS Users

You cannot use setjmp and longjmp for implementing co-routines if your program is overlaid. Normally, setjmp and longjmp save and restore all the registers needed for co-routines, but the overlay manager needs to keep track of stack contents and assumes there is only one stack. When you implement co-routines there are usually either two stacks or two partitions of one stack, and the overlay manager will not track them properly.

You can have background tasks that run with their own stacks or sections of stack, but you must ensure that the background tasks do not invoke any overlaid code, and you must not use the overlay versions of setjmp or longjmp to switch to and from background. When you avoid using overlay code or support routines, the existence of the background stacks does not disturb the overlay manager.

Return Value

setjmp returns 0 when it is initially called. If the return is from a call to longjmp, setjmp returns a nonzero value (as in the example).


See Also

longjmp

signal


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


setlocale

See Also	Example	Portability

Syntax

#include <locale.h>

char *setlocale(int category, const char *locale);

Description

Selects or queries a locale.

Borland C++ supports the following locales at present:

Module	Locale supported

de_DE	German

fr_FR	French

en_GB	English (Great Britain)

en_US	English (United States)

Note:	Future releases of Borland C++ will increase the number of locales supported.

For each locale, the following character sets are supported:

DOS437	English

DOS850	Multilingual (Latin I)

WIN1252	Windows, Multilingual

For a description of DOS character sets, see MS-DOS User's Guide and Reference. See also MS Windows 3.1 Programmer's Reference, Volume 4 for a discussion of the WIN1252 character set.

The possible values for the category argument are as follows:

Value	Affect

LC_ALL	Affects all the following categories

LC_COLLATE	Affects strcoll and strxfrm

LC_CTYPE	Affects single-byte character handling functions. The mbstowcs and mbtowc functions are not affected.

LC_MONETARY	Affects monetary formatting by the localeconv function

LC_NUMERIC	Affects the decimal point of non-monetary data formatting. This includes the printf family of functions, and the information returned by localeconv.

LC_TIME	Affects strftime

The locale argument is a pointer to the name of the locale or named locale category. Passing a NULL pointer returns the current locale in effect. Passing a pointer that points to a null string requests setlocale to look for environment variables to determine which locale to set. The locale names are case sensitive.

Note:	The LOCALE.BLL file is installed in BC4\BIN directory.

If you specify a locale other than the default C locale, setlocale tries to access the locale library file named LOCALE.BLL to obtain the locale data. This file is located using the following strategies:

1. Searching the directory where the application's executable resides.

2. Searching in the current default directory.

3. Accessing the "PATH" environment variable and searching in each of the specified directories.

If the locale library is not found, setlocale terminates.

When setlocale is unable to honor a locale request, the preexisting locale in effect is unchanged and a null pointer is returned.

If the locale argument is a NULL pointer, the locale string for the category is returned. If category is LC_ALL, a complete locale string is returned. The structure of the complete locale string consists of the names of all the categories in the current locale concatenated and separated by semicolons. This string can be used as the locale parameter when calling setlocale with LC_ALL. This will reinstate all the locale categories that are named in the complete locale string, and allows saving and restoring of locale states. If the complete locale string is used with a single category, for example, LC_TIME, only that category will be restored from the locale string.

ANSI C states that if an empty string "" is used as the locale parameter an implementation defined locale is used. setlocale has been implemented to look for corresponding _environment variables in this instance as POSIX suggests.

If the _environment variable LC_ALL exists, the category will be set according to this variable. If the variable does not exist, the _environment variable that has the same name as the requested category is looked for and the category is set accordingly.

If none of the above are satisfied, the _environment variable named LANG is used. Otherwise, setlocale fails and returns a NULL pointer.

To take advantage of dynamically loadable locales in your application, define _ _USELOCALES_ _ for each module. If _ _USELOCALES_ _ is not defined, all locale-sensitive functions and macros will work only with the default C locale.

If a NULL pointer is used as the argument for the locale parameter, setlocale returns a string that specifies the current locale in effect. If the category parameter specifies a single category, such as LC_COLLATE, the string pointed to will be the name of that category. If LC_ALL is used as the category parameter then the string pointed to will be a full locale string that will indicate the name of each category in effect.

    .

    .

    .

localenameptr = setlocale( LC_COLLATE, NULL );

if (localenameptr)

   printf( "%s\n", localenameptr );

    .

    .

    .

The output here will be one of the module names together with the specified code page. For example, the output could be fr_FR.DOS850@dbase.

    .

    .

    .

localenameptr = setlocale( LC_ALL, NULL );

if (localenameptr)

   printf( "%s\n", localenameptr );

    .

    .

    .

An example of the output here could be the following:

   fr_FR.DOS850@dbase;fr_FR.DOS850;fr_FR.DOS850;fr_FR.DOS850;

   fr_FR.DOS850;fr_FR.DOS850;;

Each category in this full string is delimited by a semicolon. This string can be copied and saved by an application and then used again to restore the same locale categories at another time. Each delimited name corresponds to the locale category constants defined in locale.h. Therefore, the first name is the name of the LC_COLLATE category, the second is the LC_CTYPE category, and so on. Any other categories named in the locale.h header file are reserved for future implementation.

Here are some examples of setting locales by using setlocale:

Set all default categories for the specified French locale:

   setlocale( LC_ALL, "fr_FR.DOS850" );

Note:	The default collation is named dbase. Therefore, whether you specify dbase or nothing at all, you get the same collation. However, dbase might not be the default in future releases.

Set French locale to named collation dbase:

   setlocale( LC_COLLATE, "fr_FR.DOS850@dbase" )

When a category is loaded from the locale library, the default category is the one that will be loaded unless a modifier name is used. For example:

   setlocale( LC_COLLATE, "fr_FR.DOS850" )

causes the default LC_COLLATE category to be loaded. It might or might not have a specific name.

   setlocale( LC_COLLATE, "fr_FR.DOS850@dbase" )

specifies that the LC_COLLATE category named dbase to be loaded. This might or might not be the default.

setlocale updates the lconv locale structure when a request has been fulfilled.

When an application exits, any allocated memory used for the locale object is deallocated.

Return value

If selection is successful, setlocale returns a pointer to a string that is associated with the selected category (or possibly all categories) for the new locale.

On failure, a NULL pointer is returned and the locale is unchanged. All other possible returns are discussed in the Remarks section above.


See Also

localeconv


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	+	+	+


setmem

See Also	Example	Portability

Syntax

#include <mem.h>

void setmem(void *dest, unsigned length, char value);

Description

Assigns a value to a range of memory.

setmem sets a block of length bytes, pointed to by dest, to the byte value.

Return Value

None.


See Also

memset

strset


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


setmode

See Also	Example	Portability

Syntax

#include <fcntl.h>

int setmode(int handle, int amode);

Description

Sets mode of an open file.

setmode sets the mode of the open file associated with handle to either binary or text. The argument amode must have a value of either O_BINARY or O_TEXT, never both. (These symbolic constants are defined in fcntl.h.)

Return Value

setmode returns the previous translation mode if successful. On error it returns -1 and sets the global variable errno to

EINVAL	Invalid argument


See Also

creat

open

_rtl_creat

_rtl_open


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


setvbuf

See Also	Example	Portability

Syntax

#include <stdio.h>

int setvbuf(FILE *stream, char *buf, int type, size_t size);

Description

Assigns buffering to a stream.

setvbuf causes the buffer buf to be used for I/O buffering instead of an automatically allocated buffer. It is used after the given stream is opened.

If buf is null, a buffer will be allocated using malloc; the buffer will use size as the amount allocated. The buffer will be automatically freed on close. The size parameter specifies the buffer size and must be greater than zero.

The parameter size is limited by the constant UINT_MAX as defined in limits.h.

stdin and stdout are unbuffered if they are not redirected; otherwise, they are fully buffered. Unbuffered means that characters written to a stream are immediately output to the file or device, while buffered means that the characters are accumulated and written as a block.

The type parameter is one of the following:

_IOFBF	fully buffered file.  When a buffer is empty, the next input operation will attempt to fill the entire buffer. On output, the buffer will be completely filled before any data is written to the file.

_IOLBF	line buffered file.  When a buffer is empty, the next input operation will still attempt to fill the entire buffer. On output, however, the buffer will be flushed whenever a newline character is written to the file.

_IONBF	unbuffered file.  The buf and size parameters are ignored. Each input operation will read directly from the file, and each output operation will immediately write the data to the file.

A common cause for error is to allocate the buffer as an automatic (local) variable and then fail to close the file before returning from the function where the buffer was declared.

Return Value

On success, setvbuf returns 0.

On error (if an invalid value is given for type or size, or if there is not enough space to allocate a buffer), it returns nonzero.


See Also

fflush

fopen

setbuf


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


setverify

See Also	Example	Portability

Syntax

#include <dos.h>

void setverify(int value);

Description

Sets the state of the verify flag in the operating system.

setverify sets the current state of the verify flag to value, which can be either 0 (off) or 1 (on).

The verify flag controls output to the disk. When verify is off, writes are not verified; when verify is on, all disk writes are verified to ensure proper writing of the data.

Return Value

None.


See Also

getverify


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	 	 	 	+


signal

See Also	Example	Portability

Syntax

#include <signal.h>

void (_USERENTRY *signal(int sig, void (_USERENTRY *func)

                                  (int sig[, int subcode])))(int);

Description

Specifies signal-handling actions.

signal determines how receipt of signal number sig will subsequently be treated. You can install a user-specified handler routine (specified by the argument func) or use one of the two predefined handlers, SIG_DFL and SIG_IGN, in signal.h. The function func must be used with the _USERENTRY calling convention.

A routine that catches a signal (such as a floating point) also clears the signal. To continue to receive signals, a signal handler must be reinstalled by calling signal again.

Function Pointer	Description

SIG_DFL	Terminates the program

SIG_ERR	Indicates an error return from signal

SIG_IGN	Ignore this type signal

The following table shows signal types and their defaults:

Signal Type	Description

SIGBREAK	Keyboard must be in raw mode.

SIGABRT 	Abnormal termination. Default action is equivalent to calling _exit(3).

SIGFPE	Arithmetic error caused by division by 0, invalid operation, and the like. Default action is equivalent to calling _exit(1).

SIGILL	Illegal operation. Default action is equivalent to calling _exit(1).

SIGINT	Ctrl-C interrupt. Default action is to do an INT 23h.

SIGSEGV	Illegal storage access. Default action is equivalent to calling _exit(1).

SIGTERM	Request for program termination. Default action is equivalent to calling _exit(1).

SIGUSR1, SIGUSR2, SIGUSR3

User-defined signals (available only in Win32) can be generated only by calling raise. Default action is to ignore the signal

signal.h defines a type called sig_atomic_t, the largest integer type the processor can load or store atomically in the presence of asynchronous interrupts (for the 8086 family, this is a 16-bit word, for 80386 and higher number processors, it is a 32-bit word -- a Borland C++ integer).

When a signal is generated by the raise function or by an external event, the following two things happen:

If a user-specified handler has been installed for the signal, the action for that signal type is set to SIG_DFL.

The user-specified function is called with the signal type as the parameter.

User-specified handler functions can terminate by a return or by a call to abort, _exit, exit, or longjmp. If your handler function is expected to continue to receive and handle more signals, you must have the handler function call signal again.

Borland C++ implements an extension to ANSI C when the signal type is SIGFPE, SIGSEGV, or SIGILL. The user-specified handler function is called with one or two extra parameters. If SIGFPE, SIGSEGV, or SIGILL has been raised as the result of an explicit call to the raise function, the user-specified handler is called with one extra parameter, an integer specifying that the handler is being explicitly invoked. The explicit activation values for SIGFPE, SIGSEGV and SIGILL are as follows

Note:	Declarations of these types are defined in float.h.

SIGSEGV signal	Meaning

SIGFPE	FPE_EXPLICITGEN

SIGSEGV	SEGV_EXPLICITGEN

SIGILL	ILL_EXPLICITGEN

If SIGFPE is raised because of a floating-point exception, the user handler is called with one extra parameter that specifies the FPE_xxx type of the signal. If SIGSEGV, SIGILL, or the integer-related variants of SIGFPE signals (FPE_INTOVFLOW or FPE_INTDIV0) are raised as the result of a processor exception, the user handler is called with two extra parameters:

1.	The SIGFPE, SIGSEGV, or SIGILL exception type (see float.h for all these types). This first parameter is the usual ANSI signal type.

2.	An integer pointer into the stack of the interrupt handler that called the user-specified handler. This pointer points to a list of the processor registers saved when the exception occurred. The registers are in the same order as the parameters to an interrupt function; that is, BP, DI, SI, DS, ES, DX, CX, BX, AX, IP, CS, FLAGS. To have a register value changed when the handler returns, change one of the locations in this list.

For example, to have a new SI value on return, do something like this:

   *((int*)list_pointer + 2) = new_SI_value;

In this way, the handler can examine and make any adjustments to the registers that you want.

The following SIGFPE-type signals can occur (or be generated). They correspond to the exceptions that the 8087 family is capable of detecting, as well as the "INTEGER DIVIDE BY ZERO" and the "INTERRUPT ON OVERFLOW" on the main CPU. (The declarations for these are in float.h.)

SIGFPE signal	Meaning

FPE_INTOVFLOW	INTO executed with OF flag set

FPE_INTDIV0	Integer divide by zero

FPE_INVALID	Invalid operation

FPE_ZERODIVIDE	Division by zero

FPE_OVERFLOW	Numeric overflow

FPE_UNDERFLOW 	Numeric underflow

FPE_INEXACT 	Precision

FPE_EXPLICITGEN	User program executed raise(SIGFPE)

FPE_STACKFAULT	Floating-point stack overflow or underflow

FPE_STACKFAULT	Stack overflow

The FPE_INTOVFLOW and FPE_INTDIV0 signals are generated by integer operations, and the others are generated by floating-point operations. Whether the floating-point exceptions are generated depends on the coprocessor control word, which can be modified with _control87. Denormal exceptions are handled by Borland C++ and not passed to a signal handler.

The following SIGSEGV-type signals can occur:

SEGV_BOUND	Bound constraint exception

SEGV_EXPLICITGEN	raise(SIGSEGV) was executed

The 8088 and 8086 processors don't have a bound instruction. The 186, 286, 386, and NEC V series processors do have this instruction. So, on the 8088 and 8086 processors, the SEGV_BOUND type of SIGSEGV signal won't occur. Borland C++ doesn't generate bound instructions, but they can be used in inline code and separately compiled assembler routines that are linked in.

The following SIGILL-type signals can occur:

ILL_EXECUTION	Illegal operation attempted

ILL_EXPLICITGEN	raise(SIGILL) was executed

The 8088, 8086, NEC V20, and NEC V30 processors do not have an illegal operation exception. The 186, 286, 386, NEC V40, and NEC V50 processors do have this exception type. On 8088, 8086, NEC V20, and NEC V30 processors, the ILL_EXECUTION type of SIGILL won't occur.

When the signal type is SIGFPE, SIGSEGV, or SIGILL, a return from a signal handler is generally not advisable if the state of the 8087 is corrupt, the results of an integer division are wrong, an operation that shouldn't have overflowed did, a bound instruction failed, or an illegal operation was attempted. The only time a return is reasonable is when the handler alters the registers so that a reasonable return context exists or the signal type indicates that the signal was generated explicitly (for example, FPE_EXPLICITGEN, SEGV_EXPLICITGEN, or ILL_EXPLICITGEN). Generally in this case you would print an error message and terminate the program using  _exit, exit, or abort. If a return is executed under any other conditions, the program's action will probably be unpredictable.

Note:	Take special care when using the signal function in a multithread program. The SIGINT, SIGTERM, and SIGBREAK signals can be used only by the main thread (thread one) in a non-Win32 application. When one of these signals occurs, the currently executing thread is suspended, and control transfers to the signal handler (if any) set up by thread one. Other signals can be handled by any thread.

A signal handler should not use C++ run-time library functions, because a semaphore deadlock might occur. Instead, the handler should simply set a flag or post a semaphore, and return immediately.

Return Value

On success, signal returns a pointer to the previous handler routine for the specified signal type.

On error, signal returns SIG_ERR, and the external variable errno is set to EINVAL.


See Also

abort

_c_exit

_cexit

_control87

ctrlbrk

exit

longjmp

raise

setjmp


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


sin, sinl

See Also	Example	Portability

Syntax

#include <math.h>

double sin(double x);

long double sinl(long double x);

Description

Calculates sine.

sin computes the sine of the input value. Angles are specified in radians.

sinl is the long double version; it takes a long double argument and returns a long double result. Error handling for these functions can be modified through the functions _matherr and _matherrl.

This function can be used with bcd and complex types.

Return Value

sin and sinl return the sine of the input value.


See Also

acos

asin

atan

atan2

bcd

complex

cos

tan


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
sin	+	+	+	+	+		+
sinl	+		+	+			+


sinh, sinhl

See Also	Example	Portability

Syntax

#include <math.h>

double sinh(double x);

long double sinhl(long double x);

Description

Calculates hyperbolic sine.

sinh computes the hyperbolic sine, [image].

sinl is the long double version; it takes a long double argument and returns a long double result. Error handling for sinh and sinhl can be modified through the functions _matherr and _matherrl.

This function can be used with bcd and complex types.

Return Value

sinh and sinhl return the hyperbolic sine of x.

When the correct value overflows, these functions return the value HUGE_VAL (sinh) or _LHUGE_VAL (sinhl) of appropriate sign. Also, the global variable errno is set to ERANGE.


See Also

acos

asin

atan

atan2

bcd

complex

cos

cosh

sin

tan

tanh


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
sinh	+	+	+	+	+		+
sinhl	+		+	+			+


sleep

Example	Portability

Syntax

#include <dos.h>

void sleep(unsigned seconds);

Description

Suspends execution for an interval (seconds).

With a call to sleep, the current program is suspended from execution for the number of seconds specified by the argument seconds. The interval is accurate only to the nearest hundredth of a second or to the accuracy of the operating system clock, whichever is less accurate.

Return Value

None.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	 	+	 	 	+


sopen

See Also	Example	Portability

Syntax

#include <fcntl.h>

#include <sys\stat.h>

#include <share.h>

#include <io.h>

int sopen(char *path, int access, int shflag[, int mode]);

Description

Opens a shared file.

sopen opens the file given by path and prepares it for shared reading or writing, as determined by access, shflag, and mode.

For sopen, access is constructed by ORing flags bitwise from the following lists:

Read/write flags

You can use only one of the following flags:

O_RDONLY	Open for reading only.

O_WRONLY	Open for writing only.

O_RDWR	Open for reading and writing.

Other access flags

You can use any logical combination of the following flags:

O_NDELAY	Not used; for UNIX compatibility.

O_APPEND	If set, the file pointer is set to the end of the file prior to each write.

O_CREA	If the file exists, this flag has no effect. If the file does not exist, the file is created, and the bits of mode are used to set the file attribute bits as in chmod.

O_TRUNC	If the file exists, its length is truncated to 0. The file attributes remain unchanged.

O_EXCL	Used only with O_CREAT. If the file already exists, an error is returned.

O_BINARY	This flag can be given to explicitly open the file in binary mode.

O_TEXT	This flag can be given to explicitly open the file in text mode.

O_NOINHERIT	The file is not passed to child programs.

Note:	These O_... symbolic constants are defined in fcntl.h.

If neither O_BINARY nor O_TEXT is given, the file is opened in the translation mode set by the global variable _fmode.

If the O_CREAT flag is used in constructing access, you need to supply the mode argument to sopen from the following symbolic constants defined in sys\stat.h.

Value of mode	Access permission

S_IWRITE 	Permission to write

S_IREAD 	Permission to read

S_IREAD|S_IWRITE	Permission to read/write

shflag specifies the type of file-sharing allowed on the file path. Symbolic constants for shflag are defined in share.h.

Value of shflag	What it does

SH_COMPAT 	Sets compatibility mode.

SH_DENYRW 	Denies read/write access

SH_DENYWR 	Denies write access

SH_DENYRD 	Denies read access

SH_DENYNONE	Permits read/write access

SH_DENYNO 	Permits read/write access

Return Value

On success, sopen returns a nonnegative integer (the file handle), and the file pointer (that marks the current position in the file) is set to the beginning of the file.

On error, it returns -1, and the global variable errno is set to

EACCES	ermission denied

EINVACC	nvalid access code

EMFILE	oo many open files

ENOENT	Path or file function not found


See Also

chmod

close

creat

lock

lseek

open

_rtl_open

unlock

umask


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


spawnl, spawnle, spawnlp, spawnlpe, spawnv, spawnve, spawnvp, spawnvpe

See Also	Examples	Portability

Syntax

#include <process.h>

#include <stdio.h>

int spawnl(int mode, char *path, char *arg0, arg1, ..., argn, NULL);

int spawnle(int mode, char *path, char *arg0, arg1, ..., argn, NULL, char *envp[]);

int spawnlp(int mode, char *path, char *arg0, arg1, ..., argn, NULL);

int spawnlpe(int mode, char *path, char *arg0, arg1, ..., argn, NULL, char *envp[]);

int spawnv(int mode, char *path, char *argv[]);

int spawnve(int mode, char *path, char *argv[], char *envp[]);

int spawnvp(int mode, char *path, char *argv[]);

int spawnvpe(int mode, char *path, char *argv[], char *envp[]);

Note:	In spawnle, spawnlpe, spawnv, spawnve, spawnvp, and spawnvpe, the last string must be NULL.

Description

The functions in the spawn... family create and run (execute) other files, known as child processes. There must be sufficient memory available for loading and executing a child process.

The value of mode determines what action the calling function (the parent process) takes after the spawn... call. The possible values of mode are

P_WAIT	Puts parent process on hold until child process completes execution.

P_NOWAIT	Continues to run parent process while child process runs. The child process ID is returned, so that the parent can wait for completion using cwait or wait. This mode is currently not available for 16-bit Windows or 16-bit DOS; using it generates an error value.

P_NOWAITO	Identical to P_NOWAIT except that the child process ID isn't saved by the operating system, so the parent process can't wait for it using cwait or wait.

P_DETACH	Identical to P_NOWAITO, except that the child process is executed in the background with no access to the keyboard or the display.

P_OVERLAY	Overlays child process in memory location formerly occupied by parent. Same as an exec... call.

path is the file name of the called child process. The spawn... function calls search for path using the standard operating system search algorithm:

If there is no extension or no period, they search for an exact file name. If the file is not found, they search for files first with the extension EXE, then COM, and finally BAT.

If an extension is given, they search only for the exact file name.

If only a period is given, they search only for the file name with no extension.

If path does not contain an explicit directory, spawn... functions that have the p suffix search the current directory, then the directories set with the operating system PATH environment variable.

The suffixes p, l, and v, and e added to the spawn... "family name" specify that the named function operates with certain capabilities.

p	The function searches for the file in those directories specified by the PATH environment variable. Without the p suffix, the function searches only the current working directory.

l	The argument pointers arg0, arg1, ..., argn are passed as separate arguments. Typically, the l suffix is used when you know in advance the number of arguments to be passed.

v	The argument pointers argv[0], ..., arg[n] are passed as an array of pointers. Typically, the v suffix is used when a variable number of arguments is to be passed.

e	The argument envp can be passed to the child process, letting you alter the environment for the child process. Without the e suffix, child processes inherit the environment of the parent process.

Each function in the spawn... family must have one of the two argument-specifying suffixes (either l or v). The path search and environment inheritance suffixes (p and e) are optional.

For example:

spawnl takes separate arguments, searches only the current directory for the child, and passes on the parent's environment to the child.

spawnvpe takes an array of argument pointers, incorporates PATH in its search for the child process, and accepts the envp argument for altering the child's environment.

The spawn... functions must pass at least one argument to the child process (arg0 or argv[0]). This argument is, by convention, a copy of path. (Using a different value for this 0   argument won't produce an error.) If you want to pass an empty argument list to the child process, then arg0 or argv[0] must be NULL.

Under DOS 3.x, path is available for the child process; under earlier versions, the child process cannot use the passed value of the 0   argument (arg0 or argv[0]).

When the l suffix is used, arg0 usually points to path, and arg1, ...., argn point to character strings that form the new list of arguments. A mandatory null following argn marks the end of the list.

When the e suffix is used, you pass a list of new environment settings through the argument envp. This environment argument is an array of character pointers. Each element points to a null-terminated character string of the form

envvar = value

where envvar is the name of an environment variable, and value is the string value to which envvar is set. The last element in envp[] is null. When envp is null, the child inherits the parents' environment settings.

The combined length of arg0 + arg1 + ... + argn (or of argv[0] + argv[1] + ... + argv[n]), including space characters that separate the arguments, must be less than 260 bytes for Windows (128 for DOS). Null-terminators are not counted.

When a spawn... function call is made, any open files remain open in the child process.

Return Value

On a success, the spawn... functions, where mode is P_WAIT, return the child process' exit status (0 for a normal termination). If the child specifically calls exit with a nonzero argument, its exit status can be set to a nonzero value.

If mode is P_NOWAIT or P_NOWAITO, the spawn functions return the process ID of the child process. This ID can be passed to cwait.

On error, the spawn... functions return -1, and the global variable errno is set to one of the following values:

E2BIG	Arg list too long

EINVAL	Invalid argument

ENOENT	Path or file name not found

ENOEXEC	Exec format error

ENOMEM	Not enough memory


See Also

abort

atexit

_c_exit

_cexit

cwait

_exit

exit

exec...

_fpreset

searchpath

system

wait


Examples

spawnl

spawnle

spawnlp

spawnlpe

spawnv

spawnve

spawnvp

spawnvpe


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+	 	 	+


_splitpath

See Also	Example	Portability

Syntax

#include <stdlib.h>

void _splitpath(const char *path, char *drive, char *dir, char *name, char *ext);

Description

Splits a full path name into its components.

_splitpath takes a file's full path name (path) as a string in the form

  X:\DIR\SUBDIR\NAME.EXT

and splits path into its four components. It then stores those components in the strings pointed to by drive, dir, name, and ext. (All five components must be passed, but any of them can be a null, which means the corresponding component will be parsed but not stored.) The maximum sizes for these strings are given by the constants _MAX_DRIVE, _MAX_DIR, _MAX_PATH, _MAX_FNAME, and _MAX_EXT (defined in stdlib.h), and each size includes space for the null-terminator. These constants are defined in stdlib.h.

Constant	String

_MAX_PATH	path

_MAX_DRIVE	drive; includes colon (:)

_MAX_DIR	dir; includes leading and trailing backslashes (\)

_MAX_FNAME	name

_MAX_EXT	ext; includes leading dot (.)

_splitpath assumes that there is enough space to store each non-null component.

When _splitpath splits path, it treats the punctuation as follows:

drive includes the colon (C:, A:, and so on).

dir includes the leading and trailing backslashes (\BC\include\, \source\, and so on).

name includes the file name.

ext includes the dot preceding the extension (.C, .EXE, and so on).

_makepath and _splitpath are invertible; if you split a given path with _splitpath, then merge the resultant components with _makepath, you end up with path.

Return Value

None.


See Also

_fullpath

_makepath


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


sprintf

See Also	Example	Portability

Syntax

#include <stdio.h>

int sprintf(char *buffer, const char *format[, argument, ...]);

Description

Writes formatted output to a string.

Note:	For details on format specifiers, see printf.

sprintf accepts a series of arguments, applies to each a format specifier contained in the format string pointed to by format, and outputs the formatted data to a string.

sprintf applies the first format specifier to the first argument, the second to the second, and so on. There must be the same number of format specifiers as arguments.

Return Value

On success, sprintf returns the number of bytes output. The return value does not include the terminating null byte in the count.

On error, sprintf returns EOF.


See Also

fprintf

printf


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


sqrt, sqrtl

See Also	Example	Portability

Syntax

#include <math.h>

double sqrt(double x);

long double sqrtl(long double x);

Description

Calculates the positive square root.

sqrt calculates the positive square root of the argument x.

sqrtl is the long double version; it takes a long double argument and returns a long double result. Error handling for these functions can be modified through the functions _matherr and _matherrl.

This function can be used with bcd and complex types.

Return Value

On success, sqrt and sqrtl return the value calculated, the square root of x. If x is real and positive, the result is positive. If x is real and negative, the global variable errno is set to

EDOM	Domain error


See Also

bcd

complex

exp

log

pow


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
sqrt	+	+	+	+	+		+
sqrtl	+		+	+			+


srand

See Also	Example	Portability

Syntax

#include <stdlib.h>

void srand(unsigned seed);

Description

Initializes random number generator.

The random number generator is reinitialized by calling srand with an argument value of 1. It can be set to a new starting point by calling srand with a given seed number.

Return Value

None.


See Also

rand

random

randomize


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


sscanf

See Also	Example	Portability

Syntax

#include <stdio.h>

int sscanf(const char *buffer, const char *format[, address, ...]);

Description

Scans and formats input from a string.

Note:	For details on format specifiers, see scanf.

sscanf scans a series of input fields, one character at a time, reading from a string. Then each field is formatted according to a format specifier passed to sscanf in the format string pointed to by format. Finally, sscanf stores the formatted input at an address passed to it as an argument following format. There must be the same number of format specifiers and addresses as there are input fields.

sscanf might stop scanning a particular field before it reaches the normal end-of-field (whitespace) character, or it might terminate entirely, for a number of reasons. See scanf for a discussion of possible causes.

Return Value

On success, sscanf returns the number of input fields successfully scanned, converted, and stored; the return value does not include scanned fields that were not stored.

If sscanf attempts to read at end-of-string, it returns EOF.

On error (If no fields were stored), it returns 0.


See Also

fscanf

scanf


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


stackavail

See Also	Example	Portability

Syntax

#include <malloc.h>

size_t stackavail(void);

Description

Gets the amount of available stack memory.

stackavail returns the number of bytes available on the stack. This is the amount of dynamic memory that alloca can access.

Return Value

stackavail returns a size_t value indicating the number of bytes available.


See Also

alloca


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


_status87

Example	Portability

Syntax

#include <float.h>

unsigned int _status87(void);

Description

Gets floating-point status.

_status87 gets the floating-point status word, which is a combination of the 80x87 status word and other conditions detected by the 80x87 exception handler.

Return Value

The bits in the return value give the floating-point status. See float.h for a complete definition of the bits returned by _status87.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


stime

See Also	Example	Portability

Syntax

#include <time.h>

int stime(time_t *tp);

Description

Sets system date and time.

stime sets the system time and date. tp points to the value of the time as measured in seconds from 00:00:00 GMT, January 1, 1970.

Return Value

stime returns a value of 0.


See Also

asctime

ftime

gettime

gmtime

localtime

time

tzset


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	 	 	 	+


stpcpy

See Also	Example	Portability

Syntax

#include <string.h>

char *stpcpy(char *dest, const char *src);

Description

Copies one string into another.

stpcpy copies the string src to dest, stopping after the terminating null character of src has been reached.

Return Value

stpcpy returns dest + strlen(src).


See Also

strcpy


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


strcat, _fstrcat

Example	Portability

Syntax

#include <string.h>

char *strcat(char *dest, const char *src);

char far * far _fstrcat(char far *dest, const char far *src)

Description

Appends one string to another.

strcat appends a copy of src to the end of dest. The length of the resulting string is strlen(dest) + strlen(src).

Return Value

strcat returns a pointer to the concatenated strings.


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
strcat	+	+	+	+	+	+	+
_fstrcat	+		+


strchr, _fstrchr

See Also	Example	Portability

Syntax

#include <string.h>

char *strchr(const char *s, int c);                          /* C only */

char far * far _fstrchr(const char far *s, int c)            /* C only */

const char *strchr(const char *s, int c);                    // C++ only

char *strchr( char *s, int c);                               // C++ only

const char far * far _fstrchr(const char far *s, int c);     // C++ only

char far * far _fstrchr( char far *s, int c);                // C++ only

Description

Scans a string for the first occurrence of a given character.

strchr scans a string in the forward direction, looking for a specific character. strchr finds the first occurrence of the character c in the string s. The null-terminator is considered to be part of the string.

For example:

strchr(strs,0)

returns a pointer to the terminating null character of the string strs.

Return Value

strchr returns a pointer to the first occurrence of the character c in s; if c does not occur in s, strchr returns null.


See Also

strcspn

strrchr


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
strchr	+	+	+	+	+	+	+
_fstrchr	+		+


strcmp

See Also	Example	Portability

Syntax

#include <string.h>

int strcmp(const char *s1, const char *s2);

Description

Compares one string to another.

strcmp performs an unsigned comparison of s1 to s2, starting with the first character in each string and continuing with subsequent characters until the corresponding characters differ or until the end of the strings is reached.

Return Value

If s1 is...	strcmp returns a value that is...

less than s2	< 0

the same as s2	== 0

greater than s2	> 0


See Also

strcmpi

strcoll

stricmp

strncmp

strncmpi

strnicmpstrnicmp


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


strcmpi

See Also	Example	Portability

Syntax

#include <string.h>

int strcmpi(const char *s1, const char *s2);

Description

Compares one string to another, without case sensitivity.

strcmpi performs an unsigned comparison of s1 to s2, without case sensitivity (same as stricmp--implemented as a macro).

It returns a value (< 0, 0, or > 0) based on the result of comparing s1 (or part of it) to s2 (or part of it).

The routine strcmpi is the same as stricmp. strcmpi is implemented through a macro in string.h and translates calls from strcmpi to stricmp. Therefore, in order to use strcmpi, you must include the header file string.h for the macro to be available. This macro is provided for compatibility with other C compilers.

Return Value

If s1 is...	strcmpi returns a value that is...

less than s2	< 0

the same as s2	== 0

greater than s2	> 0


See Also

strcmp

strcoll

stricmp

strncmp

strncmpi

strnicmp


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	 	+	 	+


strcoll

See Also	Example	Portability

Syntax

#include <string.h>

int strcoll(char *s1, char *s2);

Description

Compares two strings.

strcoll compares the string pointed to by s1 to the string pointed to by s2, according to the current locale's LC_COLLATE category.

Return Value

If s1 is...	strcoll returns a value that is...

less than s2	< 0

the same as s2	== 0

greater than s2	> 0


See Also

strcmp

strcmpi

stricmp

strncmp

strncmpi

strnicmp

strxfrm


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	+	+	+


strcpy

See Also	Example	Portability

Syntax

#include <string.h>

char *strcpy(char *dest, const char *src);

Description

Copies one string into another.

Copies string src to dest, stopping after the terminating null character has been moved.

Return Value

strcpy returns dest.


See Also

stpcpy


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


strcspn, _fstrcspn

See Also	Example	Portability

Syntax

#include <string.h>

size_t strcspn(const char *s1, const char *s2);

size_t far *far _fstrcspn(const char far *s1, const char far *s2)

Description

Scans a string for the initial segment not containing any subset of a given set of characters.

The strcspn functions search s2 until any one of the characters contained in s1 is found. The number of characters which were read in s2 is the return value. The string termination character is not counted. Neither string is altered during the search.

Return Value

strcspn returns the length of the initial segment of string s1 that consists entirely of characters not from string s2.


See Also

strchr

strrchr


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
strcspn	+	+	+	+	+	+	+
_fstrcspn	+		+


_strdate

See Also	Example	Portability

Syntax

#include <time.h>

char *_strdate(char *buf);

Description

Converts current date to string.

_strdate converts the current date to a string, storing the string in the buffer buf. The buffer must be at least 9 characters long.

The string has the form MM/DD/YY where MM, DD, and YY are all two-digit numbers representing the month, day, and year. The string is terminated by a null character.

Return Value

_strdate returns buf, the address of the date string.


See Also

asctime

ctime

localtime

strftime

_strtime

timetime


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	+


strdup, _fstrdup

See Also	Example	Portability

Syntax

#include <string.h>

char *strdup(const char *s);

char far * far _fstrdup(const char far *s)

Description

Copies a string into a newly created location.

strdup makes a duplicate of string s, obtaining space with a call to malloc. The allocated space is (strlen(s) + 1) bytes long. The user is responsible for freeing the space allocated by strdup when it is no longer needed.

Return Value

strdup returns a pointer to the storage location containing the duplicated string, or returns null if space could not be allocated.


See Also

free


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
strdup	+	+	+	+			+
_fstrdup	+		+


_strerror

See Also	Example	Portability

Syntax

#include <string.h>

char  *_strerror(const char *s);

Description

Builds a customized error message.

_strerror lets you generate customized error messages; it returns a pointer to a null-terminated string containing an error message.

If s is null, the return value points to the most recent error message.

If s is not null, the return value contains s (your customized error message), a colon, a space, the most-recently generated system error message, and a new line. s should be 94 characters or less.

Return Value

_strerror returns a pointer to a constructed error string. The error message string is constructed in a static buffer that is overwritten with each call to _strerror.


See Also

perror

strerrorstrerror


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	+


strerror

See Also	Example	Portability

Syntax

#include <string.h>

char *strerror(int errnum);

Description

Returns a pointer to an error message string.

strerror takes an int parameter errnum, an error number, and returns a pointer to an error message string associated with errnum.

Return Value

strerror returns a pointer to a constructed error string. The error message string is constructed in a static buffer that is overwritten with each call to strerror.


See Also

perror

_strerror


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	+	+	+


strftime

See Also	Example	Portability

Syntax

#include <time.h>

size_t strftime(char *s, size_t maxsize, const char *fmt, const struct tm *t);

Description

Formats time for output.

strftime formats the time in the argument t into the array pointed to by the argument s according to the fmt specifications. All ordinary characters are copied unchanged. No more than maxsize characters are placed in s.

The time is formatted according to the current locale's LC_TIME category.

Return Value

On success, strftime returns the number of characters placed into s.

On error (if the number of characters required is greater than maxsize), strftime returns 0.

More about strftime

ANSI-defined format specifiers

POSIX-defined Format Specifiers

POSIX-defined Format Specifier Modifiers


See Also

localtime

mktime

time


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	+	+	+


strftime Format String

Consists of zero or more directives and ordinary characters. A directive consists of the % character followed by a character that determines the substitution that is to take place.


ANSI-defined Format Specifiers for strftime

See Also

The following table describes the ANSI-defined specifiers for the format string used with strftime.

Format specifier	Substitutes

%%	Character %

%a	Abbreviated weekday name

%A	Full weekday name

%b	Abbreviated month name

%B	Full month name

%c	Date and time

%d	Two-digit day of month (01 - 31)

%H	Two-digit hour (00 - 23)

%I	Two-digit hour (01 - 12)

%j	Three-digit day of year (001 - 366)

%m	Two-digit month as a decimal number (1 - 12)

%M	2-digit minute (00 - 59)

%p	AM or PM

%S	Two-digit second (00 - 59)

%U	Two-digit week number where Sunday is the first day of the week (00 - 53)

%w	Weekday where 0 is Sunday (0 - 6)

%W	Two-digit week number where Monday is the first day of week the week (00 - 53)

%x	Date

%X	Time

%y	Two-digit year without century (00 to 99)

%Y	Year with century

%Z	Time zone name, or no characters if no time zone


See Also

POSIX-defined Format Specifiers


POSIX-defined Format Specifiers for strftime

See Also

The following table describes the POSIX-defined specifiers for the format string used with strftime.

Note:	You must define __USELOCALES__ in order to use these descriptors.

Format specifier	Substitution

%C	Century as a decimal number (00 - 99). For example, 1992 => 19

%D	Date in the format mm/dd/yy

%e	Day of the month as a decimal number in a two-digit field with leading space  (1 -31)

%h	A synonym for %b

%n	Newline character

%r	12-hour time (01 - 12) format with am/pm string i.e. "%I:%M:%S %p"

%t	Tab character

%T	24-hour time (00 - 23) in the format "HH:MM:SS"

%u	Weekday as a decimal number (1 Monday - 7 Sunday)

Modifiers

strftime also supports POSIX-defined modifiers for certain specifiers. See POSIX-defined Format Specifier Modifiers.


See Also

ANSI-defined format specifiers


POSIX-defined Format Specifier Modifiers for strftime

See Also

The following table describes the POSIX-defined modifiers for the following format string specifiers used with strftime.

Note:	You must define __USELOCALES__ in order to use these descriptors.

Descriptor modifier	Substitutes

%Od	Day of the month using alternate numeric symbols

%Oe	Day of the month using alternate numeric symbols

%OH	Hour (24 hour) using alternate numeric symbols

%OI	Hour (12 hour) using alternate numeric symbols

%Om	Month using alternate numeric symbols

%OM	Minutes using alternate numeric symbols

%OS	Seconds using alternate numeric symbols

%Ou	Weekday as a number using alternate numeric symbols

%OU	Week number of the year using alternate numeric symbols

%Ow	Weekday as number using alternate numeric symbols

%OW	Week number of the year using alternate numeric symbols

%Oy	Year (offset from %C)  using alternate numeric symbols

%O modifier

When the %O modifier is used before any of the above supported numeric format descriptors (for example, %Od), the numeric value is converted to the corresponding ordinal string, if it exists. If an ordinal string does not exist, the basic format descriptor is used unmodified.

For example, on 4/20/94

%d produces 20

%Od produces 20th


See Also

ANSI-defined format specifiers

POSIX-defined Format Specifiers


stricmp, _fstricmp

See Also	Example	Portability

Syntax

#include <string.h>

int stricmp(const char *s1, const char *s2);

int far _fstricmp(const char far *s1, const char far *s2)

Description

Compares one string to another, without case sensitivity.

stricmp performs an unsigned comparison of s1 to s2, starting with the first character in each string and continuing with subsequent characters until the corresponding characters differ or until the end of the strings is reached. The comparison is not case sensitive.

It returns a value (< 0, 0, or > 0) based on the result of comparing s1 (or part of it) to s2 (or part of it).

The routines stricmp and strcmpi are the same; strcmpi is implemented through a macro in string.h that translates calls from strcmpi to stricmp. Therefore, in order to use stricmp, you must include the header file string.h for the macro to be available.

Return Value

If s1 is...	stricmp returns a value that is...

less than s2	< 0

the same as s2	== 0

greater than s2	> 0


See Also

strcmp

strcmpi

strcoll

strncmp

strncmpi

strnicmp


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
stricmp	+	+	+	+	+	+	+
_fstricmp	+		+


strlen, _fstrlen

Example	Portability

Syntax

#include <string.h>

size_t strlen(const char *s);

size_t far _fstrlen(const char far *s)

Description

Calculates the length of a string.

strlen calculates the length of s.

Return Value

strlen returns the number of characters in s, not counting the null-terminating character.


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
strlen	+	+	+	+	+	+	+
_fstrlen	+		+


strlwr, _fstrlwr

See Also	Example	Portability

Syntax

#include <string.h>

char *strlwr(char *s);

char far * far _fstrlwr(char char far *s)

Description

Converts uppercase letters in a string to lowercase.

strlwr converts uppercase letters in string s to lowercase according to the current locale's LC_CTYPE category. For the C locale, the conversion is from uppercase letters (A to Z) to lowercase letters (a to z). No other characters are changed.

Return Value

strlwr returns a pointer to the string s.


See Also

strupr


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
strlwr	+	+	+	+	+	+	+
_fstrlwr	+		+


strncat, _fstrncat

Example	Portability

Syntax

#include <string.h>

char *strncat(char *dest, const char *src, size_t maxlen);

char far * far _fstrncat(char far *dest, const char far *src, size_t maxlen)

Description

Appends a portion of one string to another.

strncat copies at most maxlen characters of src to the end of dest and then appends a null character. The maximum length of the resulting string is strlen(dest) + maxlen.

Return Value

strncat returns dest.


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
strncat	+	+	+	+	+	+	+
_fstrncat	+		+


strncmp, _fstrncmp

See Also	Example	Portability

Syntax

#include <string.h>

int strncmp(const char *s1, const char *s2, size_t  maxlen);

int far _fstrncmp(const char far *s1, const char far *s2, size_t maxlen)

Description

Compares a portion of one string to a portion of another.

strncmp makes the same unsigned comparison as strcmp, but looks at no more than maxlen characters. It starts with the first character in each string and continues with subsequent characters until the corresponding characters differ or until it has examined maxlen characters.

Return Value

strncmp returns an int value based on the result of comparing s1 (or part of it) to s2 (or part of it):

< 0 if s1 is less than s2

== 0 if s1 is the same as s2

> 0 if s1 is greater than s2


See Also

strcmp

strcoll

stricmp

strncmpi

strnicmp


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
strncmp	+	+	+	+	+	+	+
_fstrncmp	+		+


strncmpi

Example	Portability

Syntax

#include <string.h>

int strncmpi(const char *s1, const char *s2, size_t n);

Description

Compares a portion of one string to a portion of another, without case sensitivity.

strncmpi performs a signed comparison of s1 to s2, for a maximum length of n bytes, starting with the first character in each string and continuing with subsequent characters until the corresponding characters differ or until n characters have been examined. The comparison is not case sensitive. (strncmpi is the same as strnicmp--implemented as a macro). It returns a value (< 0, 0, or > 0) based on the result of comparing s1 (or part of it) to s2 (or part of it).

The routines strnicmp and strncmpi are the same; strncmpi is implemented through a macro in string.h that translates calls from strncmpi to strnicmp. Therefore, in order to use strncmpi, you must include the header file string.h for the macro to be available. This macro is provided for compatibility with other C compilers.

Return Value

If s1 is...	strncmpi returns a value that is...

less than s2	< 0

the same as s2	== 0

greater than s2	> 0


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+


strncpy, _fstrncpy

Example	Portability

Syntax

#include <stdio.h>

char *strncpy(char *dest, const char *src, size_t maxlen);

char far * far _fstrncpy(char far *dest, const char far *src, size_t maxlen)

Description

Copies a given number of bytes from one string into another, truncating or padding as necessary.

strncpy copies up to maxlen characters from src into dest, truncating or null-padding dest. The target string, dest, might not be null-terminated if the length of src is maxlen or more.

Return Value

strncpy returns dest.


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
strncpy	+	+	+	+	+	+	+
_fstrncpy	+		+


strnicmp, _fstrnicmp

Example	Portability

Syntax

#include <string.h>

int strnicmp(const char *s1, const char *s2, size_t maxlen);

int far _fstrnicmp(const char far *s1, const char far *s2, size_t maxlen)

Description

Compares a portion of one string to a portion of another, without case sensitivity.

strnicmp performs a signed comparison of s1 to s2, for a maximum length of maxlen bytes, starting with the first character in each string and continuing with subsequent characters until the corresponding characters differ or until the end of the strings is reached. The comparison is not case sensitive.

It returns a value (< 0, 0, or > 0) based on the result of comparing s1 (or part of it) to s2 (or part of it).

Return Value

If s1 is...	strnicmp returns a value that is...

less than s2	< 0

the same as s2	== 0

greater than s2	> 0


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
strnicmp	+		+	+			+
_fstrnicmp	+		+


strnset, _fstrnset

Example	Portability

Syntax

#include <string.h>

char *strnset(char *s, int ch, size_t n);

char far * far _fstrnset(char far *s, int ch, size_t n)

Description

Sets a specified number of characters in a string to a given character.

strnset copies the character ch into the first n bytes of the string s. If n > strlen(s), then strlen(s) replaces n. It stops when n characters have been set, or when a null character is found.

Return Value

strnset returns s.


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
strnset	+		+	+			+
_fstrnset	+		+


strpbrk, _fstrpbrk

Example	Portability

Syntax

#include <string.h>

char *strpbrk(const char *s1, const char *s2);          /* C only */

char far *far _fstrpbrk(const char far *s1,
const char far*s2)                                    /* C only */

const char *strpbrk(const char *s1, const char *s2);    // C++ only

char *strpbrk(char *s1, const char *s2);                // C++ only

const char far *far _fstrpbrk(const char far *s1,
const char far *s2);                                  // C++ only

char far * far _fstrpbrk(char far *s1,

                         const char far *s2);           // C++ only

Description

Scans a string for the first occurrence of any character from a given set.

strpbrk scans a string, s1, for the first occurrence of any character appearing in s2.

Return Value

strpbrk returns a pointer to the first occurrence of any of the characters in s2. If none of the s2 characters occur in s1, strpbrk returns null.


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
strpbrk	+	+	+	+	+	+	+
_fstpbrk	+		+


strrchr, _fstrrchr

See Also	Example	Portability

Syntax

char *strrchr(const char *s, int c);                  /* C only */

char far * far _fstrrchr(const char far *s, int c)    /* C only */

const char *strrchr(const char *s, int c);            // C++ only

char *strrchr(char *s, int c);                        // C++ only

const char *_fstrrchr(const char far *s, int c);      // C++ only

char *_fstrrchr(char far *s, int c);                  // C++ only

Description

Scans a string for the last occurrence of a given character.

strrchr scans a string in the reverse direction, looking for a specific character. strrchr finds the last occurrence of the character c in the string s. The null-terminator is considered to be part of the string.

Return Value

strrchr returns a pointer to the last occurrence of the character c. If c does not occur in s, strrchr returns null.


See Also

strcspn

strchr


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
strrchr	+	+	+	+	+	+	+
_fstrrchr	+		+


strrev, _fstrrev

Example	Portability

Syntax

#include <string.h>

char *strrev(char *s);

char far * far _fstrrev(char far *s)

Description

Reverses a string.

strrev changes all characters in a string to reverse order, except the terminating null character. (For example, it would change string\0 to gnirts\0.)

Return Value

strrev returns a pointer to the reversed string.


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
strrev	+		+	+			+
_fstrrev	+		+


strset, _fstrset

See Also	Example	Portability

Syntax

#include <string.h>

char *strset(char *s, int ch);

char far * far _fstrset(char far *s, int ch)

Description

Sets all characters in a string to a given character.

strset sets all characters in the string s to the character ch. It quits when the terminating null character is found.

Return Value

strset returns s.


See Also

setmem


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
strset	+		+	+			+
_fstrset	+		+


strspn, _fstrspn

Example	Portability

Syntax

#include <string.h>

size_t strspn(const char *s1, const char *s2);

size_t far _fstrspn(const char far *s1, const char far *s2)

Description

Scans a string for the first segment that is a subset of a given set of characters.

strspn finds the initial segment of string s1 that consists entirely of characters from string s2.

Return Value

strspn returns the length of the initial segment of s1 that consists entirely of characters from s2.


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
strspn	+	+	+	+	+	+	+
_fstrspn	+		+


strstr, _fstrstr

Example	Portability

Syntax

#include <string.h>

char *strstr(const char *s1, const char *s2);                /* C only */

char far * far _fstrstr(const char far *s1,
const char far*s2);                                        /* C only */

const char *strstr(const char *s1, const char *s2);          // C++ only

char *strstr(char *s1, const char *s2);                      // C++ only

const char far *far _fstrstr(const char far *s1,
const char far *s2);                                       // C++ only

char far * far _fstrstr(char far *s1, const char far *s2);   // C++ only

Description

Scans a string for the occurrence of a given substring.

strstr scans s1 for the first occurrence of the substring s2.

Return Value

strstr returns a pointer to the element in s1, where s2 begins (points to s2 in s1). If s2 does not occur in s1, strstr returns null.


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
strstr	+	+	+	+	+	+	+
_fstrstr	+		+


_strtime

See Also	Example	Portability

Syntax

#include <time.h>

char *_strtime(char *buf);

Description

Converts current time to string.

_strtime converts the current time to a string, storing the string in the buffer buf. The buffer must be at least 9 characters long.

The string has the following form:

   HH:MM:SS

where HH, MM, and SS are all two-digit numbers representing the hour, minute, and second, respectively. The string is terminated by a null character.

Return Value

_strtime returns buf, the address of the time string.


See Also

asctime

ctime

localtime

strftime

_strdate

timetime


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


strtod, _strtold

See Also	Example	Portability

Syntax

#include <stdlib.h>

double strtod(const char *s, char **endptr);

long double _strtold(const char *s, char **endptr);

Description

Convert a string to a double or long double value.

strtod converts a character string, s, to a double value. s is a sequence of characters that can be interpreted as a double value; the characters must match this generic format:

   [ws] [sn] [ddd] [.] [ddd] [fmt[sn]ddd]

where:

[ws]	=	optional whitespace

[sn]	=	optional sign (+ or -)

[ddd]	=	optional digits

[fmt]	=	optional e or E

[.]	=	optional decimal point

strtod also recognizes +INF and -INF for plus and minus infinity, and +NAN and -NAN for Not-a-Number.

For example, here are some character strings that strtod can convert to double:

  + 1231.1981 e-1

  502.85E2

  + 2010.952

strtod stops reading the string at the first character that cannot be interpreted as an appropriate part of a double value.

If endptr is not null, strtod sets *endptr to point to the character that stopped the scan (*endptr = &stopper). endptr is useful for error detection.

_strtold is the long double version; it converts a string to a long double value.

Return Value

These functions return the value of s as a double (strtod) or a long double (_strtold). In case of overflow, they return plus or minus HUGE_VAL (strtod) or _LHUGE_VAL (_strtold).


See Also

atof


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
strtod	+	+	+	+	+	+	+
_strtold	+		+	+			+


strtok, _fstrtok

Example	Portability

Syntax

#include <string.h>

char *strtok(char *s1, const char *s2);

char far * far _fstrtok(char far *s1, const char far *s2)

Description

Searches one string for tokens, which are separated by delimiters defined in a second string.

strtok considers the string s1 to consist of a sequence of zero or more text tokens, separated by spans of one or more characters from the separator string s2.

The first call to strtok returns a pointer to the first character of the first token in s1 and writes a null character into s1 immediately following the returned token. Subsequent calls with null for the first argument will work through the string s1 in this way, until no tokens remain.

The separator string, s2, can be different from call to call.

Note:	Calls to strtok cannot be nested with a function call that also uses strtok. Doing so will causes an endless loop.

Return Value

strtok returns a pointer to the token found in s1. A NULL pointer is returned when there are no more tokens.


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
strtok	+	+	+	+	+	+	+
_fstrtok	+		+


strtol

See Also	Example	Portability

Syntax

#include <stdlib.h>

long strtol(const char *s, char **endptr, int radix);

Description

Converts a string to a long value.

strtol converts a character string, s, to a long integer value. s is a sequence of characters that can be interpreted as a long value; the characters must match this generic format:

   [ws] [sn] [0] [x] [ddd]

where:

[ws]	=	optional whitespace

[sn]	=	optional sign (+ or -)

[0]	=	optional zero (0)

[x]	=	optional x or X

[ddd]	=	optional digits

strtol stops reading the string at the first character it doesn't recognize.

If radix is between 2 and 36, the long integer is expressed in base radix. If radix is 0, the first few characters of s determine the base of the value being converted.

First character 	Second character	String interpreted as...

0	1 - 7	Octal

0	x or X	Hexadecimal

1 - 9	 	Decimal

If radix is 1, it is considered to be an invalid value. If radix is less than 0 or greater than 36, it is considered to be an invalid value.

Any invalid value for radix causes the result to be 0 and sets the next character pointer *endptr to the starting string pointer.

If the value in s is meant to be interpreted as octal, any character other than 0 to 7 will be unrecognized.

If the value in s is meant to be interpreted as decimal, any character other than 0 to 9 will be unrecognized.

If the value in s is meant to be interpreted as a number in any other base, then only the numerals and letters used to represent numbers in that base will be recognized. (For example, if radix equals 5, only 0 to 4 will be recognized; if radix equals 20, only 0 to 9 and A to J will be recognized.)

If endptr is not null, strtol sets *endptr to point to the character that stopped the scan (*endptr = &stopper).

Return Value

strtol returns the value of the converted string, or 0 on error.


See Also

atoi

atol

strtoul


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	+	+	+


strtoul

See Also	Example	Portability

Syntax

#include <stdlib.h>

unsigned long strtoul(const char *s, char **endptr, int radix);

Description

Converts a string to an unsigned long in the given radix.

strtoul operates the same as strtol, except that it converts a string str to an unsigned long value (where strtol converts to a long). Refer to the entry for strtol for more information.

Return Value

strtoul returns the converted value, an unsigned long, or 0 on error.


See Also

atol

strtol


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	+ 	+ 	+


strupr, _fstrupr

See Also	Example	Portability

Syntax

#include <string.h>

char *strupr(char *s);

char far * far _fstrupr(char far *s)

Description

Converts lowercase letters in a string to uppercase.

strupr converts lowercase letters in string s to uppercase according to the current locale's LC_CTYPE category. For the default C locale, the conversion is from lowercase letters (a to z) to uppercase letters (A to Z). No other characters are changed.

Return Value

strupr returns s.


See Also

strlwr


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
strupr	+		+	+			+
_fstrupr	+		+


strxfrm

See Also	Example	Portability

Syntax

#include<string.h>

size_t strxfrm(char *target, const char *source, size_t n);

Description

Transforms a portion of a string to a specified collation.

strxfrm transforms the string pointed to by source into the string target for no more than n characters. The transformation is such that if the strcmp function is applied to the resulting strings, its return corresponds with the return values of the strcoll function.

No more than n characters, including the terminating null character, are copied to target.

strxfrm transforms a character string into a special string according to the current locale's LC_COLLATE category. The special string that is built can be compared with another of the same type, byte for byte, to achieve a locale-correct collation result. These special strings, which can be thought of as keys or tokenized strings, are not compatible across the different locales.

The tokens in the tokenized strings are built from the collation weights used by strcoll from the active locale's collation tables.

Processing stops only after all levels have been processed for the character string or the length of the tokenized string is equal to the maxlen parameter.

All redundant tokens are removed from each level's set of tokens.

The tokenized string buffer must be large enough to contain the resulting tokenized string. The length of this buffer depends on the size of the character string, the number of collation levels, the rules for each level and whether there are any special characters in the character string. Certain special characters can cause extra character processing of the string resulting in more space requirements. For example, the French character "oe" will take double the space for itself because in some locales, it expands to collation weights for each level. Substrings that have substitutions will also cause extra space requirements.

There is no safe formula to determine the required string buffer size, but at least (levels * string length) are required.

Return Value

Number of characters copied not including the terminating null character. If the value returned is greater than or equal to n, the content of target is indeterminate.


See Also

strcmp

strcoll

strncpy


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	+	+	+


swab

Example	Portability

Syntax

#include <stdlib.h>

void swab(char *from, char *to, int nbytes);

Description

Swaps bytes.

swab copies nbytes bytes from the from string to the to string. Adjacent even- and odd-byte positions are swapped. This is useful for moving data from one machine to another machine with a different byte order. nbytes should be even.

Return Value

None.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


system

See Also	Example	Portability

Syntax

#include <stdlib.h>

int system(const char *command);

Description

Issues an operating system command.

system invokes the operating system command processor to execute an operating system command, batch file, or other program named by the string command, from inside an executing C program.

To be located and executed, the program must be in the current directory or in one of the directories listed in the PATH string in the environment.

The COMSPEC environment variable is used to find the command processor program file, so that file need not be in the current directory.

Return Value

If command is a NULL pointer, system returns nonzero if a command processor is available.

If command is not a NULL pointer, system returns 0 if the command processor was successfully started.

If an error occurred, a -1 is returned and errno is set to one of the following:

ENOENT	Path or file function not found

ENOEXEC	Exec format error

ENOMEM	Not enough memory


See Also

exec...

_fpreset

searchpath

spawn...


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	 	+	 	 	+


tan, tanl

See Also	Example	Portability

Syntax

#include <math.h>

double tan(double x);

long double tanl(long double x);

Description

Calculates the tangent.

tan calculates the tangent. Angles are specified in radians.

tanl is the long double version; it takes a long double argument and returns a long double result. Error handling for these routines can be modified through the functions _matherr and _matherrl.

This function can be used with bcd and complex types.

Return Value

tan and tanl return the tangent of x, sin(x)/cos(x).


See Also

acos

asin

atan

atan2

bcd

complex

cos

sin


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
tan	+	+	+	+	+	+	+
tanl	+		+	+			+


tanh, tanhl

See Also	Example	Portability

Syntax

#include <math.h>

double tanh(double x);

long double tanhl(long double x);

Description

Calculates the hyperbolic tangent.

tanh computes the hyperbolic tangent, sinh(x)/cosh(x).

tanhl is the long double version; it takes a long double argument and returns a long double result. Error handling for these functions can be modified through the functions _matherr and _matherrl.

This function can be used with bcd and complex types.

Return Value

tanh and tanhl return the hyperbolic tangent of x.


See Also

bcd

complex

cos

cosh

sin

sinh

tan


Portability

	DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2
tanh	+	+	+	+	+	+	+
tanhl	+		+	+			+


tell

See Also	Example	Portability

Syntax

#include <io.h>

long tell(int handle);

Description

Gets the current position of a file pointer.

tell gets the current position of the file pointer associated with handle and expresses it as the number of bytes from the beginning of the file.

Return Value

tell returns the current file pointer position. A return of -1 (long) indicates an error, and the global variable errno is set to

EBADF	Bad file number


See Also

fgetpos

fseek

ftell

lseek


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


tempnam

See Also	Example	Portability

Syntax

#include <stdio.h>

char *tempnam(char *dir, char *prefix)

Description

Creates a unique file name in specified directory.

The tempnam function creates a unique file name in arbitrary directories. The unique file is not actually created; tempnam only verifies that it does not currently exist. It attempts to use the following directories, in the order shown, when creating the file name:

The directory specified by the TMP environment variable.

The dir argument to tempnam.

The P_tmpdir definition in stdio.h. If you edit stdio.h and change this definition, tempnam will not use the new definition.

The current working directory.

If any of these directories is NULL, or undefined, or does not exist, it is skipped.

The prefix argument specifies the first part of the file name; it cannot be longer than 5 characters, and cannot contain a period (.). A unique file name is created by concatenating the directory name, the prefix, and 6 unique characters. Space for the resulting file name is allocated with malloc; when this file name is no longer needed, the caller should call free to free it.

If you do create a temporary file using the name constructed by tempnam, it is your responsibility to delete the file name (for example, with a call to remove). It is not deleted automatically. (tmpfile does delete the file name.)

Return Value

If tempnam is successful, it returns a pointer to the unique temporary file name, which the caller can pass to free when it is no longer needed. Otherwise, if tempnam cannot create a unique file name, it returns NULL.


See Also

mktemp

tmpfile

tmpnam


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


textattr

See Also	Example	Portability

Syntax

#include <conio.h>

void textattr(int newattr);

Description

Sets text attributes.

Note:	Do not use this function for Win32s or Win32 GUI applications.

textattr lets you set both the foreground and background colors in a single call. (Normally, you set the attributes with textcolor and textbackground.)

This function does not affect any characters currently onscreen; it affects only those characters displayed by functions (such as cprintf) performing text mode, direct video output after this function is called.

The color information is encoded in the newattr parameter as follows:

In this 8-bit newattr parameter:

ffff is the 4-bit foreground color (0 to 15).

bbb is the 3-bit background color (0 to 7).

B is the blink-enable bit.

If the blink-enable bit is on, the character blinks. This can be accomplished by adding the constant BLINK to the attribute.

If you use the symbolic color constants defined in conio.h for creating text attributes with textattr, note the following limitations on the color you select for the background:

You can select only one of the first eight colors for the background.

You must shift the selected background color left by 4 bits to move it into the correct bit positions.

These symbolic constants are listed in the following table:

Symbolic constant	Numeric value	Foreground or background

BLACK	0	Both

BLUE	1	Both

GREEN	2	Both

CYAN	3	Both

RED	4	Both

MAGENTA	5	Both

BROWN	6	Both

LIGHTGRAY	7	Both

DARKGRAY	8	Foreground only

LIGHTBLUE	9	Foreground only

LIGHTGREEN	10	Foreground only

LIGHTCYAN	11	Foreground only

LIGHTRED	12	Foreground only

LIGHTMAGENTA	13	Foreground only

YELLOW	14	Foreground only

WHITE	15	Foreground only

BLINK	128	Foreground only

Return Value

None.


See Also

gettextinfo

highvideo

lowvideo

normvideo

textbackground

textcolor


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+	 	 	+


textbackground

See Also	Example	Portability

Syntax

#include <conio.h>

void textbackground(int newcolor);

Description

Selects new text background color.

Note:	Do not use this function for Win32s or Win32 GUI applications.

textbackground selects the background color. This function works for functions that produce output in text mode directly to the screen. newcolor selects the new background color. You can set newcolor to an integer from 0 to 7, or to one of the symbolic constants defined in conio.h. If you use symbolic constants, you must include conio.h.

Once you have called textbackground, all subsequent functions using direct video output (such as cprintf) will use newcolor. textbackground does not affect any characters currently onscreen.

The following table lists the symbolic constants and the numeric values of the allowable colors:

Symbolic constant	Numeric value

BLACK	0

BLUE	1

GREEN	2

CYAN	3

RED	4

MAGENTA	5

BROWN	6

LIGHTGRAY	7

Return Value

None.


See Also

gettextinfo

textattr

textcolor


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+	 	 	+


textcolor

See Also	Example	Portability

Syntax

#include <conio.h>

void textcolor(int newcolor);

Description

Selects new character color in text mode.

Note:	Do not use this function for Win32s or Win32 GUI applications.

textcolor selects the foreground character color. This function works for the console output functions. newcolor selects the new foreground color. You can set newcolor to an integer as given in the table below, or to one of the symbolic constants defined in conio.h. If you use symbolic constants, you must include conio.h.

Once you have called textcolor, all subsequent functions using direct video output (such as cprintf) will use newcolor. textcolor does not affect any characters currently onscreen.

The following table lists the allowable colors (as symbolic constants) and their numeric values:

Symbolic constant	Numeric value

BLACK	0

BLUE	1

GREEN	2

CYAN	3

RED	4

MAGENTA	5

BROWN	6

LIGHTGRAY	7

DARKGRAY	8

LIGHTBLUE	9

LIGHTGREEN	10

LIGHTCYAN	11

LIGHTRED	12

LIGHTMAGENTA	13

YELLOW	14

WHITE	15

BLINK	128

You can make the characters blink by adding 128 to the foreground color. The predefined constant BLINK exists for this purpose.

For example:

   textcolor(CYAN + BLINK);

Note:	Some monitors do not recognize the intensity signal used to create the eight "light" colors (8-15). On such monitors, the light colors are displayed as their "dark" equivalents (0-7). Also, systems that do not display in color can treat these numbers as shades of one color, special patterns, or special attributes (such as underlined, bold, italics, and so on). Exactly what you'll see on such systems depends on your hardware.

Return Value

None.


See Also

gettextinfo

highvideo

lowvideo

normvideo

textattr

textbackground


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+	 	 	+


textmode

See Also	Example	Portability

Syntax

#include <conio.h>

void textmode(int newmode);

Description

Puts screen in text mode.

Note:	Do not use this function for Win32s or Win32 GUI applications.

textmode selects a specific text mode.

You can give the text mode (the argument newmode) by using a symbolic constant from the enumeration type text_modes (defined in conio.h).

The most commonly used text_modes type constants and the modes they specify are given in the following table. Some additional values are defined in conio.h.

Symbolic Constant	Text Mode

LASTMODE	Previous text mode

BW40	Black and white, 40 columns

C40	Color, 40 columns

BW80	Black and white, 80 columns

C80	Color, 80 columns

MONO	Monochrome, 80 columns

C4350	EGA 43-line and VGA 50-line modes

When textmode is called, the current window is reset to the entire screen, and the current text attributes are reset to normal, corresponding to a call to normvideo.

Specifying LASTMODE to textmode causes the most recently selected text mode to be reselected.

textmode should be used only when the screen or window is in text mode (presumably to change to a different text mode). This is the only context in which textmode should be used. When the screen is in graphics mode, use restorecrtmode instead to escape temporarily to text mode.

Return Value

None.


See Also

gettextinfo

window


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+	 	 	+


time

See Also	Example	Portability

Syntax

#include <time.h>

time_t time(time_t *timer);

Description

Gets time of day.

time gives the current time, in seconds, elapsed since 00:00:00 GMT, January 1, 1970, and stores that value in the location pointed to by timer, provided that timer is not a NULL pointer.

Return Value

time returns the elapsed time in seconds.


See Also

asctime

ctime

difftime

ftime

gettime

gmtime

localtime

settime

stime

tzset


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


tmpfile

See Also	Example	Portability

Syntax

#include <stdio.h>

FILE *tmpfile(void);

Description

Opens a "scratch" file in binary mode.

tmpfile creates a temporary binary file and opens it for update (w + b). If you do not change the directory after creating the temporary file, the file is automatically removed when it's closed or when your program terminates.

Return Value

tmpfile returns a pointer to the stream of the temporary file created. If the file can't be created, tmpfile returns NULL.


See Also

fopen

tmpnam


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


tmpnam

See Also	Example	Portability

Syntax

#include <stdio.h>

char *tmpnam(char *s);

Description

Creates a unique file name.

tmpnam creates a unique file name, which can safely be used as the name of a temporary file. tmpnam generates a different string each time you call it, up to TMP_MAX times. TMP_MAX is defined in stdio.h as 65,535.

The parameter to tmpnam, s, is either null or a pointer to an array of at least L_tmpnam characters. L_tmpnam is defined in stdio.h. If s is NULL, tmpnam leaves the generated temporary file name in an internal static object and returns a pointer to that object. If s is not NULL, tmpnam places its result in the pointed-to array, which must be at least L_tmpnam characters long, and returns s.

If you do create such a temporary file with tmpnam, it is your responsibility to delete the file name (for example, with a call to remove). It is not deleted automatically. (tmpfile does delete the file name.)

Return Value

If s is null, tmpnam returns a pointer to an internal static object. Otherwise, tmpnam returns s.


See Also

tmpfile


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


toascii

Example	Portability

Syntax

#include <ctype.h>

int toascii(int c);

Description

Translates characters to ASCII format.

toascii is a macro that converts the integer c to ASCII by clearing all but the lower 7 bits; this gives a value in the range 0 to 127.

Return Value

toascii returns the converted value of c.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


_tolower

Example	Portability

Syntax

#include <ctype.h>

int _tolower(int ch);

Description

_tolower is a macro that does the same conversion as tolower, except that it should be used only when ch is known to be uppercase (AZ).

To use _tolower, you must include ctype.h.

Return Value

_tolower returns the converted value of ch if it is uppercase; otherwise, the result is undefined.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


tolower

Example	Portability

Syntax

#include <ctype.h>

int tolower(int ch);

Description

Translates characters to lowercase.

tolower is a function that converts an integer ch (in the range EOF to 255) to its lowercase value (a to z; if it was uppercase, A to Z). All others are left unchanged.

Return Value

tolower returns the converted value of ch if it is uppercase; it returns all others unchanged.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


_toupper

Example	Portability

Syntax

#include <ctype.h>

int _toupper(int ch);

Description

Translates characters to uppercase.

_toupper is a macro that does the same conversion as toupper, except that it should be used only when ch is known to be lowercase (a to z).

To use _toupper, you must include ctype.h.

Return Value

_toupper returns the converted value of ch if it is lowercase; otherwise, the result is undefined.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


toupper

Example	Portability

Syntax

#include <ctype.h>

int toupper(int ch);

Description

Translates characters to uppercase.

toupper is a function that converts an integer ch (in the range EOF to 255) to its uppercase value (A to Z; if it was lowercase, a to z). All others are left unchanged.

Return Value

toupper returns the converted value of ch if it is lowercase; it returns all others unchanged.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


tzset

See Also	Example	Portability

Syntax

#include <time.h>

void tzset(void)

Description

Sets value of global variables _daylight, _timezone, and _tzname.

tzset is available on XENIX systems.

tzset sets the _daylight, _timezone, and _tzname global variables based on the environment variable TZ. The library functions ftime and localtime use these global variables to adjust Greenwich Mean Time (GMT) to the local time zone. The format of the TZ environment string is:

   TZ = zzz[+/-]d[d][lll]

where zzz is a three-character string representing the name of the current time zone. All three characters are required. For example, the string "PST" could be used to represent Pacific standard time.

[+/-]d[d] is a required field containing an optionally signed number with 1 or more digits. This number is the local time zone's difference from GMT in hours. Positive numbers adjust westward from GMT. Negative numbers adjust eastward from GMT. For example, the number 5 = EST, +8 = PST, and -1 = continental Europe. This number is used in the calculation of the global variable _timezone. _timezone is the difference in seconds between GMT and the local time zone.

lll is an optional three-character field that represents the local time zone, daylight saving time. For example, the string "PDT" could be used to represent pacific _daylight saving time. If this field is present, it causes the global variable _daylight to be set nonzero. If this field is absent, _daylight is set to zero.

If the TZ environment string isn't present or isn't in the preceding form, a default TZ = "EST5EDT" is presumed for the purposes of assigning values to the global variables _daylight, _timezone, and _tzname.

The global variable _tzname[0] points to a three-character string with the value of the time-zone name from the TZ environment string. _tzname[1] points to a three-character string with the value of the _daylight saving time-zone name from the TZ _environment string. If no _daylight saving name is present, _tzname[1] points to a null string.

Return Value

None.


See Also

asctime

ctime

ftime

gmtime

localtime

stime

time


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


ultoa

See Also	Example	Portability

Syntax

#include <stdlib.h>

char *ultoa(unsigned long value, char *string, int radix);

Description

Converts an unsigned long to a string.

ultoa converts value to a null-terminated string and stores the result in string. value is an unsigned long.

radix specifies the base to be used in converting value; it must be between 2 and 36, inclusive. ultoa performs no overflow checking, and if value is negative and radix equals 10, it does not set the minus sign.

Note:	The space allocated for string must be large enough to hold the returned string, including the terminating null character (\0). ultoa can return up to 33 bytes.

Return Value

ultoa returns string.


See Also

itoa

ltoa


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


umask

See Also	Example	Portability

Syntax

#include <io.h>

unsigned umask(unsigned mode);

Description

Sets file read/write permission mask.

The umask function sets the access permission mask used by open and creat. Bits that are set in mode will be cleared in the access permission of files subsequently created by open and creat.

The mode can have one of the following values, defined in sys\stat.h:

Value of mode	Access permission

S_IWRITE	Permission to write

S_IREAD	Permission to read

S_IREAD|S_IWRITE	Permission to read and write

Return Value

The previous value of the mask. There is no error return.


See Also

creat

open


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


ungetc

See Also	Example	Portability

Syntax

#include <stdio.h>

int ungetc(int c, FILE *stream);

Description

Pushes a character back into input stream.

Note:	Do not use this function for Win32s or Win32 GUI applications.

ungetc pushes the character c back onto the named input stream, which must be open for reading. This character will be returned on the next call to getc or fread for that stream. One character can be pushed back in all situations. A second call to ungetc without a call to getc will force the previous character to be forgotten. A call to fflush, fseek, fsetpos, or rewind erases all memory of any pushed-back characters.

Return Value

On success, ungetc returns the character pushed back.

On eror, it returns EOF.


See Also

fgetc

getc

getchar


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


ungetch

See Also	Example	Portability

Syntax

#include <conio.h>

int ungetch(int ch);

Description

Pushes a character back to the keyboard buffer.

Note:	Do not use this function for Win32s or Win32 GUI applications.

ungetch pushes the character ch back to the console, causing ch to be the next character read. The ungetch function fails if it is called more than once before the next read.

Return Value

On success, ungetch returns the character ch.

On error, it returns EOF.


See Also

getch

getche


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	 	+	 	 	+


unixtodos

See Also	Example	Portability

Syntax

#include <dos.h>

void unixtodos(long time, struct date *d, struct time *t);

Description

Converts date and time from UNIX to DOS format.

unixtodos converts the UNIX-format time given in time to DOS format and fills in the date and time structures pointed to by d and t.

time must not represent a calendar time earlier than Jan. 1, 1980 00:00:00.

Return Value

None.


See Also

dostounix


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


unlink

See Also	Example	Portability

Syntax

#include <io.h>

int unlink(const char *filename);

Description

Deletes a file.

unlink deletes a file specified by filename. Any drive, path, and file name can be used as a filename. Wildcards are not allowed.

Read-only files cannot be deleted by this call. To remove read-only files, first use chmod or _rtl_chmod to change the read-only attribute.

Note:	If your file is open, be sure to close it before unlinking it.

Return Value

On success, unlink returns 0.

On error, it returns -1 and sets the global variable errno to one of the following values:

EACCES	Permission denied

ENOENT	Path or file name not found


See Also

chmod

remove


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


unlock

See Also	Example	Portability

Syntax

#include <io.h>

int unlock(int handle, long offset, long length);

Description

Releases file-sharing locks.

unlock provides an interface to the operating system file-sharing mechanism. unlock removes a lock previously placed with a call to lock. To avoid error, all locks must be removed before a file is closed. A program must release all locks before completing.

Return Value

On success, unlock returns 0

O error, it returns  -1.


See Also

lock

locking

sopen


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


utime

See Also	Example	Portability

Syntax

#include <utime.h>

int utime(char *path, struct utimbuf *times);

Description

Sets file time and date.

utime sets the modification time for the file path. The modification time is contained in the utimbuf structure pointed to by times. This structure is defined in utime.h, and has the following format:

   struct utimbuf {

      time_t   actime;    /* access time */

      time_t   modtime;   /* modification time */

      };

The FAT (file allocation table) file system supports only a modification time; therefore, on FAT file systems utime ignores actime and uses only modtime to set the file's modification time.

If times is NULL, the file's modification time is set to the current time.

Return Value

On sucess, utime returns 0.

On error, it returns -1, and sets the global variable errno  to one of the following values:

EACCES	Permission denied

EMFILE	Too many open files

ENOENT	Path or file name not found


See Also

setftime

stat

time


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


va_arg, va_end, va_start

See Also	Example	Portability

Syntax

#include <stdarg.h>

void va_start(va_list ap, lastfix);

type va_arg(va_list ap, type);

void va_end(va_list ap);

Description

Implement a variable argument list.

Some C functions, such as vfprintf and vprintf, take variable argument lists in addition to taking a number of fixed (known) parameters. The va_arg, va_end, and va_start macros provide a portable way to access these argument lists. They are used for stepping through a list of arguments when the called function does not know the number and types of the arguments being passed.

The header file stdarg.h declares one type (va_list) and three macros (va_start, va_arg, and va_end).

va_list: This array holds information needed by va_arg and va_end. When a called function takes a variable argument list, it declares a variable ap of type va_list.

va_start: This routine (implemented as a macro) sets ap to point to the first of the variable arguments being passed to the function. va_start must be used before the first call to va_arg or va_end.

va_start takes two parameters: ap and lastfix. (ap is explained under va_list in the preceding paragraph; lastfix is the name of the last fixed parameter being passed to the called function.)

va_arg: This routine (also implemented as a macro) expands to an expression that has the same type and value as the next argument being passed (one of the variable arguments). The variable ap to va_arg should be the same ap that va_start initialized.

Note:	Because of default promotions, you cannot use char, unsigned char, or float types with va_arg.

The first time va_arg is used, it returns the first argument in the list. Each successive time va_arg is used, it returns the next argument in the list. It does this by first dereferencing ap, and then incrementing ap to point to the following item. va_arg uses the type to both perform the dereference and to locate the following item. Each successive time va_arg is invoked, it modifies ap to point to the next argument in the list.

va_end: This macro helps the called function perform a normal return. va_end might modify ap in such a way that it cannot be used unless va_start is recalled. va_end should be called after va_arg has read all the arguments; failure to do so might cause strange, undefined behavior in your program.

Return Value

va_start and va_end return no values; va_arg returns the current argument in the list (the one that ap is pointing to).


See Also

vprintf

vscanf


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


vfprintf

See Also	Example	Portability

Syntax

#include <stdio.h>

int vfprintf(FILE *stream, const char *format, va_list arglist);

Description

Writes formatted output to a stream.

The v...printf functions are known as alternate entry points for the ...printf functions. They behave exactly like their ...printf counterparts, but they accept a pointer to a list of arguments instead of an argument list.

For details on format specifiers, see Printf Format Specifiers.

vfprintf accepts a pointer to a series of arguments, applies to each argument a format specifier contained in the format string pointed to by format, and outputs the formatted data to a stream. There must be the same number of format specifiers as arguments.

Return Value

On success, vfprintf returns the number of bytes output.

On error, it returns EOF.


See Also

printf

va_arg

va_end

va_start


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


vfscanf

See Also	Example	Portability

Syntax

#include <stdio.h>

int vfscanf(FILE *stream

const char *format

va_list arglist);

Description

Scans and formats input from a stream.

The v...scanf functions are known as alternate entry points for the ...scanf functions. They behave exactly like their ...scanf counterparts but they accept a pointer to a list of arguments instead of an argument list.

For details on format specifiers, see Scanf Format Specifiers.

vfscanf scans a series of input fields one character at a time reading from a stream. Then each field is formatted according to a format specifier passed to vfscanf in the format string pointed to by format. Finally vfscanf stores the formatted input at an address passed to it as an argument following format. There must be the same number of format specifiers and addresses as there are input fields. vfscanf might stop scanning a particular field before it reaches the normal end-of-field (whitespace) character or it might terminate entirely for a number of reasons. See scanf for a discussion of possible causes.

Return Value

vfscanf returns the number of input fields successfully scanned converted and stored; the return value does not include scanned fields that were not stored. If no fields were stored the return value is 0.

If vfscanf attempts to read at end-of-file the return value is EOF.


See Also

fscanf

scanf

va_arg

va_end

va_start


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


vprintf

See Also	Example	Portability

Syntax

#include <stdarg.h>

int vprintf(const char *format, va_list arglist);

Description

Writes formatted output to stdout.

Note:	Do not use this function for Win32s or Win32 GUI applications.

The v...printf functions are known as alternate entry points for the ...printf functions. They behave exactly like their ...printf counterparts, but they accept a pointer to a list of arguments instead of an argument list.

For details on format specifiers, see Printf Format Specifiers.

vprintf accepts a pointer to a series of arguments, applies to each a format specifier contained in the format string pointed to by format, and outputs the formatted data to stdout. There must be the same number of format specifiers as arguments.

Note:	When you use the SS!=DS flag in 16-bit applications, vprintf assumes that the address being passed is in the SS segment.

Return Value

vprint returns the number of bytes output. In the event of error, vprint returns EOF.


See Also

freopen

printf

va_arg

va_end

va_start


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	 	+	+	 	+


vscanf

See Also	Example	Portability

Syntax

#include <stdarg.h>

int vscanf(const char *format, va_list arglist);

Description

Scans and formats input from stdin.

Note:	Do not use this function for Win32s or Win32 GUI applications.

The v...scanf functions are known as alternate entry points for the ...scanf functions. They behave exactly like their ...scanf counterparts, but they accept a pointer to a list of arguments instead of an argument list.

For details on format specifiers, see Scanf Format Specifiers.

vscanf scans a series of input fields, one character at a time, reading from stdin. Then each field is formatted according to a format specifier passed to vscanf in the format string pointed to by format. Finally, vscanf stores the formatted input at an address passed to it as an argument following format. There must be the same number of format specifiers and addresses as there are input fields.

vscanf might stop scanning a particular field before it reaches the normal end-of-field (whitespace) character, or it might terminate entirely, for a number of reasons. See scanf for a discussion of possible causes.

Return Value

vscanf returns the number of input fields successfully scanned, converted, and stored; the return value does not include scanned fields that were not stored. If no fields were stored, the return value is 0.

If vscanf attempts to read at end-of-file, the return value is EOF.


See Also

freopen

fscanf

scanf

va_arg

va_end

va_start


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


vsprintf

See Also	Example	Portability

Syntax

#include <stdarg.h>

int vsprintf(char *buffer, const char *format, va_list arglist);

Description

Writes formatted output to a string.

The v...printf functions are known as alternate entry points for the ...printf functions. They behave exactly like their ...printf counterparts, but they accept a pointer to a list of arguments instead of an argument list.

For details on format specifiers, see Printf Format Specifiers.

vsprintf accepts a pointer to a series of arguments, applies to each a format specifier contained in the format string pointed to by format, and outputs the formatted data to a string. There must be the same number of format specifiers as arguments.

Return Value

vsprintf returns the number of bytes output. In the event of error, vsprintf returns EOF.


See Also

printf

va_arg

va_end

va_start


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


vsscanf

See Also	Example	Portability

Syntax

#include <stdarg.h>

int vsscanf(const char *buffer, const char *format, va_list arglist);

Description

Scans and formats input from a stream.

The v...scanf functions are known as alternate entry points for the ...scanf functions. They behave exactly like their ...scanf counterparts, but they accept a pointer to a list of arguments instead of an argument list.

For details on format specifiers, see Scanf Format Specifiers.

vsscanf scans a series of input fields, one character at a time, reading from a stream. Then each field is formatted according to a format specifier passed to vsscanf in the format string pointed to by format. Finally, vsscanf stores the formatted input at an address passed to it as an argument following format. There must be the same number of format specifiers and addresses as there are input fields.

vsscanf might stop scanning a particular field before it reaches the normal end-of-field (whitespace) character, or it might terminate entirely, for a number of reasons. See scanf  for a discussion of possible causes.

Return Value

vsscanf returns the number of input fields successfully scanned, converted, and stored; the return value does not include scanned fields that were not stored. If no fields were stored, the return value is 0.

If vsscanf attempts to read at end-of-string, the return value is EOF.


See Also

fscanf

scanf

sscanf

va_arg

va_end

va_start

vfscanf


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


wait

See Also	Portability

Syntax

#include <process.h>

int wait(int *statloc);

Description

Waits for one or more child processes to terminate.

The wait function waits for one or more child processes to terminate. The child processes must be those created by the calling program; wait cannot wait for grandchildren (processes spawned by child processes). If statloc is not NULL, it points to location where wait will store the termination status.

If the child process terminated normally (by calling exit, or returning from main), the termination status word is defined as follows:

Bits 0-7	Zero.

Bits 8-15	The least significant byte of the return code from the child process. This is the value that is passed to exit, or is returned from main. If the child process simply exited from main without returning a value, this value will be unpredictable. If the child process terminated abnormally, the termination status word is defined as follows:

Bits 0-7	Termination information about the child:

 	1	Critical error abort.

 	2	Execution fault, protection exception.

 	3	External termination signal.

Bits 8-15	Zero.

Return Value

When wait returns after a normal child process termination it returns the process ID of the child.

When wait returns after an abnormal child termination it returns -1 to the parent and sets errno to EINTR.

If wait returns without a child process completion it returns a -1 value and sets errno to

ECHILD	No child process exists


See Also

cwait

spawn


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

 	 	 	+	 	 	+


wcstombs

Example	Portability

Syntax

#include <stdlib.h>

size_t wcstombs(char *s, const wchar_t *pwcs, size_t n);

Description

Converts a wchar_t array into a multibyte string.

wcstombs converts the type wchar_t elements contained in pwcs into a multibyte character string s. The process terminates if either a null character or an invalid multibyte character is encountered.

No more than n bytes are modified. If n number of bytes are processed before a null character is reached, the array s is not null terminated.

The behavior of wcstombs is affected by the setting of LC_CTYPE category of the current locale.

Return Value

If an invalid multibyte character is encountered, wcstombs returns (size_t) -1. Otherwise, the function returns the number of bytes modified, not including the terminating code, if any.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


wctomb

Example	Portability

Syntax

#include <stdlib.h>

int wctomb(char *s, wchar_t wc);

Description

Converts wchar_t code to a multibyte character.

If s is not null, wctomb determines the number of bytes needed to represent the multibyte character corresponding to wc (including any change in shift state). The multibyte character is stored in s. At most MB_CUR_MAX characters are stored. If the value of wc is zero, wctomb is left in the initial state.

The behavior of wctomb is affected by the setting of LC_CTYPE category of the current locale.

Return Value

If s is a NULL pointer, wctomb returns a nonzero value if multibyte character encodings do have state-dependent encodings, and a zero value if they do not.

If s is not a NULL pointer, wctomb returns -1 if the wc value does not represent a valid multibyte character. Otherwise, wctomb returns the number of bytes that are contained in the multibyte character corresponding to wc. In no case will the return value be greater than the value of MB_CUR_MAX macro.


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	+	+	+


wherex

See Also	Example	Portability

Syntax

#include <conio.h>

int wherex(void);

Description

Gives horizontal cursor position within window.

Note:	Do not use this function for Win32s or Win32 GUI applications.

wherex returns the x-coordinate of the current cursor position (within the current text window).

Return Value

wherex returns an integer in the range 1 to the number of columns in the current video mode.


See Also

gettextinfo

gotoxy

wherey


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


wherey

See Also	Example	Portability

Syntax

#include <conio.h>

int wherey(void);

Description

Gives vertical cursor position within window.

Note:	Do not use this function for Win32s or Win32 GUI applications.

wherey returns the y-coordinate of the current cursor position (within the current text window).

Return Value

wherey returns an integer in the range 1 to the number of rows in the current video mode.


See Also

gettextinfo

gotoxy

wherex


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


window

See Also	Example	Portability

Syntax

#include <conio.h>

void window(int left, int top, int right, int bottom);

Description

Defines active text mode window.

Note:	Do not use this function for Win32s or Win32 GUI applications.

window defines a text window onscreen. If the coordinates are in any way invalid, the call to window is ignored.

left and top are the screen coordinates of the upper left corner of the window.

right and bottom are the screen coordinates of the lower right corner.

The minimum size of the text window is one column by one line. The default window is full screen, with the coordinates:

  1,1,C,R

where C is the number of columns in the current video mode, and R is the number of rows.

Return Value

None.


See Also

clreol

clrscr

delline

gettextinfo

gotoxy

insline

puttext

textmode


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	 	+	 	 	+


See Also

lseek

_rtl_read

write


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	 	+	+	 	 	+


write

See Also	Example	Portability

Syntax

#include <io.h>

int write(int handle, void *buf, unsigned len);

Description

Writes to a file.

write writes a buffer of data to the file or device named by the given handle. handle is a file handle obtained from a creat, open, dup, or dup2 call.

This function attempts to write len bytes from the buffer pointed to by buf to the file associated with handle. Except when write is used to write to a text file, the number of bytes written to the file will be no more than the number requested. The maximum number of bytes that write can write is UINT_MAX -1, because UINT_MAX is the same as -1, which is the error return indicator for write. On text files, when write sees a linefeed (LF) character, it outputs a CR/LF pair. UINT_MAX is defined in limits.h.

If the number of bytes actually written is less than that requested, the condition should be considered an error and probably indicates a full disk. For disks or disk files, writing always proceeds from the current file pointer. For devices, bytes are sent directly to the device. For files opened with the O_APPEND option, the file pointer is positioned to EOF by write before writing the data.

Return Value

write returns the number of bytes written. A write to a text file does not count generated carriage returns. In case of error, write returns -1 and sets the global variable errno to one of the following values:

EACCES	Permission denied

EBADF	Bad file number


See Also

creat

lseek

open

read

_rtl_write


Portability

DOS	UNIX	Win 16	Win 32	ANSI C	ANSI C++	OS/2

+	+	+	+	 	 	+


abs example
/* abs example */

#include <stdio.h>

#include <math.h>

int main(void)

{

  int number = -1234;

  printf("number: %d  absolute value: %d\n", number, abs(number));

  return 0;

}


cabs Example
/* cabs example */

#include <stdio.h>

#include <math.h>

#ifdef __cplusplus

  #include <complex.h>

#endif

#ifdef __cplusplus /* if C++, use class complex */

  void print_abs(void)

  {

    complex z(1.0, 2.0);

    double  absval;

    absval = abs(z);

    printf("The absolute value of %.2lfi %.2lfj is %.2lf",

      real(z), imag(z), absval);

  }

#else  /* below function is for C (and not C++) */

  void print_abs(void)

  {

    struct complex z;

    double absval;

    z.x = 2.0;

    z.y = 1.0;

    absval = cabs(z);

    printf("The absolute value of %.2lfi %.2lfj is %.2lf",

      z.x, z.y, absval);

  }

#endif

int main(void)

{

  print_abs();

  return 0;

}


fabs example
/* fabs example */

#include <stdio.h>

#include <math.h>

int main(void)

{

   float  number = -1234.0;

   printf("number: %f  absolute value: %f\n", number, fabs(number));

   return 0;

}


labs example
/* labs example */

#include <stdio.h>

#include <math.h>

int main(void)

{

   long result;

   long x = -12345678L;

   result= labs(x);

   printf("number: %ld abs value: %ld\n", x, result);

   return 0;

}


acos example
/* acos example */

#include <stdio.h>

#include <math.h>

int main(void)

{

  double result;

  double x = 0.5;

  result = acos(x);

  printf("The arc cosine of %lf is %lf\n", x, result);

  return 0;

}


asin example
/* asin example */

#include <stdio.h>

#include <math.h>

int main(void)

{

   double result;

   double x = 0.5;

   result = asin(x);

   printf("The arc sin of %lf is %lf\n", x, result);

  return(0);

}


atan example
/* atan example */

#include <stdio.h>

#include <math.h>

int main(void)

{

   double result;

   double x = 0.5;

   result = atan(x);

   printf("The arc tangent of %lf is %lf\n", x, result);

return(0);

}


atan2 example
/* atan2 example */

#include <stdio.h>

#include <math.h>

int main(void)

{

   double result;

   double x = 90.0, y = 45.0;

   result = atan2(y, x);

   printf("The arc tangent ratio of %lf is %lf\n", (y / x), result);

   return 0;

}


alloca example
/* alloca example */

#include <malloc.h>

#include <stdio.h>

#include <stdlib.h>

void test(int a)

{

   char *newstack;

   int len = a;

   char dummy[1];

dummy[0] = 0;         /* force good stack frame */

   printf("SP before calling alloca(0x%X) = 0x%X\n",len,_SP);

   newstack = (char *) alloca(len);

printf("SP after calling alloca = 0x%X\n",_SP);

   if (newstack)

      printf("Alloca(0x%X) returned %p\n",len,newstack);

   else

      printf("Alloca(0x%X) failed\n",len);

}

void main()

{

   test(256);

   test(16384);

}


asctime example
/* asctime example */

#include <string.h>

#include <time.h>

#include <stdio.h>

int main(void)

{

  struct tm t;

  char str[80];

  /* sample loading of tm structure  */

  t.tm_sec    = 1;  /* Seconds */

  t.tm_min    = 30; /* Minutes */

  t.tm_hour   = 9;  /* Hour */

  t.tm_mday   = 22; /* Day of the Month  */

  t.tm_mon    = 11; /* Month */

  t.tm_year   = 56; /* Year - does not include century */

  t.tm_wday   = 4;  /* Day of the week  */

  t.tm_yday   = 0;  /* Does not show in asctime */

  t.tm_isdst  = 0;  /* Is Daylight SavTime; does not show in asctime */

  /* converts structure to null terminated string */

  strcpy(str, asctime(&t));

  printf("%s\n", str);

  return 0;

}


ctime example
/* ctime example */

#include <stdio.h>

#include <time.h>

int main(void)

{

  time_t t;

  time(&t);

  printf("Today's date and time: %s\n", ctime(&t));

  return 0;

}


beginthread example
/* _beginthread example */

#include <stdio.h>

#include <errno.h>

#include <stddef.h>     /* _threadid variable */

#include <process.h>    /* _beginthread, _endthread */

#include <time.h>       /* time, _ctime */

void thread_code(void *threadno)

{

    time_t t;

    time(&t);

    printf("Executing thread number %d, ID = %d, time = %s\n",

        (int)threadno, _threadid, ctime(&t));

    _endthread();

}

void start_thread(int i)

{

    int thread_id;

#if     defined(__WIN32__)

    if ((thread_id = _beginthread(thread_code,4096,(void *)i)) == (unsigned long)-1)

#else

    if ((thread_id = _beginthread(thread_code,4096,(void *)i)) == -1)

#endif

    {

        printf("Unable to create thread %d, errno = %d\n",i,errno);

        return;

    }

    printf("Created thread %d, ID = %ld\n",i,thread_id);

}

int main(void)

{

    int i;

    for (i = 1; i < 20; i++)

        start_thread(i);

    printf("Hit ENTER to exit main thread.\n");

    getchar();

    return 0;

}


_beginthreadNT example
/* beginthreadNT example */

#include        <windows.h>

#include        <process.h>

#include        <stdio.h>

#include        <conio.h>

/*      This function acts as the 'main' function for each new thread.

static  void    threadMain(void *arg) */

{

        printf("Thread %2d has an ID of %u\n", (int)arg, GetCurrentThreadId());

        _endthread();

}

int     main(void)

{

        #define NTHREADS        25

        HANDLE  hThreads[NTHREADS];

        int     i;

        //      Create NTHREADS inheritable threads that are initially

        //      suspended and that will run starting at threadMain().

        //      at threadMain().

        for     (i = 0; i < NTHREADS; i++)

        {

                SECURITY_ATTRIBUTES     sa =

                {

                        sizeof(SECURITY_ATTRIBUTES),    // structure size

                        0,                              // No security descriptor

                        TRUE,                           // Thread handle is inheritable

                };

                DWORD   threadId;

                hThreads[i] = (HANDLE)_beginthreadNT(

                                        threadMain,             // Thread starting address

                                        4096,                   // Thread stack size

                                        (void *)i,              // Thread start argument

                                        &sa,                    // Thread security

                                        CREATE_SUSPENDED,       // Create in suspended state

                                        &threadId);             // Thread ID.

                if      (hThreads[i] == INVALID_HANDLE_VALUE)

                {

                        MessageBox(0, "Thread Creation Failed", "Error", MB_OK);

                        return  1;

                }

                printf("Created thread %2d with an ID of %u\n", i, threadId);

        }

        printf("\nPress a key to thaw all threads\n\n");

        getch();

        //      Resume the suspended threads.

        for     (i = 0; i < NTHREADS; i++)

                ResumeThread(hThreads[i]);

        //      Wait for all threads to finish execution.

        WaitForMultipleObjects(NTHREADS,        // Number of objects to wait for

                               hThreads,        // The objects to wait for

                               TRUE,            // Wait for all objects

                               INFINITE);       // No timeout

        //      Close all of the thread handles.

        for     (i = 0; i < NTHREADS; i++)

                CloseHandle(hThreads[i]);

        return  0;

}


biosequip example
/* biosequip example */

#include <bios.h>

#include <stdio.h>

#define CO_PROCESSOR_MASK 0x0002

int main(void)

{

  int equip_check;

   /* get the current equipment configuration */

   equip_check = biosequip();

   /* check to see if there is a coprocessor installed */

   if (equip_check & CO_PROCESSOR_MASK)

      printf("There is a math coprocessor installed.\n");

   else

      printf("No math coprocessor installed.\n");

   return 0;

}


_bios_equiplist example
/* _bios_equiplist example */

#include <stdio.h>

#include <bios.h>

#define CO_PROCESSOR_MASK 0x0002

int main(void)

{

  unsigned equip_check;

  /* get the current equipment configuration */

  equip_check = _bios_equiplist();

  /* check to see if there is a coprocessor installed */

  if (equip_check & CO_PROCESSOR_MASK)

    printf("There is a math coprocessor installed.\n");

   else

    printf("No math coprocessor installed.\n");

  return 0;

}


biosmemory example
/* biosmemory example */

#include <stdio.h>

#include <bios.h>

int main(void)

{

   int memory_size;

   memory_size = biosmemory();  /* returns value up to 640K */

   printf("RAM size = %dK\n",memory_size);

   return 0;

}


_bios_memsize example
/* _bios_memsize example */

#include <stdio.h>

#include <bios.h>

int main(void)

{

  unsigned   memory_size;

  memory_size = _bios_memsize();   /* returns value up to 640K */

  printf("RAM size = %dK\n", memory_size);

  return 0;

}


biostime example
/* biostime example */

#include <stdio.h>

#include <bios.h>

#include <time.h>

#include <conio.h>

int main(void)

{

  long bios_time;

   clrscr();

   printf("The number of clock ticks since midnight is:\n");

   printf("The number of seconds since midnight is:\n");

   printf("The number of minutes since midnight is:\n");

   printf("The number of hours since midnight is:\n");

   printf("\nPress any key to stop:");

   while(!kbhit())

   {

      bios_time = biostime(0, 0L);

      gotoxy(50, 1);

      printf("%lu", bios_time);

      gotoxy(50, 2);

      printf("%.4f", bios_time / _BIOS_CLK_TCK);

      gotoxy(50, 3);

      printf("%.4f", bios_time / _BIOS_CLK_TCK / 60);

      gotoxy(50, 4);

      printf("%.4f", bios_time / _BIOS_CLK_TCK / 3600);

   }

   return 0;

}


_bios_timeofday example
/* _bios_timeofday example */

#include <bios.h>

#include <time.h>

#include <conio.h>

#include <stdio.h>

int main(void)

{

  long bios_time;

  clrscr();

  printf("The number of clock ticks since midnight is:\n");

  printf("The number of seconds since midnight is:\n");

  printf("The number of minutes since midnight is:\n");

  printf("The number of hours since midnight is:\n");

  printf("\nPress any key to stop:");

  while(!kbhit())

  {

    _bios_timeofday(_TIME_GETCLOCK, &bios_time);

    gotoxy(50, 1);

    printf("%lu", bios_time);

    gotoxy(50, 2);

    printf("%.4f", bios_time / CLK_TCK);

    gotoxy(50, 3);

    printf("%.4f", bios_time / CLK_TCK / 60);

    gotoxy(50, 4);

    printf("%.4f", bios_time / CLK_TCK / 3600);

  }

  return 0;

}


bsearch example
/* bsearch example */

#include <stdlib.h>

#include <stdio.h>

typedef int (*fptr)(const void*, const void*);

#define NELEMS(arr) (sizeof(arr) / sizeof(arr[0]))

int numarray[] = {123, 145, 512, 627, 800, 933};

int numeric (const int *p1, const int *p2)

{

   return(*p1 - *p2);

}

#pragma argsused

int lookup(int key)

{

   int  *itemptr;

   /* The cast of (int(*)(const void *,const void*))

      is needed to avoid a type mismatch error at

      compile time */

   itemptr = (int *) bsearch (&key, numarray, NELEMS(numarray),

      sizeof(int), (fptr)numeric);

   return (itemptr != NULL);

}

int main(void)

{

   if (lookup(512))

      printf("512 is in the table.\n");

   else

      printf("512 isn't in the table.\n");

   return 0;

}


lfind example
/* lfind example */

#include <stdio.h>

#include <stdlib.h>

int compare(int *x, int *y)

{

   return( *x - *y );

}

int main(void)

{

   int array[5] = {35, 87, 46, 99, 12};

   size_t nelem = 5;

   int key;

   int *result;

   key = 99;

   result = (int *) lfind(&key, array, &nelem,

      sizeof(int), (int(*)(const void *,const void *))compare);

   if (result)

      printf("Number %d found\n",key);

   else

      printf("Number %d not found\n",key);

   return 0;

}


lsearch example
/* lsearch example */

#include <stdlib.h>

#include <stdio.h>

#include <string.h>     /* for strcmp declaration */

/* initialize number of colors */

char *colors[10] = { "Red", "Blue", "Green" };

int ncolors = 3;

int colorscmp(char **arg1, char **arg2)

{

   return(strcmp(*arg1, *arg2));

}

int addelem(char **key)

{

   int oldn = ncolors;

   lsearch(key, colors, (size_t *)&ncolors, sizeof(char *),

     (int(*)(const void *,const void *))colorscmp);

   return(ncolors == oldn);

}

int main(void)

{

   int i;

   char *key = "Purple";

   if (addelem(&key))

      printf("%s already in colors table\n", key);

   else

   {

      printf("%s added to colors table\n", key);

   }

   printf("The colors:\n");

   for (i = 0; i < ncolors; i++)

      printf("%s\n", colors[i]);

   return 0;

}


qsort example
/* qsort example */

#include <stdio.h>

#include <stdlib.h>

#include <string.h>

int sort_function( const void *a, const void *b);

char list[5][4] = { "cat", "car", "cab", "cap", "can" };

int main(void)

{

   int  x;

   qsort((void *)list, 5, sizeof(list[0]), sort_function);

   for (x = 0; x < 5; x++)

      printf("%s\n", list[x]);

   return 0;

}

int sort_function( const void *a, const void *b)

{

   return( strcmp((char *)a,(char *)b) );

}


_rtl_chmod example
/* _rtl_chmod example */

#include <errno.h>

#include <stdio.h>

#include <dos.h>

#include <io.h>

int get_file_attrib(char *filename);

int main(void)

{

  char filename[128];

  int attrib;

  printf("Enter a filename:");

  scanf("%s", filename);

  attrib = get_file_attrib(filename);

  if (attrib == -1)

     switch(errno)

     {

        case ENOENT : printf("Path or file not found.\n");

                      break;

        case EACCES : printf("Permission denied.\n");

                      break;

        default:      printf("Error number: %d", errno);

                      break;

     }

  else

     {

        if (attrib & FA_RDONLY)

           printf("%s is read-only.\n", filename);

        if (attrib & FA_HIDDEN)

           printf("%s is hidden.\n", filename);

        if (attrib & FA_SYSTEM)

           printf("%s is a system file.\n", filename);

        if (attrib & FA_DIREC)

           printf("%s is a directory.\n", filename);

        if (attrib & FA_ARCH)

           printf("%s is an archive file.\n", filename);

     }

  return 0;

}

/* returns the attributes of a DOS file */

int get_file_attrib(char *filename)

{

   return(_rtl_chmod(filename, 0));

}


_dos_getfileattr example
/* _dos_getfileattr example */

#include <stdio.h>

#include <dos.h>

int main(void)

{

  char filename[128];

  unsigned attrib;

  printf("Enter a file name:");

  scanf("%s", filename);

  if (_dos_getfileattr(filename,&attrib) != 0)

  {

    perror("Unable to obtain file attributes");

    return 1;

  }

  if (attrib & _A_RDONLY)

    printf("%s is read-only.\n", filename);

  if (attrib & _A_HIDDEN)

    printf("%s is hidden.\n", filename);

  if (attrib & _A_SYSTEM)

    printf("%s is a system file.\n", filename);

  if (attrib & _A_VOLID)

    printf("%s is a volume label.\n", filename);

  if (attrib & _A_SUBDIR)

    printf("%s is a directory.\n", filename);

  if (attrib & _A_ARCH)

    printf("%s is an archive file.\n", filename);

  return 0;

}


_dos_setfileattr example
/* _dos_setfileattr example */

#include <stdio.h>

#include <dos.h>

int main(void)

{

  char filename[128];

  unsigned attrib;

  printf("Enter a file name:");

  scanf("%s", filename);

  if (_dos_getfileattr(filename,&attrib) != 0)

  {

    perror("Unable to obtain file attributes");

    return 1;

  }

  if (attrib & _A_RDONLY)

  {

    printf("%s currently read-only, making it read-write.\n", filename);

    attrib &= ~_A_RDONLY;

  }

  else

  {

    printf("%s currently read-write, making it read-only.\n", filename);

    attrib |= _A_RDONLY;

  }

  if (_dos_setfileattr(filename,attrib) != 0)

    perror("Unable to set file attributes");

  return 0;

}


close example
/* close example */

#include <string.h>

#include <stdio.h>

#include <fcntl.h>

#include <io.h>

main()

{

  int handle;

  char buf[11] = "0123456789";

  /* create a file containing 10 bytes */

  handle = open("NEW.FIL", O_CREAT);

  if (handle > -1)

  {

    write(handle, buf, strlen(buf));

    close(handle);                    /* close the file */

  }

  else

  {

    printf("Error opening file\n");

  }

  return 0;

}


_rtl_close example
/* _rtl_close example */

#include <string.h>

#include <stdio.h>

#include <fcntl.h>

#include <io.h>

int main(void)

{

   int handle;

   char msg[] = "Hello world";

   if ((handle = _rtl_open("TEST.$$$", O_RDWR)) == -1)

   {

      perror("Error:");

      return 1;

   }

   _rtl_write(handle, msg, strlen(msg));

   _rtl_close(handle);

   return 0;

}


_dos_close example
/* _dos_close example */

#include <dos.h>

#include <string.h>

#include <stdio.h>

int main(void)

{

  unsigned count;

  int handle;

  char buf[11] = "0123456789";

  /* create a file containing 10 bytes */

  if (_dos_creat("DUMMY.FIL", _A_NORMAL, &handle) != 0)

  {

    perror("Unable to create DUMMY.FIL");

    return 1;

  }

  if (_dos_write(handle, buf, strlen(buf), &count) != 0)

  {

    perror("Unable to write to DUMMY.FIL");

    return 1;

  }

  /* close the file */

  _dos_close(handle);

  return 0;

}


cos example
/* cos example */

#include <stdio.h>

#include <math.h>

int main(void)

{

   double result;

   double x = 0.5;

   result = cos(x);

   printf("The cosine of %lf is %lf\n", x, result);

   return 0;

}


sin example
/* sin example */

#include <stdio.h>

#include <math.h>

int main(void)

{

   double result, x = 0.5;

   result = sin(x);

   printf("The sin of %lf is %lf\n", x, result);

   return 0;

}


tan example
/* tan example */

#include <stdio.h>

#include <math.h>

int main(void)

{

   double result, x;

   x = 0.5;

   result = tan(x);

   printf("The tan of %lf is %lf\n", x, result);

   return 0;

}


cosh example
/* cosh example */

#include <stdio.h>

#include <math.h>

int main(void)

{

   double result;

   double x = 0.5;

   result = cosh(x);

   printf("The hyperbolic cosine of %lf is %lf\n", x, result);

   return 0;

}


sinh example
/* sinh example */

#include <stdio.h>

#include <math.h>

int main(void)

{

   double result, x = 0.5;

   result = sinh(x);

   printf("The hyperbolic sin of %lf is %lf\n", x, result);

   return 0;

}


tanh example
/* tanh example */

#include <stdio.h>

#include <math.h>

int main(void)

{

   double result, x;

   x = 0.5;

   result = tanh(x);

   printf("The hyperbolic tangent of %lf is %lf\n", x, result);

   return 0;

}


creat example
/* creat example */

#include <sys\stat.h>

#include <string.h>

#include <fcntl.h>

#include <io.h>

int main(void)

{

   int handle;

   char buf[11] = "0123456789";

   /* change the default file mode from text to binary */

   _fmode = O_BINARY;

   /* create a binary file for reading and writing */

   handle = creat("DUMMY.FIL", S_IREAD |S_IWRITE);

   /* write 10 bytes to the file */

   write(handle, buf, strlen(buf));

   /* close the file */

   close(handle);

   return 0;

}


_rtl_creat example
/* _rtl_creat example */

#include <dos.h>

#include <string.h>

#include <stdio.h>

#include <io.h>

int main() {

  unsigned count;

  int handle;

  char buf[11] = "0123456789";

  /* Create a 10-byte file using _dos_creat. */

  if (_dos_creat("DUMMY.FIL", _A_NORMAL, &handle) != 0) {

    perror("Unable to _dos_creat DUMMY.FIL");

    return 1;

  }

  if (_dos_write(handle, buf, strlen(buf), &count) != 0) {

    perror("Unable to _dos_write to DUMMY.FIL");

    return 1;

  }

  _dos_close(handle);

  /* Create another 10-byte file using _rtl_creat. */

  if ((handle = _rtl_creat("DUMMY2.FIL", 0)) < 0) {

    perror("Unable to _rtl_create DUMMY2.FIL");

    return 1;

  }

  if (_rtl_write(handle, buf, strlen(buf)) < 0) {

    perror("Unable to _rtl_write to DUMMY2.FIL");

    return 1;

  }

  _rtl_close(handle);

  return 0;

}


_dos_creat example
/* _dos_creat example */

#include <dos.h>

#include <string.h>

#include <stdio.h>

int main(void)

{

  unsigned count;

  int handle;

  char buf[11] = "0123456789";

  /* create a file containing 10 bytes */

  if (_dos_creat("DUMMY.FIL", _A_NORMAL, &handle) != 0)

  {

    perror("Unable to create DUMMY.FIL");

    return 1;

  }

  if (_dos_write(handle, buf, strlen(buf), &count) != 0)

  {

    perror("Unable to write to DUMMY.FIL");

    return 1;

  }

  /* close the file */

  _dos_close(handle);

  return 0;

}


_dos_creatnew example
/* _dos_creatnew example */

#include <dos.h>

#include <string.h>

#include <stdio.h>

int main(void)

{

  unsigned count;

  int handle;

  char buf[11] = "0123456789";

  /* create a file containing 10 bytes */

  if (_dos_creatnew("DUMMY.FIL", _A_NORMAL, &handle) != 0)

  {

    perror("Unable to create DUMMY.FIL");

    return 1;

  }

  if (_dos_write(handle, buf, strlen(buf), &count) != 0)

  {

    perror("Unable to write to DUMMY.FIL");

    return 1;

  }

  /* close the file */

  _dos_close(handle);

  return 0;

}


creatnew example
/* creatnew example */

#include <string.h>

#include <stdio.h>

#include <errno.h>

#include <dos.h>

#include <io.h>

int main(void)

{

   int handle;

   char buf[11] = "0123456789";

   /* attempt to create a file that doesn't already exist */

   handle = creatnew("DUMMY.FIL", 0);

if (handle == -1)

      printf("DUMMY.FIL already exists.\n");

   else

   {

      printf("DUMMY.FIL successfully created.\n");

      write(handle, buf, strlen(buf));

      close(handle);

   }

   return 0;

}


disable example
/* disable example */

/* * * * * * * * * *

NOTE: This is an interrupt service routine. You cannot compile this program with Test Stack Overflow turned on and get an executable file that operates correctly.

 * * * * * * * * * */

#include <stdio.h>

#include <dos.h>

#include <conio.h>

#define INTR 0X1C    /* The clock tick interrupt */

#ifdef __cplusplus

    #define __CPPARGS ...

#else

    #define __CPPARGS

#endif

void interrupt (*oldhandler)(__CPPARGS);

int count=0;

void interrupt handler(__CPPARGS) /* if C++, need the the ellipsis */

{

/* disable interrupts during the handling of the interrupt */

   disable();

/* increase the global counter */

   count++;

/* reenable interrupts at the end of the handler */

enable();

/* call the old routine */

   oldhandler();

}

int main(void)

{

/* save the old interrupt vector */

   oldhandler = getvect(INTR);

/* install the new interrupt handler */

   setvect(INTR, handler);

/* loop until the counter exceeds 20 */

   while (count < 20)

      printf("count is %d\n",count);

/* reset the old interrupt handler */

   setvect(INTR, oldhandler);

return 0;

}


_disable example
/* _disable example */

/* * * * * * * * * *

NOTE: This is an interrupt service routine. You cannot compile this program with Test Stack Overflow turned on and get an executable file that operates correctly.

 * * * * * * * * * */

#include <stdio.h>

#include <dos.h>

#include <conio.h>

#define INTR 0X1C    /* The clock tick interrupt */

#ifdef __cplusplus

    #define __CPPARGS ...

#else

    #define __CPPARGS

#endif

void interrupt (*oldhandler)(__CPPARGS);

int count=0;

void interrupt handler(__CPPARGS) /* if C++, need the the ellipsis */

{

/* disable interrupts during the handling of the interrupt */

   _disable();

/* increase the global counter */

   count++;

/* reenable interrupts at the end of the handler */

   enable();

/* call the old routine */

   oldhandler();

}

int main(void)

{

/* save the old interrupt vector */

oldhandler = _dos_getvect(INTR);

/* install the new interrupt handler */

   _dos_setvect(INTR, handler);

/* loop until the counter exceeds 20 */

   while (count < 20)

      printf("count is %d\n",count);

/* reset the old interrupt handler */

   _dos_setvect(INTR, oldhandler);

   return 0;

}


enable example
/* enable example */

/* * * * * * * * * *

NOTE: This is an interrupt service routine. You cannot compile this program with Test Stack Overflow turned on and get an executable file that operates correctly.

 * * * * * * * * * */

#include <stdio.h>

#include <dos.h>

#include <conio.h>

#define INTR 0X1C    /* The clock tick interrupt */

#ifdef __cplusplus

    #define __CPPARGS ...

#else

    #define __CPPARGS

#endif

void interrupt (*oldhandler)(__CPPARGS);

int count=0;

void interrupt handler(__CPPARGS) /* if C++, need the the ellipsis */

{

/* disable interrupts during the handling of the interrupt */

   disable();

/* increase the global counter */

   count++;

/* reenable interrupts at the end of the handler */

   enable();

/* call the old routine */

   oldhandler();

}

int main(void)

{

/* save the old interrupt vector */

   oldhandler = getvect(INTR);

/* install the new interrupt handler */

   setvect(INTR, handler);

/* loop until the counter exceeds 20 */

   while (count < 20)

      printf("count is %d\n",count);

/* reset the old interrupt handler */

   setvect(INTR, oldhandler);

   return 0;

}


_enable example
/* _enable example */

/* * * * * * * * * *

NOTE: This is an interrupt service routine. You cannot compile this program with Test Stack Overflow turned on and get an executable file that operates correctly.

 * * * * * * * * * */

#include <stdio.h>

#include <dos.h>

#include <conio.h>

#define INTR 0X1C    /* The clock tick interrupt */

#ifdef __cplusplus

    #define __CPPARGS ...

#else

    #define __CPPARGS

#endif

void interrupt (*oldhandler)(__CPPARGS);

int count=0;

void interrupt handler(__CPPARGS) /* if C++, need the the ellipsis */

{

/* disable interrupts during the handling of the interrupt */

   disable();

/* increase the global counter */

   count++;

/* reenable interrupts at the end of the handler */

   _enable();

/* call the old routine */

   oldhandler();

}

int main(void)

{

/* save the old interrupt vector */

   oldhandler = _dos_getvect(INTR);

/* install the new interrupt handler */

   _dos_setvect(INTR, handler);

/* loop until the counter exceeds 20 */

   while (count < 20)

      printf("count is %d\n",count);

/* reset the old interrupt handler */

   _dos_setvect(INTR, oldhandler);

   return 0;

}


div example
/* div example */

/* div example */

#include <stdlib.h>

#include <stdio.h>

div_t x;

int main(void)

{

   x = div(10,3);

   printf("10 div 3 = %d remainder %d\n",

   x.quot, x.rem);

   return 0;

}


ldiv example
/* ldiv example */

/* ldiv example */

#include <stdlib.h>

#include <stdio.h>

int main(void)

{

   ldiv_t lx;

   lx = ldiv(100000L, 30000L);

  printf("100000 div 30000 = %ld remainder %ld\n", lx.quot, lx.rem);

   return 0;

}


dup example
/* dup example */

#include <string.h>

#include <stdio.h>

#include <conio.h>

#include <io.h>

void flush(FILE *stream);

int main(void)

{

  FILE *fp;

  char msg[] = "This is a test";

  /* create a file */

  fp = fopen("DUMMY.FIL", "w");

  /* write some data to the file */

  fwrite(msg, strlen(msg), 1, fp);

  clrscr();

  printf("Press any key to flush DUMMY.FIL:");

  getch();

  /* flush the data to DUMMY.FIL without closing it */

  flush(fp);

  printf("\nFile was flushed, Press any key to quit:");

  getch();

  return 0;

}

void flush(FILE *stream)

{

  int duphandle;

  /* flush TC's internal buffer */

  fflush(stream);

  /* make a duplicate file handle */

  duphandle = dup(fileno(stream));

  /* close the duplicate handle to flush the DOS buffer */

  close(duphandle);

}


dup2 example
/* dup2 example */

#include <sys\stat.h>

#include <string.h>

#include <fcntl.h>

#include <io.h>

int main(void)

{

   #define STDOUT 1

   int nul, oldstdout;

   char msg[] = "This is a test";

   /* create a file */

   nul = open("DUMMY.FIL", O_CREAT | O_RDWR,

      S_IREAD | S_IWRITE);

   /* create a duplicate handle for standard output */

   oldstdout = dup(STDOUT);

   /*

      redirect standard output to DUMMY.FIL

      by duplicating the file handle onto

      the file handle for standard output.

   */

   dup2(nul, STDOUT);

   /* close the handle for DUMMY.FIL */

   close(nul);

   /* will be redirected into DUMMY.FIL */

   write(STDOUT, msg, strlen(msg));

   /* restore original standard output handle */

   dup2(oldstdout, STDOUT);

   /* close duplicate handle for STDOUT */

   close(oldstdout);

   return 0;

}


ecvt example
/* ecvt example */

#include <stdlib.h>

#include <stdio.h>

#include <conio.h>

int main(void)

{

   char *string;

   double value;

   int dec, sign;

   int ndig = 10;

   clrscr();

   value = 9.876;

   string = ecvt(value, ndig, &dec, &sign);

   printf("string = %s      dec = %d sign = %d\n", string, dec, sign);

   value = -123.45;

   ndig= 15;

   string = ecvt(value,ndig,&dec,&sign);

   printf("string = %s dec = %d sign = %d\n", string, dec, sign);

   value = 0.6789e5; /* scientific notation */

   ndig = 5;

   string = ecvt(value,ndig,&dec,&sign);

   printf("string = %s         dec = %d sign = %d\n", string, dec, sign);

   return 0;

}


fcvt example
/* fcvt example */

#include <stdlib.h>

#include <stdio.h>

int main(void)

{

  char *str;

  double num;

  int dec, sign, ndig = 5;

  /* a regular number */

  num = 9.876;

  str = fcvt(num, ndig, &dec, &sign);

  printf("string = %10s decimal place = %d sign = %d\n", str, dec, sign);

  /* a negative number */

  num = -123.45;

  str = fcvt(num, ndig, &dec, &sign);

  printf("string = %10s decimal place = %d sign = %d\n", str, dec, sign);

  /* scientific notation */

  num = 0.678e5;

  str = fcvt(num, ndig, &dec, &sign);

  printf("string = %10s  decimal place= %d  sign = %d\n", str, dec, sign);

  return 0;

}


execl example
/* execl example */

/* execl() example */

#include <stdio.h>

#include <process.h>

int main(int argc, char *argv[])

{

  int loop;

  printf("%s running...\n\n", argv[0]);

  if (argc == 1) {    /* check for only one command-line parameter */

    printf("%s calling itself again...\n", argv[0]);

    execl(argv[0], argv[0], "ONE", "TWO", "THREE", NULL);

    perror("EXEC:");

    exit(1);

  }

  printf("%s called with arguments:\n", argv[0]);

  for (loop = 1; loop <= argc; loop++)

    puts(argv[loop]);       /* Display all command-line parameters */

  return 0;

}


execlp example
/* execlp example */

/* execlp example */

#include <process.h>

#include <stdio.h>

#include <errno.h>

int main( int argc, char *argv[])

{

   int i;

   printf("Command line arguments:\n");

   for (i=0; i < argc; ++i)

      printf("[%2d] %s\n", i, argv[i]);

   printf("About to exec child with arg1 arg2 ...\n");

   execlp("CHILD.EXE", "CHILD.EXE", "arg1", "arg2", NULL);

   perror("exec error");

   exit(1);

   return 0;

}


execle example
/* execle example */

#include <process.h>

#include <stdlib.h>

#include <stdio.h>

int main(int argc, char *argv[], char *env[])

{

  int loop;

  char *new_env[] = { "TESTING", NULL };

  printf("%s running...\n\n", argv[0]);

  if (argc == 1) {   /* check for only one command-line parameter */

    printf("%s calling itself again...\n", argv[0]);

    execle(argv[0], argv[0], "ONE", "TWO", "THREE", NULL, new_env);

    perror("EXEC:");

    exit(1);

  }

  printf("%s called with arguments:\n", argv[0]);

  for (loop = 1; loop <= argc; loop++)

    puts(argv[loop]);  /* display all command-line parameters */

  /* display the first environment parameter */

  printf("value of env[0]: %s\n",env[0]);

  return 0;

}


execlpe example
/* execlpe example */

#include <process.h>

#include <stdio.h>

#include <errno.h>

int main(int argc, char *argv[], char **envp )

{

  int i;

  printf("Command line arguments:\n");

  for (i=0; i < argc; ++i)

    printf("[%2d] : %s\n", i, argv[i]);

  printf("About to exec child with arg1 arg2 ...\n");

  execlpe("CHILD.EXE", "CHILD.EXE", "arg1", "arg2", NULL, envp);

  perror("exec error");

  exit(1);

  return 0;

}


execv example
/* execv example */

#include <process.h>

#include <stdio.h>

#include <errno.h>

int main(int argc, char *argv[])

{

  int i;

  printf("Command line arguments:\n");

  for (i=0; i < argc; i++)

    printf("[%2d] : %s\n", i, argv[i]);

  printf("About to exec child with arg1 arg2 ...\n");

  execv("CHILD.EXE", argv);

  perror("exec error");

  exit(1);

  return 0;

}


execve example
/* execve example */

#include <process.h>

#include <stdio.h>

#include <errno.h>

int main(int argc, char *argv[], char **envp)

{

  int i;

  printf("Command line arguments:\n");

  for (i=0; i < argc; ++i)

    printf("[%2d] : %s\n", i, argv[i]);

  printf("About to exec child with arg1 arg2 ...\n");

  execve("CHILD.EXE", argv, envp);

  perror("exec error");

  exit(1);

  return 0;

}


execvp example
/* execvp example */

#include <process.h>

#include <stdio.h>

#include <errno.h>

int main(int argc, char *argv[])

{

  int i;

  printf("Command line arguments:\n");

  for (i=0; i < argc; ++i)

    printf("[%2d] : %s\n", i, argv[i]);

  printf("About to exec child with arg1 arg2 ...\n");

  execvp("CHILD.EXE", argv);

  perror("exec error");

  exit(1);

  return 0;

}


execvpe example
/* execvpe example */

#include <process.h>

#include <stdio.h>

#include <errno.h>

int main(int argc, char *argv[], char **envp)

{

  int i;

  printf("Command line arguments:\n");

  for (i=0; i < argc; ++i)

    printf("[%2d] : %s\n", i, argv[i]);

  printf("About to exec child with arg1 arg2 ...\n");

  execvpe("CHILD.EXE", argv, envp);

  perror("exec error");

  exit(1);

  return 0;

}


_exit example
/* _exit example */

#include   <stdlib.h>

#include   <stdio.h>

void done(void);

int main(void)

{

   atexit(done);

   _exit(0);

   return 0;

}

void done()

{

   printf("hello\n");

}


_c_exit example
/* _c_exit example */

#include <process.h>

#include <io.h>

#include <fcntl.h>

#include <stdio.h>

#include <dos.h>

main()

{

  int fd;

  char c;

  if ((fd = open("_c_exit.c",O_RDONLY)) < 0)

  {

    printf("Unable to open _c_exit.c for reading\n");

    return 1;

  }

  if (read(fd,&c,1) != 1)

    printf("Unable to read from open file handle %d before _c_exit\n",fd);

  else

    printf("Successfully read from open file handle %d before _c_exit\n",fd);

  printf("Interrupt zero vector before _c_exit = %Fp\n",_dos_getvect(0));

  _c_exit();

  if (read(fd,&c,1) != 1)

    printf("Unable to read from open file handle %d after _c_exit\n",fd);

  else

    printf("Successfully read from open file handle %d after _c_exit\n",fd);

  printf("Interrupt zero vector after _c_exit = %Fp\n",_dos_getvect(0));

 return 0;

}


exit Example
/* exit */

#include <stdlib.h>

#include <conio.h>

#include <stdio.h>

int main(void)

{

   int status;

   printf("Enter either 1 or 2\n");

   status = getch();

   /* Sets DOS errorlevel  */

   exit(status - '0');

/* Note: this line is never reached */

   return 0;

}


_cexit example
/* _cexit example */

#include <windows.h>

#include <process.h>

#include <io.h>

#include <fcntl.h>

#include <stdio.h>

#include <stdlib.h>

void exit_func(void)

{

  printf("Exit function called\n\n");

  printf("Close Window to return to program... It will beep if able to read from file");

}

int main(void)

{

  int fd;

  char c;

  if ((fd = open("_cexit.c",O_RDONLY)) < 0)

  {

printf("Unable to open _cexit.c for reading\n");

return 1;

  }

  atexit(exit_func);

  if (read(fd,&c,1) != 1)

printf("Unable to read from open file handle %d before _cexit\n",fd);

  else

printf("Successfully read from open file handle %d before _cexit\n",fd);

  _cexit();

  if (read(fd,&c,1) == 1)

  MessageBeep(0);

  return 0;

}


farfree example
/* farfree example */

#include <stdio.h>

#include <alloc.h>

#include <string.h>

#include <dos.h>

int main(void)

{

   char far *fptr;

   char *str = "Hello";

   /* allocate memory for the far pointer */

   fptr = (char far *) farcalloc(10, sizeof(char));

   /* copy "Hello" into allocated memory */

/*

Note: movedata is used because you might be in a small data model, in which case a normal string copy routine can't be used since it assumes the pointer size is near.

 */

   movedata(FP_SEG(str), FP_OFF(str),

            FP_SEG(fptr), FP_OFF(fptr),

            strlen(str));

   /* display string (note the F modifier) */

   printf("Far string is: %Fs\n", fptr);

   /* free the memory */

   farfree(fptr);

   return 0;

}


free example
/* free example */

#include <string.h>

#include <stdio.h>

#include <alloc.h>

int main(void)

{

   char *str;

   /* allocate memory for string */

   str = (char *) malloc(10);

   /* copy "Hello" to string */

   strcpy(str, "Hello");

   /* display string */

   printf("String is %s\n", str);

   /* free memory */

   free(str);

   return 0;

}


fgetc example
/* fgetc example */

#include <string.h>

#include <stdio.h>

#include <conio.h>

int main(void)

{

   FILE *stream;

   char string[] = "This is a test";

   char ch;

   /* open a file for update */

   stream = fopen("DUMMY.FIL", "w+");

   /* write a string into the file */

   fwrite(string, strlen(string), 1, stream);

   /* seek to the beginning of the file */

   fseek(stream, 0, SEEK_SET);

   do

   {

      /* read a char from the file */

      ch = fgetc(stream);

      /* display the character */

      putch(ch);

   } while (ch != EOF);

   fclose(stream);

   return 0;

}


fputc example
/* fputc example */

#include <stdio.h>

int main(void)

{

   char msg[] = "Hello world";

   int i = 0;

   while (msg[i])

   {

      fputc(msg[i], stdout);

      i++;

   }

   return 0;

}


fgetchar example
/* fgetchar example */

#include <stdio.h>

int main(void)

{

   char ch;

   /* prompt the user for input */

   printf("Enter a character followed by <Enter>: ");

   /* read the character from stdin */

   ch = fgetchar();

   /* display what was read */

   printf("The character read is: '%c'\n", ch);

   return 0;

}


fputchar example
/* fputchar example */

#include <stdio.h>

int main(void)

{

   char msg[] = "This is a test";

   int i = 0;

   while (msg[i])

   {

      fputchar(msg[i]);

      i++;

   }

   return 0;

}


fgets example
/* fgets example */

#include <string.h>

#include <stdio.h>

int main(void)

{

   FILE *stream;

   char string[] = "This is a test";

   char msg[20];

   /* open a file for update */

   stream = fopen("DUMMY.FIL", "w+");

   /* write a string into the file */

   fwrite(string, strlen(string), 1, stream);

   /* seek to the start of the file */

   fseek(stream, 0, SEEK_SET);

   /* read a string from the file */

   fgets(msg, strlen(string)+1, stream);

   /* display the string */

   printf("%s", msg);

   fclose(stream);

   return 0;

}


fputs example
/* fputs example */

#include <stdio.h>

int main(void)

{

   /* write a string to standard output */

   fputs("Hello world\n", stdout);

   return 0;

}


_dos_findfirst and _dos_findnext example
/* _dos_findfirst and _dos_findnext example */

#include <stdio.h>

#include <dos.h>

int main(void)

{

  struct find_t ffblk;

  int done;

  printf("Directory listing of *.*\n");

  done = _dos_findfirst("*.*",_A_NORMAL,&ffblk);

  while (!done) {

    printf("  %s\n", ffblk.name);

    done = _dos_findnext(&ffblk);

  }

  return 0;

}

/* Program output

Directory listing of *.*

  FINDFRST.C

  FINDFRST.OBJ

  FINDFRST.MAP

  FINDFRST.EXE  */


findfirst and findnext example
/* findfirst and findnext example */

/* findfirst and findnext example */

#include <stdio.h>

#include <dir.h>

int main(void)

{

   struct ffblk ffblk;

   int done;

   printf("Directory listing of *.*\n");

   done = findfirst("*.*",&ffblk,0);

   while (!done)

   {

      printf("  %s\n", ffblk.ff_name);

      done = findnext(&ffblk);

   }

   return 0;

}


_fsopen example
/* _fsopen example */

#include <io.h>

#include <process.h>

#include <share.h>

#include <stdio.h>

int main(void)

{

  FILE *f;

  int status;

  f = _fsopen("c:\\autoexec.bat", "r", SH_DENYNO);

  if (f == NULL)

  {

    printf("_fsopen failed\n");

    exit(1);

  }

  status = access("c:\\autoexec.bat", 6);

  if (status == 0)

    printf("read/write access allowed\n");

  else

    printf("read/write access not allowed\n");

  fclose(f);

  return 0;

}


fdopen example
/* fdopen example */

#include <sys\stat.h>

#include <stdio.h>

#include <fcntl.h>

#include <io.h>

int main(void)

{

   int handle;

   FILE *stream;

   /* open a file */

   handle = open("DUMMY.FIL", O_CREAT,

                  S_IREAD | S_IWRITE);

   /* now turn the handle into a stream */

   stream = fdopen(handle, "w");

   if (stream == NULL)

      printf("fdopen failed\n");

   else

   {

      fprintf(stream, "Hello world\n");

      fclose(stream);

   }

   return 0;

}


fopen example
/* fopen example */

/* Program to create backup of the AUTOEXEC.BAT file */

#include <stdio.h>

int main(void)

{

   FILE *in, *out;

   if ((in = fopen("\\AUTOEXEC.BAT", "rt"))

       == NULL)

   {

      fprintf(stderr, "Cannot open input file.\n");

      return 1;

   }

   if ((out = fopen("\\AUTOEXEC.BAK", "wt"))

       == NULL)

   {

      fprintf(stderr, "Cannot open output file.\n");

      return 1;

   }

   while (!feof(in))

      fputc(fgetc(in), out);

   fclose(in);

   fclose(out);

   return 0;

}


freopen example
/* freopen example */

#include <stdio.h>

int main(void)

{

   /* redirect standard output to a file */

   if (freopen("OUTPUT.FIL", "w", stdout)

       == NULL)

      fprintf(stderr, "error redirecting stdout\n");

   /* this output will go to a file */

   printf("This will go into a file.");

   /* close the standard output stream */

   fclose(stdout);

   return 0;

}


freemem example
/* freemem example */

#include <dos.h>

#include <alloc.h>

#include <stdio.h>

int main(void)

{

   unsigned int size, segp;

   int stat;

   size = 64; /* (64 x 16) = 1024 bytes */

   stat = allocmem(size, &segp);

   if (stat < 0)

      printf("Allocated memory at segment: %x\n", segp);

   else

      printf("Failed: maximum number of\

             paragraphs available is %u\n", stat);

   freemem(segp);

   return 0;

}


fstat example
/* fstat example */

#include <sys\stat.h>

#include <stdio.h>

#include <time.h>

int main(void)

{

   struct stat statbuf;

   FILE *stream;

   /* open a file for update */

   if ((stream = fopen("DUMMY.FIL", "w+"))

       == NULL)

   {

      fprintf(stderr, "Cannot open output file.\n");

      return(1);

   }

   fprintf(stream, "This is a test");

   fflush(stream);

   /* get information about the file */

   fstat(fileno(stream), &statbuf);

   fclose(stream);

   /* display the information returned */

   if (statbuf.st_mode & S_IFCHR)

      printf("Handle refers to a device.\n");

   if (statbuf.st_mode & S_IFREG)

      printf("Handle refers to an ordinary file.\n");

   if (statbuf.st_mode & S_IREAD)

      printf("User has read permission on file.\n");

   if (statbuf.st_mode & S_IWRITE)

      printf("User has write permission on file.\n");

   printf("Drive letter of file: %c\n", 'A'+statbuf.st_dev);

   printf("Size of file in bytes: %ld\n", statbuf.st_size);

   printf("Time file last opened: %s\n", ctime(&statbuf.st_ctime));

   return 0;

}


stat example
/* stat example */

#include <sys\stat.h>

#include <stdio.h>

#include <time.h>

#define FILENAME "TEST.$$$"

int main(void)

{

   struct stat statbuf;

   FILE *stream;

   /* open a file for update */

   if ((stream = fopen(FILENAME, "w+")) == NULL)

   {

      fprintf(stderr, "Cannot open output file.\n");

      return(1);

   }

   /* get information about the file */

   stat(FILENAME, &statbuf);

   fclose(stream);

   /* display the information returned */

   if (statbuf.st_mode & S_IFCHR)

      printf("Handle refers to a device.\n");

   if (statbuf.st_mode & S_IFREG)

      printf("Handle refers to an ordinary file.\n");

   if (statbuf.st_mode & S_IREAD)

      printf("User has read permission on file.\n");

   if (statbuf.st_mode & S_IWRITE)

      printf("User has write permission on file.\n");

   printf("Drive letter of file: %c\n", 'A'+statbuf.st_dev);

   printf("Size of file in bytes: %ld\n", statbuf.st_size);

   printf("Time file last opened: %s\n", ctime(&statbuf.st_ctime));

   return 0;

}


getc example
/* getc example */

#include <stdio.h>

int main(void)

{

   char ch;

   printf("Input a character:");

/* read a character from the

standard input stream */

   ch = getc(stdin);

   printf("The character input was: '%c'\n", ch);

   return 0;

}


putc example
/* putc example */

#include <stdio.h>

int main(void)

{

   char msg[] = "Hello world\n";

   int i = 0;

   while (msg[i])

      putc(msg[i++], stdout);

   return 0;

}


getch example
/* getch example */

#include <conio.h>

#include <stdio.h>

int main(void)

{

  int c;

  int extended = 0;

  c = getch();

  if (!c)

    extended = getch();

  if (extended)

    printf("The character is extended\n");

  else

    printf("The character isn't extended\n");

  return 0;

}


getche example
/* getche example */

#include <stdio.h>

#include <conio.h>

int main(void)

{

   char ch;

   printf("Input a character:");

   ch = getche();

   printf("\nYou input a '%c'\n", ch);

   return 0;

}


getchar example
/* getchar example */

#include <stdio.h>

int main(void)

{

   int c;

/*

Note that getchar reads from stdin and is line buffered; this means it will not return until you press ENTER.

 */

   while ((c = getchar()) != '\n')

      printf("%c", c);

   return 0;

}


putchar example
/* putchar example */

#include <stdio.h>

/* define some box-drawing characters */

#define LEFT_TOP  0xDA

#define RIGHT_TOP 0xBF

#define HORIZ     0xC4

#define VERT      0xB3

#define LEFT_BOT  0xC0

#define RIGHT_BOT 0xD9

int main(void)

{

   char i, j;

   /* draw the top of the box */

   putchar(LEFT_TOP);

   for (i=0; i<10; i++)

      putchar(HORIZ);

   putchar(RIGHT_TOP);

   putchar('\n');

   /* draw the middle */

   for (i=0; i<4; i++)

   {

      putchar(VERT);

      for (j=0; j<10; j++)

         putchar(' ');

      putchar(VERT);

      putchar('\n');

   }

   /* draw the bottom */

   putchar(LEFT_BOT);

   for (i=0; i<10; i++)

      putchar(HORIZ);

   putchar(RIGHT_BOT);

   putchar('\n');

   return 0;

}


getcwd example
/* getcwd example */

#include <stdio.h>

#include <dir.h>

int main(void)

{

   char buffer[MAXPATH];

   getcwd(buffer, MAXPATH);

   printf("The current directory is: %s\n", buffer);

   return 0;

}


_getdcwd example
/* _getdcwd example */

#include <direct.h>

#include <stdio.h>

char buf[65];

void main()

{

  if (_getdcwd(3, buf, sizeof(buf)) == NULL)

    perror("Unable to get current directory of drive C");

  else

    printf("Current directory of drive C is %s\n",buf);

}


_dos_getdate example
/* _dos_getdate example */

#include <dos.h>

#include <stdio.h>

int main(void)

{

  struct dosdate_t d;

  _dos_getdate(&d);

  printf("The current year is: %d\n", d.year);

  printf("The current day is: %d\n", d.day);

  printf("The current month is: %d\n", d.month);

  return 0;

}


_dos_setdate example
/* _dos_setdate example */

#include <dos.h>

#include <process.h>

#include <stdio.h>

int main(void)

{

  struct dosdate_t reset;

  reset.year  = 2001;

  reset.day   = 1;

  reset.month = 1;

  printf("Setting date to 1/1/2001.\n");

  _dos_setdate(&reset);

  system("date");

  return 0;

}


getdate example
/* getdate example */

#include <dos.h>

#include <stdio.h>

int main(void)

{

   struct date d;

   getdate(&d);

   printf("The current year is: %d\n", d.da_year);

   printf("The current day is: %d\n", d.da_day);

   printf("The current month is: %d\n", d.da_mon);

   return 0;

}


setdate example
/* setdate example */

#include <stdio.h>

#include <process.h>

#include <dos.h>

int main(void)

{

   struct date reset;

   struct date save_date;

   getdate(&save_date);

   printf("Original date:\n");

   system("date");

   reset.da_year = 2001;

   reset.da_day = 1;

   reset.da_mon = 1;

   setdate(&reset);

   printf("Date after setting:\n");

   system("date");

   setdate(&save_date);

   printf("Back to original date:\n");

   system("date");

   return 0;

}


_dos_getdiskfree example
/* _dos_getdiskfree example */

#include <stdio.h>

#include <dos.h>

#include <process.h>

int main(void)

{

  struct diskfree_t free;

  long avail;

  if (_dos_getdiskfree(0, &free) != 0) {

    printf("Error in _dos_getdiskfree() call\n");

    exit(1);

  }

  avail = (long) free.avail_clusters

        * (long) free.bytes_per_sector

        * (long) free.sectors_per_cluster;

  printf("The current drive has %ld bytes available\n", avail);

  return 0;

}


getdfree example
/* getdfree example */

#include <stdio.h>

#include <dos.h>

#include <process.h>

int main(void)

{

  struct diskfree_t free;

  long avail;

  if (_dos_getdiskfree(0, &free) != 0) {

    printf("Error in _dos_getdiskfree() call\n");

    exit(1);

  }

  avail = (long) free.avail_clusters

        * (long) free.bytes_per_sector

        * (long) free.sectors_per_cluster;

  printf("The current drive has %ld bytes available\n", avail);

  return 0;

}


_chdrive example
/* _chdrive example */

 #include <stdio.h>

#include <direct.h>

int main(void)

{

  if (_chdrive(3) == 0)

    printf("Successfully changed to drive C:\n");

  else

    printf("Cannot change to drive C:\n");

  return 0;

}


_dos_getdrive example
/* _dos_getdrive example */

#include <stdio.h>

#include <dos.h>

int main(void)

{

  unsigned disk;

  _dos_getdrive(&disk);

  printf("The current drive is: %c\n", disk + 'A' - 1);

  return 0;

}


_dos_setdrive example
/* _dos_setdrive example */

#include <stdio.h>

#include <dos.h>

int main(void)

{

  unsigned maxdrives;

  _dos_setdrive(3,&maxdrives);	/* set drive to C: */

  printf("The number of logical drives is: %d\n", maxdrives);

  return 0;

}


_getdrive example
/* _getdrive example */

#include <stdio.h>

#include <direct.h>

int main(void)

{

  int disk;

  disk = _getdrive() + 'A' - 1;

  printf("The current drive is: %c\n", disk);

  return 0;

}


getdisk example
/* getdisk example */

#include <stdio.h>

#include <dir.h>

int main(void)

{

  int disk, maxdrives = setdisk(2);

  disk = getdisk() + 'A';

  printf("\nThe number of logical drives is:%d\n", maxdrives);

  printf("The current drive is: %c\n", disk);

  return 0;

 }


setdisk example
/* setdisk example */

#include <stdio.h>

#include <dir.h>

int main(void)

{

   int save, disk, disks;

   /* save original drive */

   save = getdisk();

   /* print number of logic drives */

   disks = setdisk(save);

   printf("%d logical drives on the system\n\n", disks);

   /* print the drive letters available */

   printf("Available drives:\n");

   for (disk = 0;disk < 26;++disk)

   {

      setdisk(disk);

      if (disk == getdisk())

         printf("%c: drive is available\n", disk + 'a');

   }

   setdisk(save);

   return 0;

}


getdta example
/* getdta example */

#include <dos.h>

#include <stdio.h>

int main(void)

{

   char far *dta;

   dta = getdta();

   printf("The current disk transfer address is: %Fp\n", dta);

   return 0;

}


setdta example
/* setdta example */

#include <process.h>

#include <string.h>

#include <stdio.h>

#include <dos.h>

int main(void)

{

   char line[80], far *save_dta;

   char buffer[256] = "SETDTA test!";

   struct fcb blk;

   int result;

   /* get new file name from user */

   printf("Enter a file name to create:");

   gets(line);

   /* parse the new file name to the dta */

   parsfnm(line, &blk, 1);

   printf("%d %s\n", blk.fcb_drive, blk.fcb_name);

   /* request DOS services to create file */

   if (bdosptr(0x16, &blk, 0) == -1)

   {

      perror("Error creating file");

      exit(1);

   }

   /* save old dta and set new dta */

   save_dta = getdta();

   setdta(buffer);

   /* write new records */

   blk.fcb_recsize = 256;

   blk.fcb_random = 0L;

   result = randbwr(&blk, 1);

   printf("result = %d\n", result);

   if (!result)

      printf("Write OK\n");

   else

   {

      perror("Disk error");

      exit(1);

   }

   /* request DOS services to close the file */

   if (bdosptr(0x10, &blk, 0) == -1)

   {

      perror("Error closing file");

      exit(1);

   }

   /* reset the old dta */

   setdta(save_dta);

   return 0;

}


getfat example
/* getfat example */

#include <stdio.h>

#include <dos.h>

int main(void)

{

   struct fatinfo diskinfo;

   int flag = 0;

   printf("Please insert disk in drive A\n");

   getchar();

   getfat(1, &diskinfo);

/* get drive information */

   printf("\nDrive A: is ");

   switch((unsigned char) diskinfo.fi_fatid)

   {

      case 0xFD:

        printf("360K low density\n");

        break;

      case 0xF9:

        printf("1.2 Meg high density\n");

        break;

      default:

        printf("unformatted\n");

        flag = 1;

   }

   if (!flag)

   {

      printf("  sectors per cluster %5d\n", diskinfo.fi_sclus);

      printf("   number of clusters %5d\n", diskinfo.fi_nclus);

      printf("     bytes per sector %5d\n", diskinfo.fi_bysec);

   }

   return 0;

}


getfatd example
/* getfatd example */

#include <stdio.h>

#include <dos.h>

int main()

{

   struct fatinfo diskinfo;

   /* get default drive information */

   getfatd(&diskinfo);

   printf("\nDefault Drive:\n");

   printf("sectors per cluster: %5d\n",diskinfo.fi_sclus);

   printf("FAT ID byte:         %5X\n",diskinfo.fi_fatid & 0xFF);

   printf("number of clusters   %5d\n",diskinfo.fi_nclus);

   printf("bytes per sector     %5d\n",diskinfo.fi_bysec);

   return 0;

}


getftime example
/* getftime example */

#include <stdio.h>

#include <io.h>

int main(void)

{

   FILE *stream;

   struct ftime ft;

   if ((stream = fopen("TEST.$$$",

        "wt")) == NULL)

   {

      fprintf(stderr, "Cannot open output file.\n");

      return 1;

   }

   getftime(fileno(stream), &ft);

   printf("File time: %u:%u:%u\n",

          ft.ft_hour, ft.ft_min,

          ft.ft_tsec * 2);

   printf("File date: %u/%u/%u\n",

          ft.ft_month, ft.ft_day,

          ft.ft_year+1980);

   fclose(stream);

   return 0;

}


setftime example
/* setftime example */

#include <stdio.h>

#include <process.h>

#include <fcntl.h>

#include <io.h>

int main(void)

{

   struct ftime filet;

   FILE *fp;

   if ((fp = fopen("TEST.$$$", "w")) == NULL)

   {

      perror("Error:");

      exit(1);

   }

   fprintf(fp, "testing...\n");

   /* load ftime structure with new time and date */

   filet.ft_tsec = 1;

   filet.ft_min = 1;

   filet.ft_hour = 1;

   filet.ft_day = 1;

   filet.ft_month = 1;

   filet.ft_year = 21;

   /* show current directory for time and date */

   system("dir TEST.$$$");

   /* change the time and date stamp*/

   setftime(fileno(fp), &filet);

   /* close and remove the temporary file */

   fclose(fp);

   system("dir TEST.$$$");

   unlink("TEST.$$$");

   return 0;

}


_dos_getftime example
/* _dos_getftime example */

#include <stdio.h>

#include <dos.h>

int main()

{

  FILE *stream;

  unsigned date, time;

  if ((stream = fopen("TEST.$$$", "w")) == NULL)

  {

    fprintf(stderr, "Cannot open output file.\n");

    return 1;

  }

  _dos_getftime(fileno(stream), &date, &time);

  printf("File date: 0x%x\n",date);

  printf("File time: 0x%x\n",time);

  fclose(stream);

  return 0;

}


_dos_setftime example
/* _dos_setftime example */

#include <stdio.h>

#include <dos.h>

int main()

{

  FILE *stream;

  unsigned date, time;

  if ((stream = fopen("TEST.$$$", "w")) == NULL)

  {

    fprintf(stderr, "Cannot open output file.\n");

    return 1;

  }

  _dos_getftime(fileno(stream), &date, &time);

  printf("File year of TEST.$$$: %d\n",((date >> 9) & 0x7f) + 1980);

  date = (date & 0x1ff) | (21 << 9);

  _dos_setftime(fileno(stream), date, time);

  printf("Set file year to 2001.\n");

  fclose(stream);

  return 0;

}


puts example
/* puts example */

#include <stdio.h>

int main(void)

{

   char string[] = "This is an example output string\n";

   puts(string);

   return 0;

}


gets example
/* gets example */

#include <stdio.h>

int main(void)

{

   char string[80];

   printf("Input a string:");

   gets(string);

   printf("The string input was: %s\n", string);

   return 0;

}


puttext example
/* puttext example */

#include <conio.h>

int main(void)

{

   char buffer[512];

   /* put some text to the console */

   clrscr();

   gotoxy(20, 12);

   cprintf("This is a test.  Press any key to continue ...");

   getch();

   /* grab screen contents */

   gettext(20, 12, 36, 21,buffer);

   clrscr();

   /* put selected characters back to the screen */

   gotoxy(20, 12);

   puttext(20, 12, 36, 21, buffer);

   getch();

   return 0;

}


gettext example
/* gettext example */

#include <conio.h>

char buffer[4096];

int main(void)

{

   int i;

   clrscr();

   for (i = 0; i <= 20; i++)

      cprintf("Line #%d\r\n", i);

   gettext(1, 1, 80, 25, buffer);

   gotoxy(1, 25);

   cprintf("Press any key to clear screen...");

   getch();

   clrscr();

   gotoxy(1, 25);

   cprintf("Press any key to restore screen...");

   getch();

   puttext(1, 1, 80, 25, buffer);

   gotoxy(1, 25);

   cprintf("Press any key to quit...");

   getch();

   return 0;

}


_dos_gettime example
/* _dos_gettime example */

#include   <dos.h>

int main(void)

{

  struct dostime_t t;

  _dos_gettime(&t);

  printf("The current time is: %2d:%02d:%02d.%02d\n", t.hour, t.minute,

    t.second, t.hsecond);

  return 0;

}


_dos_settime example
/* _dos_settime example */

#include <dos.h>

#include <process.h>

#include <stdio.h>

int main(void)

{

  struct dostime_t reset;

  reset.hour    = 17;

  reset.minute  = 0;

  reset.second  = 0;

  reset.hsecond = 0;

  printf("Setting time to 5 PM.\n");

  _dos_settime(&reset);

  system("time");

  return 0;

}


gettime example
/* gettime example */

#include   <stdio.h>

#include   <dos.h>

int main(void)

{

   struct  time t;

   gettime(&t);

   printf("The current time is: %2d:%02d:%02d.%02d\n",

          t.ti_hour, t.ti_min, t.ti_sec, t.ti_hund);

   return 0;

}


settime example
/* settime example */

#include <stdio.h>

#include <dos.h>

int main(void)

{

   struct  time t;

   gettime(&t);

   printf("The current minute is: %d\n", t.ti_min);

   printf("The current hour is: %d\n", t.ti_hour);

   printf("The current hundredth of a second is: %d\n", t.ti_hund);

   printf("The current second is: %d\n", t.ti_sec);

   /* Add one to the minutes struct element and then call settime  */

   t.ti_min++;

   settime(&t);

   return 0;

}


_dos_getvect and _dos_setvect example
/* _dos_getvect and _dos_setvect example */

#include <stdio.h>

#include <dos.h>

#ifdef __cplusplus

    #define __CPPARGS ...

#else

    #define __CPPARGS

#endif

void interrupt get_out(__CPPARGS);    /* interrupt prototype */

void interrupt (*oldfunc)(__CPPARGS); /* interrupt function pointer */

int looping = 1;

int main(void)

{

  puts("Press <Shift><PrtSc> to terminate");

  /* save the old interrupt */

  oldfunc  = _dos_getvect(5);

  /* install interrupt handler */

  _dos_setvect(5,get_out);

  /* do nothing */

  while (looping);

  /* restore to original interrupt routine */

  _dos_setvect(5,oldfunc);

  puts("Success");

  return 0;

}

void interrupt get_out(__CPPARGS) {

  looping = 0;             /* change global var to get out of oop */

}


getvect and setvect example
/* getvect and setvect example */

/* * * * * * * * * * * * * * *

NOTE: This is an interrupt service routine.

You can NOT compile this program with

Test Stack Overflow turned on and get an

executable file that will operate correctly.

 * * * * * * * * * * * * * * */

#include <stdio.h>

#include <dos.h>

#include <conio.h>

#define INTR 0X1C    /* The clock tick interrupt */

#ifdef __cplusplus

    #define __CPPARGS ...

#else

    #define __CPPARGS

#endif

void interrupt ( *oldhandler)(__CPPARGS);

int count=0;

void interrupt handler(__CPPARGS)

{

/* increase the global counter */

   count++;

/* call the old routine */

oldhandler();

}

int main(void)

{

/* save the old interrupt vector */

   oldhandler = getvect(INTR);

/* install the new interrupt handler */

   setvect(INTR, handler);

/* loop until the counter exceeds 20 */

while (count < 20)

      printf("count is %d\n",count);

/* reset the old interrupt handler */

   setvect(INTR, oldhandler);

   return 0;

}


getw example
/* getw example */

#include <stdio.h>

#include <stdlib.h>

#define FNAME "test.$$$"

int main(void)

{

FILE *fp;

int word;

/* place the word in a file */

fp = fopen(FNAME, "wb");

if (fp == NULL)

{

printf("Error opening file %s\n", FNAME);

      exit(1);

   }

   word = 94;

   putw(word,fp);

   if (ferror(fp))

       printf("Error writing to file\n");

   else

       printf("Successful write\n");

   fclose(fp);

   /* reopen the file */

   fp = fopen(FNAME, "rb");

   if (fp == NULL)

   {

      printf("Error opening file %s\n", FNAME);

      exit(1);

   }

   /* extract the word */

   word = getw(fp);

   if (ferror(fp))

       printf("Error reading file\n");

   else

       printf("Successful read: word = %d\n", word);

   /* clean up */

   fclose(fp);

   unlink(FNAME);

   return 0;

}


putw example
/* putw example */

#include <stdio.h>

#include <stdlib.h>

#define FNAME "test.$$$"

int main(void)

{

   FILE *fp;

   int word;

   /* place the word in a file */

   fp = fopen(FNAME, "wb");

   if (fp == NULL)

   {

      printf("Error opening file %s\n", FNAME);

      exit(1);

   }

   word = 94;

   putw(word,fp);

   if (ferror(fp))

       printf("Error writing to file\n");

   else

       printf("Successful write\n");

   fclose(fp);

   /* reopen the file */

   fp = fopen(FNAME, "rb");

   if (fp == NULL)

   {

      printf("Error opening file %s\n", FNAME);

      exit(1);

   }

   /* extract the word */

   word = getw(fp);

   if (ferror(fp))

       printf("Error reading file\n");

   else

       printf("Successful read: word = %d\n", word);

   /* clean up */

   fclose(fp);

   unlink(FNAME);

   return 0;

}


gmtime example
/* gmtime example */

#include <stdio.h>

#include <stdlib.h>

#include <time.h>

#include <dos.h>

/* Pacific Standard Time & Daylight Savings */

char *tzstr = "TZ=PST8PDT";

int main(void)

{

   time_t t;

   struct tm *gmt, *area;

   putenv(tzstr);

   tzset();

   t = time(NULL);

   area = localtime(&t);

   printf("Local time is: %s", asctime(area));

   gmt = gmtime(&t);

   printf("GMT is:        %s", asctime(gmt));

   return 0;

}


localtime example
/* localtime example */

#include <time.h>

#include <stdio.h>

#include <dos.h>

int main(void)

{

   time_t timer;

   struct tm *tblock;

   /* gets time of day */

   timer = time(NULL);

   /* converts date/time to a structure */

   tblock = localtime(&timer);

   printf("Local time is: %s", asctime(tblock));

   return 0;

}


heapcheck and _heapchk example
/* heapcheck and _heapchk example */

#include <stdio.h>

#include <alloc.h>

#define NUM_PTRS  10

#define NUM_BYTES 16

int main(void)

{

   char *array[ NUM_PTRS ];

   int i;

   for( i = 0; i < NUM_PTRS; i++ )

      array[ i ] = (char *) malloc( NUM_BYTES );

   for( i = 0; i < NUM_PTRS; i += 2 )

      free( array[ i ] );

   if( heapcheck() == _HEAPCORRUPT )

      printf( "Heap is corrupted.\n" );

   else

      printf( "Heap is OK.\n" );

   return 0;

}


heapcheckfree example
/* heapcheckfree example */

#include <stdio.h>

#include <alloc.h>

#define NUM_PTRS  10

#define NUM_BYTES 16

int main(void)

{

char far *array[ NUM_PTRS ];

int i;

  for( i = 0; i < NUM_PTRS; i++ )

  array[ i ] = (char far *) farmalloc( NUM_BYTES );

  for( i = 0; i < NUM_PTRS; i += 2 )

  farfree( array[ i ] );

  if( farheapcheck() == _HEAPCORRUPT )

    printf( "Heap is corrupted.\n" );

  else

    printf( "Heap is OK.\n" );

  return 0;

}


heapchecknode example
/* heapchecknode example */

#include <stdio.h>

#include <alloc.h>

#define NUM_PTRS  10

#define NUM_BYTES 16

int main(void)

{

   char *array[ NUM_PTRS ];

   int i;

   for( i = 0; i < NUM_PTRS; i++ )

      array[ i ] = (char *) malloc( NUM_BYTES );

   for( i = 0; i < NUM_PTRS; i += 2 )

      free( array[ i ] );

   for( i = 0; i < NUM_PTRS; i++ )

   {

      printf( "Node %2d ", i );

      switch( heapchecknode( array[ i ] ) )

      {

         case _HEAPEMPTY:

              printf( "No heap.\n" );

              break;

         case _HEAPCORRUPT:

              printf( "Heap corrupt.\n" );

              break;

         case _BADNODE:

              printf( "Bad node.\n" );

              break;

         case _FREEENTRY:

              printf( "Free entry.\n" );

              break;

         case _USEDENTRY:

              printf( "Used entry.\n" );

              break;

         default:

              printf( "Unknown return code.\n" );

               break;

      }

   }

   return 0;

}


heapfillfree example
/* heapfillfree example */

#include <stdio.h>

#include <alloc.h>

#include <mem.h>

#define NUM_PTRS  10

#define NUM_BYTES 16

int main(void)

{

   char *array[ NUM_PTRS ];

   int i;

   int res;

   for( i = 0; i < NUM_PTRS; i++ )

      array[ i ] = (char *) malloc( NUM_BYTES );

   for( i = 0; i < NUM_PTRS; i += 2 )

      free( array[ i ] );

   if( heapfillfree( 1 ) < 0 )

   {

      printf( "Heap corrupted.\n" );

      return 1;

   }

   for( i = 1; i < NUM_PTRS; i += 2 )

      memset( array[ i ], 0, NUM_BYTES );

   res = heapcheckfree( 1 );

   if( res < 0 )

      switch( res )

      {

         case _HEAPCORRUPT:

              printf( "Heap corrupted.\n" );

              return 1;

         case _BADVALUE:

              printf( "Bad value in free space.\n" );

              return 1;

         default:

              printf( "Unknown error.\n" );

              return 1;

      }

   printf( "Test successful.\n" );

   return 0;

}


heapwalk example
/* heapwalk example*/

#include <stdio.h>

#include <alloc.h>

#define NUM_PTRS  10

#define NUM_BYTES 16

int main( void )

{

   struct heapinfo hi;

char *array[ NUM_PTRS ];

   int i;

   for( i = 0; i < NUM_PTRS; i++ )

      array[ i ] = (char *) malloc( NUM_BYTES );

   for( i = 0; i < NUM_PTRS; i += 2 )

      free( array[ i ] );

   hi.ptr = NULL;

   printf( "   Size   Status\n" );

   printf( "   ----   ------\n" );

   while( heapwalk( &hi ) == _HEAPOK )

   printf( "%7u    %s\n", hi.size, hi.in_use ? "used" : "free" );

   return 0;

}


_rtl_heapwalk example
/* _rtl_heapwalk example*/

#include <stdio.h>

#include <malloc.h>

#include <alloc.h>

#define NUM_PTRS  10

#define NUM_BYTES 16

#if defined(__FLAT__)

int main( void )

{

struct heapinfo hi;

char *array[ NUM_PTRS ];

int i;

for( i = 0; i < NUM_PTRS; i++ )

array[ i ] = (char *) malloc( NUM_BYTES );

for( i = 0; i < NUM_PTRS; i += 2 )

free( array[ i ] );

hi.ptr = NULL;

printf( "   Size   Status\n" );

printf( "   ----   ------\n" );

while( _rtl_heapwalk( &hi ) == _HEAPOK )

printf( "%7u    %s\n", hi.size, hi.in_use ? "used" : "free" );

return 0;

}

#endif


inp example
/* inp example */

#include <stdio.h>

#include <dos.h>

int main(void)

{

   int result;

   int port = 0;  /* serial port 0 */

   result = inport(port);

   printf("Word read from port %d = 0x%X\n", port, result);

   return 0;

}


inpw example
/* inpw example */

#include <stdio.h>

#include <conio.h>

int main(void)

{

  unsigned result;

  unsigned port = 0;

  result = inpw(port);

  printf("Word read from port %d = 0x%X\n", port, result);

  return 0;

}


outp example
/* outp example */

#include <stdio.h>

#include <conio.h>

int main(void)

{

  unsigned port = 0;

  int value;

  value = outp(port, 'C');

  printf("Value %c sent to port number %d\n", value, port);

  return 0;

}


outpw example
/* outpw example */

#include <stdio.h>

#include <conio.h>

int main(void)

{

  unsigned value;

  unsigned port = 0;

  value = outpw(port, 64);

  printf("Value %d sent to port number %d\n", value, port);

  return 0;

}


inport example
/* inport example */

#include <stdio.h>

#include <dos.h>

int main(void)

{

  int result;

  int port = 0;

  result = inport(port);

  printf("Word read from port %d = 0x%X\n", port, result);

  return 0;

}


inportb example
/* inportb example */

#include <stdio.h>

#include <conio.h>

int main(void)

{

   unsigned char result;

   int port = 0;           /* serial port 1 */

   result = inportb(port);

   printf("Byte read from port %d = 0x%X\n", port, result);

   return 0;

}


outport example
/* outport example */

#include <conio.h>

#include <stdio.h>

int main(void)

{

   int port = 0;

   int value = 'C';

   outport(port, value);

   printf("Value %d sent to port number %d\n", value, port);

   return 0;

}


outportb example
/* outportb example */

#include <stdio.h>

#include <dos.h>

int main(void)

{

int port = 0;

char value = 'C';

outportb(port, value);

   printf("Value %c sent to port number %d\n", value, port);

return 0;

}


int86 example
/* int86 example */

#include <stdio.h>

#include <conio.h>

#include <dos.h>

#define VIDEO 0x10

void movetoxy(int x, int y)

{

union REGS regs;

   regs.h.ah = 2;  /* set cursor position */

regs.h.dh = y;

   regs.h.dl = x;

   regs.h.bh = 0;  /* video page 0 */

int86(VIDEO, &regs, &regs);

}

int main(void)

{

clrscr();

movetoxy(35, 10);

printf("Hello\n");

return 0;

}


int86x example
/* int86x example */

#include <dos.h>

#include <process.h>

#include <stdio.h>

int main(void)

{

char filename[80];

union REGS inregs, outregs;

struct SREGS segregs;

printf("Enter filename: ");

gets(filename);

inregs.h.ah = 0x43;

inregs.h.al = 0x21;

inregs.x.dx = FP_OFF(filename);

segregs.ds = FP_SEG(filename);

int86x(0x21, &inregs, &outregs, &segregs);

   printf("File attribute: %X\n", outregs.x.cx);

   return 0;

}


intdos example
/* intdos example */

#include <stdio.h>

#include <dos.h>

/* deletes file name; returns 0 on success, nonzero on failure */

int delete_file(char near *filename)

{

   union REGS regs;

   int ret;

   regs.h.ah = 0x41;

/* delete file */

   regs.x.dx = (unsigned) filename;

   ret = intdos(&regs, &regs);

   /* if carry flag is set, there was an error */

   return(regs.x.cflag ? ret : 0);

}

int main(void)

{

   int err;

   err = delete_file("NOTEXIST.$$$");

   if (!err)

      printf("Able to delete NOTEXIST.$$$\n");

   else

      printf("Not Able to delete NOTEXIST.$$$\n");

   return 0;

}


intdosx example
/* intdosx example */

#include <stdio.h>

#include <dos.h>

/* deletes file name; returns 0 on success,

nonzero on failure */

int delete_file(char far *filename)

{

   union REGS regs; struct SREGS sregs;

   int ret;

   regs.h.ah = 0x41;                      /* delete file */

   regs.x.dx = FP_OFF(filename);

   sregs.ds = FP_SEG(filename);

   ret = intdosx(&regs, &regs, &sregs);

   /* if carry flag is set, there was an error */

   return(regs.x.cflag ? ret : 0);

}

int main(void)

{

   int err;

   err = delete_file("NOTEXIST.$$$");

   if (!err)

      printf("Able to delete NOTEXIST.$$$\n");

   else

      printf("Not Able to delete NOTEXIST.$$$\n");

   return 0;

}


itoa example
/* itoa example */

#include <stdlib.h>

#include <stdio.h>

int main(void)

{

   int number = 12345;

   char string[25];

   itoa(number, string, 10);

   printf("integer = %d string = %s\n", number, string);

   return 0;

}


ltoa example
/* ltoa example */

#include <stdlib.h>

#include <stdio.h>

int main(void)

{

   char string[25];

   long value = 123456789L;

   ltoa(value,string,10);

   printf("number = %ld  string = %s\n", value, string);

   return 0;

}


ultoa example
/* ultoa example */

#include <stdlib.h>

#include <stdio.h>

int main( void )

{

   unsigned long lnumber = 3123456789L;

   char string[25];

   ultoa(lnumber,string,10);

   printf("string = %s  unsigned long = %lu\n",string,lnumber);

   return 0;

}


keep example
/* keep example */

/* * * * * * * * * * * * *

NOTE: This is an interrupt service routine. You can NOT compile this program with Test Stack Overflow turned on and get an executable file which will operate correctly.

Due to the nature of this function the formula used to compute the number of paragraphs may not necessarily work in all cases.  Use with care!

Terminate Stay Resident (TSR) programs are complex and no other support for them is provided.

Refer to the MS-DOS technical documentation for more information.

 * * * * * * * * * * * * */

#include <dos.h>

/* The clock tick interrupt */

#define INTR 0x1C

/* Screen attribute (blue on grey) */

#define ATTR 0x7900

#ifdef __cplusplus

    #define __CPPARGS ...

#else

    #define __CPPARGS

#endif

/* reduce heaplength and stacklength to make a smaller program in memory */

extern unsigned _heaplen = 1024;

extern unsigned _stklen  = 512;

void interrupt ( *oldhandler)(__CPPARGS);

typedef unsigned int (far *s_arrayptr);

void interrupt handler(__CPPARGS)

{

   s_arrayptr screen[80];

   static int count;

/* For a color screen the video memory is at B800:0000.

   For a monochrome system use B000:000 */

   screen[0] = (s_arrayptr) MK_FP(0xB800,0);

/* increase the counter and keep it within 0 to 9 */

   count++;

   count %= 10;

/* put the number on the screen */

   screen[0][79] = count + '0' + ATTR;

/* call the old interrupt handler */

   oldhandler();

}

int main(void)

{

/* get the address of the current clock

   tick interrupt */

oldhandler = getvect(INTR);

/* install the new interrupt handler */

setvect(INTR, handler);

/* * *

_psp is the starting address of the program in memory.  The top of the stack is the end of the program.

Using _SS and _SP together we can get the end of the stack.  You may want to allow a bit of safety space to insure that enough room is being allocated ie:

   (_SS + ((_SP + safety space)/16) - _psp)

* * */

keep(0, (_SS + (_SP/16) - _psp));

return 0;

}


localeconv example
/* localeconv example */

#include <locale.h>

#include <stdio.h>

int main(void)

{

   struct lconv ll;

   struct lconv *conv = &ll;

/* read the locality conversion structure */

   conv = localeconv();

/* display the structure */

  printf("Decimal Point                 : %s\n", conv-> decimal_point);

  printf("Thousands Separator           : %s\n", conv-> thousands_sep);

  printf("Grouping                      : %s\n", conv-> grouping);

  printf("International Currency symbol : %s\n", conv-> int_curr_symbol);

  printf("$ thousands separator         : %s\n", conv-> mon_thousands_sep);

  printf("$ grouping                    : %s\n", conv-> mon_grouping);

  printf("Positive sign                 : %s\n", conv-> positive_sign);

  printf("Negative sign                 : %s\n", conv-> negative_sign);

  printf("International fraction digits : %d\n", conv-> int_frac_digits);

  printf("Fraction digits               : %d\n", conv-> frac_digits);

  printf("Positive $ symbol precedes    : %d\n", conv-> p_cs_precedes);

  printf("Positive sign space separation: %d\n", conv-> p_sep_by_space);

  printf("Negative $ symbol precedes    : %d\n", conv-> n_cs_precedes);

  printf("Negative sign space separation: %d\n", conv-> n_sep_by_space);

  printf("Positive sign position        : %d\n", conv-> p_sign_posn);

  printf("Negative sign position        : %d\n", conv-> n_sign_posn);

  return 0;

}


setlocale example
/* setlocale example */

#include <locale.h>

#include <stdio.h>

int main(void)

{

   char *old_locale;

   /* The only locale supported in Borland C++ is "C" */

   old_locale = setlocale(LC_ALL,"C");

   printf("Old locale was %s\n",old_locale);

   return 0;

}


locking example
/* locking example */

#include <io.h>

#include <fcntl.h>

#include <process.h>

#include <share.h>

#include <stdio.h>

#include <sys\locking.h>

int main(void)

{

  int handle, status;

  long length;

  /* must have DOS SHARE.EXE loaded for file locking to function */

  handle = sopen("c:\\autoexec.bat", O_RDONLY,SH_DENYNO);

  if (handle < 0) {

    printf("sopen failed\n");

    exit(1);

  }

  length = filelength(handle);

  status = locking(handle,LK_LOCK,length/2);

  if (status == 0)

    printf("lock succeeded\n");

  else

    perror("lock failed");

  status = locking(handle,LK_UNLCK,length/2);

  if (status == 0)

    printf("unlock succeeded\n");

  else

    perror("unlock failed");

  close(handle);

  return 0;

}


lock example
/* lock example */

#include <io.h>

#include <fcntl.h>

#include <sys\stat.h>

#include <process.h>

#include <share.h>

#include <stdio.h>

int main(void)

{

   int handle, status;

   long length;

   /* Must have DOS Share.exe loaded for */

   /* file locking to function properly */

   handle = sopen("c:\\autoexec.bat",

      O_RDONLY,SH_DENYNO,S_IREAD);

   if (handle < 0)

   {

      printf("sopen failed\n");

      exit(1);

   }

   length = filelength(handle);

   status = lock(handle,0L,length/2);

   if (status == 0)

      printf("lock succeeded\n");

   else

      printf("lock failed\n");

   status = unlock(handle,0L,length/2);

   if (status == 0)

      printf("unlock succeeded\n");

   else

      printf("unlock failed\n");

   close(handle);

   return 0;

}


unlock example
/* unlock example */

#include <io.h>

#include <fcntl.h>

#include <sys\stat.h>

#include <process.h>

#include <share.h>

#include <stdio.h>

int main(void)

{

   int handle, status;

   long length;

   handle = sopen("c:\\autoexec.bat",O_RDONLY,SH_DENYNO,S_IREAD);

   if (handle < 0)

   {

       printf("sopen failed\n");

       exit(1);

   }

   length = filelength(handle);

   status = lock(handle,0L,length/2);

   if (status == 0)

      printf("lock succeeded\n");

   else

      printf("lock failed\n");

   status = unlock(handle,0L,length/2);

   if (status == 0)

      printf("unlock succeeded\n");

   else

      printf("unlock failed\n");

   close(handle);

   return 0;

}


log example
/* log example */

#include <math.h>

#include <stdio.h>

int main(void)

{

   double result;

   double x = 8.6872;

   result = log(x);

   printf("The natural log of %lf is %lf\n", x, result);

   return 0;

}


log10 example
/* log10 example */

#include <math.h>

#include <stdio.h>

int main(void)

{

   double result;

   double x = 800.6872;

   result = log10(x);

   printf("The common log of %lf is %lf\n", x, result);

   return 0;

}


_lrotl and _lrotr example
/* _lrotl and _lrotr example */

#include <stdlib.h>

#include <stdio.h>

/* function prototypes */

int lrotl_example(void);

int lrotr_example(void);

/* lrotl example */

int lrotl_example(void)

{

   unsigned long result;

   unsigned long value = 100;

   result = _lrotl(value,1);

   printf("The value %lu rotated left one bit is: %lu\n", value, result);

   return 0;

}

/* lrotr example */

int lrotr_example(void)

{

   unsigned long result;

   unsigned long value = 100;

   result = _lrotr(value,1);

   printf("The value %lu rotated right one bit is: %lu\n", value, result);

   return 0;

}

int main(void)

{

   lrotl_example();

   lrotr_example();

   return 0;

}


_rotl and _rotr example
/* _rotl and _rotr example */

#include <stdlib.h>

#include <stdio.h>

/* rotl example */

int rotl_example(void)

{

   unsigned value, result;

   value = 32767;

   result = _rotl(value, 1);

   printf("The value %u rotated left one bit is: %u\n", value, result);

   return 0;

}

/* rotr example */

int rotr_example(void)

{

   unsigned value, result;

   value = 32767;

   result = _rotr(value, 1);

   printf("The value %u rotated right one bit is: %u\n", value, result);

   return 0;

}

int main(void)

{

   rotl_example();

   rotr_example();

   return 0;

}


_makepath example
/* _makepath example */

#include <dir.h>

#include <string.h>

#include <stdio.h>

#include <stdlib.h>

int main(void)

{

  char s[_MAX_PATH];

  char drive[_MAX_DRIVE];

  char dir[_MAX_DIR];

  char file[_MAX_FNAME];

  char ext[_MAX_EXT];

  getcwd(s,_MAX_PATH);           /* get current working directory */

 if (s[strlen(s)-1] != '\\')

     strcat(s,"\\");             /* append a trailing \ character */

  _splitpath(s,drive,dir,file,ext); /* split the string to separate

    elems */

  strcpy(file,"DATA");

  strcpy(ext,".TXT");

  _makepath(s,drive,dir,file,ext); /* merge everything into one string */

  puts(s);                       /* display resulting string */

  return 0;

}


_splitpath example
/* _splitpath example */

#include <dir.h>

#include <string.h>

#include <stdio.h>

#include <stdlib.h>

int main(void)

{

  char s[_MAX_PATH];

  char drive[_MAX_DRIVE];

  char dir[_MAX_DIR];

  char file[_MAX_FNAME];

  char ext[_MAX_EXT];

  /* get current working directory */

  getcwd(s,_MAX_PATH);

  if (s[strlen(s)-1] != '\\')

  /* append a trailing \ character */

    strcat(s,"\\");

  /* split the string to separate elems */

  _splitpath(s,drive,dir,file,ext);

  strcpy(file,"DATA");

  strcpy(ext,".TXT");

  /* merge everything into one string */

  _makepath(s,drive,dir,file,ext);

  /* display resulting string */

  puts(s);

  return 0;

}


fnsplit example
/* fnsplit example */

#include <stdlib.h>

#include <stdio.h>

#include <dir.h>

int main(void)

{

    char *s;

    char drive[MAXDRIVE];

    char dir[MAXDIR];

    char file[MAXFILE];

    char ext[MAXEXT];

    int flags;

    s=getenv("COMSPEC"); /* get the comspec environment parameter */

    flags=fnsplit(s,drive,dir,file,ext);

    printf("Command processor info:\n");

    if(flags & DRIVE)

       printf("\tdrive: %s\n",drive);

    if(flags & DIRECTORY)

       printf("\tdirectory: %s\n",dir);

    if(flags & FILENAME)

       printf("\tfile: %s\n",file);

    if(flags & EXTENSION)

       printf("\textension: %s\n",ext);

    return 0;

}


fnmerge example
/* fnmerge example */

#include <string.h>

#include <stdio.h>

#include <dir.h>

int main(void)

{

   char s[MAXPATH];

   char drive[MAXDRIVE];

   char dir[MAXDIR];

   char file[MAXFILE];

   char ext[MAXEXT];

   getcwd(s,MAXPATH);              /* get the current working directory */

   strcat(s,"\\");                 /* append on a trailing character */

   fnsplit(s,drive,dir,file,ext);  /* split the string to separate elems */

   strcpy(file,"DATA");

   strcpy(ext,".TXT");

   fnmerge(s,drive,dir,file,ext);   /* merge everything into one string */

   puts(s);                         /* display resulting string */

   return 0;

}


memmove example
/* memmove example */

#include <string.h>

#include <stdio.h>

int main(void)

{

  char *dest = "abcdefghijklmnopqrstuvwxyz0123456789";

  char *src = "******************************";

  printf("destination prior to memmove: %s\n", dest);

  memmove(dest, src, 26);

  printf("destination after memmove:    %s\n", dest);

  return 0;

}


memccpy example
/* memccpy example */

#include <string.h>

#include <stdio.h>

int main(void)

{

   char *src = "This is the source string";

   char dest[50];

   char *ptr;

   ptr = (char *) memccpy(dest, src, 'c', strlen(src));

   if (ptr)

   {

      *ptr = '\0';

      printf("The character was found: %s\n", dest);

   }

   else

      printf("The character wasn't found\n");

   return 0;

}


memcpy example
/* memcpy example */

#include <stdio.h>

#include <string.h>

int main(void)

{

   char src[] = "******************************";

   char dest[] = "abcdefghijlkmnopqrstuvwxyz0123456709";

   char *ptr;

   printf("destination before memcpy: %s\n", dest);

   ptr = (char *) memcpy(dest, src, strlen(src));

   if (ptr)

      printf("destination after memcpy: %s\n", dest);

   else

      printf("memcpy failed\n");

   return 0;

}


memcmp example
/* memcmp example */

#include <stdio.h>

#include <string.h>

int main(void)

{

   char *buf1 = "aaa";

   char *buf2 = "bbb";

   char *buf3 = "ccc";

   int stat;

   stat = memcmp(buf2, buf1, strlen(buf2));

   if (stat > 0)

      printf("buffer 2 is greater than buffer 1\n");

   else

      printf("buffer 2 is less than buffer 1\n");

   stat = memcmp(buf2, buf3, strlen(buf2));

   if (stat > 0)

      printf("buffer 2 is greater than buffer 3\n");

   else

      printf("buffer 2 is less than buffer 3\n");

   return 0;

}


memicmp example
/* memicmp example */

#include <stdio.h>

#include <string.h>

int main(void)

{

   char *buf1 = "ABCDE123";

   char *buf2 = "abcde456";

   int stat;

   stat = memicmp(buf1, buf2, 5);

   printf("The strings to position 5 are ");

   if (stat)

      printf("not ");

   printf("the same\n");

   return 0;

}


_dos_open example
/* _dos_open example */

#include <string.h>

#include <stdio.h>

#include <fcntl.h>

#include <dos.h>

int main(void)

{

  int handle;

  unsigned nbytes;

  char msg[] = "Hello world\n";

  if (_dos_open("TEST.$$$", O_RDWR, &handle) != 0) {

    perror("Unable to open TEST.$$$");

    return 1;

  }

  if (_dos_write(handle, msg, strlen(msg),&nbytes) != 0)

    perror("Unable to write to TEST.$$$");

  printf("%u bytes written to TEST.$$$\n",nbytes);

  _dos_close(handle);

  return 0;

}


_rtl_open example
/* _rtl_open example */

#include <string.h>

#include <stdio.h>

#include <fcntl.h>

#include <io.h>

int main(void)

{

   int handle;

   char msg[] = "Hello world";

   if ((handle = _rtl_open("TEST.$$$", O_RDWR)) == -1)

   {

      perror("Error:");

      return 1;

   }

   _rtl_write(handle, msg, strlen(msg));

   _rtl_close(handle);

   return 0;

}


sopen example
/* sopen example */

/*      Load share before running this example.

*/

 #include <io.h>

 #include <fcntl.h>

 #include <sys\stat.h>

 #include <process.h>

 #include <share.h>

 #include <stdio.h>

 #include       <stdlib.h>

 int main(void)

 {

    int handle,

        handle1;

    handle = sopen("c:\\autoexec.bat", O_RDONLY, SH_DENYWR, S_IREAD);

    if      (handle == -1)

    {

      perror (sys_errlist[errno]);

      exit (1);

    }

    if (!handle)

    {

       printf("sopen failed\n");

       exit(1);

    }

    /*      Attempt sopen for write.

    */

    handle1 = sopen("c:\\autoexec.bat", O_RDONLY, SH_DENYWR, S_IREAD);

    if      (handle1 == -1)

    {

      perror (sys_errlist[errno]);

      exit (1);

    }

    if (!handle1)

    {

       printf("sopen failed\n");

       exit(1);

    }

    close (handle);

    close (handle1);

    return 0;

}


open example
/* open example */

#include <string.h>

#include <stdio.h>

#include <fcntl.h>

#include <io.h>

int main(void)

{

   int handle;

   char msg[] = "Hello world";

   if ((handle = open("TEST.$$$", O_CREAT | O_TEXT)) == -1)

   {

      perror("Error:");

      return 1;

   }

   write(handle, msg, strlen(msg));

   close(handle);

   return 0;

}


cprintf example
/* cprintf example */

#include <conio.h>

int main(void)

{

   /* clear the screen */

   clrscr();

   /* create a text window */

   window(10, 10, 80, 25);

   /* output some text in the window */

   cprintf("Hello world\r\n");

   /* wait for a key */

   getch();

   return 0;

}


fprintf example
/* fprintf example */

#include <stdio.h>

int main(void)

{

   FILE *stream;

   int i = 100;

   char c = 'C';

   float f = 1.234;

   /* open a file for update */

   stream = fopen("DUMMY.FIL", "w+");

   /* write some data to the file */

   fprintf(stream, "%d %c %f", i, c, f);

   /* close the file */

   fclose(stream);

   return 0;

}


printf example
/* printf example */

#include <stdio.h>

#include <string.h>

#define I 555

#define R 5.5

int main(void)

{

   int i,j,k,l;

   char buf[7];

   char *prefix = buf;

   char tp[20];

   printf("prefix  6d      6o      8x        10.2e        "

          "10.2f\n");

   strcpy(prefix,"%");

   for (i = 0; i < 2; i++)

   {

      for (j = 0; j < 2; j++)

         for (k = 0; k < 2; k++)

            for (l = 0; l < 2; l++)

            {

               if (i==0)  strcat(prefix,"-");

               if (j==0)  strcat(prefix,"+");

               if (k==0)  strcat(prefix,"#");

               if (l==0)  strcat(prefix,"0");

               printf("%5s |",prefix);

               strcpy(tp,prefix);

               strcat(tp,"6d |");

               printf(tp,I);

               strcpy(tp,"");

               strcpy(tp,prefix);

               strcat(tp,"6o |");

               printf(tp,I);

               strcpy(tp,"");

               strcpy(tp,prefix);

               strcat(tp,"8x |");

               printf(tp,I);

               strcpy(tp,"");

               strcpy(tp,prefix);

               strcat(tp,"10.2e |");

               printf(tp,R);

               strcpy(tp,prefix);

               strcat(tp,"10.2f |");

               printf(tp,R);

               printf("  \n");

               strcpy(prefix,"%");

            }

       }

   return 0;

}


sprintf example
/* sprintf example */

#include <stdio.h>

#include <math.h>

int main(void)

{

   char buffer[80];

   sprintf(buffer, "An approximation of Pi is %f\n", M_PI);

   puts(buffer);

   return 0;

}


vfprintf example
/* vfprintf example */

#include <stdio.h>

#include <stdlib.h>

#include <stdarg.h>

FILE *fp;

int vfpf(char *fmt, ...)

{

   va_list argptr;

   int cnt;

   va_start(argptr, fmt);

   cnt = vfprintf(fp, fmt, argptr);

   va_end(argptr);

   return(cnt);

}

int main(void)

{

   int inumber = 30;

   float fnumber = 90.0;

   char string[4] = "abc";

   fp = tmpfile();

   if (fp == NULL)

   {

      perror("tmpfile() call");

      exit(1);

   }

   vfpf("%d %f %s", inumber, fnumber, string);

   rewind(fp);

   fscanf(fp,"%d %f %s", &inumber, &fnumber, string);

   printf("%d %f %s\n", inumber, fnumber, string);

   fclose(fp);

   return 0;

}


vprintf example
/* vprintf example */

#include <stdio.h>

#include <stdarg.h>

int vpf(char *fmt, ...)

{

   va_list argptr;

   int cnt;

   va_start(argptr, fmt);

   cnt = vprintf(fmt, argptr);

   va_end(argptr);

   return(cnt);

}

int main(void)

{

   int inumber = 30;

   float fnumber = 90.0;

   char *string = "abc";

   vpf("%d %f %s\n",inumber,fnumber,string);

   return 0;

}


vsprintf example
/* vsprintf example */

#include <stdio.h>

#include <conio.h>

#include <stdarg.h>

char buffer[80];

int vspf(char *fmt, ...)

{

   va_list argptr;

   int cnt;

   va_start(argptr, fmt);

   cnt = vsprintf(buffer, fmt, argptr);

   va_end(argptr);

   return(cnt);

}

int main(void)

{

   int inumber = 30;

   float fnumber = 90.0;

   char string[4] = "abc";

   vspf("%d %f %s", inumber, fnumber, string);

   printf("%s\n", buffer);

   return 0;

}


_dos_read example
/* _dos_read example */

#include <stdio.h>

#include <fcntl.h>

#include <dos.h>

int main(void)

{

  int handle;

  unsigned bytes;

  char buf[10];

  /* Looks for a file in the current directory named TEST.$$$ and

    attempts to read 10 bytes from it. To use this example you

    should create the file TEST.$$$ */

  if (_dos_open("TEST.$$$", O_RDONLY, &handle) != 0) {

    perror("Unable to open TEST.$$$");

    return 1;

  }

  if (_dos_read(handle, buf, 10, &bytes) != 0) {

    perror("Unable to read from TEST.$$$");

    return 1;

  }

  else

    printf("_dos_read: %d bytes read.\n", bytes);

  return 0;

}


_rtl_read example
/* _rtl_read example */

#include <stdio.h>

#include <io.h>

#include <alloc.h>

#include <fcntl.h>

#include <process.h>

#include <sys\stat.h>

int main(void)

{

   void *buf;

   int handle, bytes;

   buf = malloc(10);

/*

Looks for a file in the current directory named TEST.$$$ and attempts to read 10 bytes from it. To use this example you should create the file TEST.$$$

 */

   if ((handle =

       open("TEST.$$$", O_RDONLY | O_BINARY, S_IWRITE | S_IREAD)) == -1)

   {

      printf("Error Opening File\n");

      exit(1);

   }

   if ((bytes = _rtl_read(handle, buf, 10)) == -1) {

      printf("Read Failed.\n");

      exit(1);

   }

   else {

      printf("_rtl_read: %d bytes read.\n", bytes);

   }

   return 0;

}


read example
/* read example */

#include <stdio.h>

#include <io.h>

#include <alloc.h>

#include <fcntl.h>

#include <process.h>

#include <sys\stat.h>

int main(void)

{

   void *buf;

   int handle, bytes;

   buf = malloc(10);

/*

Looks for a file in the current directory named TEST.$$$ and attempts to read 10 bytes from it. To use this example you should create the file TEST.$$$.

 */

   if ((handle =

      open("TEST.$$$", O_RDONLY | O_BINARY, S_IWRITE | S_IREAD)) == -1)

   {

      printf("Error Opening File\n");

      exit(1);

   }

   if ((bytes = read(handle, buf, 10)) == -1) {

      printf("Read Failed.\n");

      exit(1);

   }

   else {

      printf("Read: %d bytes read.\n", bytes);

   }

   return 0;

}


farrealloc example
/* farrealloc example */

#include <stdio.h>

#include <alloc.h>

int main(void)

{

   char far *fptr;

   char far *newptr;

   fptr = (char far *) farmalloc(16);

   printf("First address: %Fp\n", fptr);

/*

We use a second pointer, newptr, so that in the case of farrealloc() returning NULL, our original pointer is not set to NULL.

 */

   newptr = (char far *) farrealloc(fptr,64);

   printf("New address  : %Fp\n", newptr);

   if (newptr != NULL)

      farfree(newptr);

   return 0;

}


realloc example
/* realloc example */

#include <stdio.h>

#include <alloc.h>

#include <string.h>

int main(void)

{

   char *str;

   /* allocate memory for string */

   str = (char *) malloc(10);

   /* copy "Hello" into string */

   strcpy(str, "Hello");

   printf("String is %s\n  Address is %p\n", str, str);

   str = (char *) realloc(str, 20);

   printf("String is %s\n  New address is %p\n", str, str);

   /* free memory */

   free(str);

   return 0;

}


cscanf example
/* cscanf example */

#include <conio.h>

int main(void)

{

   char string[80];

   /* clear the screen */

   clrscr();

   /* Prompt the user for input */

   cprintf("Enter a string with no spaces:");

   /* read the input */

   cscanf("%s", string);

   /* display what was read */

   cprintf("\r\nThe string entered is: %s", string);

   return 0;

}


fscanf example
/* fscanf example */

#include <stdlib.h>

#include <stdio.h>

int main(void)

{

   int i;

   printf("Input an integer: ");

   /* read an integer from the

      standard input stream */

   if (fscanf(stdin, "%d", &i))

      printf("The integer read was: %i\n", i);

   else

   {

      fprintf(stderr, "Error reading an integer from stdin.\n");

      exit(1);

   }

   return 0;

}


scanf example
/* scanf example */

#include <stdio.h>

#include <conio.h>

int main(void)

{

   char label[20];

   char name[20];

   int entries = 0;

   int loop, age;

   double salary;

   struct Entry_struct

   {

      char  name[20];

      int   age;

      float salary;

   } entry[20];

/* Input a label as a string of characters restricting to 20 characters */

   printf("\n\nPlease enter a label for the chart: ");

   scanf("%20s", label);

   fflush(stdin);  /* flush the input stream in case of bad input */

/* Input number of entries as an integer */

  printf("How many entries will there be? (less than 20) ");

  scanf("%d", &entries);

  fflush(stdin);   /* flush the input stream in case of bad input */

/* input a name restricting input to only letters upper or lower case */

   for (loop=0;loop<entries;++loop)

   {

      printf("Entry %d\n", loop);

      printf("  Name   : ");

      scanf("%[A-Za-z]", entry[loop].name);

      fflush(stdin);  /* flush the input stream in case of bad input */

/* input an age as an integer */

      printf("  Age    : ");

      scanf("%d", &entry[loop].age);

      fflush(stdin);  /* flush the input stream in case of bad input */

/* input a salary as a float */

      printf("  Salary : ");

      scanf("%f", &entry[loop].salary);

      fflush(stdin); /* flush the input stream in case of bad input */

   }

/* Input a name, age and salary as a string, integer, and double */

   printf("\nPlease enter your name, age and salary\n");

   scanf("%20s %d %lf", name, &age, &salary);

/* Print out the data that was input */

   printf("\n\nTable %s\n",label);

   printf("Compiled by %s  age %d  $%15.2lf\n", name, age, salary);

   printf("-----------------------------------------------------\n");

   for (loop=0;loop<entries;++loop)

      printf("%4d | %-20s | %5d | %15.2lf\n",

         loop + 1,

         entry[loop].name,

         entry[loop].age,

         entry[loop].salary);

   printf("-----------------------------------------------------\n");

   return 0;

}


sscanf example
/* sscanf example */

#include <stdio.h>

#include <conio.h>

#include <stdlib.h>

char *names[4] = {"Peter", "Mike", "Shea", "Jerry"};

#define NUMITEMS 4

int main(void)

{

   int   loop;

   char  temp[4][80];

   char  name[20];

   int   age;

   long  salary;

/* clear the screen */

   clrscr();

/* create name, age and salary data */

   for (loop=0; loop < NUMITEMS; ++loop)

      sprintf(temp[loop], "%s %d %ld", names[loop], random(10) + 20, random(5000) + 27500L);

/* print title bar */

   printf("%4s | %-20s | %5s | %15s\n", "#", "Name", "Age", "Salary");

   printf("   --------------------------------------------------\n");

/* input a name, age and salary data */

   for (loop=0; loop < NUMITEMS; ++loop)

      {

      sscanf(temp[loop],"%s %d %ld", &name, &age, &salary);

      printf("%4d | %-20s | %5d | %15ld\n", loop + 1, name, age, salary);

      }

   return 0;

}


vfscanf example
/* vfscanf example */

#include <stdio.h>

#include <stdlib.h>

#include <stdarg.h>

FILE *fp;

int vfsf(char *fmt, ...)

{

   va_list  argptr;

   int cnt;

   va_start(argptr, fmt);

   cnt = vfscanf(fp, fmt, argptr);

   va_end(argptr);

   return(cnt);

}

int main(void)

{

   int inumber = 30;

   float fnumber = 90.0;

         char string[4] = "abc";

   fp = tmpfile();

   if (fp == NULL)

   {

      perror("tmpfile() call");

      exit(1);

   }

   fprintf(fp,"%d %f %s\n",inumber,fnumber,string);

   rewind(fp);

   vfsf("%d %f %s",&inumber,&fnumber,string);

   printf("%d %f %s\n",inumber,fnumber,string);

   fclose(fp);

   return 0;

}


vscanf example
/* vscanf example */

#include <stdio.h>

#include <conio.h>

#include <stdarg.h>

int vscnf(char *fmt, ...)

{

   va_list argptr;

   int cnt;

   printf("Enter an integer, a float, and a string (e.g. i,f,s,)\n");

   va_start(argptr, fmt);

   cnt = vscanf(fmt, argptr);

   va_end(argptr);

   return(cnt);

}

int main(void)

{

   int inumber;

   float fnumber;

   char string[80];

   vscnf("%d, %f, %s", &inumber, &fnumber, string);

   printf("%d %f %s\n", inumber, fnumber, string);

   return 0;

}


vsscanf example
/* vsscanf example */

#include <stdio.h>

#include <conio.h>

#include <stdarg.h>

char buffer[80] = "30 90.0 abc";

int vssf(char *fmt, ...)

{

   va_list  argptr;

   int cnt;

   fflush(stdin);

   va_start(argptr, fmt);

   cnt = vsscanf(buffer, fmt, argptr);

   va_end(argptr);

   return(cnt);

}

int main(void)

{

   int inumber;

   float fnumber;

   char string[80];

   vssf("%d %f %s", &inumber, &fnumber, string);

   printf("%d %f %s\n", inumber, fnumber, string);

   return 0;

}


setbuf example
/* setbuf example */

#include <stdio.h>

/* BUFSIZ is defined in stdio.h */

char outbuf[BUFSIZ];

int main(void)

{

   /* attach a buffer to the standard output stream */

   setbuf(stdout, outbuf);

   /* put some characters into the buffer */

   puts("This is a test of buffered output.\n\n");

   puts("This output will go into outbuf\n");

   puts("and won't appear until the buffer\n");

   puts("fills up or we flush the stream.\n");

   /* flush the output buffer */

   fflush(stdout);

   return 0;

}


setvbuf example
/* setvbuf example */

#include <stdio.h>

int main(void)

{

   FILE *input, *output;

   char bufr[512];

   input = fopen("file.in", "r+b");

   output = fopen("file.out", "w");

   /* set up input stream for minimal disk access,

      using our own character buffer */

if (setvbuf(input, bufr, _IOFBF, 512) != 0)

      printf("failed to set up buffer for input file\n");

   else

      printf("buffer set up for input file\n");

   /* set up output stream for line buffering using space that

      will be obtained through an indirect call to malloc */

   if (setvbuf(output, NULL, _IOLBF, 132) != 0)

      printf("failed to set up buffer for output file\n");

   else

      printf("buffer set up for output file\n");

   /* perform file I/O here */

   /* close files */

   fclose(input);

   fclose(output);

   return 0;

}


spawnl example
/* spawnl example */

#include <process.h>

#include <stdio.h>

#include <conio.h>

void spawnl_example(void)

{

   int result;

   clrscr();

   result = spawnl(P_WAIT, "bcc.exe", "bcc.exe", NULL);

   if (result == -1)

   {

      perror("Error from spawnl");

      exit(1);

   }

}

int main(void)

{

  spawnl_example();

  return 0;

}


spawnle example
/* spawnle example */

#include <process.h>

#include <stdio.h>

#include <conio.h>

void spawnle_example(void)

 {

   int result;

   clrscr();

   result = spawnle(P_WAIT, "bcc.exe", "bcc.exe", NULL, NULL);

   if (result == -1)

   {

      perror("Error from spawnle");

      exit(1);

   }

}

int main(void)

{

  spawnle_example();

  return 0;

}


spawnlp example
/* spawnlp example */

#include <process.h>

#include <stdio.h>

#include <errno.h>

void main(int argc, char *argv[])

{

   int i;

   printf("Command line arguments:\n");

   for (i=0; i<argc; ++i)

      printf("[%2d] : %s\n", i, argv[i]);

   printf("About to exec child with arg1 arg2 ...\n");

   spawnlp(P_WAIT, "C:\\BC4\\BIN\\BCC.EXE", "C:\\BC4\\BIN\\BCC.EXE", argv[1], argv[2], NULL);

   perror("exec error");

   exit(1);

}


spawnlpe example
/* spawnlpe example */

#include <process.h>

#include <stdio.h>

#include <errno.h>

int main( int argc, char *argv[], char **envp )

{

   int i;

   printf("Command line arguments:\n");

   for (i=0; i < argc; ++i)

      printf("[%2d] %s\n", i, argv[i]);

   printf("About to exec child with arg1 arg2 ...\n");

   spawnlpe(P_WAIT, "C:\\BC4\\BIN\\BCC.EXE", "C:\\BC4\\BIN\\BCC.EXE", argv[1], argv[2], NULL, envp);

   perror("exec error");

   exit(1);

   return 0;

}


spawnv example
/* spawnv example */

#include <process.h>

#include <stdio.h>

#include <errno.h>

void main(int argc, char *argv[])

{

   int i;

   printf("Command line arguments:\n");

   for (i=0; i<argc; ++i)

      printf("[%2d] : %s\n", i, argv[i]);

   printf("About to exec child with arg1 arg2 ...\n");

spawnv(P_WAIT, "C:\\BC4\\BIN\\BCC.EXE", argv);

   perror("exec error");

   exit(1);

 }


spawnve example
/* spawnve example */

#include <process.h>

#include <stdio.h>

#include <errno.h>

void main(int argc, char *argv[], char **envp)

{

   int i;

   printf("Command line arguments:\n");

   for (i=0; i<argc; ++i)

      printf("[%2d] : %s\n", i, argv[i]);

   printf("About to exec child with arg1 arg2 ...\n");

spawnve(P_WAIT, "C:\\BC4\\BIN\\TDMEM.EXE", argv, envp);

   perror("exec error");

   exit(1);

}


spawnvp example
/* spawnvp example */

#include <process.h>

#include <stdio.h>

#include <errno.h>

void main(int argc, char *argv[])

{

   int i;

   printf("Command line arguments:\n");

   for (i=0; i<argc; ++i)

      printf("[%2d] : %s\n", i, argv[i]);

   printf("About to exec child with arg1 arg2 ...\n");

   spawnvp(P_WAIT, "C:\\BC4\\BIN\\BCC.EXE", argv);

   perror("exec error");

   exit(1);

}


spawnvpe example
/* spawnvpe example */

#include <process.h>

#include <stdio.h>

#include <errno.h>

int main( int argc, char *argv[], char **envp )

{

int i;

printf("Command line arguments:\n");

for (i=0; i < argc; ++i)

printf("[%2d] %s\n", i, argv[i]);

printf("About to exec child with arg1 arg2 ...\n");

spawnvpe(P_WAIT, "C:\\BC4\\BIN\\BCC.EXE", argv, envp);

perror("exec error");

exit(1);

   return 0;

}


strcmp example
/* strcmp example */

#include <string.h>

#include <stdio.h>

int main(void)

{

char *buf1 = "aaa", *buf2 = "bbb", *buf3 = "ccc";

int ptr;

ptr = strcmp(buf2, buf1);

if (ptr > 0)

      printf("buffer 2 is greater than buffer 1\n");

   else

      printf("buffer 2 is less than buffer 1\n");

   ptr = strcmp(buf2, buf3);

   if (ptr > 0)

      printf("buffer 2 is greater than buffer 3\n");

   else

      printf("buffer 2 is less than buffer 3\n");

   return 0;

}


strcmpi example
/* strcmpi example */

/* strncmpi example */

#include <string.h>

#include <stdio.h>

int main(void)

{

   char *buf1 = "BBB", *buf2 = "bbb";

   int ptr;

   ptr = strcmpi(buf2, buf1);

   if (ptr > 0)

      printf("buffer 2 is greater than buffer 1\n");

   if (ptr < 0)

      printf("buffer 2 is less than buffer 1\n");

   if (ptr == 0)

      printf("buffer 2 equals buffer 1\n");

   return 0;

}


stricmp example
/* stricmp example */

#include <string.h>

#include <stdio.h>

int main(void)

{

   char *buf1 = "BBB", *buf2 = "bbb";

   int ptr;

   ptr = stricmp(buf2, buf1);

   if (ptr > 0)

      printf("buffer 2 is greater than buffer 1\n");

   if (ptr < 0)

      printf("buffer 2 is less than buffer 1\n");

   if (ptr == 0)

      printf("buffer 2 equals buffer 1\n");

   return 0;

}


strspn example
/* strspn example */

#include <stdio.h>

#include <string.h>

#include <alloc.h>

int main(void)

{

   char *string1 = "1234567890";

   char *string2 = "123DC8";

   int length;

   length = strspn(string1, string2);

   printf("Character where strings differ is at position %d\n", length);

   return 0;

}


strcspn example
/* strcspn example */

#include <stdio.h>

#include <string.h>

#include <alloc.h>

int main(void)

{

   char *string1 = "1234567890";

   char *string2 = "747DC8";

   int length;

   length = strcspn(string1, string2);

   printf("Character where strings intersect is at position %d\n",

          length);

   return 0;

}


_strerror example
/* _strerror example */

#include <stdio.h>

#include <errno.h>

int main(void)

{

   char *buffer;

   buffer = strerror(errno);

   printf("Error: %s\n", buffer);

   return 0;

}


strerror example
/* strerror example */

#include <stdio.h>

#include <errno.h>

int main(void)

{

  char *buffer;

  buffer = strerror(errno);

  printf("Error: %s\n", buffer);

  return 0;

}


strlwr example
/* strlwr example */

#include <stdio.h>

#include <string.h>

int main(void)

{

   char *string = "Borland International";

   printf("string prior to strlwr: %s\n", string);

   strlwr(string);

   printf("string after strlwr:    %s\n", string);

   return 0;

}


strupr example
/* strupr example */

#include <stdio.h>

#include <string.h>

int main(void)

{

   char *string = "abcdefghijklmnopqrstuvwxyz", *ptr;

   /* converts string to upper case characters */

   ptr = strupr(string);

   printf("%s\n", ptr);

   return 0;

}


strncmp example
/* strncmp example */

#include <string.h>

#include <stdio.h>

int  main(void)

{

   char *buf1 = "aaabbb", *buf2 = "bbbccc", *buf3 = "ccc";

   int ptr;

   ptr = strncmp(buf2,buf1,3);

   if (ptr > 0)

      printf("buffer 2 is greater than buffer 1\n");

   else

      printf("buffer 2 is less than buffer 1\n");

   ptr = strncmp(buf2,buf3,3);

   if (ptr > 0)

      printf("buffer 2 is greater than buffer 3\n");

   else

      printf("buffer 2 is less than buffer 3\n");

   return(0);

}


strncmpi example
/* strncmpi Example */

#include <string.h>

#include <stdio.h>

int main(void)

{

   char *buf1 = "BBBccc", *buf2 = "bbbccc";

   int ptr;

   ptr = strncmpi(buf2,buf1,3);

   if (ptr > 0)

      printf("buffer 2 is greater than buffer 1\n");

   if (ptr < 0)

      printf("buffer 2 is less than buffer 1\n");

   if (ptr == 0)

      printf("buffer 2 equals buffer 1\n");

   return 0;

}


strnicmp example
/* strnicmp Example */

#include <string.h>

#include <stdio.h>

int main(void)

{

   char *buf1 = "BBBccc", *buf2 = "bbbccc";

   int ptr;

   ptr = strnicmp(buf2, buf1, 3);

   if (ptr > 0)

      printf("buffer 2 is greater than buffer 1\n");

   if (ptr < 0)

      printf("buffer 2 is less than buffer 1\n");

   if (ptr == 0)

      printf("buffer 2 equals buffer 1\n");

   return 0;

}


strtod example
/* strtod example */

#include <stdio.h>

#include <stdlib.h>

int main(void)

{

   char input[80], *endptr;

   double value;

   printf("Enter a floating point number:");

   gets(input);

   value = strtod(input, &endptr);

   printf("The string is %s the number is %lf\n", input, value);

   return 0;

}


strtol example
/* strtol example */

#include <stdlib.h>

#include <stdio.h>

int main(void)

{

   char *string = "87654321", *endptr;

   long lnumber;

   /* strtol converts string to long integer  */

   lnumber = strtol(string, &endptr, 10);

   printf("string = %s  long = %ld\n", string, lnumber);

   return 0;

}


strtoul example
/* strtoul example */

#include <stdlib.h>

#include <stdio.h>

int main(void)

{

   char *string = "87654321", *endptr;

   unsigned long lnumber;

   lnumber = strtoul(string, &endptr, 10);

   printf("string = %s  long = %lu\n",

   string, lnumber);

   return 0;

}


textattr example
/* textattr example */

#include <conio.h>

int main(void)

{

   int i;

   clrscr();

   for (i=0; i<9; i++)

   {

       textattr(i + ((i+1) << 4));

       cprintf("This is a test\r\n");

   }

   return 0;

}


textbackground and textcolor example
/* textbackground and textcolor example */

#include <conio.h>

int main(void)

{

   int i, j;

   clrscr();

   for (i=0; i<9; i++)

   {

       for (j=0; j<80; j++)

          cprintf("C");

       cprintf("\r\n");

       textcolor(i+1);

       textbackground(i);

   }

   return 0;

}


time example
/* time example */

#include <time.h>

#include <stdio.h>

#include <dos.h>

int main(void)

{

   time_t t;

   t = time(NULL);

   printf("The number of seconds since January 1, 1970 is %ld",t);

   return 0;

}


stime example
/* stime example */

#include <stdio.h>

#include <time.h>

int main(void)

{

  time_t t;

  t = time(NULL);

  printf("Current date is %s", ctime(&t));

  t -= 24L*60L*60L;  /* Back up to same time previous day */

  stime(&t);

  printf("\nNew date is %s", ctime(&t));

   return 0;

}


tolower example
/* tolower example */

#include <string.h>

#include <stdio.h>

#include <ctype.h>

int main(void)

{

   int length, i;

   char *string = "THIS IS A STRING";

   length = strlen(string);

   for (i=0; i<length; i++)

   {

       string[i] = tolower(string[i]);

   }

   printf("%s\n",string);

   return 0;

}


_tolower example
/* _tolower example */

#include <string.h>

#include <stdio.h>

#include <ctype.h>

int main(void)

{

   int length, i;

   char *string = "THIS IS A STRING.";

   length = strlen(string);

   for (i = 0; i < length; i++) {

       if ((string[i] >= 'A') && (string[i] <= 'Z')){

          string[i] = _tolower(string[i]);

       }

   }

   printf("%s\n",string);

   return 0;

}


toupper example
/* toupper example */

#include <string.h>

#include <stdio.h>

#include <ctype.h>

int main(void)

{

   int length, i;

   char *string = "this is a string";

   length = strlen(string);

   for (i=0; i<length; i++)

   {

      string[i] = toupper(string[i]);

   }

   printf("%s\n",string);

   return 0;

}


_toupper example
/* _toupper example */

#include <string.h>

#include <stdio.h>

#include <ctype.h>

int main(void)

{

   int length, i;

   char *string = "this is a string.";

   length = strlen(string);

   for (i = 0; i < length; i++) {

      if ((string[i] >= 'a') && (string[i] <= 'z')){

         string[i] = _toupper(string[i]);

         }

   }

   printf("%s\n",string);

   return 0;

}


_dos_write example
/* _dos_write example */

#include <dos.h>

#include <string.h>

#include <stdio.h>

int main(void)

{

  unsigned count;

  int handle;

  char buf[11] = "0123456789";

  /* create a file containing 10 bytes */

  if (_dos_creat("DUMMY.FIL", _A_NORMAL, &handle) != 0)

  {

    perror("Unable to create DUMMY.FIL");

    return 1;

  }

  if (_dos_write(handle, buf, strlen(buf), &count) != 0)

  {

    perror("Unable to write to DUMMY.FIL");

    return 1;

  }

  /* close the file */

  _dos_close(handle);

  return 0;

}


_rtl_write example
/* _rtl_write example */

#include <stdio.h>

#include <io.h>

#include <alloc.h>

#include <fcntl.h>

#include <process.h>

#include <sys\stat.h>

int main(void)

{

   void *buf;

   int handle, bytes;

   buf = malloc(200);

/*

Create a file name TEST.$$$ in the current directory and writes 200 bytes to it. If TEST.$$$ already exists, it's overwritten.

 */

   if ((handle = open("TEST.$$$", O_CREAT | O_WRONLY | O_BINARY,

                       S_IWRITE | S_IREAD)) == -1)

   {

      printf("Error Opening File\n");

      exit(1);

   }

   if ((bytes = _rtl_write(handle, buf, 200)) == -1) {

      printf("Write Failed.\n");

      exit(1);

   }

   printf("_rtl_write: %d bytes written.\n",bytes);

   return 0;

}


write example
/* write example */

#include <stdio.h>

#include <stdlib.h>

#include <fcntl.h>

#include <sys\stat.h>

#include <io.h>

#include <string.h>

int main(void)

{

   int handle;

   char string[40];

   int length, res;

/*

Create a file named "TEST.$$$" in the current directory and write a string to it.  If "TEST.$$$" already exists, it will be overwritten.

 */

   if ((handle = open("TEST.$$$", O_WRONLY | O_CREAT | O_TRUNC,

                         S_IREAD | S_IWRITE)) == -1)

   {

      printf("Error opening file.\n");

      exit(1);

   }

   strcpy(string, "Hello, world!\n");

   length = strlen(string);

   if ((res = write(handle, string, length)) != length)

   {

      printf("Error writing to the file.\n");

      exit(1);

   }

   printf("Wrote %d bytes to the file.\n", res);

   close(handle);

   return 0;

}


getcurdir example
/* getcurdir example */

#include <dir.h>

#include <stdio.h>

#include <string.h>

char *current_directory(char *path)

{

  strcpy(path, "X:\\");      /* fill string with form of response: X:\ */

  path[0] = 'A' + getdisk();    /* replace X with current drive letter */

  getcurdir(0, path+3);  /* fill rest of string with current directory */

  return(path);

}

int main(void)

{

  char curdir[MAXPATH];

  current_directory(curdir);

  printf("The current directory is %s\n", curdir);

  return 0;

}


getenv example
/* getenv example */

#include <stdio.h>

#include <stdlib.h>

#include <alloc.h>

#include <string.h>

#include <dos.h>

int main(void)

{

   char *path, *ptr;

   int i = 0;

   /* get the current path environment */

   ptr = getenv("PATH");

   /* set up new path */

   path = (char *) malloc(strlen(ptr)+15);

   strcpy(path,"PATH=");

   strcat(path,ptr);

   strcat(path,";c:\\temp");

   /* replace the current path and display current environment */

   putenv(path);

   while (_environ[i])

       printf("%s\n",_environ[i++]);

   return 0;

}


putenv example
/* putenv example */

#include <stdio.h>

#include <stdlib.h>

#include <alloc.h>

#include <string.h>

#include <dos.h>

int main(void)

{

   char *path, *ptr;

   int i = 0;

   /* get the current path environment */

   ptr = getenv("PATH");

   /* set up new path */

   path = (char *) malloc(strlen(ptr)+15);

   strcpy(path,"PATH=");

   strcat(path,ptr);

   strcat(path,";c:\\temp");

   /* replace the current path and display current environment */

   putenv(path);

   while (_environ[i])

       printf("%s\n",_environ[i++]);

   return 0;

}


getpass example
/* getpass example */

#include <conio.h>

int main(void)

{

   char *password;

   password = getpass("Input a password:");

   cprintf("The password is: %s\r\n", password);

   return 0;

}


getpid example
/* getpid example */

#include <stdio.h>

#include <process.h>

int main()

{

   printf("This program's process identification number (PID) "

          "number is %X\n", getpid());

   printf("Note: under DOS it is the PSP segment\n");

   return 0;

}


gettextinfo example
/* gettextinfo example */

#include <conio.h>

int main(void)

 {

   struct text_info ti;

   gettextinfo(&ti);

   cprintf("window left      %2d\r\n",ti.winleft);

   cprintf("window top       %2d\r\n",ti.wintop);

   cprintf("window right     %2d\r\n",ti.winright);

   cprintf("window bottom    %2d\r\n",ti.winbottom);

   cprintf("attribute        %2d\r\n",ti.attribute);

   cprintf("normal attribute %2d\r\n",ti.normattr);

   cprintf("current mode     %2d\r\n",ti.currmode);

   cprintf("screen height    %2d\r\n",ti.screenheight);

   cprintf("screen width     %2d\r\n",ti.screenwidth);

   cprintf("current x        %2d\r\n",ti.curx);

   cprintf("current y        %2d\r\n",ti.cury);

   return 0;

}


getverify example
/* getverify example */

#include <stdio.h>

#include <conio.h>

#include <dos.h>

int main(void)

{

   int verify_flag;

   printf("Enter 0 to set verify flag off\n");

   printf("Enter 1 to set verify flag on\n");

   verify_flag = getch() - 0;

   setverify(verify_flag);

   if (getverify())

      printf("DOS verify flag is on\n");

   else

      printf("DOS verify flag is off\n");

   return 0;

}


setverify example
/* setverify example */

#include <stdio.h>

#include <conio.h>

#include <dos.h>

int main(void)

{

    int verify_flag;

    printf("Enter 0 to set verify flag off\n");

    printf("Enter 1 to set verify flag on\n");

    verify_flag = getch() - 0;

    setverify(verify_flag);

    if (getverify())

       printf("DOS verify flag is on\n");

    else

       printf("DOS verify flag is off\n");

    return 0;

}


gotoxy example
/* gotoxy example */

#include <conio.h>

int main(void)

{

    clrscr();

    gotoxy(35, 12);

    cprintf("Hello world");

    getch();

    return 0;

}


harderr example
/* harderr example */

/*

This program will trap disk errors and

prompt the user for action. Try running it

with no disk in drive A: to invoke its

functions.

*/

#include <stdio.h>

#include <conio.h>

#include <dos.h>

#define IGNORE  0

#define RETRY   1

#define ABORT   2

int buf[500];

/*

define the error messages for trapping disk problems

*/

 static char *err_msg[] = {

     "write protect",

  "unknown unit",

     "drive not ready",

     "unknown command",

     "data error (CRC)",

     "bad request",

  "seek error",

     "unknown media type",

     "sector not found",

     "printer out of paper",

     "write fault",

     "read fault",

     "general failure",

  "reserved",

     "reserved",

     "invalid disk change"

};

error_win(char *msg)

{

    int retval;

    cputs(msg);

/*

prompt for user to press a key to abort, retry, ignore

*/

    while(1)

    {

  retval= getch();

  if (retval == 'a' || retval == 'A')

  {

      retval = ABORT;

      break;

  }

  if (retval == 'r' || retval == 'R')

  {

retval = RETRY;

      break;

  }

  if (retval == 'i' || retval == 'I')

  {

      retval = IGNORE;

      break;

  }

    }

    return(retval);

}

/*

pragma warn -par reduces warnings which occur

due to the non use of the parameters

not_used1 and not_used2 to the handler.

*/

#pragma warn -par

void handler(unsigned int ax, unsigned int not_used1, unsigned int *not_used2)

{

static char msg[80];

unsigned di;

int drive;

int errorno;

di= _DI;

/*

if this is not a disk error then it was

another device having trouble

*/

if (ax < 0)

{

/* report the error */

error_win("Device error");

/* and return to the program directly requesting abort */

_hardretn(ABORT);

}

/* otherwise it was a disk error */

drive = ax & 0x00FF;

errorno = di & 0x00FF;

/* report which error it was */

sprintf(msg, "Error: %s on drive %c\r\nA)bort, R)etry, I)gnore: ",

  err_msg[errorno], 'A' + drive);

/*

return to the program via dos interrupt 0x23 with abort, retry,

or ignore as input by the user.

*/

_hardresume(error_win(msg));

// return ABORT;

}

#pragma warn +par

int main(void)

{

/*

install our handler on the hardware problem interrupt

*/

_harderr(handler);

   clrscr();

   printf("Make sure there is no disk in drive A:\n");

   printf("Press any key ....\n");

   getch();

   printf("Trying to access drive A:\n");

   printf("fopen returned %p\n",fopen("A:temp.dat", "w"));

   return 0;

}


hardresume example
/* hardresume example */

/*

This program will trap disk errors and

prompt the user for action. Try running it

with no disk in drive A: to invoke its

functions.

*/

#include <stdio.h>

#include <conio.h>

#include <dos.h>

#define IGNORE  0

#define RETRY   1

#define ABORT   2

int buf[500];

/*

define the error messages for trapping disk problems

*/

static char *err_msg[] = {

    "write protect",

 "unknown unit",

 "drive not ready",

    "unknown command",

    "data error (CRC)",

    "bad request",

    "seek error",

    "unknown media type",

    "sector not found",

    "printer out of paper",

    "write fault",

    "read fault",

    "general failure",

 "reserved",

 "reserved",

    "invalid disk change"

};

error_win(char *msg)

{

    int retval;

    cputs(msg);

/*

prompt for user to press a key to abort, retry, ignore

*/

    while(1)

    {

  retval= getch();

  if (retval == 'a' || retval == 'A')

  {

      retval = ABORT;

      break;

  }

  if (retval == 'r' || retval == 'R')

  {

retval = RETRY;

break;

  }

  if (retval == 'i' || retval == 'I')

  {

      retval = IGNORE;

      break;

  }

    }

    return(retval);

}

/*

pragma warn -par reduces warnings which occur

due to the non use of the parameters

not_used1 and not_used2 to the handler.

*/

#pragma warn -par

void handler(unsigned int ax, unsigned int not_used1, unsigned int *not_used2)

{

    static char msg[80];

 unsigned di;

 int drive;

 int errorno;

    di= _DI;

 /*

 if this is not a disk error then it was

 another device having trouble

 */

    if (ax < 0)

 {

 /* report the error */

 error_win("Device error");

 /* and return to the program directly requesting abort */

 _hardretn(ABORT);

    }

 /* otherwise it was a disk error */

    drive = ax & 0x00FF;

    errorno = di & 0x00FF;

 /* report which error it was */

 sprintf(msg, "Error: %s on drive %c\r\nA)bort, R)etry, I)gnore: ",

      err_msg[errorno], 'A' + drive);

 /*

 return to the program via dos interrupt 0x23 with abort, retry,

 or ignore as input by the user.

 */

 _hardresume(error_win(msg));

// return ABORT;

 }

 #pragma warn +par

 int main(void)

 {

 /*

 install our handler on the hardware problem interrupt

 */

 _harderr(handler);

 clrscr();

 printf("Make sure there is no disk in drive A:\n");

 printf("Press any key ....\n");

    getch();

    printf("Trying to access drive A:\n");

    printf("fopen returned %p\n",fopen("A:temp.dat", "w"));

 return 0;

}


highvideo example
/* highvideo example */

#include <conio.h>

int main(void)

{

clrscr();

lowvideo();

cprintf("Low Intensity text\r\n");

highvideo();

gotoxy(1,2);

cprintf("High Intensity Text\r\n");

return 0;

}


lowvideo example
/* lowvideo example */

#include <conio.h>

int main(void)

{

clrscr();

highvideo();

   cprintf("High Intensity Text\r\n");

   lowvideo();

gotoxy(1,2);

   cprintf("Low Intensity Text\r\n");

return 0;

}


normvideo example
/* normvideo example */

#include <conio.h>

int main(void)

{

    normvideo();

    cprintf("NORMAL Intensity Text\r\n");

 return 0;

}


hypot example
/* hypot example */

#include <stdio.h>

#include <math.h>

int main(void)

{

 double result;

 double x = 3.0;

    double y = 4.0;

    result = hypot(x, y);

    printf("The hypotenuse is: %lf\n", result);

    return 0;

}


imag example
/* imag example */

#include <iostream.h>

#include <complex.h>

int main(void)

{

 double x = 3.1, y = 4.2;

    complex z = complex(x,y);

    cout << "z = " << z << "\n";

 cout << "  has real part = " << real(z) << "\n";

    cout << "  and imaginary real part = " << imag(z) << "\n";

    cout << "z has complex conjugate = " << conj(z) << "\n";

 return 0;

}


insline example
/* insline example */

#include <conio.h>

int main(void)

{

    clrscr();

    cprintf("INSLINE inserts an empty line in the text window\r\n");

 cprintf("at the cursor position using the current text\r\n");

    cprintf("background color.  All lines below the empty one\r\n");

    cprintf("move down one line and the bottom line scrolls\r\n");

 cprintf("off the bottom of the window.\r\n");

    cprintf("\r\nPress any key to continue:");

 gotoxy(1, 3);

 getch();

    insline();

    getch();

 return 0;

}


intr example
/* intr example */

#include <stdio.h>

#include <string.h>

#include <dir.h>

#include <dos.h>

#define CF 1  /* Carry flag */

int main(void)

{

    char directory[80];

 struct REGPACK reg;

    printf("Enter directory to change to: ");

    gets(directory);

    reg.r_ax = 0x3B << 8;         /* shift 3Bh into  AH */

    reg.r_dx = FP_OFF(directory);

    reg.r_ds = FP_SEG(directory);

    intr(0x21, &reg);

    if (reg.r_flags & CF)

       printf("Directory change failed\n");

    getcwd(directory, 80);

    printf("The current directory is: %s\n", directory);

    return 0;

}


ioctl example
/* ioctl example */

#include <stdio.h>

#include <dir.h>

#include <io.h>

int main(void)

{

    int stat;

    /* use func 8 to determine if the default drive is removable */

    stat = ioctl(0, 8, 0, 0);

    if (!stat)

       printf("Drive %c is removable.\n", getdisk() + 'A');

    else

       printf("Drive %c is not removable.\n", getdisk() + 'A');

    return 0;

}


isatty example
/* isatty example */

#include <stdio.h>

#include <io.h>

int main(void)

{

    int handle;

    handle = fileno(stdprn);

    if (isatty(handle))

       printf("Handle %d is a device type\n", handle);

    else

       printf("Handle %d isn't a device type\n", handle);

    return 0;

}


kbhit example
/* kbhit example */

#include <conio.h>

int main(void)

{

 cprintf("Press any key to continue:");

    while (!kbhit()) /* do nothing */ ;

    cprintf("\r\nA key was pressed...\r\n");

    return 0;

}


ldexp example
/* ldexp example */

#include <stdio.h>

#include <math.h>

int main(void)

{

    double value;

    double x = 2;

    /* ldexp raises 2 by a power of 3

       then multiplies the result by 2   */

    value = ldexp(x,3);

    printf("The ldexp value is: %lf\n", value);

    return 0;

}


setjmp example
/* setjmp example */

#include <stdio.h>

#include <setjmp.h>

#include <stdlib.h>

void subroutine(jmp_buf);

int main(void)

{

    int value;

    jmp_buf jumper;

    value = setjmp(jumper);

    if (value != 0)

    {

       printf("Longjmp with value %d\n", value);

       exit(value);

    }

    printf("About to call subroutine ... \n");

    subroutine(jumper);

    return 0;

}

void subroutine(jmp_buf jumper)

{

    longjmp(jumper,1);

}


longjmp example
/* longjmp example */

#include <stdio.h>

#include <setjmp.h>

#include <stdlib.h>

void subroutine(jmp_buf);

int main(void)

{

    int value;

    jmp_buf jumper;

    value = setjmp(jumper);

    if (value != 0)

    {

       printf("Longjmp with value %d\n", value);

       exit(value);

    }

    printf("About to call subroutine ... \n");

    subroutine(jumper);

    return 0;

}

void subroutine(jmp_buf jumper)

{

    longjmp(jumper,1);

}


lseek example
/* lseek example */

#include <sys\stat.h>

#include <string.h>

#include <stdio.h>

#include <fcntl.h>

#include <io.h>

int main(void)

{

    int handle;

    char msg[] = "This is a test";

    char ch;

    /* create a file */

    handle = open("TEST.$$$", O_CREAT | O_RDWR, S_IREAD | S_IWRITE);

    /* write some data to the file */

    write(handle, msg, strlen(msg));

    /* seek to the begining of the file */

    lseek(handle, 0L, SEEK_SET);

    /* reads chars from the file until we hit EOF */

    do

    {

       read(handle, &ch, 1);

       printf("%c", ch);

    }  while (!eof(handle));

    close(handle);

    return 0;

}


malloc example
/* malloc example */

#include <stdio.h>

#include <string.h>

#include <alloc.h>

#include <process.h>

int main(void)

{

    char *str;

    /* allocate memory for string */

    if ((str = (char *) malloc(10)) == NULL)

    {

       printf("Not enough memory to allocate buffer\n");

       exit(1);  /* terminate program if out of memory */

    }

    /* copy "Hello" into string */

    strcpy(str, "Hello");

    /* display string */

    printf("String is %s\n", str);

    /* free memory */

    free(str);

    return 0;

}


_matherr example
/* _matherr example */

#include <math.h>

#include <string.h>

#include <stdio.h>

int matherr (struct exception *a)

{

  if (a->type == DOMAIN)

    if (!strcmp(a->name,"sqrt")) {

      a->retval = sqrt (-(a->arg1));

    return 1;

    }

  return 0;

}

int main(void)

{

  double x = -2.0, y;

  y = sqrt(x);

  printf("Matherr corrected value: %lf\n",y);

  return 0;

}


max and min example
/* max and min example */

#include <stdlib.h>

#include <stdio.h>

#ifdef __cplusplus

   int max (int value1, int value2);

   int max(int value1, int value2)

   {

      return ( (value1 > value2) ? value1 : value2);

   }

#endif

int main(void)

{

    int x = 5;

    int y = 6;

    int z;

    z = max(x, y);

    printf("The larger number is %d\n", z);

    return 0;

}


memchr example
/* memchr example */

#include <string.h>

#include <stdio.h>

int main(void)

{

    char str[17];

    char *ptr;

    strcpy(str, "This is a string");

    ptr = (char *) memchr(str, 'r', strlen(str));

    if (ptr)

       printf("The character 'r' is at position: %d\n", ptr - str);

    else

       printf("The character was not found\n");

    return 0;

}


memset example
/* memset example */

#include <string.h>

#include <stdio.h>

#include <mem.h>

int main(void)

{

    char buffer[] = "Hello world\n";

    printf("Buffer before memset: %s\n", buffer);

    memset(buffer, '*', strlen(buffer) - 1);

    printf("Buffer after memset:  %s\n", buffer);

    return 0;

}


mkdir example
/* mkdir example */

#include <stdio.h>

#include <conio.h>

#include <process.h>

#include <dir.h>

#define DIRNAME "testdir.$$$"

int main(void)

{

    int stat;

    stat = mkdir(DIRNAME);

    if (!stat)

           printf("Directory created\n");

    else

    {

       printf("Unable to create directory\n");

       exit(1);

    }

    getch();

    system("dir/p");

    getch();

    stat = rmdir(DIRNAME);

    if (!stat)

           printf("\nDirectory deleted\n");

    else

    {

           perror("\nUnable to delete directory\n");

       exit(1);

    }

    return 0;

}


rmdir example
/* rmdir example */

#include <stdio.h>

#include <conio.h>

#include <process.h>

#include <dir.h>

#define DIRNAME "testdir.$$$"

int main(void)

{

    int stat;

    stat = mkdir(DIRNAME);

    if (!stat)

           printf("Directory created\n");

    else

    {

       printf("Unable to create directory\n");

       exit(1);

    }

    getch();

    system("dir/p");

    getch();

    stat = rmdir(DIRNAME);

    if (!stat)

           printf("\nDirectory deleted\n");

    else

    {

           perror("\nUnable to delete directory\n");

       exit(1);

    }

    return 0;

}


mktemp example
/* mktemp example */

#include <dir.h>

#include <stdio.h>

int main(void)

{

    /* fname defines the template for the

      temporary file.  */

    char *fname = "TXXXXXX", *ptr;

    ptr = mktemp(fname);

    printf("%s\n",ptr);

    return 0;

}


mktime example
/* mktime example */

#include <stdio.h>

#include <time.h>

 char *wday[] = {"Sunday", "Monday", "Tuesday", "Wednesday",

  "Thursday", "Friday", "Saturday", "Unknown"};

int main(void)

{

    struct tm time_check;

    int year, month, day;

/*  Input a year, month and day to find the weekday for */

    printf("Year:  ");

    scanf("%d", &year);

    printf("Month: ");

    scanf("%d", &month);

    printf("Day:   ");

    scanf("%d", &day);

/*  load the time_check structure with the data */

    time_check.tm_year = year - 1900;

    time_check.tm_mon  = month - 1;

    time_check.tm_mday = day;

    time_check.tm_hour = 0;

    time_check.tm_min  = 0;

    time_check.tm_sec  = 1;

    time_check.tm_isdst = -1;

/*  call mktime to fill in the weekday field of the structure */

    if (mktime(&time_check) == -1)

       time_check.tm_wday = 7;

/*  print out the day of the week */

    printf("That day is a %s\n", wday[time_check.tm_wday]);

    return 0;

}


modf example
/* modf example */

#include <math.h>

#include <stdio.h>

int main(void)

{

    double fraction, integer;

    double number = 100000.567;

    fraction = modf(number, &integer);

    printf("The whole and fractional parts of %lf are %lf and %lf\n",

           number, integer, fraction);

    return 0;

}


movedata example
/* movedata example */

#include <mem.h>

#define MONO_BASE 0xB000

char buf[80*25*2];

/* saves the contents of the monochrome screen in buffer */

void save_mono_screen(char near *buffer)

{

   movedata(MONO_BASE, 0, _DS, (unsigned)buffer, 80*25*2);

}

int main(void)

{

   save_mono_screen(buf);

   return 0;

}


movmem example
/* movmem example */

#include <mem.h>

#include <alloc.h>

#include <stdio.h>

#include <string.h>

int main(void)

{

    char *source = "Borland International";

    char *destination;

    int length;

    length = strlen(source);

    destination = (char *) malloc(length + 1);

    movmem(source, destination, length);

    printf("%s\n", destination);

    return 0;

}


movetext example
/* movetext example */

#include <conio.h>

#include <string.h>

int main(void)

{

    char *str = "This is a test string";

    clrscr();

    cputs(str);

    getch();

    movetext(1, 1, strlen(str), 2, 10, 10);

    getch();

    return 0;

}


norm example
/* norm example */

#include <iostream.h>

#include <complex.h>

int main(void)

{

    double x = 3.1, y = 4.2;

    complex z = complex(x,y);

    cout << "z = " << z << "\n";

    cout << "  has real part = " << real(z) << "\n";

    cout << "  and imaginary real part = " << imag(z) << "\n";

    cout << "z has complex conjugate = " << conj(z) << "\n";

    double mag = sqrt(norm(z));

    double ang = arg(z);

    cout << "The polar form of z is:\n";

    cout << "   magnitude = " << mag << "\n";

    cout << "   angle (in radians) = " << ang << "\n";

    cout << "Reconstructing z from its polar form gives:\n";

    cout << "   z = " << polar(mag,ang) << "\n";

    return 0;

}


closedir example
/* closedir and readdir example */

/* opendir.c - test opendir(), readdir(), closedir() */

#include <dirent.h>

#include <stdio.h>

#include <stdlib.h>

void scandir(char *dirname)

{

   DIR *dir;

   struct dirent *ent;

   printf("First pass on '%s':\n",dirname);

   if ((dir = opendir(dirname)) == NULL)

   {

     perror("Unable to open directory");

     exit(1);

   }

   while ((ent = readdir(dir)) != NULL)

     printf("%s\n",ent->d_name);

   printf("Second pass on '%s':\n",dirname);

   rewinddir(dir);

   while ((ent = readdir(dir)) != NULL)

     printf("%s\n",ent->d_name);

   if (closedir(dir) != 0)

     perror("Unable to close directory");

}

void main(int argc,char *argv[])

{

   if (argc != 2)

   {

     printf("usage: opendir dirname\n");

     exit(1);

   }

   scandir(argv[1]);

   exit(0);

}


opendir example
/* opendir example */

 /* opendir.c - test opendir(), readdir(), closedir() */

#include <dirent.h>

#include <stdio.h>

#include <stdlib.h>

void scandir(char *dirname)

{

   DIR *dir;

   struct dirent *ent;

   printf("First pass on '%s':\n",dirname);

   if ((dir = opendir(dirname)) == NULL)

   {

     perror("Unable to open directory");

     exit(1);

   }

   while ((ent = readdir(dir)) != NULL)

     printf("%s\n",ent->d_name);

   printf("Second pass on '%s':\n",dirname);

   rewinddir(dir);

   while ((ent = readdir(dir)) != NULL)

     printf("%s\n",ent->d_name);

   if (closedir(dir) != 0)

     perror("Unable to close directory");

}

void main(int argc,char *argv[])

{

   if (argc != 2)

   {

     printf("usage: opendir dirname\n");

     exit(1);

   }

   scandir(argv[1]);

   exit(0);

}


parsfnm example
/* parsfnm example */

#include <process.h>

#include <string.h>

#include <stdio.h>

#include <dos.h>

int main(void)

{

    char line[80];

    struct fcb blk;

    /* get file name */

    printf("Enter drive and file name (no path; e.g., a:file.dat)\n");

    gets(line);

    /* put file name in fcb */

    if (parsfnm(line, &blk, 1) == NULL)

       printf("Error in parsfm call\n");

    else

       printf("Drive #%d  Name: %11s\n", blk.fcb_drive, blk.fcb_name);

    return 0;

}


peek example
/* peek example */

#include <stdio.h>

#include <conio.h>

#include <dos.h>

int main(void)

{

    int value = 0;

    printf("The current status of your keyboard is:\n");

    value = peek(0x0040, 0x0017);

    if (value & 1)

       printf("Right shift on\n");

    else

       printf("Right shift off\n");

    if (value & 2)

       printf("Left shift on\n");

    else

       printf("Left shift off\n");

    if (value & 4)

       printf("Control key on\n");

    else

       printf("Control key off\n");

    if (value & 8)

       printf("Alt key on\n");

    else

       printf("Alt key off\n");

    if (value & 16)

       printf("Scroll lock on\n");

    else

       printf("Scroll lock off\n");

    if (value & 32)

       printf("Num lock on\n");

    else

       printf("Num lock off\n");

    if (value & 64)

       printf("Caps lock on\n");

    else

       printf("Caps lock off\n");

    return 0;

}


perror example
/* perror example */

#include <stdio.h>

int main(void)

{

    FILE *fp;

    fp = fopen("perror.dat", "r");

    if (!fp)

       perror("Unable to open file for reading");

    return 0;

}


poke example
/* poke example */

#include <dos.h>

#include <conio.h>

int main(void)

{

    clrscr();

    cprintf("Make sure the scroll lock key is off and press any key\r\n");

    getch();

    poke(0x0000,0x0417,16);

    cprintf("The scroll lock is now on\r\n");

    return 0;

}


polar example
/* polar example */

#include <iostream.h>

#include <complex.h>

int main(void)

{

    double x = 3.1, y = 4.2;

    complex z = complex(x,y);

    cout << "z = " << z << "\n";

    cout << "  has real part = " << real(z) << "\n";

    cout << "  and imaginary real part = " << imag(z) << "\n";

    cout << "z has complex conjugate = " << conj(z) << "\n";

    double mag = sqrt(norm(z));

    double ang = arg(z);

    cout << "The polar form of z is:\n";

    cout << "   magnitude = " << mag << "\n";

    cout << "   angle (in radians) = " << ang << "\n";

    cout << "Reconstructing z from its polar form gives:\n";

    cout << "   z = " << polar(mag,ang) << "\n";

    return 0;

}


poly example
/* poly example */

#include <stdio.h>

#include <math.h>

/* polynomial:  x**3 - 2x**2 + 5x - 1 */

int main(void)

{

  double array[] = { -1.0, 5.0, -2.0, 1.0

};

  double result;

  result = poly(2.0, 3, array);

  printf("The polynomial: x**3 - 2.0x**2 + 5x - 1 at 2.0 is %lf\n", result);

  return 0;

}


pow example
/* pow example */

#include <math.h>

#include <stdio.h>

int main(void)

{

  double x = 2.0, y = 3.0;

  printf("%lf raised to %lf is %lf\n", x, y, pow(x, y));

  return 0;

}


pow10 example
/* pow10 example */

#include <math.h>

#include <stdio.h>

int main(void)

{

  double p = 3.0;

  printf("Ten raised to %lf is %lf\n", p, pow10(p));

  return 0;

}


putch example
/* putch example */

#include <stdio.h>

#include <conio.h>

int main(void)

{

  char ch = 0;

  printf("Input a string:");

  while ((ch != '\r'))

  {

    ch = getch();

    putch(ch);

  }

  return 0;

}


raise example
/* raise example */

#include <signal.h>

int main(void)

{

    int a, b;

    a = 10;

    b = 0;

    if (b == 0)

    /* preempt divide by zero error */

       raise(SIGFPE);

    a = a / b;

    return 0;

}


rand example
/* rand example */

#include <stdlib.h>

#include <stdio.h>

int main(void)

{

    int i;

    randomize();

    printf("Ten random numbers from 0 to 99\n\n");

    for(i=0; i<10; i++)

       printf("%d\n", rand() % 100);

    return 0;

}


random example
/* random example */

#include <stdlib.h>

#include <stdio.h>

#include <time.h>

/* prints a random number in the range 0 to 99 */

int main(void)

 {

    randomize();

    printf("Random number in the 0-99 range: %d\n", random (100));

    return 0;

}


randomize example
/* randomize example */

#include <stdlib.h>

#include <stdio.h>

#include <time.h>

int main(void)

{

    int i;

    randomize();

    printf("Ten random numbers from 0 to 99\n\n");

    for(i=0; i<10; i++)

        printf("%d\n", rand() % 100);

    return 0;

}


real example
/* real example */

#include <iostream.h>

#include <complex.h>

int main(void)

{

    double x = 3.1, y = 4.2;

    complex z = complex(x,y);

    cout << "z = " << z << "\n";

    cout << "  has real part = " << real(z) << "\n";

    cout << "  and imaginary real part = " << imag(z) << "\n";

    cout << "z has complex conjugate = " << conj(z) << "\n";

    return 0;

}


remove example
/* remove example */

#include <stdio.h>

int main(void)

{

    char file[80];

    /* prompt for file name to delete */

    printf("File to delete: ");

    gets(file);

    /* delete the file */

    if (remove(file) == 0)

       printf("Removed %s.\n",file);

    else

       perror("remove");

    return 0;

}


rename example
/* rename example */

#include <stdio.h>

int main(void)

{

    char oldname[80], newname[80];

    /* prompt for file to rename and new name */

    printf("File to rename: ");

    gets(oldname);

    printf("New name: ");

    gets(newname);

    /* Rename the file */

    if (rename(oldname, newname) == 0)

       printf("Renamed %s to %s.\n", oldname, newname);

    else

       perror("rename");

    return 0;

}


rewind example
/* rewind example */

#include <stdio.h>

#include <dir.h>

int main(void)

{

    FILE *fp;

    char *fname = "TXXXXXX", *newname, first;

    newname = mktemp(fname);

    fp = fopen(newname,"w+");

    fprintf(fp,"abcdefghijklmnopqrstuvwxyz");

    rewind(fp);

    fscanf(fp,"%c",&first);

    printf("The first character is: %c\n",first);

    fclose(fp);

    remove(newname);

    return 0;

}


rewinddir example
/* rewinddir example */

/* opendir.c - test opendir(), readdir(), closedir() */

#include <dirent.h>

#include <stdio.h>

#include <stdlib.h>

void scandir(char *dirname)

{

   DIR *dir;

   struct dirent *ent;

   printf("First pass on '%s':\n",dirname);

   if ((dir = opendir(dirname)) == NULL)

   {

     perror("Unable to open directory");

     exit(1);

   }

   while ((ent = readdir(dir)) != NULL)

     printf("%s\n",ent->d_name);

   printf("Second pass on '%s':\n",dirname);

   rewinddir(dir);

   while ((ent = readdir(dir)) != NULL)

     printf("%s\n",ent->d_name);

   if (closedir(dir) != 0)

     perror("Unable to close directory");

 }

 void main(int argc,char *argv[])

 {

   if (argc != 2)

   {

     printf("usage: opendir dirname\n");

     exit(1);

   }

   scandir(argv[1]);

   exit(0);

}


rmtmp example
/* rmtmp example */

#include <stdio.h>

#include <process.h>

void main()

{

   FILE *stream;

   int i;

   /* Create temporary files */

   for (i = 1; i <= 10; i++)

   {

     if ((stream = tmpfile()) == NULL)

       perror("Could not open temporary file\n");

     else

       printf("Temporary file %d created\n", i);

   }

   /* Remove temporary files */

   if (stream != NULL)

     printf("%d temporary files deleted\n", rmtmp());

}


_searchenv example
/* _searchenv example */

#include <stdio.h>

#include <stdlib.h>

char buf[_MAX_PATH];

int main(void)

{

  /* looks for TLINK */

  _searchenv("TLINK.EXE","PATH",buf);

  if (buf[0] == '\0')

    printf("TLINK.EXE not found\n");

  else

    printf("TLINK.EXE found in %s\n", buf);

  /* looks for non-existent file */

  _searchenv("NOTEXIST.FIL","PATH",buf);

  if (buf[0] == '\0')

    printf("NOTEXIST.FIL not found\n");

  else

    printf("NOTEXIST.FIL found in %s\n", buf);

  return 0;

}

  /* Program output

      TLINK.EXE found in C:\BIN\TLINK.EXE

      NOTEXIST.FIL not found

  */


searchpath example
/* searchpath example */

#include <stdio.h>

#include <dir.h>

int main(void)

{

    char *p;

    /* Looks for TLINK and returns a pointer

       to the path  */

    p = searchpath("TLINK.EXE");

    printf("Search for TLINK.EXE : %s\n", p);

    /* Looks for non-existent file  */

    p = searchpath("NOTEXIST.FIL");

    printf("Search for NOTEXIST.FIL : %s\n", p);

    return 0;

}


abort example
/* abort example */

#include <stdio.h>

#include <stdlib.h>

 int main(void)

 {

   printf("Calling abort()\n");

   abort();

   return 0; /* This is never reached */

 }


access example
/* access example */

 #include <stdio.h>

 #include <io.h>

 int file_exists(char *filename);

 int main(void)

 {

printf("Does NOTEXIST.FIL exist: %s\n",

 file_exists("NOTEXISTS.FIL") ? "YES" : "NO");

return 0;

 }

 int file_exists(char *filename)

 {

   return (access(filename, 0) == 0);

 }


arg example
/* arg example */

 #include <iostream.h>

 #include <complex.h>

 int main(void)

 {

    double x = 3.1, y = 4.2;

    complex z = complex(x,y);

    cout << "z = " << z << "\n";

    cout << "  has real part = " << real(z) << "\n";

    cout << "  and imaginary part = " << imag(z) << "\n";

    cout << "z has complex conjugate = " << conj(z) << "\n";

    double mag = sqrt(norm(z));

    double ang = arg(z);

    cout << "The polar form of z is:\n";

    cout << "   magnitude = " << mag << "\n";

    cout << "   angle (in radians) = " << ang << "\n";

    cout << "Reconstructing z from its polar form gives:\n";

    cout << "   z = " << polar(mag,ang) << "\n";

    return 0;

 }


assert example
/* assert example */

 #include <assert.h>

 #include <stdio.h>

 #include <stdlib.h>

 struct ITEM {

    int key;

    int value;

 };

 /* add item to list, make sure list is not  null */

 void additem(struct ITEM *itemptr) {

    assert(itemptr != NULL);

    /* add item to list */

 }

 int main(void)

 {

    additem(NULL);

    return 0;

 }


atexit example
/* atexit example */

 #include <stdio.h>

 #include <stdlib.h>

 void exit_fn1(void)

 {

    printf("Exit function #1 called\n");

 }

 void exit_fn2(void)

 {

    printf("Exit function #2 called\n");

 }

 int main(void)

 {

    /* post exit function #1 */

    atexit(exit_fn1);

    /* post exit function #2 */

    atexit(exit_fn2);

    return 0;

 }


atof example
/* atof example */

 #include <stdlib.h>

 #include <stdio.h>

 int main(void)

 {

    float f;

    char *str = "12345.67";

    f = atof(str);

    printf("string = %s float = %f\n", str, f);

    return 0;

 }


atoi example
/* atoi example */

 #include <stdlib.h>

 #include <stdio.h>

 int main(void)

 {

    int n;

    char *str = "12345.67";

    n = atoi(str);

    printf("string = %s integer = %d\n", str, n);

    return 0;

 }


atol example
/* atol example */

 #include <stdlib.h>

 #include <stdio.h>

 int main(void)

 {

    long l;

    char *lstr = "98765432";

    l = atol(lstr);

    printf("string = %s integer = %ld\n", lstr, l);

    return(0);

 }


bcd example
/* bcd example */

 #include <iostream.h>

 #include <bcd.h>

 double x = 10000.0;         // ten thousand dollars

 bcd a = bcd(x/3,2);         // a third, rounded to nearest penny

 int main(void)

 {

    cout << "share of fortune = $" << a << "\n";

    return 0;

 }


bdos example
/* bdos example */

 #include <stdio.h>

 #include <dos.h>

 /* Get current drive as 'A', 'B', ... */

 char current_drive(void)

 {

    char curdrive;

    /* Get current disk as 0, 1, ... */

    curdrive = bdos(0x19, 0, 0);

    return('A' + curdrive);

 }

 int main(void)

 {

    printf("The current drive is %c:\n", current_drive());

    return 0;

 }


bdosptr example
/* bdosptr example */

 #include <string.h>

 #include <stdio.h>

 #include <dir.h>

 #include <dos.h>

 #include <errno.h>

 #include <stdlib.h>

 #define  BUFLEN  80

 int main(void)

 {

    char  buffer[BUFLEN];

    int   test;

    printf("Enter full pathname of a directory\n");

    gets(buffer);

    test = bdosptr(0x3B,buffer,0);

       if(test)

       {

          printf("DOS error message: %d\n", errno);

          /* See errno.h for error listings */

          exit (1);

       }

    getcwd(buffer, BUFLEN);

    printf("The current directory is: %s\n", buffer);

    return 0;

 }


calloc example
/* calloc example */

 #include <stdio.h>

 #include <alloc.h>

 #include <string.h>

 int main(void)

 {

    char *str = NULL;

    /* allocate memory for string */

    str = (char *) calloc(10, sizeof(char));

    /* copy "Hello" into string */

    strcpy(str, "Hello");

    /* display string */

    printf("String is %s\n", str);

    /* free memory */

    free(str);

    return 0;

 }


ceil and floor example
/* ceil and floor example */

 #include <math.h>

 #include <stdio.h>

 int main(void)

 {

    double number = 123.54;

    double down, up;

    down = floor(number);

    up = ceil(number);

    printf("original number     %5.2lf\n", number);

    printf("number rounded down %5.2lf\n", down);

    printf("number rounded up   %5.2lf\n", up);

    return 0;

 }


cgets example
/* cgets example */

 #include <stdio.h>

 #include <conio.h>

 int main(void)

 {

    char buffer[83];

    char *p;

    /* There's space for 80 characters plus the NULL terminator */

    buffer[0] = 81;

    printf("Input some chars:");

    p = cgets(buffer);

    printf("\ncgets read %d characters: \"%s\"\n", buffer[1], p);

    printf("The returned pointer is %p, buffer[0] is at %p\n", p, &buffer);

    /* Leave room for 5 characters plus the NULL terminator */

    buffer[0] = 6;

    printf("Input some chars:");

    p = cgets(buffer);

    printf("\ncgets read %d characters: \"%s\"\n", buffer[1], p);

    printf("The returned pointer is %p, buffer[0] is at %p\n", p, &buffer);

    return 0;

 }


_chain_intr example
/* _chain_intr example */

#include <dos.h>

#include <stdio.h>

#include <process.h>

#ifdef __cplusplus

    #define __CPPARGS ...

#else

    #define __CPPARGS

#endif

typedef void interrupt (*fptr)(__CPPARGS);

static void mesg(char *s)

{

  while (*s)

    bdos(2,*s++,0);

}

#pragma argsused

void interrupt handler2(unsigned bp, unsigned di)

{

  _enable();

  mesg("In handler 2.\r\n");

  if (di == 1)

    mesg("DI is 1\r\n");

  else

    mesg("DI is not 1\r\n");

  di++;

}

#pragma argsused

void interrupt handler1(unsigned bp, unsigned di)

{

  _enable();

  mesg("In handler 1.\r\n");

  if (di == 0)

    mesg("DI is 0\r\n");

  else

    mesg("DI is not 0\r\n");

  di++;

  mesg("Chaining to handler 2.\r\n");

  _chain_intr((fptr) handler2);

}

int main()

{

  _dos_setvect(128,(fptr) handler1);

  printf("About to generate interrupt 128\n");

  _DI = 0;

  geninterrupt(128);

  printf("DI was 0 before interrupt, is now 0x%x\n",_DI);

  return 0;

}


chdir example
/* chdir example */

#include <stdio.h>

#include <stdlib.h>

#include <dir.h>

char old_dir[MAXDIR];

char new_dir[MAXDIR];

int main(void)

{

   if (getcurdir(0, old_dir))

   {

      perror("getcurdir()");

      exit(1);

   }

   printf("Current directory is: \\%s\n", old_dir);

   if (chdir("\\"))

   {

      perror("chdir()");

      exit(1);

   }

   if (getcurdir(0, new_dir))

   {

      perror("getcurdir()");

      exit(1);

   }

   printf("Current directory is now: \\%s\n", new_dir);

   printf("\nChanging back to original directory: \\%s\n", old_dir);

   if (chdir(old_dir))

   {

      perror("chdir()");

      exit(1);

   }

   return 0;

}


chmod example
/* chmod example */

/* NEW chmod() example: */

#include <errno.h>

#include <stdio.h>

#include <io.h>

#include <process.h>

#include <sys\stat.h>

void main(void)

{

  char filename[64];

  struct stat stbuf;

  int amode;

  printf("Enter name of file: ");

  scanf("%s", filename);

  if (stat(filename, &stbuf) != 0)

  {

    perror("Unable to get file information");

    exit(1);

  }

  if (stbuf.st_mode & S_IWRITE)

  {

    printf("Changing to read-only\n");

    amode = S_IREAD;

  }

  else

  {

    printf("Changing to read-write\n");

    amode = S_IREAD|S_IWRITE;

  }

  if (chmod(filename, amode) != 0)

  {

    perror("Unable to change file mode");

    exit(1);

  }

  exit(0);

}


chsize example
/* chsize example */

#include <string.h>

#include <fcntl.h>

#include <io.h>

int main(void)

{

   int handle;

   char buf[11] = "0123456789";

   /* create text file containing 10 bytes */

   handle = open("DUMMY.FIL", O_CREAT);

   write(handle, buf, strlen(buf));

   /* truncate the file to 5 bytes in size */

   chsize(handle, 5);

   /* close the file */

   close(handle);

   return 0;

}


_clear87 and _status87 example
/* _clear87 and _status87 example */

#include <stdio.h>

#include <float.h>

int main(void)

{

   float x;

   double y = 1.5e-100;

   printf("\nStatus 87 before error: %X\n", _status87());

   x = y; /* create underflow and precision loss */

   printf("Status 87 after  error: %X\n", _status87());

   _clear87();

   printf("Status 87 after  clear: %X\n", _status87());

   y = x;

   return 0;

}


clearerr example
/* clearerr example */

#include <stdio.h>

int main(void)

{

   FILE *fp;

   char ch;

   /* open a file for writing */

   fp = fopen("DUMMY.FIL", "w");

   /* force an error condition by attempting to read */

   ch = fgetc(fp);

   printf("%c\n",ch);

   if (ferror(fp))

   {

      /* display an error message */

      printf("Error reading from DUMMY.FIL\n");

      /* reset the error and EOF indicators */

      clearerr(fp);

   }

   fclose(fp);

   return 0;

}


clock example
/* clock example */

#include <time.h>

#include <stdio.h>

#include <dos.h>

int main(void)

{

   clock_t start, end;

   start = clock();

   delay(2000);

   end = clock();

   printf("The time was: %f\n", (end - start) / CLK_TCK);

   return 0;

}


clreol example
/* clreol example */

#include <conio.h>

int main(void)

{

   clrscr();

   cprintf("The function CLREOL clears all characters from the\r\n");

   cprintf("cursor position to the end of the line within the\r\n");

   cprintf("current text window, without moving the cursor.\r\n");

   cprintf("Press any key to continue . . .");

   gotoxy(14, 4);

   getch();

   clreol();

   getch();

   return 0;

}


clrscr example
/* clrscr example */

#include <conio.h>

int main(void)

{

   int i;

   clrscr();

   for (i = 0; i < 20; i++)

      cprintf("%d\r\n", i);

   cprintf("\r\nPress any key to clear screen");

   getch();

   clrscr();

   cprintf("The screen has been cleared!");

   getch();

   return 0;

}


complex example
/* complex example */

#include <iostream.h>

#include <complex.h>

int main(void)

{

   double x = 3.1, y = 4.2;

   complex z = complex(x,y);

   cout << "z = "<< z << "\n";

   cout << " and imaginary real part = " << imag(z) << "\n";

   cout << "z has complex conjugate =  " << conj(z) << " \n";

   return 0;

}


conj example
/* conj example */

#include <iostream.h>

#include <complex.h>

int main(void)

{

   double x = 3.1, y = 4.2;

   complex z = complex(x,y);

   cout << "z = "<< z << "\n";

   cout << " and imaginary real part = " << imag(z) << "\n";

   cout << "z has complex conjugate =  " << conj(z) << " \n";

   return 0;

}


country example
/* country example */

#include <dos.h>

#include <stdio.h>

#define USA 0

int main(void)

{

   struct COUNTRY country_info;

   country(USA, &country_info);

   printf("The currency symbol for the USA is: %s\n",

           country_info.co_curr);

   return 0;

}


cputs example
/* cputs example */

#include <conio.h>

int main(void)

{

   /* clear the screen */

   clrscr();

   /* create a text window */

   window(10, 10, 80, 25);

   /* output some text in the window */

   cputs("This is within the window\r\n");

   /* wait for a key */

   getch();

   return 0;

}


creattemp example
/* creattemp example */

#include <string.h>

#include <stdio.h>

#include <io.h>

int main(void)

{

   int handle;

   char pathname[128];

   strcpy(pathname, "\\");

   /* create a unique file in the root directory */

   handle = creattemp(pathname, 0);

   printf("%s was the unique file created.\n", pathname);

   close(handle);

   return 0;

}


ctrlbrk example
/* ctrlbrk example */

#include <stdio.h>

#include <dos.h>

#define ABORT 0

int c_break(void)

{

   printf("Control-Break pressed.  Program aborting ...\n");

return (ABORT);

}

void main(void)

{

   ctrlbrk(c_break);

   for(;;)

   {

      printf("Looping... Press <Ctrl-Break> to quit:\n");

   }

}


delline example
/* delline example */

#include <conio.h>

int main(void)

{

   clrscr();

   cprintf("The function DELLINE deletes the line containing the\r\n");

   cprintf("cursor and moves all lines below it one line up.\r\n");

   cprintf("DELLINE operates within the currently active text\r\n");

   cprintf("window.  Press any key to continue . . .");

   gotoxy(1,2);  /* Move the cursor to the second line and first column */

   getch();

   delline();

   getch();

   return 0;

}


difftime example
/* difftime example */

#include <time.h>

#include <stdio.h>

#include <dos.h>

#include <conio.h>

int main(void)

{

   time_t first, second;

   clrscr();

   first = time(NULL);  /* Gets system

                           time */

   delay(2000);         /* Waits 2 secs */

   second = time(NULL); /* Gets system time

                           again */

   printf("The difference is: %f seconds\n",difftime(second,first));

   getch();

   return 0;

}


dosexterr example
/* dosexterr example */

#include <stdio.h>

#include <dos.h>

int main(void)

{

   FILE *fp;

   struct DOSERROR info;

   fp = fopen("perror.dat","r");

   if (!fp) perror("Unable to open file for reading");

   dosexterr(&info);

   printf("Extended DOS error information:\n");

   printf("   Extended error: %d\n",info.de_exterror);

   printf("            Class: %x\n",info.de_class);

   printf("           Action: %x\n",info.de_action);

   printf("      Error Locus: %x\n",info.de_locus);

   return 0;

}


dostounix example
/* dostounix example */

#include <time.h>

#include <stddef.h>

#include <dos.h>

#include <stdio.h>

int main(void)

{

  time_t t;

  struct time d_time;

  struct date d_date;

  struct tm *local;

  getdate(&d_date);

  gettime(&d_time);

  t = dostounix(&d_date, &d_time);

  local = localtime(&t);

  printf("Time and Date: %s\n", asctime(local));

  return 0;

}


__emit__ example
/* __emit__ example */

#include <dos.h>

int main(void)

{

/* Emit code that will generate a print screen via int 5 */

   __emit__(0xcd,0x05);

   return 0;

}


eof example
/* eof example */

#include <sys\stat.h>

#include <string.h>

#include <stdio.h>

#include <fcntl.h>

#include <io.h>

int main(void)

{

   int handle;

   char msg[] = "This is a test";

   char ch;

   /* create a file */

   handle = open("DUMMY.FIL",

                 O_CREAT | O_RDWR,

                 S_IREAD | S_IWRITE);

   /* write some data to the file */

   write(handle, msg, strlen(msg));

   /* seek to the beginning of the file */

   lseek(handle, 0L, SEEK_SET);

   /* reads chars from the file until it reaches EOF */

   do

   {

      read(handle, &ch, 1);

      printf("%c", ch);

   } while (!eof(handle));

   close(handle);

   return 0;

}


exp and expl example
/* exp and expl example */

#include <stdio.h>

#include <math.h>

int main(void)

{

   double result;

   double x = 4.0;

   result = exp(x);

   printf("'e' raised to the power \

          of %lf (e ^ %lf) = %lf\n",

          x, x, result);

   return 0;

}


farcalloc example
/* farcalloc example */

#include <stdio.h>

#include <alloc.h>

#include <string.h>

#include <dos.h>

int main(void)

{

   char far *fptr;

   char *str = "Hello";

   /* allocate memory for the far pointer */

   fptr = (char far *) farcalloc(10, sizeof(char));

   /* copy "Hello" into allocated memory */

   /*

      Note: movedata is used because you might be in a small data model, in

      which case a normal string copy routine can not be used since it

      assumes the pointer size is near.

   */

   movedata(FP_SEG(str), FP_OFF(str),

      FP_SEG(fptr), FP_OFF(fptr),

      strlen(str));

   /* display string (note the F modifier) */

   printf("Far string is: %Fs\n", fptr);

   /* free the memory */

   farfree(fptr);

   return 0;

}


farmalloc example
/* farmalloc example */

#include <stdio.h>

#include <alloc.h>

#include <string.h>

#include <dos.h>

int main(void)

{

   char far *fptr;

   char *str = "Hello";

   /* allocate memory for the far pointer */

   fptr = (char far *) farmalloc(10);

   /* copy "Hello" into allocated memory */

   /*

    Note: movedata is used because we might be in a small data model,

      in which case a normal string copy routine can not be used since it

      assumes the pointer size is near.

   */

   movedata(FP_SEG(str), FP_OFF(str),

            FP_SEG(fptr), FP_OFF(fptr),

            strlen(str) + 1);

   /* display string (note the F modifier)

*/

   printf("Far string is: %Fs\n", fptr);

   /* free the memory */

   farfree(fptr);

   return 0;

}


fclose example
/* fclose example */

#include <string.h>

#include <stdio.h>

int main(void)

{

   FILE *fp;

   char buf[11] = "0123456789";

   /* create a file containing 10 bytes */

   fp = fopen("DUMMY.FIL", "w");

   fwrite(&buf, strlen(buf), 1, fp);

   /* close the file */

   fclose(fp);

   return 0;

}


fcloseall example
/* fcloseall example */

#include <stdio.h>

int main(void)

{

   int streams_closed;

   /* open two streams */

   fopen("DUMMY.ONE", "w");

   fopen("DUMMY.TWO", "w");

   /* close the open streams */

   streams_closed = fcloseall();

   if (streams_closed == EOF)

      /* issue an error message */

      perror("Error");

   else

      /* print result of fcloseall() function */

      printf("%d streams were closed.\n", streams_closed);

   return 0;

}


feof example
/* feof example */

#include <stdio.h>

int main(void)

{

   FILE *stream;

   /* open a file for reading */

   stream = fopen("DUMMY.FIL", "r");

   /* read a character from the file */

   fgetc(stream);

   /* check for EOF */

   if (feof(stream))

      printf("We have reached end-of-file\n");

   /* close the file */

   fclose(stream);

   return 0;

}


ferror example
/* ferror example */

#include <stdio.h>

int main(void)

{

   FILE *stream;

   /* open a file for writing */

   stream = fopen("DUMMY.FIL", "w");

   /* force an error condition by attempting to read */

   (void) getc(stream);

   if (ferror(stream))  /* test for an error on the stream */

   {

      /* display an error message */

      printf("Error reading from DUMMY.FIL\n");

      /* reset the error and EOF indicators */

      clearerr(stream);

   }

   fclose(stream);

   return 0;

}


fflush example
/* fflush example */

#include <string.h>

#include <stdio.h>

#include <conio.h>

#include <io.h>

void flush(FILE *stream);

int main(void)

{

   FILE *stream;

   char msg[] = "This is a test";

   /* create a file */

   stream = fopen("DUMMY.FIL", "w");

   /* write some data to the file */

   fwrite(msg, strlen(msg), 1, stream);

   clrscr();

   printf("Press any key to flush DUMMY.FIL:");

   getch();

   /* flush the data to DUMMY.FIL without closing it */

   flush(stream);

   printf("\nFile was flushed, Press any key to quit:");

   getch();

   return 0;

}

void flush(FILE *stream)

{

     int duphandle;

     /* flush the stream's internal buffer */

     fflush(stream);

     /* make a duplicate file handle */

     duphandle = dup(fileno(stream));

     /* close the duplicate handle to flush the DOS buffer */

     close(duphandle);

}


fgetpos and fsetpos example
/* fgetpos and fsetpos example */

#include <stdlib.h>

#include <stdio.h>

void showpos(FILE *stream);

int main(void)

{

   FILE *stream;

   fpos_t filepos;

   /* open a file for update */

   stream = fopen("DUMMY.FIL", "w+");

   /* save the file pointer position */

   fgetpos(stream, &filepos);

   /* write some data to the file */

   fprintf(stream, "This is a test");

   /* show the current file position */

   showpos(stream);

   /* set a new file position, display it */

   if (fsetpos(stream, &filepos) == 0)

     showpos(stream);

   else

   {

      fprintf(stderr, "Error setting file pointer.\n");

      exit(1);

   }

   /* close the file */

   fclose(stream);

   return 0;

}

void showpos(FILE *stream)

{

   fpos_t pos;

   /* display the current file pointer

      position of a stream */

   fgetpos(stream, &pos);

   printf("File position: %ld\n", pos);

}


filelength example
/* filelength example */

#include <string.h>

#include <stdio.h>

#include <fcntl.h>

#include <io.h>

int main(void)

{

   int handle;

   char buf[11] = "0123456789";

   /* create a file containing 10 bytes */

   handle = open("DUMMY.FIL", O_CREAT);

   write(handle, buf, strlen(buf));

   /* display the size of the file */

   printf("file length in bytes: %ld\n", filelength(handle));

   /* close the file */

   close(handle);

   return 0;

}


fileno example
/* fileno example */

#include <stdio.h>

int main(void)

{

   FILE *stream;

   int handle;

   /* create a file */

   stream = fopen("DUMMY.FIL", "w");

   /* obtain the file handle associated with the stream */

   handle = fileno(stream);

   /* display the handle number */

   printf("handle number: %d\n", handle);

   /* close the file */

   fclose(stream);

   return 0;

}


flushall example
/* flushall example */

#include <stdio.h>

int main(void)

{

   FILE *stream;

   /* create a file */

   stream = fopen("DUMMY.FIL", "w");

   /* flush all open streams */

   printf("%d streams were flushed.\n", flushall());

   /* close the file */

   fclose(stream);

   return 0;

}


fmod and fmodl example
/* fmod and fmodl example */

#include <stdio.h>

#include <math.h>

int main(void)

{

   double x = 5.0, y = 2.0;

   double result;

   result = fmod(x,y);

   printf("The remainder of (%lf / %lf) is %lf\n", x, y, result);

   return 0;

}


FP_OFF, FP_SEG, and MK_FP example
/* FP_OFF, and FP_SEG example*/

#include <stdio.h>

#include <dos.h>

main()

{

  char *str = "Hello\n";

  printf("The address pointed to by str is %04X:%04X\n",

          FP_SEG(str), FP_OFF(str));

  printf("The address of str is %04X:%04X\n", FP_SEG(&str), FP_OFF(&str));

  return 0;

}


fread example
/* fread example */

#include <string.h>

#include <stdio.h>

int main(void)

{

   FILE *stream;

   char msg[] = "this is a test";

   char buf[20];

   if ((stream = fopen("DUMMY.FIL", "w+"))

       == NULL)

   {

      fprintf(stderr, "Cannot open output file.\n");

      return 1;

   }

   /* write some data to the file */

   fwrite(msg, strlen(msg)+1, 1, stream);

   /* seek to the beginning of the file */

   fseek(stream, SEEK_SET, 0);

   /* read the data and display it */

   fread(buf, strlen(msg)+1, 1, stream);

   printf("%s\n", buf);

   fclose(stream);

   return 0;

}


frexp and frexpl example
/* frexp and frexpl examples */

#include <math.h>

#include <stdio.h>

int main(void)

{

   double mantissa, number;

   int exponent;

   number = 8.0;

   mantissa = frexp(number, &exponent);

   printf("The number %lf is ", number);

   printf("%lf times two to the ", mantissa);

   printf("power of %d\n", exponent);

   return 0;

}


fseek example
/* fseek example */

#include <stdio.h>

long filesize(FILE *stream);

int main(void)

{

   FILE *stream;

   stream = fopen("MYFILE.TXT", "w+");

   fprintf(stream, "This is a test");

   printf("Filesize of MYFILE.TXT is %ld bytes\n", filesize(stream));

   fclose(stream);

   return 0;

}

long filesize(FILE *stream)

{

   long curpos, length;

   curpos = ftell(stream);

   fseek(stream, 0L, SEEK_END);

   length = ftell(stream);

   fseek(stream, curpos, SEEK_SET);

   return length;

}


ftell example
/* ftell example */

#include <stdio.h>

int main(void)

{

   FILE *stream;

   stream = fopen("MYFILE.TXT", "w+");

   fprintf(stream, "This is a test");

   printf("The file pointer is at byte %ld\n", ftell(stream));

   fclose(stream);

   return 0;

}


ftime example
/* ftime example */

#include <stdio.h>

#include <stdlib.h>

#include <time.h>

#include <sys\timeb.h>

/* pacific standard & daylight savings */

char *tzstr = "TZ=PST8PDT";

int main(void)

{

   struct timeb t;

   putenv(tzstr);

   tzset();

   ftime(&t);

   printf("Seconds since 1/1/1970 GMT: %ld\n", t.time);

   printf("Thousandths of a second: %d\n", t.millitm);

   printf("Difference between local time and GMT: %d\n", t._timezone);

   printf("Daylight savings in effect (1) not (0): %d\n", t.dstflag);

   return 0;

}


_fullpath example
/* _fullpath example */

#include <stdio.h>

#include <stdlib.h>

char buf[_MAX_PATH];

void main(int argc, char *argv[])

{

  for ( ; argc; argv++, argc--)

  {

    if (_fullpath(buf, argv[0], _MAX_PATH) == NULL)

      printf("Unable to obtain full path of %s\n",argv[0]);

    else

      printf("Full path of %s is %s\n",argv[0],buf);

  }

}


fwrite example
/* fwrite example */

#include <stdio.h>

struct mystruct

{

  int i;

  char ch;

};

int main(void)

{

   FILE *stream;

   struct mystruct s;

   if ((stream = fopen("TEST.$$$", "wb")) == NULL) /* open file TEST.$$$ */

   {

      fprintf(stderr, "Cannot open output file.\n");

      return 1;

   }

   s.i = 0;

   s.ch = 'A';

   fwrite(&s, sizeof(s), 1, stream); /* write struct s to file */

   fclose(stream); /* close file */

   return 0;

}


gcvt example
/* gcvt example */

#include <stdlib.h>

#include <stdio.h>

int main(void)

{

   char str[25];

   double num;

   int sig = 5; /* significant digits */

   /* a regular number */

   num = 9.876;

   gcvt(num, sig, str);

   printf("string = %s\n", str);

   /* a negative number */

   num = -123.4567;

   gcvt(num, sig, str);

   printf("string = %s\n", str);

   /* scientific notation */

   num = 0.678e5;

   gcvt(num, sig, str);

   printf("string = %s\n", str);

   return(0);

}


geninterrupt example
/* geninterrupt example */

#include <conio.h>

#include <dos.h>

/* function prototype */

void writechar(char ch);

int main(void)

{

   clrscr();

   gotoxy(80,25);

   writechar('*');

   getch();

   return 0;

}

/*

   outputs a character at the current cursor

   position using the video BIOS to avoid

   the scrolling of the screen when writing

   to location (80,25).

*/

void writechar(char ch)

{

   struct text_info ti;

   /* grab current text settings */

   gettextinfo(&ti);

   /* interrupt 0x10 sub-function 9 */

   _AH = 9;

   /* character to be output */

   _AL = ch;

   _BH = 0;                  /* video page */

   _BL = ti.attribute;  /* video attribute */

   _CX = 1;           /* repetition factor */

   geninterrupt(0x10);  /* output the char */

}


getcbrk and setcbrk example
/* getcbrk and setcbrk example */

#include <dos.h>

#include <conio.h>

#include <stdio.h>

int main(void)

{

   int break_flag;

   printf("Enter 0 to turn control break off\n");

   printf("Enter 1 to turn control break on\n");

   break_flag = getch() - 0;

   setcbrk(break_flag);

   if (getcbrk())

      printf("Cntrl-brk flag is on\n");

   else

      printf("Cntrl-brk flag is off\n");

   return 0;

}


segread example
/* segread example */

#include <stdio.h>

#include <dos.h>

int main(void)

{

   struct SREGS segs;

   segread(&segs);

   printf("Current segment register settings\n\n");

   printf("CS: %X   DS: %X\n", segs.cs, segs.ds);

   printf("ES: %X   SS: %X\n", segs.es, segs.ss);

   return 0;

}


setmem example
/* setmem example */

#include <stdio.h>

#include <alloc.h>

#include <mem.h>

int main(void)

{

   char *dest;

   dest = (char *) calloc(21, sizeof(char));

   setmem(dest, 20, 'c');

   printf("%s\n", dest);

   return 0;

}


setmode example
/* setmode example */

#include <fcntl.h>

#include <io.h>

#include <stdio.h>

int main (int argc, char ** argv )

(

  FILE *fp;

  int newmode;

  long where;

  char buf[256];

  fp = fopen( argv[1], "r+" );

  if ( !fp )

  {

    printf( "Couldn't open %s\n", argv[1] );

    return -1;

  }

  newmode = setmode( fileno( fp ), O_BINARY );

  if ( newmode == -1 )

  {

    printf( "Coudn't set mode of %s\n", argv[1] );

    return -2

  }

  fp->flags |= _F_BIN;

  where = ftell( fp );

  printf ("file position: %d\n", where );

  fread( buf, 1, 1, fp );

  where = ftell ( fp );

  printf( "read %c, file position: %ld\n", *buf, where );

  fclose ( fp );

  return 0;

}


signal example
/* signal example */

/* signal example */

/*

    This example installs a signal handler routine for SIGFPE,

    catches an integer overflow condition, makes an adjustment to AX

    register, and returns.  This example program MAY cause your computer

    to crash, and will produce runtime errors depending on which memory

    model is used.

*/

#pragma inline

#include <stdio.h>

#include <signal.h>

#ifdef __cplusplus

   typedef void (*fptr)(int);

#else

   typedef void (*fptr)();

#endif

void Catcher(int *reglist)

{

   signal(SIGFPE, (fptr)Catcher);  //  ******reinstall signal handler

   printf("Caught it!\n"); *(reglist + 8) = 3; /* make return AX = 3 */

}

int main(void)

{

   signal(SIGFPE, (fptr)Catcher);  /* cast Catcher to appropriate type */

   asm     mov     ax,07FFFH       /* AX = 32767 */

   asm     inc     ax              /* cause overflow */

   asm     into                    /* activate handler */

   /* The handler set AX to 3 on return. If that had not happened,

      there would have been another exception when the next 'into'

      executed after the 'dec' instruction. */

   asm     dec     ax              /* no overflow now */

   asm     into                    /* doesn't activate */

   return 0;

}


sleep example
/* sleep example */

#include <dos.h>

#include <stdio.h>

int main(void)

{

   int i;

   for (i=1; i<5; i++)

   {

      printf("Sleeping for %d seconds\n", i);

      sleep(i);

   }

   return 0;

}


sqrt example
/* sqrt example */

#include <math.h>

#include <stdio.h>

int main(void)

{

   double x = 4.0, result;

   result = sqrt(x);

   printf("The square root of %lf is %lf\n", x, result);

   return 0;

}


srand example
/* srand example */

#include <stdlib.h>

#include <stdio.h>

#include <time.h>

int main(void)

{

   int i;

   time_t t;

   srand((unsigned) time(&t));

   printf("Ten random numbers from 0 to 99\n\n");

   for(i=0; i<10; i++)

       printf("%d\n", rand() % 100);

   return 0;

}


stpcpy example
/* stpcpy example */

#include <stdio.h>

#include <string.h>

int main(void)

{

   char string[10];

   char *str1 = "abcdefghi";

   stpcpy(string, str1);

   printf("%s\n", string);

   return 0;

}


strcat example
/*strcat example */

#include <string.h>

#include <stdio.h>

int main(void)

{

   char destination[25];

   char *blank = " ", *c = "C++", *Borland = "Borland";

   strcpy(destination, Borland);

   strcat(destination, blank);

   strcat(destination, c);

   printf("%s\n", destination);

   return 0;

}


strchr example
/* strchr example */

#include <string.h>

#include <stdio.h>

int main(void)

{

   char string[15];

   char *ptr, c = 'r';

   strcpy(string, "This is a string");

   ptr = strchr(string, c);

   if (ptr)

      printf("The character %c is at position: %d\n", c, ptr-string);

   else

      printf("The character was not found\n");

   return 0;

}


strcoll example
/* strcoll example */

#include <stdio.h>

#include <string.h>

int main(void)

{

   char *two = "International";

   char *one = "Borland";

   int check;

   check = strcoll(one, two);

   if (check == 0)

      printf("The strings are equal\n");

   if (check <  0)

      printf("%s comes before %s\n", one, two);

   if (check >  0)

      printf("%s comes before %s\n", two, one);

   return 0;

}


strcpy example
/* strcpy example */

#include <stdio.h>

#include <string.h>

int main(void)

{

   char string[10];

   char *str1 = "abcdefghi";

   strcpy(string, str1);

   printf("%s\n", string);

   return 0;

}


_strdate example
/* _strdate example */

#include <time.h>

#include <stdio.h>

void main(void)

{

  char datebuf[9];

  char timebuf[9];

  _strdate(datebuf);

  _strtime(timebuf);

  printf("Date: %s  Time: %s\n",datebuf,timebuf);

}


strdup example
/* strdup example */

#include <stdio.h>

#include <string.h>

#include <alloc.h>

int main(void)

{

   char *dup_str, *string = "abcde";

   dup_str = strdup(string);

   printf("%s\n", dup_str);

   free(dup_str);

   return 0;

}


strftime example
/* strftime example */

#include <stdio.h>

#include <time.h>

#include <dos.h>

int main(void)

{

   struct tm *time_now;

   time_t secs_now;

   char str[80];

   tzset();

   time(&secs_now);

   time_now = localtime(&secs_now);

   strftime(str, 80,

            "It is %M minutes after %I o'clock (%Z)  %A, %B %d 19%y",

            time_now);

   printf("%s\n",str);

   return 0;

}


strlen example
/*strlen example */

#include <stdio.h>

#include <string.h>

int main(void)

{

   char *string = "Borland International";

   printf("%d\n", strlen(string));

   return 0;

}


strncat example
/*strncat example */

#include <string.h>

#include <stdio.h>

int main(void)

{

   char destination[25];

   char *source = " States";

   strcpy(destination, "United");

   strncat(destination, source, 7);

   printf("%s\n", destination);

   return 0;

}


strncpy example
/* strncpy example */

#include <stdio.h>

#include <string.h>

int main(void)

{

   char string[10];

   char *str1 = "abcdefghi";

   strncpy(string, str1, 3);

   string[3] = '\0';

   printf("%s\n", string);

   return 0;

}


strnset example
/* strnset example */

#include <stdio.h>

#include <string.h>

int main(void)

{

   char *string = "abcdefghijklmnopqrstuvwxyz";

   char letter = 'x';

   printf("string before strnset: %s\n", string);

   strnset(string, letter, 13);

   printf("string after  strnset: %s\n", string);

   return 0;

}


strpbrk example
/* strpbrk example */

#include <stdio.h>

#include <string.h>

int main(void)

{

   char *string1 = "abcdefghijklmnopqrstuvwxyz";

   char *string2 = "onm";

   char *ptr;

   ptr = strpbrk(string1, string2);

   if (ptr)

      printf("strpbrk found first character: %c\n", *ptr);

   else

      printf("strpbrk didn't find character in set\n");

   return 0;

}


strrchr example
/* strrchr example */

#include <string.h>

#include <stdio.h>

int main(void)

{

   char string[15];

   char *ptr, c = 'r';

   strcpy(string, "This is a string");

   ptr = strrchr(string, c);

   if (ptr)

      printf("The character %c is at position: %d\n", c, ptr-string);

   else

      printf("The character was not found\n");

   return 0;

}


strrev example
/* strrev example */

#include <string.h>

#include <stdio.h>

int main(void)

{

   char *forward = "string";

   printf("Before strrev(): %s\n", forward);

   strrev(forward);

   printf("After strrev():  %s\n", forward);

   return 0;

}


strset example
/* strset example */

#include <stdio.h>

#include <string.h>

int main(void)

{

   char string[10] = "123456789";

   char symbol = 'c';

   printf("Before strset(): %s\n", string);

   strset(string, symbol);

   printf("After strset():  %s\n", string);

   return 0;

}


strstr example
/* strstr example */

#include <stdio.h>

#include <string.h>

int main(void)

{

   char *str1 = "Borland International", *str2 = "nation", *ptr;

   ptr = strstr(str1, str2);

   printf("The substring is: %s\n", ptr);

   return 0;

}


_strtime example
/* _strtime example */

#include <time.h>

#include <stdio.h>

void main(void)

{

  char datebuf[9];

  char timebuf[9];

  _strdate(datebuf);

  _strtime(timebuf);

  printf("Date: %s  Time: %s\n",datebuf,timebuf);

}


strtok example
/* strtok example */

 #include <string.h>

 #include <stdio.h>

 int main(void)

 {

    char input[16] = "abc,d";

    char *p;

    /* strtok places a NULL terminator

    in front of the token, if found */

    p = strtok(input, ",");

    if (p)   printf("%s\n", p);

    /* A second call to strtok using a NULL

    as the first parameter returns a pointer

    to the character following the token  */

    p = strtok(NULL, ",");

    if (p)   printf("%s\n", p);

    return 0;

 }


strxfrm example
/* strxfrm example */

#include <stdio.h>

#include <string.h>

#include <alloc.h>

int main(void)

{

   char *target;

   char *source = "Frank Borland";

   int length;

   /* allocate space for the target string */

   target = (char *) calloc(80, sizeof(char));

   /* copy the source over to the target and get the length */

   length = strxfrm(target, source, 80);

   /* print out the results */

   printf("%s has the length %d\n", target, length);

   return 0;

}


swab example
/* swab example */

#include <stdlib.h>

#include <stdio.h>

#include <string.h>

char source[15] = "rFna koBlrna d";

char target[15];

int main(void)

{

   swab(source, target, strlen(source));

   printf("This is target: %s\n", target);

   return 0;

}


system example
/* system example */

#include <stdlib.h>

#include <stdio.h>

int main(void)

{

   printf("About to spawn command.com and run a DOS command\n");

   system("dir");

   return 0;

}


tell example
/* tell example */

#include <string.h>

#include <stdio.h>

#include <fcntl.h>

#include <io.h>

int main(void)

{

   int handle;

   char msg[] = "Hello world";

   if ((handle = open("TEST.$$$", O_CREAT | O_TEXT | O_APPEND)) == -1)

   {

      perror("Error:");

      return 1;

   }

   write(handle, msg, strlen(msg));

   printf("The file pointer is at byte %ld\n", tell(handle));

   close(handle);

   return 0;

}


tempnam example
/* tempnam example */

#include <stdio.h>

#include <stdlib.h>

void main(void)

{

  FILE *stream;

  int i;

  char *name;

  for (i = 1; i <= 10; i++) {

    if ((name = tempnam("\\tmp","wow")) == NULL)

      perror("tempnam couldn't create name");

    else {

      printf("Creating %s\n",name);

      if ((stream = fopen(name,"wb")) == NULL)

        perror("Could not open temporary file\n");

      else

        fclose(stream);

    }

    free(name);

  }

  printf("Warning: temp files not deleted.\n");

}


textmode example
/* textmode example */

#include <conio.h>

int main(void)

{

   textmode(BW40);

   cprintf("ABC");

   getch();

   textmode(C40);

   cprintf("ABC");

   getch();

   textmode(BW80);

   cprintf("ABC");

   getch();

   textmode(C80);

   cprintf("ABC");

   getch();

   textmode(MONO);

   cprintf("ABC");

   getch();

   return 0;

}


tmpfile example
/* tmpfile example */

#include <stdio.h>

#include <process.h>

int main(void)

{

   FILE *tempfp;

   tempfp = tmpfile();

   if (tempfp)

      printf("Temporary file created\n");

   else

   {

      printf("Unable to create temporary file\n");

      exit(1);

   }

   return 0;

}


tmpnam example
/* tmpnam example */

#include <stdio.h>

int main(void)

{

   char name[13];

   tmpnam(name);

   printf("Temporary name: %s\n", name);

   return 0;

}


toascii example
/* toascii example */

#include <stdio.h>

#include <ctype.h>

int main(void)

{

   int number, result;

   number = 511;

   result = toascii(number);

   printf("%d %d\n", number, result);

   return 0;

}


tzset example
/* tzset example */

#include <time.h>

#include <stdlib.h>

#include <stdio.h>

int main(void)

{

   time_t td;

   putenv("TZ=PST8PDT");

   tzset();

   time(&td);

   printf("Current time = %s\n", asctime(localtime(&td)));

   return 0;

}


ungetc example
/* ungetc example */

#include <stdio.h>

#include <ctype.h>

int main( void )

{

   int i=0;

   char ch;

   puts("Input an integer followed by a char:");

   /* read chars until non digit or EOF */

   while((ch = getchar()) != EOF && isdigit(ch))

      i = 10 * i + ch - 48; /* convert ASCII into int value */

   /* if non digit char was read, push it back into input buffer */

   if (ch != EOF)

      ungetc(ch, stdin);

   printf("i = %d, next char in buffer = %c\n", i, getchar());

   return 0;

}


ungetch example
/* ungetch example */

#include <stdio.h>

#include <ctype.h>

#include <conio.h>

int main( void )

{

   int i=0;

   char ch;

   puts("Input an integer followed by a char:");

   /* read chars until non digit or EOF */

   while((ch = getche()) != EOF && isdigit(ch))

      i = 10 * i + ch - 48; /* convert ASCII into int value */

   /* if non digit char was read, push it back into input buffer */

   if (ch != EOF)

      ungetch(ch);

   printf("\n\ni = %d, next char in buffer = %c\n", i, getch());

   return 0;

}


unixtodos example
/* unixtodos example */

#include <stdio.h>

#include <dos.h>

char *month[] = {"---", "Jan", "Feb", "Mar", "Apr", "May", "Jun",

                        "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"};

#define SECONDS_PER_DAY 86400L  /* the number of seconds in one day */

struct date dt;

struct time tm;

int main(void)

{

   unsigned long val;

/* get today's date and time */

   getdate(&dt);

   gettime(&tm);

   printf("today is %d %s %d\n", dt.da_day, month[dt.da_mon], dt.da_year);

/*convert date and time to unix format (num of seconds since Jan 1, 1970*/

   val = dostounix(&dt, &tm);

/* subtract 42 days worth of seconds */

   val -= (SECONDS_PER_DAY * 42);

/* convert back to dos time and date */

   unixtodos(val, &dt, &tm);

   printf("42 days ago it was %d %s %d\n",

          dt.da_day, month[dt.da_mon], dt.da_year);

   return 0;

}


unlink example
/* unlink example */

#include <stdio.h>

#include <io.h>

int main(void)

{

   FILE *fp = fopen("junk.jnk","w");

   int status;

   fprintf(fp,"junk");

   status = access("junk.jnk",0);

   if (status == 0)

      printf("File exists\n");

   else

      printf("File doesn't exist\n");

   fclose(fp);

   unlink("junk.jnk");

   status = access("junk.jnk",0);

   if (status == 0)

      printf("File exists\n");

   else

      printf("File doesn't exist\n");

   return 0;

}


umask example
/* umask example */

#include <io.h>

#include <stdio.h>

#include <sys\stat.h>

#define FILENAME "TEST.$$$"

int main(void)

{

    unsigned oldmask;

    FILE *f;

    struct stat statbuf;

    /* Cause subsequent files to be created as read-only */

    oldmask = umask(S_IWRITE);

    printf("Old mask = 0x%x\n",oldmask);

    /* Create a zero-length file */

    if ((f = fopen(FILENAME,"w+")) == NULL)

    {

        perror("Unable to create output file");

        return (1);

    }

    fclose(f);

    /* Verify that the file is read-only */

    if (stat(FILENAME,&statbuf) != 0)

    {

        perror("Unable to get information about output file");

        return (1);

    }

    if (statbuf.st_mode & S_IWRITE)

        printf("Error! %s is writable!\n",FILENAME);

    else

        printf("Success! %s is not writable.\n",FILENAME);

    return (0);

}


utime example
/* utime example */

/* Copy timestamp from one file to another */

#include <sys\stat.h>

#include <utime.h>

#include <stdio.h>

int main( int argc, char *argv[] )

{

  struct stat src_stat;

  struct utimbuf times;

  if(argc != 3) {

    printf( "Usage: copytime <source file> <dest file>\n" );

    return 1;

  }

  if (stat(argv[1],&src_stat) != 0) {

    perror("Unable to get status of source file");

    return 1;

  }

  times.modtime = times.actime = src_stat.st_mtime;

  if (utime(argv[2],&times) != 0) {

    perror("Unable to set time of destination file");

    return 1;

  }

  return 0;

}


va_arg example
/* va_arg example */

#include <stdio.h>

#include <stdarg.h>

/* calculate sum of a 0 terminated list */

void sum(char *msg, ...)

{

   int total = 0;

   va_list ap;

   int arg;

   va_start(ap, msg);

   while ((arg = va_arg(ap,int)) != 0) {

      total += arg;

   }

   printf(msg, total);

   va_end(ap);

}

int main(void) {

   sum("The total of 1+2+3+4 is %d\n", 1,2,3,4,0);

   return 0;

}


wherex and wherey example
/* wherex and wherey example */

#include <conio.h>

int main(void)

{

   clrscr();

   gotoxy(10,10);

   cprintf("Current location is X: %d  Y: %d\r\n", wherex(), wherey());

   getch();

   return 0;

}


window example
/* window example */

#include <conio.h>

int main(void)

{

   window(10,10,40,11);

   textcolor(BLACK);

   textbackground(WHITE);

   cprintf("This is a test\r\n");

   return 0;

}


getpsp example
/* getpsp example */

#include <stdio.h>

#include <dos.h>

int main(void)

{

   static char command[128];

   char far *cp;

   int len, i;

   printf("The program segment prefix is: %u\n", getpsp());

/*

_psp is preset to segment of the PSP. Command line is located at offset 0x81 from start of PSP

*/

   cp = (char *) MK_FP(_psp, 0x80);

   len = *cp;

   for (i = 0; i < len; i++)

      command[i] = cp[i+1];

   printf("Command line: %s\n", command);

   return 0;

}


stackavail example
/* stackavail example */

 #include <malloc.h>

 #include <stdio.h>

 int main(void)

 {

   char *buf;

   printf("\nThe stack: %u\tstack pointer: %u", stackavail(), _SP);

   buf = (char *) alloca(100 * sizeof(char));

   printf("\nNow, the stack: %u\tstack pointer: %u", stackavail(), _SP);

   return 0;

 }

 /* ************************************************

      Program output

      The stack: 64046       stack pointer: 65524

      Now, the stack: 63946  stack pointer: 65424

    ************************************************ */


set_new_handler example
/* set_new_handler example */

#include <iostream.h>

#include <new.h>

#include <stdlib.h>

void mem_warn() {

  cerr << "\nCan't allocate!";

  exit(1);

  }

void main(void) {

  set_new_handler(mem_warn);

  char *ptr = new char[100];

  cout << "\nFirst allocation: ptr = " << hex << long(ptr);

  ptr = new char[64000U];

  cout << "\nFinal allocation: ptr = " << hex << long(ptr);

  set_new_handler(0);  // Reset to default.

}


isalpha example
/* isalpha example */

#include <stdio.h>

#include <ctype.h>

int main(void)

{

  char c = 'C';

  if (isalpha(c))

    printf("%c is alphabetical\n",c);

  else printf("%c is not alphabetical\n",c);

  return 0;

}


isalnum example
/* isalnum example */

#include <stdio.h>

#include <ctype.h>

int main(void)

{

  char c = 'C';

  if (isalnum(c))

    printf("%c is alphanumeric\n",c);

  else printf("%c is not alphanumeric\n",c);

  return 0;

}


isascii example
/* isascii example */

#include <stdio.h>

#include <ctype.h>

#include <stdio.h>

int main(void)

{

  char c = 'C';

  if (isascii(c))

    printf("%c is ascii\n",c);

  else printf("%c is not ascii\n",c);

  return 0;

}


iscntr example
/* iscntrl example */

#include <stdio.h>

#include <ctype.h>

int main(void)

{

  char c = 'C';

  if (iscntrl(c))

    printf("%c is a control character\n",c);

  else printf("%c is not a control character\n",c);

  return 0;

}


isdigit example
/* isdigit example */

#include <stdio.h>

#include <ctype.h>

int main(void)

{

  char c = 'C';

  if (isdigit(c))

    printf("%c is a digit\n",c);

  else printf("%c is not a digit\n",c);

  return 0;

}


isgraph example
/* isgraph example */

#include <stdio.h>

#include <ctype.h>

int main(void)

{

  char c = 'C';

  if (isgraph(c))

    printf("%c is a graphic character\n",c);

  else printf("%c is not a graphic character\n",c);

  return 0;

}


islower example
/* islower example */

#include <stdio.h>

#include <ctype.h>

int main(void)

{

  char c = 'C';

  if (islower(c))

    printf("%c is a lowercase character\n",c);

  else printf("%c is not a lowercase character\n",c);

  return 0;

}


isprint example
/* isprint example */

#include <stdio.h>

#include <ctype.h>

int main(void)

{

  char c = 'C';

  if (isprint(c))

    printf("%c is a printable character\n",c);

  else printf("%c is not a printable character\n",c);

  return 0;

}


ispunct example
/* ispunct example */

#include <stdio.h>

#include <ctype.h>

int main(void)

{

  char c = 'C';

  if (ispunct(c))

    printf("%c is a punctuation character\n",c);

  else printf("%c is not a punctuation character\n",c);

  return 0;

}


isspace example
/* isspace example */

#include <stdio.h>

#include <ctype.h>

int main(void)

{

  char c = 'C';

  if (isspace(c))

    printf("%c is white space\n",c);

  else printf("%c is not white space\n",c);

  return 0;

}


isupper example
/* isupper example */

#include <stdio.h>

#include <ctype.h>

int main(void)

{

  char c = 'C';

  if (isupper(c))

    printf("%c is an uppercase character\n",c);

  else printf("%c is not an uppercase character\n",c);

  return 0;

}


isxdigit example
/* isxdigit example */

#include <stdio.h>

#include <ctype.h>

int main(void)

{

  char c = 'C';

  if (isxdigit(c))

    printf("%c is a hexidecimal digit\n",c);

  else printf("%c is not a hexidecimal digit\n",c);

  return 0;

}


mblen example
/* mblen example */

#include <stdlib.h>

#include <stdio.h>

void main (void)

{

  int i ;

  char *mulbc = (char *)malloc( sizeof( char) );

  wchar_t widec = L'a';

  printf (" convert a wide character to multibyte character:\n" );

  i = wctomb (mulbc, widec);

  printf( "\tCharacters converted: %u\n", i);

  printf( "\tMultibyte character: %x\n\n", mulbc);

  printf( " Find length--in byte-- of multibyte character:\n");

  i = mblen( mulbc, MB_CUR_MAX);

  printf("\tLenght--in bytes--if multiple character: %u\n",i);

  printf("\tWide character: %x\n\n", mulbc);

  printf( " Attempt to find length of a Wide character Null:\n");

  widec = L'\0';

  wctomb(mulbc, widec);

  i = mblen( mulbc, MB_CUR_MAX);

  printf("\tLenght--in bytes--if multiple character: %u\n",i);

  printf("\tWide character: %x\n\n", mulbc);

}


mbstowcs example
/* mbstowcs example */

#include <stdio.h>

#include <stdlib.h>

void main(void)

{

  int x;

  char    *mbst = (char *)malloc(MB_CUR_MAX);

  wchar_t *pwst = L"Hi";

  wchar_t *pwc      = (wchar_t *)malloc(sizeof( wchar_t));

  printf ("Convert to multibyte string:\n");

  x = wcstombs (mbst, pwst, MB_CUR_MAX);

  printf ("\tCharacters converted %u\n",x);

  printf ("\tHEx value of first");

  printf (" multibyte character: %#.4x\n\n", mbst);

  printf ("Convert back to wide character string:\n");

  x = mbstowcs(pwc, mbst, MB_CUR_MAX);

  printf( "\tCharacters converted: %u\n",x);

  printf( "\tHex value of first");

  printf( "wide character: %#.4x\n\n", pwc);

}


mbtowc example
/* mbtowc example */

#include <stdlib.h>

#include<stdio.h>

void main(void)

{

  int     x;

  char     *mbchar    = (char *)calloc(1, sizeof( char));

  wchar_t  wchar      = L'a';

  wchar_t   *pwcnull = NULL;

  wchar_t  *pwchar    = (wchar_t *)calloc(1,  sizeof( wchar_t ));

  printf ("Convert a wide character to multibyte character:\n");

  x = wctomb( mbchar, wchar);

  printf( "\tCharacters converted: %u\n", x);

  printf( "\tMultibyte character: %x\n\n", mbchar);

  printf ("Convert multibyte character back to a wide character:\n");

  x = mbtowc( pwchar, mbchar, MB_CUR_MAX );

  printf( "\tBytes converted: %u\n", x);

  printf( "\tWide character: %x\n\n", pwchar);

  printf ("Atempt to convert when target is NULL\n" );

  printf (" returns the length of the multibyte character:\n" );

  x = mbtowc (pwcnull, mbchar, MB_CUR_MAX );

  printf ( "\tlength of multibyte character:%u\n\n", x );

  printf ("Attempt to convert a NULL pointer to a" );

  printf (" wide character:\n" );

  mbchar = NULL;

  x = mbtowc (pwchar, mbchar, MB_CUR_MAX);

  printf( "\tBytes converted: %u\n", x );

  }


MK_FP example
/* MK_FP example */

#include <stdio.h>

#include <conio.h>

#include <string.h>

#include <dos.h>

#include <malloc.h>

main()

{

  char *str = "hello\n";

  char far *farstr;

  printf ("the address pointed to by str is %04X:%04X\n",

    FP_SEG(str), FP_OFF(str));

  farstr = (char far *)MK_FP( FP_SEG(str),  FP_OFF(str));

  printf ("the string pointed by far pointer is %s\n", farstr);

  return 0;

}


_msize example
/* _msize example */

/* _msize works as a 32-bit command, not as a 16-bit command */

#include <malloc.h>        /* malloc() _msize() */

#include <stdio.h>            /* printf() */

int main( )

{

  int size;

  int *buffer;

  buffer = malloc(100 * sizeof(int));

  size = _msize(buffer);

  printf("Allocated %d bytes for 100 integers\n", size);

  return(0);

}


offsetof example
/* offsetof example */

/*

This program uses the offsetof command to show the effect

of changing alignment boundaries within a structure.

It produces this output:

  In STRUCT1, two_bytes begins at byte 1.

  In STRUCT2, two_bytes begins at byte 2.

By default, the 16-bit compiler aligns structure members

at 1-byte boundaries.  With the -a2 flag set, the compiler

aligns fields on even boundaries.

The CPU often processes structure elements more quickly

when they align on even boundaries.

*/

#include <stddef.h>      // offsetof()

#include <stdio.h>      // printf()

#pragma option -a1      // align on bytes (default)

typedef struct {

  char one_byte;

  int two_bytes;

} STRUCT1;

#pragma option -a2      // align on even bytes

typedef struct {

  char one_byte;

  int two_bytes;

} STRUCT2;

#pragma option -a.      // restore command-line option

void main()

{

  printf( "In STRUCT1, two_bytes begins at byte %d.\n",

    offsetof(STRUCT1, two_bytes) );

  printf( "In STRUCT2, two_bytes begins at byte %d.\n",

    offsetof(STRUCT2, two_bytes) );

}


_pipe example
/* _pipe example */

#include <stdlib.h>

#include <stdio.h>

#include <io.h>

#include <fcntl.h>

#include <process.h>

void main(int argc, char *argv[])

{

    int handles[2];

    int retcode, stat, pid;

    char asc_handle[10];

    if (argc > 1)   /* this is the child */

    {

        /* Get the read pipe handle from command line,

         * and set the handle to binary.

         */

        handles[0] = atoi(argv[1]);

        setmode(handles[0],O_BINARY);

        /* Read the desired return code from pipe

         */

        if (read(handles[0], &amp.retcode, sizeof(retcode)) < 0)

        {

            perror("Child&colon. unable to read pipe");

            retcode = 255;

        }

        printf("Child&colon. returning %d to parent\n",retcode);

        exit(retcode);

    }

    else            /* this is the parent */

    {

        /* Open a pipe, convert read handle number to ASCII.

         * Write a value to the pipe that the child process

         * will use as its return code.

         */

        if (_pipe(handles,256,O_BINARY) == -1)

        {

            perror("Parent&colon. unable to create pipe");

            exit(1);

        }

        sprintf(asc_handle,"%d",handles[0]);

        retcode = 10;

        if (write(handles[1],&amp.retcode,sizeof(retcode)) < 0)

        {

            perror("Parent&colon. unable to write to pipe");

            exit(1);

        }

        /* Call ourself with read handle as argument.

         */

        if ((pid = spawnl(P_NOWAIT, argv[0], argv[0],

                          asc_handle, NULL)) == -1)

            perror("Parent&colon. spawnl failed");

        else

        {

            printf("Parent&colon. spawned child process %d\n",pid);

            if (wait(&amp.stat) != pid)

                perror("Parent&colon. wait failure");

            else

            {

                if ((stat &amp. 0xff) == 0)

                    printf("Parent&colon. child returned %d\n", stat >> 8);

                else

                    printf("Parent&colon. child terminated abnormally\n");

            }

        }

        close(handles[0]);

        close(handles[1]);

        exit(0);

    }

}


send example
/* send example */

/*

 There are two short programs here.  SEND spawns a child

 process, RECEIVE.  Each process holds one end of a

 pipe.  The parent transmits its command-line argument

 to the child, which prints the string and exits.

 IMPORTANT:  The parent process must be linked with

 the \32bit\fileinfo.obj file.  The code in fileinfo

 enables a parent to share handles with a child.

 Without this extra information, the child cannot use

 the handle it receives.

*/

/* SEND */

#include <fcntl.h>            // _pipe()

#include <io.h>            // write()

#include <process.h>          // spawnl() cwait()

#include <stdio.h>          // puts() perror()

#include <stdlib.h>          // itoa()

#include <string.h>          // strlen()

#define DECIMAL_RADIX 10      // for atoi()

enum PIPE_HANDLES { IN, OUT };  // to index the array of handles

int main(int argc, char *argv[])

{

  int handles[2];           // in- and

//outbound pipe handles

  char handleStr[10];        // a handle

//stored as a string

  int pid;

  // system's ID for child process

  if (argc <= 1)

  {

    puts("No message to send.");

    return(1);

  }

  if (_pipe(handles, 256, O_TEXT) != 0)

  {

    perror("Cannot create the pipe");

    return(1);

  }

  // store handle as a string for passing on the command line

  itoa(handles[IN], handleStr, DECIMAL_RADIX);

  // create the child process, passing it the inbound pipe handle

     spawnl(P_NOWAIT, "receive.exe", "receive.exe", handleStr, NULL);

  // transmit the message

  write(handles[OUT], argv[1], strlen(argv[1])+1);

  // when done with the pipe, close both handles

  close(handles[IN]);

  close(handles[OUT]);

  // wait for the child to finish

  wait(NULL);

  return(0);

}


_setcursortype example
/* _setcursortype example */

#include <conio.h>

int main( )

{

  // tell the user what to do

  clrscr();

  cputs("Press any key three times.\n\r");

  cputs("Each time the cursor will change shape.\n\r");

  gotoxy(1,5);           // show a solid cursor

  cputs("Now the cursor is solid.\n\r");

  _setcursortype(_SOLIDCURSOR);

  while(!kbhit()) {};         // wait to proceed

  getch();

  gotoxy(1,5);           // remove the cursor

  cputs("Now the cursor is gone.");

  clreol();

  gotoxy(1,6);

  _setcursortype(_NOCURSOR);

  while(!kbhit()) {};         // wait to proceed

  getch();

  gotoxy(1,5);                 // show a normal cursor

  cputs("Now the cursor is normal.");

  clreol();

  gotoxy(1,6);

  _setcursortype(_NORMALCURSOR);

  while(!kbhit()) {};         // wait to proceed

  getch();

  clrscr();

  return(0);

}


_dos_com example
/* _dos_commit example */

#include <dos.h>

#include <errno.h>

#include <conio.h>

void main(void)

{

  char save[]  = "to disk.",

  prompt[]     = " File exist,overwrite?[y/n]",

  err[]      = "Error occured. ",

  newline[]  = "\n\r";

int handle, ch;

unsigned count;

  /* Open file and create and overwrite it */

  if (_dos_createnew( "DUMMY.FIL",_A_NORMAL, &handle) !=0)

  {

    if (errno == EEXIST)

    {

    /* Use _dos_write to display prompts*/

    _dos_write (1, prompt, sizeof( prompt ) -1, &count );

    ch = bdos( 1, 0, 0) & 0x00ff;

    if ( (ch == 'y') || (ch == 'Y') )

      _dos_creat( "DUMMY.FIL", _A_NORMAL, &handle);

    _dos_write( 1,newline, sizeof( newline) -1, &count);

    }

  }

  /* Write to file; output passes through operating system's buffer*/

  if ( _dos_write( handle, save, sizeof( save ),&count) != 0 )

  {

  _dos_write( 1, err, sizeof( err) - 1, &count );

  _dos_write( 1, newline, sizeof( newline ) -1, &count );

  }

  /* Write directly to file with no intermediate buffering */

  if ( _dos_commit( handle ) != 0 )

  {

  _dos_write( 1, err, sizeof(err) -1, &count);

  _dos_write( 1, newline, sizeof( newline ) - 1 , &count);

  }

  /* Close file */

  if (_dos_close( handle ) != 0)

  {

  _dos_write( 1, err, sizeof(err) -1, &count );

  _dos_write( 1, newline, sizeof(newline) -1, &count );

  }

}


_expand example
/* _expand example */

#include <stdio.h>

#include <malloc.h>

#include <stdlib.h>

void main(void)

{

  char *bufchar;

  printf( "Allocate a 512 element buffer\n" );

  if( (bufchar = (char *) calloc(512, sizeof( char ) )) == NULL)

    exit( 1 );

  printf( "Allocated %d bytes at %Fp\n",

    _msize ( bufchar ), (void __far *)bufchar );

  if ((bufchar = (char *) _expand (bufchar, 1024)) == NULL)

    printf ("can not expand");

  else

    printf (" Expanded block to %d bytes at %Fp\n",

      _msize( bufchar ) , (void __far *)bufchar );

/* free memory  */

  free( bufchar );

  exit (0);

}


_get_osfhandle example
/* _get_osfhandle and _open_osfhandle example */

#include <windowsx.h>

#include <fcntl.h>

#include <stdio.h>

#include <io.h>

#ifndef __FLAT__

#error This Example must be compiled using 32 bit compiler

#endif

//Example for _get_osfhandle() and _open_osfhandle()

BOOL InitApplication(HINSTANCE hInstance);

HWND InitInstance(HINSTANCE hInstance, int nCmdShow);

LRESULT FAR PASCAL _export MainWndProc(HWND hWnd, UINT message,

            WPARAM wParam, LPARAM lParam);

Example_get_osfhandle(HWND hWnd);

#pragma argsused

int PASCAL WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,

        LPSTR lpCmdLine, int nCmdShow)

{

MSG msg;      // message

  if (!InitApplication(hInstance))  // Initialize shared things

   return (FALSE); // Exits if unable to initialize

  /* Perform initializations that apply to a specific instance */

  if (!(InitInstance(hInstance, nCmdShow)))

   return (FALSE);

  /* Acquire and dispatch messages until a WM_QUIT message is received. */

  while (GetMessage(&msg, // message structure

   NULL, // handle of window receiving the message

   NULL, // lowest message to examine

   NULL))  // highest message to examine

  {

  TranslateMessage(&msg); // Translates virtual key codes

  DispatchMessage(&msg);  // Dispatches message to window

  }

  return (msg.wParam);  // Returns the value from PostQuitMessage

}

BOOL InitApplication(HINSTANCE hInstance)

{

  WNDCLASS  wc;

  // Fill in window class structure with parameters that describe the

  // main window.

  wc.style = CS_HREDRAW | CS_VREDRAW; // Class style(s).

  wc.lpfnWndProc = (long (FAR PASCAL*)(void *,unsigned int,unsigned int, long ))MainWndProc; // Function to retrieve messages for

                // windows of this class.

  wc.cbClsExtra = 0;  // No per-class extra data.

  wc.cbWndExtra = 0;  // No per-window extra data.

  wc.hInstance = hInstance; // Application that owns the class.

  wc.hIcon = LoadIcon(NULL, IDI_APPLICATION);

  wc.hCursor = LoadCursor(NULL, IDC_ARROW);

  wc.hbrBackground = GetStockObject(WHITE_BRUSH);

  wc.lpszMenuName = NULL;  // Name of menu resource in .RC file.

  wc.lpszClassName = "Example"; // Name used in call to CreateWindow.

  /* Register the window class and return success/failure code. */

  return (RegisterClass(&wc));

}

HWND InitInstance(HINSTANCE hInstance, int nCmdShow)

{

  HWND  hWnd; // Main window handle.

  /* Create a main window for this application instance.  */

  hWnd = CreateWindow(

   "Example",                 // See RegisterClass() call.

   "Example _get_osfhandle _open_osfhandle (32 bit)",  // Text for window title bar.

   WS_OVERLAPPEDWINDOW,        // Window style.

   CW_USEDEFAULT,         // Default horizontal position.

   CW_USEDEFAULT,          // Default vertical position.

   CW_USEDEFAULT,            // Default width.

   CW_USEDEFAULT,        // Default height.

   NULL,                  // Overlapped windows have no parent.

   NULL,                  // Use the window class menu.

   hInstance,              // This instance owns this window.

   NULL                   // Pointer not needed.

  );

  /* If window could not be created, return "failure" */

  if (!hWnd)

   return (FALSE);

  /* Make the window visible; update its client area; and return "success" */

  ShowWindow(hWnd, nCmdShow); // Show the window

  UpdateWindow(hWnd);     // Sends WM_PAINT message

  return (hWnd);        // Returns the value from PostQuitMessage

}

#pragma argsused

LRESULT FAR PASCAL _export MainWndProc(HWND hWnd, UINT message,

            WPARAM wParam, LPARAM lParam)

{

  switch (message)

  {

    case WM_CREATE:

    {

      Example_get_osfhandle(hWnd);

      return NULL;

    }

    case WM_QUIT:

    case WM_DESTROY:  // message: window being destroyed

      PostQuitMessage(0);

    break;

    default:      // Passes it on if unproccessed

      return (DefWindowProc(hWnd, message, wParam, lParam));

  }

}

Example_get_osfhandle(HWND hWnd)

{

    long osfHandle;

    char str[128];

    int fHandle = open("file1.c", O_CREAT|O_TEXT);

    if(fHandle != -1)

    {

      osfHandle = _get_osfhandle(fHandle);

      sprintf(str, "file handle = %lx OS file handle = %lx", fHandle, osfHandle);

      MessageBox(hWnd,str,"_get_osfhandle",MB_OK|MB_ICONINFORMATION);

      close(fHandle);

      fHandle = _open_osfhandle(osfHandle, O_TEXT );

      sprintf(str, "file handle = %lx OS file handle = %lx", fHandle, osfHandle);

      MessageBox(hWnd,str,"_open_osfhandle",MB_OK|MB_ICONINFORMATION);

         close(fHandle);

    }

    else

      MessageBox(hWnd,"File Open Error","WARNING",MB_OK|MB_ICONSTOP);

    close(fHandle);

      return 0;

}


_heapset example
/* _heapset example */

#include <windowsx.h>

#include <malloc.h>

#include <stdio.h>

#include <stdlib.h>

#ifndef __FLAT__

#error This Example must be compiled using 32 bit compiler

#endif

BOOL InitApplication(HINSTANCE hInstance);

HWND InitInstance(HINSTANCE hInstance, int nCmdShow);

LRESULT FAR PASCAL _export MainWndProc(HWND hWnd, UINT message,

            WPARAM wParam, LPARAM lParam);

void ExampleHeapSet(HWND hWnd);

#pragma argsused

int PASCAL WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,

        LPSTR lpCmdLine, int nCmdShow)

{

MSG msg;      // message

  if (!InitApplication(hInstance))  // Initialize shared things

   return (FALSE); // Exits if unable to initialize

  /* Perform initializations that apply to a specific instance */

  if (!(InitInstance(hInstance, nCmdShow)))

   return (FALSE);

  /* Acquire and dispatch messages until a WM_QUIT message is received. */

  while (GetMessage(&msg, // message structure

   NULL, // handle of window receiving the message

   NULL, // lowest message to examine

   NULL))  // highest message to examine

  {

  TranslateMessage(&msg); // Translates virtual key codes

  DispatchMessage(&msg);  // Dispatches message to window

  }

  return (msg.wParam);  // Returns the value from PostQuitMessage

}

BOOL InitApplication(HINSTANCE hInstance)

{

  WNDCLASS  wc;

  // Fill in window class structure with parameters that describe the

  // main window.

  wc.style = CS_HREDRAW | CS_VREDRAW; // Class style(s).

  wc.lpfnWndProc = (long (FAR PASCAL*)(void *,unsigned int,unsigned int, long ))MainWndProc; // Function to retrieve messages for

                // windows of this class.

  wc.cbClsExtra = 0;  // No per-class extra data.

  wc.cbWndExtra = 0;  // No per-window extra data.

  wc.hInstance = hInstance; // Application that owns the class.

  wc.hIcon = LoadIcon(NULL, IDI_APPLICATION);

  wc.hCursor = LoadCursor(NULL, IDC_ARROW);

  wc.hbrBackground = GetStockObject(WHITE_BRUSH);

  wc.lpszMenuName = NULL;  // Name of menu resource in .RC file.

  wc.lpszClassName = "Example"; // Name used in call to CreateWindow.

  /* Register the window class and return success/failure code. */

  return (RegisterClass(&wc));

}

HWND InitInstance(HINSTANCE hInstance, int nCmdShow)

{

  HWND  hWnd; // Main window handle.

  /* Create a main window for this application instance.  */

  hWnd = CreateWindow(

   "Example",                 // See RegisterClass() call.

   "Example _heapset 32 bit only",  // Text for window title bar.

   WS_OVERLAPPEDWINDOW,        // Window style.

   CW_USEDEFAULT,         // Default horizontal position.

   CW_USEDEFAULT,          // Default vertical position.

   CW_USEDEFAULT,            // Default width.

   CW_USEDEFAULT,        // Default height.

   NULL,                  // Overlapped windows have no parent.

   NULL,                  // Use the window class menu.

   hInstance,              // This instance owns this window.

   NULL                   // Pointer not needed.

  );

  /* If window could not be created, return "failure" */

  if (!hWnd)

   return (FALSE);

  /* Make the window visible; update its client area; and return "success" */

  ShowWindow(hWnd, nCmdShow); // Show the window

  UpdateWindow(hWnd);     // Sends WM_PAINT message

  return (hWnd);        // Returns the value from PostQuitMessage

}

void ExampleHeapSet(HWND hWnd)

{

  int hsts;

  char *buffer;

  if ( (buffer = (char *)malloc( 1 )) == NULL )

    exit(0);

  hsts = _heapset( 'Z' );

  switch (hsts)

  {

    case _HEAPOK:

      MessageBox(hWnd,"Heap is OK","Heap",MB_OK|MB_ICONINFORMATION);

      break;

    case _HEAPEMPTY:

      MessageBox(hWnd,"Heap is empty","Heap",MB_OK|MB_ICONINFORMATION);

      break;

    case _HEAPBADNODE:

      MessageBox(hWnd,"Bad node in heap","Heap",MB_OK|MB_ICONINFORMATION);

      break;

    default:

      break;

  }

  free (buffer);

}

#pragma argsused

LRESULT FAR PASCAL _export MainWndProc(HWND hWnd, UINT message,

            WPARAM wParam, LPARAM lParam)

{

  switch (message) {

    case WM_CREATE:

    {

      //Example _heapset

      ExampleHeapSet(hWnd);

      return NULL;

    }

    case WM_QUIT:

    case WM_DESTROY:  // message: window being destroyed

      PostQuitMessage(0);

    break;

    default:      // Passes it on if unproccessed

      return (DefWindowProc(hWnd, message, wParam, lParam));

  }

}


_searchstr example
/* _searchstr example */

#include <stdio.h>

#include <stdlib.h>

char buf[_MAX_PATH];

int main(void)

{

  /* look for TLINK.EXE */

  _searchstr("TLINK.EXE", "PATH", buf);

  if (buf[0] == '\0')

  printf ("TLINK.EXE not found\n");

  else

  printf ("TLINK.EXE found in %s\n", buf);

  return 0;

}


_popen and _pclose example
/* _popen and _pclose example */

/* this program initiates a child process to run the dir command

   and pipes the directory listing from the child to the parent.

*/

#include <stdio.h>     // popen() pclose() feof() fgets() puts()

#include <string.h>    // strlen()

int main( )

{

  FILE* handle;        // handle to one end of pipe

  char message[256];   // buffer for text passed through pipe

  int status;          // function return value

  // open a pipe to receive text from a process running "DIR"

  handle = _popen("dir /b", "rt");

  if (handle == NULL)

  {

    perror("_popen error");

  }

  // read and display input received from the child process

  while (fgets(message, sizeof(message), handle))

  {

    fprintf(stdout, message);

  }

  // close the pipe and check the return status

    status = _pclose(handle);

  if (status == -1)

  {

    perror("_pclose error");

  }

  return(0);

}


wctomb example
/* wctomb example */

#include <stdio.h>

#include <stdlib.h>

void main(void)

{

  int x;

  wchar_t wc = L'a';

  char *pmbNULL = NULL;

  char *pmb = (char *)malloc(sizeof( char ));

  printf (" Convert a wchar_t array into a multibyte string:\n");

  x = wctomb( pmb, wc);

  printf ("Character converted: %u\n", x);

  printf ("Multibyte string: %1s\n\n",pmb);

  printf (" Convert when target is NULL\n");

  x = wctomb( pmbNULL, wc);

  printf ("Character converted: %u\n",x);

  printf ("Multibyte stri ng: %1s\n\n",pmbNULL);

}


wcstombs example
/* wcstombs example */

#include <stdio.h>

#include <stdlib.h>

void main(void)

{

  int x;

  char *pbuf = (char*)malloc( MB_CUR_MAX);

  wchar_t *pwcsEOL = L'\0';

  char *pwchi= L"Hi there!";

  printf (" Convert entire wchar string into a multibyte string:\n");

  x = wcstombs( pbuf, pwchi,MB_CUR_MAX);

  printf ("Character converted: %u\n", x);

  printf ("Multibyte string character: %1s\n\n",pbuf);

  printf (" Convert when target is NULL\n");

  x = wcstombs( pbuf, pwcsEOL, MB_CUR_MAX);

  printf ("Character converted: %u\n",x);

  printf ("Multibyte string: %1s\n\n",pbuf);

}


EasyWin
Using EasyWin

See Also

EasyWin is a feature of Borland C++ that lets you compile standard DOS applications that use traditional TTY style input and output so they will run as true Windows programs. EasyWin does not require you to make any changes to a DOS program in order to run it under Windows.

Note:	EasyWin cannot be used with the DLL version of the run-time library.

Some of the functions that EasyWin includes are:

clreol	gotoxy	wherey

clrscr	wherex

These functions have the same names (and uses) as functions in conio.h header file. Classes in constrea.h provide console I/O functionality for use with C++ streams.

The following routines are portable to EasyWin programs but are not available in 16-bit Windows programs. They are provided to ease porting of existing code into a 16-bit Windows application.

fgetchar	kbhit	puts

getch	perror	scanf

getchar	printf	vprintf

getche	putch	vscanf

gets	putchar


See Also

Converting DOS Applications to Windows

_InitEasyWin

Using EasyWin from within a Windows Program


Converting DOS Applications to Windows

C Example	C++ Example

To convert your console-based applications that use standard files or iostream functions, check the EasyWin Target Type in TargetExpert in the IDE. If you are using the command-line compiler, use the compiler switch (-W). Borland C++ will note that your program does not contain a WinMain function (normally required for Windows applications) and link the EasyWin library. When you run your program in the Windows environment, a standard window will be created, and your program will take input and produce output for that window exactly as if it were the standard screen.

The EasyWin window can be used any time input or output is requested from or to a TTY device. This means that in addition to stdin and stdout, the stderr, stdaux, and cerr devices are all connected to this window.


/* EasyWin C Example */

#include <stdio.h>

int main()

{

  printf("Hello, world\n");

  return 0;

}


// EasyWin C++ Example

#include <iostream.h>

int main()

{

  cout << "Hello, world\n";

  return 0;

}


Using EasyWin from within a Windows Program

See Also	Example

Borland C++ provides EasyWin so you can quickly and easily convert your DOS applications to 16-bit Windows programs.

You might also want to use EasyWin from within a 16-bit Windows program. For example, you might want to add printf functions to your program code to help debug your Windows program.

To use EasyWin from within a Windows program, call _InitEasyWin() before performing any standard input or output.


See Also

Using EasyWin


_InitEasyWin Example
/* _InitEasyWin Example */

#include <stdio.h>

#include <windows.h>

#pragma argsused

int PASCAL WinMain( HANDLE hInstance, HANDLE hPrevInstance,

                    LPSTR lpszCmdParam, int nCmdShow )

{

   char    *p;

   _InitEasyWin();

   p = "This is an example of how Borlancd C++"

    " will automatically\ndo the concatenation for"

    " you on very long strings,\nresulting in nicer"

    " looking programs.";

   printf(p);

   return(0);

}


Error and Warning Messages

Overview

Symbols

, expected - Compiler Error

#undef directive ignored - Compiler Warning

'%s' is not a valid library - Linker Warning

'%s' is not a valid template type member - Compiler Error

'%s' requires run-time initialization/finalization - Compiler Error

( expected - Compiler Error

) expected - Compiler Error

: expected after private - Compiler Error

: expected after protected - Compiler Error

: expected after public - Compiler Error

< expected - Compiler Error

> expected - Compiler Error

{ expected - Compiler Error

} expected - Compiler Error

16-bit segments not supported in module '%s' - Linker Error

32-bit processing not supported in overlays - Linker Error

A

Abnormal program termination - Run-Time Error

Access can only be changed to public or protected - Compiler Error

Added file 'filename' does not begin correctly, ignored - Librarian Warning

Address of overloaded function 'function' doesn't match 'type' - Compiler Error

Ambiguity between 'function1' and 'function2' - Compiler Error

Ambiguous member name 'name' - Compiler Error

Ambiguous operators need parentheses - Compiler Warning

Ambiguous Override of Virtual Base Member '<function1>': '<function2>' - Compiler Error

Application is running - Run-Time Error

Array allocated using 'new' may not have an initializer - Compiler Error

Array bounds missing ] - Compiler Error

Array must have at least one element - Compiler Error

Array of references is not allowed - Compiler Error

Array size for 'delete' ignored  - Compiler Warning

Array size for 'delete' ignored - Compiler Error

Array size too large - Compiler Error

Array variable 'identifier' is near - Compiler Warning

Assembler statement too long - Compiler Error

Assigning 'type' to 'enumeration' - Compiler Warning

Assignment to 'this' not allowed, use X::operator new instead - Compiler Error

Attempt to export non-public symbol '%s' - Linker Error

Attempt to export non-public symbol 'symbol' - Linker Warning

Attempt to grant or reduce access to 'identifier' - Compiler Error

Attempting to return a reference to a local object - Compiler Error

Attempting to return a reference to local variable 'identifier' - Compiler Error

Automatic data segment exceeds 64K - Linker Error

B

'base' is an indirect virtual base class of 'class' - Compiler Error

Bad call of intrinsic function - Compiler Error

Bad character in parameters - Linker Error

Bad define directive syntax - Compiler Error

Bad field list in debug information in module '%s' - Linker Error

Bad file name '%s' - Linker Error

Bad file name format in include directive - Compiler Error

Bad file name format in line directive - Compiler Error

Bad GCD type in GRPDEF, extended dictionary aborted - Librarian Warning

Bad ifdef directive syntax - Compiler Error

Bad LF_POINTER in module '%s' - Linker Error

Bad object file '%s' near file offset %lx - Linker Error

Bad object file record in library file 'filename' in module 'module' near module file offset '0xxxxxxxxx' - Linker Error

Bad object file record in library file 'filename' near module file offset '0xxxxxxxxx' - Linker Error

Bad OMF record type 'type' encountered in module 'module' - Librarian Error

Bad syntax for pure function definition - Compiler Error

Bad undef directive syntax - Compiler Error

Bad version number in parameter block - Linker Error

Base class '<base1>' is also a base class of '<base2>' - Compiler Error

Base class 'class' contains dynamically dispatchable functions - Compiler Error

Base class 'class' is inaccessible because also in 'class' - Compiler Warning

Base class 'class' is included more than once - Compiler Error

Base class 'class' is initialized more than once - Compiler Error

Base initialization without a class name is now obsolete - Compiler Warning

Bit field cannot be static - Compiler Error

Bit field too large - Compiler Error

Bit fields must be signed or unsigned int - Compiler Error

Bit fields must be signed or unsigned int - Compiler Warning

Bit fields must contain at least one bit - Compiler Error

Bit fields must have integral type - Compiler Error

Body has already been defined for function 'function' - Compiler Error

Both return and return with a value used - Compiler Warning

C

Call of nonfunction - Compiler Error

Call to function 'function' with no prototype - Compiler Warning

Call to function with no prototype - Compiler Warning

Cannot add or subtract relocatable symbols - Compiler Error

Cannot allocate a reference - Compiler Error

Cannot call 'main' from within the program - Compiler Error

Cannot call near class member function with a pointer of type 'type' - Compiler Error

Cannot cast from 'type1' to 'type2' - Compiler Error

Cannot convert 'type1' to 'type2' - Compiler Error

Cannot create instance of abstract class 'class' - Compiler Error

Cannot create precompiled header: reason - Compiler Error

Cannot define a pointer or reference to a reference - Compiler Error

Cannot find 'class'::operator=('class'&) to copy a vector - Compiler Error

Cannot find class::class (class &) to copy a vector - Compiler Error

Cannot find default constructor to initialize array element of type 'class' - Compiler Error

Cannot find default constructor to initialize base class 'class' - Compiler Error

Cannot find default constructor to initialize member 'identifier' - Compiler Error

Cannot generate 'function' from template function 'template' - Compiler Error

Cannot have a non-inline function in a local class - Compiler Error

Cannot have a static data in a local class - Compiler Error

Cannot inherit non-RTTI class from RTTI base - Compiler Error

Cannot initialize 'type1' with 'type2' - Compiler Error

Cannot initialize a class member here - Compiler Error

Cannot modify a const object - Compiler Error

Cannot overload 'main' - Compiler Error

Cannot Take Address of 'main' - Compiler Error

Cannot Throw '<type>' -- Ambiguous Base Class '<base>' - Compiler Error

Cannot use tiny or huge memory model with Windows - Compiler Error

Cannot write GRPDEF list, extended dictionary aborted - Librarian Warning

Case bypasses initialization of a local variable - Compiler Error

Case outside of switch - Compiler Error

Case statement missing : - Compiler Error

'catch' Expected  - Compiler Error

Character constant must be one or two characters long - Compiler Error

Class 'class' may not contain pure functions - Compiler Error

Class '<classname>' is abstract because of 'member = 0' - Compiler Error

Class member 'member' declared outside its class - Compiler Error

Code has no effect - Compiler Warning

Common segment exceeds 64K - Linker Error

Compiler could not generate copy constructor for class 'class' - Compiler Error

Compiler could not generate default constructor for class 'class' - Compiler Error

Compiler could not generate default destructor for class 'class' - Compiler Error

Compiler could not generate operator = for class 'class' - Compiler Error

Compiler stack overflow - Compiler Error

Compiler table limit exceeded - Compiler Error

Compound statement missing } - Compiler Error

Condition is always false - Compiler Warning

Condition is always true - Compiler Warning

Conflicting type modifiers - Compiler Error

Constant expression required - Compiler Error

Constant is long - Compiler Warning

Constant member 'member' in class without constructors - Compiler Error

Constant member 'member' is not initialized - Compiler Warning

Constant out of range in comparison - Compiler Warning

Constant variable 'variable' must be initialized - Compiler Error

Constructor cannot be declared 'const' or 'volatile' - Compiler Error

Constructor cannot have a return type specification - Compiler Error

'constructor' is not a base class of 'class' - Compiler Error

Constructor initializer list ignored - Compiler Warning

Conversion may lose significant digits - Compiler Warning

Conversion operator cannot have a return type specification - Compiler Error

Conversion to 'type' will fail for members of virtual base 'class' - Compiler Warning

Could not allocate memory for per module data - Librarian Error

Could not create list file 'filename' - Librarian Error

Could not create swapfile - Linker Error

Could not find a match for argument(s) - Compiler Error

Could not find file 'filename' - Compiler Error

Could not get procedure address from DLL '%s' - Linker Error

Could not load DLL '%s' - Linker Error

Could not write output - Librarian Error

D

Debug information enabled, but no debug information found in OBJs - Linker Warning

Debug information in module 'module' will be ignored - Linker Warning

Debugging information overflow; try fewer modules with debug info - Linker Error

Declaration does not specify a tag or an identifier - Compiler Error

Declaration ignored - Compiler Warning

Declaration is not allowed here - Compiler Error

Declaration missing ; - Compiler Error

Declaration of static function '(...)' ignored - Compiler Warning

Declaration syntax error - Compiler Error

Declaration terminated incorrectly - Compiler Error

Declaration was expected - Compiler Error

Declare operator delete (void*) or (void*, size_t) - Compiler Error

Declare operator delete[] (void*) or (void*, size_t) - Compiler Error

Declare type 'type' prior to use in prototype - Compiler Warning

Default argument value redeclared for parameter 'parameter' - Compiler Error

Default argument value redeclared - Compiler Error

Default expression may not use local variables - Compiler Error

Default outside of switch - Compiler Error

Default value missing following parameter 'parameter' - Compiler Error

Default value missing - Compiler Error

Define directive needs an identifier - Compiler Error

Delete array size missing ] - Compiler Error

Destructor cannot be declared 'const' or 'volatile' - Compiler Error

Destructor cannot have a return type specification - Compiler Error

Destructor for 'class' required in conditional expression - Compiler Error

Destructor for class is not accessible - Compiler Error

Destructor name must match the class name - Compiler Error

Directive ignored - Linker Warning

Divide error - Run-Time Error

Division by zero - Compiler Error

Division by zero - Compiler Warning

do statement must have while - Compiler Error

do-while statement missing ( - Compiler Error

do-while statement missing ) - Compiler Error

do-while statement missing ; - Compiler Error

DOS error, ax = 'decimal number' - Linker Error

DPMI programs must use the large memory model - Compiler Error

Duplicate case - Compiler Error

Duplicate Handler for '<type1>', Already Had '<type2>' - Compiler Error

Duplicate ordinal 'number' in exports - Linker Error

Duplicate ordinal for exports: '%s' (%d) and '%s' (%d) - Linker Error

E

Empty LEDATA record in module %s - Linker Warning

Enum syntax error - Compiler Error

Error directive: 'message' - Compiler Error

Error opening 'filename' for output - Librarian Error

Error opening 'filename' - Librarian Error

Error reading input file, exe format error? - Linker Warning

Error renaming 'filename' to 'filename' - Librarian Error

Error writing output file - Compiler Error

Error writing output file - Linker Warning

'__except' or '__finally' Expected Following '__try' - Compiler Error

Exception handling not enabled - Compiler Error

Exception Handling Variable May Not Be Used Here - Compiler Error

Exception Specification Not Allowed Here - Compiler Error

Exe alignment too small - Linker Warning

Explicit stacks are ignored for PE images - Linker Warning

Export '%s' is duplicated - Linker Warning

Expression expected - Compiler Error

Expression of scalar type expected - Compiler Error

Expression syntax - Compiler Error

Extended dictionary not found in library %s: extended dictionaries ignored - Linker Warning

Extern '%s' was not qualified with __import in module %s - Linker Warning

extern variable cannot be initialized - Compiler Error

Extra argument in template class name 'template' - Compiler Error

Extra parameter in call to function - Compiler Error

Extra parameter in call - Compiler Error

F

Failed read from '%s' - Linker Error

Failed write to '%s' - Linker Error

File is not a New Exe - Linker Warning

File is not an exe - Linker Warning

File must contain at least one external declaration - Compiler Error

File name too long - Compiler Error

'filename' couldn't be created, original won't be changed - Librarian Warning

'filename' file not found - Librarian Error

'filename' ('linenum'): Duplicate external name in exports - Linker Warning

'filename' ('linenum'): Duplicate internal name in exports - Linker Warning

'filename' ('linenum'): Duplicate internal name in imports - Linker Warning

'filename' ('linenum'): File read error - Linker Error

'filename' ('linenum'): Incompatible attribute - Linker Error

'filename' ('linenum'): Missing internal name - Linker Error

'filename' ('linenum'): Syntax error - Linker Error

Fixup overflow at 'seg:xxxx'h, target = 'seg:xxxx'h in module 'module' - Linker Error

Fixup overflow at 'seg:xxxx'h, target = 'symbol' in module 'module' - Linker Error

Fixupp to zero length segment in module %s - Linker Error

Floating point error: Divide by 0 - Run-Time Error

Floating point error: Domain - Run-Time Error

Floating point error: Overflow - Run-Time Error

Floating point error: Partial loss of precision - Run-Time Error

Floating point error: Stack fault - Run-Time Error

Floating point error: Underflow - Run-Time Error

For statement missing ( - Compiler Error

For statement missing ) - Compiler Error

For statement missing ; - Compiler Error

Friends must be functions or classes - Compiler Error

Function body ignored - Compiler Warning

Function call missing ) - Compiler Error

'function' cannot return a value - Compiler Error

Function defined inline after use as extern - Compiler Error

Function definition cannot be a typedef'ed declaration - Compiler Error

Function 'function' cannot be static - Compiler Error

Function 'function' should have a prototype - Compiler Error

'function' must be declared with no parameters - Compiler Error

'function' must be declared with one parameter - Compiler Error

'function' must be declared with two parameters - Compiler Error

Function should return a value - Compiler Error

Function should return a value - Compiler Warning

'function' was previously declared with the language 'language' - Compiler Error

'function1' cannot be distinguished from 'function2' - Compiler Error

'function1' hides virtual function 'function2' - Compiler Warning

Function1 hides virtual function function2 - Compiler Error

Functions 'function1' and 'function2' both use same dispatch number - Compiler Error

Functions are not expanded inline - Compiler Warning

Functions Cannot Return Arrays or Functions - Compiler Error

Functions containing local destructors are not expanded inline in function 'function' - Compiler Warning

Functions containing reserved words are not expanded inline - Compiler Warning

Functions containing reserved words are not expanded inline

Functions may not be part of a struct or union - Compiler Error

G

General error (16-bit) - Linker Error

General error (32-bit) - Linker Error

General error in library file in module 'module' near module file offset '0xyyyyyyyy'  - Linker Error

General error in module '%s' - Linker Error

General error in module 'module' near module file offset '0xyyyyyyyy' - Linker Error

Global anonymous union not static - Compiler Error

Goto bypasses initialization of a local variable - Compiler Error

Goto Into an Exception Handler is Not Allowed - Compiler Error

Goto statement missing label - Compiler Error

Group 'group' exceeds 64K - Linker Error

Group 'group1' overlaps group 'group2' - Linker Warning

Group overflowed maximum size: 'group' - Compiler Error

H

Handler for '<type1>' Hidden by Previous Handler for '<type2>' - Compiler Error

Hexadecimal value contains more than 3 digits - Compiler Error

Hexadecimal value contains more than 3 digits - Compiler Warning

I

'identifier' cannot be declared in an anonymous union - Compiler Error

'identifier' cannot start a parameter declaration - Compiler Error

'identifier' declared but never used - Compiler Warning

Identifier expected - Compiler Error

Identifier 'identifier' cannot have a type qualifier - Compiler Error

'identifier' is assigned a value that is never used - Compiler Warning

Identifier is assigned a value that is never used - Compiler Error

'identifier' is declared as both external and static - Compiler Warning

Identifier is declared as both external and static - Compiler Error

'identifier' is declared as both external and static - Compiler Error

'identifier' is not a member of 'struct' - Compiler Error

'identifier' is not a non-static member and can't be initialized here - Compiler Error

'identifier' is not a parameter - Compiler Error

'identifier' is not a public base class of 'classtype' - Compiler Error

'identifier' must be a member function or have parameter of class type - Compiler Error

'identifier' must be a member function - Compiler Error

'identifier' must be a previously defined class or struct - Compiler Error

'identifier' must be a previously defined enumeration tag - Compiler Error

'identifier' specifies multiple or duplicate access - Compiler Error

If statement missing ( - Compiler Error

If statement missing ) - Compiler Error

Ill-formed pragma - Compiler Warning

Ill-formed pragma - Compiler Warning

Illegal ACBP byte in SEGDEF in module %s - Linker Error

Illegal character 'character' (0x'value') - Compiler Error

Illegal component to GRPDEF in module %s - Linker Error

Illegal group definition: 'group' in module 'module' - Linker Error

Illegal initialization - Compiler Error

Illegal local public in %m - Linker Error

Illegal octal digit - Compiler Error

Illegal parameter to __emit__ - Compiler Error

Illegal pointer subtraction - Compiler Error

Illegal structure operation - Compiler Error

Illegal to take address of bit field - Compiler Error

Illegal use of floating point - Compiler Error

Illegal use of member pointer - Compiler Error

Illegal use of pointer - Compiler Error

Image base address must be a multiple of 0x10000 - Linker Error

Implicit conversion of 'type1' to 'type2' not allowed - Compiler Error

Import record does not match previous definition - Linker Warning

Imported references from VIRDEFs not supported - Linker Error

Improper use of typedef 'identifier' - Compiler Error

Include Files Nested too Deep - Compiler Error

Incompatible type conversion - Compiler Error

Incorrect number format - Compiler Error

Incorrect option - Compiler Error

Incorrect use of default - Compiler Error

Incorrect version of RLINK32.DLL - Linker Error

Initialization is only partially bracketed

Initialization is only partially bracketed - Compiler Warning

Initializer for object '' " ignored - Compiler Warning

Initializing 'enumeration' with 'type' - Compiler Error

Initializing 'type' with 'type' - Compiler Warning

Initializing enumeration with type - Compiler Warning

Inline assembly not allowed in inline and template function - Compiler Error

Inline assembly not allowed

Internal compiler error - Compiler Error

Internal linker error 'errorcode' - Linker Error

Invalid combination of opcode and operands - Compiler Error

Invalid entry at 'segment:xxxxh' - Linker Warning

Invalid entry point offset - Linker Error

Invalid indirection - Compiler Error

Invalid initial stack offset - Linker Error

Invalid macro argument separator - Compiler Error

Invalid page size value ignored - Librarian Warning

Invalid pointer addition - Compiler Error

Invalid register combination (e.g. [BP+BX]) - Compiler Error

Invalid segment definition in module 'module' - Linker Error

Invalid template argument list - Compiler Error

Invalid template qualified name 'template::name' - Compiler Error

Invalid use of dot - Compiler Error

Invalid use of template 'template' - Compiler Error

Irreducible expression tree - Compiler Error

Irreducible expression tree - Compiler Error

L

Last parameter of 'operator' must have type 'int' - Compiler Error

Library contains COMDEF records - extended dictionary not created - Librarian Warning

Library too large, please restart with /P 'size' - Librarian Error

Library too large, restart with library page size 'size' - Librarian Error

Limit of 254 segments for new executable file exceeded - Linker Error

Linkage specification not allowed - Compiler Error

Linker stack overflow - Linker Error

Lvalue required - Compiler Error

M

Macro argument syntax error - Compiler Error

Macro definition ignored - Compiler Warning

Macro expansion too long - Compiler Error

main must have a return type of int - Compiler Error

Malformed command-line - Linker Error

Matching base class function 'function' has different dispatch number - Compiler Error

Matching base class function 'function' is not dynamic - Compiler Error

Maximum precision used for member pointer type type - Compiler Error

Member 'member' cannot be used without an object - Compiler Error

Member 'member' has the same name as its class - Compiler Error

Member 'member' is initialized more than once - Compiler Error

Member function must be called or its address taken - Compiler Error

Member identifier expected - Compiler Error

Member is ambiguous: 'member1' and 'member2' - Compiler Error

'member' is not accessible - Compiler Error

Member pointer required on right side of .* or ->* - Compiler Error

Memory full listing truncated! - Librarian Warning

Memory reference expected - Compiler Error

Misplaced break - Compiler Error

Misplaced continue - Compiler Error

Misplaced decimal point - Compiler Error

Misplaced elif directive - Compiler Error

Misplaced else directive - Compiler Error

Misplaced else - Compiler Error

Misplaced endif directive - Compiler Error

Mixed common types in module %s. Cannot mix COMDEFs and VIRDEFs - Linker Error

Mixing pointers to different 'char' types - Compiler Error

Mixing pointers to signed and unsigned char - Compiler Warning

Multiple base classes not supported - Compiler Error

Multiple base classes require explicit class names - Compiler Error

Multiple declaration for 'identifier' - Compiler Error

Multiple entry points defined - Linker Error

Multiple stack segments found. The most recent one will be used. - Linker Warning

Must take address of a memory location - Compiler Error

N

Need an identifer to declare - Compiler Error

New Executable header overflowed 64K - Linker Error

No : following the ? - Compiler Error

No automatic data segment - Linker Warning

No base class to initialize - Compiler Error

No declaration for function 'function' - Compiler Error

No declaration for function 'function' - Compiler Warning

No file name ending - Compiler Error

No internal name for IMPORT in .DEF file - Linker Error

No module definition file specified: using defaults - Linker Warning

No output file specified - Linker Error

No program entry point - Linker Warning

No program starting address defined - Linker Warning

No stack - Linker Warning

Non-ANSI Keyword Used: '<keyword>' - Compiler Error

Non-const function function called for const object - Compiler Error

Non-constant function 'function' called for constant object - Compiler Warning

Non-virtual function 'function' declared pure - Compiler Error

Non-volatile function 'function' called for volatile object - Compiler Error

Non-volatile function function called for volatile object - Compiler Warning

Nonportable pointer comparison - Compiler Error

Nonportable pointer comparison - Compiler Warning

Nonportable pointer conversion - Compiler Error

Nonportable pointer conversion - Compiler Warning

Nontype template argument must be of scalar type - Compiler Error

Not an allowed type - Compiler Error

Not enough memory for command-line buffer - Librarian Error

Not enough memory - Linker Error

Numeric constant too large - Compiler Error

O

Object module 'filename' is invalid - Librarian Error

Objects of type 'type' cannot be initialized with { } - Compiler Error

Old debug information in module '%s' will be ignored - Linker Warning

Only member functions may be 'const' or 'volatile' - Compiler Error

Only one of a set of overloaded functions can be functions can be "C" - Compiler Error

Operand of 'delete' must be non-const pointer - Compiler Error

operator -> must return a pointer or a class - Compiler Error

operator [] missing ] - Compiler Error

operator delete must return void - Compiler Error

Operator delete[] must return void - Compiler Error

Operator must be declared as function - Compiler Error

'operator' must be declared with one or no parameters - Compiler Error

'operator' must be declared with one or two parameters - Compiler Error

Operator new must have an initial parameter of type size_t - Compiler Error

Operator new must return an object of type void * - Compiler Error

Operator new[] must have an initial parameter of type size_t - Compiler Error

Operator new[] must return an object of type void - Compiler Error

Operators may not have default argument values - Compiler Error

Optimizer: Error Reading Input File - Linker Error

Optimizer: Error Writing Output File - Linker Error

Optimizer: Out of Memory - Linker Error

Out of memory creating extended dictionary - Librarian Error

Out of memory for block '%s' - Linker Error

Out of memory reading LE/LIDATA record from object module - Librarian Error

Out of memory - Compiler Error

Out of memory - Librarian Error

Out of memory - Linker Error

Out of memory - Linker Warning

Out of space allocating per module debug struct - Librarian Error

Output device is full - Librarian Error

'overload' is now unnecessary and obsolete - Compiler Warning

Overloadable operator expected - Compiler Error

Overloaded 'function name' ambiguous in this context - Compiler Error

Overloaded prefix 'operator' used as a postfix operator - Compiler Error

Overloaded prefix 'operator' used as a postfix operator - Compiler Warning

P

Parameter 'number' missing name - Compiler Error

Parameter 'parameter' is never used - Compiler Error

Parameter 'parameter' is never used - Compiler Warning

Parameter names are used only with a function body - Compiler Error

'path' - path is too long - Librarian Error

Pointer to structure required on left side of -> or ->* - Compiler Error

Possible reference to undefined extern xxxx::i in module 'module' - Linker Warning

Possible use of 'identifier' before definition - Compiler Error

Possible use of 'identifier' before definition - Compiler Warning

Possibly incorrect assignment - Compiler Error

Possibly incorrect assignment - Compiler Warning

Public 'symbol' in module 'filename' clashes with prior module - Librarian Error

Public symbol 'symbol' defined in both module <module1> and <module2> - Linker Warning

R

'reason' - extended dictionary not created - Librarian Warning

Record kind 'num' found, expected theadr or lheadr in module 'filename' - Librarian Error

Record length 'len' exceeds available buffer in module 'module' - Librarian Error

Recursive template function: '" instantiated '' - Compiler Error

Redefinition of 'macro' is not identical - Compiler Error

Redefinition of 'macro' is not identical - Compiler Warning

Reference initialized with 'type1', needs lvalue of type 'type2' - Compiler Error

Reference Member '<member>' Initialized with a Non-Reference Parameter - Compiler Error

Reference member 'member' in class without constructors - Compiler Error

Reference member 'member' is not initialized - Compiler Error

Reference member 'member' needs a temporary for initialization - Compiler Error

Reference variable 'variable' must be initialized - Compiler Error

Register allocation failure - Compiler Error

Register allocation failure - Compiler Error

Resource alignment too small - Linker Warning

Results are safe in file 'filename' - Librarian Warning

S

Self relative fixupp overflowed in module 'module' - Linker Warning

Side effects are not allowed - Compiler Error

Size of 'identifier' is unknown or zero - Compiler Error

Size of the type is unknown or zero - Compiler Error

sizeof may not be applied to a bit field - Compiler Error

sizeof may not be applied to a function - Compiler Error

'specifier' has already been included - Compiler Error

Stack overflow - Run-Time Error

Stack size is less than 1400h. It has been reset to 1400h - Linker Warning

Statement missing ; - Compiler Error

Storage class 'storage class' is not allowed here - Compiler Error

Structure passed by value - Compiler Error

Structure passed by value - Compiler Warning

Structure required on left side of . or .* - Compiler Error

Structure size too large - Compiler Error

Stub program exceeds 64K - Linker Error

Style of function definition is now obsolete - Compiler Error

Style of function definition is now obsolete - Compiler Warning

Subscripting missing ] - Compiler Error

Superfluous & with function - Compiler Error

Superfluous & with function - Compiler Warning

Suspicious pointer conversion - Compiler Error

Suspicious pointer conversion - Compiler Warning

Switch selection expression must be of integral type - Compiler Error

Switch statement missing ( - Compiler Error

Switch statement missing ) - Compiler Error

'symbol' conflicts with module 'module' in module 'module' - Linker Warning

'symbol' defined in module 'module' is duplicated in module 'module' - Linker Error

T

Table limit exceeded - Linker Error

Target index of FIXUPP is 0 in Module '%s' - Linker Error

Template argument must be a constant expression - Compiler Error

Template class nesting too deep: 'class' - Compiler Error

Template function argument 'argument' not used in argument types - Compiler Error

Template functions may only have 'type-arguments' - Compiler Error

Templates can only be declared at file level - Compiler Error

Templates must be classes or functions - Compiler Error

Templates not supported - Compiler Error

Temporary used for parameter '???' - Compiler Warning

Temporary used for parameter 'number' in call to 'function' - Compiler Warning

Temporary used for parameter 'number' - Compiler Warning

Temporary used for parameter 'parameter' in call to 'function' - Compiler Warning

Temporary used for parameter 'parameter' - Compiler Warning

Temporary used for parameter 2 in call to '???' - Compiler Warning

Temporary used to initialize 'identifier' - Compiler Error

Temporary used to initialize 'identifier' - Compiler Warning

Terminated by user (16-bit) - Linker Error

Terminated by user (32-bit) - Linker Error

The '...' Handler Must be Last - Compiler Error

The combinations '+*' or '*+' are not allowed - Librarian Error

The constructor 'constructor' is not allowed - Compiler Error

The value for 'identifier' is not within the range of an int - Compiler Error

'this' can only be used within a member function - Compiler Error

Too few arguments in template class name 'template' - Compiler Error

Too few parameters in call to function - Compiler Error

Too few parameters in call - Compiler Error

Too many commas on command-line - Linker Error

Too many decimal points - Compiler Error

Too many default cases - Compiler Error

Too many default libraries - Linker Error

Too many error or warning messages - Compiler Error

Too many error or warning messages - Linker Error

Too many errors - Linker Error

Too many exponents - Compiler Error

Too many initializers - Compiler Error

Too many LNAMEs - Linker Error

Too many storage classes in declaration - Compiler Error

Too many types in declaration - Compiler Error

Too much global data defined in file - Compiler Error

Trying to derive a far class from the huge base 'base' - Compiler Error

Trying to derive a far class from the near base 'base' - Compiler Error

Trying to derive a huge class from the far base 'base' - Compiler Error

Trying to derive a huge class from the near base 'base' - Compiler Error

Trying to derive a near class from the far base 'base' - Compiler Error

Trying to derive a near class from the huge base 'base' - Compiler Error

Two consecutive dots - Compiler Error

Two operands must evaluate to the same type - Compiler Error

'<type>' is Not a Polymorphic Class Type - Compiler Error

Type '<type>' is Not a Defined Class with Virtual Functions - Compiler Error

Type 'typename' may not be defined here - Compiler Error

Type mismatch in default argument value - Compiler Error

Type mismatch in default value for parameter 'parameter' - Compiler Error

Type mismatch in parameter 'number' in call to 'function' - Compiler Error

Type mismatch in parameter 'number' in template class name 'template' - Compiler Error

Type mismatch in parameter 'number' - Compiler Error

Type mismatch in parameter 'parameter' in call to 'function' - Compiler Error

Type mismatch in parameter 'parameter' in template name 'template' - Compiler Error

Type mismatch in parameter 'parameter' - Compiler Error

Type mismatch in redeclaration of 'identifier' - Compiler Error

Type name expected - Compiler Error

Type qualifier 'identifier' must be a struct or class name - Compiler Error

U

Unable to create output file 'filename' - Compiler Error

Unable to open 'filename' - Compiler Error

Unable to open file '%s' - Linker Error

Unable to open file 'filename' - Linker Error

Unable to open include file 'filename' - Compiler Error

Unable to open input file 'filename' - Compiler Error

Unable to process debug info, disable TASM /zi option - Linker Error

Undefined label 'identifier' - Compiler Error

Undefined structure 'structure' - Compiler Error

Undefined structure 'structure' - Compiler Warning

Undefined symbol 'identifier' - Compiler Error

Undefined symbol 'symbol' in module 'module' - Linker Error

Unexpected } - Compiler Error

Unexpected end of file in comment started on 'line number' - Compiler Error

Unexpected end of file in conditional started on 'line number' - Compiler Error

Union cannot be a base type - Compiler Error

Union cannot have a base type - Compiler Error

Union member 'member' is of type class with constructor - Compiler Error

Union member 'member' is of type class with destructor - Compiler Error

Union member 'member' is of type class with operator = - Compiler Error

Unions cannot have virtual member functions - Compiler Error

Unknown assembler instruction - Compiler Warning

Unknown command line switch 'X' ignored - Librarian Warning

Unknown language, must be C or C++ - Compiler Error

Unknown Optimization - Linker Error

Unknown preprocessor directive: 'identifier' - Compiler Error

Unreachable code - Compiler Warning

Unsupported option '%s' - Linker Error

Unterminated string or character constant - Compiler Error

Use '> >' for nested templates instead of '>>' - Compiler Error

Use . or -> to call 'member', or & to take its address - Compiler Error

Use . or -> to call function - Compiler Error

Use :: to take the address of a member function - Compiler Error

Use qualified name to access nested type 'type' - Compiler Warning

User break, library aborted - Librarian Error

User break - Compiler Error

User-defined message - Compiler Error

Using based linking for DLLs may cause the DLL to malfunction - Linker Warning

V

Value of type void is not allowed - Compiler Error

Variable 'identifier' is initialized more than once - Compiler Error

Variable 'variable' has been optimized and is no longer available - Compiler Error

VIRDEF Name Conflict for '<function>' - Compiler Error

'virtual' can only be used with member functions - Compiler Error

Virtual function 'function1' conflicts with base class 'base' - Compiler Error

virtual specified more than once - Compiler Error

void & is not a valid type - Compiler Error

Void functions may not return a value - Compiler Warning

W

While statement missing ( - Compiler Error

While statement missing ) - Compiler Error

Wrong number of arguments in call of macro 'macro' - Compiler Error


Error and Warning Messages Overview

Messages are written with the message class first, followed by the source file name and line number where the error was detected, and finally with the text of the message itself.

Be aware that the compiler generates messages as they are detected. Because C and C++ don't force any restrictions on placing statements on a line of text, the true cause of the error might be one or more lines before or after the line number mentioned in the error message.

Symbols

Some messages include a symbol (such as a variable, file name, or module) that is taken from your program. Here's what the symbols in error and warning messages stand for.

Symbol	Meaning

'argument' 	An argument

'class'	A class name

'filename'	A file name (with or without extension)

'function'	A function name

'group'	A group name

'identifier'	An identifier (variable name or other)

'language'	The name of a programming language

'len'	An actual number

'member'	The name of a data member or member function

'message'	A message string

'module'	A module name

'num'	An actual number

'number'	An actual number

'option'	An option

'parameter'	A parameter name

'path'	A path name

'reason'	Reason given in message

'segment'	A segment name

'size'	An actual number

'specifier'	A type specifier

'symbol'	A symbol name

'type'	A type name

'XXXXh'	A 4-digit hexadecimal number, followed by h

Compiler Errors and Warnings

Compile-time error messages indicate errors in program syntax, command-line errors, or errors in accessing a disk or memory. When most compile-time errors occurs, the compiler completes the current phase (preprocessing, parsing, optimizing and code-generating) of the compilation and stops. But when fatal compile-time errors happen, compilation stops completely. If a fatal error occurs, fix the error and restart compilation.

Run-time errors occur after the program has successfully compiled and is running. Run-time errors are usually caused by logic errors in your program code. If you receive a run-time error, you must fix the error in your source code and recompile the program for the fix to take effect.

Warnings indicate that conditions which are suspicious but legitimate exist or that machine-dependent constructs exist in your source files. Warnings do not stop compilation.

Warnings are issued as a result of a variety of conditions.

ANSI violations	Warn you of code that is acceptable to Borland C++ (because of C++ code or Borland C++ extensions), but is not in the ANSI definition of C.

Frequent warnings	Alert you to common programming mistakes. These warning messages point out conditions that are not in violation of the Borland C++ language but can yield the wrong result.

Less frequent warnings	Alert you to less common programming mistakes. These warning messages point out conditions that are not in violation of the Borland C++ language but can yield the wrong result.

Portability warnings	Alert you to possible problems with porting your code to other compilers. These usually apply to Borland C++ extensions.

C++ warnings	Warn you of errors you've made in your C++ code. They might be due to obsolete items or incorrect syntax.

Run-time Errors and Warnings

Run-time errors occur after the program has successfully compiled and is running.

Linker Errors and Warnings

As a rule, Linker errors do not make the linker stop or cause .EXE or .MAP files to be deleted. When such errors happens, don't try to execute the .EXE file. Fix the error and re-link.

A fatal link error, however, stops the linker immediately. In such a case, the .EXE file is deleted. All Linker errors are treated as fatal errors if you are compiling from the Integrated Development Environment (IDE).

Linker warnings point out conditions that you should fix. When warnings occur, .EXE and .MAP files are still created.

Librarian Errors and Warnings

Librarian errors and warnings occur when there is a problem with files or extended dictionaries, when memory runs low, or when there are problems as libraries are accessed.


Compiler table limit exceeded

One of the compiler's internal tables overflowed.

This usually means that the module being compiled contains too many function bodies.

This limitation will not be solved by making more memory available to the compiler. You need to simplify the file being compiled.


Irreducible expression tree

This is a sign of some form of compiler error. An expression on the indicated line of the source file caused the code generator to be unable to generate code.

The expression should be avoided. Notify Borland if an expression can consistently reproduce this error.


Register allocation failure

This is a sign of some form of compiler error.

Possible Causes

An expression on the indicated line of the source file was so complicated that the code generator could not generate code for it.

Solutions

Simplify the expression. If this does not solve the problem, avoid the expression.

Notify Borland if an expression can consistently reproduce this error.


Bad call of intrinsic function

You have used an intrinsic function without supplying a prototype. You may have supplied a prototype for an intrinsic function that was not what the compiler expected.


Unable to open input file 'filename'

This error occurs if the source file can't be found.

Check the spelling of the name. Make sure the file is on the specified disk or directory.

Check under Options|Settings|Directories and verify that the proper directory paths are listed. If multiple paths are required, use a semi-colon to separate them, like this:

C:\bc\lib;C:\bc\owl\lib


Unable to create output file 'filename'

This error occurs if the work disk is full or write protected.

This error also occurs if the output directory does not exist.

Solutions

If the disk is full, try deleting unneeded files and restarting the compilation.

If the disk is write-protected, move the source files to a writable disk and restart the compilation.


Error writing output file

A DOS error that prevents the C++ IDE from writing an .OBJ, .EXE, or temporary file.

Solutions

Make sure that the Output directory in the Directories dialog box is a valid directory.

Check that there is enough free disk space.


Error directive: 'message'

This message is issued when an #error directive is processed in the source file.

'message' is the text of the #error directive.


Out of memory (compiler)
Out of memory

The total working storage is exhausted.

This error can occur in the following circumstances:

Not enough virtual memory is available for compiling a particular file. In this case, shut down any other concurrent applications. You may also try to re-configure your machine for more available virtual memory, or break up the source file being compiled into smaller separate components. You can also compile the file on a system with more available RAM.

The compiler has encountered an exceedingly complex or long expression at the line indicated and has insufficient reserves to parse it. Break the expression down into separate statements.


Unable to open 'filename' (compiler)
Unable to open 'filename'

This error occurs if the specified file can't be opened.

Make sure the file is on the specified disk or directory. Check Options|Settings|Directories and verify the proper paths are listed. If multiple paths are required, use a semi-colon to separate them, like this:

C:\bc\include;c:\bc\include\owl


Declaration syntax error

Your source file contained a declaration that was missing a symbol or had an extra symbol added to it.

Check for a missing semi-colon or parenthesis on that line or on previous lines.


Wrong number of arguments in call of macro 'macro'

Your source file called the named macro with an incorrect number of arguments.


Array size too large

The declared array is larger than 64K and the 'huge' keyword was not used.

If you need an array of this size, either use the 'huge' modifier, like this:

int huge array[70000L];  /* Allocate 140000 bytes */

or dynamically allocate it with farmalloc( ) or farcalloc( ), like this:

int huge *array = (int huge *) farmalloc (sizeof (int) * 70000); ?? Allocate 140,000 bytes


Invalid macro argument separator

In a macro definition, arguments must be separated by commas.

The compiler encountered some other character after an argument name.

This is correct:

#define tri_add(a, b, c)  ((a) + (b) + (c))

This is incorrect:

#define tri_add(a  b. c)  ((a) + (b) + (c))


Assembler statement too long

Inline assembly statements can't be longer than 480 bytes.


Macro argument syntax error

See Also

An argument in a macro definition must be an identifier.

The compiler encountered some non-identifier character where an argument was expected.


See Also

Identifier expected


Bad file name format in include directive/line directive
Bad file name format in include directive

OR	Bad file name format in line directive

Include and line directive file names must be surrounded by quotes ("filename.h") or angle brackets (<filename.h>).

The file name was missing the opening quote or angle bracket.

If a macro was used, the resulting expansion text is not surrounded by quote marks.


Invalid indirection

The indirection operator (*) requires a non-void pointer as the operand.

Example

int main (void)

{

  void *p;

  *p = 10;     /* ERROR: Invalid Indirection */

  return 0;

}


Illegal use of pointer

Pointers can only be used with these operators:

addition	(+)

subtraction	(-)

assignment	(=)

comparison	(==)

indirection	(*)

arrow	(->)

Your source file used a pointer with some other operator.

Example

int main (void)

{

  char *p;

  p /= 7;     /* ERROR: Illegal Use of Pointer */

  return 0;

}


Not an allowed type

Your source file declared some sort of forbidden type; for example, a function returning a function or array.


Incompatible type conversion

The cast requested can't be done.


Misplaced decimal point

The compiler encountered a decimal point in a floating-point constant as part of the exponent.


Incorrect use of default

The compiler found no colon after the default keyword.


Invalid use of dot

An identifier must immediately follow a period operator (.).

Example

struct foo {

  int x;

  int y;

}p = 0,0;

int main (void)

{

  p.x++;         /* Correct */

  p.  y++;       /* Error: Invalid use of dot */

  return 0;

}


Function call missing )

The function call argument list had some sort of syntax error, such as a missing or mismatched right parenthesis.


Case statement missing :

A case statement must have a constant expression followed by a colon.

The expression in the case statement either was missing a colon or had an extra symbol before the colon.


Character constant must be one or two characters long

Character constants can only be one or two characters long.


Compound statement missing }

The compiler reached the end of the source file and found no closing brace.

This is most commonly caused by mismatched braces.


Cannot modify a const object

This indicates an illegal operation on an object declared to be const, such as an assignment to the object.


Declaration missing ;

Your source file contained a struct or union field declaration that was not followed by a semicolon.

Check previous lines for a missing semicolon.


Define directive needs an identifier

See Also

The first non-whitespace character after a #define must be an identifier.

The compiler found some other character.


See Also

Identifier expected


Too much global data defined in file

The sum of the global data declarations exceeds 64K bytes. This includes any data stored in the DGROUP (all global variables, literal strings, and static locals).

Solutions

Check the declarations for any array that might be too large. You can also remove variables from the DGROUP.

Here's how:

 	Declare the variables as automatic. This uses stack space.

 	Dynamically allocate memory from the heap using calloc, malloc, or farmalloc for the variables. This requires the use of pointers.

 	Declare variables with the _far16 keyword. This puts variables in their own far data segment. (Limits you to running one instance of your app under Windows.)

Literal strings are also put in the DGROUP. Get the file farstr.zip from our BBS to extract literal strings into their own segment.


Two consecutive dots

Because an ellipsis contains three dots (...), and a decimal point or member selection operator uses one dot (.), two consecutive dots cannot legally occur in a C program.


Too many storage classes in declaration

A declaration can never have more than one storage class, either Auto, Register, Static, or Extern.


Too many types in declaration

A declaration can never have more than one of these basic types:

 	char

 	class

 	int

 	float

 	double

 	struct

 	union

 	enum

 	typedef name


Misplaced elif directive

The compiler encountered an #elif directive without any matching #if, #ifdef, or #ifndef directive.


Misplaced else directive

The compiler encountered an #else directive without any matching #if, #ifdef, or #ifndef directive.


Misplaced endif directive

The compiler encountered an #endif directive without any matching #if, #ifdef, or #ifndef directive.


Enum syntax error

See Also

An enum declaration did not contain a properly formed list of identifiers.


See Also

Identifier expected


Unexpected end of file in comment started on 'line number'

The source file ended in the middle of a comment.

This is normally caused by a missing close of comment (*/).


Unexpected end of file in conditional started on 'line number'

The source file ended before the compiler (or MAKE) encountered #endif.

The #endif either was missing or misspelled.

Every #if statement needs a matching #endif statement.


Expression syntax

This is a catch-all error message when the compiler parses an expression and encounters a serious error.

Possible Causes

This is most commonly caused by one of the following:

 	two consecutive operators

 	mismatched or missing parentheses

 	a missing semicolon on the previous statement.

Solutions

If the line where the error occurred looks syntactically correct, look at the line directly above for errors.

Try moving the line with the error to a different location in the file and recompiling.

If the error still occurs at the moved statement, the syntax error is occurring somewhere in that statement.

If the error occurred in another statement, the syntax error is probably in the surrounding code.


Too few parameters in call

See Also

A call to a function with a prototype (via a function pointer) had too few arguments.

Prototypes require that all parameters be given.

Make certain that your call to a function has the same parameters as the function prototype.


See Also

Identifier expected


Too few parameters in call to 'function'

See Also

A call to the named function (declared using a prototype) had too few arguments.

Make certain that the parameters in the call to the function matches the parameters of the function prototype.


See Also

Identifier expected


Illegal use of floating point

Floating-point operands are not allowed in these operators

 	shift (SHL, SHR)

 	bitwise Boolean (AND, OR, XOR, NOT)

 	conditional (? :)

 	indirection (*)

 	certain others

The compiler found a floating-point operand with one of these prohibited operators.


File name too long

The file name given in an #include directive was too long for the compiler to process.

File names in DOS must be no more than 79 characters long.


Conflicting type modifiers

This occurs when a declaration is given that includes more than one addressing modifier on a pointer or more than one language modifier for a function.

Only one addressing modifier (_ _far16,) can be given for a single pointer.

Only one language modifier (cdecl, and pascal) can be given for a function.

One cannot multiply derive from a class declared to use the fast this pointer optimization, and one that was not. For example:

class __fastthis A { // one way to declare a class as using the

   myex();           // fast this optimization, note that

};                   // #pragma option -po- turns it off.

class B {

   twoex();

};

class c : A , B {}; // error

// note that __fastthis is only recognized in BC 4.0 or later


Goto statement missing label

See Also

The goto keyword must be followed by an identifier.


See Also

Identifier expected


Group overflowed maximum size: 'name'

The total size of the segments in a group (for example, DGROUP) exceeded 64K.


Bad ifdef directive syntax

An #ifdef directive must contain a single identifier (and nothing else) as the body of the directive.


Illegal character 'character' (0x'value')

The compiler encountered some invalid character in the input file.

The hexadecimal value of the offending character is printed.

This can also be caused by extra parameters passed to a function macro.


Illegal initialization

Initializations must be one of the following:

constant expressions

the address of a global extern or static variable plus or minus a constant


Unable to open include file 'filename'

The compiler could not find the named file.

Possible Causes

 	The named file does not exist.

 	An #include file included itself.

 	You do not have FILES set in CONFIG.SYS on your root directory.

Solutions

 	Verify that the named file exists.

 	Set FILES = 20 in CONFIG.SYS.


No file name ending

The file name in an #include statement was missing the correct closing quote or angle bracket.


Lvalue required

The left side of an assignment operator must be an addressable expression.

Addressable expressions include the following:

 	numeric or pointer variables

 	structure field references or indirection through a pointer

 	a subscripted array element


Too many error or warning messages (compiler)
Too many error or warning messages

There were more errors or warnings than set in the Options|Settings|Compiler Messages


statement missing (

In a do, for, if, switch, or while statement, the compiler found no left parenthesis after the while keyword or test expression.


statement missing )

In a do, for, if, switch, or while statement, the compiler found no right parenthesis after the while keyword or test expression.


do-while statement missing ; OR For statement missing ;
do-while statement missing OR For statement missing ;

In a do or for statement, the compiler found no semicolon after the right parenthesis.


Type mismatch in redeclaration of 'identifier'

See Also

Your source file redeclared a variable with a different type than was originally declared for the variable.

Possible Causes

This can occur if a function is called and subsequently declared to return something other than an integer.

Solutions

If this has happened, you must declare the function before the first call to it.


See Also

Identifier expected


Default outside of switch

The compiler encountered a default statement outside a switch statement.

This is most commonly caused by mismatched braces.


Macro expansion too long

A macro can't expand to more than 4,096 characters.


Too many decimal points

The compiler encountered a floating-point constant with more than one decimal point.


Too many exponents

The compiler encountered more than one exponent in a floating-point constant.


Too many initializers

The compiler encountered more initializers than were allowed by the declaration being initialized.


Inline assembly not allowed

Your source file contains inline assembly language statements and you are compiling it from within the integrated environment.

You must use the BCC command to compile this source file from the DOS command line.


Incorrect number format

The compiler encountered a decimal point in a hexadecimal number.


Numeric constant too large

String and character escape sequences larger than hexadecimal or octal 77 can't be generated.

Two-byte character constants can be specified by using a second backslash. For example,

\\

represents a two-byte constant.

A numeric literal following an escape sequence should be broken up like this:

printf("" "12345");

This prints a carriage return followed by 12345.


Illegal octal digit

The compiler found an octal constant containing a non-octal digit (8 or 9).


Type mismatch in parameter 'number' in call to 'function'

Your source file declared the named function with a prototype, and the given parameter number (counting left to right from 1) could not be converted to the declared parameter type.

When compiling C++ programs, this message is always preceded by another message that explains the exact reason for the type mismatch.

That other message is usually "Cannot convert 'type1' to 'type2'", but the mismatch might be due to many other reasons.


Type mismatch in parameter 'parameter' in call to 'function'

Your source file declared the named function with a prototype, and the named parameter could not be converted to the declared parameter type.

When compiling C++ programs, this message is always preceded by another message that explains the exact reason for the type mismatch.

That other message is usually "Cannot convert 'type1' to 'type2'" but the mismatch might be due to many other reasons.


Type mismatch in parameter 'number'

The function called, via a function pointer, was declared with a prototype.

However, the given parameter number (counting left to right from 1) could not be converted to the declared parameter type.

When compiling C++ programs, this message is always preceded by another message that explains the exact reason for the type mismatch.

That other message is usually "Cannot convert 'type1' to 'type2'" but the mismatch might be due to many other reasons.


Type mismatch in parameter 'parameter'

Your source file declared the function called via a function pointer with a prototype.

However, the named parameter could not be converted to the declared parameter type.

When compiling C++ programs, this message is always preceded by another message that explains the exact reason for the type mismatch.

That other message is usually "Cannot convert 'type1' to 'type2'" but the mismatch might be due to many other reasons.


Pointer to structure required on left side of -> or ->*

Nothing but a pointer is allowed on the left side of the arrow (->) in C or C++.

In C++ a -> operator is allowed.


Invalid pointer addition

Your source file attempted to add two pointers together.


Illegal pointer subtraction

This is caused by attempting to subtract a pointer from a non-pointer.


Illegal structure operation

Structures can only be used with dot (.), address-of (&) or assignment (=) operators, or be passed to or from a function as parameters.

The compiler encountered a structure being used with some other operator.


Bad define directive syntax

A macro definition starts or ends with the ## operator, or contains the # operator that is not followed by a macro argument name.


Unterminated string or character constant

The compiler found no terminating quote after the beginning of a string or character constant.


Structure size too large

Your source file declared a structure larger than 64K.


Bad undef directive syntax

An #undef directive must contain a single identifier (and nothing else) as the body of the directive.


Unknown preprocessor directive: 'identifier'

See Also

The compiler encountered a # character at the beginning of a line. The directive name that followed the # was not one of the following:

 	define

 	else

 	endif

 	if

 	ifdef

 	ifndef

 	include

 	line

 	undef


See Also

Identifier expected


Undefined symbol 'identifier'

See Also

The named identifier has no declaration.

Possible Causes

actual declaration of identifier has been commented out.

misspelling, either at this point or at the declaration.

there was an error in the declaration of the identifier.

Tools to help track down the problem:

CPP

GREP


See Also

Identifier expected


Could not find file 'filename'

The compiler is unable to find the file supplied on the command line.


Nonportable pointer conversion (error)
Non-portable pointer conversion

(Command-line for controling display = -wrpt)

An implicit conversion between a pointer and an integral type is required, but the types are not the same size.

This can't be done without an explicit cast.

This conversion might not make any sense, so be sure this is what you want to do.


Extra parameter in call

A call to a function, via a pointer defined with a prototype, had too many arguments.


Extra parameter in call to function

A call to the named function (which was defined with a prototype) had too many arguments given in the call.


User break (compiler)
User break

You typed a Ctrl-Break while compiling in the IDE.

(This is not an error, just a confirmation.)


Multiple base classes require explicit class names

In a C++ class constructor, if there is more than one immediate base class, each base class constructor call in the constructor header must include the base class name.


Member is ambiguous: 'member1' and 'member2'

You must qualify the member reference with the appropriate base class name.

In C++ class 'class', member 'member' can be found in more than one base class, and it was not qualified to indicate which one you meant.

This applies only in multiple inheritance, where the member name in each base class is not hidden by the same member name in a derived class on the same path.

The C++ language rules require that this test for ambiguity be made before checking for access rights (private, protected, public).

It is possible to get this message even though only one (or none) of the members can be accessed.


'function1' cannot be distinguished from 'function2'

The parameter type lists in the declarations of these two functions do not differ enough to tell them apart.

Try changing the order of parameters or the type of a parameter in one declaration.


Attempt to grant or reduce access to 'identifier'

See Also

A C++ derived class can modify the access rights of a base class member, but only by restoring it to the rights in the base class.

It can't add or reduce access rights.


See Also

Identifier expected


Array must have at least one element

ANSI C and C++ require that an array be defined to have at least one element (objects of zero size are not allowed).

An old programming trick declares an array element of a structure to have zero size, then allocates the space actually needed with malloc.

You can still use this trick, but you must declare the array element to have (at least) one element if you are compiling in strict ANSI mode.

Declarations (as opposed to definitions) of arrays of unknown size are still allowed.

Example

char ray[];         /* definition of unknown size -- ILLEGAL */

char ray[0];        /* definition of 0 size -- ILLEGAL */

extern char ray[];  /* declaration of unknown size -- OK */


operator -> must return a pointer or a class

The C++ operator -> function must be declared to either return a class or a pointer to a class (or struct or union).

In either case, it must be something to which the -> operator can be applied.


'identifier' must be a previously defined class or struct

See Also

You are attempting to declare 'identifier' to be a base class, but either it is not a class or it has not yet been fully defined.

Correct the name or rearrange the declarations.


See Also

Identifier expected


Misplaced break

The compiler encountered a break statement outside a switch or looping construct.

You can only use break statements inside of switch statements or loops.


Switch selection expression must be of integral type

The selection expression in parentheses in a switch statement must evaluate to an integral type (char, short, int, long, enum).

You might be able to use an explicit cast to satisfy this requirement.


Cannot cast from 'type1' to 'type2'

A cast from type 'ident1' to type 'ident2' is not allowed.

In C++, you cannot cast a member function pointer to a normal function pointer.

For example:

class A {

public:

   int myex();

};

typedef int (*fp)();

test()

{

   fp myfp - (fp) &A::myex; //error

The reason being that a class member function takes a hidden parameter, the this pointer, thus it behaves very differently than a normal function pointer.

A static member function behaves as normal function pointer and can be cast.

For example:

class A {

public:

   static int myex();

};

typedef int (*fp)();

test()

{

   fp myfp - (fp) &A::myex; //ok

However, static member functions can only access static data members of the class.

In C

 	A pointer can be cast to an integral type or to another pointer.

 	An integral type can be cast to any integral, floating, or pointer type.

 	A floating type can be cast to an integral or floating type.

Structures and arrays can't be cast to or from.

You usually can't cast from a void type.

In C++

User-defined conversions and constructors are checked for. If one can't be found, the preceding rules apply (except for pointers to class members).

Among integral types, only a constant zero can be cast to a member pointer.

A member pointer can be cast to an integral type or to a similar member pointer.

A similar member pointer points to a data member (or to a function) if the original does. The qualifying class of the type being cast to must be the same as (or a base class of) the original.


Constructor cannot have a return type specification

C++ constructors have an implicit return type used by the compiler, but you can't declare a return type or return a value.


Misplaced continue

The compiler encountered a continue statement outside a looping construct.


Declaration terminated incorrectly

A declaration has an extra or incorrect termination symbol, such as a semicolon placed after a function body.

A C++ member function declared in a class with a semicolon between the header and the opening left brace also generates this error.


Need an identifier to declare

See Also

In this context, an identifier was expected to complete the declaration.

This might be a typedef with no name, or an extra semicolon at file level.

In C++, it might be a class name improperly used as another kind of identifier.


See Also

Identifier expected


Default value missing

When a C++ function declares a parameter with a default value, all of the following parameters must also have default values.

In this declaration, a parameter with a default value was followed by a parameter without a default value.


Declare operator delete (void*) or (void*, size_t)
Declare operator delete[] (void*) or (void*, size_t)

Declare the operator delete with one of the following:

1.	a single void* parameter, or

2.	a second parameter of type size_t

If you use the second version, it will be used in preference to the first version.

The global operator delete can only be declared using the single-parameter form.


operator delete must return void
operator delete[] must return void

This C++ overloaded operator delete was declared in some other way.

Declare the operator delete with one of the following:

1.	a single void* parameter, or

2.	a second parameter of type size_t

If you use the second version, it will be used in preference to the first version.

The global operator delete can only be declared using the single-parameter form.


Destructor name must match the class name

In a C++ class, the tilde (~) introduces a declaration for the class destructor.

The name of the destructor must be same as the class name.

In your source file, the ~ preceded some other name.


Destructor cannot have a return type specification

C++ destructors never return a value, and you can't declare a return type or return a value.


Default value missing following parameter 'parameter'

See Also

All parameters following the first parameter with a default value must also have defaults specified.


See Also

Identifier expected


Misplaced else

The compiler encountered an else statement without a matching if statement.

Possible Causes

 	An extra "else" statement

 	An extra semicolon

 	Missing braces

 	Some syntax error in a previous "if" statement


Unknown language, must be C or C++

In the C++ construction

extern "name" type func( /*...*/ );

the given "name" must be "C" or "C++" (use the quotes); other language names are not recognized.

You can declare an external Pascal function without the compiler's renaming like this:

extern "C" int pascal func( /*...*/ );

To declare a (possibly overloaded) C++ function as Pascal and allow the usual compiler renaming (to allow overloading), you can do this:

extern int pascal func( /*...*/ );


'function' was previously declared with the language 'language'

Only one language modifier (cdecl pascal) can be given for a function.

This function has been declared with different language modifiers in two locations.


Parameter names are used only with a function body

When declaring a function (not defining it with a function body), you must use either empty parentheses or a function prototype.

A list of parameter names only is not allowed.

Example declarations

int func();             /* declaration without prototype -- OK */

int func(int, int);     /* declaration with prototype -- OK */

int func(int i, int j); /* parameter names in prototype -- OK */

int func(i, j);         /* parameter names only -- ILLEGAL */


extern variable cannot be initialized

The storage class extern applied to a variable means that the variable is being declared but not defined here--no storage is being allocated for it.

Therefore, you can't initialize the variable as part of the declaration.


Cannot initialize 'type1' with 'type2'

You are attempting to initialize an object of type 'type1' with a value of type 'type2' which is not allowed.

The rules for initialization are essentially the same as for assignment.


Objects of type 'type' cannot be initialized with {}

Ordinary C structures can be initialized with a set of values inside braces.

C++ classes can only be initialized with constructors if the class has constructors, private members, functions, or base classes that are virtual.


operator new must return an object of type void *
Operator new[] must return an object of type void *

This C++ overloaded operator new was declared in some other way.


'function' must be declared with no parameters

See Also

This C++ operator function was incorrectly declared with parameters.


See Also

Identifier expected


'function' must be declared with one parameter

See Also

This C++ operator function was incorrectly declared with more than one parameter.


See Also

Identifier expected


'function' must be declared with two parameters

See Also

This C++ operator function was incorrectly declared with other than two parameters.


See Also

Identifier expected


'identifier' must be a member function or have a parameter of class type

See Also

Most C++ operator functions must have an implicit or explicit parameter of class type.

This operator function was declared outside a class and does not have an explicit parameter of class type.


See Also

Identifier expected


Only one of a set of overloaded functions can be "C"

C++ functions are by default overloaded, and the compiler assigns a new name to each function.

If you wish to override the compiler's assigning a new name by declaring the function extern "C", you can do this for only one of a set of functions with the same name.

(Otherwise the linker would find more than one global function with the same name.)


'identifier' is not a parameter

See Also

In the parameter declaration section of an old-style function definition, 'identifier' is declared but is not listed as a parameter.

Either remove the declaration or add 'identifier' as a parameter.


See Also

Identifier expected


Type qualifier 'identifier' must be a struct or class name

See Also

The C++ qualifier in the construction qual::identifier is not the name of a struct or class.


See Also

Identifier expected


Two operands must evaluate to the same type

The types of the expressions on both sides of the colon in the conditional expression operator (?:) must be the same, except for the usual conversions.

These are some examples of usual conversions

 	char to int

 	float to double

 	void* to a particular pointer

In this expression, the two sides evaluate to different types that are not automatically converted.

This might be an error or you might merely need to cast one side to the type of the other.

When compiling C++ programs, this message is always preceded by another message that explains the exact reason for the type mismatch.

That other message is usually "Cannot convert 'type1' to 'type2'" but the mismatch might be due to many other reasons.


'this' can only be used within a member function

In C++, "this" is a reserved word that can be used only within class member functions.


Virtual function 'function1' conflicts with base class 'base'

A virtual function has the same argument types as one in a base class, but a different return type.

This is illegal.


Bit field too large

This error occurs when you supply a bit field with more than 16 bits.


Bit fields must contain at least one bit

You can't declare a named bit field to have 0 (or less than 0) bits.

You can declare an unnamed bit field to have 0 bits.

This is a convention used to force alignment of the following bit field to a byte boundary (or to a word boundary, if you choose the or turn on the Word Alignment option in the Code Generation dialog box.


Overloadable operator expected

Almost all C++ operators can be overloaded.

These are the only ones that can't be overloaded:

 	the field-selection dot (.)

 	dot-star (.*)

 	double colon (::)

 	conditional expression (?:)

The preprocessor operators (# and ##) are not C or C++ language operators and thus can't be overloaded.

Other non-operator punctuation, such as semicolon (;), can't be overloaded.


Default argument value redeclared

When a parameter of a C++ function is declared to have a default value, this value can't be changed, redeclared, or omitted in any other declaration for the same function.


Default argument value redeclared for parameter 'paraemter'
Default argument value redeclared for parameter 'parameter'

When a parameter of a C++ function is declared to have a default value, this value can't be changed, redeclared, or omitted in any other declaration for the same function.


Declaration is not allowed here

Declarations can't be used as the control statement for while, for, do, if, or switch statements.


Array allocated using 'new' may not have an initializer

When initializing a vector (array) of classes, you must use the constructor that has no arguments.

This is called the default constructor, which means that you can't supply constructor arguments when initializing such a vector.


Trying to derive a far class from the near base 'base'

If a class is declared (or defaults to) near, all derived classes must also be near.


Trying to derive a near class from the far base 'base'

If a class is declared (or defaults to) far, all derived classes must also be far.


Destructor for class is not accessible

The destructor for this C++ class is protected or private, and can't be accessed here to destroy the class.

If a class destructor is private, the class can't be destroyed, and thus can never be used. This is probably an error.

A protected destructor can be accessed only from derived classes.

This is a useful way to ensure that no instance of a base class is ever created, but only classes derived from it.


Division by zero (error)
Division by zero

Your source file contained a divide or remainder in a constant expression with a zero divisor.


Too many default cases

The compiler encountered more than one default statement in a single switch.


'identifier' specifies multiple or duplicate access

See Also

A base class can be declared public or private, but not both.

This access specifier can appear no more than once for a base class.


See Also

Identifier expected


Base class 'class' is included more than once

A C++ class can be derived from any number of base classes, but can be directly derived from a given class only once.


Duplicate case

Each case of a switch statement must have a unique constant expression value.


Member 'member' is initialized more than once

In a C++ class constructor, the list of initializations following the constructor header includes the same member name more than once.


Multiple declaration for 'identifier'

See Also

This identifier was improperly declared more than once.

This might be caused by conflicting declarations such as:

 	int a; double a;

 	a function declared two different ways, or

 	a label repeated in the same function, or

 	some declaration repeated other than an extern function or a simple variable

This can also happen by inadvertently including the same header file twice. For example, given:

//a.h

struct A { int a; };

//b.h

#include "a.h"

//myprog.cpp

#include "a.h"

#include "b.h"

myprog.cpp will get two declarations for the struct A. To protect against this, one would write the a.h header file as:

//a.h

#ifndef __A_H

#define __A_H

struct A { int a; };

#endif

This will allow one to safely include a.h several times in the same source code file.


See Also

Identifier expected


Base class 'class' is initialized more than once

In a C++ class constructor, the list of initializations following the constructor header includes base class 'class' more than once.


'specifier' has already been included

This type specifier occurs more than once in this declaration.

Delete or change one of the occurrences.


Body has already been defined for function 'function'

A function with this name and type was previously supplied a function body.

A function body can only be supplied once.

One cause of this error is not declaring a default constructor which you implement. For example:

class A {

public:

   virtual myex();

};

A::A() {} // error

Having not seen you declare the default constructor in the class declaration, the compiler has had to generate one, thus giving the error message when it sees one. this is a correct example:

class A {

public:

   A();

   virtual myex();

};

A::A() {}


virtual specified more than once

The C++ reserved word "virtual" can appear only once in one member function declaration.


File must contain at least one external declaration

This compilation unit was logically empty, containing no external declarations.

ANSI C and C++ require that something be declared in the compilation unit.


'member' is not accessible

You are trying to reference C++ class member 'member,' but it is private or protected and can't be referenced from this function.

This sometimes happens when you attempt to call one accessible overloaded member function (or constructor), but the arguments match an inaccessible function.

The check for overload resolution is always made before checking for accessibility.

If this is the problem, try an explicit cast of one or more parameters to select the desired accessible function.

Virtual base class constructors must be accessible within the scope of the most derived class. This is because C++ always constructs virtual base classes first, no matter how far down the hierarchy they are. For example:

class A {

public:

   A();

};

class B : private virtual A {};

class C : private B {

public:

C();

};

C::C() {} // error, A::A() is not accessible

Since A is private to B, which is private to C, it makes A's constructor not accessible to C. However, the constructor for C must be able to call the constructors for its virtual base class, A. If B inherits A publicly, the above example would compile.


Function defined inline after use as extern

Functions can't become inline after they have already been used.

Either move the inline definition forward in the file or delete it entirely.

The compiler encountered something like:

myex();

twoex() { myex(); }

inline myex() { return 2; } // error

and already used the function as an extern before it saw that it was specified as inline. This would be correct:

myex();

inline myex() { return 2; }

twoex() { myex(); }

or better:

inline myex();

inline myex() { return 2; }

twoex() { myex(); }


Undefined label 'identifier'

See Also

The named label has a goto in the function, but no label definition.


See Also

Identifier expected


Unexpected
Unexpected }

An extra right brace was encountered where none was expected. Check for a missing {.

Useful Tip:

The IDE has a mechanism for finding a matching curly brace. If you put the cursor on the '{' or '}' character, hold down control, hit 'Q' and then '{' or '}', it will position the cursor on the matching brace.


Ambiguity between 'function1' and 'function2'

Both of the named overloaded functions could be used with the supplied parameters.

This ambiguity is not allowed.


Class member 'member' declared outside its class

C++ class member functions can be declared only inside the class declaration.

Unlike nonmember functions, they can't be declared multiple times or at other locations.


'constructor' is not an unambiguous base class of 'class'

A C++ class constructor is trying to call a base class constructor 'constructor.'

This error can also occur if you try to change the access rights of 'class::constructor.'

Check your declarations.


'identifier' must be a member function

See Also

Most C++ operator functions can be members of classes or ordinary non-member functions, but these are required to be members of classes:

 	operator =

 	operator ->

 	operator ( )

 	type conversions

This operator function is not a member function but should be.


See Also

Identifier expected


Parameter 'number' missing name

In a function definition header, this parameter consisted only of a type specifier 'number' with no parameter name.

This is not legal in C.

(It is allowed in C++, but there's no way to refer to the parameter in the function.)


No base class to initialize

This C++ class constructor is trying to implicitly call a base class constructor, but this class was declared with no base classes.

Check your declarations.


Illegal to take address of bit field

It is not legal to take the address of a bit field, although you can take the address of other kinds of fields.


Cannot initialize a class member here

Individual members of structs, unions, and C++ classes can't have initializers.

A struct or union can be initialized as a whole using initializers inside braces.

A C++ class can only be initialized by the use of a constructor.


: expected after private/protected/public
: expected after private/protected/private

When used to begin a private, protected, or public section of a C++ class, the reserved words "private," "protected," and "public" must be followed by a colon.


No : following the ?

The question mark (?) and colon (:) operators do not match in this expression.

The colon might have been omitted, or parentheses might be improperly nested or missing.


, expected

See Also

A comma was expected in a list of declarations, initializations, or parameters.

This problem is often caused by a missing syntax element earlier in the file or one of its included headers.


See Also

Identifier expected


Cannot find class::class/operator (class &) to copy a vector
Cannot find 'class::class' ('class'&) to copy a vector

OR	Cannot find 'class'::operator=('class'&) to copy a vector

Cannot find class::class ...

When a C++ class 'class1' contains a vector (array) of class 'class2', and you want to construct an object of type 'class1' from another object of type 'class 1', you must use this constructor:

class2::class2(class2&)

so that the elements of the vector can be constructed.

The constructor, called a copy constructor, takes just one parameter (which is a reference to its class).

Usually, the compiler supplies a copy constructor automatically.

However, if you have defined a constructor for class 'class2' that has a parameter of type 'class2&' and has additional parameters with default values, the copy constructor can't exist and can't be created by the compiler.

This is because these two can't be distinguished:

class2::class2(class2&)

class2::class2(class2&, int = 1)

You must redefine this constructor so that not all parameters have default values.

You can then define a reference constructor or let the compiler create one.

Cannot find class::operator= ...

When a C++ class 'class1' contains a vector (array) of class 'class2', and you want to copy a class of type 'class1', you must use this assignment operator:

class2::class2(class2&)

so that the elements of the vector can be copied.

Usually, the compiler automatically supplies this operator.

However, if you have defined an operator= for class 'class2' that does not take a parameter of type 'class2&,' the compiler will not supply it automatically--you must supply one.


Declaration was expected

A declaration was expected here but not found.

This is usually caused by a missing delimiter such as a comma, semicolon, right parenthesis, or right brace.


'identifier' must be a previously defined enumeration tag

See Also

This declaration is attempting to reference 'ident' as the tag of an enum type, but it has not been so declared.

Correct the name, or rearrange the declarations.


See Also

Identifier expected


Expression expected

An expression was expected here, but the current symbol can't begin an expression.

This message might occur where the controlling expression of an if or while clause is expected or where a variable is being initialized.

This message is often due to a symbol that is missing or has been added.


Member identifier expected

See Also

The name of a structure or C++ class member was expected here, but not found.

The right side of a dot (.) or arrow (->) operator must be the name of a member in the structure or class on the left of the operator.


See Also

Identifier expected


'identifier' is not a member of struct
'identifier' is not a member of 'struct'

See Also

You are trying to reference 'identifier' as a member of 'struct', but it is not a member.

Check your declarations.


See Also

Identifier expected


Friends must be functions or classes

A friend of a C++ class must be a function or another class.


Functions may not be part of a struct or union

This C struct or union field was declared to be of type function rather than pointer to function.

Functions as fields are allowed only in C++.


Identifier expected

An identifier was expected here, but not found.

In C, an identifier is expected in the following situations:

 	in a list of parameters in an old-style function header

 	after the reserved words struct or union when the braces are not present, and

 	as the name of a member in a structure or union (except for bit fields of width 0).

In C++, an identifier is also expected in these situations:

 	in a list of base classes from which another class is derived, following a double colon (::), and

 	after the reserved word "operator" when no operator symbol is present.


Constant/Reference variable 'variable' must be initialized

This C++ object is declared constant or as a reference, but is not initialized.

It must be initialized at the point of declaration.


Inline assembly not allowed in inline and template functions

The compiler can't handle inline assembly statements in a C++ inline or template function.

You could eliminate the inline assembly code or, in the case of an inline function, make this a macro, and remove the inline storage class.


{ expected

A left brace was expected at the start of a block or initialization.


Attempting to return a reference to local variable 'identifier'

See Also

This C++ function returns a reference type, and you are trying to return a reference to a local (auto) variable.

This is illegal, because the variable referred to disappears when the function exits.

You can return a reference to any static or global variable, or you can change the function to return a value instead.


See Also

Identifier expected


( expected

A left parenthesis was expected before a parameter list.


Reference member 'member' is not initialized

References must always be initialized, in the constructor for the class.

A class member of reference type must have an initializer provided in all constructors for that class.

This means you can't depend on the compiler to generate constructors for such a class, because it has no way of knowing how to initialize the references.


Could not find a match for argument(s)

No C++ function could be found with parameters matching the supplied arguments. Check parameters passed to function or overload function for parameters that are being passed.


Use :: to take the address of a member function

If f is a member function of class c, you take its address with the syntax

&c::f

Note the use of the class type name (not the name of an object) and the :: separating the class name from the function name.

(Member function pointers are not true pointer types, and do not refer to any particular instance of a class.)


Cannot find default constructor to initialize base class 'class'

Whenever a C++ derived class 'class2' is constructed, each base class 'class1' must first be constructed.

If the constructor for 'class2' does not specify a constructor for 'class1' (as part of 'class2's' header), there must be a constructor class1::class1() for the base class.

This constructor without parameters is called the default constructor.

The compiler will supply a default constructor automatically unless you have defined any constructor for class 'class1'.

In that case, the compiler will not supply the default constructor automatically--you must supply one.

class Base {

public:

   Base(int) {}

};

class Derived = public Base {

   Derived():Base(1) {}

}

// must explicitly call the Base constructor, or provide a

// default constructor in Base.

Class members with constructors must be initialized in the class' initializer list, for example:

class A {

public

   A( int );

};

class B {

public:

   A a;

   B() : a( 3 ) {}; //ok

};


Cannot find default constructor to initialize member 'identifier'

See Also

When the following occurs

1.	a C++ class 'class1' contains a member of class 'class2,'

and

2.	you want to construct an object of type 'class1' (but not from another object of type 'class1')

there must be a constructor class2::class2() so that the member can be constructed.

This constructor without parameters is called the default constructor.

The compiler will supply a default constructor automatically unless you have defined any constructor for class 'class2'.

In that case, the compiler will not supply the default constructor automatically--you must supply one.


See Also

Identifier expected


Use . or -> to call function

You attempted to call a member function without providing an object. *this is required to call a member function.

class X {

   member func() {}

};

X x;

X*xp = new X;

X.memberfunc();

Xp-> memberfunc();


missing ]

This error is generated if any of the following occur:

 	Your source file declared an array in which the array bounds were not terminated by a right bracket.

 	The array specifier in an operator is missing a right bracket.

 	The operator [ ] was declared as operator [.

 	A right bracket is missing from a subscripting expression.

Add the bracket or fix the declaration.

Check for a missing or extra operator or mismatched parentheses.


} expected

A right brace was expected at the end of a block or initialization.


Must take address of a memory location

Your source file used the address-of operator (&) with an expression that can't be used that way; for example, a register variable.


) expected

A right parenthesis was expected at the end of a parameter list.


Statement missing ;

The compiler encountered an expression statement without a semicolon following it.


Bit field cannot be static

Only ordinary C++ class data members can be declared static, not bit fields.


Global anonymous union not static

In C++, a global anonymous union at the file level must be static.


Structure required on left side of . or .*

The left side of a dot (.) operator (or C++ dot-star operator, .*) must evaluate to a structure type. In this case it did not.

This error can occur when you create an instance of a class using empty parentheses, and then try to access a member of that 'object'.


Constant expression required

Arrays must be declared with constant size.

This error is commonly caused by misspelling a #define constant.


Call of nonfunction

The name being called is not declared as a function.

This is commonly caused by incorrectly declaring the function or misspelling the function name.


Case outside of switch

The compiler encountered a case statement outside a switch statement.

This is often caused by mismatched braces.


Member pointer required on right side of .* or ->*

The right side of a C++ dot-star (.*) or an arrow star (->*) operator must be declared as a pointer to a member of the class specified by the left side of the operator.

In this case, the right side is not a member pointer.


Type name expected

One of these errors has occurred:

 	In declaring a file-level variable or a struct field, neither a type name nor a storage class was given.

 	In declaring a typedef, no type for the name was supplied.

 	In declaring a destructor for a C++ class, the destructor name was not a type name (it must  be the same name as its class).

 	In supplying a C++ base class name, the name was not the name of a class.


union cannot have a base type

In general, a C++ class can be of union type, but such a class can't be derived from any other class.


Value of type void is not allowed

A value of type void is really not a value at all, so it can't appear in any context where an actual value is required.

Such contexts include the following:

 	the right side of an assignment

 	an argument of a function

 	the controlling expression of an if, for, or while statement.


do statement must have while

Your source file contained a do statement that was missing the closing while keyword.


Identifier 'identifier' cannot have a type qualifier

See Also

A C++ qualifier class::identifier can't be applied here.

A qualifier is not allowed on the following:

 	typedef names

 	function declarations (except definitions at the file level)

 	on local variables or parameters of functions

 	on a class member--except to use its own class as a qualifier (redundant but legal).


See Also

Identifier expected


sizeof may not be applied to a bit field

sizeof returns the size of a data object in bytes, which does not apply to a bit field.


sizeof may not be applied to a function

sizeof can be applied only to data objects, not functions.

You can request the size of a pointer to a function.


Storage class 'storage class' is not allowed here

The given storage class is not allowed here.

Probably two storage classes were specified, and only one can be given.


Access can only be changed to public or protected

A C++ derived class can modify the access rights of a base class member, but only to public or protected.

A base class member can't be made private.


Variable 'identifier' is initialized more than once

See Also

This variable has more than one initialization.

It is legal to declare a file level variable more than once, but it can have only one initialization (even if two are the same).


See Also

Identifier expected


Improper use of typedef 'identifier'

See Also

Your source file used a typedef symbol where a variable should appear in an expression.

Check for the declaration of the symbol and possible misspellings.


See Also

Identifier expected


Size of 'identifier' is unknown or zero

See Also

This identifier was used in a context where its size was needed.

A struct tag might only be declared (the struct not defined yet), or an extern array might be declared without a size.

It's illegal then to have some references to such an item (like sizeof) or to dereference a pointer to this type.

Rearrange your declaration so that the size of 'identifier' is available.


See Also

Identifier expected


Size of the type is unknown or zero

This type was used in a context where its size was needed.

For example, a struct tag might only be declared (the struct not defined yet).

It's illegal then to have some references to such an item (like sizeof) or to dereference a pointer to this type.

Rearrange your declarations so that the size of this type is available.


Conversion operator cannot have a return type specification

This C++ type conversion member function specifies a return type different from the type itself.

A declaration for conversion function operator can't specify any return type.


Linkage specification not allowed

Linkage specifications such as extern "C" are only allowed at the file level.

Move this function declaration out to the file level.


Reference member 'member' needs a temporary for initialization

You provided an initial value for a reference type that was not an lvalue of the referenced type.

This requires the compiler to create a temporary for the initialization.

Because there is no obvious place to store this temporary, the initialization is illegal.


'identifier' cannot be declared in an anonymous union

See Also

The compiler found a declaration for a member function or static member in an anonymous union.

Such unions can only contain data members.


See Also

Identifier expected


Function 'function' cannot be static

Only ordinary member functions and the operators new and delete can be declared static.

Constructors, destructors and other operators must not be static.


Cannot overload 'main'

main is the only function that can't be overloaded.


Non-virtual function 'function' declared pure

Only virtual functions can be declared pure, because derived classes must be able to override them.


Bad syntax for pure function definition

Pure virtual functions are specified by appending "= 0" to the declaration, like this:

class A { virtual void f () = 0;}

class B : public A { void f () {}; }

You wrote something similar, but not quite the same.


Cannot create instance of abstract class 'class'

Abstract classes (those with pure virtual functions) can't be used directly, only derived from.

When you derive an abstract base class, with the intention to instantiate instances of this derived class, you must override each of the pure virtual functions of the base class exactly as they are declared.

For example:

class A {

public:

   virtual myex( int ) = 0;

   virtual twoex( const int ) const = 0;

};

class B : public A {

public:

   myex( int );

   twoex( const int );

};

B b;   // error

The error occurs because we have not overriden the virtual function which twoex can act on const objects of the class. We have created a new one which acts on non-const objects. This would compile:

class A {

public:

   virtual myex( int ) = 0;

   virtual twoex( const int ) const = 0;

};

class B : public A {

public:

   myex( int );

   twoex( const int ) const;

};

B b;   // ok


Cannot define a pointer or reference to a reference

It is illegal to have a pointer to a reference or a reference to a reference.


Array of references is not allowed

It is illegal to have an array of references, because pointers to references are not allowed and array names are coerced into pointers.


void & is not a valid type

A reference always refers to an object, but an object cannot have the type void.

Thus, the type void is not allowed.


'identifier' is not a non-static member and can't be initialized here

See Also

Only data members can be initialized in the initializers of a constructor.

This message means that the list includes a static member or function member.

Static members must be initialized outside of the class, for example:

class A { static int i; };

int A::i = -1;


See Also

Identifier expected


Destructor for 'class' required in conditional expression

If the compiler must create a temporary local variable in a conditional expression, it has no good place to call the destructor because the variable might or might not have been initialized.

The temporary can be explicitly created, as with classname(val, val), or implicitly created by some other code.

You should recast your code to eliminate this temporary value.


The value for 'identifier' is not within the range of an int

See Also

All enumerators must have values that can be represented as an integer.

You have attempted to assign a value that is out of the range of an integer.

If you need a constant of this value, use a const integer.


See Also

Identifier expected


Member 'member' cannot be used without an object

This means that you have written class::member where 'member' is an ordinary (non-static) member, and there is no class to associate with that member.

For example, it is legal to write this:

obj.class::member

but not to write this:

class::member


Function should return a value (error)
Function should return a value

(Command-line equivalent for controling display of this warning = -wrvl)

Your source file declared the current function to return some type other than int or void, but the compiler encountered a return with no value.

This is usually some sort of error.

int functions are exempt, because in old versions of C there was no void type to indicate functions that return nothing.

Default = displayed


Undefined structure 'structure' (error)
Undefined structure 'structure'

(Command-line equivalent for controling display of this warning = -wstu)

The named structure was used in the source file, probably on a pointer to a structure, but had no definition in the source file.

This is probably caused by a misspelled structure name or a missing declaration.

Default = displayed


'base' is an indirect virtual base class of 'class'

You can't create a pointer to a C++ member of a virtual base class.

You have attempted to create such a pointer (either directly, or through a cast) and access an inaccessible member of one of your base classes.


'identifier' is not a public base class of 'classtype'

See Also

The right operand of a .*, ->*, or ::operator was not a pointer to a member of a class that is either identical to (or an unambiguous accessible base class of) the left operand's class type.


See Also

Identifier expected


'operator' must be declared with one or no parameters

See Also

When operator ++ or operator -- is declared as a member function, it must be declared to take either:

 	no parameters (for the prefix version of the operator), or

 	one parameter of type int (for the postfix version).


See Also

Identifier expected


'operator' must be declared with one or two parameters

See Also

When operator ++ or operator -- is declared as a non-member function, it must be declared to take either:

 	one parameter (for the prefix version of the operator), or

 	two parameters (for the postfix version)


See Also

Identifier expected


'virtual' can only be used with member functions

A data member has been declared with the virtual specifier.

Only member functions can be declared virtual.

For example:

class myclass

{

public:

   virtual int a;    //error

};


Address of overloaded function 'function' doesn't match 'type'

A variable or parameter is assigned (or initialized with) the address of an overloaded function.

However, the type of the variable or parameter doesn't match any of the overloaded functions with the specified name.


Ambiguous member name 'name'

Whenever a structure member name is used in inline assembly, such a name must be unique.

(If it is defined in more than one structure, all of the definitions must agree as to its type and offset within the structures).

In this case, an ambiguous member name has been used.

For example:

struct A

{

   int a;

   int b;

};

...

asm ax,.a;


Assignment to 'this' not allowed, use X::operator new instead

In early versions of C++, the only way to control allocation of class of objects was by assigning to the 'this' parameter inside a constructor.

This practice is no longer allowed, because a better, safer, and more general technique is to define a member function operator new instead.

For example:

this = malloc(n);


Cannot allocate a reference

You have attempted to create a reference using the new operator.

This is illegal, because references are not objects and can't be created through new.


Cannot call near class member function with a pointer of type 'type'

Member functions of near classes can't be called via a _ _far16 or member pointer.

This also applies to calls using pointers to members.

(Remember, classes are near by default in the tiny, small, and medium memory models.)

Either change the pointer to be near, or declare the class as far.


Cannot convert 'type1' to 'type2'

An assignment, initialization, or expression requires the specified type conversion to be performed, but the conversion is not legal.

In C++, the compiler will convert one function pointer to another only if the signature for the functions are the same. Signature refers to the arguments and return type of the function. For example:

myex( int );

typedef int ( *ffp )( float );

test()

{

   ffp fp = myex; //error

}

Seeing that myex takes an int for its argument, and fp is a pointer to a function which takes a float as argument, the compiler will not convert it for you.

In cases where this is what is intended, performing a typecast is necessary:

myex( int );

typedef int ( *ffp )( float );

test()

{

   ffp fp = (ffp)myex;  //ok

}


Class 'class' may not contain pure functions

The class being declared cannot be abstract, and therefore it cannot contain any pure functions.


Compiler could not generate 'member function' for class 'class'
Compiler could not generate copy constructor for class 'class'

OR	Compiler could not generate default constructor for class 'class'

OR	Compiler could not generate operator = for class 'class'

Sometimes the compiler is required to generate a member function for the user.

Whenever such a member function can't be generated due to applicable language rules, the compiler issues one of these error messages.


Constant/Reference member 'member' in class without constructors

A class that contains constant or reference members (or both) must have at least one user-defined constructor.

Otherwise, there would be no way to ever initialize such members.


Constructor/Destructor cannot be declared 'const' or 'volatile'

A constructor or destructor has been declared as const or volatile.

This is not allowed.


Default expression may not use local variables

A default argument expression is not allowed to use any local variables or other parameters.


Illegal use of member pointer

Pointers to class members can only be passed as arguments to functions, or used with the following operators:

 	assignment

 	comparison

 	.*

 	->*

 	?:

 	&&

 	||

The compiler has encountered a member pointer being used with a different operator.

In order to call a member function pointer, one must supply an instance of the class for it to call upon.

For example:

class A {

public:

   myex();

};

typedef int (A::*Amfptr)();

myex()

{

   Amfptr mmyex = &A::myex;

   (*mmyex)():  //error

}

This will compile:

class A {

public:

   myex();

};

typedef int (A::*Amfptr)();

foo()

{

   A a;

   Amfptr mmyex - &A::myex;

   (a.*mmyex)90;

}


Implicit conversion of 'type1' to 'type2' not allowed

When a member function of a class is called using a pointer to a derived class, the pointer value must be implicitly converted to point to the appropriate base class.

In this case, such an implicit conversion is illegal.


Last parameter of 'operator' must have type 'int'

When a postfix operator ++ or operator -- is overloaded, the last parameter must be declared with the type int.


Member function must be called or its address taken

A reference to a member function must be called, or its address must be taken with & operator.

In this case, a member function has been used in an illegal context.

For example:

class A

{

   void (A::* infptr)(void);

public;

   A();

   void myex(void);

};

A::A()

{

   infptr = myex;   //illegal - call myex or take address?

   infptr = A::& myex;   //correct

}


Reference initialized with 'type1', needs lvalue of type 'type2'

A reference variable that is not declared constant must be initialized with an lvalue of the appropriate type.

In this case, the initializer either wasn't an lvalue, or its type didn't match the reference being initialized.


Only member functions may be 'const' or 'volatile'

Something other than a class member function has been declared const or volatile.


Operand of 'delete' must be non-const pointer

It is illegal to delete a variable that is not a pointer.

It is also illegal to delete a pointer to a constant.

For example:

const int x=10;

   const int * a = &x;

   int * const b = new int;

   int &c = *b;

   delete a;   //illegal - deleting pointer to constant

   delete b;   //legal

   delete c;   //illegal - operand not of pointer type

               //should use 'delete&c' instead


Operator must be declared as function

An overloaded operator was declared with something other than function type.

For example:

class A

{

   A& operator +;   ..note missing parenthesis

};

In the example, the function operator '()' is missing, so the operator does not have function type and generates this error.


Operators may not have default argument values

It is illegal for overloaded operators to have default argument values.


Overloaded 'function name' ambiguous in this context

The only time an overloaded function name can be used or assigned without actually calling the function is when a variable or parameter of the correct function pointer type is initialized or assigned the address of the overload function.

In this case, an overloaded function name has been used in some other context, for example, the following code will generate this error:

class A{

   A(){myex;}           //calling the function

   void myex(int) {}    //or taking its address?

   void myex(float){}

};


Type mismatch in default argument value

The default parameter value given could not be converted to the type of the parameter.

The message "Type mismatch in default argument value" is used when the parameter was not given a name.

When compiling C++ programs, this message is always preceded by another message that explains the exact reason for the type mismatch.

That other message is most often "Cannot convert 'type1' to 'type2'" but the mismatch could be due to another reason.


Type mismatch in default value for parameter 'parameter'

The default parameter value given could not be converted to the type of the parameter.

The message "Type mismatch in default argument value" is used when the parameter was not given a name.

When compiling C++ programs, this message is always preceded by another message that explains the exact reason for the type mismatch.

That other message is usually "Cannot convert 'type1' to 'type2'" but the mismatch might be due to many other reasons.


union cannot be a base type

A union can't be used as a base type for another class type.


unions cannot have virtual member functions

A union can't have virtual functions as its members.


Union member 'member' is of type class with constructor/destructor/operator =
Union member 'member' is of type class with constructor (or destructor, or operator =)

A union can't contain members that are of type class with user-defined constructors, destructors, or operator =.


Use . or -> to call 'member', or & to take its address

A reference to a non-static class member without an object was encountered.

Such a member can't be used without an object, or its address must be taken with the & operator.


'function' cannot return a value
Void 'function' cannot return a value

(Command-line equivalent for controling display of this warning =

A function with a return type void contains a return statement that returns a value; for example, an int.

Default = displayed


'identifier' cannot start a parameter declaration

See Also

An undefined 'identifier' was found at the start of an argument in a function declarator.

Often the type name is misspelled or the type declaration is missing. This is usually caused by not including the appropriate header file.


See Also

Identifier expected


< expected

The keyword template was not followed by <.

Every template declaration must include the template formal parameters enclosed within < >, immediately following the template keyword.


Attempting to return a reference to a local object

You attempted to return a reference to a temporary object in a function that returns a reference type. This may be the result of a constructor or a function call.

This object will disappear when the function returns, making the reference illegal.


Base class 'class' contains dynamically dispatchable functions

This error occurs when a class containing a DDVT function attempts to inherit DDVT functions from multiple parent classes.

Currently, dynamically dispatched virtual tables do not support the use of multiple inheritance.


Bit fields must be signed or unsigned int (error)
Bit fields must be signed or unsigned int

In ANSI C, bit fields may only be signed or unsigned int (not char or long, for example).


Cannot add or subtract relocatable symbols

The only arithmetic operation that can be performed on a relocatable symbol in an assembler operand is addition or subtraction of a constant.

Variables, procedures, functions, and labels are relocatable symbols.


Cannot have a non-inline function/static data in a local class

All members of classes declared local to a function must be entirely defined in the class definition.

This means that local classes cannot contain any static data members, and all of their member functions must have bodies defined within the class definition.


Case bypasses initialization of a local variable

In C++ it is illegal to bypass the initialization of a local variable.

This error indicates a case label that can transfer control past this local variable.


Declaration does not specify a tag or an identifier

See Also

This declaration doesn't declare anything.

This may be a struct or union without a tag or a variable in the declaration. C++ requires that something be declared.

For example:

struct

{

int a

};

//no tag or identifier


See Also

Identifier expected


Expression of scalar type expected

The !, ++, and -- operators require an expression of scalar type.

Only these types are allowed:

 	char

 	short

 	int

 	long

 	enum

 	float

 	double

 	long double

 	pointer


Extra argument in template class name 'template'

A template class name specified too many actual values for its formal parameters.


Function 'function' should have a prototype

A function was called with no prototype in scope.

In C, prototypes are recommended for all functions. In C++, prototypes are required for all functions.

In all cases, a function definition (a function header with its body) serves as a prototype if it appears before any other mention of the function.


Function definition cannot be a typedef'ed declaration

In ANSI C, a function body cannot be defined using a typedef with a function Type.

Redefine the function body.


Functions 'function1' and 'function2' both use the same dispatch number

This error indicates a dynamically dispatched virtual table (DDVT) problem.


Goto bypasses initialization of a local variable

In C++ it is illegal to bypass the initialization of a local variable.

This error indicates a goto statement that can transfer control past this local variable.


Illegal parameter to _ _emit_ _

There are some restrictions on inserting literal values directly into your code with the __emit__ function.

For example, you cannot give a local variable as a parameter to __emit__.


Invalid combination of opcode and operands

The built-in assembler does not accept this combination of operands.

Possible Causes

 	There are too many or too few operands for this assembler opcode.

 	The number of operands is correct, but their types or order do not match the opcode.


Invalid register combination (e.g. [BP+BX])

The built-in assembler detected an illegal combination of registers in an instruction.

These are valid index register combinations:

 	[BX]

 	[BP]

 	[SI]

 	[DI]

 	[BX+SI]

 	[BX+DI]

 	[BP+SI]

 	[BP+DI]

Other index register combinations are not allowed.


Invalid template argument list

This error indicates that an illegal template argument list was found.

In a template declaration, the keyword template must be followed by a list of formal arguments enclosed within the < and > delimiters.


Invalid template qualified name 'template::name'

When defining a template class member, the actual arguments in the template class name used as the left operand for the :: operator must match the formal arguments of the template class.


Invalid use of template 'template'

You can only use a template class name without specifying its actual arguments inside a template definition.

Using a template class name without specifying its actual arguments outside a template definition is illegal.


Matching base class function 'function' has different dispatch number

If a DDVT function is declared in a derived class, the matching base class function must have the same dispatch number as the derived function.


Matching base class function 'function' is not dynamic

If a DDVT function is declared in a derived class, the matching base class function must also be dynamic.


Member 'member' has the same name as its class

A static data member, enumerator, member of an anonymous union, or nested type cannot have the same name as its class.

Only a member function or a non-static member can have a name that is identical to its class.


Memory reference expected

The built-in assembler requires a memory reference.

You probably forgot to put square brackets around an index register operand.


Nontype template argument must be of scalar type

A nontype formal template argument must have scalar type; it can have an integral, enumeration, or pointer type.


operator new must have an initial parameter of type size_t
Operator new[] Must Have an Initial Parameter of Type size_t

See Also

Operator new can be declared with an arbitrary number of parameters.

It must always have at least one, the amount of space to allocate.


See Also

Identifier expected


Template argument must be a constant expression

A non-type template class argument must be a constant expression of the appropriate type.

This includes constant integral expressions and addresses of objects or functions with external linkage or members.


Template class nesting too deep: 'class'

The compiler imposes a certain limit on the level of template class nesting. This limit is usually only exceeded through a recursive template class dependency.

When this nesting limit is exceeded, the compiler issues this error message for all of the nested template classes. This usually makes it easy to spot the recursion.

This error message is always followed by the fatal error "Out of memory".


Template functions may only have 'type-arguments'

A function template was declared with a non-type argument.

This is not allowed with a template function, as there is no way to specify the value when calling it.


Template function argument 'argument' not used in argument types

The given argument was not used in the argument list of the function.

The argument list of a template function must use all of the template formal arguments; otherwise, there is no way to generate a template function instance based on actual argument types.


Templates can only be declared at file level

Templates cannot be declared inside classes or functions.

They are only allowed in the global scope, or file level.

For example:

template <class T, class U>

void foo(Ta,Tb)

{

   .

   .

   .

}

// error U is not used


Templates must be classes or functions

The declaration in a template declaration must specify either a class type or a function.


The constructor 'constructor' is not allowed

Constructors of the form

X::(X)

are not allowed.

This is the correct way to write a copy constructor:

X::(const X&).


Too few arguments in template class name 'template'

A template class name was missing actual values for some of its formal parameters.


Trying to derive a far class from the huge base 'base'

If a class is declared (or defaults to) huge, all derived classes must also be huge.


Trying to derive a huge class from the far base 'base'

If a class is declared (or defaults to) far, all derived classes must also be far.


Trying to derive a huge class from the near base 'base'

If a class is declared (or defaults to) near, all derived classes must also be near.


Trying to derive a near class from the huge base 'base'

If a class is declared (or defaults to) far, all derived classes must also be far.


Type mismatch in parameter 'parameter' in template class name 'template'

The actual template argument value supplied for the given parameter did not exactly match the formal template parameter type.

When compiling C++ programs, this message is always preceded by another message that explains the exact reason for the type mismatch.

That other message is usually "Cannot convert 'type1' to 'type2'" but the mismatch might be due to many other reasons.


Type mismatch in parameter 'number' in template class name 'template'

The actual template argument value supplied for the given parameter did not exactly match the formal template parameter type.

When compiling C++ programs, this message is always preceded by another message that explains the exact reason for the type mismatch.

That other message is usually "Cannot convert 'type1' to 'type2'" but the mismatch might be due to many other reasons.


Bit fields must have integral type

In C++, bit fields must have an integral type. This includes enumerations.


Cannot find default constructor to initialize array element of type 'class'

When declaring an array of a class that has constructors, you must either explicitly initialize every element of the array, or the class must have a default constructor.

The compiler will define a default constructor for a class unless you have defined any constructors for the class.


Cannot generate 'function' from template function 'template'

A call to a template function was found, but a matching template function cannot be generated from the function template.


Variable 'variable' has been optimized and is no longer available

You have tried to inspect, watch, or otherwise access a variable which the optimizer removed.

This variable is never assigned a value and has no stack location.


Function should return a value (warning)
Function should return a value

This function was declared (maybe implicitly) to return a value.

The compiler found a return statement without a return value, or it reached the end of the function without finding a return statement.

Either return a value or change the function declaration to return void.


Undefined structure 'structure' (warning)
Undefined structure 'structure'

Your source file used the named structure on some line before where the error is indicated (probably on a pointer to a structure) but had no definition for the structure.

This is probably caused by a misspelled structure name or a missing declaration.


Call to function 'function' with no prototype

This message is given if the "Prototypes required" warning is enabled and you call function 'function' without first giving a prototype for that function.


Initializing 'identifier' with 'identifier'

(Command-line equivalent for controling display of this warning = -wbei)

You're trying to initialize an enum variable to a different type.

For example, the following initialization will result in this warning, because 2 is of type int, not type enum count:

enum count zero, one, two x = 2;

It is better programming practice to use an enum identifier instead of a literal integer when assigning to or initializing enum types.

This is an error, but is reduced to a warning to give existing programs a chance to work.


Initialization is only partially bracketed

(Command-line equivalent for controling display of this warning = -wpin)

When structures are initialized, braces can be used to mark the initialization of each member of the structure.

If a member itself is an array or structure, nested pairs of braces can be used.

This ensures that the compiler's idea and your idea of what value goes with which member are the same.

When some of the optional braces are omitted, the compiler issues this warning.

Default = not displayed


'identifier' is declared as both external and static

See Also

(Command-line equivalent for controling display of this warning = -wext)

This identifier appeared in a declaration that implicitly or explicitly marked it as global or external, and also in a static declaration.

The identifier is taken as static.

You should review all declarations for this identifier.

Default = displayed


See Also

Identifier expected


Declare type 'type' prior to use in prototype

(Command-line equivalent for controling display of this warning = -wdpu)

When a function prototype refers to a structure type that has not previously been declared, the declaration inside the prototype is not the same as a declaration outside the protoype.

For example,

int func(struct s *ps);  struct s  /* ... */ ;

Because there is no "struct s" in scope at the prototype for func, the type of parameter ps is pointer to undefined struct s, and is not the same as the "struct s" that is later declared.

This will result in later warning and error messages about incompatible types, which would be very mysterious without this warning message.

To fix the problem, you can move the declaration for "struct s" ahead of any prototype that references it, or add the incomplete type declaration "struct s;" ahead of any prototype that references "structs".

If the function parameter is a struct, rather than a pointer to struct, the incomplete declaration is not sufficient.

You must then place the struct declaration ahead of the prototype.

Default = displayed


Division by zero (warning)
Division by zero

(Command-line equivalent for controling display of this warning = -wzdi)

A divide or remainder expression had a literal zero as a divisor.

Default = displayed


Ambiguous operators need parentheses

See Also

(Command-line equivalent for controling display of this warning = -wamb)

This warning is displayed whenever two shift, relational, or bitwise-Boolean operators are used together without parentheses.

Also, an addition or subtraction operator that appears without parentheses with a shift operator will produce this warning.

Programmers frequently confuse the precedence of these operators, because the precedence assigned to them is somewhat counter intuitive.

Default = not displayed


See Also

Precedence of Operators


Superfluous & with function

(Command-line equivalent for controling display of this warning = -wamp)

An address-of operator (&) is not needed with function name; any such operators are discarded.

Default = not displayed


Parameter 'parameter' is never used

(Command-line equivalent for controling display of this warning = -wpar)

The named parameter, declared in the function, was never used in the body of the function.

This might or might not be an error and is often caused by misspelling the parameter.

This warning can also occur if the identifier is redeclared as an automatic (local) variable in the body of the function.

The parameter is masked by the automatic variable and remains unused.

Default = displayed


Restarting compile using assembly

The compiler encountered an asm with no accompanying or #pragma inline statement.

The compile restarts using assembly language capabilities.


Unknown assembler instruction

(Command-line equivalent for controling display of this warning = -wasm)

The compiler encountered an inline assembly statement with a disallowed opcode.

Check the spelling of the opcode.

This warning is off by default.

Default = not displayed


Hexadecimal value contains more than 3 digits
Hexadecimal value contains more than three digits

(Command-line equivalent for controling display of this warning = -wbig)

Under older versions of C, a hexadecimal escape sequence could contain no more than three digits.

The ANSI standard allows any number of digits to appear as long as the value fits in a byte.

This warning results when you have a long hexadecimal escape sequence with many leading zero digits (such as \x00045).

Older versions of C would interpret such a string differently.

Default = displayed


Constant is long

(Command-line equivalent for controling display of this warning = -wcln)

The compiler encountered one of the following:

 	a decimal constant greater than 32,767 or

 	an octal, hexadecimal, or decimal constant greater than 65,535 without a letter l or L following it

The constant is treated as a long.

Default = not displayed


Nonportable pointer comparison (warning)
Non-portable pointer comparison

(Command-line equivalent for controling display of this warning = -wcpt)

Your source file compared a pointer to a non-pointer other than the constant 0.

You should use a cast to suppress this warning if the comparison is proper.

Default = displayed


Temporary used to initialize 'identifier'

See Also

(Command-line equivalent for controling display of this warning = -wlin)

In C++, a variable or parameter of reference type must be assigned a reference to an object of the same type.

If the types do not match, the actual value is assigned to a temporary of the correct type, and the address of the temporary is assigned to the reference variable or parameter.

The warning means that the reference variable or parameter does not refer to what you expect, but to a temporary variable, otherwise unused.

Default = displayed

Related Topics

Example


See Also

Identifier expected


Example for "Temporary used ..." error messages

In this example, function f requires a reference to an int, and c is a char:

f(int&);

char c;

f(c);

Instead of calling f with the address of c, the compiler generates code equivalent to the C++ source code:

int X = c, f(X);


Temporary used for parameter 'parameter'

OR	Temporary used for parameter 'number'

OR	Temporary used for parameter 'parameter' in call to 'function'

OR	Temporary used for parameter 'number' in call to 'function'

(Command-line equivalent for controling display of this warning = -wlvc)

In C++, a variable or parameter of reference type must be assigned a reference to an object of the same type.

If the types do not match, the actual value is assigned to a temporary of the correct type, and the address of the temporary is assigned to the reference variable or parameter.

The warning means that the reference variable or parameter does not refer to what you expect, but to a temporary variable, otherwise unused.

Default = displayed

Related Topics

Example


The constant member 'member' is not initialized
The constant member 'identifier' is not initialized

(Command-line equivalent for controling display of this warning = -wnci)

This C++ class contains a constant member 'member' that doesn't have an initialization.

Note that constant members can be initialized only; they can't be assigned to.

Default = displayed


Functions containing reserved words are not expanded inline

OR	Functions containing local destructors are not expanded inline in function 'function'

(Command-line equivalent for controling display of this warning = -winl)

Reserved Words

Functions containing any of these reserved words can't be expanded inline, even when specified as inline:

 	break

 	case

 	continue

 	do

 	for

 	goto

 	switch

 	while

The function is still perfectly legal, but will be treated as an ordinary static (not global) function.

A copy of the function will appear in each compilation unit where it is called.

Local Destructors

You've created an inline function for which the compiler turns off inlining. You can ignore this warning; the function will be generated out of line.

Default = displayed


Base initialization without a class name is now obsolete

(Command-line equivalent for controling display of this warning = -wobi)

Early versions of C++ provided for initialization of a base class by following the constructor header with just the base class constructor parameter list.

It is now recommended to include the base class name.

This makes the code much clearer, and is required when you have multiple base classes.

Old way

derived::derived(int i) : (i, 10) { ... }

New way

derived::derived(int i) : base(i, 10) { ... }

Default = displayed


Style of function definition is now obsolete

(Command-line equivalent for controling display of this warning = -wofp)

In C++, this old C style of function definition is illegal:

int func(p1, p2) int p1, p2; { /* ... */ }

This practice might not be allowed by other C++ compilers.

Default = displayed


'overload' is now unnecessary and obsolete
Overload is now unnecessary and obsolete

(Command-line equivalent for controling display of this warning = -wovl)

Early versions of C++ required the reserved word "overload" to mark overloaded function names.

C++ now uses a "type-safe linkage" scheme, whereby all functions are assumed overloaded unless marked otherwise.

The use of "overload" should be discontinued.

Default = displayed


Assigning 'type' to 'enumeration'

(Command-line equivalent for controling display of this warning = -weas)

Assigning an integer value to an enum type.

This is an error in C++, but is reduced to a warning to give existing programs a chance to work.

Default = displayed


Non-constant function 'function' called for constant object
Non-const function 'function' called for const object

(Command-line equivalent for controling display of this warning = -wncf)

A non-const member function was called for a const object.

(This is an error, but was reduced to a warning to give existing programs a chance to work.)

Default = displayed


Non-volatile function 'function' called for volatile object

In C++, a class member function was called for a volatile object of the class type, but the function was not declared with volatile following the function header. Only a volatile member function can be called for a volatile object.

For example, if you have

  class c

  {

  public:

    f() volatile;

    g();

  };

  volatile c vcvar;

it is legal to call vcvar.f(), but not to call vcvar.g().


'function1' hides virtual function 'function2'

(Command-line equivalent for controling display of this warning = -whid)

A virtual function in a base class is usually overridden by a declaration in a derived class.

In this case, a declaration with the same name but different argument types makes the virtual functions inaccessible to further derived classes.

Default = displayed


Possible use of 'identifier' before definition

See Also

(Command-line equivalent for controling display of this warning = -wdef)

Your source file used the variable 'identifier' in an expression before it was assigned a value.

The compiler uses a simple scan of the program to determine this condition.

If the use of a variable occurs physically before any assignment, this warning will be generated.

Of course, the actual flow of the program can assign the value before the program uses it.

Default = not displayed


See Also

Identifier expected


Constant out of range in comparison

(Command-line equivalent for controling display of this warning = -wrng)

Your source file includes a comparison involving a constant sub-expression that was outside the range allowed by the other sub-expression's type.

For example, comparing an unsigned quantity to -1 makes no sense.

To get an unsigned constant greater than 32,767 (in decimal), you should either

 	cast the constant to unsigned--for example, (unsigned) 65535, or

 	append a letter u or U to the constant--for example, 65535u.

Whenever this message is issued, the compiler still generates code to do the comparison.

If this code ends up always giving the same result (such as comparing a char expression to 4000), the code will still perform the test.

Default = displayed


Redefinition of 'macro' is not identical

(Command-line equivalent for controling display of this warning = -wdup)

Your source file redefined the macro 'ident' using text that was not exactly the same as the first definition of the macro.

The new text replaces the old.

Default = displayed


Array variable 'identifier' is near

See Also

(Command-line equivalent for controling display of this warning = -wias)

When you use set the Far Data Threshold option, the compiler automatically makes any global variables that are larger than the threshold size be far.

When the variable is an initialized array with an unspecified size, its total size is not known when the compiler must decide whether to make it near or far, so the compiler makes it near.

The compiler issues this warning if the number of initializers given for the array causes the total variable size to exceed the data size threshold.

If the fact that the compiler made the variable be near causes problems, make the offending variable explicitly far.

To do this, insert the keyword "far" immediately to the left of the variable name in its definition.

Default = displayed


See Also

Identifier expected


Possibly incorrect assignment

(Command-line equivalent for controling display of this warning = -wpia)

This warning is generated when the compiler encounters an assignment operator as the main operator of a conditional expression (part of an if, while, or do-while statement).

This is usually a typographical error for the equality operator.

If you want to suppress this warning, enclose the assignment in parentheses and compare the whole thing to zero explicitly.

For example, this code

if (a = b) ...

should be rewritten as

if ((a = b) != 0) ...

Default = displayed


Conversion may lose significant digits

(Command-line equivalent for controling display of this warning = -wsig)

For an assignment operator or some other circumstance, your source file requires a conversion from long or unsigned long to int or unsigned int type.

Because int type and long type variables don't have the same size, this kind of conversion might alter the behavior of a program.

Default = not displayed


No declaration for function 'function'

(Command-line equivalent for controling display of this warning = -wnod)

This message is given if you call a function without first declaring that function.

In C, you can declare a function without presenting a prototype, as in

int func();

In C++, every function declaration is also a prototype; this example is equivalent to

int func(void);

The declaration can be either classic or modern (prototype) style.

Default = not displayed


Code has no effect

(Command-line equivalent for controling display of this warning = -weff)

This warning is issued when the compiler encounters a statement with some operators that have no effect.

For example, the statement

a + b;

has no effect on either variable.

The operation is unnecessary and probably indicates a bug.

Default = displayed


'identifier' is assigned a value that is never used

(Command-line equivalent for controling display of this warning = -waus)

The variable appears in an assignment, but is never used anywhere else in the function just ending.

The warning is indicated only when the compiler encounters the closing brace.

Default = displayed


Ill-formed pragma

(Command-line equivalent for controling display of this warning = -will)

A pragma does not match one of the pragmas expected by the compiler.

Default = displayed


Call to function with no prototype

(Command-line equivalent for controling display of this warning = -wpro)

This message is given if the "Prototypes required" warning is enabled and you call a function without first giving a prototype for that function.

Default = displayed


Suspicious pointer conversion

(Command-line equivalent for controling display of this warning = -wsus)

The compiler encountered some conversion of a pointer that caused the pointer to point to a different type.

You should use a cast to suppress this warning if the conversion is proper.

A common cause of this warning is when the C compiler converts a function pointer of one type to another (the C++ compiler generates an error when asked to do that). It can be suppressed by doing a typecast. Here is a common occurence of it for Window programmers:

#define STRICT

#include <windows.h>

LPARAM _export WndProc( HWND , UINT , WPARAM , LPARAM );

test() {

   WNDCLASS wc;

   wc.lpfnWndProc = WndProc;  //warning

}

It is suppressed by making the assignment to lpfnWndProc as follows:

wc.lpfnWndProc = ( WNDPROC ) WndProc;

Default = displayed


Unreachable code

(Command-line equivalent for controling display of this warning = -wrch)

A break, continue, goto, or return statement was not followed by a label or the end of a loop or function.

The compiler checks while, do,, and for loops with a constant test condition, and attempts to recognize loops that can't fall through.

Default = not displayed


Both return and return with a value used
Both return and return of a value used

(Command-line equivalent for controling display of this warning = -wret)

The current function has return statements with and without values.

This is legal C, but almost always an error.

Possibly a return statement was omitted from the end of the function.

Default = displayed


Nonportable pointer conversion

(Command-line equivalent for controling display of this warning = -wrpt)

A nonzero integral value is used in a context where a pointer is needed or where an integral value is needed; the sizes of the integral type and pointer are the same.

Use an explicit cast if this is what you really meant to do.

Default = displayed


Void functions may not return a value

Your source file declared the current function as returning void, but the compiler encountered a return statement with a value.

The value of the return statement will be ignored.


Structure passed by value

(Command-line equivalent for controling display of this warning = -wstv)

This warning is generated any time a structure is passed by value as an argument.

It is a frequent programming mistake to leave an address-of operator (&) off a structure when passing it as an argument.

Because structures can be passed by value, this omission is acceptable.

This warning provides a way for the compiler to warn you of this mistake.

Default = not displayed


Mixing pointers to signed and unsigned char
Mixing pointers to different 'char' types

(Command-line equivalent for controling display of this warning = -wucp)

You converted a signed char pointer to an unsigned char pointer, or vice versa, without using an explicit cast.

(Strictly speaking, this is incorrect, but it is often harmless.)

Default = not displayed


'identifier' declared but never used

(Command-line equivalent for controling display of this warning = -wuse)

Your source file declared the named variable as part of the block just ending, but the variable was never used.

The warning is indicated when the compiler encounters the closing brace of the compound statement or function.

The declaration of the variable occurs at the beginning of the compound statement or function.

Default = not displayed


Condition is always true/false
Condition is always true OR Condition is always false

(Command-line equivalent for controling display of this warning = -wccc)

Whenever the compiler encounters a constant comparison that (due to the nature of the value being compared) is always true or false, it issues this warning and evaluates the condition at compile time.

For example:

  void proc(unsigned x){

    if (x >= 0)        /* always 'true' */

    {

       ...

    }

  }

Default = displayed


Array size for 'delete' ignored

(Command-line equivalent for controling display of this warning = -wdsz)

The C++ IDE issues this warning when you've specified the array size when deleting an array.

With the new C++ specification, you don't need to make this specification. the compiler ignores this construct.

This warning lets older code compile.

Default = displayed


Base class 'class1' is inaccessible because also in 'class2'
Base class 'base1' is also a 'base class of ' ???"

(Command-line equivalent for controling display of this warning = -wibc)

It is not legal to use a class as both a direct and indirect base class, since the members are automatically ambiguous.

Try making the base class virtual in both locations.

Default = displayed


Bit fields must be signed or unsigned int (warning)
Bit fields must be signed or unsigned int

(Command-line equivalent for controling display of this warning = -wbbf)

In ANSI C, bit fields may not be of type signed char or unsigned char.

When you're not compiling in strict ANSI mode, the compiler allows these constructs, but flags them with this warning.

Default = not displayed


Overloaded prefix 'operator operator' used as a postfix operator
Overloaded prefix operator 'operator' used as a postfix operator

(Command-line equivalent for controling display of this warning = -wpre)

With the latest C++ specification, it is now possible to overload both the prefix and postfix versions of the ++ and -- operators.

Whenever the prefix operator is overloaded, but is used in a postfix context, the compiler uses the prefix operator and issues this warning.

This allows older code to compile.

Default = not displayed


Use qualified name to access nested type 'type'

(Command-line equivalent for controling display of this warning = -wnst)

In older versions of the C++ specification, typedef and tag names declared inside classes were directly visible in the global scope.

With the latest specification of C++, these names must be prefixed with class::qualifier if they are to be used outside of their class scope.

The compiler issues this warning whenever a name is uniquely defined in one single class.

The compiler allows this usage without  class::. This allows older versions of code to compile.

Default = displayed


Conversion to 'type' will fail for members of virtual base 'class'

This warning is issued only if the -Vv option or Options|Project|C++ Options|C++ Compatibility|Deep Virtual Bases option is in use.

The warning is issued in some cases when a member pointer to one type is cast to a member pointer of another type and if the class of the converted member pointer has virtual bases.

Encountering this warning means that at run-time, if the member pointer conversion cannot be completed, the result of the cast will be a NULL member pointer.


Stack overflow

This error is reported when you compile a function with the Test Stack Overflow option on, but there is not enough stack space to allocate the function's local variables.

This error can also be caused by the following:

infinite recursion, or

an assembly language procedure that does not maintain the stack project

 	a large array in a function


Abnormal program termination

The program called abort because Window failed to execute.

This message can be caused by memory overwrites.


Divide error

You tried to divide an integer by zero, which is illegal.


Floating point error: Divide by 0

OR	Floating point error: Domain

OR	Floating point error: Overflow

These fatal errors result from a floating-point operation for which the result is not finite:

 	Divide by 0	means the result is +INF or -INF exactly, such as 1.0/0.0.

 	Domain	means the result is NAN (not a number), like 0.0/0.0.

 	Overflow	means the result is +INF (infinity) or -INF with complete loss of precision, such as assigning 1e200*1e200 to a double.


Floating point error: Partial loss of precision/Underflow
Floating point error: Partial loss of precision

OR	Floating point error: Underflow

These exceptions are masked by default, because underflows are converted to zero and losses of precision are ignored.


Floating point error: Stack fault

The floating-point stack has been overrun. This error may be due to assembly code using too many registers or due to a misdeclaration of a floating-point function.

The program prints the error message and calls abort and _exit.

These floating-point errors can be avoided by masking the exception so that it doesn't occur, or by catching the exception with signal.


Type 'typename' may not be defined here

Class and enumeration types may not be defined in a function return type, a function argument type, a conversion operator type, or the type specified in a cast.

You must define the given type before using it in one of these contexts.

Note:	This error message is often the result of a missing semicolon (;) for a class declaration. You might want to verify that all the class declarations preceding the line on which the error occurred end with a semicolon.


Cannot call 'main' from within the program

C++ does not allow recursive calls of main( ).


Application is running

The application you tried to run is already running.

For Windows, make sure the message loop of the program has properly terminated.

PostQuitMessage(0);


Maximum precision used for member pointer type type

When a member pointer type is declared, its class has not been fully defined, and the -Vmd option has been used, the compiler has to use the most general (and the least efficient) representation for that member pointer type. This can cause less efficient code to be generated (and make the member pointer type unnecessarily large), and can also cause problems with separate compilation; see the -Vm compiler switch for details.


Include Files Nested too Deep

This message flags (directly or indirectly) recursive #include directives.


Cannot Take Address of 'main'

In C++ it is illegal to take the address of the main function.


Ambiguous Override of Virtual Base Member '<function1>': '<function2>'

A virtual function in a virtual base class was overridden with two or more different functions along different paths in the inheritance hierarchy.


Cannot Throw '<type>' -- Ambiguous Base Class '<base>'

It is not legal to throw a class that contains more than one copy of a (non-virtual) base class.


Exception Specification Not Allowed Here

Function pointer type declarations are not allowed to contain exception specifications.


Exception Handling Variable May Not Be Used Here

An attempt has been made to use one of the exception handling values that are restricted to particular exception handling constructs, such as GetExceptionCode().


Functions Cannot Return Arrays or Functions

A function was defined to return an array or a function. Check to see if either the intented return was a pointer to an array or function (and perhaps the * is missing) or if the function definition contained a request for an incorrect datatype.


Duplicate Handler for '<type1>', Already Had '<type2>'

It is not legal to specify two handlers for the same type.


The '...' Handler Must be Last

In a list of catch handlers, if the '...' handler is present, it must be the last handler in the list (i.e. it can not be followed by any more catch handlers).


VIRDEF Name Conflict for '<function>'

The compiler must truncate mangled names to a certain length because of a name length limit that is imposed by the linker. This truncation may (in very rare cases) cause two names to mangle to the same linker name. If these names happen to both be VIRDEF names, the compiler issues this error message. The simplest workaround for this problem is to change the name of <function> so that the conflict is avoided.


Goto Into an Exception Handler is Not Allowed

It is not legal to jump into a try block, or an exception handler that is attached to a try block.


'catch' Expected

In a C++ program, a 'try' block must be followed by at least one 'catch' block.


Type '<type>' is Not a Defined Class with Virtual Functions

dynamic_cast was used with a pointer to a class type that is either undefined, or doesn't have any virtual member functions.


> Expected

A new-style cast (e.g., dynamic_cast) was found with a missing closing ">".


'<type>' is Not a Polymorphic Class Type

This error is generated if the -RT compiler option (for run-time type information) is disabled and either

dynamic_cast was used with a pointer to a class

or

you tried to delete a pointer to an object of a class that has a virtual destructor


'__except' or '__finally' Expected Following '__try'

In C, a '__try block' must be followed by a '__except' or '__finally' handler block.


Reference Member '<member>' Initialized with a Non-Reference Parameter

An attempt has been made to bind a reference member to a constructor parameter. Since the parameter will cease to exist the moment the constructor returns to its caller, this will not work correctly.


Non-ANSI Keyword Used: '<keyword>'

A non-ANSI keyword (such as '__fastcall') was used when strict ANSI conformance was requested via the -A option.


Handler for '<type1>' Hidden by Previous Handler for '<type2>'

This warning is issued when a handler for a type 'D' that is derived from type 'B' is specified after a handler for B', since the handler for 'D' will never be invoked.


Cannot Create Pre-Compiled Header: <reason>

This warning is issued when pre-compiled headers are enabled but the compiler could not generate one, for one of the following reasons:

reason	explanation

write failed	The compiler could not write to the pre-compiled header file. This is usually due to the disk being full.

code in header	One of the headers contained a non-inline function body.

initialized data in header	One of the headers contained a global variable definition (in C, a global variable with an initializer, in C++ any variable that is not declared as 'extern').

header incomplete	The pre-compiled header ended in the middle of a declaration, e.g. inside a class definition (this often happens when there is a missing"}" in a header file).


Use '> >' for Nested Templates Instead of '>>'

Whitespace is required to separate the closing ">" in a nested template name, but since it is an extremely common mistake to leave out the space, the compiler accepts a ">>" with this warning.


Initializing enumeration with type

You're trying to initialize an enum variable to a different type. For example,

enum count { zero, one, two } x = 2;

will result in this warning, because 2 is of type int, not type enum count. It is better programming practice to use an enum identifier instead of a literal integer when assigning to or initializing enum types.

This is an error, but is reduced to a warning to give existing programs a chance to work.


main must have a return type of int

In C++, function main has special requirements, one of which is that it cannot be declared with any return type other than int.


'ident' is obsolete

Issues a warning upon usage for any  "C" linkage function that has been specified. This will warn about functions that are "obsolete".

Here's an example of it's usage:

#ifdef __cplusplus

extern "C" {

#endif

void my_func(void);

#ifdef __cplusplus

}

#endif

#pragma obsolete my_func

main()

{

my_func();   // Generates warning about obsolete function

}


Unexpected termination during compilation [Module Seg#:offset]

OR	Unexpected termination during linking [Module Seg#:offset]

If either of these errors occur, it indicates a catastrophic failure of the Borland tools. You should contact Borland to report the problem and to find a potential work around for your specific case. By isolating the test case as well as possible, you will increase the chance for either Borland or yourself to find a work around for the problem.

Commonly, compiler failures can be worked around by moving the source code that is currently being compiled. Simple cases might be switching the order of variable declarations, or functions within the source module. Moving the scope and storage of variables also helps in many cases.

For linker failures, you will most likely want to reduce the amount of debugging information that the linker has to work with. Try compiling only one or two modules with debug info instead of an entire project. Similarly, switching the order that object modules are handed to the linker can work around the problem. The IDE hands objs to the linker in the order that they are listing in the project tree. Try moving a source up or down in the list.


Unable to load 16 bit compiler

OR	Unable to load 16 bit linker

OR	Unable to load 32 bit compiler

OR	Unable to load 32 bit linker

In the case of the 16 bit linker or compiler, the file BCWS16.DLL must be either in the directory where BCW.EXE resides, or somewhere along your path. If the DLL is in the correct location and still will not load, it is possible that you do not have enough memory for the DLL to load. BCW operates optimally when you have at least 12 megs of memory in any combination of physical ram and virtual memory.

For the 32 bit linker and compiler, the same rules apply for BCWS32.EXE. In addition, you must have a system running which supplies the Win32 API. Check to make sure that you have properly installed either NT or Win32s on your windows system by running another 32 bit application such as the FreeCell game which accompanies the operating system.


Compiler stack overflow

The compiler's stack has overflowed. This can be caused by a number of things, among them very deeply nested statements in a function body (e.g., if/else) or expressions with a very large number of operands. You must simplify your code if this message occurs. Adding more memory to your system will not help.


286/287 instructions not enabled

Use the -2 command-line compiler option or the 80286 option in the Options|Project|16-bit Compiler|Processor settings to enable 286/287 opcodes. Be aware that the resulting code cannot be run on 8086- and 8088-based machines.


Incorrect option:

An error has occured in either the config file or a command-line option. The compiler may not have recognized the configuration file parameter as legal; check for a preceding hyphen (-), or the compiler may not have recognized the command-line parameter as legal.

This error can also occur if you use a #pragma option in your code with an invalid option.


Unable to execute command

TLINK or TASM cannot be found, or possibly the disk is bad.


__far16' may only be used with '__pascal' or '__cdecl'

When you use __far16 to make calls to functions or reference data in a 16-bit DLL, such functions and data can be modified only by __pascal or __cdecl.


Function calls not supported

In integrated debugger expression evaluation, calls to functions (including implicit conversion functions, constructors, destructors, overloaded operators, and inline functions) are not supported.


Not a valid expression format type

Invalid format specifier folowing expression in the debug evaluate or watch window. A valid format specifier is an optional repeat value followed by a format character (c, d, f[n], h, x, m, p, r, or s).


Cannot access an inactive scope

You have tried to evaluate or inspect a variable local to a function that is currently not active. (This is an integrated debugger expression evaluation message.)


Unable to create turboc.$ln

The compiler cannot create the temporary file TURBOC.$LN because it cannot access the disk or the disk is full.


Conversion of near pointer not allowed

A near pointer cannot be converted to a far pointer in the expression evaluation box when a program is not currently running. This is because the conversion needs the current value of DS in the user program, which doesn't exist.


'new' and 'delete' not supported

An integrated debugger expression evaluation, the new and delete operators are not supported.


Exception handling not enabled

A 'try' block was found with the exception handling disabled.


No file names given

The command line of the Borland C++ command-line compiler (BCC) contained no file names. You must specify a source file name.


Multiple base classes not supported

An error has occured while using the command-line utility H2ASH. See the online file "tsm_util.txt" for further information about this utility.


Overloaded function resolution not supported

In integrated debugger expression evaluation, resolution of overloaded functions or operators is not supported, not even to take an address.


Templates not supported

An error has occured while using the command-line utility H2ASH. See the online file "tsm_util.txt" for further information about this utility.


No type information

Debugger has no type information for this variable. Module may have been compiled without debug switch turned on, or by another compiler or assembler.


Virtual base classes not supported

An error has occured while using the command-line utility H2ASH. See the online file "tsm_util.txt" for further information about this utility.


Overlays only supported in medium, large, and huge memory models

Only programs using the medium, large, or huge memory models can be overlaid.


Repeat count needs an lvalue

The expression before the comma (,) in the Watch or Evaluate window must be a manipulable region of storage. For example, expressions like this one are not valid:

i++,10d

x = y, 10m


Can't inherit non-RTTI class from RTTI base

When virtual functions are present, the RTTI attribute of all base classes must match that of the derived class.


Side effects are not allowed

Side effects such as assignments, ++, or -- are not allowed in the debugger watch window. A common error is to use x = y (not allowed) instead of x == y to test the equality of x and y.


'%s' is not a valid template type member

A member of a template with some actual arguments that depend on the formal arguments of an enclosing template was found not to be a member of the specified template in a particular instance.


'%s' requires run-time initialization/finalization

This message is issued when a global variable that is declared as __thread (a Win32-only feature) or a static data member of a template class is initialized with a non-constant initial value.

This message is also issued when a global variable that is declared as __thread (a Win32-only feature) or a static data member of a template class has the type class with constructor or destructor.


Cannot use tiny or huge memory model with Windows

This message is self-explanatory. Use small, medium, compact, or large instead.


Declaration ignored

An error has occured while using the command-line utility H2ASH. See the online file "tsm_util.txt" for further information about this utility.


Macro definition ignored

An error has occured while using the command-line utility H2ASH. See the online file "tsm_util.txt" for further information about this utility.


Constructor initializer list ignored

An error has occured while using the command-line utility H2ASH. See the online file "tsm_util.txt" for further information about this utility.


Function body ignored

An error has occured while using the command-line utility H2ASH. See the online file "tsm_util.txt" for further information about this utility.


Initializer for object '' ignored

An error has occured while using the command-line utility H2ASH. See the online file "tsm_util.txt" for further information about this utility.


Functions are not expanded inline

Exception specifications are not expanded inline: Check your inline code for lines containing exception specification.

Functions taking class-by-value argument(s) are not expanded inline: When exception handling is enabled, functions that take class arguments by value cannot be expanded inline.

Note:	that functions taking class parameters by reference are not subject to this restriction.


undef directive ignored
#undef directive ignored

An error has occured while using the command-line utility H2ASH. See the online file "tsm_util.txt" for further information about this utility.


Declaration of static function '(...)' ignored

An error has occured while using the command-line utility H2ASH. See the online file "tsm_util.txt" for further information about this utility.


Temporary used for parameter
Temporary used for parameter '???'

In C++, a variable or parameter of reference type must be assigned a reference to an object of the same type. If the types do not match, the actual value is assigned to a temporary of the correct type, and the address of the temporary is assigned to the reference variable or parameter.

The warning means that the reference variable or parameter does not refer to what you expect, but to a temporary variable, otherwise unused.

In the following example, function f requires a reference to an int, and c is a char:

f(int&amp.);

char c;

f(c);

Instead of calling f with the address of c, the compiler generates code equivalent to the C++ source code:

int X = c, f(X);


Temporary used for parameter 2 in call to ???
Temporary used for parameter 2 in call to '???'

In C++, a variable or parameter of reference type must be assigned a reference to an object of the same type. If the types do not match, the actual value is assigned to a temporary of the correct type, and the address of the temporary is assigned to the reference variable or parameter.

The warning means that the reference variable or parameter does not refer to what you expect, but to a temporary variable, otherwise unused.

In the following example, function f requires a reference to an int, and c is a char:

f(int&amp.);

char c;

f(c);

Instead of calling f with the address of c, the compiler generates code equivalent to the C++ source code:

int X = c, f(X);


Internal compiler error

An error occurred in the internal logic of the compiler. This error shouldn't occur in practice, but is generated in the event that a more specific error message is not available.


DPMI programs must use the large memory model

DPMI programs can only use large memory model. Timy, Small, Medium, Compact, and Huge memory models are not allowed.


Recursive template function: '' instantiated ''
Recursive template function: '" instantiated ''

The compiler has detected a recursive template function instance. For example:

    template<class T> void f(T x)

    {

       f((T*)0);   // recursive template function!

    }

    void main()

    {

       f(0);

    }

The compiler will issue one message per each nesting of the recursive instantiation, so it is usually quite obvious where the recursion has occurred. To fix a recursive template, either change the dependencies, or provide a specialized version that will stop the recursion. For example, adding the following function definition to the above program will remove the endless recursion:

    void f(int **)

    {

    }


Class '<classname>' is abstract because of 'member = 0'

This message is issued immediately after the "Cannot create instance of abstract class 'classname>' error message and is intended to make it easier to figure out why a particular class is considered abstract by the compiler.

For example, consider the following example of an illegal attempt to instantiate an abstract class:

struct VB

{

virtual	void  f() = 0;

virtual	void  g() = 0;

virtual	void  h() = 0;

};

struct D1 : virtual VB

{

void   f();

};

struct D2 : virtual VB

{

void   h();

};

struct DD : D1, D2

{

}

v;   // error 'DD' is an abstract class

The above code will result in the following two error messages:

Error TEST.CPP 21: Cannot create instance of abstract class 'DD'

Error TEST.CPP 21: Class 'DD' is abstract because of 'VB::g() = 0'


User-Defined Message

The error message on which you have requested Help, is a user-defined warning.

In Borland C++ code, user-defined messages are introduced by using the #pragma message compiler syntax.

Note:	In addition to messages that you introduce with the #pragma message compiler syntax, user-defined warnings can be introduced by third party libraries. Should you require Help about a third party warning, please contact the vendor of the header file that issued the warning.


Bad character in parameters

One of the following characters was encountered in a response file:

  "    *    <    =    >    ?    [    ]    |

or any control character other than horizontal tab, line feed, carriage return, or Ctrl-Z.


Invalid initial stack offset

This message occurs only when modules with 32-bit records are linked.

It means that the initial stack pointer value exceeds the DOS limit of 64K.


Bad version number in parameter block

This error indicates an internal inconsistency in the IDE.

If it occurs, exit and restart the IDE.


'filename' ('linenum'): Incompatible attribute

The linker encountered incompatible segment attributes in a CODE or DATA statement.

For instance, both PRELOAD and LOADONCALL can't be attributes for the same segment.


'filename' ('linenum'): Missing internal name

In the IMPORTS section of the module definition file, there was a reference to an entry specified via module name and ordinal number.

When an entry is specified by ordinal number, an internal name must be assigned to this import definition.

It is this internal name that your program uses to refer to the imported definition.

The syntax in the module definition file should be:

  <internalname>=<modulename>.<ordinal>


'filename' ('linenum'): File read error

A DOS error occurred while attempting to read the specified file.

This usually means that a premature end of file occurred. Check for 0 length files.


'filename' ('linenum'): Syntax error

The linker found a syntax error in the module definition file.

The file name and line number tell you where the syntax error occurred.


Group 'group' exceeds 64K

This message will occur if a group exceeds 64K when the segments of the group are combined.


Internal linker error 'errorcode'

An error occurred in the internal logic of the linker.

This error shouldn't occur, but is listed for completeness in the event that a more specific error isn't generated.

If this error persists, write down the errorcode number and contact Borland.


Out of memory (linker)
Out of memory

The linker has run out of dynamically allocated memory needed during the link process. The total working storage is exhausted.

This error is a catchall for running into a limit on memory usage.

Solutions

You can try reducing size of active RAM disks and/or disk caches.

Close one or more applications to free up memory.


Not enough memory
Not enough memory to run application

There is not enough memory to run the linker.

Try closing one or more applications, then run the linker again.


Bad object file record in library file 'filename' in module 'module' near module file offset '0xxxxxxxxx'

OR	Bad object file record in library file 'filename' near module file offset '0xxxxxxxxx'

An ill-formed object file was encountered.

This is most commonly caused by specifying a source file, by naming an object file that was not completely built, or by corrupting the response file so that a non .obj file is included in the .obj file list or library file list.

This can occur if the machine was rebooted during a compile, or if a compiler did not delete its output object file when a Ctrl-Brk was pressed.

Recompile. If error persists, call Borland Tech Support.


DOS error, ax = 'decimal number'

This occurs if a DOS call returned an unexpected error. The ax value printed is the resulting error code. This could indicate a linker internal error or a DOS error. The only DOS calls the linker makes where this error could occur are read, write, seek, and close.

Make sure that there are no zero length .obj files included in the link.


Stub program exceeds 64K

This errors occurs if a DOS stub program written for a Windows application exceeds 64K.

Stub programs are specified via the STUB module definition file statement.

The linker only supports stub programs of 64K or smaller.


Table limit exceeded

This message results from one of the linker's internal tables overflowing.

This usually means that the programs being linked have exceeded the linker's capacity for public symbols, external symbols, or for logical segment definitions.

Each instance of a distinct segment name in an object file counts as a logical segment; if two object files define this segment, then this results in two logical segments.

When the table limit is exceeded, try linking with extended dictionaries.


Illegal group definition: 'group' in module 'module'

This error results from an invalid GRPDEF record in an .OBJ file.

This could result from custom-built .OBJ files or a bug in the translator used to generate the .OBJ file.

If this occurs in a file created by a Borland compiler, recompile the file. If the error persists, contact Borland.


Invalid segment definition in module 'module'

This error results from an invalid GRPDEF record in an .OBJ file.

This could result from custom-built .OBJ files or a bug in the translator used to generate the .OBJ file.

If this occurs in a file created by a Borland compiler, recompile the file. If the error persists, contact Borland.


Debugging information overflow; try fewer modules with debug info

Too many modules containing debugging information are included in the link.

The debugging information executable file specification uses 16-bit fields for many counts.

This error message indicates that one of the count fields has overflowed.


Limit of 254 segments for new executable file exceeded

You have reached the limit of segments that can be specified by the executable file format.

Only 254 segments can be represented in Windows EXEs and DLLs.

To reduce the total number of segments to below 254, turn on the Pack Code Segments option.


General error

OR	General error in library file 'filename' in module 'module' near module file offset '0xyyyyyyyy'

OR	General error in module 'module' near module file offset '0xyyyyyyyy'

The linker gives as much information as possible about what processing was happening at the time of the unknown fatal error.


Terminated by user

A Ctrl Break was detected.


Unable to open file 'filename'

The named file can't be found, possibly because it does not exist or is misspelled,

or resides in a different directory than the ones being searched.

If you are using the IDE, make sure you have set the appropriate directory paths in the

Options|Directories dialog box.


Linker stack overflow

TLINK uses a recursive procedure for marking modules to be included in an executable image from libraries. This procedure can cause stack overflows in extreme circumstances.

If you get this error message, remove some modules from libraries, include them with the

object files in the link, and try again.


32-bit processing not supported in overlays.
32-bit processing not supported in overlays

Invalid combination of /o (overlays) and /3 (32-bit processing) specified in link command-line.


Imported references from VIRDEFs not supported
Imported reference from a VIRDEF to "symbol name"

The linker does not support references from VIRDEFs to symbols that are imported from dynamically linked libraries.

If you have an inline function in an executable which references a static data member of a class in a DLL, take the function out of the line.


Invalid entry point offset

The only code that could produce this is:

_TEXT  segment public 'CODE'

main:

_TEXT  ends

       end main

In this case, the linker is trying to apply the fixup contained in the record for main, but there is no code.


Common segment exceeds 64K

The program had more than 64K of near uninitialized data.

Try declaring some uninitialized data as far.


Fixup overflow at 'seg:xxxx'h, target = 'segment:xxx'h in module 'module'

OR	Fixup overflow at 'seg:xxxx'h, target = 'symbol' in module 'module'

Either of these messages indicates an incorrect data or code reference in an object file that the linker must fix up at link time.

This message is most often caused by a mismatch of memory models. A near call to a function in a different code segment is the most likely cause.

This error can also result if you generate a near call to a data variable or a data reference to a function.

In either case, the symbol named as the target in the error message is the referenced variable or function.

The reference is in the named module, so look in the source file of that module for the offending reference.

Rebuild the entire program to ensure that all modules have been compiled with in the same memory model. Checked that linked libraries were also compiled in the same memory module.

If this technique does not identify the cause of the failure, or if you are programming in assembly language or a high-level language besides C or C++, there might be other possible causes for this message.

Even in C++, this message could be generated if you are using different segment or group names than the default values for a given memory model.


'symbol' defined in module 'module' is duplicated in module 'module'

This message results from a conflict between two symbols (either public or communal).

This usually means that a symbol is defined in two modules.

An error occurs if both are encountered in the .OBJ file(s), because the linker doesn't know which is valid.


Too many error or warning messages (linker)
Too many error or warning messages

There is a user specified limit on the number of error messages or warnings to be displayed. This limit has been reached.


Undefined symbol 'symbol' in module 'module'

The named symbol is referenced in the given module but is not defined anywhere in the set of object files and libraries included in the link.

Check to make sure the symbol is spelled correctly.

You will usually see this error from the linker for C or C++ symbols if any of the following occur:

You did not properly match a symbol's declarations of pascal and cdecl type in different source files.

You have omitted the name of an .OBJ file your program needs.

You did not link in the emulation library.

If you are linking C++ code with C modules, you might have forgotten to wrap C external declarations in extern "C" .

You might also have a case mismatch between two symbols.


Automatic data segment exceeds 64K

The sum of the DGROUP physical segment, local heap, and stack exceeded 64K.

Either specify smaller values for the HEAPSIZE and STACKSIZE statements in the module definition file, or decrease the size of your near data in DGROUP.

The map file will show the sizes of the component segments in DGROUP.


New Executable header overflowed 64K

Industry standards require that headers be no larger than 64K in size. If you encounter this message, check to see if the resident name table is increasing the size of the header so that it exceeds this limitation.


Write failed, disk full?

Writing to the specified disk failed. Check to see if the disk is full.


Segment %s exceeds 64K

Industry standards require that segments be no larger than 64K in size. If you encounter this message, the segment in question has exceeded this limit.


Segment alignment factor too small

Segment alignment factor is too small to allow access to segments. If you encounter this error, use the /A Linker option and try a larger alignment factor, like 1024. The /A option defaults to 512.


Segment too large for segment table

Industry standards require that segments be no larger than 64K in size. If you encounter this message, the segment in question has exceeded this limit.


Undefined alias symbol %m

The symbol being aliased was undefined. This occured either because of an invalid function name or the function itself was not included in the link.


Segment %s relocation data exceeds 64K

16-bit Windows programs have a limit of 64K of relocation data per segment. It is unlikely that this limit will ever be exceeded, but can be if a particular module contains extremely large jump tables or virtual tables in the code segment itself. If you get this message, try breaking the associated code module into two pieces, as this may reduce the total number of relocations per segment to below 64K.


Import library %s encountered in obj list

An import library can not be listed in a response file as an .OBJ.


Duplicate ordinal 'number' in exports

The linker encountered two exports with the same ordinal value.

Check the module definition file to ensure that there are no duplicate ordinal values specified in the EXPORTS section.

If not, you are linking with modules that specify exports by ordinals and one of two things happened:

two export records specify the same ordinal, or

the exports section in the module definition file duplicates an ordinal in an export record.


Unknown Optimization

This error message refers to an UNDOCUMENTED optimization feature.


Could not create swapfile

This error message refers to an UNDOCUMENTED optimization feature.


'symbol' conflicts with module 'module' in module 'module'

This indicates an inconsistency in the definition of 'symbol.'

This means that either the linker found one virtual function and one common definition with the same name.


Invalid entry at 'segment:xxxxh'

This error indicates that a necessary entry was missing from the entry table of a Windows executable file.

The application may not work in real mode unless you fix the code and the data.


'symbol' defined in module 'module1' is duplicated in module 'module2'

There is a conflict between two symbols (either public or communal). This usually means that a symbol is defined in two modules.

The linker issues a warning because the symbol exists in more than one object file.

The linker will use the first instance of the symbol that is encountered.


No automatic data segment

No group named DGROUP was found.

Because the Borland initialization files define DGROUP, you will only see this error if you don't link with an initialization file and your program doesn't define DGROUP.

Windows uses DGROUP to find the local data segment.

The DGROUP is required for Windows applications (but not DLLs) unless DATA NONE is specified in the module definition file.


No program starting address defined

This warning means that no module defined the initial starting address of the program.

You probably forgot to link in the initialization module C0x.OBJ.

This warning should not occur when linking a Windows DLL.


Attempt to export non-public symbol 'symbol'

A symbol name was listed in the EXPORTS section of the module definition file, but no symbol of this name was found as public in the modules linked.

If compiling in C++ mode this is usually caused by the name mangling that occurs as a result of C++'s type safe linkage. Inserting the _export keyword in the function prototype and function definition is required for all C++ Windows callback functions.

Language independent causes are a mistake in spelling or case, case sensitive exports, or that a procedure of this name was not defined.

If case sensitive exports are being used, the pascal calling convention used by Windows requires that these symbols consist of all upper case characters.


'filename' ('linenum'): Duplicate internal name in exports

Two export functions listed in the EXPORTS section of the module definition file defined the same internal name.


'filename' ('linenum'): Duplicate internal name in imports

Two import functions listed in the IMPORTS section of the module definition file defined the same internal name.


'filename' ('linenum'): Duplicate external name in exports

Two export functions listed in the EXPORTS section of a module definition file defined the same external name.

For example:

EXPORTS   AnyProc=MyProc1   AnyProc=MyProc2


Debug information in module 'module' will be ignored

Object files compiled with debug information now have a version record. The version of this record is inconsistent with what the linker currently supports.

The linker did not generate debug information for the module in question. Recompile with the current compiler to generate correct debug information.


Stack size is less than 1400h. It has been reset to 1400h

Windows 3.0 requires the stack size of an application to be at least 1400h. If the automatic data segment (ADS) is near 64K, but your stack is less than 1400h, this can cause the ADS to overflow at load time, but not at link time.

For a Windows application, the linker forces the stack size to be at least 1400h.


Group 'group1' overlaps group 'group2'

The linker encountered nested groups.


Possible reference to undefined extern xxxx::i in module 'module'

Static data member has been declared but not defined in application.

This warning occurs by itself (i.e., without an accompanying 'undefined symbol' error) whenever code declares a static data member that is not defined anywhere, and then that symbol is not actually referenced (it is then 'idle' code).


Unable to process debug info, disable TASM /zi option

Debug information is too complex. Disable the TASM /zi option.

If C debug information is required, it should be obtained at the C source level.


No program entry point
No program starting address defined

This message appears if no starting execution point was defined for the application. This usually happens if you forget to link in the startup code.


No stack

This warning is issued if no stack segment is defined in any of the object files or in any of the libraries included in the link. Except for DLLs, this indicates an error.

If a Borland C++ program produces this message, make sure you are using the correct C0x startup object files.


No module definition file specified: using defaults

This warning occurs when you do not specify a .DEF file for the link.

The following defaults are assumed:

CODE	PRELOAD  MOVEABLE  DISCARDABLE

DATA	PRELOAD  MOVEABLE  MULTIPLE (if an .EXE)

DATA	PRELOAD  MOVEABLE  SINGLE (if a .DLL)

HEAPSIZE	4096

STACKSIZE	5120


Alias %m defined in module %s will be ignored
Alias %m defined in module %s is redefined in module module name

A second definition to the alias was encountered, so the second alias is being used.


Segment %s overlaps group %s

Topic not complete in this version of Help.


Extended dictionary not found in library %s: extended dictionaries ignored

When you specify that extended dictionaries be used, all libraries must have extended dictionaries. In this case, a library was encountered that did not have an extended dictionary, thus aborting the link. Use the TLIB /E option to generate an extended dictionary for the library in question.


Invalid extended dictionary in library %s: extended dictionaries ignored

An extended dictionary in the library in question was generated with an outdated version of TLIB. Rebuild the library with a current version of TLIB, specifying that an extended dictionary be created.


Out of memory at library %s: extended dictionaries ignored

The linker has run out of dynamically allocated memory needed during the link process. The total working storage is exhausted.

This error is a catchall for running into a limit on memory usage.

Solutions

You can try reducing size of active RAM disks and/or disk caches.

Close one or more applications to free up memory.


Resident Name Table is greater than 64K

Exports too great for 64K limit. When this error is encountered, break exports up or make some exported by name and some by ordinal number. Another possible fix is to have the Linker transfer the resident name table to the non-resident name table and discard the non-resident name table. (TLINK options /Gr /Gn, IDE options on 16-bit linker page.)


NonResident Name Table is greater than 64K

Industry standards require that nonresident name tables be no larger than 64K in size. If you encounter this message and do not require the nonresident name table to remain intact, you can discard it by linking with the /Gn linker option. If you do require that the nonresident name table remain intact, you must restructure your program, so that names are shorter or explicitly use the resident name table for a portion of the defines.


Self relative fixupp overflowed in module 'module'
Self relative fixup overflowed in module 'module'

This message appears if a self-relative reference (a call or a jump) is made from one physical segment to another. This often happens when employing assembler code, but can occur if you use the segment-naming options in the compiler. If the reference is from one code segment to another, you are safe. If, however, the reference is from a code segment to a data segment, you have probably made a mistake in some assembler code.


Using based linking for DLLs may cause the DLL to malfunction

This warning occurs if you use the /B switch when linking a DLL. In almost every case, this is an error that will prevent the application from running.


Public symbol 'symbol' defined in both module <module1> and <module2>

There is a conflict between two public symbols. This usually means that a symbol is defined in two modules.

An error occurs if both are encountered in the .OBJ file(s), because TLINK doesn't know which is valid.

A warning results if TLINK finds one of the duplicated symbols in a library and finds the other in an .OBJ file; in this case, TLINK uses the one in the .OBJ file.


Import record does not match previous definition

This warning usually occurs if an IMPDEF record appears in an import library at the same time as the import in question is imported from a .DEF file. If the description of the imports differ in internal name or ordinal, this warning appears, and the first definition is used.


Multiple stack segments found. The most recent one will be used.

This warning occurs when two stack segments of different names are defined in the object modules. The startup code defines a stack segment for the application.


No program entry point

This message appears if no starting execution point was defined for the application. This usually happens if you forget to link in the startup code.


Empty LEDATA record in module %s

This warning can happen if the translator emits a data record containing data. If this should happen, report the occurance to the translator vendor. There should be no bad side effects from the record.


Explicit stacks are ignored for PE images

Win32 apps are PE format applications, which do not have explicit stacks. The stack segment will be linked into the image, but it will not be used as the application stack. Instead, the stack size parameter will be used to set the stack size, and the operating system will allocate a stack for the application.


Export '%s' is duplicated

This warning will occur if two different functions with the same name are exported by the use of _export. The linker cannot resolve which definition to export, and will use the first symbol.


Old debug information in module '%s' will be ignored

Debug information in the OBJ is incompatible with this linker, and will be ignored.


Extern '%s' was not qualified with __import in module %s

Win32 apps which make reference to imported symbols need to make indirections to get to the data. For calls, this is handled automatically by the linker. For references to imported DATA, the compiler must generate an indirection, or the application will function incorrectly. The compiler knows to generate the indirection when the symbol is qualified with __import. If the linker sees a segment relative reference to a symbol which is imported, and if the symbol was not qualified with __import, you will get this message.


Debug information enabled, but no debug information found in OBJs

No part of the application was compiled with debug information, but you requested that debug information be turned on in the link.


Directive ignored.
Directive ignored

This error message refers to an UNDOCUMENTED optimization feature. Please contact Borland Technical Support for assistance.


Ffile is not an exe
File is not an exe

This error message refers to an UNDOCUMENTED optimization feature. Please contact Borland Technical Support for assistance.


File is not a New Exe

This error message refers to an UNDOCUMENTED optimization feature. Please contact Borland Technical Support for assistance.


Out of memory

The linker has run out of dynamically allocated memory needed during the link process. This error is a catchall for running into a TLINK limit on memory usage. This usually means that too many modules, externals, groups, or segments have been defined by the object files being linked together. You can try reducing the size of RAM disks and/or disk caches that might be active.


Error reading input file, exe format error?

This error message refers to an UNDOCUMENTED optimization feature. Please contact Borland Technical Support for assistance.


Error writing output file

A DOS error prevents Borland C++ from writing an .OBJ, .EXE, or temporary file. Check the output directory and make sure that this is a valid directory. Also check that there is enough free disk space.


Resource alignment too small.
Resource alignment too small

This error message refers to an UNDOCUMENTED optimization feature. Please contact Borland Technical Support for assistance.


Exe alignment too small

This error message refers to an UNDOCUMENTED optimization feature. Please contact Borland Technical Support for assistance.


'%s' is not a valid library

This error happens when the first record in a library file is not the LIBSTART record.

This can happen when something that is not a library is passed as a library file to the linker, or if the library file was corrupted.


Too many LNAMEs

TLINK32 supports only 255 LNAMEs appearing in ab OBJ file.


Illegal ACBP byte in SEGDEF in module %s

This error is typically a translator error.


Illegal component to GRPDEF in module %s

This error is typically a translator error.


Unsupported option '%s'

An unknown option was supplied on the command-line.


Too many commas on command-line

An invalid entry in the command-line was found.


Malformed command-line

An invalid entry in the command-line was found.


Bad file name '%s'

An invalid file name was passed to the linker.


Unable to open file '%s'

The Linker was unable to open the file.


Failed read from '%s'

The Linker was unable to read from the file.


Failed write to '%s'

The Linker was unable to write to the file.


Terminated by user

The user pressed the Ctrl-Break key.


Too many errors

The Linker got more errors than the maximum number of errors specified by the user.


Bad object file '%s' near file offset %lx

The Linker has found a bad OBJ file. This is usually caused by a translator error.


No output file specified

You did not specify an output file.


Image base address must be a multiple of 0x10000

Based images must be aligned on 64K boundaries.


General error in module '%s'

An unhandled exception occurred in the Linker. Borland International should be informed of the circumstances.


General error

An unhandled exception occurred in the Linker. Borland International should be informed of the circumstances.


Mixed common types in module %s. Cannot mix COMDEFs and VIRDEFs
Mixed common types in module %s. Cannot mix COMDEFs and VIRDEFs.

You cannot mix both COMDEFs and VIRDEFs. Turn off the -Fc switch to stop generating COMDEFs, or turn on the -Vs switch to stop generating VIRDEFs.


Out of memory for block '%s'

The Linker ran out of memory. Try reducing the size of disk caches and/or RAM drives.


Bad LF_POINTER in module '%s'

This is typically caused by bad debug information in the OBJ file. Borland International should be informed.


Target index of FIXUPP is 0 in Module '%s'
Target index of FIXUP is 0 in Module '%s'

This is a translator error.


Bad field list in debug information in module '%s'

This is typically caused by bad debug information in the OBJ file. Borland International should be informed.


Could not load DLL '%s'

The Linker was not able to load the specified DLL. Check to make sure that the DLL is on your path.


Could not get procedure address from DLL '%s'

The Linker was not able to get a procedure from the specified DLL. Check to make sure that you have the correct version of the DLL.


Incorrect version of RLINK32.DLL

The RLINK32.DLL was not the correct version. Check to make sure that you have the correct version of the DLL.


Too many default libraries

The Linker can handle a maximum of 128 default libraries.


16-bit segments not supported in module '%s'

16-bit segments are not supported for Win32 applications. Check to make sure that you have not compiled the application with the 16-bit compiler.


Multiple entry points defined

Multiple entry points were defined for the application. This can happen if you have specified the startup code twice, or if you are making use of assembler code which defines a starting address for the application.


Duplicate ordinal for exports: '%s' (%d) and '%s' (%d)

Two exports share the same ordinal. The Linker cannot resolve which export should get which ordinal.


Attempt to export non-public symbol '%s'

The EXPORTS section in the .DEF file specified the name of a symbol which has no public definition.


Fixupp to zero length segment in module %s
Fixup to zero length segment in module %s

A reference has been made past the end of an image segment. This reference would end up accessing an invalid address, and has been flagged as an error.


No internal name for IMPORT in .DEF file

The .DEF file has a semantic error. The user probably forgot to put the internal name for an import before the module name. For example:

IMPORTS

     _foo.1

Here, _foo was to be the function to be imported, but the proper syntax is:

IMPORTS

     _foo=mydll.1


Relocation Table Overflow

This error only occurs for 32-bit object modules. The file being linked contains more base fixups than the standard DOS relocation table can hold (base afixups are created mostly by calls to far functions).


Relocation offset overflow

This error only occurs for 32-bit object modules and indicates a relocation (segment fixup) offset greater than the DOS limit of 64K.


Relocation item exceeds 1 Meg DOS limit

The DOS executable file format doesn't support relocation items for locations exceeding 1 MB. Although DOS could never load an image this big, DOS extenders can, and thus TLINK supports generating images greater than DOS could load. Even if the image is loaded with a DOS extender, the DOS executable file format is limited to describing relocation items in the first 1MB of the image.


Program entry point may not reside in an overlay

Although almost all of an application can be overlaid, the initial starting address cannot reside in an overlay. This error usually means that an attempt was made to overlay the initialization module C0x.OBJ, for instance, by specifying the /o option before the startup module.


Overlays generated and no overlay manager included

This warning is issued if overlays are created but the symbol _ _OVRTRAP_ _ is not defined in any of the object modules or libraries linked in. The standard overlay library (OVERLAY.LIB) defines this symbol.


Overlays ignored in new executable image

This error occurs if you attempt to link a Windows program with the /o option on. Windows executables can't be overlaid, although, with discardable code segments, you should be able to achieve a similar effect.


32-bit record encountered

An object file that contains 80386 32-bit records was encountered, and the /3 option had not been used.


No stub for fixup at segment:xxxh in module module

This error occurs when the target for a fixup is in an overlay segment, but no stub is found for a target external. This is usually the result of not making public a symbol in an overlay that is referenced from the same module.


Cannot generate COM file: program exceeds 64K

You used the /Tdc or /t option, but the total program size exceeds the .COM file limit.


Cannot generate COM file : invalid initial entry point
Cannot generate COM file: invalid initial entry point address

You used the /Tdc or /t option, but the program starting address is not equal to 100H, which is required with .COM files.


Cannot generate COM file : data below initial CS:IP defined

This error results from trying to generate data or code below the starting address (usually 100) of a .COM file. Be sure that the starting address is set to 100 by using the (ORG 100H) instruction. This error message should not occur for programs written in a high-level language. If it does, ensure that the correct  startup (COx) object module is being linked in.


Cannot generate COM file : segment-relocatable items
Cannot generate COM file : segment-relocatable items present

You used the /Tdc or /t option, but the program contains segment-relative fixups, which are not allowed with .COM files.


Cannot generate COM file : stack segment present

You used the /Tdc or /t option, but the program declares a stack segment, which is not allowed with .COM files.


Debug info switch ignored for COM files

Borland C++ does not include debug information for .COM files. See the description of the /v option.


Illegal local public in %m

This message occurs when the linker sees an LPUBDEF record with an offset of zero for a VIRDEF that resides in an overlay segment. This can happen if you are trying to use structured exception support in an application that uses overlays.


No stub for fixup at %s:%s

This error occurs when the target for a fixup is in an overlay segment, but no stub is found for a target external. This is usually the result of not making public a symbol in an overlay that is referenced from the same module.


Optimizer: Out of Memory

Not enough memory available to perform optimizations.


Optimizer: Error Reading Input File

The hardware error "read failed" occurred.


Optimizer: Error Writing Output File

The disk is either full, or the hardware error "write failed" occurred.


Bad OMF record type 'type' encountered in module 'module'

The librarian encountered a bad Object Module Format (OMF) record while reading through the object module.

Because the librarian has already read and verified the header records in 'module', the object module is probably corrupt. Recreate it.


Could not allocate memory for per module data

The librarian has run out of memory.


Could not create list file 'filename'

The librarian could not create a list file for the library. This could be due to lack of disk space.


Could not write output

The librarian could not write the output file.


Error opening 'filename' (librarian)
Error opening 'filename'

The librarian cannot open the specified file.


Error opening 'filename' for output

The librarian cannot open the specified file for output.


Error renaming 'filename' to 'filename'

This error occurs when the librarian is building a temporary library file and renaming the temporary file to the target library file name.

The error indicates that the target file is read only.


Library too large, restart with library page size 'size'

The library being created could not be built with the current library page size.

You can set the library page size with the Library Page Size option.


Not enough memory for command-line buffer

This error occurs when the librarian runs out of memory.


Object module 'filename' is invalid

The librarian could not understand the header record of the object module being added to the library.

The librarian assumes that it is an invalid module.


Out of memory (librarian)
Out of memory

For any number of reasons, the librarian or the C++ IDE ran out of memory while building the library. For many specific cases a more detailed message is reported.

Close one or more applications.


Out of memory creating extended dictionary

The librarian has run out of memory while creating an extended dictionary for a library.

The library is created but will not have an extended dictionary.


Out of memory reading LE/LIDATA record from object module

The librarian is attempting to read a record of data from the object module, but it cannot get a large enough block of memory.

If the module being added has a large data segment or segments, try adding the module before any other modules.


Out of space allocating per module debug struct

The librarian ran out of memory while allocating space for the debug information associated with a particular object module.

Removing debugging information from some modules being added to the library might resolve the problem.


Output device is full

The output device is full. This error usually means that there is no space left on the disk.


'path' - path is too long

This error occurs when the length of any of the library file or module file's 'path' is greater then 64.


Public 'symbol' in module 'filename' clashes with prior module

A public symbol may only appear once in a library file. A module which is being added to the library contains a public 'symbol' that is already in a module of the library and cannot be added.


Record kind 'num' found, expected theadr or lheadr in module 'filename'

The librarian could not understand the header record of the object module being added to the library and has assumed that it is an invalid module.


Record length 'len' exceeds available buffer in module 'module'

This error occurs when the record length 'len' exceeds the available buffer to load the buffer in module 'module'.

This occurs when the librarian runs out of dynamic memory.


The combinations '+*' or '*+' are not allowed

It is not legal to add and extract an object module from a library in one action.


User break, library aborted

You pressed Cancel while compiling in the IDE. The library was not created.

(This is not an error, just a confirmation.)


Added file 'filename' does not begin correctly, ignored

The librarian has decided that the file being added is not an object module. It will not try to add it to the library.

The library is created anyway.


Bad GCD type in GRPDEF, extended dictionary aborted

The librarian encountered an invalid entry in a group definition (GRPDEF) record while creating an extended dictionary.

The only type of GRPDEF record that the librarian supports is segment index type. Object modules created by products other than Borland tools may create GRPDEF records of other types.

This warning is also generated if the object module is corrupted.


Cannot write GRPDEF list, extended dictionary aborted

The librarian cannot write the extended dictionary to the tail end of the library file. There may not be enough space on the disk.


'filename' couldn't be created, original won't be changed

You tried to extract an object, but the librarian cannot create the object file to extract the module into.

Either the object already exists and is read only, or the disk is full.


'reason' - extended dictionary not created

OR	Library contains COMDEF records - extended dictionary not created

The Librarian could not produce the extended dictionary because of the reason given in the warning message.

If the Library contains COMDEF records message is displayed, an object record being added to a library contains a COMDEF record.

This is not compatible with the extended dictionary option.


'filename' file not found

The IDE creates the library by removing the existing library and rebuilding it. If any of the specified objects do not exist, the library is incomplete and this error is generated.

If the IDE reports that an object does not exist, either the source module has not been compiled or there were errors during compilation. Using either the Project|Make All or Project|Build All commands should resolve the problem or indicate where the errors occurred.


Invalid page size value ignored

The librarian encountered an invalid page size.

The page size must be an integer that is a power of 2.


Memory full listing truncated!

The librarian ran out of memory while creating a library listing file. A list file will be created, but is not complete.


Results are safe in file 'filename'

The librarian has successfully built the library into a temporary file, but cannot rename the file to the desired library name.

The temporary file will not be removed (so that the library can be preserved).


Unknown command line switch 'X' ignored

A forward slash character (/) was encountered on the command line or in a response file without being followed by one of the allowed options.


32-Bit Resource Linker Error Messages and Warnings
Resource Linker Error Messages and Warnings

Bad EXE header format in file

Error creating file

Error creating temporary file in directory

Error deleting file

Error in CURSDIR. Cannot find CURS

Error in FONTDIR. Cannot find FONT

Error in ICONDIR. Cannot find ICON

Error in RES format. Cannot find NAMEDIR resource

Error in RES format

Error opening file

Error positioning file

Error positioning file

Error reading file

Error renaming file

Error sizing file

Error writing file

Error. EXE alignment too small for packing resources too

Error. Expecting RES file, not EXE. File: <filename>

Error. Missing Name resource. RES not for Windows 3

FONTDIR resource too big to link

NAMEDIR resource too big to link

Not a Windows format EXE file

Reporting error.

Resource file is 32-bit format. Please recompile.

Too many files to open

Too many resources to handle

Unsupported EXE RC version

Windows version is set to Win32, but target type is Win16.


Internal software error!

The resource linker encountered unexpected data. Restart the resource link. If the error persists, contact Borland Technical Support.


Out of memory!

Not enough memory is available for compiling a particular file. In this case, shut down any other concurrent applications. You may also try to re-configure your machine for more available memory, or break up the source file being compiled into smaller separate components. You can also compile the file on a system with more available RAM.


Bad EXE header format in file
Bad EXE header format in file.

The executable file contained invalid information in its header. The file might not be a valid executable or might contain corrupted data.


Bad EXE segment table in file
Bad EXE segment table in file.

The executable file contained invalid information in its segment table. The file might not be a valid executable or might contain corrupted data.


Error in packing preload area. Turn off preload packing.

An error occurred while the resource linker was trying to optimize how resources and segments are arranged in the executable file. (This error only occurs for 16-bit resources.)

Solution

To correct this error, turn off the Pack Fastload Area option in the Resources Options.


Error creating file
Error creating file.

An error occurred when the resource linker tried to create a file. This error occurs if the work disk is full or write-protected. It can also occur if the output directory does not exist.

Solutions

If the disk is full, try deleting unneeded files and restarting the resource link.

If the disk is write-protected, direct the output to a writeable disk and restart the resource link.


Error creating temporary file in directory
Error creating temporary file in directory.

An error occurred when the resource linker tried to create a temporary file. This error occurs if the work disk is full or write-protected. It can also occur if the output directory does not exist.

Solutions

If the disk is full, try deleting unneeded files and restarting the resource link.

If the disk is write-protected, direct the output to a writeable disk and restart the resource link.


Error deleting file
Error deleting file.

An error occurred when the resource linker tried to delete a file. This error occurs if the file is marked as read-only or does not exist.

Solutions

If the disk is read-only, change its attributes so that it can be deleted.


Error in CURSDIR. Cannot find CURS
Error in CURSDIR. Cannot find CURS.

An entry was found in the cursor directory that had no corresponding cursor resource. The resource file is probably corrupted.


Error in EXE's resource table format
Error in EXE's resource table format.

There is invalid information in the executable files resource table. The executable file might contain invalid resource information or be corrupt.


Error in FONTDIR. Cannot find FONT
Error in FONTDIR. Cannot find FONT.

An entry was found in the font directory that had no corresponding font resource. The resource file is probably corrupted.


Error in ICONDIR. Cannot find ICON
Error in ICONDIR. Cannot find ICON.

An entry was found in the icon directory that had no corresponding icon resource. The resource file is probably corrupted.


Error in RES format
Error in RES format.

There is invalid information in the binary resource file. The resource file might contain invalid resource information or be corrupt. Try recompiling the resources and restart the resource link.


Error in RES format. Cannot find NAMEDIR resource
Error in RES format. Cannot find NAMEDIR resource.

An entry was found in the name-table that had no corresponding resource. Verify that you have included the appropriate resource in your resource script. Name-tables are not used for Windows version 3.1 or greater.


Error in resource binary length (bad format?)
Error in resource binary length (bad format?).

There is an error in the size of a binary resource. The format of the resource might be invalid or the resource has been corrupted.


Error in STRINGTABLE format
Error in STRINGTABLE format.

The resource linker (RLINK) should not generate this message.


Error making absolute file name
Error making absolute file name.

The resource linker (RLINK) should not generate this message.


Error opening file
Error opening file.

An error occurred when the resource linker tried to open a file. This error occurs if the file does not exist, another process has denied access to the file, the path or filename is incorrect, or there are no more available file handles.


Error positioning file
Error positioning file.

An error occurred trying to seek to a location in a file. This file could be truncated or corrupted. Try verifying the disk integrity using CHKDSK or recompile the resource files and restart the resource link.


Error positioning file
Error positioning file.

The resource linker (RLINK) should not generate this message.


Error reading file
Error reading file.

An error occurred when the resource linker tried to read a file. This error typically occurs when there is a disk error while the file is being read.


Error renaming file
Error renaming file.

An error occurred when the resource linker tried to rename a file. This error occurs if the file is marked as read-only or does not exist or a file already exists having the name that the resource linker is trying to use.

Solutions

If the disk is read-only, change its attributes so that it can be deleted.

If a file having the name already exists you can either delete that file or choose another name.


Error sizing file
Error sizing file.

A disk error occurred when trying to determine the file size.


Error writing file
Error writing file.

An error occurred when the resource linker tried to write to a file. This error occurs if the work disk is full or write-protected.

Solutions

If the disk is full, try deleting unneeded files and restarting the resource link.

If the disk is write-protected, direct the output to a writeable disk and restart the resource link.


Error. EXE alignment too small for packing resources too
Error. EXE alignment too small for packing resources too.

You have pre-packing turned on and the resources will not fit with the current image alignment. Try increasing the alignment, re-link, and restart the resource link.


Error. Missing Name resource. RES not for Windows 3
Error. Missing NAME resource. RES not for Windows 3.

The binary resource file is missing the NAME resource. The resource file is probably not a Windows 3 resource file.


FONTDIR resource too big to link
FONTDIR resource too big to link.

The directory of fonts table size has been exceeded. Try splitting your fonts into multiple FON files.


NAMEDIR resource too big to link
NAMEDIR resource too big to link.

The name-table maximum size has been exceeded. Name-table entries are not used in Windows 3.1 or later.


Not a Windows format EXE file
Not a Windows format EXE file.

The executable file you tried to bind resources to is not a valid Windows or Win32 executable file.


Program execution arrived at yet-to-be-written code
Program execution arrived at yet-to-be-written code.

The resource linker (RLINK) should not generate this message.


Resultant EXE size too big
Resultant EXE size too big.

The resource linker (RLINK) should not generate this message.


Too many files to open
Too many files to open.

You have exceeded the resource linkers limit on files. Try combining some of your individual resource files into a single resource.


Too many resources to handle
Too many resources to handle.

You have too many resources for the resource linker to handle. Try reducing the total number of resources you are trying to link.


Too many STRINGTABLEs to link
Too many STRINGTABLEs to link.

The resource linker (RLINK) should not generate this message.

You have too many string tables for the resource linker to handle. Try reducing the total number of string tables in your resource.


Unsupported EXE RC version
Unsupported EXE RC version.

The executable you are attempting to link the resources to already has resources attached. The version number of these resources is not recognized by this resource linker. Try removing the resources or relinking.


Resource file is 32-bit format. Please recompile.
32-bit format in resource file. Please recompile.

The compiled resource (.RES) file you are trying to use with your application contains 32-bit resources, but the target type of your application is for 16-bit Windows. Recompile the resource file for Windows 3.1 or change the target type for your application to Win32.


Reporting error.

The resource linker encountered a problem while trying to report an error.


Error. Expecting RES file, not EXE. File: <filename>

The resource linker was.expecting a compiled resource (.RES) file, but found an executable (.EXE) instead. Verify that you have the correct node and file types specified.


Windows version is set to Win32, but target type is Win16.

The version for your resources is set to Win32, but the target type for your project is for a 16-bit Windows application. 16-bit Windows applications cannot use 32-bit resources.

Either change the version for your resources to Windows 3.1 or change the target type for your application to Win32.