Bull AIX 5.3 - General Programming Guide

Bull

AIX 5L General Programming Concepts

Writing and Debugging Programs

AIX

86 A2 65EM 02

ORDER REFERENCE

Bull

AIX 5L General Programming Concepts

Writing and Debugging Programs

AIX

Software

October 2005

BULL CEDOC

357 AVENUE PATTON

B.P.20845

49008 ANGERS CEDEX 01

FRANCE

86 A2 65EM 02

ORDER REFERENCE

The following copyright notice protects this book under the Copyright laws of the United States of America

and other countries which prohibit such actions as, but not limited to, copying, distributing, modifying, and

making derivative works.

Copyright

Bull S.A. 1992, 2005

Printed in France

Suggestions and criticisms concerning the form, content, and presentation of

this book are invited. A form is provided at the end of this book for this purpose.

To order additional copies of this book or other Bull Technical Publications, you

are invited to use the Ordering Form also provided at the end of this book.

Trademarks and Acknowledgements

We acknowledge the right of proprietors of trademarks mentioned in this book.

AIX

R

is a registered trademark of International Business Machines Corporation, and is being used under

licence.

UNIX is a registered trademark in the United States of America and other countries licensed exclusively through

the Open Group.

Linux is a registered trademark of Linus Torvalds.

The information in this document is subject to change without notice. Bull will not be liable for errors contained

herein, or for incidental or consequential damages in connection with the use of this material.

Contents

About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xi

Highlighting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xi

Case-Sensitivity in AIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xi

ISO 9000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xi

Related Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xi

Chapter 1. Tools and Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

Entering a Program into the System . . . . . . . . . . . . . . . . . . . . . . . . . .1

Checking a Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

Compiling and Linking a Program . . . . . . . . . . . . . . . . . . . . . . . . . . .1

Subroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2

Shell Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2

Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3

Chapter 2. Curses Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5

Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5

Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5

Structure of a Curses Program . . . . . . . . . . . . . . . . . . . . . . . . . . . .6

Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6

Initializing Curses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6

Windows in the Curses Environment . . . . . . . . . . . . . . . . . . . . . . . . . .7

Manipulating Window Data with Curses . . . . . . . . . . . . . . . . . . . . . . . . .8

Controlling the Cursor with Curses . . . . . . . . . . . . . . . . . . . . . . . . . .11

Manipulating Characters with Curses . . . . . . . . . . . . . . . . . . . . . . . . .11

Understanding Terminals with Curses . . . . . . . . . . . . . . . . . . . . . . . . .18

Working with Color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24

Manipulating Video Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . .24

Manipulating Soft Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26

Curses Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27

List of Additional Curses Subroutines . . . . . . . . . . . . . . . . . . . . . . . . .27

Chapter 3. Debugging Programs . . . . . . . . . . . . . . . . . . . . . . . . . .29

adb Debug Program Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . .29

Getting Started with the adb Debug Program . . . . . . . . . . . . . . . . . . . . . .29

Controlling Program Execution . . . . . . . . . . . . . . . . . . . . . . . . . . .31

Using adb Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35

Customizing the adb Debug Program . . . . . . . . . . . . . . . . . . . . . . . . .37

Computing Numbers and Displaying Text . . . . . . . . . . . . . . . . . . . . . . . .40

Displaying and Manipulating the Source File with the adb Program . . . . . . . . . . . . . .41

adb Debug Program Reference Information . . . . . . . . . . . . . . . . . . . . . . .48

Example adb Program: adbsamp . . . . . . . . . . . . . . . . . . . . . . . . . . .52

Example adb Program: adbsamp2 . . . . . . . . . . . . . . . . . . . . . . . . . .53

Example adb Program: adbsamp3 . . . . . . . . . . . . . . . . . . . . . . . . . .53

Example of Directory and i-node Dumps in adb Debugging . . . . . . . . . . . . . . . . .54

Example of Data Formatting in adb Debugging . . . . . . . . . . . . . . . . . . . . .56

Example of Tracing Multiple Functions in adb Debugging . . . . . . . . . . . . . . . . . .58

dbx Symbolic Debug Program Overview . . . . . . . . . . . . . . . . . . . . . . . .61

