Preface

WorkShop: Command-Line Utilities provides the reference information needed to perform Sun WorkShop^TM functions from the command line.

Who Should Use This Book

This book is designed to assist users who choose to perform WorkShop functions from the command line instead of using WorkShop's graphical user interface (GUI).

The audience for this book includes programmers, developers, and engineers who need, or prefer, to work directly from a command line.

Before You Read This Book

For an overview and details about using the WorkShop suite of applications, see WorkShop: Getting Started.

If you are building, analyzing, debugging, or optimizing distributed, multithreaded, and multiprocessor applications and programs, you will need the information in WorkShop: Beyond the Basics.

DMake users will find basic information about the Sun WorkShop^TM TeamWare suite of applications in Sun WorkShop TeamWare: User's Guide and Sun WorkShop TeamWare: Solutions Guide.

How This Book Is Organized

Part 1, "Using dbx," explains the commands and topics you need to debug programs from the command line.

Part 2, "Using Multithreaded Tools," explains how to request and use a loop report and explains the LockLint commands and utilities.

Part 3, "Using Source Browsing," explains how to use sbquery, sbinit, and sbtags to browse sources from the command line.

Part 4, "Using Merging," explains how to use Merging to compare text files.

How to Get Help

This release of WorkShop includes a new documentation delivery system as well as online manuals and video demonstrations. To find out more, you can start in any of the following places:

Apart from this manual, you can also access help online in two modes: from the WorkShop help menu, and in the dbx Commands window.

From the main Workshop window, choose Help Help Contents.
In the Dbx Commands window, at the dbx prompt:
Online Help - A new help system containing extensive task-oriented, context-sensitive help. To access the help, choose Help Help Contents. Help menus are available from all WorkShop windows.
WorkShop Documentation - A complete set of online manuals, which make up the complete documentation set for WorkShop and are available using AnswerBook^TM or any HTML browser. To access the online manuals, choose Help WorkShop Manuals from any WorkShop window, or type answerbook &.
Video Demonstrations - These demos provide a general overview of WorkShop and describe how to use WorkShop to build targets or debug programs. To access them, choose Help Demos from the WorkShop main window.
Release Notes - The Release Notes contain last-minute information about WorkShop and specific information about software limitations and bugs. To access the Release Notes, choose Help Release Notes.
Manual Pages - The man pages provide information about the command-line utilities of the SunOS operating system. Each tool has at least one man page. To access the man pages, type man utility_name.

How to Access the AnswerBook Documentation

To access the AnswerBook online documentation for WorkShop, you must run a script to set up your environment.

At a command prompt, type:
% workshop-answerbooks

`%` `workshop-answerbooks`

The script sets the AB_CARDCATALOG environment variable and runs /usr/openwin/bin/answerbook. The AnswerBook Navigator opens and displays the available AnswerBook documents.

Sun WorkShop Documentation

Available with all WorkShop products.


WorkShop Roadmap	Provides a map to installation and use of your version of WorkShop. Includes a complete list of the documentation included with your WorkShop.
WorkShop Installation and Licensing Guide	Provides instructions about product licensing and installation of WorkShop products. Provides instructions for local or remote installation for single independent license servers, multiple independent license servers, and redundant license servers.
WorkShop: Getting Started	Provides the information you need to use the basic WorkShop features.
WorkShop: Beyond the Basics	Contains information about the advanced programming, debugging, browsing, and visualization applications in the WorkShop product suite, including: DMake, LoopTool, Thread Analyzer, and WorkShop Visual.
WorkShop: Command-Line Utilities	Contains instructions for command-line use of `dbx`, multithreaded tools, the source browser, and merging.
WorkShop Online Help	Contains extensive task-oriented information for the tools included with WorkShop.
WorkShop Video Demonstrations	Consists of three video demonstrations providing information about WorkShop building and debugging as well as general product information.
Release Notes	Contains last-minute information regarding WorkShop, including any software incompatibilities and limitations. To access the Release Notes, choose Help Release Notes.
Manual Pages	Provide information about the WorkShop command-line utilities.

Sun WorkShop TeamWare Documentation

Available only with Sun Performance WorkShop Fortran and Sun Visual WorkShop C++.


Sun WorkShop TeamWare: User's Guide	Describes how to use all the tools in the TeamWare toolset, for both the command-line interface and the graphical user interface.
Sun WorkShop TeamWare: Solutions Guide	Provides an in-depth case study and eight scenario-based topics to help users take full advantage of TeamWare's features.
Sun WorkShop TeamWare Online Help	Provides succinct task-oriented information to help you become familiar with the application. Help volume includes video demonstrations.
Manual Pages	Provide information about the TeamWare commands and utilities.

Sun Visual WorkShop C++ Documentation

