t0intro.3 - plan9port - [fork] Plan 9 from user space
(HTM) git clone git://src.adamsgaard.dk/plan9port
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
t0intro.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.