Using the dbx Debug Program . . . . . . . . . . . . . . . . . . . . . . . . . . .61

Displaying and Manipulating the Source File with the dbx debug Program . . . . . . . . . . . .65

Examining Program Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69

Debugging at the Machine Level with dbx . . . . . . . . . . . . . . . . . . . . . . .74

Customizing the dbx Debugging Environment . . . . . . . . . . . . . . . . . . . . . .78

Developing for the dbx Plug-in Framework . . . . . . . . . . . . . . . . . . . . . . .80

List of dbx Subcommands . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96

Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98

Chapter 4. Error-Logging Overview . . . . . . . . . . . . . . . . . . . . . . . . .99

Error-Logging Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99

Managing Error Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Error Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Error Logging Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Error Logging and Alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114

Error Logging Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114

Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115

Chapter 5. File Systems and Logical Volumes . . . . . . . . . . . . . . . . . . . .117

File Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117

Working With JFS Directories . . . . . . . . . . . . . . . . . . . . . . . . . . .119

Working with JFS2 Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Working with JFS i-nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Working with JFS2 i-nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Allocating JFS File Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Allocating JFS2 File Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

JFS File System Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

JFS2 File System Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Writing Programs That Access Large Files . . . . . . . . . . . . . . . . . . . . . . . 133

Linking for Programmers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

Using File Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Creating and Removing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Working with File I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

File Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

File Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Creating New File System Types . . . . . . . . . . . . . . . . . . . . . . . . . . 155

Logical Volume Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Chapter 6. Floating-Point Exceptions . . . . . . . . . . . . . . . . . . . . . . . . 161

Floating-Point Exception Subroutines . . . . . . . . . . . . . . . . . . . . . . . . . 161

Floating-Point Trap Handler Operation . . . . . . . . . . . . . . . . . . . . . . . . 162

Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Chapter 7. Input and Output Handling . . . . . . . . . . . . . . . . . . . . . . . 171

Low-Level I/O Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

Stream I/O Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Terminal I/O Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Asynchronous I/O Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

Chapter 8. Large Program Support . . . . . . . . . . . . . . . . . . . . . . . . . 175

Understanding the Large Address-Space Model . . . . . . . . . . . . . . . . . . . . . 175

Understanding the Very Large Address-Space Model . . . . . . . . . . . . . . . . . . . 176

Enabling the Large and Very Large Address-Space Models . . . . . . . . . . . . . . . . 176

Executing Programs with Large Data Areas . . . . . . . . . . . . . . . . . . . . . . 177

Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Chapter 9. Programming on Multiprocessor Systems . . . . . . . . . . . . . . . . . 179

Identifying Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

Controlling Processor Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

Using Dynamic Processor Deallocation . . . . . . . . . . . . . . . . . . . . . . . . 180

Dynamic Memory Guarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

iv General Programming Concepts: Writing and Debugging Programs

Creating Locking Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Chapter 10. Multi-Threaded Programming . . . . . . . . . . . . . . . . . . . . . . 189

Understanding Threads and Processes . . . . . . . . . . . . . . . . . . . . . . . . 189

Thread-Safe and Threaded Libraries in AIX . . . . . . . . . . . . . . . . . . . . . . 194

Creating Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Terminating Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

Synchronization Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

Using Mutexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

Using Condition Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

Using Read-Write Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Joining Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

Scheduling Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

Contention Scope and Concurrency Level . . . . . . . . . . . . . . . . . . . . . . . 229

Synchronization Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

One-Time Initializations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

Thread-Specific Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

Creating Complex Synchronization Objects . . . . . . . . . . . . . . . . . . . . . . 237

Signal Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

Process Duplication and Termination . . . . . . . . . . . . . . . . . . . . . . . . . 244

Threads Library Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

Writing Reentrant and Thread-Safe Code . . . . . . . . . . . . . . . . . . . . . . . 255

Developing Multi-Threaded Programs . . . . . . . . . . . . . . . . . . . . . . . . 260

Developing Multi-Threaded Programs to Examine and Modify pthread Library Objects . . . . . . . 263

Developing Multi-Threaded Program Debuggers . . . . . . . . . . . . . . . . . . . . . 267

Benefits of Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

