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