INTRO(2) INTRO(2)
NAME
intro - introduction to library functions
SYNOPSIS
#include <u.h>
#include <libc.h>
#include <stdio.h>
#include <bio.h>
#include <libg.h>
#include <gnot.h>
#include <frame.h>
#include <layer.h>
#include <regexp.h>
DESCRIPTION
This section describes functions in various libraries. For
the most part, each library is defined by a single C include
file, 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, <libg.h> defines the contents of library
/$objtype/lib/libg.a which may be abbreviated when named to
the loader as -lg . In practice, 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 identified by the
section number at the top of the manual page:
(2) These functions constitute the `C library', libc, con-
taining most of the basic non-system call subroutines
such as strlen . Declarations for all of these func-
tions are in <libc.h>, which must be preceded by
(needs) an include of <u.h>.
(2G) These functions constitute the library libg, the graph-
ics library. Declarations for these functions are in
<libg.h>, which needs <libc.h> and <u.h>.
(2S) These functions constitute the library libstdio, the
Page 1 Plan 9 (printed 12/21/24)
INTRO(2) INTRO(2)
`standard I/O package' (see fgetc(2)). Declarations for
these functions are in <stdio.h>.
(2X) Various specialized libraries have not been given dis-
tinctive captions. Files in which such libraries are
found are named on appropriate pages.
The include file <u.h>, a prerequisite of several other
include files, declares the architecture-dependent and
-independent types, including: ushort, uchar, and ulong, the
unsigned integer types; schar, the signed char type; vlong,
a very long integral type; 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);
Length, a union giving different views of the 64-bit length
of a file, declared as
typedef union
{
char clength[8];
vlong vlength;
struct
{
long hlength; /* high order */
long length; /* low order */
};
} Length;
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 that
occupy no more than NAMELEN-1 bytes. A path element cannot
contain a space or slash.
When a process presents a file name to Plan 9, it is
evaluated by the following algorithm. Start with a direc-
tory 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
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 transla-
tion (see below) and repeat. The last step may yield a
directory or regular file. The collection of files reach-
able 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,
Page 2 Plan 9 (printed 12/21/24)
INTRO(2) INTRO(2)
evaluation instead continues 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. Using bind
and mount to do name space adjustment affects only the cur-
rent 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. File descriptors range
from 0 to 99 in the current system. The system allocates
the numbers by selecting the lowest unused descriptor. 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 table. 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 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 pro-
grams will be confused by such chicanery. The exception is
that the system prints messages about broken processes to
file descriptor 2.
Files are normally read or written in sequential order. The
I/O position 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 contain an integral number of records, called directory
entries, of length DIRLEN (defined in <libc.h>). Each entry
is a machine-independent representation of the information
about an existing file in the directory, including the name,
ownership, permission, 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 trans-
lated into a more convenient, addressable form called a Dir
structure; dirstat, dirfstat, dirwstat, and dirfwstat exe-
cute the appropriate translations (see stat(2)).
New files are made with create (in open(2)) and deleted with
remove(2). Directories may not directly be written; create,
remove, wstat, and fwstat alter them.
Page 3 Plan 9 (printed 12/21/24)
INTRO(2) INTRO(2)
Pipe(2) creates a connected pair of file descriptors, useful
for local communication.
Process execution and control
A new process is created when an existing one calls rfork
with the RFPROC 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 running the
same program as the parent; exec(2) will bring in a differ-
ent one.
Each process has a unique integer process id; a set of open
files, indexed 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 sharing of these attributes.
A process terminates by calling exits(2). A parent process
may call wait (in exits(2)) to wait for some child to termi-
nate. A string of status information 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.
SEE ALSO
nm(1), 2l(1), 2c(1)
DIAGNOSTICS
Math functions in libc will return special values when the
function is undefined 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 oth-
ers employ system calls in their implementation. All system
calls return integers, with -1 indicating that an error
occurred; errstr(2) recovers a string describing the error.
Functions that may affect the value of the error string are
said to ``set errstr''; it is understood that the error
string is altered only if an error occurs.
Page 4 Plan 9 (printed 12/21/24)