| <head> |
| <title>intro(3) - Plan 9 from User Space</title> |
| <meta content="text/html; charset=utf-8" http-equiv=Content-Type> |
| </head> |
| <body bgcolor=#ffffff> |
| <table border=0 cellpadding=0 cellspacing=0 width=100%> |
| <tr height=10><td> |
| <tr><td width=20><td> |
| <tr><td width=20><td><b>INTRO(3)</b><td align=right><b>INTRO(3)</b> |
| <tr><td width=20><td colspan=2> |
| <br> |
| <p><font size=+1><b>NAME </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| intro – introduction to library functions<br> |
| |
| </table> |
| <p><font size=+1><b>SYNOPSIS </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>#include <u.h> <br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>#include</font></tt> <i>any Unix headers <br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </i> |
| <tt><font size=+1>#include <libc.h> <br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>#include <auth.h> <br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>#include <bio.h> <br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>#include <draw.h> <br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>#include <fcall.h> <br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>#include <frame.h> <br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>#include <mach.h> <br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>#include <regexp.h> <br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>#include <thread.h> <br> |
| </font></tt> |
| </table> |
| <p><font size=+1><b>DESCRIPTION </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| 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 <tt><font size=+1>/usr/local/plan9/lib/lib</font></tt><i>x</i><tt><font size=+1>.a</font></tt>, |
| where <i>x</i> is the base of the include file name, |
| stripped of a leading <tt><font size=+1>lib</font></tt> if present. For example, <tt><font size=+1><draw.h></font></tt> defines |
| the contents of library <tt><font size=+1>/usr/local/plan9/lib/libdraw.a</font></tt>, which |
| may be abbreviated when named to the loader as <tt><font size=+1>−ldraw</font></tt>. 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 <a href="../man1/9c.html"><i>9c</i>(1)</a>. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| The library to which a function belongs is defined by the header |
| file that defines its interface. The ‘C library’, <i>libc</i>, contains |
| most of the basic subroutines such as <i>strlen</i>. Declarations for |
| all of these functions are in <tt><font size=+1><libc.h></font></tt>, which must be preceded by |
| (<i>needs</i>) an include of <tt><font size=+1><u.h></font></tt>. The graphics library, <i>draw</i>, is |
| defined by <tt><font size=+1><draw.h></font></tt>, which needs <tt><font size=+1><libc.h></font></tt> and <tt><font size=+1><u.h></font></tt>. The Buffered I/O |
| library, <i>libbio</i>, is defined by <tt><font size=+1><bio.h></font></tt>, which needs <tt><font size=+1><libc.h></font></tt> and <tt><font size=+1><u.h></font></tt>. |
| The ANSI C Standard I/O library, <i>libstdio</i>, is defined by <tt><font size=+1><stdio.h></font></tt>, |
| which needs <tt><font size=+1><u.h></font></tt>. There are a few other, less commonly used libraries |
| defined on |
| individual pages of this section. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| The include file <tt><font size=+1><u.h></font></tt>, a prerequisite of several other include |
| files, declares the architecture-dependent and -independent types, |
| including: <i>uchar</i>, <i>ushort</i>, and <i>ulong</i>, the unsigned integer types; |
| <i>schar</i>, the signed char type; <i>vlong</i> and <i>uvlong</i>, the signed and |
| unsigned very long integral types; <i>Rune</i>, the Unicode |
| character type; <i>u8int</i>, <i>u16int</i>, <i>u32int</i>, and <i>u64int</i>, the unsigned |
| integral types with specific widths; <i>jmp_buf</i>, the type of the |
| argument to <i>setjmp</i> and <i>longjmp</i>, plus macros that define the layout |
| of <i>jmp_buf</i> (see <a href="../man3/setjmp.html"><i>setjmp</i>(3)</a>); and the macros <tt><font size=+1>va_arg</font></tt> and friends |
| for accessing arguments of variadic functions (identical to the |
| macros defined in <tt><font size=+1><stdarg.h></font></tt> in ANSI C). |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| Plan 9 and Unix use many similarly-named functions for different |
| purposes: for example, Plan 9’s <i>dup</i> is closer to (but not exactly) |
| Unix’s <i>dup2</i>. To avoid name conflicts, <tt><font size=+1><libc.h></font></tt> defines many of these |
| names as preprocessor macros to add a <i>p9</i> prefix, so that <i>dup</i> becomes |
| <i>p9dup</i>. To disable this renaming, |
| <tt><font size=+1>#define NOPLAN9DEFINES</font></tt> before including <tt><font size=+1><libc.h></font></tt>. If Unix headers |
| must be included in a program, they should be included after <tt><font size=+1><u.h></font></tt>, |
| which sets important preprocessor directives (for example, to |
| enable 64-bit file offsets), but before <tt><font size=+1><libc.h></font></tt>, to avoid renaming |
| problems. |
| <p><font size=+1><b>Name space </b></font><br> |
| Files are collected into a hierarchical organization called a |
| <i>file tree</i> starting in a <i>directory</i> called the <i>root</i>. File names, |
| also called <i>paths</i>, consist of a number of <tt><font size=+1>/</font></tt>-separated <i>path elements</i> |
| 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. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| When a process presents a file name to Plan 9, it is <i>evaluated</i> |
| by the following algorithm. Start with a directory that depends |
| on the first character of the path: <tt><font size=+1>/</font></tt> 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.<br> |
| <p><font size=+1><b>File I/O </b></font><br> |
| Files are opened for input or output by <i>open</i> or <i>create</i> (see <a href="../man3/open.html"><i>open</i>(3)</a>). |
| These calls return an integer called a <i>file descriptor</i> which identifies |
| the file to subsequent I/O calls, notably <a href="../man3/read.html"><i>read</i>(3)</a> and <i>write</i>. 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 <a href="../man3/dup.html"><i>dup</i>(3)</a>. File descriptors |
| are indices into a kernel resident <i>file descriptor table</i>. Each |
| process has an associated file descriptor table. In threaded programs |
| (see <a href="../man3/thread.html"><i>thread</i>(3)</a>), the file descriptor table is shared by all the |
| procs. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| 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. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| Files are normally read or written in sequential order. The I/O |
| position in the file is called the <i>file offset</i> and may be set |
| arbitrarily using the <a href="../man3/seek.html"><i>seek</i>(3)</a> system call. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| Directories may be opened like regular files. Instead of reading |
| them with <a href="../man3/read.html"><i>read</i>(3)</a>, use the <tt><font size=+1>Dir</font></tt> structure-based routines described |
| in <a href="../man3/dirread.html"><i>dirread</i>(3)</a>. The entry corresponding to an arbitrary file can |
| be retrieved by <i>dirstat</i> (see <a href="../man3/stat.html"><i>stat</i>(3)</a>) or <i>dirfstat</i>; <i>dirwstat</i> and |
| <i>dirfwstat</i> write back entries, thus changing the properties of |
| a |
| file. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| New files are made with <i>create</i> (see <a href="../man3/open.html"><i>open</i>(3)</a>) and deleted with |
| <a href="../man3/remove.html"><i>remove</i>(3)</a>. Directories may not directly be written; <i>create</i>, <i>remove</i>, |
| <i>wstat</i>, and <i>fwstat</i> alter them. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <a href="../man3/Pipe.html"><i>Pipe</i>(3)</a> creates a connected pair of file descriptors, useful for |
| bidirectional local communication.<br> |
| <p><font size=+1><b>Process execution and control </b></font><br> |
| A new process is created when an existing one calls <a href="../man2/fork.html"><i>fork</i>(2)</a>. 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; <a href="../man3/exec.html"><i>exec</i>(3)</a> |
| will bring in a different one. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| Each process has a unique integer process id; a set of open files, |
| indexed by file descriptor; and a current working directory (changed |
| by <a href="../man2/chdir.html"><i>chdir</i>(2)</a>). |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| Each process has a set of attributes -- memory, open files, name |
| space, etc. -- that may be shared or unique. Flags to <i>rfork</i> control |
| the sharing of these attributes. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| A process terminates by calling <a href="../man3/exits.html"><i>exits</i>(3)</a>. A parent process may |
| call <a href="../man3/wait.html"><i>wait</i>(3)</a> to wait for some child to terminate. A bit of status |
| information may be passed from <i>exits</i> to <i>wait</i>. 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. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| A process can go to sleep for a specified time by calling <a href="../man3/sleep.html"><i>sleep</i>(3)</a>. |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| There is a <i>notification</i> mechanism for telling a process about |
| events such as address faults, floating point faults, and messages |
| from other processes. A process uses <a href="../man3/notify.html"><i>notify</i>(3)</a> to register the |
| function to be called (the <i>notification handler</i>) when such events |
| occur.<br> |
| <p><font size=+1><b>Multithreading </b></font><br> |
| Where possible according to the ANSI C standard, the main C library |
| works properly in multiprocess programs; <i>malloc</i>, <i>print</i>, and the |
| other routines use locks (see <a href="../man3/lock.html"><i>lock</i>(3)</a>) to synchronize access to |
| their data structures. The graphics library defined in <tt><font size=+1><draw.h></font></tt> |
| is also multi-process capable; details are in <a href="../man3/graphics.html"><i>graphics</i>(3)</a>. |
| In general, though, multiprocess programs should use some form |
| of synchronization to protect shared data. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| The thread library, defined in <tt><font size=+1><thread.h></font></tt>, provides support for |
| multiprocess programs. It includes a data structure called a <tt><font size=+1>Channel</font></tt> |
| that can be used to send messages between processes, and coroutine-like |
| <i>threads</i>, 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. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| 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 <a href="../man3/ioproc.html"><i>ioproc</i>(3)</a> |
| or <a href="../man3/mouse.html"><i>mouse</i>(3)</a>.<br> |
| |
| </table> |
| <p><font size=+1><b>SEE ALSO </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <a href="../man1/nm.html"><i>nm</i>(1)</a>, <a href="../man1/9c.html"><i>9c</i>(1)</a><br> |
| |
| </table> |
| <p><font size=+1><b>DIAGNOSTICS </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| Math functions in <i>libc</i> return special values when the function |
| is undefined for the given arguments or when the value is not |
| representable (see <a href="../man3/nan.html"><i>nan</i>(3)</a>). |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| Some of the functions in <i>libc</i> are system calls and many others |
| employ system calls in their implementation. All system calls |
| return integers, with –1 indicating that an error occurred; <a href="../man3/errstr.html"><i>errstr</i>(3)</a> |
| recovers a string describing the error. Some user-level library |
| functions also use the <i>errstr</i> mechanism to report errors. |
| Functions that may affect the value of the error string are said |
| to “set <i>errstr</i>”; it is understood that the error string is altered |
| only if an error occurs.<br> |
| |
| </table> |
| |
| <td width=20> |
| <tr height=20><td> |
| </table> |
| <!-- TRAILER --> |
| <table border=0 cellpadding=0 cellspacing=0 width=100%> |
| <tr height=15><td width=10><td><td width=10> |
| <tr><td><td> |
| <center> |
| <a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a> |
| </center> |
| </table> |
| <!-- TRAILER --> |
| </body></html> |
