INTRO(2)                                                 INTRO(2)

     NAME
          intro - introduction to library functions

     SYNOPSIS
          #include <u.h>

          #include <libc.h>

          #include <auth.h>

          #include <bio.h>

          #include <draw.h>

          #include <fcall.h>

          #include <frame.h>

          #include <mach.h>

          #include <ndb.h>

          #include <regexp.h>

          #include <stdio.h>

          #include <thread.h>

     DESCRIPTION
          This section describes functions in various libraries.  For
          the most part, each library is defined by a single C include
          file, such as those 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 exam-
          ple, <draw.h> defines the contents of library
          /$objtype/lib/libdraw.a, which may be abbreviated when named
          to the loader as -ldraw.  In practice, each include file
          contains a #pragma that directs the loader to pick up the
          associated 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, draw, is defined by <draw.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

     Page 1                       Plan 9             (printed 12/2/22)

     INTRO(2)                                                 INTRO(2)

          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); the
          macros va_arg and friends for accessing arguments of vari-
          adic functions (identical to the macros defined in
          <stdarg.h> in ANSI C); and Length, for historical reasons a
          union, representing the 64-bit length of a file, declared
          something like

               typedef union
               {
                     vlong length;
               } 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 contain a space
          or slash.

          When a process presents a file name to Plan 9, it is
          evaluated by the following algorithm.  Start with a direc-
          tory 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
          anything 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 transla-
          tion (see below), and repeat.  The last step may yield a
          directory or regular file.  The collection of files reach-
          able 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 continues 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.  Using bind

     Page 2                       Plan 9             (printed 12/2/22)

     INTRO(2)                                                 INTRO(2)

          and mount to do name space adjustment affects only the cur-
          rent 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. The system allocates the
          numbers by selecting the lowest unused descriptor.  They are
          allocated dynamically; there is no visible limit to the num-
          ber of file descriptors a process may have open.  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 descriptor table may be shared by
          several processes.

          By convention, file descriptor 0 is the standard input, 1 is
          the standard 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 pro-
          grams will be confused by such chicanery.  The exception is
          that the system prints messages about broken processes to
          file descriptor 2.

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

          Directories may be opened and read much like regular files.
          They contain an integral number of records, called directory
          entries, of length DIRLEN (defined in <libc.h>).  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 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 trans-
          lated into a more convenient, addressable form called a Dir
          structure; dirstat, dirfstat, dirwstat, and dirfwstat exe-
          cute the appropriate translations (see stat(2)).

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

          The operating system kernel records the file name used to
          access each open file or directory.  If the file is opened
          by a local name (one that does not begin / or #), the system

     Page 3                       Plan 9             (printed 12/2/22)

     INTRO(2)                                                 INTRO(2)

          makes the stored name absolute by prefixing the string asso-
          ciated with the current directory.  Similar lexical adjust-
          ments are made for path names containing . (dot) or ..
          (dot-dot).  By this process, the system maintains a record
          of the route by which each file was accessed.  Although
          there is a possibility for error-the name is not maintained
          after the file is opened, so removals and renamings can con-
          found it-this simple method usually permits the system to
          return, via the fd2path(2) system call and related calls
          such as getwd(2), a valid name that may be used to find a
          file again.  This is also the source of the names reported
          in the name space listing of ns(1) or /dev/ns (see proc(3)).

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

        Process execution and control
          A new process is created when an existing one calls rfork
          with the RFPROC 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 running the
          same program as the parent; exec(2) will bring in a differ-
          ent one.

          Each process has a unique integer process id; a set of open
          files, indexed by file descriptor; and a current working
          directory (changed by chdir(2)).

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

          The memory of a process is divided into segments. Every pro-
          gram has at least a text (instruction) and stack segment.
          Most also have an initialized 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 termi-
          nate.  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.

        Multithreading

     Page 4                       Plan 9             (printed 12/2/22)

     INTRO(2)                                                 INTRO(2)

          By calling rfork with the RFMEM bit set, a program may cre-
          ate several independently executing processes sharing the
          same memory (except for the stack segment, which is unique
          to each process).  Where possible according to the ANSI C
          standard, the main C library works properly in multiprocess
          programs; malloc, print, and the other routines use locks
          (see lock(2)) to synchronize access to their data struc-
          tures.  The graphics library defined in <draw.h> is also
          multi-process capable; details are in graphics(2). In gen-
          eral, though, multiprocess programs should use some form of
          synchronization to protect shared data.

          The thread library, defined in <thread.h>, provides support
          for multiprocess programs.  It includes a data structure
          called a Channel that can be used to send messages between
          processes, and coroutine-like threads, which enable multiple
          threads of control within a single process.  The threads
          within a process are scheduled by the library, but there is
          no pre-emptive scheduling within a process; thread switching
          occurs only at communication or synchronization points.

          Most programs using the thread library comprise multiple
          processes communicating over channels, and within some pro-
          cesses, multiple threads.  Since Plan 9 I/O calls may block,
          a system call may block all the threads in a process.
          Therefore, a program that shouldn't block unexpectedly will
          use a process to serve the I/O request, passing the result
          to the main processes over a channel when the request com-
          pletes.  For an example of this design, see mouse(2).

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

     DIAGNOSTICS
          Math functions in libc return special values when the func-
          tion is undefined 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 oth-
          ers employ system calls in their implementation.  All system
          calls return integers, with -1 indicating that an error
          occurred; errstr(2) recovers a string describing the error.
          Some user-level library functions also use the errstr mecha-
          nism 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.

     BUGS
          The limitation of path elements to 27 bytes (NAMELEN-1) is a
          liability in the networked world.

     Page 5                       Plan 9             (printed 12/2/22)