.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 <stdio.h>
.PP
.B #include <bio.h>
.PP
.B #include <libg.h>
.PP
.B #include <gnot.h>
.PP
.B #include <frame.h>
.PP
.B #include <layer.h>
.PP
.B #include <regexp.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, listed above, and a single archive file containing
the library proper.  The name of the archive is
.BI /$objtype/lib/lib x .a ,
where
.I x
is the base of the include file name, stripped of a leading
.B lib
if present.
For example,
.B <libg.h>
defines the contents of library
.B /$objtype/lib/libg.a
which may be abbreviated when named to the loader as
.B -lg .
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
identified by the section number at the top of the manual page:
.TP 
(2)
These functions constitute the `C library',
.I libc,
containing most of the basic non-system call subroutines such
as
.I 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> .
.TP
(2G)
These functions constitute the library
.IR libg ,
the graphics library.
Declarations for these functions are in
.BR <libg.h> ,
which needs
.B <libc.h>
and
.BR <u.h> .
.TP
(2S)
These functions constitute the library
.IR libstdio ,
the `standard I/O package'
(see
.IR fgetc (2)).
Declarations for these functions are in
.BR <stdio.h> .
.TP
(2X)
Various
specialized libraries have not been given distinctive
captions.
Files in which such libraries are found are named
on appropriate pages.
.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 
.I 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);
.IR Length ,
a union giving different views of the 64-bit length of a file, declared as
.IP
.EX
.ta 6n +\w'struct 'u +\w'long 'u +\w'hlength;   'u
typedef union
{
	char	clength[8];
	vlong	vlength;
	struct
	{
		long	hlength;	/* high order */
		long	length;	/* low order */
	};
} Length;
.EE
.SS "Name space
Files are collected into a hierarchical organization called a
.I "file tree
starting in a
.I directory
called the
.I 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
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 .
File descriptors range from 0 to 99 in the current system.
The system allocates the numbers by selecting the lowest unused descriptor.
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
.I "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;
.I dirstat,
.I dirfstat,
.I 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
.IR Pipe (2)
creates a connected pair of file descriptors,
useful for 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
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.
.SH SEE ALSO
.IR nm (1), 
.IR 2l (1), 
.IR 2c (1)
.SH DIAGNOSTICS
Math functions in
.I libc
will 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.
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.