From adc93f6097615f16d57e8a24a256302f2144ec4e Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 17:37:50 +0000 Subject: cut out the html - they're going to cause diffing problems. --- man/man3/intro.html | 288 ---------------------------------------------------- 1 file changed, 288 deletions(-) delete mode 100644 man/man3/intro.html (limited to 'man/man3/intro.html') 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 @@ - -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.
- -
- -

 -
-
- - -
-
-
-Space Glenda -
-
- - -- cgit v1.2.3