.TH SYS-INTRO 2.SH NAMESys: intro \- introduction to the.B Sysmodule.SH SYNOPSIS.EXinclude "sys.m";sys := load Sys Sys->PATH;.EE.SH DESCRIPTIONInferno system calls are provided by the built-in module declared by.BR sys.m .It contains the fundamental system data structures and interfaces.There are currently 42 calls, providing: file access; basic I/O;name space manipulation; formatted outputfor Limbo; and basic character and string manipulation..SS "File Name Space"Files are collected into a hierarchical organization called a.I file.I treestarting in a.I directorycalled the.IR root..IR Filenames ,also called.IR paths ,consist of a number of.BR / -separated.I "path elementswith the slashes corresponding to directories.A path element must contain only printablecharacters (those outside ASCII and Latin-1 control space).A path element cannot contain a space, slash, or.BR # .The path element.B \&..refers to the parent directory of the directory containing that element..PPWhen a process presents a file name to Inferno,it is.I evaluatedby the following algorithm..TP1.Start with a directory that depends on the first character of the path:.B /means the root of the main hierarchy,.B #means the separate root of a kernel device's file tree(see Section 3),and anything else means the process's current working directory..TP2.For each path element, look up the elementin the directory, advance to that directory,do a possible translation (see below)..TP3.Repeat.The last step may yield a directory or regular file..PPThe collection of files reachable from the root is called the.I "name spaceof a process..PPA program can use.B bindor.B mount(see.IR 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..PPAlso, these same calls create\f2union directories\fP,which are concatenations of ordinary directoriesthat are searched sequentially until the desired element is found..PPThe result of evaluating.B \&..in a union directory is undefined..PPUsing.B bindand.B mountto do name space adjustment affects onlythe current name space group (see below, and.IR sys-pctl (2))..PPCertain conventions about the layout of the name space should be preserved;see.IR namespace (4)..SS "File I/O"Files are opened for input or outputby.B openor.B create(see.IR sys-open (2)).These calls return a reference to an object of type.B FD(file descriptor)that identifies the file to subsequent I/O calls,notably.B readand.B write(see.IR sys-read (2)).When the last reference to an.B FDdisappears, the file descriptor is released\(emclosed, in Unix parlance.The.B FDcontains an integer file descriptor, similar to those in Unix, but the.B FDtype is the one passed to Limbo I/O routines..PPInteger file descriptor values range from 0 to.I nin the current system, where the upper bounddepends on the underlying operating system.The system allocates the numbers by selecting the lowest unused descriptor.They may be reassigned using.B dup(see.IR sys-dup (2)).Integer file descriptor values are indices into akernel-resident.IR "file descriptor table" ,which is inherited from the parent when a process is created by a Limbo.B spawnoperation.A set of processes, called a.IR "file descriptor group" ,shares that table, so files opened by one process may beread and written by other processes in the group.  See.IR sys-pctl (2)for more information..PPBy 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..PPFiles are normally read or written in sequential order.The I/O position in the file is called the.IR "file offset"and may be set arbitrarily using the.B seeksystem call.RI ( sys-seek (2))..PPDirectories may be opened and readmuch like regular files (see.IR sys-dirread (2)).They contain an integral number of records,called.IR "directory entries" .Each entry is a machine-independent representation ofthe information about an existing file in the directory,including thename,ownership,permission,access dates,and so on..PPThe entrycorresponding to an arbitrary file can be retrieved by.B stator.B fstat(see.IR sys-stat (2));.B wstatand.B fwstatwrite back entries, thus changing the properties of a file..PPNew files are made with.B createand deleted with.B remove(see.IR sys-open (2)and.IR sys-remove (2))..PPDirectories are manipulated by.BR create ,.BR remove ,.BR wstat ,and.BR fwstat ;they may not directly be written..PPInferno provides no guarantee of consistency shouldseveral processes access a file concurrently.Guaranteed synchronous writes are not available.Nor is file locking from underlying file systems supported by Inferno.Processes can coordinate their file operations by other mechanisms..PPAtomicity is guaranteed for byte counts smaller than the.I Styxmessage size;see.IR read (5)..SS "Process execution and control"A Limbo.IR process ,also called a.IR thread ,is the basic unit of computation for Limbo application programmingin the Inferno operating system..PPA newly spawned thread shares the same.I "address spaceas that of its creator thread.That is, the set of global  variables that is in scope toone 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 theiractions to share this data coherently..PPThe newly created thread also shares the same set of open file descriptorsand the current working directory..PPProcesses are also organized into.I "process groups.RB ( pgrps )that represent the set of threads of a singleapplication and can be terminated by a single kill request; see.IR prog (3)..PPA newly-spawned thread automatically inherits the following attributes:file name space (including sharedcurrent directory); file descriptor group; and process group.A thread can subsequentlyacquire a new, independent name space, new or modified file descriptor group,or new process group.See.IR  sys-pctl (2)..SS "User/Group Identity"The Inferno operating system maintains user identifier.RB ( uid )and group identifier.RB ( gid )stringsfor each process.These values are also attributes of files and directories.See.IR sys-stat (2)and.IR stat (5).A comparison of process and file identities take place when a processattempts to open or create a file..PPWhen a pathname crosses from one server to another the process identities aremapped by each server receiving a file request..PPThe.B uidand.B gidstrings are assigned to the thread createdwhen a user logs into Inferno and cannot be changed..SH SOURCE.B /emu/port/inferno.c.br.B /os/port/inferno.c.SH DIAGNOSTICSSystem calls often return an integer status, or tuples containing results andan integer status,and follow the convention 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 themost recent error, using the.RB ` %r 'format of.IR sys-print (2).Exceptions to this general rule are noted in the`DIAGNOSTICS' sections..PPFrom Limbo, system calls that return values on the heap, for instance strings in.B Dirstructures returned by.IR sys-stat (2),and arrays of directory entries returned by.IR sys-readdir (2),can also raise ``out of memory: heap'' exceptions when attemptingto create the return value.