About This Manual

This manual describes the programming environment of the Digital UNIX® operating system, with an emphasis on the C programming language. The availability of other programming languages on any system is determined by the choices made at the time the system was configured or modified.

Audience

This manual addresses all programmers who use the Digital UNIX operating system to create or maintain programs in any supported language.

New and Changed Features

The following major changes and additions have been made to this manual for the Version 4.0 release of Digital UNIX:

Chapter 2 - Removed information on pragmas from this chapter, creating a new Chapter 3 on pragmas.
Chapter 7 - Created a new chapter documenting Third Degree, an Atom tool.
Chapter 8 - Modified to include information on Atom tools used in profiling.
Chapter 9 - Created a new chapter on using and developing Atom tools.
Chapter 10 - Merged the contents of Chapter 4 from System Tuning and Performance Management into this chapter. Also, information on the uopt global optimizer (used with the -oldc version of the C compiler) has been moved to Appendix D.
Chapter 12 - Modified to include information on TIS (Thread Independent Services) and the changes to libc functions to make them thread-safe.

Organization

This manual contains twelve chapters and four appendixes.

Chapter 1 Describes the phases of program development and which Digital UNIX programming tools to use during those phases.

Chapter 2 Describes the tools that make up the compiler system and how to use them. These tools include compiler commands, preprocessors, compilation options, multilanguage programs, and the archiver.

Chapter 3 Describes the implementation-specific pragmas that are supported on the C compiler using the -newc and -oldc flags.

Chapter 4 Describes the use, creation, and maintenance of shared libraries and discusses how symbols are resolved.

Chapter 5 Describes how to use the dbx debugger. Includes information about the dbx commands, working with the monitor, setting breakpoints, and debuggging machine code.

Chapter 6 Describes how to use the lint command to produce clean code.

Chapter 7 Describes how to use the Third Degree Atom tool to perform memory access checks and leak detection on an application program.

Chapter 8 Describes how to use the prof and gprof tools to profile your code, enabling you to find which portions of code are consuming the most execution time.

Chapter 9 Discusses how to use prepackaged Atom tools to instrument an application program for various purposes, such as to obtain profiling data or to perform cache-use analysis. It also describes how you can design and create custom Atom tools.

Chapter 10 Describes how to optimize your code using the optimizer and the post-link optimizer.

Chapter 11 Describes how to use the features of the DEC C compiler for Digital UNIX to write a structured exception handler or a termination handler.

Chapter 12 Describes how to develop multithreaded programs.

Appendix A Describes how to use 32-bit pointers on 64-bit Digital UNIX systems.

Appendix B Describes how to achieve source code compatibility for C language programs in the System V habitat.

Appendix C Describes how to write dynamically configurable kernel subsystems.

Appendix D Describes the global optimizer (uopt) used by the DEC OSF/1 C compiler (-oldc).

Related Documents

In addition to this manual, the following manuals contain information pertaining to program development:

Programming: General

Calling Standard for Alpha Systems

Assembly Language Programmer's Guide

Programming Support Tools

Network Programmer's Guide

Digital Portable Mathematics Library

Writing Software for the International Market

Kernel Debugging

Ladebug Debugger Manual

Programming: Compatibility, Migration, and Standards

ULTRIX to Digital UNIX Migration Guide

VAX System V to Digital UNIX Migration Guide

System V Compatibility User's Guide

POSIX Conformance Document

XPG3 Questionnaire

Programming: Realtime

Guide to Realtime Programming

Programming: Streams

Programmer's Guide: STREAMS

Programming: Multithreaded Applications

Guide to DECthreads

General User Information

Release Notes

Documentation Overview

The printed version of the Digital UNIX documentation set is color coded to help specific audiences quickly find the books that meet their needs. (You can order the printed documentation from Digital.) This color coding is reinforced with the use of an icon on the spines of books. The following list describes this convention:

Audience Icon Color Code

General users G Blue

System and network administrators S Red

Programmers P Purple

Device driver writers D Orange

Reference page users R Green

Some books in the documentation set help meet the needs of several audiences. For example, the information in some system books is also used by programmers. Keep this in mind when searching for information on specific topics.

The Documentation Overview, Glossary, and Master Index provides information on all of the books in the Digital UNIX documentation set.

Reader's Comments

Digital welcomes any comments and suggestions you have on this and other Digital UNIX manuals.

You can send your comments in the following ways:

Fax: 603-881-0120 Attn: UEG Publications, ZK03-3/Y32
Internet electronic mail: readers_comment@zk3.dec.com
A Reader's Comment form is located on your system in the following location:
```
/usr/doc/readers_comment.txt
```
Mail:
Digital Equipment Corporation
UEG Publications Manager
ZK03-3/Y32
110 Spit Brook Road
Nashua, NH 03062-9987
A Reader's Comment form is located in the back of each printed manual. The form is postage paid if you mail it in the United States.