Chapter 11. lex and yacc Program Information . . . . . . . . . . . . . . . . . . . . 277

Generating a Lexical Analyzer with the lex Command . . . . . . . . . . . . . . . . . . . 277

Using the lex Program with the yacc Program . . . . . . . . . . . . . . . . . . . . . 278

Extended Regular Expressions in the lex Command . . . . . . . . . . . . . . . . . . . 279

Passing Code to the Generated lex Program . . . . . . . . . . . . . . . . . . . . . . 282

Defining lex Substitution Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

lex Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

Actions Taken by the Lexical Analyzer . . . . . . . . . . . . . . . . . . . . . . . . 284

lex Program Start Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

Creating a Parser with the yacc Program . . . . . . . . . . . . . . . . . . . . . . . 288

The yacc Grammar File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

Using the yacc Grammar File . . . . . . . . . . . . . . . . . . . . . . . . . . . 290

yacc Grammar File Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . 292

yacc Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

yacc Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

yacc Program Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

Parser Operation Generated by the yacc Command . . . . . . . . . . . . . . . . . . . 298

Using Ambiguous Rules in the yacc Program . . . . . . . . . . . . . . . . . . . . . . 300

Turning on Debug Mode for a Parser Generated by the yacc Command . . . . . . . . . . . . 301

Example Program for the lex and yacc Programs . . . . . . . . . . . . . . . . . . . . 301

Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

Chapter 12. make Command . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

Creating a Description File . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

Internal Rules for the make Program . . . . . . . . . . . . . . . . . . . . . . . . . 310

Defining and Using Macros in a Description File . . . . . . . . . . . . . . . . . . . . . 314

Creating a Target File with the Make Command . . . . . . . . . . . . . . . . . . . . . 318

Contents v

Using the make Command with Source Code Control System (SCCS) Files . . . . . . . . . . 318

Using the make Command with Non-Source Code Control System (SCCS) Files . . . . . . . . 320

Understanding How the make Command Uses Environment Variables . . . . . . . . . . . . 320

Using the make Command in Parallel Run Mode . . . . . . . . . . . . . . . . . . . . 321

Example of a Description File . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

Chapter 13. m4 Macro Processor Overview . . . . . . . . . . . . . . . . . . . . . 325

Using the m4 Macro Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

Creating a User-Defined Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

Using a Predefined m4 Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

Additional m4 Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

Chapter 14. Object Data Manager (ODM) . . . . . . . . . . . . . . . . . . . . . . 335

ODM Object Classes and Objects . . . . . . . . . . . . . . . . . . . . . . . . . . 335

ODM Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

ODM Object Searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

ODM Commands and Subroutines . . . . . . . . . . . . . . . . . . . . . . . . . . 345

ODM Example Code and Output . . . . . . . . . . . . . . . . . . . . . . . . . . 346

Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349

Chapter 15. Simultaneous Multi-Threading . . . . . . . . . . . . . . . . . . . . . . 351

Benefitting from Simultaneous Multi-Threading . . . . . . . . . . . . . . . . . . . . . 351

Setting the Mode With the smtctl Command . . . . . . . . . . . . . . . . . . . . . . 351

Hardware Management Console Configuration for Simultaneous Multi-Threading . . . . . . . . 352

Micro-Partitioning and Simultaneous Multi-Threading . . . . . . . . . . . . . . . . . . . 352

Hardware Thread Priorities . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

Chapter 16. Dynamic logical partitioning . . . . . . . . . . . . . . . . . . . . . . 355

DLPAR-Safe and -Aware Programs . . . . . . . . . . . . . . . . . . . . . . . . . 355

Processor Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

Integrating the DLPAR Operation into the Application . . . . . . . . . . . . . . . . . . . 359

Actions Taken by DLPAR Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . 360

Making Kernel Extensions DLPAR-Aware . . . . . . . . . . . . . . . . . . . . . . . 365

Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

Chapter 17. sed Program Information . . . . . . . . . . . . . . . . . . . . . . . . 371

Manipulating Strings with sed . . . . . . . . . . . . . . . . . . . . . . . . . . . 371

Chapter 18. Shared Libraries and Shared Memory . . . . . . . . . . . . . . . . . . . 377

