Limbo System Module — Inferno 1ed

Limbo System Module

The Limbo system modules are as follows:


bind, mount, unmount - change file name space
byte2char, char2byte - convert between bytes and characters
chdir - change working directory
dial, announce, export, listen - make network connections
dirread - read directory
dup - duplicate an open file descriptor
file2chan - create file connected to Limbo channel
millisec - millisecond timer
open, create - open/create a file for reading or writing
pctl - process control
print, fprint, sprint - print formatted output
read, write, stream - read, write, or stream file
remove - remove a file
seek - change file offset
sleep - delay execution
stat, fstat, fwstat, wstat - get and put file status
tokenize - split string into words
utfbytes - compute the Unicode length of a UTF byte sequence

Synopsis

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

Description

Inferno system calls are provided by the system module interface file, sys.m. The system module provides access to system calls for basic string and file manipulation, primitive printing functions and network functions.

File Name Space

Files are collected into a hierarchical organization called a file tree starting in a directory called the root. Filenames, also called pathnames, consist of a number of path elements separated by slashes (/) the slashes which correspond 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 directory containing that element.

When a process presents a file name to Inferno, 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)

anything else means the current working directory of the process.

For each path element, look up the element in the directory, advance to that directory, do a possible translation.

Repeat. The last step may yield a directory or regular file.

The collection of files that can be reached from the root is called the name space of a process.

A program can use bind or mount so that whenever a specified file is reached during an evaluation, that evaluation continues instead from some other specified file. These calls create union directories, which are concatenations of ordinary directories that are searched sequentially until the desired element is found.

Using bind and mount to do name space adjustment affects only the current name space group.

File Manipulation Functions

File Descriptor (FD)

The Limbo programming language and its libraries manage I/O via references to instances of an abstract data type, FD, called a file descriptor. This type holds an integer-valued file descriptor, the form used by the operating system, in a structure that can be reference counted and garbage collected. There are occasions when a program must access the underlying integer file descriptor, such as arranging I/O re-direction for the standard input and output for a new process.

Files are opened for input, output or input/output by open or create. These calls return reference to an abstract data type (adt) of type FD (file descriptor) that identifies the file to subsequent I/O calls, such as read and write.

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.

File descriptors are garbage-collected as soon as they are no longer referenced. There is no close function.

Integer File Descriptor

The FD abstract data type includes a number that is an integer file descriptor. Values for this number range from 0 to n, where the upper bound depends on the underlying operating system. The system allocates the numbers by selecting the lowest unused value. They may be reassigned with dup and used to initialize FD adts using fides. Integer file descriptor values are indices into a kernel-resident file descriptor table.

By convention, the first three integer values are used by application programs as follows:


0	standard input,
1	standard output,
2	standard error output.

Since this is only a convention, it is possible to close file descriptor 0, or even to replace it by a file open only for writing. However, programs must agree upon convention.

File Descriptor Group

By default, a Limbo process shares its file descriptor table with the creator process.

The set of processes that shares that table is called a file descriptor group. Files opened by one process in the group may be read from and written to other processes in the group. (See pctl - process control).

Directories and files

Directories may be opened and read much like regular files (see dirread - read directory). They contain an integral number of records, called directory entries. 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 similar information.

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

New files are made with create and deleted with remove (see open, create - open/create a file for reading or writing and remove - remove a file). As with regular files, attributes of directories can be manipulated by wstat, and fwstat. Directories may not be written directly.

infernosupport@lucent.com

Museum