Porting Unix Software

Porting UNIX Software

From Download to Debug

By Greg Lehey

Chapter 0 Preface i
Audience ii
Organization ii
Operating System Versions ii
Conventions used in this book iii
Describing the keyboard iv
Terminology iv
Acknowledgements v
Part I 1
Chapter 1 Introduction 1
What is porting? 1
How long does it take? 2
Why we need to port 3
Unix flavours 3
Where you fit in 8
But can I do it? 8
How to use this book 9
Part 2 10
Preparations 11
Chapter 2 Unpacking the goodies 13
Getting the sources 13
Software from the Internet 13
Choice of archive medium 14
Archives 14
Archive programs 15
Living with tar 15
Compression programs 20
Encoded files 20
Split archives 21
What's that archive? 21
Identifying archives 23
What's in that archive? 25
README 25
INSTALL file 26
Other files 27
Chapter 3 Care and feeding of source trees 29
Updating old archives 29
Patch 30
Pruning the tree 38
Save the cleaned archive 39
Handling trees on CD-ROM 39
Link trees 39
Object links on CD-ROM 41
Tracking changes to the tree 42
Timestamps 42
cmp 44
An example—updating an existing tree 45
Chapter 4 Package configuration 47
Installation paths 48
Preferred tools 49
Conveying configuration information 49
What do I need to change? 52
Creating configuration information 52
Multiple Makefile targets 53
Manual configuration 53
Configuration scripts 54
GNU package configuration 55
imake 56
Chapter 5 Building the package 59
Preparation 59
Make sure you have enough space 59
Use a windowing system 59
Keep a log file 60
Save make output 61
Standard targets 62
make depend 62
make all 62
make install 63
make clean 63
make stamp-halfway 63
Problems running make 63
Missing Makefile or targets 64
Missing targets 66
make doesn't understand the Makefile 66
make refers to non-existent files 67
Problems with subordinate makes 68
make doesn't rebuild correctly 68
Incorrect dependencies 68
No dependency on Makefile 68
Other errors from make 69
Trailing blanks in variables 69
Comments in command lists 69
make forgets the current directory 70
Missing separator - stop 70
Commands commence before first target 70
Syntax errors from the shell 71
Circular dependency dropped 71
Nonsensical targets 71
Unable to stop make 71
Problems with make clean 72
Subordinate makes 72
Incorrect continuation lines 73
Prompts in Makefiles 74
Arg list too long 74
Modifying Makefiles 76
Chapter 6 Running the compiler 77
Compiler warnings 77
Implicit return type 79
Inconsistent function returns 79
Uninitialized variables 80
Signed comparisons of unsigned values 80
Character subscripts to arrays 80
Dequalifying types 81
Increasing alignment requirements 81
Implicit conversions between enums 82
Incomplete switch statements 82
long indices for switch 82
Changing non-volatile automatic variables 82
Invalid keyword sequences in declarations 83
Trigraphs 83
Nested comments 83
Missing parentheses 83
Functions with embedded extern definitions 84
Compiler errors 84
Undefined symbols 84
Conflicts between preprocessor and compiler variables 85
Other preprocessors 88
Syntax errors 88
Virtual memory exhausted 89
Compiler limits exceeded 89
Running compiler passes individually 89
Incorrect code from compiler 90
Chapter 7 Documentation 91
Preformatted documentation 91
PostScript 92
.dvi format 94
Format conversion 94
roff and friends 94
formatting with nroff or troff 95
Other roff-related programs 98
Man pages 99
man history 99
TeX 101
GNU Info and Texinfo 103
The World-Wide Web 103
Chapter 8 Testing the results 105
What makes ported programs fail? 105
A strategy for testing 106
Symbolic debuggers 107
Libraries and debugging information 109
Limitations of debuggers 119
Tracing system calls 120
trace 120
ktrace 122
truss 123
Tracing through fork 124
Tracing network traffic 124
Chapter 9 Installation 125
make install 126
Configuring the installed package 127
Installing the correct files 127
To replace or not to replace? 127
Updating 128
install 128
Installing documentation 130
Man pages. 130
GNU info 132
Removing installed software 133
Removing software manually 133
Removing too much 137
Keeping track of installed software 137
System V pkgadd 138
pkginfo 138
pkgmap 138
Package subdirectories 139
pkgadd 140
Removing packages 140
Making installable packages 140
Making a prototype file 141
Running pkgmk 142
Chapter 10 Where to go from here 143
Reporting modifications 143
diff 144
Saving the archive 148
Not done after all? 148
Part II Platform dependencies 151
Software Dependencies 151
Chapter 11 Hardware dependencies 153
Data types 153
Integer sizes 153
Floating point types 154
Pointer size 155
Address space 155
Character order 156
Data alignment 158
Instruction alignment 160
Chapter 12 Kernel dependencies 161
Interprocess communication 162
Pipes 163
Sockets 163
Other kinds of pipe 164
System V IPC 165
Miscellaneous system functionality 168
exec 168
getrlimit and setrlimit 169
Process groups 171
Real and effective user IDs 172
vfork 174
wait and friends 175
waitpid 176
wait3 and wait4 177
Chapter 13 Signals 179
Supported signals 180
Unreliable and reliable signals 181
Signal handlers 183
System V.4 signal handlers 183
BSD signal handlers 185
SIGCLD and SIGCHLD 186
Interrupted system calls 186
Calling functions from signal handlers 187
Current signal implementations 188
Seventh Edition signal function 188
BSD signal functions 188
System V signal functions 191
POSIX.1 signal functions 192
Signals under Linux 196
Other signal-related functions 196
sigstack and sigaltstack 196
setjmp and longjmp 197
kill 200
killpg 201
raise 201
sys_siglist and psignal 201
Chapter 14 File systems 203
File system structures 204
The Berkeley Fast File System 204
Other file systems 205
Function calls 206
chsize 206
dup2 207
fchdir and friends 207
fcntl 207
getdents and getdirentries 209
getdtablesize 210
ioctl 211
lstat 211
ltrunc 211
mkdir and rmdir 211
open 212
pathconf and fpathconf 212
read 213
rename 213
revoke 213
readdir and friends 213
readv and writev 215
statfs and statvfs 216
symlink 218
sysfs 218
truncate and ftruncate 218
ustat 219
utime and utimes 219
Non-blocking I/O 220
select 220
poll 223
rdchk 224
SIGPOLL 225
SIGIO 225
File locking 226
Lock files 227
locking system call 228
flock 229
fcntl locking 229
lockf 231
Which locking scheme? 231
Memory-mapped files 232
mmap 232
msync 233
munmap 234
Chapter 15 Terminal Drivers 235
Typical terminal code 236
Terminology 237
Terminal data structures 239
Old terminal driver definitions 239
termio and termios structures 241
Terminal driver modes 249
Canonical mode 249
Non-canonical mode 249
Raw mode 250
Cooked mode 250
Cbreak mode 250
Emulating old terminal driver modes 250
gtty and stty 251
The Linux terminal driver 251
ioctl 252
ioctl request codes 252
Terminal ioctls 254
Terminal attributes 256
Hardware control 260
Queue control 262
Session control 263
Miscellaneous functions 264
termios functions 265
Direct termios functions 265
termios auxiliary functions 267
Chapter 16 Timekeeping 269
Difficult to use 270
Implementations differ 270
Differing time formats 270
Daylight Savings Time 271
National time formats 271
Global timekeeping variables 271
Getting the current time 272
time 272
ftime 272
gettimeofday 273
Setting the current time 274
adjtime 274
settimeofday 274
stime 274
Converting time values 274
strftime 275
strptime 275
ascftime 275
asctime and asctime_r 275
cftime 276
ctime and ctime_r 276
dysize 276
gmtime and gmtime_r 277
localtime and localtime_r 277
mktime 277
timegm 278
timelocal 278
difftime 278
timezone 278
tzset 278
tzsetwall 279
Suspending process execution 279
nap 279
setitimer 279
sleep 281
usleep 281
select and poll 281
Chapter 17 Header files 283
ANSI C, POSIX.1, and header files 283
ANSI and POSIX.1 restrictions 285
Declarations for C++ 285
ANSI header files 288
Type information 288
Classes of header files 289
/usr/include/sys 289
Problems with header files 290
Chapter 18 Function libraries 293
Standard library functionality 293
alloca 293
bcopy 294
bzero 294
fnmatch 294
getcwd and getwd 295
gethostname and uname 295
index 296
malloc 296
memmove 296
remove 297
rindex 297
snprintf and vsnprintf 297
strcasecmp and strncasecmp 297
strdup 298
strerror and sys_errlist 298
stricmp and strnicmp 299
Block memory access functions 299
Regular expression routines 300
regexpr 301
regcmp 302
regex: re_comp and re_exec 303
Eighth edition regexp 304
POSIX.2 regex 305
termcap and terminfo 307
termcap 308
Problems with termcap 312
terminfo 313
printcap 316
Chapter 19 Make 317
Terminology 317
Additional make features 318
Internal variables 318
Variables with special meanings 318
Special targets 319
include directive 320
Conditional execution 320
Other forms of variable assignment 321
Functions 322
Multiple targets 323
BSD make 323
Additional rule delimiter 323
Assignment operators 323
Variables 324
Variable substitution 325
Special sources 327
Specifying dependencies 327
BSD Makefile configuration system 327
Chapter 20 Compilers 337
The C language 337
Kernighan and Ritchie 338
UNIX C 338
ANSI C 340
Differences in the ANSI C preprocessor 342
Assertions 344
C++ 345
Other C dialects 346
Intel 8086 memory models 346
Other differences in MS-DOS 347
Compiler organization 348
Other compiler organizations 350
The C preprocessor 350
Which compiler to use 350
Chapter 21 Object files and friends 353
Object formats 354
The assembler 358
Assembler syntax 358
Assembler symbols 359
Relocation information 362
String table and name list 363
Examining symbol tables: the nm program 364
Debugging information 367
The linker 368
Function libraries 369
Library search 369
Shared libraries 370
Other linker input 371
Merging relocatable files 372
Problems with the link editor 372
Dumping to object files 376
Process initialization and stack frames 377
Stack frames 377
Setting up the initial parameters 378
Initializing C++ programs 380
Stack growth during function calls 381
Object Archive formats 383
Appendix A Comparative reference to UNIX data types 385
Appendix B Compiler options 391
compiler options 391
C compiler options 391
gcc dialect options 405
gcc debugging options 407
gcc warning options 407
cpp options 410
Appendix C Assembler directives and options 415
as options 415
as directives 417
Debug information 421
Appendix D Linker options 423
Appendix E Where to get sources 431
CD-ROM producers 431
Appendix F Bibliography 435