Shared Objects and Runtime Linking . . . . . . . . . . . . . . . . . . . . . . . . . 377

Shared Libraries and Lazy Loading . . . . . . . . . . . . . . . . . . . . . . . . . 379

Creating a Shared Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381

Program Address Space Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 383

Understanding Memory Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . 385

Inter-Process Communication (IPC) Limits . . . . . . . . . . . . . . . . . . . . . . . 389

Creating a Mapped Data File with the shmat Subroutine . . . . . . . . . . . . . . . . . . 392

Creating a Copy-On-Write Mapped Data File with the shmat Subroutine . . . . . . . . . . . . 393

Creating a Shared Memory Segment with the shmat Subroutine . . . . . . . . . . . . . . . 394

Paging Space Programming Requirements . . . . . . . . . . . . . . . . . . . . . . 394

List of Memory Manipulation Services . . . . . . . . . . . . . . . . . . . . . . . . 395

List of Memory Mapping Services . . . . . . . . . . . . . . . . . . . . . . . . . . 396

Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396

Chapter 19. System Memory Allocation Using the malloc Subsystem . . . . . . . . . . . 399

Working with the Process Heap . . . . . . . . . . . . . . . . . . . . . . . . . . . 400

Understanding System Allocation Policy . . . . . . . . . . . . . . . . . . . . . . . . 401

vi General Programming Concepts: Writing and Debugging Programs

User-Defined Malloc Replacement . . . . . . . . . . . . . . . . . . . . . . . . . . 408

Debug Malloc Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .411

Malloc Multiheap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417

Malloc Buckets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418

Malloc Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422

Malloc Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422

Malloc Disclaim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424

Malloc Detect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424

Configuring and Using the Malloc Thread Cache . . . . . . . . . . . . . . . . . . . . 425

Chapter 20. AIX Vector Programming . . . . . . . . . . . . . . . . . . . . . . . . 427

Vector Extension Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427

Runtime Determination of Vector Capability . . . . . . . . . . . . . . . . . . . . . . 427

AIX ABI Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428

Legacy ABI Compatibility and Interoperability . . . . . . . . . . . . . . . . . . . . . . 430

Extended Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430

Vector Memory Allocation and Alignment . . . . . . . . . . . . . . . . . . . . . . . 431

printf and scanf of Vector Data Types . . . . . . . . . . . . . . . . . . . . . . . . 432

Threaded Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432

Compilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432

Assembler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433

Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433

Core Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434

Chapter 21. Packaging Software for Installation . . . . . . . . . . . . . . . . . . . . 435

Installation Procedure Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 435

Package Control Information Requirements . . . . . . . . . . . . . . . . . . . . . . 436

Format of a Software Package . . . . . . . . . . . . . . . . . . . . . . . . . . . 436

Package Partitioning Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 436

Software Vital Product Data (SWVPD) . . . . . . . . . . . . . . . . . . . . . . . . 436

Software Product Packaging Parts . . . . . . . . . . . . . . . . . . . . . . . . . . 437

Package and Fileset Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . 437

Fileset Revision Level Identification . . . . . . . . . . . . . . . . . . . . . . . . . 439

Contents of a Software Package . . . . . . . . . . . . . . . . . . . . . . . . . . 439

The lpp_name Package Information File . . . . . . . . . . . . . . . . . . . . . . . 440

The liblpp.a Installation Control Library File . . . . . . . . . . . . . . . . . . . . . . 450

Further Description of Installation Control Files . . . . . . . . . . . . . . . . . . . . . 453

Installation Control Files Specifically for Repackaged Products . . . . . . . . . . . . . . . 458

Installation Files for Supplemental Disk Subsystems . . . . . . . . . . . . . . . . . . . 461

Format of Distribution Media . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461

Tape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461

CD-ROM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461

Diskette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462

The Table of Contents File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463

The installp Processing of Product Packages . . . . . . . . . . . . . . . . . . . . . . 464

Installation Commands Used During Installation and Update Processing . . . . . . . . . . . . 470

Chapter 22. Source Code Control System (SCCS) . . . . . . . . . . . . . . . . . . . 471

Introduction to SCCS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471

SCCS Flag and Parameter Conventions . . . . . . . . . . . . . . . . . . . . . . . 472

