3 intro \- introduction to library functions
8 .B #include \fIany Unix headers\fR
24 .B #include <regexp.h>
26 .B #include <thread.h>
29 This section describes functions
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,
37 is the base of the include file name, stripped of a leading
42 defines the contents of library
43 .BR \*9/lib/libdraw.a ,
44 which may be abbreviated when named to the loader as
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
50 libraries a program needs;
54 The library to which a function belongs is defined by the
55 header file that defines its interface.
58 contains most of the basic subroutines such
61 Declarations for all of these functions are
64 which must be preceded by
76 The Buffered I/O library,
84 The ANSI C Standard I/O library,
90 There are a few other, less commonly used libraries defined on
91 individual pages of this section.
95 a prerequisite of several other include files,
96 declares the architecture-dependent and -independent types, including:
101 the unsigned integer types;
103 the signed char type;
107 the signed and unsigned very long integral types;
109 the Unicode character type;
115 the unsigned integral types with specific widths;
117 the type of the argument to
121 plus macros that define the layout of
125 .\" definitions of the bits in the floating-point control register
131 and friends for accessing arguments of variadic functions (identical to the
136 Plan 9 and Unix use many similarly-named functions for different purposes:
137 for example, Plan 9's
139 is closer to (but not exactly) Unix's
141 To avoid name conflicts,
143 defines many of these names as preprocessor macros to add a
150 To disable this renaming,
155 If Unix headers must be included in a program,
156 they should be included after
158 which sets important preprocessor directives
159 (for example, to enable 64-bit file offsets),
162 to avoid renaming problems.
164 Files are collected into a hierarchical organization called a
170 File names, also called
172 consist of a number of
175 with the slashes corresponding to directories.
176 A path element must contain only printable
177 characters (those outside the control spaces of
180 A path element cannot contain a slash.
182 When a process presents a file name to Plan 9, it is
184 by the following algorithm.
185 Start with a directory that depends on the first
186 character of the path:
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.
195 Files are opened for input or output
202 These calls return an integer called a
203 .IR "file descriptor"
204 which identifies the file
205 to subsequent I/O calls,
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
215 File descriptors are indices into a
217 .IR "file descriptor table" .
218 Each process has an associated file descriptor table.
222 the file descriptor table is shared by all the procs.
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.
235 Files are normally read or written in sequential order.
236 The I/O position in the file is called the
238 and may be set arbitrarily using the
242 Directories may be opened like regular files.
243 Instead of reading them with
248 routines described in
251 corresponding to an arbitrary file can be retrieved by
260 write back entries, thus changing the properties of a file.
262 New files are made with
268 Directories may not directly be written;
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
283 The new (child) process starts out with
284 copies of the address space and most other attributes
285 of the old (parent) process.
287 the child starts out running
288 the same program as the parent;
290 will bring in a different one.
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
298 Each process has a set of attributes \(em memory, open files,
299 name space, etc. \(em that may be shared or unique.
302 control the sharing of these attributes.
304 A process terminates by calling
306 A parent process may call
308 to wait for some child to terminate.
309 A bit of status information
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.
319 A process can go to sleep for a specified time by calling
324 mechanism for telling a process about events such as address faults,
325 floating point faults, and messages from other processes.
328 to register the function to be called (the
329 .IR "notification handler" )
330 when such events occur.
332 Where possible according to the ANSI C standard,
333 the main C library works properly in multiprocess programs;
336 and the other routines use locks (see
338 to synchronize access to their data structures.
339 The graphics library defined in
341 is also multi-process capable; details are in
343 In general, though, multiprocess programs should use some form of synchronization
344 to protect shared data.
346 The thread library, defined in
348 provides support for multiprocess programs.
349 It includes a data structure called a
351 that can be used to send messages between processes,
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.
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
378 special values when the function is undefined for the
379 given arguments or when the value is not representable
383 Some of the functions in
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;
389 recovers a string describing the error.
390 Some user-level library functions also use the
392 mechanism to report errors.
393 Functions that may affect the value of the error string are said to ``set
395 it is understood that the error string is altered only if an error occurs.
