man(1) Manual page archive


     SYS-INTRO(2)                                         SYS-INTRO(2)

     NAME
          Sys: intro - introduction to the Sys module

     SYNOPSIS
          include "sys.m";
          sys := load Sys Sys->PATH;

     DESCRIPTION
          Inferno system calls are provided by the built-in module
          declared by sys.m.  It contains the fundamental system data
          structures and interfaces.  There are currently 39 calls,
          providing: file access; basic I/O; name space manipulation;
          formatted output for Limbo; exception handling; and basic
          character and string manipulation.

        File Name Space
          Files are collected into a hierarchical organization called
          a file tree starting in a directory called the root.
          Filenames, 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).
          A path element cannot contain a space, slash, or #.  The
          path element .. refers to the parent directory of the direc-
          tory containing that element.

          When a process presents a file name to Inferno, it is
          evaluated by the following algorithm.

          1.   Start with a directory that depends on the first char-
               acter of the path: / means the root of the main hierar-
               chy, # means the separate root of a kernel device's
               file tree (see Section 3), and anything else means the
               process's current working directory.

          2.   For each path element, look up the element in the
               directory, advance to that directory, do a possible
               translation (see below).

          3.   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 sys-bind(2)) to say
          that whenever a certain (specified) file is reached during
          an evaluation, that evaluation continues instead from some
          other (specified) file.

     SYS-INTRO(2)                                         SYS-INTRO(2)

          Also, these same calls create union directories, which are
          concatenations of ordinary directories that are searched
          sequentially until the desired element is found.

          The result of evaluating .. in a union directory is unde-
          fined.

          Using bind and mount to do name space adjustment affects
          only the current name space group (see below, and sys-
          pctl(2)).

          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
          sys-open(2)). These calls return a reference to an object of
          type FD (file descriptor) that identifies the file to subse-
          quent I/O calls, notably read and write (see sys-read(2)).
          When the last reference to an FD disappears, the file
          descriptor is released-closed, in Unix parlance.  The FD
          contains an integer file descriptor, similar to those in
          Unix, but the FD type is the one passed to Limbo I/O rou-
          tines.

          Integer file descriptor values range from 0 to n in the cur-
          rent system, where the upper bound depends on the underlying
          operating system.  The system allocates the numbers by
          selecting the lowest unused descriptor.  They may be reas-
          signed using dup (see sys-dup(2)). Integer file descriptor
          values are indices into a kernel-resident file descriptor
          table, which is inherited from the parent when a process is
          created by a Limbo spawn operation.  A set of processes,
          called a file descriptor group, shares that table, so files
          opened by one process may be read and written by other pro-
          cesses in the group.  See sys-pctl(2) for more information.

          By convention, file descriptor 0 is the standard input, 1 is
          the standard output, and 2 is the standard error output.
          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.

          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 system call (sys-seek(2)).

          Directories may be opened and read much like regular files
          (see sys-dirread(2)). They contain an integral number of
          records, called directory entries. Each entry is a machine-
          independent representation of the information about an

     SYS-INTRO(2)                                         SYS-INTRO(2)

          existing file in the directory, including the name, owner-
          ship, permission, access dates, and so on.

          The entry corresponding to an arbitrary file can be
          retrieved by stat or fstat (see sys-stat(2)); wstat and
          fwstat write back entries, thus changing the properties of a
          file.

          New files are made with create and deleted with remove (see
          sys-open(2) and sys-remove(2)).

          Directories are manipulated by create, remove, wstat, and
          fwstat; they may not directly be written.

          Inferno provides no guarantee of consistency should several
          processes access a file concurrently.  Guaranteed syn-
          chronous writes are not available.  Nor is file locking from
          underlying file systems supported by Inferno.  Processes can
          coordinate their file operations by other mechanisms.

          Atomicity is guaranteed for byte counts smaller than the
          Styx message size; see read(5).

        Process execution and control
          A Limbo process, also called a thread, is the basic unit of
          computation for Limbo application programming in the Inferno
          operating system.

          A newly spawned thread shares the same address space as that
          of its creator thread.  That is, the set of global  vari-
          ables that is in scope to one is in scope to the other.  A
          change made by one can be detected by the other.  Since they
          are scheduled independently, they should synchronize their
          actions to share this data coherently.

          The newly created thread also shares the same set of open
          file descriptors and the current working directory.

          Processes are also organized into process groups (pgrps)
          that represent the set of threads of a single application
          and can be terminated by a single kill request; see prog(3).

          A newly-spawned thread automatically inherits the following
          attributes: file name space (including shared current direc-
          tory); file descriptor group; and process group.  A thread
          can subsequently acquire a new, independent name space, new
          or modified file descriptor group, or new process group.
          See sys-pctl(2).

        User/Group Identity
          The Inferno operating system maintains user identifier (uid)
          and group identifier (gid) strings for each process.  These

     SYS-INTRO(2)                                         SYS-INTRO(2)

          values are also attributes of files and directories.  See
          sys-stat(2) and stat(5). A comparison of process and file
          identities take place when a process attempts to open or
          create a file.

          When a pathname crosses from one server to another the pro-
          cess identities are mapped by each server receiving a file
          request.

          The uid and gid strings are assigned to the thread created
          when a user logs into Inferno and cannot be changed.

     SOURCE
          /emu/inferno.c
          /os/port/inferno.c

     DIAGNOSTICS
          System calls often return an integer status, or tuples con-
          taining results and an integer status, and follow the con-
          vention that a status of -1 is returned when an error
          occurred; a non-negative value (usually 0) is returned on
          success.  If an error occurred, a detailed error message can
          be obtained for the most recent error, using the `%r' format
          of sys-print(2). Exceptions to this general rule are noted
          in the `DIAGNOSTICS' sections.