term% ls -F
term% cat index.txt
INTRO(2)                      System Calls Manual                     INTRO(2)

       intro - introduction to library functions

       #include <u.h>

       #include <libc.h>

       #include <auth.h>

       #include <bio.h>

       #include <fcall.h>

       #include <frame.h>

       #include <layer.h>

       #include <libg.h>

       #include <mach.h>

       #include <ndb.h>

       #include <panel.h>

       #include <regexp.h>

       #include <stdio.h>

       This  section  describes  functions in various libraries.  For the most
       part, each library is defined by a single C include file, listed above,
       and  a  single archive file containing the library proper.  The name of
       the archive is /$objtype/lib/libx.a, where x is the base of the include
       file name, stripped of a leading lib if present.  For example, <libg.h>
       defines the contents of library /$objtype/lib/libg.a, which may be  ab‐
       breviated  when  named to the loader as -lg.  In practice, each include
       file contains a #pragma that directs the loader to pick up the  associ‐
       ated  archive  automatically,  so  it  is  rarely necessary to tell the
       loader which libraries a program needs.

       The library to which a function belongs is defined by the  header  file
       that  defines  its  interface.  The `C library', libc, contains most of
       the basic subroutines such as strlen.  Declarations for  all  of  these
       functions are in <libc.h>, which must be preceded by (needs) an include
       of <u.h>.  The graphics library, libg, the graphics  library.   is  de‐
       fined  by  <libg.h>,  which needs <libc.h> and <u.h>.  The Buffered I/O
       library, libbio, is defined by <bio.h>, which needs <libc.h> and <u.h>.
       The  ANSI  C  Standard  I/O library, libstdio, is defined by <stdio.h>,
       which has no prerequisites.  There are a few other, less commonly  used
       libraries defined on individual pages of this section.

       The  include file <u.h>, a prerequisite of several other include files,
       declares the architecture-dependent and -independent types,  including:
       ushort, uchar, and ulong, the unsigned integer types; schar, the signed
       char type; vlong, a very long integral type; jmp_buf, the type  of  the
       argument  to  setjmp and longjmp, plus macros that define the layout of
       jmp_buf (see setjmp(2)); definitions of the bits in the  floating-point
       control  register as used by getfcr(2); and Length, a union giving dif‐
       ferent views of the 64-bit length of a file, declared something like

              typedef union
                    char   clength[8];
                    vlong  vlength;
                           long hlength;   /* high order */
                           long length;    /* low order */
              } Length;

   Name space
       Files are collected into a hierarchical organization called a file tree
       starting  in  a  directory  called  the  root.  File names, 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)
       that  occupy  no more than NAMELEN-1 bytes.  A path element cannot con‐
       tain a space or slash.

       When a process presents a file name to Plan 9, 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), and any‐
       thing else means the process's current  working  directory.   Then  for
       each  path  element,  look  up the element in the directory, advance to
       that directory, do a possible translation (see below), and 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 bind(2)) to say  that  whenever  a
       specified file is reached during evaluation, evaluation instead contin‐
       ues from a second specified file.  Also, the same system  calls  create
       union  directories,  which  are  concatenations of ordinary directories
       that are searched sequentially until the desired element is found.  Us‐
       ing bind and mount to do name space adjustment affects only the current
       process group (see below).  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 open(2)).
       These calls return an integer called a file descriptor which identifies
       the  file to subsequent I/O calls, notably read(2) and write.  File de‐
       scriptors range from 0 to 99 in the current system.  The  system  allo‐
       cates  the numbers by selecting the lowest unused descriptor.  They may
       be reassigned using dup(2).  File descriptors are indices into a kernel
       resident  file  descriptor  table.  Each process has an associated file
       descriptor table.  In some cases (see rfork in fork(2)) a file descrip‐
       tor table may be shared by several processes.

       By  convention, file descriptor 0 is the standard input, 1 is the stan‐
       dard output, and 2 is the standard error output.  With  one  exception,
       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.  The exception is
       that the system prints messages about broken processes to file descrip‐
       tor 2.

       Files  are normally read or written in sequential order.  The I/O posi‐
       tion in the file is called the file offset and may be  set  arbitrarily
       using the seek(2) system call.

       Directories  may be opened and read much like regular files.  They con‐
       tain an integral number of records, called directory entries, of length
       DIRLEN (defined in <libc.h>).  Each entry is a machine-independent rep‐
       resentation of the information about an existing file in the directory,
       including  the  name,  ownership,  permission, access dates, and so on.
       The entry corresponding to  an  arbitrary  file  can  be  retrieved  by
       stat(2)  or  fstat;  wstat and fwstat write back entries, thus changing
       the properties of a file.  An entry may be translated into a more  con‐
       venient,  addressable  form  called a Dir structure; dirstat, dirfstat,
       dirwstat, and  dirfwstat  execute  the  appropriate  translations  (see

       New files are made with create (in open(2)) and deleted with remove(2).
       Directories may not directly be written; create, remove, wstat, and fw‐
       stat alter them.

       Pipe(2)  creates a connected pair of file descriptors, useful for bidi‐
       rectional local communication.

   Process execution and control
       A new process is created when an existing one calls rfork with the  RF‐
       PROC bit set, usually just by calling fork(2).  The new (child) process
       starts out with copies of the address space and most  other  attributes
       of  the old (parent) process.  In particular, the child starts out run‐
       ning the same program as the parent; exec(2) will bring in a  different

       Each  process has a unique integer process id; a set of open files, in‐
       dexed by file descriptor; and a current working directory  (changed  by

       Each  process has a set of attributes — memory, open files, name space,
       etc. — that may be shared or unique.  Flags to rfork control the  shar‐
       ing of these attributes.

       The memory of a process is divided into segments.  Every program has at
       least a text (instruction) and stack segment.  Most also have  an  ini‐
       tialized  data  segment  and  a segment of zero-filled data called bss.
       Processes may segattach(2) other segments for special purposes.

       A process terminates by calling exits(2).  A parent  process  may  call
       wait  (in  exits(2))  to wait for some child to terminate.  A string of
       status information may be passed from exits to wait.  A process can  go
       to sleep for a specified time by calling sleep(2).

       There  is  a  notification mechanism for telling a process about events
       such as address faults, floating point faults, and messages from  other
       processes.   A  process  uses  notify(2) to register the function to be
       called (the notification handler) when such events occur.

       Most of the functions in this section are available in  the  same  form
       from  Alef,  with byte substituted for char and uchar and int for long,
       and with adjustment for  Alef  having  only  one  floating-point  type,
       called float, holding double-precision values.  The main exceptions are
       that the long-valued functions such  as  strtoul  have  their  final  l
       changed  to  an  i  to reflect the different type structure of the lan‐
       guage; that the Bio library has a different  organization  (see  Bio(2)
       for  details); and for various reasons some things are missing, notably
       ctype and the Stdio, IP, Layer, Lock, Mach, Ndb, and  Panel  libraries.
       Also,  there  is  no  <u.h>;  instead  <alef.h>  replaces  both  it and
       <libc.h>.  The machine-dependent definitions in Alef,  which  are  only
       needed for getfcr(2) and relatives, are in <arch.h>.

       Within this manual, only explicit differences in the Alef libraries are
       documented, the Alef functions are not all indexed, and  the  substitu‐
       tions  for  <libc.h>  as  well  as char, uchar, etc.  are assumed.  The
       sources to the Alef libraries all live under /sys/src/alef/lib.

       NOTE: Because the languages have different  calling  conventions,  Alef
       programs cannot be linked with C libraries.

       nm(1), 2l(1), 2c(1)

       Math functions in libc return special values when the function is unde‐
       fined for the given arguments or when the value  is  not  representable
       (see nan(2)).

       Some  of  the functions in libc are system calls and many others employ
       system calls in their implementation.  All system  calls  return  inte‐
       gers,  with  -1 indicating that an error occurred; errstr(2) recovers a
       string describing the error.  Some user-level  library  functions  also
       use  the  errstr mechanism to report errors.  Functions that may affect
       the value of the error string are said to ``set errstr''; it is  under‐
       stood that the error string is altered only if an error occurs.