Plan B User's Manual


Name

intro ­ Introduction to System Calls.

Synopsis

#include <ulib.h>

Description

This section introduces the usage of Plan B for an application programmer. There is a single include file as shown in the synopsys. No other include is necessary unless library functions are required (standard C library functions are considered part of the system library). For a description of library functions see intro(3).

For hosted environments (e.g. when running Plan B on top of another operating system) the whole set of system calls from the host operating system is also available. Using any of them would make the program non portable to other architectures.

Boxes

In Plan B all system resources are exported by means of boxes. A box is an abstraction used instead of the more traditional file. Most system calls are exporting the box interface to the application programmer. Other system calls are used to provide other related services, such as naming.

Programs can use make(2) to create a box and delete(2) to delete a box. Boxes can be copied using copy(2) and linked using link(2) (although not all boxes can be linked). Boxes have neither read() nor write() defined; vm(4) boxes can be copied instead.

A box may contain other boxes. The names for the boxes contained within a given one (maybe none) can be obtained with selectors(2).

Box metadata include several time stamps, permissions, ownership, type, and constraints. Metadata can be accessed with info(2) and changed with chinfo(2).

All these system calls use names, there is no such thing as a "box descriptor" in Plan B.

Types and constraints

Boxes have type and must be of the same type to be copied or linked. Conversion declarations may aid on this, as said below. Along with the type, boxes have constraints. Constraints are sequences of constraint elements determining properties of the constrained box. System boxes use two constraint elements: architecture and network name. For example, binary boxes have type bin and constraints like p98!wave (Executing on Plan B running over Plan 9 for 386; using wireless ethernet) and p95!gsyc (Executing on Plan B running over Plan 9 for ARM; using GSyC ethernet).

All system calls accept constraint specifiers along with names, to determine which one of the boxes with a given name is used. The constraint is specified by contatenating it to the name, separated by by a "!" character (e.g. /a/box!p98!wave)

When a constraint is given, the box used will match the constraint given by the user—those not matching will be ignored for the purpose of the system call. Two constraints match if they match element by element. When specifying a constraint for a system call, two special names can be used as constraint elements: "%" and "*". A constraint element "*" matches any name. A constraint element "%" is used when two different boxes are used on a single system call. It is used to request such element to be the same in both boxes, although any concrete name can match. Trailing constraint elements not specified are considered to be "*" and thus ignored. See copy(2) for several examples using constraint specifiers.

Name spaces

Each application has its own name space. A name space is a prefix table bounding boxes imported from the network (or the local node). A new name may be introduced with import(2) and removed with forget(2). Name spaces can listen for network ads to discover new resources, see import(2) Besides, each name space has a current working box, which is a name prepended to each relative name used. It can be changed with change(2) and retrieved with dot(2).

Side by side with the name space, there is a set of conversion declarations. Each declaration tells the system how to convert a box from one type to another. New declarations can be introduced with cast(2) and later removed with uncast(2).

Other resources

All other resources are manipulated by using boxes provided by the system. Do not look for system calls to handle them; try on section 4 of the manual instead.

Diagnostics

All system calls may raise exceptions; the error strings describes the cause. See error(3) for a description.

Source

/src/b

See also

Plan B: Boxes for network resources. Francisco J Ballesteros.

The Box: A replacement for files. Francisco J Ballesteros and Sergio Arevalo. HotOS-VII.

Bugs

Many, including that there are missing sections.

Known system limits are described in limits(2). Oh, I forgot!, another bug is that there is no limits(2).


Plan B User's Manual. First edition.