From c8b6342d3c2a167dec16931815926e9e4387e7ef Mon Sep 17 00:00:00 2001 From: rsc Date: Thu, 13 Jan 2005 04:49:19 +0000 Subject: Many small edits. --- man/man3/0intro.3 | 395 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 395 insertions(+) create mode 100644 man/man3/0intro.3 (limited to 'man/man3/0intro.3') diff --git a/man/man3/0intro.3 b/man/man3/0intro.3 new file mode 100644 index 00000000..e544cc8d --- /dev/null +++ b/man/man3/0intro.3 @@ -0,0 +1,395 @@ +.TH INTRO 3 +.SH NAME +intro \- introduction to library functions +.SH SYNOPSIS +.nf +.B #include +.PP +.B #include \fIany Unix headers\fR +.PP +.B #include +.PP +.B #include +.PP +.B #include +.PP +.B #include +.PP +.B #include +.PP +.B #include +.PP +.B #include +.PP +.B #include +.PP +.B #include +.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 +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 , +which must be preceded by +.RI ( needs ) +an include of +.BR . +The graphics library, +.IR draw , +is defined by +.BR , +which needs +.B +and +.BR . +The Buffered I/O library, +.IR libbio , +is defined by +.BR , +which needs +.B +and +.BR . +The ANSI C Standard I/O library, +.IR libstdio , +is defined by +.BR , +which needs +.BR . +There are a few other, less commonly used libraries defined on +individual pages of this section. +.PP +The include file +.BR , +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 +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 +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 . +If Unix headers must be included in a program, +they should be included after +.BR , +which sets important preprocessor directives +(for example, to enable 64-bit file offsets), +but before +.BR , +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 +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 , +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. -- cgit v1.2.3