Available only with Sun Visual WorkShop C++.


WorkShop documentation	Visual WorkShop C++ contains the entire WorkShop and TeamWare documentation sets.
C++ User's Guide	Describes how to use the Sun Compiler C++ to write programs in C++. It covers the C++ compiler options, programs, templates, exception handling, and more. It is intended for the experienced C++ programmer.
C++ Library Reference	Describes how to use the complex, coroutine, and iostream libraries, and lists the manual pages for these libraries.
Tools.h++ Class Library Reference	Describes how to use the Tools.h++ class library, and a set of C++ classes that can simplify programming while maintaining efficiency.
C++ Quick Reference Card	Provides concise descriptions of the C++ compiler flags.
C User's Guide	Describes how to use the Sun Compiler ANSI C to write programs in C. It covers the C compiler options, the pragmas, the lint tool, the cscope tool, and more. Intended for the experienced C programmer.
WorkShop: Visual User's Guide	Explains how to use Visual, an interactive tool for building graphical user interfaces (GUIs) using the widgets of the standard OSF/Motif toolkit or Microsoft Foundation Class. It includes a tutorial as well as reference information for the more advanced user.
Visual Quick Reference Card	Contains menu shortcuts and icon explanations for Visual.
Numerical Computation Guide	Describes the floating-point software and hardware for the SPARC^TM, Intel, and PowerPC architectures. It also contains a tutorial on floating-point arithmetic.
Incremental Link Editor (ild)	Describes how to use `ild` as an incremental linker to replace `ld` for linking programs. `ild` allows you to complete the development sequence more quickly than a standard linker.
Performance Profiling Tools	Describes the `prof` (1), `gprof` (1), and `tcov`(1) utilities.
Manual Pages	Provide information about the command-line commands and utilities included with the Visual WorkShop C++.

Sun Performance WorkShop Fortran Documentation

Available only with Sun Performance WorkShop Fortran.


WorkShop documentation	Contains the entire WorkShop and TeamWare documentation set.
Fortran User's Guide	Describes how to use the Sun Compiler Fortran 77 4.0 and the Sun Compiler Fortran 90 1.2, including the compiler command options, debugging and development tools, program profiling and performance tuning, mixing C and Fortran, and making and using libraries. Intended for programmers with knowledge of Fortran.
FORTRAN 77 Language Reference	Describes and defines the Fortran 77 language accepted by the Sun Compiler `f77`. Intended for use by programmers with knowledge of and experience with Fortran.
Fortran Programmer's Guide	Provides the essential information programmers need to develop efficient applications using the Sun Compiler Fortran 77 4.0 and the Sun Compiler Fortran 90 1.2. Includes information on input/output, program development, use and creation of software libraries, program analysis and debugging, numerical accuracy, porting, performance, optimization, parallelization, and the C/Fortran interface.
Fortran Library Reference	Describes the language and routines of the Fortran compilers.
Fortran 90 Browser	Describes how to use the Sun Fortran 90 Browser, one of the development tools in the `f90` package, to view Fortran 90 source code. Intended for programmers with knowledge of Fortran 90.
Fortran Quick Reference Card	Lists the Sun Compiler `f77` 4.0's command-line options with brief descriptions.
Numerical Computation Guide	Describes the floating-point software and hardware for the SPARC, Intel, and PowerPC architectures. It also contains a tutorial on floating-point arithmetic.
Incremental Link Editor (ild)	Describes how to use `ild` as an incremental linker to replace `ld` for linking programs. `ild` allows you to complete the development sequence more quickly than with a standard linker.
Performance Profiling Tools	Describes the `prof` (1), `gprof` (1), and `tcov`(1) utilities.
Manual Pages	Provide information about the Fortran command-line commands and utilities.

Sun WorkShop Professional Pascal Documentation

Available only with Sun WorkShop Professional Pascal.


WorkShop documentation	Contains the entire WorkShop documentation set.
Pascal User's Guide	Describes how to begin writing and compiling Pascal programs on Solaris. Pascal is a derivative of the Berkeley Pascal system distributed with UNIX® 4.2 BSD. It complies with FIPS PUB 109 ANSI/IEEE 770 X3.97-1983 and BS6192/ISO7185 at both level 0 and level 1, and it includes many extensions to the standard.
Pascal Language Reference	Provides reference material for the Sun Compiler Pascal 4.0, an implementation of the Pascal language that includes all the standard language elements and many extensions. Pascal 4.0 contains a compiler switch, `-xl`, to provide compatibility with Apollo DOMAIN Pascal to ease the task of porting your Apollo Pascal applications to workstations.
Pascal Quick Reference Card	Lists all of the Sun Compiler Pascal 4.0 options with a brief, one-line description of each option.
Numerical Computation Guide	Describes the floating-point software and hardware for the SPARC, Intel, and PowerPC architectures. It also contains a tutorial on floating-point arithmetic.
Incremental Link Editor (ild)	Describes how to use `ild` as an incremental linker to replace `ld` for linking programs. `ild` allows you to complete the development sequence more quickly than with a standard linker.
Performance Profiling Tools	Describes the `prof` (1), `gprof` (1), and `tcov`(1) utilities.
Manual Pages	Provide information about the command-line commands and utilities.

