INTRO(2)                                                 INTRO(2)

     Name
          intro - Introduction to System Calls.

     Synopsis
          #include <ulib.h>

     Description
          This section introduces the usage of Plan B for an applica-
          tion 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 architec-
          tures.

        Boxes
          In Plan B all system resources are exported by means of
          boxes. A box is an abstraction used instead of the more tra-
          ditional 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 con-
          tained within a given one (maybe none) can be obtained with
          selectors(2).

          Box metadata include several time stamps, permissions, own-
          ership, 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. Con-
          straints are sequences of constraint elements determining
          properties of the constrained box. System boxes use two

     INTRO(2)                                                 INTRO(2)

          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).

          Most system calls accept constraint specifiers along with
          names, to determine which one of the boxes with a given name
          is used. The box used will match the constraint given by the
          user. Two constraints match if they match element by ele-
          ment. 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 con-
          straint 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 net-
          work 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 conver-
          sion 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 Balles-
          teros.

     INTRO(2)                                                 INTRO(2)

          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 for-
          got!, another bug is that there is no limits(2).