Creating, Editing, and Updating an SCCS File . . . . . . . . . . . . . . . . . . . . . 472

Controlling and Tracking SCCS File Changes . . . . . . . . . . . . . . . . . . . . . . 474

Detecting and Repairing Damaged SCCS Files . . . . . . . . . . . . . . . . . . . . . 475

List of Additional SCCS Commands . . . . . . . . . . . . . . . . . . . . . . . . . 476

Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476

Contents vii

Chapter 23. Subroutines, Example Programs, and Libraries . . . . . . . . . . . . . . . 477

128-Bit Long Double Floating-Point Data Type . . . . . . . . . . . . . . . . . . . . . 478

List of Character Manipulation Subroutines . . . . . . . . . . . . . . . . . . . . . . 480

List of Executable Program Creation Subroutines . . . . . . . . . . . . . . . . . . . . 481

List of Files and Directories Subroutines . . . . . . . . . . . . . . . . . . . . . . . 481

List of FORTRAN BLAS Level 1: Vector-Vector Subroutines . . . . . . . . . . . . . . . . 483

List of FORTRAN BLAS Level 2: Matrix-Vector Subroutines . . . . . . . . . . . . . . . . 483

List of FORTRAN BLAS Level 3: Matrix-Matrix Subroutines . . . . . . . . . . . . . . . . 484

List of Numerical Manipulation Subroutines . . . . . . . . . . . . . . . . . . . . . . 484

List of Long Long Integer Numerical Manipulation Subroutines . . . . . . . . . . . . . . . 485

List of 128-Bit Long Double Numerical Manipulation Subroutines . . . . . . . . . . . . . . 485

List of Processes Subroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . 486

List of Multi-threaded Programming Subroutines . . . . . . . . . . . . . . . . . . . . . 488

List of Programmer’s Workbench Library Subroutines . . . . . . . . . . . . . . . . . . . 490

List of Security and Auditing Subroutines . . . . . . . . . . . . . . . . . . . . . . . 491

List of String Manipulation Subroutines . . . . . . . . . . . . . . . . . . . . . . . . 492

Programming Example for Manipulating Characters . . . . . . . . . . . . . . . . . . . 493

Searching and Sorting Example Program . . . . . . . . . . . . . . . . . . . . . . . 495

List of Operating System Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . 498

librs2.a Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499

Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500

Chapter 24. System Management Interface Tool (SMIT) . . . . . . . . . . . . . . . . . 501

SMIT Screen Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501

SMIT Object Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504

SMIT Aliases and Fast Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507

SMIT Information Command Descriptors . . . . . . . . . . . . . . . . . . . . . . . 508

SMIT Command Generation and Execution . . . . . . . . . . . . . . . . . . . . . . 510

Adding Tasks to the SMIT Database . . . . . . . . . . . . . . . . . . . . . . . . . 512

Debugging SMIT Database Extensions . . . . . . . . . . . . . . . . . . . . . . . . 513

Creating SMIT Help Information for a New Task . . . . . . . . . . . . . . . . . . . . . 513

sm_menu_opt (SMIT Menu) Object Class . . . . . . . . . . . . . . . . . . . . . . . 514

sm_name_hdr (SMIT Selector Header) Object Class . . . . . . . . . . . . . . . . . . . 516

sm_cmd_opt (SMIT Dialog/Selector Command Option) Object Class . . . . . . . . . . . . . 518

sm_cmd_hdr (SMIT Dialog Header) Object Class . . . . . . . . . . . . . . . . . . . . 522

SMIT Example Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524

Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536

Chapter 25. System Resource Controller . . . . . . . . . . . . . . . . . . . . . . 537

Subsystem Interaction with the SRC . . . . . . . . . . . . . . . . . . . . . . . . . 537

SRC Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538

SRC Communication Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542

Programming Subsystem Communication with the SRC . . . . . . . . . . . . . . . . . . 545

Defining Your Subsystem to the SRC . . . . . . . . . . . . . . . . . . . . . . . . . 551

List of Additional SRC Subroutines . . . . . . . . . . . . . . . . . . . . . . . . . . 552

Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552

Chapter 26. Trace Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555