Sun WorkShop Professional C Documentation

Available only with Sun WorkShop Professional C.


WorkShop documentation	Contains the entire WorkShop documentation set.
C User's Guide	Describes how to use the Sun Compiler ANSI C to write programs in C. It covers the C compiler options, the pragmas, the lint tool, the cscope tool, and more. Intended for the experienced C programmer.
C Quick Reference Card	Describes the C compiler options in a concise and easy-to-read format.
Numerical Computation Guide	Describes the floating-point software and hardware for the SPARC, Intel, and PowerPC architectures. It also contains a tutorial on floating-point arithmetic.
Incremental Link Editor (ild)	Describes how to use `ild` as an incremental linker to replace `ld` for linking programs. `ild` allows you to complete the development sequence more quickly than a standard linker.
Performance Profiling Tools	Describes the `prof` (1), `gprof` (1), and `tcov`(1) utilities.
Manual Pages	Provide information about the command-line commands and utilities.

Ordering Additional Hardcopy Documentation

You can order additional copies of the hard-copy documentation by calling SunExpress at 1-800-USE-SUNX or visiting the SunExpress Web page at:

http://sunexpress.usec.sun.com.

Sun on the World Wide Web

World Wide Web users can view Sun's Developer Products site at the following URL:

http://www.sun.com/developer-products/index.html

This area is updated regularly and contains helpful information, including current release and configuration tables, special programs, and success stories.

Sun Education Classes

Sun Educational Services offers many classes for programmers who are developing applications. For more information about classes offered, contact Sun Education by telephone or email:

Sun Education Registrar 1-800-422-8020 or (408) 263-9367

training_seats@sun.com (schedule and availability)

edbrochure@sun.com (class description)

Or go to the Sun Educational Services Web site:

http://www.sun.com/sunservice/suned

What Typographic Changes Mean

Table P-1 Typographic Conventions
Typeface or Symbol	Meaning	Example
`AaBbCc123`	The names of commands, files, and directories; on-screen computer output	Edit your`.login` file. Use `ls -a` to list all files. `machine_name% You have mail`.
`AaBbCc123`	What you type, contrasted with on-screen computer output	`machine_name% su` `Password:`
AaBbCc123	Command-line placeholder: replace with a real name or value	To delete a file, type `rm` filename.
AaBbCc123	Book titles, new words or terms, or words to be emphasized	Read Chapter 6 in User's Guide. These are called class options. You must be root to do this.

The following table describes the typographic changes used in this book.Table P-1 Typographic Conventions Typeface or Symbol Meaning Example AaBbCc123 The names of commands, files, and directories; on-screen computer output Edit your.login file. Use ls -a to list all files. machine_name% You have mail. AaBbCc123 What you type, contrasted with on-screen computer output machine_name% su Password: AaBbCc123 Command-line placeholder: replace with a real name or value To delete a file, type rm filename. AaBbCc123 Book titles, new words or terms, or words to be emphasized Read Chapter 6 in User's Guide. These are called class options. You must be root to do this.

Shell Prompts in Command Examples

Shell	Prompt
C shell prompt	`machine_name%`
C shell superuser prompt	`machine_name#`
Bourne shell and Korn shell prompt	`$`
Bourne shell and Korn shell superuser prompt	`#`
Korn shell running `dbx`	(`dbx`)

The following table shows the default system prompt and superuser prompt for the C shell, Bourne shell, and Korn shell, as well as the default prompt when dbx is running in a Korn shell.Shell Prompt C shell prompt machine_name% C shell superuser prompt machine_name# Bourne shell and Korn shell prompt $ Bourne shell and Korn shell superuser prompt # Korn shell running dbx (dbx)

Preface

Who Should Use This Book

Before You Read This Book

How This Book Is Organized

How to Get Help

How to Access the AnswerBook Documentation

Related Books

Sun WorkShop Documentation

Sun WorkShop TeamWare Documentation

Sun Visual WorkShop C++ Documentation

Sun Performance WorkShop Fortran Documentation

Sun WorkShop Professional Pascal Documentation

Sun WorkShop Professional C Documentation

Ordering Additional Hardcopy Documentation

Sun on the World Wide Web

Sun Education Classes

What Typographic Changes Mean

Table P-1 Typographic Conventions

Shell Prompts in Command Examples