Topics in IRIX® Programming Document Number 007-2478-010 CONTRIBUTORS Written by David Cortesi based on previous versions by Arthur Evans, Wendy Ferguson, and Jed Hartman; updated by Susan Thomas, Julie Boney, and Steven Levine Production by Karen Jacobson Engineering contributions by Ivan Bach, Greg Boyd, Joe CaraDonna, Srinivas Lingutla, Bill Mannell, Paul Mielke, Huy Nguyen, James Pitcairne-Hill, Paul Roy, Jonathan Thompson, and Ira Pramanick © 1996 - 2004, Silicon Graphics, Inc. All rights reserved; provided portions may be copyright in third parties, as indicated elsewhere herein. No permission is granted to copy, distribute, or create derivative works from the contents of this electronic documentation in any manner, in whole or in part, without the prior written permission of Silicon Graphics, Inc. LIMITED RIGHTS LEGEND The electronic (software) version of this document was developed at private expense; if acquired under an agreement with the USA government or any contractor thereto, it is acquired as "commercial computer software" subject to the provisions of its applicable license agreement, as specified in (a) 48 CFR 12.212 of the FAR; or, if acquired for Department of Defense units, (b) 48 CFR 227-7202 of the DoD FAR Supplement; or sections succeeding thereto. Contractor/manufacturer is Silicon Graphics, Inc., 1500 Crittenden Lane, Mountain View, CA 94043-1351. Silicon Graphics, CHALLENGE, Indy, IRIS, IRIX, Onyx, and OpenGL are registered trademarks and SGI, the SGI logo, Developer Magic, Impressario, Indigo2, IRIS Inventor, IRIS GL, IRIS IM, IRIS Insight, IRIS POWER C, IRIS Showcase, IRIS Performer, O2, OCTANE, Onyx2, Origin200, Origin2000, POWER CHALLENGE, POWER CHALLENGEarray, POWER Series, REACT, and XFS are trademarks of Silicon Graphics, Inc., in the United States and/or other countries worldwide. Cray is a registered trademark and CRAY T3E and CrayLink are trademarks of Cray Inc. MIPS, R4000, and R8000 are registered trademarks and MIPSpro and R10000 are trademarks of MIPS Technologies, Inc. Ada is a registered trademark of Ada Joint Program Office, U.S. Government. AT&T is a trademark of AT&T, Inc. NFS is a registered trademark of Sun Microsystems, Inc. OSF/Motif is a trademark of Open Software Foundation, Inc. POSIX is a registered trademark of the Institute of Electrical and Electronic Engineers, Inc. (IEEE). PostScript and Display Postscript are registered trademarks of Adobe Systems, Inc. Speedo is a trademark of Bitstream, Inc. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company, Ltd. X Window System is a trademark of X Consortium, Inc. Topics in IRIX® Programming Document Number 007-2478-010 Contents List of Examples xxv List of Figures xxvii List of Tables xxix About This Manual xxxiii What This Manual Contains xxxiii What You Should Know Before Reading This Manual xxxiv Other Useful References xxxiv Obtaining Manuals xxxv Conventions Used in This Manual xxxv Reader Comments xxxvi 1. Process Address Space 3 Defining the Address Space 3 Address Space Boundaries 4 Page Numbers and Offsets 5 Address Definition 5 Address Space Limits 6 Delayed and Immediate Space Definition 7 Page Validation 9 Read-Only Pages 10 Copy-on-Write Pages 10 Interrogating the Memory System 11 iii Contents Mapping Segments of Memory 12 Segment Mapping Function mmap() 12 Describing the Mapped Object 13 Describing the New Segment 13 Mapping a File for I/O 15 Mapped File Sizes 16 Apparent Process Size 16 Mapping Portions of a File 17 File Permissions 17 NFS Considerations 17 File Integrity 18 Mapping a File for Shared Memory 19 Mapping a Segment of Zeros 19 Mapping Physical Memory 20 Mapping Kernel Virtual Memory 20 Mapping a VME Device 20 Choosing a Segment Address 21 Segments at Fixed Offsets 21 Segments at a Fixed Address 22 iv Contents Locking and Unlocking Pages in Memory 23 Memory Locking Functions 24 Locking Program Text and Data 24 Locking Mapped Segments 25 Locking Mapped Files 26 Unlocking Memory 27 Additional Memory Features 27 Changing Memory Protection 28 Synchronizing the Backing Store 28 Releasing Unneeded Pages 29 Using Origin2000 Nonuniform Memory 29 About Origin Hardware 30 Basic Building Blocks 30 Uniform Addressing 30 Cache Coherency 31 Cache Coherency in CHALLENGE Systems 32 Cache Coherency in Origin Systems 32 About CC-NUMA Performance Issues 33 About Default Memory Location 33 About Large Memory Use 34 About Multithreaded Memory Use 34 Dealing With Cache Contention 34 Detecting Cache Contention 35 Correcting Cache Contention Problems 36 Getting Optimum Memory Placement 38 Detecting Memory Placement Problems 38 Programming Desired Memory Placement 39 Using Compiler Directives for Memory Placement 39 Taking Advantage of First-Touch Allocation 40 Using Round-Robin Allocation 41 Using Dynamic Page Migration 41 Using Explicit Memory Placement 42 v Contents 2. Interprocess Communication 45 Types of Interprocess Communication Available 46 Using POSIX IPC 48 POSIX IPC Name Space 48 Using IRIX IPC 49 Using System V IPC 49 SVR4 IPC Name Space 50 Configuring the IPC Name Space 50 Listing and Removing Persistent Objects 50 Access Permissions 51 Choosing and Communicating Key Values 51 Using ID Numbers 51 Private Key Values 52 Using 4.2 BSD IPC 52 vi Contents 3. Sharing Memory Between Processes 53 Overview of Memory Sharing 53 Shared Memory Based on mmap() 54 Sharing Memory Between 32-Bit and 64-Bit Processes 54 POSIX Shared Memory Operations 55 Creating a Shared Object 55 Shared Object Pathname 56 Shared Object Open Flags 56 Shared Object Access Mode 56 Using the Shared Object File Descriptor 57 Using a Shared Object 57 Example Program 57 IRIX Shared Memory Arenas 61 Overview of Shared Arenas 61 Initializing Arena Attributes 61 Creating an Arena 63 Joining an Arena 63 Restricting Access to an Arena 64 Arena Access From Processes in a Share Group 64 Allocating in an Arena 65 Exchanging the First Datum 66 System V Shared Memory Functions 71 Creating or Finding a Shared Memory Segment 71 Attaching a Shared Segment 72 Managing a Shared Segment 72 Information About Shared Memory 73 Shared Memory Examples 73 Example of Creating a Shared Segment 73 Example of Attaching a Shared Segment 74 vii Contents 4. Mutual Exclusion 77 Overview of Mutual Exclusion 78 Test-and-Set Instructions 78 Locks 79 Semaphores 80 Condition Variables 81 Barriers 82 POSIX Facilities for Mutual Exclusion 82 Managing Unnamed Semaphores 83 Managing Named Semaphores 84 Creating a Named Semaphore 84 Closing and Removing a Named Semaphore 85 Using Semaphores 85 Using Mutexes and Condition Variables 86 IRIX Facilities for Mutual Exclusion 87 Using IRIX Semaphores 87 Creating Normal Semaphores 87 Creating Polled Semaphores 88 Operating on Semaphores 89 Using Locks 90 Creating and Managing Locks 90 Claiming and Releasing Locks 91 Using Barriers 92 Using Test-and-Set Functions 92 Using Test-and-Set 93 Using Compare-and-Swap 93 Using Compiler Intrinsics for Test-and-Set 95 Creating or Finding a Semaphore Set 97 Managing Semaphore Sets 98 Using Semaphore Sets 100 Example Programs 101 Example Uses of semget() 102 Example Uses of semctl() for Management 104 viii Contents Example Uses of semctl() for Query 106 Example Uses of semop() 108 Using the Examples 110 ix Contents 5. Signalling Events 113 Signals 113 Signal Numbers 114 Signal Implementations 116 Signal Blocking and Signal Masks 117 Multiple Signals 117 Signal Handling Policies 118 Default Handling 118 Ignoring Signals 118 Catching Signals 118 Synchronous Signal Handling 119 Signal Latency 119 Signals Under X-Windows 120 POSIX Signal Facility 120 Signal Masking 122 Using Synchronous Handling 122 Using Asynchronous Handling 123 System V Signal Facility 124 BSD Signal Facility 126 Timer Facilities 127 Timed Pauses and Schedule Cession 127 Time Data Structures 128 Time Signal Latency 128 How Timers Are Managed 129 POSIX Timers 129 Getting Program Execution Time 130 Creating Timestamps 131 Using Interval Timers 133 BSD Timers 134 Hardware Cycle Counter 135 6. Message Queues 137 Overview of Message Queues 138 Implementation Differences 138 x Contents Uses of Message Queues 140 POSIX Message Queues 140 Managing Message Queues 141 Creating a Message Queue 141 Opening an Existing Queue 142 Specifying Blocking or Nonblocking Access 142 Using Message Queues 143 Sending a Message 143 Receiving a Message 143 Using Asynchronous Notification 143 Example Programs 144 Example of mq_getattr() 145 Example of mq_open() 147 Example of mq_send() 149 Example of mq_receive() 152 System V Message Queues 155 Managing SVR4 Message Queues 155 Creating a Message Queue 155 Accessing an Existing Queue 156 Modifying a Message Queue 156 Removing a Message Queue 156 Using SVR4 Message Queues 157 Sending a Message 157 Receiving a Message 157 Example Programs 158 Example of msgget 160 Example of msgctl 163 Example of msgsnd 166 Example of msgrcv 169 xi Contents 7. File and Record Locking 175 Overview of File and Record Locking 176 Terminology 176 Record 176 Read (Shared) Lock 177 Write (Exclusive) Lock 177 Advisory Locking 177 Mandatory Locking 177 Lock Promotion and Demotion 178 Controlling File Access With File Permissions 178 Using Record Locking 179 Opening a File for Record Locking 179 Setting a File Lock 180 Whole-File Lock With fcntl() 181 Whole-File Lock With lockf() 182 Whole-File Lock With flock() 182 Setting and Removing Record Locks 183 Getting Lock Information 187 Deadlock Handling 190 Enforcing Mandatory Locking 190 xii Contents Record Locking Across Multiple Systems