| .TH INTRO 3 |
| .SH NAME |
| intro \- introduction to library functions |
| .SH SYNOPSIS |
| .nf |
| .B #include <u.h> |
| .PP |
| .B #include \fIany Unix headers\fR |
| .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 <regexp.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 \*9/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 \*9/lib/libdraw.a , |
| which may be abbreviated when named to the loader as |
| .BR -ldraw . |
| In practice, 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 |
| .IR 9c (1). |
| .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 needs |
| .BR <u.h> . |
| 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 uchar , |
| .IR ushort , |
| and |
| .IR ulong , |
| the unsigned integer types; |
| .IR schar , |
| the signed char type; |
| .I vlong |
| and |
| .IR uvlong , |
| the signed and unsigned very long integral types; |
| .IR Rune , |
| the Unicode character type; |
| .IR u8int , |
| .IR u16int , |
| .IR u32int , |
| and |
| .IR u64int , |
| the unsigned integral types with specific widths; |
| .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 (3)); |
| .\" definitions of the bits in the floating-point control register |
| .\" as used by |
| .\" .IR getfcr (2); |
| and |
| 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). |
| .PP |
| Plan 9 and Unix use many similarly-named functions for different purposes: |
| for example, Plan 9's |
| .I dup |
| is closer to (but not exactly) Unix's |
| .IR dup2 . |
| To avoid name conflicts, |
| .B <libc.h> |
| defines many of these names as preprocessor macros to add a |
| .I p9 |
| prefix, |
| so that |
| .I dup |
| becomes |
| .IR p9dup . |
| To disable this renaming, |
| .B #define |
| .B NOPLAN9DEFINES |
| before including |
| .BR <libc.h> . |
| If Unix headers must be included in a program, |
| they should be included after |
| .BR <u.h> , |
| which sets important preprocessor directives |
| (for example, to enable 64-bit file offsets), |
| but before |
| .BR <libc.h> , |
| to avoid renaming problems. |
| .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 |
| .I "path elements" |
| with the slashes corresponding to directories. |
| A path element must contain only printable |
| characters (those outside the control spaces of |
| .SM ASCII |
| and Latin-1). |
| A path element cannot contain a 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, |
| 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. |
| .SS "File I/O" |
| Files are opened for input or output |
| by |
| .I open |
| or |
| .I create |
| (see |
| .IR open (3)). |
| These calls return an integer called a |
| .IR "file descriptor" |
| which identifies the file |
| to subsequent I/O calls, |
| notably |
| .IR read (3) |
| 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 (3). |
| File descriptors are indices into a |
| kernel resident |
| .IR "file descriptor table" . |
| Each process has an associated file descriptor table. |
| In threaded programs |
| (see |
| .IR thread (3)), |
| the file descriptor table is shared by all the procs. |
| .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 (3) |
| system call. |
| .PP |
| Directories may be opened like regular files. |
| Instead of reading them with |
| .IR read (3), |
| use the |
| .B Dir |
| structure-based |
| routines described in |
| .IR dirread (3). |
| The entry |
| corresponding to an arbitrary file can be retrieved by |
| .IR dirstat |
| (see |
| .IR stat (3)) |
| or |
| .IR dirfstat ; |
| .I dirwstat |
| and |
| .I dirfwstat |
| write back entries, thus changing the properties of a file. |
| .PP |
| New files are made with |
| .I create |
| (see |
| .IR open (3)) |
| and deleted with |
| .IR remove (3). |
| Directories may not directly be written; |
| .IR create , |
| .IR remove , |
| .IR wstat , |
| and |
| .I fwstat |
| alter them. |
| .PP |
| .IR Pipe (3) |
| 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 |
| .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 (3) |
| 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 (3). |
| A parent process may call |
| .IR wait (3) |
| to wait for some child to terminate. |
| A bit of status information |
| may be passed from |
| .I exits |
| to |
| .IR 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. |
| .PP |
| A process can go to sleep for a specified time by calling |
| .IR sleep (3). |
| .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 (3) |
| to register the function to be called (the |
| .IR "notification handler" ) |
| when such events occur. |
| .SS Multithreading |
| 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 (3)) |
| 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 (3). |
| 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 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 examples of this design, see |
| .IR ioproc (3) |
| or |
| .IR mouse (3). |
| .SH SEE ALSO |
| .IR nm (1), |
| .IR 9c (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 (3)). |
| .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 (3) |
| 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. |