build: Better Build System

1 files changed, 465 insertions, 0 deletions

diff --git a/static/plan9-4e/man2/0intro.2 b/static/plan9-4e/man2/0intro.2
new file mode 100644
index 00000000..5ed0b30a
--- /dev/null
+++ b/static/plan9-4e/man2/0intro.2
@@ -0,0 +1,465 @@
+.TH INTRO 2
+.SH NAME
+intro \- introduction to library functions
+.SH SYNOPSIS
+.nf
+.B #include <u.h>
+.PP
+.B #include <libc.h>
+.PP
+.B #include <auth.h>
+.PP
+.B #include <bio.h>
+.PP
+.B #include <draw.h>
+.PP
+.B #include <fcall.h>
+.PP
+.B #include <frame.h>
+.PP
+.B #include <mach.h>
+.PP
+.B #include <ndb.h>
+.PP
+.B #include <regexp.h>
+.PP
+.B #include <stdio.h>
+.PP
+.B #include <thread.h>
+.fi
+.SH 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
+.BI /$objtype/lib/lib x .a \f1,
+where
+.I x
+is the base of the include file name, stripped of a leading
+.B lib
+if present.
+For example,
+.B <draw.h>
+defines the contents of library
+.BR /$objtype/lib/libdraw.a ,
+which may be abbreviated when named to the loader as
+.BR -ldraw .
+In practice, each include file contains a
+.B #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.
+.PP
+The library to which a function belongs is defined by the
+header file that defines its interface.
+The `C library',
+.IR libc ,
+contains most of the basic subroutines such
+as
+.IR strlen .
+Declarations for all of these functions are
+in
+.BR <libc.h> ,
+which must be preceded by
+.RI ( needs )
+an include of
+.BR <u.h> .
+The graphics library,
+.IR draw ,
+is defined by
+.BR <draw.h> ,
+which needs
+.B <libc.h>
+and
+.BR <u.h> .
+The Buffered I/O library,
+.IR libbio ,
+is defined by
+.BR <bio.h> ,
+which needs
+.B <libc.h>
+and
+.BR <u.h> .
+The ANSI C Standard I/O library,
+.IR libstdio ,
+is defined by
+.BR <stdio.h> ,
+which has no prerequisites.
+There are a few other, less commonly used libraries defined on
+individual pages of this section.
+.PP
+The include file
+.BR <u.h> ,
+a prerequisite of several other include files,
+declares the architecture-dependent and -independent types, including:
+.IR ushort ,
+.IR uchar ,
+and
+.IR ulong ,
+the unsigned integer types;
+.IR schar ,
+the signed char type;
+.IR vlong ,
+a very long integral type;
+.IR jmp_buf ,
+the type of the argument to
+.I setjmp
+and 
+.IR longjmp ,
+plus macros that define the layout of
+.IR jmp_buf
+(see
+.IR setjmp (2));
+definitions of the bits in the floating-point control register
+as used by
+.IR getfcr (2);
+the macros
+.B va_arg
+and friends for accessing arguments of variadic functions (identical to the
+macros defined in
+.B <stdarg.h>
+in ANSI C);
+and
+.IR Length ,
+for historical reasons a union,
+representing the 64-bit length of a file, declared something like
+.IP
+.EX
+.ta 6n +6n +6n
+typedef union
+{
+	vlong	length;
+} Length;
+.EE
+.SS "Name space
+Files are collected into a hierarchical organization called a
+.I "file tree
+starting in a
+.I directory
+called the
+.IR root .
+File names, also called
+.IR paths ,
+consist of a number of
+.BR / -separated
+.IR "path elements"
+with the slashes corresponding to directories.
+A path element must contain only printable
+characters (those outside
+.SM ASCII
+and Latin-1 control space)
+that occupy no more than
+.B NAMELEN-1
+bytes.
+A path element cannot contain a space or slash.
+.PP
+When a process presents a file name to Plan 9, it is
+.I evaluated
+by the following algorithm.
+Start with a directory that depends on the first
+character of the path:
+.L /
+means the root of the main hierarchy,
+.L #
+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 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
+.I "name space
+of a process.
+.PP
+A program can use
+.I bind
+or
+.I mount
+(see
+.IR 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
+.IR "union directories" ,
+which are concatenations of ordinary directories
+that are searched sequentially until the desired element is found.
+Using
+.I bind
+and
+.I 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
+.IR namespace (4).
+.SS "File I/O"
+Files are opened for input or output
+by
+.I open
+or
+.I create
+(see
+.IR open (2)).
+These calls return an integer called a
+.IR "file descriptor"
+which identifies the file
+to subsequent I/O calls,
+notably
+.IR read (2)
+and
+.IR write .
+The system allocates the numbers by selecting the lowest unused descriptor.
+They are allocated dynamically; there is no visible limit to the number of file
+descriptors a process may have open.
+They may be reassigned using
+.IR dup (2).
+File descriptors are indices into a
+kernel resident
+.IR "file descriptor table" .
+Each process has an associated file descriptor table.
+In some cases (see
+.I rfork
+in
+.IR fork (2))
+a file descriptor table may be shared by several processes.
+.PP
+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 programs will be confused by such chicanery.
+The exception is that the system prints messages about broken processes
+to file descriptor 2.
+.PP
+Files 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
+.IR seek (2)
+system call.
+.PP
+Directories may be opened and read much like regular files.
+They contain an integral number of records, called
+.IR "directory entries" ,
+of length
+.B DIRLEN
+(defined in
+.BR <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
+.IR stat (2)
+or
+.IR fstat ;
+.I wstat
+and
+.I fwstat
+write back entries, thus changing the properties of a file.
+An entry may be translated into a more convenient, addressable
+form called a
+.B Dir
+structure;
+.IR dirstat ,
+.IR dirfstat,
+.IR dirwstat ,
+and
+.I dirfwstat
+execute the appropriate translations (see
+.IR stat (2)).
+.PP
+New files are made with
+.I create
+(in
+.IR open (2))
+and deleted with
+.IR remove (2).
+Directories may not directly be written;
+.IR create ,
+.IR remove ,
+.IR wstat ,
+and
+.I fwstat
+alter them.
+.PP
+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
+.B /
+or
+.BR # ),
+the system makes the stored name absolute by prefixing
+the string associated with the current directory.
+Similar lexical adjustments are made for path names containing
+.B .
+(dot) or
+.B ..
+(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\(emthe name is not maintained after the file is opened,
+so removals and renamings can confound it\(emthis simple method usually
+permits the system to return, via the
+.IR fd2path (2)
+system call and related calls such as
+.IR 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
+.IR ns (1)
+or
+.B /dev/ns
+(see
+.IR proc (3)).
+.PP
+.IR Pipe (2)
+creates a connected pair of file descriptors,
+useful for bidirectional local communication.
+.SS "Process execution and control"
+A new process is created
+when an existing one calls
+.I rfork
+with the
+.B RFPROC
+bit set, usually just by calling
+.IR 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;
+.IR exec (2)
+will bring in a different one.
+.PP
+Each process has a unique integer process id;
+a set of open files, indexed by file descriptor;
+and a current working directory
+(changed by
+.IR chdir (2)).
+.PP
+Each process has a set of attributes \(em memory, open files,
+name space, etc. \(em that may be shared or unique.
+Flags to
+.IR rfork
+control the sharing of these attributes.
+.PP
+The memory of a process is divided into
+.IR segments .
+Every program has at least a
+.I text
+(instruction) and
+.I stack
+segment.
+Most also have an initialized
+.I data
+segment and a segment of zero-filled data called
+.IR bss .
+Processes may
+.IR segattach (2)
+other segments for special purposes.
+.PP
+A process terminates by calling
+.IR exits (2).
+A parent process may call
+.I wait
+(in
+.IR exits (2))
+to wait for some child to terminate.
+A string of status information
+may be passed from
+.I exits
+to
+.IR wait .
+A process can go to sleep for a specified time by calling
+.IR sleep (2).
+.PP
+There is a
+.I notification
+mechanism for telling a process about events such as address faults,
+floating point faults, and messages from other processes.
+A process uses
+.IR notify (2)
+to register the function to be called (the
+.IR "notification handler" )
+when such events occur.
+.SS Multithreading
+By calling
+.I rfork
+with the
+.B RFMEM
+bit set, a program may create 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;
+.IR malloc ,
+.IR print ,
+and the other routines use locks (see
+.IR lock (2))
+to synchronize access to their data structures.
+The graphics library defined in
+.B <draw.h>
+is also multi-process capable; details are in
+.IR graphics (2).
+In general, though, multiprocess programs should use some form of synchronization
+to protect shared data.
+.PP
+The thread library, defined in
+.BR <thread.h> ,
+provides support for multiprocess programs.
+It includes a data structure called a
+.B Channel
+that can be used to send messages between processes,
+and coroutine-like
+.IR 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.
+.PP
+Most programs using the thread library
+comprise multiple processes
+communicating over channels, and within some processes,
+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 completes.
+For an example of this design, see
+.IR mouse (2).
+.SH SEE ALSO
+.IR nm (1), 
+.IR 2l (1), 
+.IR 2c (1)
+.SH DIAGNOSTICS
+Math functions in
+.I libc
+return
+special values when the function is undefined for the
+given arguments or when the value is not representable
+(see
+.IR nan (2)).
+.PP
+Some of the functions in
+.I libc
+are system calls and many others employ system calls in their implementation.
+All system calls return integers,
+with \-1 indicating that an error occurred;
+.IR errstr (2)
+recovers a string describing the error.
+Some user-level library functions also use the
+.I errstr
+mechanism to report errors.
+Functions that may affect the value of the error string are said to ``set
+.IR errstr '';
+it is understood that the error string is altered only if an error occurs.
+.SH BUGS
+The limitation of path elements to 27 bytes
+.RB ( NAMELEN-1 )
+is a liability in the networked world.