The Trace Facility Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555

Controlling the Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555

Recording Trace Event Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556

Generating a Trace Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557

Extracting trace data from a dump . . . . . . . . . . . . . . . . . . . . . . . . . . 557

Trace Facility Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557

Start the Trace Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560

Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562

viii General Programming Concepts: Writing and Debugging Programs

Chapter 27. tty Subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563

TTY Subsystem Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563

Line Discipline Module (ldterm) . . . . . . . . . . . . . . . . . . . . . . . . . . . 567

Converter Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 570

TTY Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571

Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572

Chapter 28. Loader Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . 573

Using Loader Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573

Creating/Deleting Loader Domains . . . . . . . . . . . . . . . . . . . . . . . . . . 575

Chapter 29. Data Management Application Programming Interface (DMAPI) . . . . . . . . . 577

DMAPI Considerations for the Enhanced Journaled File System . . . . . . . . . . . . . . . 578

Appendix A. High-Resolution Time Measurements Using POWER-based Time Base or POWER

family Real-Time Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587

Contents ix

x General Programming Concepts: Writing and Debugging Programs

About This Book

This book provides application developers with complete information about writing applications for the AIX

®

operating system. Programmers can use this book to gain knowledge of programming guidelines and

resources. Topics include input and output handling, curses, file systems and directories, lex and yacc,

logical volume programming, shared libraries, large program support, packaging, trace facility, and System

Management Interface Tool (SMIT).

Highlighting

The following highlighting conventions are used in this book:

Bold Identifies commands, subroutines, keywords, files, structures, directories, and other items whose

names are predefined by the system. Also identifies graphical objects such as buttons, labels, and

icons that the user selects.

Italics Identifies parameters whose actual names or values are to be supplied by the user.

Monospace Identifies examples of specific data values, examples of text similar to what you might see

displayed, examples of portions of program code similar to what you might write as a programmer,

messages from the system, or information you should actually type.

Case-Sensitivity in AIX

Everything in the AIX operating system is case-sensitive, which means that it distinguishes between

uppercase and lowercase letters. For example, you can use the ls command to list files. If you type LS, the

system responds that the command is ″not found.″ Likewise, FILEA, FiLea, and filea are three distinct file

names, even if they reside in the same directory. To avoid causing undesirable actions to be performed,

always ensure that you use the correct case.

ISO 9000

ISO 9000 registered quality systems were used in the development and manufacturing of this product.

Related Publications

The following books contain information about or related to writing programs:

v AIX 5L Version 5.3 Kernel Extensions and Device Support Programming Concepts

v AIX 5L Version 5.3 Communications Programming Concepts

v AIX 5L Version 5.3 AIXwindows Programming Guide

v AIX 5L Version 5.3 System Management Guide: Operating System and Devices

v AIX 5L Version 5.3 System Management Guide: Communications and Networks

v AIX 5L Version 5.3 Commands Reference

v Keyboard Technical Reference

v AIX 5L Version 5.3 Technical Reference: Base Operating System and Extensions Volume 1

v AIX 5L Version 5.3 Technical Reference: Base Operating System and Extensions Volume 2

v Understanding the Diagnostic Subsystem for AIX

xii General Programming Concepts: Writing and Debugging Programs

Chapter 1. Tools and Utilities

This chapter provides an overview of the tools and utilities that you can use to develop C compiled

language programs. Many tools are provided to help you develop C compiled programs. The tools provide

help with the following programming tasks:

v “Entering a Program into the System”

v “Checking a Program”

v “Compiling and Linking a Program”

v “Subroutines” on page 2

v “Shell Commands” on page 2

Subroutines and shell commands are provided for use in a C compiled program.

Entering a Program into the System

The system has a line editor called ed for use in entering a program into a file. The system also has the

full-screen editor called vi, which displays one full screen of data at a time and allows interactive editing of

a file.

Checking a Program

Use the following commands to check the format of a program for consistency and accuracy:

cb Reformats a C language source program into a consistent format that uses indentation levels to show

the structure of the program.

cflow Generates a diagram of the logic flow of a C language source program.

cxref Generates a list of all external references for each module of a C language source program, including

where the reference is resolved (if it is resolved in the program).

