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 <fcall.h>
#include <frame.h>
#include <layer.h>
#include <libg.h>
#include <mach.h>
#include <ndb.h>
#include <panel.h>
#include <regexp.h>
#include <stdio.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 example, <libg.h>
defines the contents of library /$objtype/lib/libg.a, which may be ab‐
breviated when named to the loader as -lg. In practice, each include
file contains a #pragma that directs the loader to pick up the associ‐
ated 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, libg, the graphics library. is de‐
fined by <libg.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 has no prerequisites. 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:
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); and Length, a union giving dif‐
ferent views of the 64-bit length of a file, declared something like
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 (those outside ASCII and Latin-1 control space)
that occupy no more than NAMELEN-1 bytes. A path element cannot con‐
tain a space or 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. File de‐
scriptors range from 0 to 99 in the current system. The system allo‐
cates 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 descrip‐
tor 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, of length
DIRLEN (defined in <libc.h>). Each entry is a machine-independent rep‐
resentation 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 translated into a more con‐
venient, addressable form called a Dir structure; dirstat, dirfstat,
dirwstat, and dirfwstat execute 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 fw‐
stat alter them.
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 (in exits(2)) to wait for some child to terminate. 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.
Alef
Most of the functions in this section are available in the same form
from Alef, with byte substituted for char and uchar and int for long,
and with adjustment for Alef having only one floating-point type,
called float, holding double-precision values. The main exceptions are
that the long-valued functions such as strtoul have their final l
changed to an i to reflect the different type structure of the lan‐
guage; that the Bio library has a different organization (see Bio(2)
for details); and for various reasons some things are missing, notably
ctype and the Stdio, IP, Layer, Lock, Mach, Ndb, and Panel libraries.
Also, there is no <u.h>; instead <alef.h> replaces both it and
<libc.h>. The machine-dependent definitions in Alef, which are only
needed for getfcr(2) and relatives, are in <arch.h>.
Within this manual, only explicit differences in the Alef libraries are
documented, the Alef functions are not all indexed, and the substitu‐
tions for <libc.h> as well as char, uchar, etc. are assumed. The
sources to the Alef libraries all live under /sys/src/alef/lib.
NOTE: Because the languages have different calling conventions, Alef
programs cannot be linked with C libraries.
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)