diff options
Diffstat (limited to 'man/man3/intro.html')
| -rw-r--r-- | man/man3/intro.html | 288 |
1 files changed, 288 insertions, 0 deletions
diff --git a/man/man3/intro.html b/man/man3/intro.html new file mode 100644 index 00000000..f6f4b311 --- /dev/null +++ b/man/man3/intro.html @@ -0,0 +1,288 @@ +<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> |