0intro.3 (9892B)
1 .TH INTRO 3 2 .SH NAME 3 intro \- introduction to library functions 4 .SH SYNOPSIS 5 .nf 6 .B #include <u.h> 7 .PP 8 .B #include \fIany Unix headers\fR 9 .PP 10 .B #include <libc.h> 11 .PP 12 .B #include <auth.h> 13 .PP 14 .B #include <bio.h> 15 .PP 16 .B #include <draw.h> 17 .PP 18 .B #include <fcall.h> 19 .PP 20 .B #include <frame.h> 21 .PP 22 .B #include <mach.h> 23 .PP 24 .B #include <regexp.h> 25 .PP 26 .B #include <thread.h> 27 .fi 28 .SH DESCRIPTION 29 This section describes functions 30 in various libraries. 31 For the most part, each library is defined by a single C include 32 file, such as those listed above, and a single archive file containing 33 the library proper. The name of the archive is 34 .BI \*9/lib/lib x .a \f1, 35 where 36 .I x 37 is the base of the include file name, stripped of a leading 38 .B lib 39 if present. 40 For example, 41 .B <draw.h> 42 defines the contents of library 43 .BR \*9/lib/libdraw.a , 44 which may be abbreviated when named to the loader as 45 .BR -ldraw . 46 In practice, each include file contains a magic pragma 47 that directs the loader to pick up the associated archive 48 automatically, so it is rarely necessary to tell the loader 49 which 50 libraries a program needs; 51 see 52 .MR 9c (1) . 53 .PP 54 The library to which a function belongs is defined by the 55 header file that defines its interface. 56 The `C library', 57 .IR libc , 58 contains most of the basic subroutines such 59 as 60 .IR strlen . 61 Declarations for all of these functions are 62 in 63 .BR <libc.h> , 64 which must be preceded by 65 .RI ( needs ) 66 an include of 67 .BR <u.h> . 68 The graphics library, 69 .IR draw , 70 is defined by 71 .BR <draw.h> , 72 which needs 73 .B <libc.h> 74 and 75 .BR <u.h> . 76 The Buffered I/O library, 77 .IR libbio , 78 is defined by 79 .BR <bio.h> , 80 which needs 81 .B <libc.h> 82 and 83 .BR <u.h> . 84 The ANSI C Standard I/O library, 85 .IR libstdio , 86 is defined by 87 .BR <stdio.h> , 88 which needs 89 .BR <u.h> . 90 There are a few other, less commonly used libraries defined on 91 individual pages of this section. 92 .PP 93 The include file 94 .BR <u.h> , 95 a prerequisite of several other include files, 96 declares the architecture-dependent and -independent types, including: 97 .IR uchar , 98 .IR ushort , 99 and 100 .IR ulong , 101 the unsigned integer types; 102 .IR schar , 103 the signed char type; 104 .I vlong 105 and 106 .IR uvlong , 107 the signed and unsigned very long integral types; 108 .IR Rune , 109 the Unicode character type; 110 .IR u8int , 111 .IR u16int , 112 .IR u32int , 113 and 114 .IR u64int , 115 the unsigned integral types with specific widths; 116 .IR jmp_buf , 117 the type of the argument to 118 .I setjmp 119 and 120 .IR longjmp , 121 plus macros that define the layout of 122 .IR jmp_buf 123 (see 124 .MR setjmp (3) ); 125 .\" definitions of the bits in the floating-point control register 126 .\" as used by 127 .\" .IR getfcr (2); 128 and 129 the macros 130 .B va_arg 131 and friends for accessing arguments of variadic functions (identical to the 132 macros defined in 133 .B <stdarg.h> 134 in ANSI C). 135 .PP 136 Plan 9 and Unix use many similarly-named functions for different purposes: 137 for example, Plan 9's 138 .I dup 139 is closer to (but not exactly) Unix's 140 .IR dup2 . 141 To avoid name conflicts, 142 .B <libc.h> 143 defines many of these names as preprocessor macros to add a 144 .I p9 145 prefix, 146 so that 147 .I dup 148 becomes 149 .IR p9dup . 150 To disable this renaming, 151 .B #define 152 .B NOPLAN9DEFINES 153 before including 154 .BR <libc.h> . 155 If Unix headers must be included in a program, 156 they should be included after 157 .BR <u.h> , 158 which sets important preprocessor directives 159 (for example, to enable 64-bit file offsets), 160 but before 161 .BR <libc.h> , 162 to avoid renaming problems. 163 .SS "Name space 164 Files are collected into a hierarchical organization called a 165 .I "file tree 166 starting in a 167 .I directory 168 called the 169 .IR root . 170 File names, also called 171 .IR paths , 172 consist of a number of 173 .BR / -separated 174 .I "path elements" 175 with the slashes corresponding to directories. 176 A path element must contain only printable 177 characters (those outside the control spaces of 178 .SM ASCII 179 and Latin-1). 180 A path element cannot contain a slash. 181 .PP 182 When a process presents a file name to Plan 9, it is 183 .I evaluated 184 by the following algorithm. 185 Start with a directory that depends on the first 186 character of the path: 187 .L / 188 means the root of the main hierarchy, 189 and anything else means the process's current working directory. 190 Then for each path element, look up the element 191 in the directory, advance to that directory, 192 do a possible translation (see below), and repeat. 193 The last step may yield a directory or regular file. 194 .SS "File I/O" 195 Files are opened for input or output 196 by 197 .I open 198 or 199 .I create 200 (see 201 .MR open (3) ). 202 These calls return an integer called a 203 .IR "file descriptor" 204 which identifies the file 205 to subsequent I/O calls, 206 notably 207 .MR read (3) 208 and 209 .IR write . 210 The system allocates the numbers by selecting the lowest unused descriptor. 211 They are allocated dynamically; there is no visible limit to the number of file 212 descriptors a process may have open. 213 They may be reassigned using 214 .MR dup (3) . 215 File descriptors are indices into a 216 kernel resident 217 .IR "file descriptor table" . 218 Each process has an associated file descriptor table. 219 In threaded programs 220 (see 221 .MR thread (3) ), 222 the file descriptor table is shared by all the procs. 223 .PP 224 By convention, 225 file descriptor 0 is the standard input, 226 1 is the standard output, 227 and 2 is the standard error output. 228 With one exception, the operating system is unaware of these conventions; 229 it is permissible to close file 0, 230 or even to replace it by a file open only for writing, 231 but many programs will be confused by such chicanery. 232 The exception is that the system prints messages about broken processes 233 to file descriptor 2. 234 .PP 235 Files are normally read or written in sequential order. 236 The I/O position in the file is called the 237 .IR "file offset" 238 and may be set arbitrarily using the 239 .MR seek (3) 240 system call. 241 .PP 242 Directories may be opened like regular files. 243 Instead of reading them with 244 .MR read (3) , 245 use the 246 .B Dir 247 structure-based 248 routines described in 249 .MR dirread (3) . 250 The entry 251 corresponding to an arbitrary file can be retrieved by 252 .IR dirstat 253 (see 254 .MR stat (3) ) 255 or 256 .IR dirfstat ; 257 .I dirwstat 258 and 259 .I dirfwstat 260 write back entries, thus changing the properties of a file. 261 .PP 262 New files are made with 263 .I create 264 (see 265 .MR open (3) ) 266 and deleted with 267 .MR remove (3) . 268 Directories may not directly be written; 269 .IR create , 270 .IR remove , 271 .IR wstat , 272 and 273 .I fwstat 274 alter them. 275 .PP 276 .MR Pipe (3) 277 creates a connected pair of file descriptors, 278 useful for bidirectional local communication. 279 .SS "Process execution and control" 280 A new process is created 281 when an existing one calls 282 .MR fork (2) . 283 The new (child) process starts out with 284 copies of the address space and most other attributes 285 of the old (parent) process. 286 In particular, 287 the child starts out running 288 the same program as the parent; 289 .MR exec (3) 290 will bring in a different one. 291 .PP 292 Each process has a unique integer process id; 293 a set of open files, indexed by file descriptor; 294 and a current working directory 295 (changed by 296 .MR chdir (2) ). 297 .PP 298 Each process has a set of attributes \(em memory, open files, 299 name space, etc. \(em that may be shared or unique. 300 Flags to 301 .IR rfork 302 control the sharing of these attributes. 303 .PP 304 A process terminates by calling 305 .MR exits (3) . 306 A parent process may call 307 .MR wait (3) 308 to wait for some child to terminate. 309 A bit of status information 310 may be passed from 311 .I exits 312 to 313 .IR wait . 314 On Plan 9, the status information is an arbitrary text string, 315 but on Unix it is a single integer. 316 The Plan 9 interface persists here, although the functionality does not. 317 Instead, empty strings are converted to exit status 0 and non-empty strings to 1. 318 .PP 319 A process can go to sleep for a specified time by calling 320 .MR sleep (3) . 321 .PP 322 There is a 323 .I notification 324 mechanism for telling a process about events such as address faults, 325 floating point faults, and messages from other processes. 326 A process uses 327 .MR notify (3) 328 to register the function to be called (the 329 .IR "notification handler" ) 330 when such events occur. 331 .SS Multithreading 332 Where possible according to the ANSI C standard, 333 the main C library works properly in multiprocess programs; 334 .IR malloc , 335 .IR print , 336 and the other routines use locks (see 337 .MR lock (3) ) 338 to synchronize access to their data structures. 339 The graphics library defined in 340 .B <draw.h> 341 is also multi-process capable; details are in 342 .MR graphics (3) . 343 In general, though, multiprocess programs should use some form of synchronization 344 to protect shared data. 345 .PP 346 The thread library, defined in 347 .BR <thread.h> , 348 provides support for multiprocess programs. 349 It includes a data structure called a 350 .B Channel 351 that can be used to send messages between processes, 352 and coroutine-like 353 .IR threads , 354 which enable multiple threads of control within a single process. 355 The threads within a process are scheduled by the library, but there is 356 no pre-emptive scheduling within a process; thread switching occurs 357 only at communication or synchronization points. 358 .PP 359 Most programs using the thread library 360 comprise multiple processes 361 communicating over channels, and within some processes, 362 multiple threads. Since I/O calls may block, a system 363 call may block all the threads in a process. 364 Therefore, a program that shouldn't block unexpectedly will use a process 365 to serve the I/O request, passing the result to the main processes 366 over a channel when the request completes. 367 For examples of this design, see 368 .MR ioproc (3) 369 or 370 .MR mouse (3) . 371 .SH SEE ALSO 372 .IR nm (1), 373 .MR 9c (1) 374 .SH DIAGNOSTICS 375 Math functions in 376 .I libc 377 return 378 special values when the function is undefined for the 379 given arguments or when the value is not representable 380 (see 381 .MR nan (3) ). 382 .PP 383 Some of the functions in 384 .I libc 385 are system calls and many others employ system calls in their implementation. 386 All system calls return integers, 387 with \-1 indicating that an error occurred; 388 .MR errstr (3) 389 recovers a string describing the error. 390 Some user-level library functions also use the 391 .I errstr 392 mechanism to report errors. 393 Functions that may affect the value of the error string are said to ``set 394 .IR errstr ''; 395 it is understood that the error string is altered only if an error occurs.