intro(3) - Plan 9 from User Space

From 78e51a8c6678b6e3dff3d619aa786669f531f4bc Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 03:45:44 +0000 Subject: checkpoint --- man/man3/intro.html | 288 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 288 insertions(+) create mode 100644 man/man3/intro.html (limited to 'man/man3/intro.html') 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 @@ + +intro(3) - Plan 9 from User Space + + + + +

INTRO(3) INTRO(3) +

+
+

NAME
+ +
+ + intro – introduction to library functions
+ +
+

SYNOPSIS
+ +
+ + #include <u.h> + + + + #include any Unix headers
+ +
+ + #include <libc.h> + + + + #include <auth.h> + + + + #include <bio.h> + + + + #include <draw.h> + + + + #include <fcall.h> + + + + #include <frame.h> + + + + #include <mach.h> + + + + #include <regexp.h> + + + + #include <thread.h> + +
+

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 /usr/local/plan9/lib/libx.a, + where x is the base of the include file name, + stripped of a leading lib if present. For example, <draw.h> defines + the contents of library /usr/local/plan9/lib/libdraw.a, which + may be abbreviated when named to the loader as −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 9c(1). +
+ + The library to which a function belongs is defined by the header + file that defines its interface. The ‘C library’, libc, contains + most of the basic subroutines such as strlen. Declarations for + all of these functions are in <libc.h>, which must be preceded by + (needs) an include of <u.h>. The graphics library, draw, is + defined by <draw.h>, which needs <libc.h> and <u.h>. The Buffered I/O + library, libbio, is defined by <bio.h>, which needs <libc.h> and <u.h>. + The ANSI C Standard I/O library, libstdio, is defined by <stdio.h>, + which needs <u.h>. There are a few other, less commonly used libraries + defined on + individual pages of this section. +
+ + The include file <u.h>, a prerequisite of several other include + files, declares the architecture-dependent and -independent types, + including: uchar, ushort, and ulong, the unsigned integer types; + schar, the signed char type; vlong and uvlong, the signed and + unsigned very long integral types; Rune, the Unicode + character type; u8int, u16int, u32int, and u64int, the unsigned + integral types with specific widths; jmp_buf, the type of the + argument to setjmp and longjmp, plus macros that define the layout + of jmp_buf (see setjmp(3)); and the macros va_arg and friends + for accessing arguments of variadic functions (identical to the + macros defined in <stdarg.h> in ANSI C). +
+ + Plan 9 and Unix use many similarly-named functions for different + purposes: for example, Plan 9’s dup is closer to (but not exactly) + Unix’s dup2. To avoid name conflicts, <libc.h> defines many of these + names as preprocessor macros to add a p9 prefix, so that dup becomes + p9dup. To disable this renaming, + #define NOPLAN9DEFINES before including <libc.h>. If Unix headers + must be included in a program, they should be included after <u.h>, + which sets important preprocessor directives (for example, to + enable 64-bit file offsets), but before <libc.h>, to avoid renaming + problems. +
Name space
+ Files are collected into a hierarchical organization called a + file tree starting in a directory called the root. File names, + also called paths, consist of a number of /-separated path elements + 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. +
+ + When a process presents a file name to Plan 9, it is evaluated + by the following algorithm. Start with a directory that depends + on the first character of the path: / 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.
+
File I/O
+ Files are opened for input or output by open or create (see open(3)). + These calls return an integer called a file descriptor which identifies + the file to subsequent I/O calls, notably read(3) and 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 dup(3). File descriptors + are indices into a kernel resident file descriptor table. Each + process has an associated file descriptor table. In threaded programs + (see thread(3)), the file descriptor table is shared by all the + procs. +
+ + 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. +
+ + Files are normally read or written in sequential order. The I/O + position in the file is called the file offset and may be set + arbitrarily using the seek(3) system call. +
+ + Directories may be opened like regular files. Instead of reading + them with read(3), use the Dir structure-based routines described + in dirread(3). The entry corresponding to an arbitrary file can + be retrieved by dirstat (see stat(3)) or dirfstat; dirwstat and + dirfwstat write back entries, thus changing the properties of + a + file. +
+ + New files are made with create (see open(3)) and deleted with + remove(3). Directories may not directly be written; create, remove, + wstat, and fwstat alter them. +
+ + Pipe(3) creates a connected pair of file descriptors, useful for + bidirectional local communication.
+
Process execution and control
+ A new process is created when an existing one calls 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; exec(3) + will bring in a different one. +
+ + Each process has a unique integer process id; a set of open files, + indexed by file descriptor; and a current working directory (changed + by chdir(2)). +
+ + Each process has a set of attributes -- memory, open files, name + space, etc. -- that may be shared or unique. Flags to rfork control + the sharing of these attributes. +
+ + A process terminates by calling exits(3). A parent process may + call wait(3) to wait for some child to terminate. A bit of status + information may be passed from exits to 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. +
+ + A process can go to sleep for a specified time by calling sleep(3). + +
+ + There is a notification mechanism for telling a process about + events such as address faults, floating point faults, and messages + from other processes. A process uses notify(3) to register the + function to be called (the notification handler) when such events + occur.
+
Multithreading
+ Where possible according to the ANSI C standard, the main C library + works properly in multiprocess programs; malloc, print, and the + other routines use locks (see lock(3)) to synchronize access to + their data structures. The graphics library defined in <draw.h> + is also multi-process capable; details are in graphics(3). + In general, though, multiprocess programs should use some form + of synchronization to protect shared data. +
+ + The thread library, defined in <thread.h>, provides support for + multiprocess programs. It includes a data structure called a Channel + that can be used to send messages between processes, and coroutine-like + 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. +
+ + 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 ioproc(3) + or mouse(3).
+ +
+

SEE ALSO
+ +
+ + nm(1), 9c(1)
+ +
+

DIAGNOSTICS
+ +
+ + Math functions in libc return special values when the function + is undefined for the given arguments or when the value is not + representable (see nan(3)). +
+ + Some of the functions in 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; errstr(3) + recovers a string describing the error. Some user-level library + functions also use the errstr mechanism to report errors. + Functions that may affect the value of the error string are said + to “set errstr”; it is understood that the error string is altered + only if an error occurs.
+ +
+ +

+ + +

		+
	+ + + +

+ + -- cgit v1.2.3