3 intro \- introduction to library functions
24 .B #include <regexp.h>
28 .B #include <thread.h>
31 This section describes functions
33 For the most part, each library is defined by a single C include
34 file, such as those listed above, and a single archive file containing
35 the library proper. The name of the archive is
36 .BI /$objtype/lib/lib x .a \f1,
39 is the base of the include file name, stripped of a leading
44 defines the contents of library
45 .BR /$objtype/lib/libdraw.a ,
46 which may be abbreviated when named to the loader as
48 In practice, each include file contains a
50 that directs the loader to pick up the associated archive
51 automatically, so it is rarely necessary to tell the loader
53 libraries a program needs.
55 The library to which a function belongs is defined by the
56 header file that defines its interface.
59 contains most of the basic subroutines such
62 Declarations for all of these functions are
65 which must be preceded by
77 The Buffered I/O library,
85 The ANSI C Standard I/O library,
91 There are a few other, less commonly used libraries defined on
92 individual pages of this section.
96 a prerequisite of several other include files,
97 declares the architecture-dependent and -independent types, including:
103 the unsigned integer types;
105 the signed char type;
109 the signed and unsigned very long integral types;
111 the Unicode character type;
117 the unsigned integral types with specific widths;
119 the unsigned integral type with the same width as a pointer;
121 the type of the argument to
125 plus macros that define the layout of
129 definitions of the bits in the floating-point control register
135 and friends for accessing arguments of variadic functions (identical to the
140 Files are collected into a hierarchical organization called a
146 File names, also called
148 consist of a number of
151 with the slashes corresponding to directories.
152 A path element must contain only printable
153 characters (those outside the control spaces of
156 A path element cannot contain a slash.
158 When a process presents a file name to Plan 9, it is
160 by the following algorithm.
161 Start with a directory that depends on the first
162 character of the path:
164 means the root of the main hierarchy,
166 means the separate root of a kernel device's file tree (see Section 3),
167 and anything else means the process's current working directory.
168 Then for each path element, look up the element
169 in the directory, advance to that directory,
170 do a possible translation (see below), and repeat.
171 The last step may yield a directory or regular file.
172 The collection of files reachable from the root is called the
182 to say that whenever a specified file is reached during evaluation,
183 evaluation instead continues from a second specified file.
184 Also, the same system calls create
185 .IR "union directories" ,
186 which are concatenations of ordinary directories
187 that are searched sequentially until the desired element is found.
192 to do name space adjustment affects only
193 the current process group (see below).
194 Certain conventions about the layout of the name space should
198 Files are opened for input or output
205 These calls return an integer called a
206 .IR "file descriptor"
207 which identifies the file
208 to subsequent I/O calls,
213 The system allocates the numbers by selecting the lowest unused descriptor.
214 They are allocated dynamically; there is no visible limit to the number of file
215 descriptors a process may have open.
216 They may be reassigned using
218 File descriptors are indices into a
220 .IR "file descriptor table" .
221 Each process has an associated file descriptor table.
226 a file descriptor table may be shared by several processes.
229 file descriptor 0 is the standard input,
230 1 is the standard output,
231 and 2 is the standard error output.
232 With one exception, the operating system is unaware of these conventions;
233 it is permissible to close file 0,
234 or even to replace it by a file open only for writing,
235 but many programs will be confused by such chicanery.
236 The exception is that the system prints messages about broken processes
237 to file descriptor 2.
239 Files are normally read or written in sequential order.
240 The I/O position in the file is called the
242 and may be set arbitrarily using the
246 Directories may be opened and read much like regular files.
247 They contain an integral number of records, called
248 .IR "directory entries" .
249 Each entry is a machine-independent representation of
250 the information about an existing file in the directory,
251 including the name, ownership,
256 corresponding to an arbitrary file can be retrieved by
263 write back entries, thus changing the properties of a file.
264 An entry may be translated into a more convenient, addressable
273 execute the appropriate translations (see
276 New files are made with
282 Directories may not directly be written;
290 The operating system kernel records the file name used to access each open file or directory.
291 If the file is opened by a local name (one that does not begin
295 the system makes the stored name absolute by prefixing
296 the string associated with the current directory.
297 Similar lexical adjustments are made for path names containing
302 By this process, the system maintains a record of the route by which each file was accessed.
303 Although there is a possibility for error\(emthe name is not maintained after the file is opened,
304 so removals and renamings can confound it\(emthis simple method usually
305 permits the system to return, via the
307 system call and related calls such as
309 a valid name that may be used to find a file again.
310 This is also the source of the names reported in the name space listing of
318 creates a connected pair of file descriptors,
319 useful for bidirectional local communication.
320 .SS "Process execution and control"
321 A new process is created
322 when an existing one calls
326 bit set, usually just by calling
328 The new (child) process starts out with
329 copies of the address space and most other attributes
330 of the old (parent) process.
332 the child starts out running
333 the same program as the parent;
335 will bring in a different one.
337 Each process has a unique integer process id;
338 a set of open files, indexed by file descriptor;
339 and a current working directory
343 Each process has a set of attributes \(em memory, open files,
344 name space, etc. \(em that may be shared or unique.
347 control the sharing of these attributes.
349 The memory of a process is divided into
351 Every program has at least a
356 Most also have an initialized
358 segment and a segment of zero-filled data called
362 other segments for special purposes.
364 A process terminates by calling
366 A parent process may call
368 to wait for some child to terminate.
369 A string of status information
374 A process can go to sleep for a specified time by calling
379 mechanism for telling a process about events such as address faults,
380 floating point faults, and messages from other processes.
383 to register the function to be called (the
384 .IR "notification handler" )
385 when such events occur.
391 bit set, a program may create several independently executing processes sharing the same
392 memory (except for the stack segment, which is unique to each process).
393 Where possible according to the ANSI C standard,
394 the main C library works properly in multiprocess programs;
397 and the other routines use locks (see
399 to synchronize access to their data structures.
400 The graphics library defined in
402 is also multi-process capable; details are in
404 In general, though, multiprocess programs should use some form of synchronization
405 to protect shared data.
407 The thread library, defined in
409 provides support for multiprocess programs.
410 It includes a data structure called a
412 that can be used to send messages between processes,
415 which enable multiple threads of control within a single process.
416 The threads within a process are scheduled by the library, but there is
417 no pre-emptive scheduling within a process; thread switching occurs
418 only at communication or synchronization points.
420 Most programs using the thread library
421 comprise multiple processes
422 communicating over channels, and within some processes,
423 multiple threads. Since Plan 9 I/O calls may block, a system
424 call may block all the threads in a process.
425 Therefore, a program that shouldn't block unexpectedly will use a process
426 to serve the I/O request, passing the result to the main processes
427 over a channel when the request completes.
428 For examples of this design, see
440 special values when the function is undefined for the
441 given arguments or when the value is not representable
445 Some of the functions in
447 are system calls and many others employ system calls in their implementation.
448 All system calls return integers,
449 with \-1 indicating that an error occurred;
451 recovers a string describing the error.
452 Some user-level library functions also use the
454 mechanism to report errors.
455 Functions that may affect the value of the error string are said to ``set
457 it is understood that the error string is altered only if an error occurs.