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 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 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 defined 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, includ-
ing: 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 float-
ing-point control register as used by getfcr(2); and Length, a union giving different views of the 64-bit length of a file, declared some-
thing 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 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. 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 con-
tinues from a second specified file. Also, the same system calls create union directories, which are concatenations of ordinary directo-
ries that are searched sequentially until the desired element is found. Using 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 identi-
fies 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 programs 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 translated
into a more convenient, addressable form called a Dir structure; dirstat, dirfstat, dirwstat, and dirfwstat execute the appropriate trans-
lations (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.
Pipe(2) creates a connected pair of file descriptors, useful for bidirectional 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 different 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.
The memory of a process is divided into segments. Every program has at least a text (instruction) and stack segment. Most also have an
initialized 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 language;
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 substi-
tutions 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 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 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
understood that the error string is altered only if an error occurs.
INTRO(2)