INTRO(3)                                                 INTRO(3)

     NAME
          intro - introduction to library functions

     SYNOPSIS
          #include <u.h>

          #include any Unix headers

          #include <libc.h>

          #include <auth.h>

          #include <bio.h>

          #include <draw.h>

          #include <fcall.h>

          #include <frame.h>

          #include <mach.h>

          #include <regexp.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
          /lib/libx.a, where x is the base of the include file name,
          stripped of a leading lib if present.  For example, <draw.h>
          defines the contents of library /lib/libdraw.a, which may be
          abbreviated when named to the loader as -ldraw.  In prac-
          tice, each include file contains a magic 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; see 9c(1).

          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
          ANSI C Standard I/O library, libstdio, is defined by
          <stdio.h>, which needs <u.h>.  There are a few other, less

     INTRO(3)                                                 INTRO(3)

          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: uchar, ushort, and ulong, the
          unsigned integer types; schar, the signed char type; vlong
          and uvlong, the signed and unsigned very long integral
          types; Rune, the Unicode character type; u8int, u16int,
          u32int, and u64int, the unsigned integral types with spe-
          cific widths; jmp_buf, the type of the argument to setjmp
          and longjmp, plus macros that define the layout of jmp_buf
          (see setjmp(3)); and the macros va_arg and friends for
          accessing arguments of variadic functions (identical to the
          macros defined in <stdarg.h> in ANSI C).

          Plan 9 and Unix use many similarly-named functions for dif-
          ferent purposes: for example, Plan 9's dup is closer to (but
          not exactly) Unix's dup2. To avoid name conflicts, <libc.h>
          defines many of these names as preprocessor macros to add a
          p9 prefix, so that dup becomes p9dup. To disable this renam-
          ing, #define NOPLAN9DEFINES before including <libc.h>.  If
          Unix headers must be included in a program, they should be
          included after <u.h>, which sets important preprocessor
          directives (for example, to enable 64-bit file offsets), but
          before <libc.h>, to avoid renaming problems.

        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 the control spaces of ASCII and Latin-1).  A path
          element cannot contain a 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, 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 translation (see
          below), and repeat.  The last step may yield a directory or
          regular file.

        File I/O
          Files are opened for input or output by open or create (see
          open(3)). These calls return an integer called a file
          descriptor which identifies the file to subsequent I/O
          calls, notably read(3) and write. The system allocates the
          numbers by selecting the lowest unused descriptor.  They are

     INTRO(3)                                                 INTRO(3)

          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(3). File descriptors are indices
          into a kernel resident file descriptor table. Each process
          has an associated file descriptor table.  In threaded pro-
          grams (see thread(3)), the file descriptor table is shared
          by all the procs.

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

          Directories may be opened like regular files.  Instead of
          reading them with read(3), use the Dir structure-based rou-
          tines described in dirread(3). The entry corresponding to an
          arbitrary file can be retrieved by dirstat (see stat(3)) or
          dirfstat; dirwstat and dirfwstat write back entries, thus
          changing the properties of a file.

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

          Pipe(3) 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 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(3) 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.

          A process terminates by calling exits(3). A parent process

     INTRO(3)                                                 INTRO(3)

          may call wait(3) to wait for some child to terminate.  A bit
          of status information may be passed from exits to wait. On
          Plan 9, the status information is an arbitrary text string,
          but on Unix it is a single integer.  The Plan 9 interface
          persists here, although the functionality does not.
          Instead, empty strings are converted to exit status 0 and
          non-empty strings to 1.

          A process can go to sleep for a specified time by calling
          sleep(3).

          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(3)
          to register the function to be called (the notification
          handler) when such events occur.

        Multithreading
          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(3)) to
          synchronize access to their data structures.  The graphics
          library defined in <draw.h> is also multi-process capable;
          details are in graphics(3). In general, 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 I/O calls may block, a sys-
          tem call may block all the threads in a process.  Therefore,
          a program that shouldn't block unexpectedly will use a pro-
          cess to serve the I/O request, passing the result to the
          main processes over a channel when the request completes.
          For examples of this design, see ioproc(3) or mouse(3).

     SEE ALSO
          nm(1), 9c(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(3)).

     INTRO(3)                                                 INTRO(3)

          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(3) 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.