Programming Utilities Guide Sun Microsystems, Inc. 2550 Garcia Avenue Mountain View, CA 94043-1100 U.S.A. Part No: 802-5880 August 1997 Copyright 1997 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California 94303-4900 U.S.A. All rights reserved. This product or document is protected by copyright and distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this product or document may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any. Third-party software, including font technology, is copyrighted and licensed from Sun suppliers. Parts of the product may be derived from Berkeley BSD systems, licensed from the University of California. UNIX is a registered trademark in the U.S. and other countries, exclusively licensed through X/Open Company, Ltd. Sun, Sun Microsystems, the Sun logo, SunSoft, SunDocs, SunExpress, and Solaris are trademarks, registered trademarks, or service marks of Sun Microsystems, Inc. in the U.S. and other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the U.S. and other countries. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc. The OPEN LOOK and SunTM Graphical User Interface was developed by Sun Microsystems, Inc. for its users and licensees. Sun acknowledges the pioneering efforts of Xerox in researching and developing the concept of visual or graphical user interfaces for the computer industry. Sun holds a non-exclusive license from Xerox to the Xerox Graphical User Interface, which license also covers Sun’s licensees who implement OPEN LOOK GUIs and otherwise comply with Sun’s written license agreements. RESTRICTED RIGHTS: Use, duplication, or disclosure by the U.S. Government is subject to restrictions of FAR 52.227–14(g)(2)(6/87) and FAR 52.227–19(6/87), or DFAR 252.227–7015(b)(6/95) and DFAR 227.7202–3(a). DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. Copyright 1997 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, Californie 94303-4900 Etats-Unis. Tous droits réservés. Ce produit ou document est protégé par un copyright et distribué avec des licences qui en restreignent l’utilisation, la copie, la distribution, et la décompilation. Aucune partie de ce produit ou document ne peut être reproduite sous aucune forme, par quelque moyen que ce soit, sans l’autorisation préalable et écrite de Sun et de ses bailleurs de licence, s’il y en a. Le logiciel détenu par des tiers, et qui comprend la technologie relative aux polices de caractères, est protégé par un copyright et licencié par des fournisseurs de Sun. Des parties de ce produit pourront être dérivées du système Berkeley BSD licenciés par l’Université de Californie. UNIX est une marque déposée aux Etats-Unis et dans d’autres pays et licenciée exclusivement par X/Open Company, Ltd. Sun, Sun Microsystems, le logo Sun, SunSoft, SunDocs, SunExpress, et Solaris sont des marques de fabrique ou des marques déposées, ou marques de service, de Sun Microsystems, Inc. aux Etats-Unis et dans d’autres pays. Toutes les marques SPARC sont utilisées sous licence et sont des marques de fabrique ou des marques déposées de SPARC International, Inc. aux Etats-Unis et dans d’autres pays. Les produits portant les marques SPARC sont basés sur une architecture développée par Sun Microsystems, Inc. L’interface d’utilisation graphique OPEN LOOK et SunTM a été développée par Sun Microsystems, Inc. pour ses utilisateurs et licenciés. Sun reconnaît les efforts de pionniers de Xerox pour la recherche et le développement du concept des interfaces d’utilisation visuelle ou graphique pour l’industrie de l’informatique. Sun détient une licence non exclusive de Xerox sur l’interface d’utilisation graphique Xerox, cette licence couvrant également les licenciés de Sun qui mettent en place l’interface d’utilisation graphique OPEN LOOK et qui en outre se conforment aux licences écrites de Sun. CETTE PUBLICATION EST FOURNIE “EN L’ETAT” ET AUCUNE GARANTIE, EXPRESSE OU IMPLICITE, N’EST ACCORDEE, Y COMPRIS DES GARANTIES CONCERNANT LA VALEUR MARCHANDE, L’APTITUDE DE LA PUBLICATION A REPONDRE A UNE UTILISATION PARTICULIERE, OU LE FAIT QU’ELLE NE SOIT PAS CONTREFAISANTE DE PRODUIT DE TIERS. CE DENI DE GARANTIE NE S’APPLIQUERAIT PAS, DANS LA MESURE OU IL SERAIT TENU JURIDIQUEMENT NUL ET NON AVENU. Please Recycle Contents Preface xi 1. Tracing Program Execution With the TNF Utilities 1 Defining Types of Users 2 Using Existing Probe Points 2 Debugging a Program 2 Inserting Probe Points in a Library 2 Tracing Kernel Execution 2 How TNF Works 2 Inserting Probe Points 3 Starting prex 3 Running prex 6 Reading the Trace File 18 Kernel Tracing 19 Controlling Kernel Tracing (prex)20 Extracting Kernel Trace Data (tnfxtract)23 Examining Kernel Trace Data (tnfdump)24 Available Kernel Probes (tnf_probes)24 Thread Probes 25 Shell Script for Kernel Tracing 28 Contents iii Advanced Topics 31 Inserting Probe Points 31 Defining User Types for Probe Points 36 Performance Issues 38 /proc 38 dlopen() and dlclose() and History 39 Signals 39 Failure of Event-Writing Operations 39 Target Executing a fork() or exec() 40 2. Lexical Analysis 41 Internationalization 42 Generating a Lexical Analyzer Program 42 Writing lex Source 44 The Fundamentals of lex Rules 44 Advanced lex Features 49 C++ Mangled Symbols 57 Using lex and yacc Together 59 Automaton 62 Summary of Source Format 62 3. yacc — A Compiler Compiler 65 Internationalization 67 Basic Specifications 67 Actions 69 Lexical Analysis 72 Parser Operation 73 Ambiguity and Conflicts 77 Precedence 81 Error Handling 85 iv Programming Utilities Guide ♦ August 1997 The yacc Environment 88 Hints for Preparing Specifications 89 Input Style 89 Left Recursion 89 C++ Mangled Symbols 90 Lexical Tie-Ins 91 Reserved Words 91 Advanced Topics 92 Simulating error and accept in Actions 92 Accessing Values in Enclosing Rules 92 Support for Arbitrary Value Types 93 yacc Input Syntax 94 Examples 96 A Simple Example 96 An Advanced Example 99 4. make Utility 107 Dependency Checking: make vs. Shell Scripts 108 Writing a Simple Makefile 109 Basic Use of Implicit Rules 111 Processing Dependencies 111 Null Rules 114 Special Targets 114 Unknown Targets 115 Duplicate Targets 115 Reserved make Words 115 Running Commands Silently 116 Automatic Retrieval of SCCS Files 117 Passing Parameters: Simple make Macros 118 Contents v .KEEP_STATE and Command Dependency Checking 120 .KEEP_STATE and Hidden Dependencies 121 Displaying Information About a make Run 122 Using make to Compile Programs 125 Simple Makefile Example 125 Using make’s Predefined Macros 126 Using Implicit Rules to Simplify a Makefile: Suffix Rules 127 When to Use Explicit Target Entries vs. Implicit Rules 129 Implicit Rules and Dynamic Macros 129 Adding Suffix Rules 132 Pattern-Matching Rules: An Alternative to Suffix Rules 133 Building Object Libraries 139 Libraries, Members, and Symbols 139 Library Members and Dependency Checking 140 Using make to Maintain Libraries and Programs 141 More about Macros 141 Linking with System-Supplied Libraries 143 Compiling Programs for Debugging and Profiling 144 Compiling Debugging and Profiling Variants 146 Maintaining Separate Program and Library Variants 147 Maintaining a Directory of Header Files 150 Compiling and Linking with Your Own Libraries 151 Nested make Commands 151 Passing Parameters to Nested make Commands 154 Compiling Other Source Files 156 Maintaining Shell Scripts with make and SCCS 158 Running Tests with make 159 Maintaining Software Projects 161 vi Programming Utilities Guide ♦ August 1997 Organizing a Project for Ease of Maintenance 162 Building the Entire Project 163 Maintaining Directory Hierarchies with the Recursive Makefiles 165 Maintaining Recursive Targets 165 Maintaining a Large Library as a Hierarchy of Subsidiaries 166 Reporting Hidden Dependencies to make 168 make Enhancements Summary 168 Default Makefile 168 The State File .make.state 169 Hidden-Dependency Checking 169 Command-Dependency Checking 169 Automatic Retrieval of SCCS Files 169 Pattern-Matching Rules 170 Pattern-Replacement Macro References 170 New Options 172 Support for C++ and Modula-2 172 Naming Scheme for Predefined Macros 172 New Special-Purpose Targets 173 New Implicit lint Rule 173 Macro Processing Changes 173 Improved ar Library Support 175 Target Groups 175 Incompatibilities with Previous Versions 176 The −d Option 176 Dynamic Macros 176 Tilde Rules 177 Target Names 177 5. SCCS Source Code Control System 179 Contents vii The sccs Command 179 The sccs create Command 180 Basic sccs Subcommands 180 Deltas and Versions 181 sccs Subcommands 182 Checking Files In and Out 182 Incorporating Version-Dependent Information by Using ID Keywords 186 Making Inquiries 187 Deleting Committed Changes 190 Version Control for Binary Files 193 Maintaining Source Directories 194 Duplicate Source Directories 194 SCCS and make 194 Keeping SIDs Consistent Across Files 195 Starting a New Release 195 Temporary Files Used by SCCS 195 Branches 196 Using Branches 198 Administering SCCS Files 199 Interpreting Error Messages: sccs help 199 Altering History File Defaults: sccs admin 200 Validating the History File 201 Restoring the History File