term% cat index.txt INTRO(2) System Calls Manual INTRO(2)
NAME
intro - introduction to library functions
SYNOPSIS
#include <u.h>
#include <libc.h>
#include <auth.h>
#include <bio.h>
#include <draw.h>
#include <fcall.h>
#include <frame.h>
#include <mach.h>
#include <ndb.h>
#include <regexp.h>
#include <stdio.h>
#include <thread.h>
DESCRIPTION
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 /$objtype/lib/libx.a, where x is the base of
the include file name, stripped of a leading lib if present. For exam‐
ple, <draw.h> defines the contents of library /$objtype/lib/libdraw.a,
which may be abbreviated when named to the loader as -ldraw. In prac‐
tice, each include file contains a #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.
The library to which a function belongs is defined by the header file
that defines its interface. The `C library', libc, contains most of
the basic subroutines such as strlen. Declarations for all of these
functions are in <libc.h>, which must be preceded by (needs) an include
of <u.h>. The graphics library, draw, is defined by <draw.h>, which
needs <libc.h> and <u.h>. The Buffered I/O library, libbio, is defined
by <bio.h>, which needs <libc.h> and <u.h>. The ANSI C Standard I/O
library, libstdio, is defined by <stdio.h>, which needs <u.h>. There
are a few other, less commonly used libraries defined on individual
pages of this section.
The include file <u.h>, a prerequisite of several other include files,
declares the architecture-dependent and -independent types, including:
uchar, ushort, uint, and ulong, the unsigned integer types; schar, the
signed char type; vlong and uvlong, the signed and unsigned very long
integral types; Rune, the Unicode character type; u8int, u16int,
u32int, and u64int, the unsigned integral types with specific widths;
uintptr, the unsigned integral type with the same width as a pointer;
jmp_buf, the type of the argument to setjmp and longjmp, plus macros
that define the layout of jmp_buf (see setjmp(2)); definitions of the
bits in the floating-point control register as used by getfcr(2); and
the macros va_arg and friends for accessing arguments of variadic func‐
tions (identical to the macros defined in <stdarg.h> in ANSI C).
Name space
Files are collected into a hierarchical organization called a file tree
starting in a directory called the root. File names, also called
paths, consist of a number of /-separated path elements 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.
When a process presents a file name to Plan 9, it is evaluated by the
following algorithm. Start with a directory that depends on the first
character of the path: means the root of the main hierarchy, means the
separate root of a kernel device's file tree (see Section 3), and any‐
thing 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. The collection of
files reachable from the root is called the name space of a process.
A program can use bind or mount (see bind(2)) to say that whenever a
specified file is reached during evaluation, evaluation instead contin‐
ues from a second specified file. Also, the same system calls create
union directories, which are concatenations of ordinary directories
that are searched sequentially until the desired element is found. Us‐
ing bind and mount to do name space adjustment affects only the current
process group (see below). Certain conventions about the layout of the
name space should be preserved; see namespace(4).
File I/O
Files are opened for input or output by open or create (see open(2)).
These calls return an integer called a file descriptor which identifies
the file to subsequent I/O calls, notably read(2) and write. The sys‐
tem 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 dup(2). File descriptors are indices into a kernel resident file
descriptor table. Each process has an associated file descriptor ta‐
ble. In some cases (see rfork in fork(2)) a file descriptor table may
be shared by several processes.
By convention, file descriptor 0 is the standard input, 1 is the stan‐
dard 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 descrip‐
tor 2.
Files are normally read or written in sequential order. The I/O posi‐
tion in the file is called the file offset and may be set arbitrarily
using the seek(2) system call.
Directories may be opened and read much like regular files. They con‐
tain an integral number of records, called directory entries. Each en‐
try is a machine-independent representation of the information about an
existing file in the directory, including the name, ownership, permis‐
sion, access dates, and so on. The entry corresponding to an arbitrary
file can be retrieved by stat(2) or fstat; wstat and fwstat write back
entries, thus changing the properties of a file. An entry may be
translated into a more convenient, addressable form called a Dir struc‐
ture; dirstat, dirfstat, dirwstat, and dirfwstat execute the appropri‐
ate translations (see stat(2)).
New files are made with create (see open(2)) and deleted with re‐
move(2). Directories may not directly be written; create, remove,
wstat, and fwstat alter them.
The operating system kernel records the file name used to access each
open file or directory. If the file is opened by a local name (one
that does not begin / or #), the system makes the stored name absolute
by prefixing the string associated with the current directory. Similar
lexical adjustments are made for path names containing . (dot) or ..
(dot-dot). By this process, the system maintains a record of the route
by which each file was accessed. Although there is a possibility for
error—the name is not maintained after the file is opened, so removals
and renamings can confound it—this simple method usually permits the
system to return, via the fd2path(2) system call and related calls such
as getwd(2), a valid name that may be used to find a file again. This
is also the source of the names reported in the name space listing of
ns(1) or /dev/ns (see proc(3)).
Pipe(2) creates a connected pair of file descriptors, useful for bidi‐
rectional local communication.
Process execution and control
A new process is created when an existing one calls rfork with the RF‐
PROC bit set, usually just by calling fork(2). 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 run‐
ning the same program as the parent; exec(2) will bring in a different
one.
Each process has a unique integer process id; a set of open files, in‐
dexed by file descriptor; and a current working directory (changed by
chdir(2)).
Each process has a set of attributes — memory, open files, name space,
etc. — that may be shared or unique. Flags to rfork control the shar‐
ing of these attributes.
The memory of a process is divided into segments. Every program has at
least a text (instruction) and stack segment. Most also have an ini‐
tialized data segment and a segment of zero-filled data called bss.
Processes may segattach(2) other segments for special purposes.
A process terminates by calling exits(2). A parent process may call
wait(2) to wait for some child to terminate. A string of status infor‐
mation may be passed from exits to wait. A process can go to sleep for
a specified time by calling sleep(2).
There is a notification mechanism for telling a process about events
such as address faults, floating point faults, and messages from other
processes. A process uses notify(2) to register the function to be
called (the notification handler) when such events occur.
Multithreading
By calling rfork with the RFMEM bit set, a program may create several
independently executing processes sharing the same memory (except for
the stack segment, which is unique to each process). Where possible
according to the ANSI C standard, the main C library works properly in
multiprocess programs; malloc, print, and the other routines use locks
(see lock(2)) to synchronize access to their data structures. The
graphics library defined in <draw.h> is also multi-process capable; de‐
tails are in graphics(2). In general, though, multiprocess programs
should use some form of synchronization to protect shared data.
The thread library, defined in <thread.h>, provides support for multi‐
process programs. It includes a data structure called a Channel that
can be used to send messages between processes, and coroutine-like
threads, 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 switch‐
ing occurs only at communication or synchronization points.
Most programs using the thread library comprise multiple processes com‐
municating over channels, and within some processes, multiple threads.
Since Plan 9 I/O calls may block, a system call may block all the
threads in a process. Therefore, a program that shouldn't block unex‐
pectedly will use a process to serve the I/O request, passing the re‐
sult to the main processes over a channel when the request completes.
For examples of this design, see ioproc(2) or mouse(2).
SEE ALSO
nm(1), 2l(1), 2c(1)
DIAGNOSTICS
Math functions in libc return special values when the function is unde‐
fined for the given arguments or when the value is not representable
(see nan(2)).
Some of the functions in libc are system calls and many others employ
system calls in their implementation. All system calls return inte‐
gers, with -1 indicating that an error occurred; errstr(2) recovers a
string describing the error. Some user-level library functions also
use the errstr mechanism to report errors. Functions that may affect
the value of the error string are said to ``set errstr''; it is under‐
stood that the error string is altered only if an error occurs.
INTRO(2)