lint Checks for syntax and data type errors in a C language source program. The lint command might

check these areas of a program more carefully than the C language compiler does, and displays many

messages that point out possible problems.

Compiling and Linking a Program

To convert source code into a program that the system can run, you must process the source file with a

compiler and a linkage editor.

A compiler is a program that reads text from a file and changes the programming language in that file to a

form that the system understands. The linkage editor connects program modules and determines how to

put the finished program into memory. To create this final form of the program, the system does the

following:

1. If a file contains compiler source code, the compiler translates it into object code.

2. If a file contains assembler language, the assembler translates it into object code.

3. The linkage editor links the object files created in the previous step with any other object files specified

in the compiler command.

Other programming languages available for use on the operating system include the C

++

, FORTRAN,

COBOL,nd Assembler and other compiler languages.

You can write parts of a program in different languages and have one main routine call and start the

separate routines to execute. You can also use the compiler program to create object code and link the

program.

Correcting Errors in a Program

You can use the following debugging tools that are provided with the base operating system:

v The dbx symbolic debug program allows you to debug programs written in C language, C

++

,

FORTRAN, COBOL and Assembler languages. For more information, see “dbx Symbolic Debug

Program Overview” on page 61.

v The adb debug program provides subcommands you can use to examine, debug, and repair executable

binary files and to examine non-ASCII data files. For more information, see “adb Debug Program

Overview” on page 29.

v KDB Kernel Debugger and kdb command can help you determine errors in code running in the kernel.

You can use this debug program to debug device drivers and kernel extensions.

v The trace facility helps isolate system problems by monitoring selected system events. For more

information see Chapter 26, “Trace Facility,” on page 555.

When syntax errors or parameter-naming inconsistencies are discovered in a program file, you can use a

text editor or string-searching and string-editing programs to locate and change strings in the file.

String-searching and string-editing programs include the grep, sed, and awk commands. To make many

changes in one or more program files, you can include the commands in a shell program and then run the

shell program to locate and change the code in the files.

Building and Maintaining a Program

The following facilities help you control program changes and build a program from many source modules.

These facilities can be particularly useful in software development environments in which many source

modules are produced.

v The make command builds a program from source modules. Because the make command compiles

only those modules changed since the last build, its use can reduce compilation time when many

source modules must be processed.

v The Source Code Control System (SCCS) allows you to maintain separate versions of a program

without storing separate, complete copies of each version. The use of SCCS can reduce storage

requirements and help in tracking the development of a project that requires keeping many versions of

large programs. For more information, see Chapter 22, “Source Code Control System (SCCS),” on page

471

Subroutines

Subroutines from system libraries handle many complex or repetitive programming situations so that you

can concentrate on unique programming situations. See Chapter 23, “Subroutines, Example Programs,

and Libraries,” on page 477 for information on using subroutines and for lists of many of the subroutines

available on the system.

Shell Commands

You can include the functions of many of the shell commands in a C language program. Any shell

command used in a program must be available on all systems that use the program.

You can then use the fork and exec subroutines in a program to run the command as a process in a part

of the system that is separate from the program. The system subroutine also runs a shell command in a

program, and the popen subroutine uses shell filters.

2 General Programming Concepts: Writing and Debugging Programs

Related Information

For further information on this topic, see the following:

v “Manipulating Strings with sed” on page 371

v “Generating a Lexical Analyzer with the lex Command” on page 277

v Chapter 12, “make Command,” on page 307

v Chapter 23, “Subroutines, Example Programs, and Libraries,” on page 477

Chapter 1. Tools and Utilities 3

4 General Programming Concepts: Writing and Debugging Programs

Chapter 2. Curses Library

The curses library provides a set of functions that enable you to manipulate a terminal’s display regardless

of the terminal type. The curses library supports color. However, multibyte characters are not supported. All

references to characters in the curses documentation refer to single-byte characters. Throughout this

documentation, the curses library is referred to as curses.

The basis of curses programming is the window data structure. Using this structure, you can manipulate

data on a terminal’s display. You can instruct curses to treat the entire terminal display as one large

window, or you can create multiple windows on the display. The windows can be different sizes and can