Please include the following information along with your comments:

The full title of the book and the order number. (The order number is printed on the title page of this book and on its back cover.)
The section numbers and page numbers of the information on which you are commenting.
The version of Digital UNIX that you are using.
If known, the type of processor that is running the Digital UNIX software.

The Digital UNIX Publications group cannot respond to system problems or technical support inquiries. Please address technical questions to your local system vendor or to the appropriate Digital technical support office. Information provided with the software media explains how to send problem reports to Digital.

Conventions

%
$ A percent sign represents the C shell system prompt. A dollar sign represents the system prompt for the Bourne and Korn shells.

# A number sign represents the superuser prompt.

(dbx) In examples, this symbol represents the dbx debugger's prompt.

% cat Boldface type in interactive examples indicates typed user input.

file Italic (slanted) type indicates variable values, placeholders, and function argument names.

[ | ]
{ | } In syntax definitions, brackets indicate items that are optional and braces indicate items that are required. Vertical bars separating items inside brackets or braces indicate that you choose one item from among those listed.

. . . In syntax definitions, a horizontal ellipsis indicates that the preceding item can be repeated one or more times.

cat(1) A cross-reference to a reference page includes the appropriate section number in parentheses. For example, cat(1) indicates that you can find information on the cat command in Section 1 of the reference pages.

[Return] In an example, a key name enclosed in a box indicates that you press that key.

Ctrl/x This symbol indicates that you hold down the first named key while pressing the key or mouse button that follows the slash. In examples, this key combination is enclosed in a box (for example, [Ctrl/C]).

Chapter 1	Describes the phases of program development and which Digital UNIX programming tools to use during those phases.
Chapter 2	Describes the tools that make up the compiler system and how to use them. These tools include compiler commands, preprocessors, compilation options, multilanguage programs, and the archiver.
Chapter 3	Describes the implementation-specific pragmas that are supported on the C compiler using the `-newc` and `-oldc` flags.
Chapter 4	Describes the use, creation, and maintenance of shared libraries and discusses how symbols are resolved.
Chapter 5	Describes how to use the `dbx` debugger. Includes information about the `dbx` commands, working with the monitor, setting breakpoints, and debuggging machine code.
Chapter 6	Describes how to use the `lint` command to produce clean code.
Chapter 7	Describes how to use the Third Degree Atom tool to perform memory access checks and leak detection on an application program.
Chapter 8	Describes how to use the `prof` and `gprof` tools to profile your code, enabling you to find which portions of code are consuming the most execution time.
Chapter 9	Discusses how to use prepackaged Atom tools to instrument an application program for various purposes, such as to obtain profiling data or to perform cache-use analysis. It also describes how you can design and create custom Atom tools.
Chapter 10	Describes how to optimize your code using the optimizer and the post-link optimizer.
Chapter 11	Describes how to use the features of the DEC C compiler for Digital UNIX to write a structured exception handler or a termination handler.
Chapter 12	Describes how to develop multithreaded programs.
Appendix A	Describes how to use 32-bit pointers on 64-bit Digital UNIX systems.
Appendix B	Describes how to achieve source code compatibility for C language programs in the System V habitat.
Appendix C	Describes how to write dynamically configurable kernel subsystems.
Appendix D	Describes the global optimizer (`uopt`) used by the DEC OSF/1 C compiler (`-oldc`).

Audience	Icon	Color Code
General users	G	Blue
System and network administrators	S	Red
Programmers	P	Purple
Device driver writers	D	Orange
Reference page users	R	Green

`%` `$`	A percent sign represents the C shell system prompt. A dollar sign represents the system prompt for the Bourne and Korn shells.
`#`	A number sign represents the superuser prompt.
(`dbx`)	In examples, this symbol represents the `dbx` debugger's prompt.
`%` `cat`	Boldface type in interactive examples indicates typed user input.
`file`	Italic (slanted) type indicates variable values, placeholders, and function argument names.
[ \| ] { \| }	In syntax definitions, brackets indicate items that are optional and braces indicate items that are required. Vertical bars separating items inside brackets or braces indicate that you choose one item from among those listed.
. . .	In syntax definitions, a horizontal ellipsis indicates that the preceding item can be repeated one or more times.
`cat`(1)	A cross-reference to a reference page includes the appropriate section number in parentheses. For example, `cat`(1) indicates that you can find information on the `cat` command in Section 1 of the reference pages.
`[Return]`	In an example, a key name enclosed in a box indicates that you press that key.
Ctrl/x	This symbol indicates that you hold down the first named key while pressing the key or mouse button that follows the slash. In examples, this key combination is enclosed in a box (for example, `[Ctrl/C]`).