Page iii POSIX Programmer's Guide Writing Portable UNIX Programs with the POSIX.1 Standard Donald A. Lewine Data General Corporation O'Reilly & Associates, Inc 103 Morris Street, Suite A Sebastopol, CA 95472 Page iv POSIX Programmer's Guide by Donald A. Lewine Editor: Dale Dougherty Copyright © 1991 O'Reilly & Associates, Inc. All rights reserved Printed in the United States of America Printing History April 1991: First edition December 1991: Minor corrections. Appendix G added. July 1992: Minor corrections. November 1992: Minor corrections. March 1994: Minor corrections and updates. NOTICE Portions of this text have been reprinted from IEEE Std 1003.1-1988, IEEE Standard Portable Operating System for Computer Environments, copyright © 1988 by the Institute of Electrical and Electronics Engineers, Inc., and IEEE Std 1003.1-1990, Information Technology—Portable Operating System Interface (POSIX)—Part 1: System Application Program Interface (API) [C Language], copyright © 1990 by the Institute of Electrical and Electronics Engineers, Inc., with the permission of the IEEE Standards Department. Nutshell Handbook and the Nutshell Handbook logo are registered trademarks of O'Reilly & Associates, Inc. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and O'Reilly and Associates, Inc. was aware of a trademark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this book, the publisher assumes no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein. Please address comments and questions in care of the publisher: O'Reilly & Associates, Inc. INTERNET: [email protected] 103 Morris Street, Suite A Sebastopol, CA 9547 (800) 998-9938 [8/98] ISBN: 0-937175-73-0 Page v To all my students To my wife, Susan, who convinced me to do this book and who put up with all the time this effort took Page vi Acknowledgments I would like to thank all of my students who put up with all of the beta test quality revisions. They provided many useful suggestions. I would like to thank some people who provided very complete technical reviews and provided useful comments: Hal Jespersen (Posix Software Group), Chuck Karish (Mindcraft, Inc.), Thomas Mitas (HBO & Company), Neil Todd (European UNIX Systems User Group), Andy Huber (Data General Corporation), Richard Eckhouse (University of Massachusetts), Andy Silverman (88open Consortium), Henry Spencer (University of Toronto), Jeffrey S. Haemer (Interactive Systems Corporation), Paul Rabin, Dave Kirschen, and Michael Meissner (Open Software Foundation), and John S. Quarterman (Texas Internet Consulting). Thanks go to the following readers of previous printings who pointed out errors and typos: Eric Boweles, Eric Hanchrow, Milt Ratcliff, Stephen J. Friedl, Ed Myer, Chesley Reyburn. Derek M. Jones, Todd Stevenson, Bob Burchfield, Anthony Scian, and Wayne Pallock Thanks to Allen Gray for his help with the reference material. Thanks to Mike Sierra and Ellie Cutler of O'Reilly & Associates for doing the production work and for writing the index. Special thanks to Dale Dougherty for a great job of editing. His many useful suggestions were worth the months they took to implement. Thanks to the POSIX standards committees for making this book possible. Page vii Table of Contents Preface xxiii The POSIX Standard Documents xxiv Guide to POSIX for Programmers xxv Programming Guide xxv Reference Guide and Appendixes xxvi Assumptions xxvi Conventions xxvii Chapter 1 Introduction to POSIX and Portability 1 Who is Backing POSIX? 2 The POSIX Family of Standards 3 The POSIX.1 Standard Document 5 The Design of POSIX 7 POSIX and UNIX 7 7 POSIX and Non-UNIX Operating Systems 8 POSIX, C, ANSI C, and Standard C 8 Why Standard C? 9 Working Outside the Standards 10 Finding The POSIX Libraries 11 Converting Existing Programs 11 Page viii Chapter 2 Developing POSIX Applications 13 The POSIX Development Environment 13 The Standard C Compiler 13 POSIX and C Libraries 14 Converting Existing Programs 15 A Porting Example 16 An Alternate Approach 19 Standard Header Files 20 Template for a POSIX Application 24 /* Feature test switches */ 25 /* System headers */ 25 /* Local headers */ 25 /* Macros */ 25 /* File scope variables */ 25 /* External variables */ 26 /* External functions */ 26 /* Structures and unions */ 26 /* Signal catching functions */ 26 26 /* Functions */ 26 /* Main */ 26 Sample Program 26 Portability Lab 38 Chapter 3 Standard File and Terminal I/O 39 Libraries and System Calls 39 Standard Files 39 Formatted Output 40 Examples 41 Pitfalls 42 The vfprintf(), vprintf(), and vsprintf() Functions 43 Character Output Functions 45 The fputs() and puts() Functions 45 The fputc(), putc(), and putchar() Functions 45 Reading Lines of Input 45 Pitfalls 47 Additional Pitfall 47 Page ix Other Character Input Functions 47 The fgetc(), getc() and getchar() Functions 47 The fgets() Function 48 The gets() Function 48 The ungetc() Function 48 Opening and Closing Files 49 Direct Input/Output functions 50 50 The fwrite() and fread() Functions 50 File Positioning Functions 50 The fgetpos() and fsetpos() Functions 51 The ftell() and fseek() Function 51 The rewind() Function 51 Managing Buffers 52 Sample Program 53 Portability Lab 60 Chapter 4 Files and Directories 63 Portable Filenames 63 Directory Tree 64 Current Working Directory 64 Making and Removing Directories 66 The rmdir() Function 67 Simulating the mkdir() and rmdir() Functions 67 Directory Structure 67 Manipulating Directories 68 Linking to a File 69 Removing a File 69 Renaming a File 69 File Characteristics 69 Retrieving a File's Characteristics 72 Changing File Accessibility 73 Changing the Owner of a File 73 Setting File Access and Modification Times 74 Page x Reading Directories 75 The opendir() Function 76 The readdir() Function 76 The closedir() Function 76 The rewinddir() Function 76 General Comments 76 Complete Example 77 Pitfall: Symbolic Links 83 Portability Lab 84 Chapter 5 Advanced File Operations 85 Primitive File Operations 86 File Descriptors 87 Opening a file 87 Reading from a File 89 Writing to a File 89 Fast File Copy Example 90 Control Operations on a File 92 F_GETFD/F_SETFD 92 F_GETFL/F_SETFL 93 F_SETLK/F_SETLKW/F_GETLK 94 F_DUPFD 95 Setting the File Position 95 The dup() and dup2() Functions 96 Closing a File 96 FIFOs and Pipes 96 96 File Creation Mask 97 The umask() Function 98 Mixing the Levels 98 The fdopen() Function 98 The fileno() Function 98 Pitfalls 99 Portability Lab 99 Page xi Chapter 6 Working with Processes 101 Process Creation 101 The fork() Function 101 The exec() Family of Function 102 Example: Piping Output Through more 103 Portability Note 105 Process Termination 106 The wait() and waitpid() Functions 106 Terminating the Current Process 108 Returning from main() 108 Calling exit() 109 Calling _exit() 109 Calling abort() 110 Terminating Another Process 110 Signals 110 Signal Actions 112 Signal-Catching Functions 112 112 Examine and Change Signal Action 113 Standard C Signals 113 POSIX Signals 114 Example: Timing a System Function 116 Signal Sets 117 The sigemptyset() Function 118 The sigfillset() Function 118 The sigaddset() Function 118 The sigdelset() Function 118 Using the sigset Functions 118 The sigismember() Function 119 The sigprocmask() Function 119 The sigpending() Function 119 Wait for a Signal 120 Sending a Signal 121 Portability Lab 122 Page xii Chapter 7 Obtaining Information at Run-time 123 Process Identification 123 User Identification 123 User IDs 125 Group IDs 126 System Identification 132 Date and Time 133 The time() Function 133 133 The localtime() and gmtime() Functions 133 The mktime() Function 135 The strftime() Function 135 The asctime() and ctime() Functions 137 The difftime() Function 137 The clock() and times() Functions 137 Environment Variables 138 The getenv() Function 139 The sysconf() Function 140 The pathconf() and fpathconf() Functions 142 Portability Lab 143 Chapter 8 Terminal I/0 145 Terminal Concepts 146 Setting Terminal Parameters 147 The tcsetattr() and tcgetattr() Functions 147 The termios Structure 148 System V termio and POSIX termios Structures 149 Example: Reading a Password 150 Input Processing 152 Output Processing 152 Modem Control 153 Non-Canonical I/O 153 Input Modes 153 Output Modes 154 Control Modes 155 Local Modes 155 155 Control Characters 156 Speed Storing Functions 158 Page xiii Line Control Functions 160 The tcsendbreak() Function 160 The tcdrain() Function 160 The tcflush( Function 160 The tcflow() Function 161 Avoiding Pitfalls 161 Example: Computer-to-Computer Communications 162 Process Groups and Job Control 166 Process Groups 167 Foreground Process 167 Background Process 167 Session 167 Controlling Terminal 168 Get/Set Process Group 168 The setsid() Function 168 The setpgid() Function 168 The tcsetpgrp() Function 169 Portability Lab 169 Chapter 9 POSIX and Standard C 171 Common Usage C 171 Standard C 171 Getting Standard C 171 171 The Standard C Preprocessor 172 Translation Phases 172 Macro Replacement 172 Conversion of Macro Arguments to Strings 173 Token Pasting 173 New Directives 174 Namespace Issues 174 Names Reserved by the C Language 174 Names Reserved by Header Files 175 C Library Functions 176 POSIX Library Functions 177 Avoiding Pitfalls 177 Page xiv Function Prototypes 178 Avoiding Pitfalls 179 Writing New Programs 180 Maintaining Old Programs