overlap one another. A typical curses application has a single large window and one subwindow within it.

Each window on a terminal’s display has its own window data structure. This structure keeps state

information about the window, such as its size and where it is located on the display. Curses uses the

window data structure to obtain the relevant information it needs to carry out your instructions.

Terminology

When programming with curses, you should be familiar with the following terms:

Term Definition

current character The character that the logical cursor is currently on.

current line The line that the logical cursor is currently on.

curscr A virtual default window provided by curses. The curscr (current screen) is an internal

representation of what currently appears on the terminal’s external display. Do not

modify the curscr.

display A physical display connected to a workstation.

logical cursor The cursor location within each window. The window data structure keeps track of the

location of its logical cursor.

pad A pad is a window that is not restricted by the size of the screen

physical cursor The cursor that appears on a display. The workstation uses this cursor to write to the

display. There is only one physical cursor per display.

screen The window that fills the entire display. The screen is synonymous with the stdscr.

stdscr A virtual default window (standard screen) provided by curses that represents the entire

display.

window A pointer to a C data structure and the graphic representation of that data structure on

the display. A window can be thought of as a two-dimensional array representing how

all or part of the display looks at any point in time.

Naming Conventions

A single curses subroutine can have more than one version. Curses subroutines with multiple versions

follow distinct naming conventions that identify the separate versions. These conventions add a prefix to a

standard curses subroutine and identify what arguments the subroutine requires or what actions take place

when the subroutine is called. The different versions of curses subroutine names use the following

prefixes:

Prefix Description

w Identifies a subroutine that requires a window argument

p Identifies a subroutine that requires a pad argument

mv Identifies a subroutine that first performs a move to the program-supplied coordinates

If a curses subroutine has multiple versions and does not include one of the preceding prefixes, the curses

default window stdscr (standard screen) is used. The majority of subroutines that use the stdscr are

macros created in the /usr/include/curses.h file using #define statements. The preprocessor replaces

these statements at compilation time. As a result, these macros do not appear in the compiled assembler

code, a trace, a debug program, or the curses source code.

If a curses subroutine has only a single version, it does not necessarily use stdscr. For example, the

printw subroutine prints a string to the stdscr. The wprintw subroutine prints a string to a specific window

by supplying the window argument. The mvprintw subroutine moves the specified coordinates to the

stdscr and then performs the same function as the printw subroutine. Likewise, the mvwprintw subroutine

moves the specified coordinates to the specified window and then performs the same function as the

wprintw subroutine.

Structure of a Curses Program

In general, a curses program has the following progression:

1. Start curses.

2. Check for color support (optional).

3. Start color (optional).

4. Create one or more windows.

5. Manipulate windows.

6. Destroy one or more windows.

7. Stop curses.

Some steps are optional, so your program does not have to follow this progression exactly.

Return Values

With a few exceptions, all curses subroutines return either the integer value ERR or the integer value OK.

Subroutines that do not follow this convention are noted appropriately. Subroutines that return pointers

always return a null pointer or an error.

Initializing Curses

Use the following commnads to initialize curses:

endwin Terminates the curses subroutine libraries and their data structures

initscr Initializes the curses subroutine library and its data structures

isendwin Returns TRUE if the endwin subroutine has been called without any subsequent calls to the

wrefresh subroutine

newterm Sets up a new terminal

setupterm Sets up the TERMINAL structure for use by curses

You must include the curses.h file at the beginning of any program that calls curses subroutines. To do

this, use the following statement:

#include <curses.h>

Before you can call subroutines that manipulate windows or screens, you must call the initscr or newterm

subroutine. These subroutines first save the terminal’s settings and then call the setupterm subroutine to

establish a curses terminal.

If you need to temporarily suspend curses, use a shell escape or subroutine. To resume after a temporary

escape, call the wrefresh or doupdate subroutine. Before exiting a curses program, you must call the

endwin subroutine. The endwin subroutine restores tty modes, moves the cursor to the lower-left corner

of the screen, and resets the terminal into the proper nonvisual mode.

6 General Programming Concepts: Writing and Debugging Programs

Page is loading ...

Bull AIX 5.3 - General Programming Guide

Related papers

Other documents