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.

You are viewing proxied material from sdf.org. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.