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