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